499 lines
20 KiB
Plaintext
499 lines
20 KiB
Plaintext
---
|
||
title: ZZFeatureMap (v1.2)
|
||
description: API reference for qiskit.circuit.library.ZZFeatureMap in qiskit v1.2
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.circuit.library.ZZFeatureMap
|
||
---
|
||
|
||
# ZZFeatureMap
|
||
|
||
<Class id="qiskit.circuit.library.ZZFeatureMap" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/library/data_preparation/zz_feature_map.py#L20-L136" signature="qiskit.circuit.library.ZZFeatureMap(feature_dimension, reps=2, entanglement='full', data_map_func=None, parameter_prefix='x', insert_barriers=False, name='ZZFeatureMap')" modifiers="class">
|
||
Bases: [`PauliFeatureMap`](qiskit.circuit.library.PauliFeatureMap "qiskit.circuit.library.data_preparation.pauli_feature_map.PauliFeatureMap")
|
||
|
||
Second-order Pauli-Z evolution circuit.
|
||
|
||
For 3 qubits and 1 repetition and linear entanglement the circuit is represented by:
|
||
|
||
```python
|
||
┌───┐┌────────────────┐
|
||
┤ H ├┤ P(2.0*φ(x[0])) ├──■───────────────────────────■───────────────────────────────────
|
||
├───┤├────────────────┤┌─┴─┐┌─────────────────────┐┌─┴─┐
|
||
┤ H ├┤ P(2.0*φ(x[1])) ├┤ X ├┤ P(2.0*φ(x[0],x[1])) ├┤ X ├──■───────────────────────────■──
|
||
├───┤├────────────────┤└───┘└─────────────────────┘└───┘┌─┴─┐┌─────────────────────┐┌─┴─┐
|
||
┤ H ├┤ P(2.0*φ(x[2])) ├─────────────────────────────────┤ X ├┤ P(2.0*φ(x[1],x[2])) ├┤ X ├
|
||
└───┘└────────────────┘ └───┘└─────────────────────┘└───┘
|
||
```
|
||
|
||
where $\varphi$ is a classical non-linear function, which defaults to $\varphi(x) = x$ if and $\varphi(x,y) = (\pi - x)(\pi - y)$.
|
||
|
||
Examples:
|
||
|
||
```python
|
||
from qiskit.circuit.library import ZZFeatureMap
|
||
prep = ZZFeatureMap(2, reps=1)
|
||
print(prep.decompose())
|
||
```
|
||
|
||
```python
|
||
┌───┐┌─────────────┐
|
||
q_0: ┤ H ├┤ P(2.0*x[0]) ├──■──────────────────────────────────────■──
|
||
├───┤├─────────────┤┌─┴─┐┌────────────────────────────────┐┌─┴─┐
|
||
q_1: ┤ H ├┤ P(2.0*x[1]) ├┤ X ├┤ P(2.0*(pi - x[0])*(pi - x[1])) ├┤ X ├
|
||
└───┘└─────────────┘└───┘└────────────────────────────────┘└───┘
|
||
```
|
||
|
||
```python
|
||
from qiskit.circuit.library import EfficientSU2
|
||
classifier = ZZFeatureMap(3).compose(EfficientSU2(3))
|
||
classifier.num_parameters
|
||
```
|
||
|
||
```python
|
||
27
|
||
```
|
||
|
||
```python
|
||
classifier.parameters # 'x' for the data preparation, 'θ' for the SU2 parameters
|
||
```
|
||
|
||
```python
|
||
ParameterView([
|
||
ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
|
||
ParameterVectorElement(x[2]), ParameterVectorElement(θ[0]),
|
||
ParameterVectorElement(θ[1]), ParameterVectorElement(θ[2]),
|
||
ParameterVectorElement(θ[3]), ParameterVectorElement(θ[4]),
|
||
ParameterVectorElement(θ[5]), ParameterVectorElement(θ[6]),
|
||
ParameterVectorElement(θ[7]), ParameterVectorElement(θ[8]),
|
||
ParameterVectorElement(θ[9]), ParameterVectorElement(θ[10]),
|
||
ParameterVectorElement(θ[11]), ParameterVectorElement(θ[12]),
|
||
ParameterVectorElement(θ[13]), ParameterVectorElement(θ[14]),
|
||
ParameterVectorElement(θ[15]), ParameterVectorElement(θ[16]),
|
||
ParameterVectorElement(θ[17]), ParameterVectorElement(θ[18]),
|
||
ParameterVectorElement(θ[19]), ParameterVectorElement(θ[20]),
|
||
ParameterVectorElement(θ[21]), ParameterVectorElement(θ[22]),
|
||
ParameterVectorElement(θ[23])
|
||
])
|
||
```
|
||
|
||
```python
|
||
classifier.count_ops()
|
||
```
|
||
|
||
```python
|
||
OrderedDict([('ZZFeatureMap', 1), ('EfficientSU2', 1)])
|
||
```
|
||
|
||
Create a new second-order Pauli-Z expansion.
|
||
|
||
**Parameters**
|
||
|
||
* **feature\_dimension** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Number of features.
|
||
* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of repeated circuits, has a min. value of 1.
|
||
* **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]] |* [*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.13)")*\[\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*],* [*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – Specifies the entanglement structure. Refer to [`NLocal`](qiskit.circuit.library.NLocal "qiskit.circuit.library.NLocal") for detail.
|
||
* **data\_map\_func** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.13)")*\[\[*[*ndarray*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray "(in NumPy v2.1)")*],* [*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*] | None*) – A mapping function for data x.
|
||
* **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The prefix used if default parameters are generated.
|
||
* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If True, barriers are inserted in between the evolution instructions and hadamard layers.
|
||
|
||
**Raises**
|
||
|
||
[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – If the feature dimension is smaller than 2.
|
||
|
||
## Attributes
|
||
|
||
### alpha
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.alpha">
|
||
The Pauli rotation factor (alpha).
|
||
|
||
**Returns**
|
||
|
||
The Pauli rotation factor.
|
||
</Attribute>
|
||
|
||
### ancillas
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.ancillas">
|
||
A list of `AncillaQubit`s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### calibrations
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.calibrations">
|
||
Return calibration dictionary.
|
||
|
||
The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}`
|
||
</Attribute>
|
||
|
||
### clbits
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.clbits">
|
||
A list of `Clbit`s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### data
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.data">
|
||
The circuit data (instructions and context).
|
||
|
||
**Returns**
|
||
|
||
a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction.
|
||
|
||
**Return type**
|
||
|
||
QuantumCircuitData
|
||
</Attribute>
|
||
|
||
### entanglement
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.entanglement">
|
||
Get the entanglement strategy.
|
||
|
||
**Returns**
|
||
|
||
The entanglement strategy, see `get_entangler_map()` for more detail on how the format is interpreted.
|
||
</Attribute>
|
||
|
||
### entanglement\_blocks
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.entanglement_blocks">
|
||
The blocks in the entanglement layers.
|
||
|
||
**Returns**
|
||
|
||
The blocks in the entanglement layers.
|
||
</Attribute>
|
||
|
||
### feature\_dimension
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.feature_dimension">
|
||
Returns the feature dimension (which is equal to the number of qubits).
|
||
|
||
**Returns**
|
||
|
||
The feature dimension of this feature map.
|
||
</Attribute>
|
||
|
||
### flatten
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.flatten">
|
||
Returns whether the circuit is wrapped in nested gates/instructions or flattened.
|
||
</Attribute>
|
||
|
||
### global\_phase
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.global_phase">
|
||
The global phase of the current circuit scope in radians.
|
||
</Attribute>
|
||
|
||
### initial\_state
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.initial_state">
|
||
Return the initial state that is added in front of the n-local circuit.
|
||
|
||
**Returns**
|
||
|
||
The initial state.
|
||
</Attribute>
|
||
|
||
### insert\_barriers
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.insert_barriers">
|
||
If barriers are inserted in between the layers or not.
|
||
|
||
**Returns**
|
||
|
||
`True`, if barriers are inserted in between the layers, `False` if not.
|
||
</Attribute>
|
||
|
||
### instances
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.instances" attributeValue="164" />
|
||
|
||
### layout
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.layout">
|
||
Return any associated layout information about the circuit
|
||
|
||
This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.PassManager.run") to retain information about the permutations caused on the input circuit by transpilation.
|
||
|
||
There are two types of permutations caused by the [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing.
|
||
</Attribute>
|
||
|
||
### metadata
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.metadata">
|
||
Arbitrary user-defined metadata for the circuit.
|
||
|
||
Qiskit will not examine the content of this mapping, but it will pass it through the transpiler and reattach it to the output, so you can track your own metadata.
|
||
</Attribute>
|
||
|
||
### num\_ancillas
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_ancillas">
|
||
Return the number of ancilla qubits.
|
||
</Attribute>
|
||
|
||
### num\_captured\_vars
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_captured_vars">
|
||
The number of real-time classical variables in the circuit marked as captured from an enclosing scope.
|
||
|
||
This is the length of the `iter_captured_vars()` iterable. If this is non-zero, [`num_input_vars`](#qiskit.circuit.library.ZZFeatureMap.num_input_vars "qiskit.circuit.library.ZZFeatureMap.num_input_vars") must be zero.
|
||
</Attribute>
|
||
|
||
### num\_clbits
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_clbits">
|
||
Return number of classical bits.
|
||
</Attribute>
|
||
|
||
### num\_declared\_vars
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_declared_vars">
|
||
The number of real-time classical variables in the circuit that are declared by this circuit scope, excluding inputs or captures.
|
||
|
||
This is the length of the `iter_declared_vars()` iterable.
|
||
</Attribute>
|
||
|
||
### num\_input\_vars
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_input_vars">
|
||
The number of real-time classical variables in the circuit marked as circuit inputs.
|
||
|
||
This is the length of the `iter_input_vars()` iterable. If this is non-zero, [`num_captured_vars`](#qiskit.circuit.library.ZZFeatureMap.num_captured_vars "qiskit.circuit.library.ZZFeatureMap.num_captured_vars") must be zero.
|
||
</Attribute>
|
||
|
||
### num\_layers
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_layers">
|
||
Return the number of layers in the n-local circuit.
|
||
|
||
**Returns**
|
||
|
||
The number of layers in the circuit.
|
||
</Attribute>
|
||
|
||
### num\_parameters
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_parameters">
|
||
The number of parameter objects in the circuit.
|
||
</Attribute>
|
||
|
||
### num\_parameters\_settable
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_parameters_settable">
|
||
The number of distinct parameters.
|
||
</Attribute>
|
||
|
||
### num\_qubits
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_qubits">
|
||
Returns the number of qubits in this circuit.
|
||
|
||
**Returns**
|
||
|
||
The number of qubits.
|
||
</Attribute>
|
||
|
||
### num\_vars
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.num_vars">
|
||
The number of real-time classical variables in the circuit.
|
||
|
||
This is the length of the `iter_vars()` iterable.
|
||
</Attribute>
|
||
|
||
### op\_start\_times
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.op_start_times">
|
||
Return a list of operation start times.
|
||
|
||
This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit.
|
||
|
||
**Returns**
|
||
|
||
List of integers representing instruction start times. The index corresponds to the index of instruction in `QuantumCircuit.data`.
|
||
|
||
**Raises**
|
||
|
||
[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.13)") – When circuit is not scheduled.
|
||
</Attribute>
|
||
|
||
### ordered\_parameters
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.ordered_parameters">
|
||
The parameters used in the underlying circuit.
|
||
|
||
This includes float values and duplicates.
|
||
|
||
**Examples**
|
||
|
||
```python
|
||
>>> # prepare circuit ...
|
||
>>> print(nlocal)
|
||
┌───────┐┌──────────┐┌──────────┐┌──────────┐
|
||
q_0: ┤ Ry(1) ├┤ Ry(θ[1]) ├┤ Ry(θ[1]) ├┤ Ry(θ[3]) ├
|
||
└───────┘└──────────┘└──────────┘└──────────┘
|
||
>>> nlocal.parameters
|
||
{Parameter(θ[1]), Parameter(θ[3])}
|
||
>>> nlocal.ordered_parameters
|
||
[1, Parameter(θ[1]), Parameter(θ[1]), Parameter(θ[3])]
|
||
```
|
||
|
||
**Returns**
|
||
|
||
The parameters objects used in the circuit.
|
||
</Attribute>
|
||
|
||
### parameter\_bounds
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.parameter_bounds">
|
||
The parameter bounds for the unbound parameters in the circuit.
|
||
|
||
**Returns**
|
||
|
||
A list of pairs indicating the bounds, as (lower, upper). None indicates an unbounded parameter in the corresponding direction. If `None` is returned, problem is fully unbounded.
|
||
</Attribute>
|
||
|
||
### parameters
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.parameters">
|
||
The parameters defined in the circuit.
|
||
|
||
This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically.
|
||
|
||
**Examples**
|
||
|
||
The snippet below shows that insertion order of parameters does not matter.
|
||
|
||
```python
|
||
>>> from qiskit.circuit import QuantumCircuit, Parameter
|
||
>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
|
||
>>> circuit = QuantumCircuit(1)
|
||
>>> circuit.rx(b, 0)
|
||
>>> circuit.rz(elephant, 0)
|
||
>>> circuit.ry(a, 0)
|
||
>>> circuit.parameters # sorted alphabetically!
|
||
ParameterView([Parameter(a), Parameter(b), Parameter(elephant)])
|
||
```
|
||
|
||
Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting.
|
||
|
||
```python
|
||
>>> from qiskit.circuit import QuantumCircuit, Parameter
|
||
>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
|
||
>>> circuit = QuantumCircuit(1)
|
||
>>> circuit.u(*angles, 0)
|
||
>>> circuit.draw()
|
||
┌─────────────────────────────┐
|
||
q: ┤ U(angle_1,angle_2,angle_10) ├
|
||
└─────────────────────────────┘
|
||
>>> circuit.parameters
|
||
ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)])
|
||
```
|
||
|
||
To respect numerical sorting, a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used.
|
||
|
||
```python
|
||
>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
|
||
>>> x = ParameterVector("x", 12)
|
||
>>> circuit = QuantumCircuit(1)
|
||
>>> for x_i in x:
|
||
... circuit.rx(x_i, 0)
|
||
>>> circuit.parameters
|
||
ParameterView([
|
||
ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
|
||
ParameterVectorElement(x[2]), ParameterVectorElement(x[3]),
|
||
..., ParameterVectorElement(x[11])
|
||
])
|
||
```
|
||
|
||
**Returns**
|
||
|
||
The sorted [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit.
|
||
</Attribute>
|
||
|
||
### paulis
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.paulis">
|
||
The Pauli strings used in the entanglement of the qubits.
|
||
|
||
**Returns**
|
||
|
||
The Pauli strings as list.
|
||
</Attribute>
|
||
|
||
### preferred\_init\_points
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.preferred_init_points">
|
||
The initial points for the parameters. Can be stored as initial guess in optimization.
|
||
|
||
**Returns**
|
||
|
||
The initial values for the parameters, or None, if none have been set.
|
||
</Attribute>
|
||
|
||
### prefix
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.prefix" attributeValue="'circuit'" />
|
||
|
||
### qregs
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.qregs" attributeTypeHint="list[QuantumRegister]">
|
||
A list of the `QuantumRegister`s in this circuit. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### qubits
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.qubits">
|
||
A list of `Qubit`s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### reps
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.reps">
|
||
The number of times rotation and entanglement block are repeated.
|
||
|
||
**Returns**
|
||
|
||
The number of repetitions.
|
||
</Attribute>
|
||
|
||
### rotation\_blocks
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.rotation_blocks">
|
||
The blocks in the rotation layers.
|
||
|
||
**Returns**
|
||
|
||
The blocks in the rotation layers.
|
||
</Attribute>
|
||
|
||
### name
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.name" attributeTypeHint="str">
|
||
A human-readable name for the circuit.
|
||
</Attribute>
|
||
|
||
### cregs
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.cregs" attributeTypeHint="list[ClassicalRegister]">
|
||
A list of the `ClassicalRegister`s in this circuit. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### duration
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.duration" attributeTypeHint="int | float | None">
|
||
The total duration of the circuit, set by a scheduling transpiler pass. Its unit is specified by [`unit`](#qiskit.circuit.library.ZZFeatureMap.unit "qiskit.circuit.library.ZZFeatureMap.unit").
|
||
</Attribute>
|
||
|
||
### unit
|
||
|
||
<Attribute id="qiskit.circuit.library.ZZFeatureMap.unit">
|
||
The unit that [`duration`](#qiskit.circuit.library.ZZFeatureMap.duration "qiskit.circuit.library.ZZFeatureMap.duration") is specified in.
|
||
</Attribute>
|
||
</Class>
|
||
|