Apply suggestions from code review

Co-authored-by: Joel Pasvolsky <[email protected]>

Author: thisac

docs/demos/demos/intro_demo.py

@@ -21,55 +21,57 @@
 construct, and simulate quantum circuits using a performant state-vector
 simulator.
 
-## Circuits and operations
+## Circuits and Operations
 Begin with two necessary imports: The `Circuit` class, which will contain the
 full quantum circuit with all the operations, measurements, qubits and bits, and
-the operations module. The operations, or gates, contain information related to
-a particular operation, including its matrix representation, potential
-decompositions, and how to apply it to a circuit.
+the `operations` module.
 """
 
 from dwave.gate.circuit import Circuit
 import dwave.gate.operations as ops
 
 ###############################################################################
-# The `Circuit` keeps track of the operations and the logical flow of their
-# excecutions. It also stores the qubits, bits and measurments.
+# The operations, or gates, contain information related to a particular operation,
+# including its matrix representation, potential decompositions, and how to apply
+# it to a circuit.
 #
-# When initializing a circuit, the number of qubits and (optionally) the number of
-# bits, i.e., classical measurement results containers, need to be declared. More
-# qubits and bits can be added using the `Circuit.add_qubit` and `Circuit.add_bit`
+# The `Circuit` keeps track of the operations and the logical
+# flow of their executions. It also stores the qubits, bits and measurements.
+#
+# When initializing a circuit, you need to declare the number of qubits and,
+# optionally, the number of bits (i.e., classical measurement results containers).
+# You can add more qubits and bits using the `Circuit.add_qubit` and `Circuit.add_bit`
 # methods.
 
 circuit = Circuit(num_qubits=2, num_bits=2)
 
 ###############################################################################
 # You can use the `operations` module (shortened above to `ops`) to access a
-# variety of quantum gates; for example, a Pauli X operator.
+# variety of quantum gates; for example, the Pauli X operator. Note that you can
+# instantiate an operation without declaring which qubits it should be applied
+# to.
 
 ops.X()
 
 ###############################################################################
-# Notice above that an operation can be instantiated without declaring which
-# qubits it should be applied to.
-#
-# The matrix property can be accessed either via the operation class itself or an
+# You can access the matrix property via either the operation class itself or an
 # instance of the operation, which additionally can contain parameters and qubit
 # information.
 
 ops.X.matrix
 
 ###############################################################################
-# If the matrix representation is dependent on parameters (e.g., the rotation operation `ops.RX`)
-# it can only be retrieved from an instance.
+# If the matrix representation of an operator is dependent on parameters (e.g.,
+# the rotation operation `ops.RX`) it can only be retrieved from an instance.
 
 ops.RZ(4.2).matrix
 
 ###############################################################################
-# ## The circuit context
+# ## The Circuit Context
 #
-# Operations are applied by calling either a class or an instance of a class
-# within the context of the circuit. 
+# Operations are applied by calling either an operation class, or an instance of
+# an operation class, within the context of the circuit, passing along the
+# qubits on which the operation is applied.
 #
 # ```python
 # with circuit.context:
@@ -78,16 +80,16 @@
 #
 
 ###############################################################################
-# When activating the context, a named tuple containing reference registers to the
-# circuit's qubits and classical bits is returned. You can also access the qubit
-# registers directly via the `Circuit.qregisters` property, or the reference
-# registers containing all the qubits via `Circuit.qubits`.
+# When you activate a context, a named tuple containing reference registers to
+# the circuit's qubits and classical bits is returned. You can also access the
+# qubit registers directly, via the `Circuit.qregisters` property, or the
+# reference registers containing all the qubits, via `Circuit.qubits`.
 #
 # In the example below, the circuit contains a single qubit register with two
 # qubits; it could contain any number of qubit registers. You can
 #
 # * add another register with the `Circuit.add_qregister` method, where an argument `n`
-#   is the number of qubits in the new register
+#   is the number of qubits in the new register.
 # * add a qubit with `Circuit.add_qubit`, optionally passing a qubit object
 #   and/or a register to which to add it.
 
@@ -97,25 +99,25 @@
     ops.X(reg.q[0])
 
 ###############################################################################
-# This example created a circuit object with two qubits in its register, applying
+# This has created a circuit object with two qubits in its register, applying
 # a single X gate to the first qubit. Print the circuit to see general information
 # about it: type of circuit, number of qubits/bits, and number of operations.
 
 print(circuit)
 
 ###############################################################################
-# ## Applying gates to circuits
+# ## Applying Gates to Circuits
 #
 # You can apply operations to a circuit in several different ways, as demonstrated
 # in the example below. You can pass both qubits and parameters as either single
-# values (when supported by the gate) or sequences. Note that different types of
+# values (when supported by the gate) or as sequences. Note that different types of
 # gates accept slightly different arguments, although you can _always_ pass the
 # qubits as sequences via the keyword argument `qubits`.
 #
 # :::note
 # Always apply any operations you instantiate within a circuit context to
 # specific qubits in the circuit's qubit register. You can access the qubit
-# register via the named tuple returned by the context manager as `q`, indexing
+# register via the named tuple, returned by the context manager as `q`, indexing
 # into it to retrieve the corresponding qubit.
 # :::
 
@@ -147,8 +149,8 @@
 
 ###############################################################################
 # You can access all the operations in a circuit using the `Circuit.circuit`
-# property. The code below iterates over the returned list of all operations that
-# have been applied to the circuit.
+# property. The code below iterates over a list of all operations that
+# have been applied to the circuit and prints each one separately.
 
 for op in circuit.circuit:
     print(op)
@@ -161,14 +163,19 @@
 # :::
 
 ###############################################################################
-# ## Simulating a circuit
+# ## Simulating a Circuit
 #
-# `dwave-gate` comes with a performant state-vector simulator. It can be called by passing a circuit to the `simulate` method, which will update the quatum state stored in the circuit, accessible via `Circuit.state`.
+# `dwave-gate` comes with a performant state-vector simulator. You can call it by
+# passing a circuit to the `simulate` method, which will update the quantum state
+# stored in the circuit, accessible via `Circuit.state`.
 
 from dwave.gate.simulator import simulate
 
 ###############################################################################
-# We create a circuit object with 2 qubits and 1 bit in a quantum and classical registers respectively --- the bit is required to store a single qubit measurement --- and then apply a Hadamard gate and a CNOT gate to the circuit.
+# The following example creates a circuit object with 2 qubits and 1 bit in a
+# quantum and a classical register respectively---the bit is required to store a
+# single qubit measurement---and then applies a Hadamard gate and a CNOT gate to
+# the circuit.
 
 circuit = Circuit(2, 1)
 
@@ -177,7 +184,7 @@
     ops.CNOT(q[0], q[1])
 
 ###############################################################################
-# We can now simulate the circuit, which will update its stored quantum state.
+# You can now simulate the circuit, updating its stored quantum state.
 
 simulate(circuit)
 
@@ -192,63 +199,79 @@
 ###############################################################################
 # ## Measurements
 #
-# Measurements work like any other operation in dwave-gate. The main difference is that the operation generates a measurement value when simulated which can be stored in the classical register by piping it into a classical bit.
+# Measurements work like any other operation in `dwave-gate`. The main difference
+# is that the operation generates a measurement value when simulated, which can be
+# stored in the classical register by piping it into a classical bit.
 #
-# We can reuse the circuit from above by simply unlocking it and appending a `Measurement` to it.
+# The circuit above can be reused by simply unlocking it and appending a `Measurement` to it.
 
 circuit.unlock()
 with circuit.context as (q, c):
     m = ops.Measurement(q[1]) | c[0]
 
 ###############################################################################
 # :::note
-# We stored the measurement instance as `m`, which we can use for post-processing. It's also possible to do this with all other operations in the same way, allowing for multiple identical operation applications.
+# This example stored the measurement instance as `m`, which you can use for
+# post-processing. It's also possible to do this with all other operations in
+# the same way, allowing for multiple identical operation applications.
+#
 # ```python
 # with circuit.context as q, _:
 #     single_x_op = ops.X(q[0])
 #     # apply the X-gate again to the second qubit
 #     # using the previously stored operation
 #     single_x_op(q[1])
 # ```
-# This procedure can also be shortened into a single line for further convience.
+#
+# This procedure can also be shortened into a single line for further convenience.
+#
 # ```python
 # ops.CNOT(q[0], q[1])(q[1], q[2])(q[2], q[3])
 # ```
 # :::
 
 ###############################################################################
-# The circuit should now contain 3 operations: a Hadamard, a CNOT and a measurment.
+# The circuit should now contain 3 operations: a Hadamard, a CNOT and a measurement.
 
 print(circuit)
 
 ###############################################################################
-# When simulating this circuit, the measurement will be applied and the measured value will be stored in the classical register. Since a measurement will affect the quantum state, the resulting state will have collapsed into the expected result dependent on the value which has been measured.
+# When simulating this circuit, the measurement is applied and the measured
+# value is stored in the classical register. Since a measurement affects the
+# quantum state, the resulting state has collapsed into the expected result
+# dependent on the value which has been measured.
 
 simulate(circuit)
 
 ###############################################################################
-# If the measurement result is 0 the state should collapse into $\vert00\rangle$, and if the measurement result is 1 the state should collapse into $\vert11\rangle$. Outputting the measurement value and the state reveals that this is indeed the case.
+# If the measurement result is 0 the state should have collapsed into $\vert00\rangle$,
+# and if the measurement result is 1 the state should have collapsed into $\vert11\rangle$.
+# Outputting the measurement value and the state reveals that this is indeed the case.
 
 print(circuit.bits[0].value)
 print(circuit.state)
 
 ###############################################################################
-# ## Measurement post-access
-# Since we stored the measurement operation in `m`, we can use it to access the state as it was before the measurement.
+# ## Measurement Post-Access
+# Since the measurement operation has been stored in `m`, you can use it to access the
+# state as it was before the measurement.
 #
 # :::note
-# Accessing the state of the circuit along with any measurement post-sampling and state-access is only available for simulators.
+# Accessing the state of the circuit, along with any measurement post-sampling and
+# state-access, is only available for simulators.
 # :::
 
 m.state
 
 ###############################################################################
-# We can also sample that same state again using the `Measurement.sample` method, which by default only samples the state once. Here, we request 10 samples.
+# You can also sample that same state again using the `Measurement.sample` method,
+# which by default only samples the state once. Here, request 10 samples.
 
 m.sample(num_samples=10)
 
 ###############################################################################
-# Finally, we can calculate the expected value of the measurment based on a specific number of samples.
+# Finally, you can calculate the expected value of the measurement based on a
+# specific number of samples.
 
 m.expval(num_samples=10000)