Apply suggestions from code review

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

Author: thisac

docs/demos/demos/intro_demo.py

@@ -21,25 +21,27 @@
 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. 
+# 
+# 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, 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`
-# methods.
+# 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)
 
@@ -50,10 +52,10 @@
 ops.X()
 
 ###############################################################################
-# Notice above that an operation can be instantiated without declaring which
+# Notice above that you can instantiate an operation 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.
 
@@ -66,7 +68,7 @@
 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. 
@@ -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.
 
@@ -104,7 +106,7 @@
 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
@@ -115,7 +117,7 @@
 # :::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.
 # :::
 
@@ -161,14 +163,18 @@
 # :::
 
 ###############################################################################
-# ## 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.
+# This 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 +183,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,49 +198,60 @@
 ###############################################################################
 # ## 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.
+# You can reuse the circuit above 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 you simulate 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 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.
 
 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 you stored the measurement operation 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.
@@ -243,12 +260,14 @@
 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)