Merge remote-tracking branch 'origin/development'

.gitignore

@@ -3,10 +3,12 @@ __pycache__
 *.pyd
 **/build
 dist
+*.eggs
 *.egg-info
 *.cache
-.pylintc
+.pylintrc
 .pytest_cache
 /.idea
 /.eggs
 ~*
+jupyter/

conda_environment.yml

@@ -3,8 +3,14 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python>=3.6,<3.8
-  - numpy>=1.15,<2
-  - scipy>=1.1,<2
-  - matplotlib>=3.0,<4
-  - networkx>=2.2,<3
+  - python=3.7.2
+  - numpy=1.15
+  - scipy=1.2
+  - matplotlib=3.0
+  - networkx=2.2
+  - pytest=4.2
+  - cython=0.29
+  - sphinx=1.8
+  - sphinx_rtd_theme=0.4
+  - jupyter=1.0
+  - nb_conda

docs/api_guide/circuit_runners.rst

@@ -3,9 +3,13 @@
 Circuit Runners
 ===============
 
-Classes belonging to the ``circuit_runners`` namespace apply the gates of ``LogicalCircuits`` and ``QuantumCircuits`` to states represented by simulators. ``circuit_runners`` are also responsible for applying error models to quantum circuit; however, we will discus this in :ref:`error-gens`.
+Classes belonging to the ``circuit_runners`` namespace apply the gates of ``LogicalCircuits`` and ``QuantumCircuits`` to
+states represented by simulators. ``circuit_runners`` are also responsible for applying error models to quantum circuit;
+however, we will discus this in :ref:`error-gens`.
 
-The main ``circuit_runner`` is simply called ``Standard``. There is another call ``TimingRunner``, which is essentially the same as ``Standard`` except that it is used to time how long it takes simulators to apply gates and can be used to compare the runtime of simulators. I will now discuss these two ``circuit_runners``.
+The main ``circuit_runner`` is simply called ``Standard``. There is another call ``TimingRunner``, which is essentially
+the same as ``Standard`` except that it is used to time how long it takes simulators to apply gates and can be used to
+compare the runtime of simulators. I will now discuss these two ``circuit_runners``.
 
 
 Standard
@@ -17,9 +21,7 @@ Methods
 ~~~~~~~
 
 =============== =========================================
-``init``        Adds a collection of gates to the end of ``ticks``.
-``run_circuit`` Applies gates from a ``QuantumCircuit``.
-``run_logic``   Applies gates from a ``LogicalCircuit``.
+``run``         Combines a ``circuit``, ``error_gen``, ``simulator`` to run a simulation.
 =============== =========================================
 
 
@@ -41,28 +43,19 @@ To create an instance of ``Standard`` one can simply write:
 >>> import pecos as pc
 >>> circ_runner = pc.circuit_runners.Standard()
 
-By default, a ``Standard`` uses the ``StabSim`` as a simulator. This can be changed as follows:
+The ``run`` method is used to apply a ``QuantumCircuit`` or some other circuit instance to a state, where a state is an
+instance of a simulator (see :ref:`simulators`). This is seen in the following:
 
-
->>> from somepackage import MyCustomSim  # doctest: +SKIP
->>> circ_runner = pc.circuit_runners.Standard(simulator=MyCustomSim)  # doctest: +SKIP
-
-The ``init`` method is used to (re)initialize a ``simulator`` instance. An example of using this method to create a four-qubit registry is seen here:
-
->>> # Following from the previous code block.
->>> circ_runner = pc.circuit_runners.Standard()
->>> state = circ_runner.init(4)
-
-The ``run_circuit`` method is used to apply a ``QuantumCircuit`` to a state in the following:
-
->>> # Continuing with the previous code block.
+>>> state = pc.simulators.SparseSim(num_qubits=4)
 >>> qc = pc.circuits.QuantumCircuit()
 >>> qc.append('X', {0, 1})
 >>> qc.append('measure Z', {0, 1, 3})
->>> circ_runner.run_circuit(state, qc)
-{1: {0: 1, 1: 1}}
+>>> circ_runner.run(state, qc)
+({1: {0: 1, 1: 1}}, {})
 
-In the last line of this code block, we see the measurement record produced by the ``circuit_runner``. The keys of the outer dictionary are tick indices, while for the inner dictionary the keys are the indices of qubits with non-zero measurements and the values are the measurement results.
+In the last line of this code block, we see the measurement record produced by the ``circuit_runner``. The keys of the
+outer dictionary are tick indices, while for the inner dictionary the keys are the indices of qubits with non-zero
+measurements and the values are the measurement results.
 
 
 
