Skip to content

Commit ba2872b

Browse files
dongreenbergmanoelmarqueswoodsp-ibm
authored
* 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>
1 parent be8f01f commit ba2872b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+6597
-82
lines changed

qiskit/aqua/operators/__init__.py

+142-44
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# This code is part of Qiskit.
44
#
5-
# (C) Copyright IBM 2019.
5+
# (C) Copyright IBM 2019, 2020.
66
#
77
# This code is licensed under the Apache License, Version 2.0. You may
88
# obtain a copy of this license in the LICENSE.txt file in the root directory
@@ -12,69 +12,167 @@
1212
# copyright notice, and modified files need to carry a notice indicating
1313
# that they have been altered from the originals.
1414

15-
"""
15+
r"""
1616
Operators (:mod:`qiskit.aqua.operators`)
1717
========================================
18-
Operators
18+
Operators and State functions are the building blocks of Quantum Algorithms.
19+
20+
A library for Quantum Algorithms & Applications is more than a collection of
21+
algorithms wrapped in Python functions. It needs to provide tools to make writing
22+
algorithms simple and easy. This is the layer of modules between the circuits and algorithms,
23+
providing the language and computational primitives for QA&A research.
24+
25+
In Aqua, we call this layer the Operator Flow. It works by unifying computation with theory
26+
through the common language of functions and operators, in a way which preserves physical
27+
intuition and programming freedom. In the Operator Flow, we construct functions over binary
28+
variables, manipulate those functions with operators, and evaluate properties of these functions
29+
with measurements.
30+
31+
The Operator Flow is meant to serve as a lingua franca between the theory and implementation
32+
of Quantum Algorithms & Applications. Meaning, the ultimate goal is that when theorists speak
33+
their theory in the Operator Flow, they are speaking valid implementation, and when the engineers
34+
speak their implementation in the Operator Flow, they are speaking valid physical formalism. To
35+
be successful, it must be fast and physically formal enough for theorists to find it easier and
36+
more natural than hacking Matlab or NumPy, and the engineers must find it straightforward enough
37+
that they can learn it as a typical software library, and learn the physics naturally and
38+
effortlessly as they learn the code. There can never be a point where we say "below this level
39+
this is all hacked out, don't come down here, stay in the interface layer above." It all must
40+
be clear and learnable.
41+
42+
Before getting into the details of the code, it's important to note that three mathematical
43+
concepts unpin the Operator Flow. We derive most of the inspiration for the code structure from
44+
`John Watrous's formalism <https://cs.uwaterloo.ca/~watrous/TQI/>`__ (but do not follow it exactly),
45+
so it may be worthwhile to review Chapters I and II, which are free online, if you feel the
46+
concepts are not clicking.
47+
48+
1. An n-qubit State function is a complex function over n binary variables, which we will
49+
often refer to as *n-qubit binary strings*. For example, the traditional quantum "zero state" is
50+
a 1-qubit state function, with a definition of f(0) = 1 and f(1) = 0.
51+
52+
2. An n-qubit Operator is a linear function taking n-qubit state functions to n-qubit state
53+
functions. For example, the Pauli X Operator is defined by f(Zero) = One and f(One) = Zero.
54+
Equivalently, an Operator can be defined as a complex function over two n-qubit binary strings,
55+
and it is sometimes convenient to picture things this way. By this definition, our Pauli X can
56+
be defined by its typical matrix elements, f(0, 0) = 0, f(1, 0) = 1, f(0, 1) = 1,
57+
f(1, 1) = 0.
58+
59+
3. An n-qubit Measurement is a functional taking n-qubit State functions to complex values.
60+
For example, a Pauli Z Measurement can be defined by f(Zero) = 0 and f(One) = 1.
61+
62+
Below, you'll find a base class for all Operators, some convenience immutable global variables
63+
which simplify Operator construction, and two groups of submodules: Operators and Converters.
1964
2065
.. currentmodule:: qiskit.aqua.operators
2166
22-
Operators
23-
=========
67+
Operator Base Class
68+
===================
69+
70+
The OperatorBase serves as the base class for all Operators, State functions and measurements, and
71+
enforces the presence and consistency of methods to manipulate these objects conveniently.
2472
2573
.. autosummary::
2674
:toctree: ../stubs/
2775
:nosignatures:
2876
29-
BaseOperator
30-
WeightedPauliOperator
31-
TPBGroupedWeightedPauliOperator
32-
MatrixOperator
77+
OperatorBase
3378
34-
Operator support
79+
Operator Globals
3580
================
81+
The :mod:`.operator_globals` are set of immutable Operator instances that are convenient building
82+
blocks to reach for while working with the Operator flow.
83+
84+
One qubit Pauli operators:
85+
:attr:`X`, :attr:`Y`, :attr:`Z`, :attr:`I`
86+
87+
Clifford+T, and some other common non-parameterized gates:
88+
:attr:`CX`, :attr:`S`, :attr:`H`, :attr:`T`, :attr:`Swap`
89+
90+
One qubit states:
91+
:attr:`Zero`, :attr:`One`, :attr:`Plus`, :attr:`Minus`
92+
93+
Submodules
94+
==========
95+
96+
Operators
97+
++++++++++++++++++++
98+
99+
The Operators submodules include the PrimitiveOp, ListOp, and StateFn class groups which
100+
represent the primary Operator modules used in Aqua. The :mod:`legacy` submodule includes older
101+
Operator classes which are currently being migrated out of usage in Aqua, but are still used in
102+
some places.
36103
37104
.. autosummary::
38-
:toctree: ../stubs/
39-
:nosignatures:
105+
:toctree:
40106
41-
evolution_instruction
42-
suzuki_expansion_slice_pauli_list
43-
pauli_measurement
44-
measure_pauli_z
45-
covariance
46-
row_echelon_F2
47-
kernel_F2
48-
commutator
49-
check_commutativity
50-
PauliGraph
51-
Z2Symmetries
107+
primitive_ops
108+
list_ops
109+
state_fns
110+
legacy
111+
112+
Converters
113+
++++++++++++++++++++
114+
115+
The Converter submodules include objects which manipulate Operators, usually recursing over an
116+
Operator structure and changing certain Operators' representation. For example, the
117+
:class:`PauliTrotterExpectation` traverses an Operator structure, and replaces all of the
118+
:class:`OperatorStateFn` measurements containing non-diagonal Pauli terms into diagonalizing
119+
circuits following by :class:`OperatorStateFn` measurement containing only diagonal Paulis.
120+
121+
.. autosummary::
122+
:toctree:
123+
124+
converters
125+
evolutions
126+
expectations
52127
53128
"""
54129

55-
from .common import (evolution_instruction, suzuki_expansion_slice_pauli_list, pauli_measurement,
130+
from .legacy import (evolution_instruction,
131+
suzuki_expansion_slice_pauli_list,
132+
pauli_measurement,
56133
measure_pauli_z, covariance, row_echelon_F2,
57134
kernel_F2, commutator, check_commutativity)
58-
from .pauli_graph import PauliGraph
59-
from .base_operator import BaseOperator
60-
from .weighted_pauli_operator import WeightedPauliOperator, Z2Symmetries
61-
from .tpb_grouped_weighted_pauli_operator import TPBGroupedWeightedPauliOperator
62-
from .matrix_operator import MatrixOperator
135+
from .legacy import (LegacyBaseOperator, WeightedPauliOperator, Z2Symmetries,
136+
TPBGroupedWeightedPauliOperator, MatrixOperator,
137+
PauliGraph, op_converter)
138+
139+
# New Operators
140+
from .operator_base import OperatorBase
141+
from .primitive_ops import PrimitiveOp, PauliOp, MatrixOp, CircuitOp
142+
from .state_fns import (StateFn, DictStateFn, VectorStateFn,
143+
CircuitStateFn, OperatorStateFn)
144+
from .list_ops import ListOp, SummedOp, ComposedOp, TensoredOp
145+
from .converters import (ConverterBase, CircuitSampler, PauliBasisChange,
146+
DictToCircuitSum, AbelianGrouper)
147+
from .expectations import (ExpectationBase, ExpectationFactory, PauliExpectation,
148+
MatrixExpectation, AerPauliExpectation)
149+
from .evolutions import (EvolutionBase, EvolutionFactory, EvolvedOp, PauliTrotterEvolution,
150+
MatrixEvolution, TrotterizationBase, TrotterizationFactory, Trotter,
151+
Suzuki, QDrift)
152+
153+
# Convenience immutable instances
154+
from .operator_globals import EVAL_SIG_DIGITS, X, Y, Z, I, CX, S, H, T, Swap, Zero, One, Plus, Minus
63155

64156
__all__ = [
65-
'evolution_instruction',
66-
'suzuki_expansion_slice_pauli_list',
67-
'pauli_measurement',
68-
'measure_pauli_z',
69-
'covariance',
70-
'row_echelon_F2',
71-
'kernel_F2',
72-
'commutator',
73-
'check_commutativity',
74-
'PauliGraph',
75-
'BaseOperator',
76-
'WeightedPauliOperator',
77-
'Z2Symmetries',
78-
'TPBGroupedWeightedPauliOperator',
79-
'MatrixOperator'
157+
# Common
158+
'evolution_instruction', 'suzuki_expansion_slice_pauli_list',
159+
'pauli_measurement', 'measure_pauli_z',
160+
'covariance', 'row_echelon_F2', 'kernel_F2', 'commutator', 'check_commutativity',
161+
# Legacy
162+
'PauliGraph', 'LegacyBaseOperator', 'WeightedPauliOperator',
163+
'Z2Symmetries', 'TPBGroupedWeightedPauliOperator',
164+
'MatrixOperator',
165+
# Operators
166+
'OperatorBase',
167+
'PrimitiveOp', 'PauliOp', 'MatrixOp', 'CircuitOp',
168+
'StateFn', 'DictStateFn', 'VectorStateFn', 'CircuitStateFn', 'OperatorStateFn',
169+
'ListOp', 'SummedOp', 'ComposedOp', 'TensoredOp',
170+
# Converters
171+
'ConverterBase', 'CircuitSampler', 'AbelianGrouper', 'DictToCircuitSum', 'PauliBasisChange',
172+
'ExpectationBase', 'ExpectationFactory', 'PauliExpectation', 'MatrixExpectation',
173+
'AerPauliExpectation',
174+
'EvolutionBase', 'EvolvedOp', 'EvolutionFactory', 'PauliTrotterEvolution', 'MatrixEvolution',
175+
'TrotterizationBase', 'TrotterizationFactory', 'Trotter', 'Suzuki', 'QDrift',
176+
# Convenience immutable instances
177+
'X', 'Y', 'Z', 'I', 'CX', 'S', 'H', 'T', 'Swap', 'Zero', 'One', 'Plus', 'Minus'
80178
]
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# -*- coding: utf-8 -*-
2+
3+
# This code is part of Qiskit.
4+
#
5+
# (C) Copyright IBM 2020.
6+
#
7+
# This code is licensed under the Apache License, Version 2.0. You may
8+
# obtain a copy of this license in the LICENSE.txt file in the root directory
9+
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
10+
#
11+
# Any modifications or derivative works of this code must retain this
12+
# copyright notice, and modified files need to carry a notice indicating
13+
# that they have been altered from the originals.
14+
15+
"""
16+
Converters (:mod:`qiskit.aqua.operators.converters`)
17+
====================================================
18+
Converters are objects which manipulate Operators, usually traversing an Operator to
19+
change certain sub-Operators into a desired representation. Often the converted Operator is
20+
isomorphic or approximate to the original Operator in some way, but not always. For example,
21+
a converter may accept ``CircuitOp`` and return a ``SummedOp`` of ``PauliOps`` representing the
22+
circuit unitary. Converters may not have polynomial space or time scaling in their operations.
23+
On the contrary, many converters, such as a ``MatrixExpectation`` or ``MatrixEvolution``,
24+
which convert ``PauliOps`` to ``MatrixOps`` internally, will require time or space exponential
25+
in the number of qubits unless a clever trick is known (such as the use of sparse matrices).
26+
27+
Note that not all converters are in this module, as Expectations and Evolutions are also
28+
converters.
29+
30+
.. currentmodule:: qiskit.aqua.operators.converters
31+
32+
Converter Base Class
33+
====================
34+
The converter base class simply enforces the presence of a ``convert`` method.
35+
36+
.. autosummary::
37+
:toctree: ../stubs/
38+
:nosignatures:
39+
40+
ConverterBase
41+
42+
Converters
43+
==========
44+
In addition to the base class, directory holds a few miscellaneous converters which are used
45+
frequently around the Operator flow.
46+
47+
.. autosummary::
48+
:toctree: ../stubs/
49+
:nosignatures:
50+
51+
CircuitSampler
52+
AbelianGrouper
53+
DictToCircuitSum
54+
PauliBasisChange
55+
56+
"""
57+
58+
from .converter_base import ConverterBase
59+
from .circuit_sampler import CircuitSampler
60+
from .pauli_basis_change import PauliBasisChange
61+
from .dict_to_circuit_sum import DictToCircuitSum
62+
from .abelian_grouper import AbelianGrouper
63+
64+
__all__ = ['ConverterBase',
65+
'CircuitSampler',
66+
'PauliBasisChange',
67+
'DictToCircuitSum',
68+
'AbelianGrouper']

0 commit comments

Comments
 (0)