Operator Flow (qiskit-community/qiskit-aqua#852)

* Add abelian property to opvecs and AbelianGrouper to operator init. * Break up PauliCoB big clifford synthesis function into smaller ones. * Add AbelianGrouper test. * Add better input checking in primitives and remove unnecessary print. * Fix coeffs bugs in pauli_cob.py. * Reorganize pauli_cob. All tests pass, with grouping on and off. * Change expectation_value backends to work through setters. * Reorganize local_simulator_sampler.py a bit to use it in a test. * Grouping Paulis works!! All tests pass. * Add "compute TPB pauli" function to pauli_cob. * Add WIP attempt at evolution over Abelian paulis. * Fix trotter bug. * Fix some other Trotter bugs. * Add parameters to OpPaulis and test. Parameterized evolution passes!!! * Add parameter binding for Op coefficients. * Add parameter binding, and binding tests. Tests pass. * Add division to Operators to make normalization convenient. * Finish merging MinEigenSolver PR. All tests pass. * Update QAOA, all tests pass!! * Update some QAOA imports and typehints. * Add QDrift trotterization method. All tests pass. * Start migrating QPE, tests fail. * fix spell * fix almost all style errors * fix copyright * fix import cycles, changed to relative imports when possible * relative imports * Add bind_params to state_fn_circuit.py and op_circuit.py, and tests. Add list unrolling for param binding, and tests. Tests pass. * Add param list handling for all Op types. * Make OpVec printing nicer. * Add op_converter to imports for better backwards compatibility. * Add AerPauliExpectation tests. Tests pass. Issue with Aer though. * Fix a few AerPauliExpectation bugs * Start building toward parameterized Qobj. * fix some lint errors * fix some lint errors * fix style * fix copyright * set style to defaults, fix aqua unit test loading * change loading tests qpe/iqpe * Fix OpPrimitive lint errors. * Fix operator_base.py lint errors. * Fix state_fn.py lint errors. * Fix OpVec lint errors. * Fix state_fn_circuit.py lint errors. * Fix state_fn_dict.py lint errors. * Fix state_fn_operator.py lint errors. * Fix state_fn_vector.py lint errors. Tests pass. * Fix QDrift test to deal with first Op in trotterization list being OpCircuit. * Fix op_circuit.py lint errors. * Fix op_pauli.py lint errors. * Fix op_composition.py lint errors. * Fix op_kron.py lint errors. * Fix abelian_grouper.py lint errors. Tests pass. * Fix pauli_cob.py lint errors. Tests pass. * Fix Expectation lint errors. Tests pass. * Fix circuit sampler lint errors. Tests pass. * Fix other expectation lint errors. Tests pass. * Fix trotterization lint errors. Tests pass. * Add MatrixEvolution shell, fix evolution lint errors. * Fix bug in evolution tests after fixing lint errors. * Fix cyclic import for lint. * fix pylint cyclic import error * Make tests pass. Add aux_ops back to VQE, and make VQE and QAOA take old or new ops. * fix spell and lint * Fix swapping issue in evolution. * Fix composition in OpEvolution. * Fix add OpSum and kron OpKron in OpEvolution. * Add to_opflow to legacy base_operator * Clean OpCircuit and StateFnCircuit __str__ * Fix qaoa mixer. * fix spell,style * Ok now really all tests pass. * add to_matrix_op() methods to ops. * Start migrating NumpyEigensolver for Opflow * Start removing back from op_primitive eval functions. All tests pass. * Update eval logic (to be able to remove back) for operator_combos. * Add to_matrix_op for OpMatrix and StateFnVector, and change some `if back`s to `if back is not None` * Finish decoupling back args from evals. All tests pass. * Remove back from eval logic. * Remove back from eval. All tests pass. * Change matrix_expectation.py to rely on to_matrix_op. * Migrate numpy_eigen_solver.py and numpy_minimum_eigen_solver. * Remove ToMatrixOp converter. * set VQE _auto_conversion to False for now * Add sampling and tests. Fix a rounding error in a test. Fix a not none error in numpy_eigen_solver.py. * Add array methods to OpVec. Fix typo in OpPauli. Allow reverse_endianness in to_opflow for WeightedPauli. * Make NumpyEigensolver return a StateFn in result.eigenstate. * Fix flaky optimization tests. Fix OpVec so iterator interface works. * Fix StateFnVector sampling. Fix sparse NumpyEigensolution. Fix some aux_op stuff. Fix some other things here and there. Please no more breakage. * Change some sparsity stuff. * fix spelling * Typehints. * More typehints * fix copyright * fix spelling * More typehints, make globals immutable. * fix style * Rearrange tests, Add CZ to globals. * Refactor some names. * Rename OpEvolution to EvolutionOp. Tests pass. * Rename primitive ops. All tests pass. * Finish renamings. * Test IBMQ Pauli expectation. All tests pass. * Update spelling. * Update Pauli to num_qubits. * Updating some naming. * Add diag support to fix knapsack issue. * fix unit test * fix unit test * fix travis * Turn half of Steve's comments. * Fix some exponentiation things. * Fix some exponentiation things. * Add trotterization_factory. All tests pass. * Add evolution_factory. All tests pass. * Add circuit_sampler_factory. All tests pass. * Rename get_primitives to primitive_strings. Turn some of Julien's changes. * Only allow sample_circuits to accept circuit_ops. Tests pass. * Turn more review changes * fix spell, style * Add matrix_op exp_i() into HamiltonianGate. Tests fail due to CircuitOp decompose() during composition. If commented out (line 158) tests pass. * Change CircuitOp and StateFnCircuit to rely on QuantumCircuit instead of Instruction. All tests pass. Add to_circuit_op to relevant ops. Solves all the decompose issues. * Add matrix_evolution and update QAOA to test matrix_op for cost operator. Add logic to update UCCSD to operator flow. Tests pass. * Delete PauliToInstruction, as it's obsolete. * Add to_pauli_op and tests. Tests pass. * Fix composed_op.py eval bug * Add sig digit rounding. VQE tests fail. * better precision for sig digit rounding. Tests pass. * Fix pep8, add comment * Add to_circuit_op to statefns, making DictToCircuit mostly obsolete. Tests pass. * fix cyclic imports * fix numpy boolean to string coercion * Update repr and a docstring. * Make ExpectationValues into converters. Test pass. * Fix bug from merge. * Fix bugs, make Minus just a CircuitStateFn and not a ComposedOp. * Uncomment HamiltonianGate * Update lots of docstrings part I. Tests pass. * fix docstring * More docstrings. Change class.rst so docs are generated for some python operator overloads. * Add navigation structure for docs to init files * More docs. * fix doctrings * 1) Change local_simulator_sampler.py to circuit_sampler.py 2) Set up circuit_samplers directory to be removed. 3) Add IBMQ VQE test. 4) Change AerPauliExpectation and CircuitSampler to handle expval_measurement/snapshots correctly. Tests pass. * 1) Delete circuit_samplers. 2) Allow CircuitSampler to attach_results. * Update Operator init * Change Operator directory names. Tests pass. * fix spell, docs * Turn Expectations purely into converters. Tests pass. * fix docs * skip IBMQ test * Add Converters docs. Tests pass. * fix spell * Add Evolutions docs. Tests pass. * Add Expectation docs. Tests pass. * fix spell * Add StateFn docs. Tests pass. * Fix typo. * Add ListOp init docs. * Fix some ordering * Little docs edits. * fix spell * Little docs edits. * 1) Add to_legacy_op to OperatorBase to allow non-migrated algos to accept new Operators. 2) Allow QPE and iQPE to accept new Operators, migrate tests. Tests pass. * Fix typehints for minimum_eigen_solvers * Make sure expectations can handle mixed observables. * fix spell * Turn some more of Steve's comments. Tests pass. * Turn some more of Steve's comments. Fix a buncha parameter stuff, and make sure mixed Pauli evolution works. * Turn some more of Steve's comments. Tests pass. * Turn some comments, fix a QAOA bug. * Try collapsing ListOp to_matrix a bit. * Turn more comments, fix some bugs. * Turn more comments, fix some bugs. * Update ListOp docs. * Update ListOp docs. * Update ListOp docs. * fix docstring * Update minimum_eigen_solvers setter typehints. * Add Changelog and tests for DictToCircuitSum. * Update VQE's construct_circuit and some changelog elements. * fix spell * Allow MinEigenOptimizer to accept StateFn result in result.eigenstate. * fix style * Update changelog with more detail. Update VQE to call super. * Typo Co-authored-by: Manoel Marques <manoel@us.ibm.com> Co-authored-by: woodsp <woodsp@us.ibm.com>
manoelmarques · Apr 27, 2020 · ba2872b · ba2872b
1 parent be8f01f
commit ba2872b
Show file tree

Hide file tree

Showing 51 changed files with 6,597 additions and 82 deletions.
diff --git a/qiskit/aqua/operators/__init__.py b/qiskit/aqua/operators/__init__.py
@@ -2,7 +2,7 @@
 
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2019.
+# (C) Copyright IBM 2019, 2020.
 #
 # This code is licensed under the Apache License, Version 2.0. You may
 # obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -12,69 +12,167 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
+r"""
 Operators (:mod:`qiskit.aqua.operators`)
 ========================================
-Operators
+Operators and State functions are the building blocks of Quantum Algorithms.
+
+A library for Quantum Algorithms & Applications is more than a collection of
+algorithms wrapped in Python functions. It needs to provide tools to make writing
+algorithms simple and easy. This is the layer of modules between the circuits and algorithms,
+providing the language and computational primitives for QA&A research.
+
+In Aqua, we call this layer the Operator Flow. It works by unifying computation with theory
+through the common language of functions and operators, in a way which preserves physical
+intuition and programming freedom. In the Operator Flow, we construct functions over binary
+variables, manipulate those functions with operators, and evaluate properties of these functions
+with measurements.
+
+The Operator Flow is meant to serve as a lingua franca between the theory and implementation
+of Quantum Algorithms & Applications. Meaning, the ultimate goal is that when theorists speak
+their theory in the Operator Flow, they are speaking valid implementation, and when the engineers
+speak their implementation in the Operator Flow, they are speaking valid physical formalism. To
+be successful, it must be fast and physically formal enough for theorists to find it easier and
+more natural than hacking Matlab or NumPy, and the engineers must find it straightforward enough
+that they can learn it as a typical software library, and learn the physics naturally and
+effortlessly as they learn the code. There can never be a point where we say "below this level
+this is all hacked out, don't come down here, stay in the interface layer above." It all must
+be clear and learnable.
+
+Before getting into the details of the code, it's important to note that three mathematical
+concepts unpin the Operator Flow. We derive most of the inspiration for the code structure from
+`John Watrous's formalism <https://cs.uwaterloo.ca/~watrous/TQI/>`__ (but do not follow it exactly),
+so it may be worthwhile to review Chapters I and II, which are free online, if you feel the
+concepts are not clicking.
+
+1. An n-qubit State function is a complex function over n binary variables, which we will
+often refer to as *n-qubit binary strings*. For example, the traditional quantum "zero state" is
+a 1-qubit state function, with a definition of f(0) = 1 and f(1) = 0.
+
+2. An n-qubit Operator is a linear function taking n-qubit state functions to n-qubit state
+functions. For example, the Pauli X Operator is defined by f(Zero) = One and f(One) = Zero.
+Equivalently, an Operator can be defined as a complex function over two n-qubit binary strings,
+and it is sometimes convenient to picture things this way. By this definition, our Pauli X can
+be defined by its typical matrix elements, f(0, 0) = 0, f(1, 0) = 1, f(0, 1) = 1,
+f(1, 1) = 0.
+
+3. An n-qubit Measurement is a functional taking n-qubit State functions to complex values.
+For example, a Pauli Z Measurement can be defined by f(Zero) = 0 and f(One) = 1.
+
+Below, you'll find a base class for all Operators, some convenience immutable global variables
+which simplify Operator construction, and two groups of submodules: Operators and Converters.
 
 .. currentmodule:: qiskit.aqua.operators
 
-Operators
-=========
+Operator Base Class
+===================
+
+The OperatorBase serves as the base class for all Operators, State functions and measurements, and
+enforces the presence and consistency of methods to manipulate these objects conveniently.
 
 .. autosummary::
    :toctree: ../stubs/
    :nosignatures:
 
-   BaseOperator
-   WeightedPauliOperator
-   TPBGroupedWeightedPauliOperator
-   MatrixOperator
+   OperatorBase
 
-Operator support
+Operator Globals
 ================
+The :mod:`.operator_globals` are set of immutable Operator instances that are convenient building
+blocks to reach for while working with the Operator flow.
+
+One qubit Pauli operators:
+   :attr:`X`, :attr:`Y`, :attr:`Z`, :attr:`I`
+
+Clifford+T, and some other common non-parameterized gates:
+   :attr:`CX`, :attr:`S`, :attr:`H`, :attr:`T`, :attr:`Swap`
+
+One qubit states:
+   :attr:`Zero`, :attr:`One`, :attr:`Plus`, :attr:`Minus`
+
+Submodules
+==========
+
+Operators
+++++++++++++++++++++
+
+The Operators submodules include the PrimitiveOp, ListOp, and StateFn class groups which
+represent the primary Operator modules used in Aqua. The :mod:`legacy` submodule includes older
+Operator classes which are currently being migrated out of usage in Aqua, but are still used in
+some places.
 
 .. autosummary::
-   :toctree: ../stubs/
-   :nosignatures:
+   :toctree:
 
-    evolution_instruction
-    suzuki_expansion_slice_pauli_list
-    pauli_measurement
-    measure_pauli_z
-    covariance
-    row_echelon_F2
-    kernel_F2
-    commutator
-    check_commutativity
-    PauliGraph
-    Z2Symmetries
+   primitive_ops
+   list_ops
+   state_fns
+   legacy
+
+Converters
+++++++++++++++++++++
+
+The Converter submodules include objects which manipulate Operators, usually recursing over an
+Operator structure and changing certain Operators' representation. For example, the
+:class:`PauliTrotterExpectation` traverses an Operator structure, and replaces all of the
+:class:`OperatorStateFn` measurements containing non-diagonal Pauli terms into diagonalizing
+circuits following by :class:`OperatorStateFn` measurement containing only diagonal Paulis.
+
+.. autosummary::
+   :toctree:
+
+   converters
+   evolutions
+   expectations
 
 """
 
-from .common import (evolution_instruction, suzuki_expansion_slice_pauli_list, pauli_measurement,
+from .legacy import (evolution_instruction,
+                     suzuki_expansion_slice_pauli_list,
+                     pauli_measurement,
                      measure_pauli_z, covariance, row_echelon_F2,
                      kernel_F2, commutator, check_commutativity)
-from .pauli_graph import PauliGraph
-from .base_operator import BaseOperator
-from .weighted_pauli_operator import WeightedPauliOperator, Z2Symmetries
-from .tpb_grouped_weighted_pauli_operator import TPBGroupedWeightedPauliOperator
-from .matrix_operator import MatrixOperator
+from .legacy import (LegacyBaseOperator, WeightedPauliOperator, Z2Symmetries,
+                     TPBGroupedWeightedPauliOperator, MatrixOperator,
+                     PauliGraph, op_converter)
+
+# New Operators
+from .operator_base import OperatorBase
+from .primitive_ops import PrimitiveOp, PauliOp, MatrixOp, CircuitOp
+from .state_fns import (StateFn, DictStateFn, VectorStateFn,
+                        CircuitStateFn, OperatorStateFn)
+from .list_ops import ListOp, SummedOp, ComposedOp, TensoredOp
+from .converters import (ConverterBase, CircuitSampler, PauliBasisChange,
+                         DictToCircuitSum, AbelianGrouper)
+from .expectations import (ExpectationBase, ExpectationFactory, PauliExpectation,
+                           MatrixExpectation, AerPauliExpectation)
+from .evolutions import (EvolutionBase, EvolutionFactory, EvolvedOp, PauliTrotterEvolution,
+                         MatrixEvolution, TrotterizationBase, TrotterizationFactory, Trotter,
+                         Suzuki, QDrift)
+
+# Convenience immutable instances
+from .operator_globals import EVAL_SIG_DIGITS, X, Y, Z, I, CX, S, H, T, Swap, Zero, One, Plus, Minus
 
 __all__ = [
-    'evolution_instruction',
-    'suzuki_expansion_slice_pauli_list',
-    'pauli_measurement',
-    'measure_pauli_z',
-    'covariance',
-    'row_echelon_F2',
-    'kernel_F2',
-    'commutator',
-    'check_commutativity',
-    'PauliGraph',
-    'BaseOperator',
-    'WeightedPauliOperator',
-    'Z2Symmetries',
-    'TPBGroupedWeightedPauliOperator',
-    'MatrixOperator'
+    # Common
+    'evolution_instruction', 'suzuki_expansion_slice_pauli_list',
+    'pauli_measurement', 'measure_pauli_z',
+    'covariance', 'row_echelon_F2', 'kernel_F2', 'commutator', 'check_commutativity',
+    # Legacy
+    'PauliGraph', 'LegacyBaseOperator', 'WeightedPauliOperator',
+    'Z2Symmetries', 'TPBGroupedWeightedPauliOperator',
+    'MatrixOperator',
+    # Operators
+    'OperatorBase',
+    'PrimitiveOp', 'PauliOp', 'MatrixOp', 'CircuitOp',
+    'StateFn', 'DictStateFn', 'VectorStateFn', 'CircuitStateFn', 'OperatorStateFn',
+    'ListOp', 'SummedOp', 'ComposedOp', 'TensoredOp',
+    # Converters
+    'ConverterBase', 'CircuitSampler', 'AbelianGrouper', 'DictToCircuitSum', 'PauliBasisChange',
+    'ExpectationBase', 'ExpectationFactory', 'PauliExpectation', 'MatrixExpectation',
+    'AerPauliExpectation',
+    'EvolutionBase', 'EvolvedOp', 'EvolutionFactory', 'PauliTrotterEvolution', 'MatrixEvolution',
+    'TrotterizationBase', 'TrotterizationFactory', 'Trotter', 'Suzuki', 'QDrift',
+    # Convenience immutable instances
+    'X', 'Y', 'Z', 'I', 'CX', 'S', 'H', 'T', 'Swap', 'Zero', 'One', 'Plus', 'Minus'
 ]
diff --git a/qiskit/aqua/operators/converters/__init__.py b/qiskit/aqua/operators/converters/__init__.py
@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+Converters (:mod:`qiskit.aqua.operators.converters`)
+====================================================
+Converters are objects which manipulate Operators, usually traversing an Operator to
+change certain sub-Operators into a desired representation. Often the converted Operator is
+isomorphic or approximate to the original Operator in some way, but not always. For example,
+a converter may accept ``CircuitOp`` and return a ``SummedOp`` of ``PauliOps`` representing the
+circuit unitary. Converters may not have polynomial space or time scaling in their operations.
+On the contrary, many converters, such as a ``MatrixExpectation`` or ``MatrixEvolution``,
+which convert ``PauliOps`` to ``MatrixOps`` internally, will require time or space exponential
+in the number of qubits unless a clever trick is known (such as the use of sparse matrices).
+
+Note that not all converters are in this module, as Expectations and Evolutions are also
+converters.
+
+.. currentmodule:: qiskit.aqua.operators.converters
+
+Converter Base Class
+====================
+The converter base class simply enforces the presence of a ``convert`` method.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   ConverterBase
+
+Converters
+==========
+In addition to the base class, directory holds a few miscellaneous converters which are used
+frequently around the Operator flow.
+
+.. autosummary::
+   :toctree: ../stubs/
+   :nosignatures:
+
+   CircuitSampler
+   AbelianGrouper
+   DictToCircuitSum
+   PauliBasisChange
+
+"""
+
+from .converter_base import ConverterBase
+from .circuit_sampler import CircuitSampler
+from .pauli_basis_change import PauliBasisChange
+from .dict_to_circuit_sum import DictToCircuitSum
+from .abelian_grouper import AbelianGrouper
+
+__all__ = ['ConverterBase',
+           'CircuitSampler',
+           'PauliBasisChange',
+           'DictToCircuitSum',
+           'AbelianGrouper']