@@ -72,31 +65,36 @@ The ``run_logic`` method is used to apply ``LogicalCircuits``:
 >>> logic = pc.circuits.LogicalCircuit()
 >>> logic.append(surface.gate('ideal init |0>'))
 >>> logic.append(surface.gate('I'))
->>> state = circ_runner.init(surface.num_qudits)
->>> circ_runner.run_logic(state, logic)
+>>> state = pc.simulators.SparseSim(surface.num_qudits)
+>>> circ_runner.run(state, logic)
 ({}, {})
 
 
 
-The final line is the output of ``run_logic``. The first dictionary is a record measurement and the second is a record of the errors generated. In this example, all the measurement results are zero and we have not applied any error models. In :ref:`error-gens`, there are examples of where this is not the case; therefore, refer to that section if you are curious about the output of ``run_logic``.
+The final line is the output of ``run``. The first dictionary is a record measurement and the second is a record
+of the errors generated. In this example, all the measurement results are zero and we have not applied any error models.
+In :ref:`error-gens`, there are examples of where this is not the case; therefore, refer to that section if you are
+curious about the output of ``run``.
 
 TimingRunner
 ------------
 
-As mention, ``TimingRunner`` is essentially the same as ``Standard`` except the runtime for applying gates is recorded. The attribute ``total_time`` stores this value and is used in the following:
+As mention, ``TimingRunner`` is essentially the same as ``Standard`` except the runtime for applying gates is recorded.
+The attribute ``total_time`` stores this value and is used in the following:
 
 >>> circ_runner = pc.circuit_runners.TimingRunner()
->>> state = circ_runner.init(4)
+>>> state = pc.simulators.SparseSim(4)
 >>> qc = pc.circuits.QuantumCircuit()
 >>> qc.append('X', {0, 1, 2, 3})
->>> circ_runner.run_circuit(state, qc)
-{}
+>>> circ_runner.run(state, qc)
+({}, {})
 >>> circ_runner.total_time   # doctest: +SKIP
 7.22257152574457e-06
 
-``TimingRunner`` times the execution of gates by using Python's ``perf_counter`` method. The time recorded by ``total_time`` continues to accumulate until it is reset by the ``reset_time`` method:
+``TimingRunner`` times the execution of gates by using Python's ``perf_counter`` method. The time recorded by
+``total_time`` continues to accumulate until it is reset by the ``reset_time`` method:
 
->>> # Continuing from previous Listing.
+>>> # Continuing from previous code block.
 >>> circ_runner.reset_time()
 >>> circ_runner.total_time
 0.0

docs/api_guide/decoders.rst

@@ -3,15 +3,19 @@
 Decoders
 ========
 
-A decoder in PECOS is simply a function or other callable that takes the measurement outcomes from error extractions (syndromes) as input and returns a ``QuantumCircuit``, which is used as a recovery operation to mitigate errors. Decoder classes and functions are in the ``decoders`` namespace.
+A decoder in PECOS is simply a function or other callable that takes the measurement outcomes from error extractions
+(syndromes) as input and returns a ``QuantumCircuit``, which is used as a recovery operation to mitigate errors. Decoder
+classes and functions are in the ``decoders`` namespace.
 
 The ``MWPM2D`` class is an available decoder class, which I will discuss next.
 
 
 MWPM2D
 ------
 
-One of the standard decoders used for surface codes is the minimum-weight-perfect-matching (MWPM) decoder [Den+02]_. The ``MWPM2D`` class implements the 2D version of this decoder for ``Surface4444`` and ``SurfaceMedial4444``, that is, it decodes syndromes for a single round of error extraction:
+One of the standard decoders used for surface codes is the minimum-weight-perfect-matching (MWPM) decoder [Den+02]_. The
+``MWPM2D`` class implements the 2D version of this decoder for ``Surface4444`` and ``SurfaceMedial4444``, that is, it
+decodes syndromes for a single round of error extraction:
 
 >>> import pecos as pc
 >>> depolar = pc.error_gens.DepolarGen(model_level='code_capacity')
@@ -20,7 +24,7 @@ One of the standard decoders used for surface codes is the minimum-weight-perfec
 >>> logic.append(surface.gate('ideal init |0>'))
 >>> logic.append(surface.gate('I', num_syn_extract=1))
 >>> circ_runner = pc.circuit_runners.Standard(seed=1)
->>> state = circ_runner.init(surface.num_qudits)
+>>> state = pc.simulators.SparseSim(surface.num_qudits)
 >>> decode = pc.decoders.MWPM2D(surface).decode
 >>> meas, err = circ_runner.run_logic(state, logic, error_gen=depolar, error_params={'p': 0.1})
 >>> meas   # doctest: +SKIP