|
2 | 2 |
|
3 | 3 | # This code is part of Qiskit.
|
4 | 4 | #
|
5 |
| -# (C) Copyright IBM 2019. |
| 5 | +# (C) Copyright IBM 2019, 2020. |
6 | 6 | #
|
7 | 7 | # This code is licensed under the Apache License, Version 2.0. You may
|
8 | 8 | # obtain a copy of this license in the LICENSE.txt file in the root directory
|
|
12 | 12 | # copyright notice, and modified files need to carry a notice indicating
|
13 | 13 | # that they have been altered from the originals.
|
14 | 14 |
|
15 |
| -""" |
| 15 | +r""" |
16 | 16 | Operators (:mod:`qiskit.aqua.operators`)
|
17 | 17 | ========================================
|
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. |
19 | 64 |
|
20 | 65 | .. currentmodule:: qiskit.aqua.operators
|
21 | 66 |
|
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. |
24 | 72 |
|
25 | 73 | .. autosummary::
|
26 | 74 | :toctree: ../stubs/
|
27 | 75 | :nosignatures:
|
28 | 76 |
|
29 |
| - BaseOperator |
30 |
| - WeightedPauliOperator |
31 |
| - TPBGroupedWeightedPauliOperator |
32 |
| - MatrixOperator |
| 77 | + OperatorBase |
33 | 78 |
|
34 |
| -Operator support |
| 79 | +Operator Globals |
35 | 80 | ================
|
| 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. |
36 | 103 |
|
37 | 104 | .. autosummary::
|
38 |
| - :toctree: ../stubs/ |
39 |
| - :nosignatures: |
| 105 | + :toctree: |
40 | 106 |
|
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 |
52 | 127 |
|
53 | 128 | """
|
54 | 129 |
|
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, |
56 | 133 | measure_pauli_z, covariance, row_echelon_F2,
|
57 | 134 | 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 |
63 | 155 |
|
64 | 156 | __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' |
80 | 178 | ]
|
0 commit comments