---
title: excitation_preserving (latest version)
description: API reference for qiskit.circuit.library.excitation_preserving in the latest version of qiskit
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.circuit.library.excitation_preserving
---

# qiskit.circuit.library.excitation\_preserving

`qiskit.circuit.library.excitation_preserving(num_qubits, mode='iswap', entanglement='full', reps=3, skip_unentangled_qubits=False, skip_final_rotation_layer=False, parameter_prefix='θ', insert_barriers=False, name='ExcitationPreserving')`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/circuit/library/n_local/excitation_preserving.py#L26-L139)

The heuristic excitation-preserving wave function ansatz.

The `excitation_preserving` circuit preserves the ratio of $|00\rangle$, $|01\rangle + |10\rangle$ and $|11\rangle$ states. To this end, this circuit uses two-qubit interactions of the form

$$
\newcommand{\rotationangle}{\theta/2}

\begin{pmatrix}
1 & 0 & 0 & 0 \\
0 & \cos\left(\rotationangle\right) & -i\sin\left(\rotationangle\right) & 0 \\
0 & -i\sin\left(\rotationangle\right) & \cos\left(\rotationangle\right) & 0 \\
0 & 0 & 0 & e^{-i\phi}
\end{pmatrix}
$$

for the mode `"fsim"` or with $e^{-i\phi} = 1$ for the mode `"iswap"`.

Note that other wave functions, such as UCC-ansatzes, are also excitation preserving. However these can become complex quickly, while this heuristically motivated circuit follows a simpler pattern.

This trial wave function consists of layers of $Z$ rotations with 2-qubit entanglements. The entanglement is created using $XX+YY$ rotations and optionally a controlled-phase gate for the mode `"fsim"`.

Examples:

With linear entanglement, this circuit is given by:

```python
from qiskit.circuit.library import excitation_preserving

ansatz = excitation_preserving(3, reps=1, insert_barriers=True, entanglement="linear")
ansatz.draw("mpl")
```

![Circuit diagram output by the previous code.](https://eu-de.quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-circuit-library-excitation_preserving-1.avif)

The entanglement structure can be explicitly specified with the `entanglement` argument. The `"fsim"` mode includes an additional parameterized [`CPhaseGate`](/docs/api/qiskit/qiskit.circuit.library.CPhaseGate "qiskit.circuit.library.CPhaseGate") in each block:

```python
ansatz = excitation_preserving(3, reps=1, mode="fsim", entanglement=[[0, 2]])
ansatz.draw("mpl")
```

![Circuit diagram output by the previous code.](https://eu-de.quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-circuit-library-excitation_preserving-2_00.avif)

![Circuit diagram output by the previous code.](https://eu-de.quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-circuit-library-excitation_preserving-2_01.avif)

**Parameters**

- **num\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of qubits.
- **mode** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – Choose the entangler mode, can be “iswap” or “fsim”.
- **reps** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Specifies how often the structure of a rotation layer followed by an entanglement layer is repeated.
- **entanglement** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]] |* [*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]]] |* [*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)*\[\[*[*int*](https://docs.python.org/3/library/functions.html#int)*],* [*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]] |* [*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)  *|*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*Iterable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*]]]]*) – The indices specifying on which qubits the input blocks act. See [`n_local()`](/docs/api/qiskit/qiskit.circuit.library.n_local "qiskit.circuit.library.n_local") for detailed information.
- **skip\_final\_rotation\_layer** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Whether a final rotation layer is added to the circuit.
- **skip\_unentangled\_qubits** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If `True`, the rotation gates act only on qubits that are entangled. If `False`, the rotation gates act on all qubits.
- **parameter\_prefix** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – The name of the free parameters.
- **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If True, barriers are inserted in between each layer. If False, no barriers are inserted.
- **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – The name of the circuit.

**Returns**

An excitation-preserving circuit.

**Return type**

[*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit")