n_local

class qiskit.circuit.library.n_local(num_qubits, rotation_blocks, entanglement_blocks, entanglement='full', reps=3, insert_barriers=False, parameter_prefix='θ', overwrite_block_parameters=True, skip_final_rotation_layer=False, skip_unentangled_qubits=False, name='nlocal')

Bases:

Construct an n-local variational circuit.

The structure of the n-local circuit are alternating rotation and entanglement layers. In both layers, parameterized circuit-blocks act on the circuit in a defined way. In the rotation layer, the blocks are applied stacked on top of each other, while in the entanglement layer according to the entanglement strategy. The circuit blocks can have arbitrary sizes (smaller equal to the number of qubits in the circuit). Each layer is repeated reps times, and by default a final rotation layer is appended.

For instance, a rotation block on 2 qubits and an entanglement block on 4 qubits using "linear" entanglement yields the following circuit.

┌──────┐ ░ ┌──────┐                      ░ ┌──────┐
┤0     ├─░─┤0     ├──────────────── ... ─░─┤0     ├
│  Rot │ ░ │      │┌──────┐              ░ │  Rot │
┤1     ├─░─┤1     ├┤0     ├──────── ... ─░─┤1     ├
├──────┤ ░ │  Ent ││      │┌──────┐      ░ ├──────┤
┤0     ├─░─┤2     ├┤1     ├┤0     ├ ... ─░─┤0     ├
│  Rot │ ░ │      ││  Ent ││      │      ░ │  Rot │
┤1     ├─░─┤3     ├┤2     ├┤1     ├ ... ─░─┤1     ├
├──────┤ ░ └──────┘│      ││  Ent │      ░ ├──────┤
┤0     ├─░─────────┤3     ├┤2     ├ ... ─░─┤0     ├
│  Rot │ ░         └──────┘│      │      ░ │  Rot │
┤1     ├─░─────────────────┤3     ├ ... ─░─┤1     ├
└──────┘ ░                 └──────┘      ░ └──────┘
 
|                                 |
+---------------------------------+
       repeated reps times

Entanglement:

The entanglement describes the connections of the gates in the entanglement layer. For a two-qubit gate for example, the entanglement contains pairs of qubits on which the gate should acts, e.g. [[ctrl0, target0], [ctrl1, target1], ...]. A set of default entanglement strategies is provided and can be selected by name:

• "full" entanglement is each qubit is entangled with all the others.
• "linear" entanglement is qubit $i$ entangled with qubit $i + 1$, for all $i \in \{0, 1, ... , n - 2\}$, where $n$ is the total number of qubits.
• "reverse_linear" entanglement is qubit $i$ entangled with qubit $i + 1$, for all $i \in \{n-2, n-3, ... , 1, 0\}$, where $n$ is the total number of qubits. Note that if entanglement_blocks=="cx" then this option provides the same unitary as "full" with fewer entangling gates.
• "pairwise" entanglement is one layer where qubit $i$ is entangled with qubit $i + 1$, for all even values of $i$, and then a second layer where qubit $i$ is entangled with qubit $i + 1$, for all odd values of $i$.
• "circular" entanglement is linear entanglement but with an additional entanglement of the first and last qubit before the linear part.
• "sca" (shifted-circular-alternating) entanglement is a generalized and modified version of the proposed circuit 14 in Sim et al.. It consists of circular entanglement where the “long” entanglement connecting the first with the last qubit is shifted by one each block. Furthermore the role of control and target qubits are swapped every block (therefore alternating).

If an entanglement layer contains multiple blocks, then the entanglement should be given as list of entanglements for each block. For example:

entanglement_blocks = ["rxx", "ryy"]
entanglement = ["full", "linear"]  # full for rxx and linear for ryy

or:

structure_rxx = [[0, 1], [2, 3]]
structure_ryy = [[0, 2]]
entanglement = [structure_rxx, structure_ryy]

Finally, the entanglement can vary in each repetition of the circuit. For this, we support passing a callable that takes as input the layer index and returns the entanglement for the layer in the above format. See the examples below for a concrete example.

Examples

The rotation and entanglement gates can be specified via single strings, if they are made up of a single block per layer:

from qiskit.circuit.library import n_local
 
circuit = n_local(3, "ry", "cx", "linear", reps=2, insert_barriers=True)
circuit.draw("mpl")

Multiple gates per layer can be set by passing a list. Here, for example, we use Pauli-Y and Pauli-Z rotations in the rotation layer:

circuit = n_local(3, ["ry", "rz"], "cz", "full", reps=1, insert_barriers=True)
circuit.draw("mpl")

To omit rotation or entanglement layers, the block can be set to an empty list:

circuit = n_local(4, [], "cry", reps=2)
circuit.draw("mpl")

The entanglement can be set explicitly via the entanglement argument:

entangler_map = [[0, 1], [2, 0]]
circuit = n_local(3, "x", "crx", entangler_map, reps=2)
circuit.draw("mpl")

We can set different entanglements per layer, by specifing a callable that takes as input the current layer index, and returns the entanglement structure. For example, the following uses different entanglements for odd and even layers:

Parameters

• num_qubits (int) – The number of qubits of the circuit.
• rotation_blocks (str |Gate | Iterable[str |Gate]) – The blocks used in the rotation layers. If multiple are passed, these will be applied one after another (like new sub-layers).
• entanglement_blocks (str |Gate | Iterable[str |Gate]) – The blocks used in the entanglement layers. If multiple are passed, these will be applied one after another.
• entanglement (BlockEntanglement | Iterable[BlockEntanglement] | Callable[[int], BlockEntanglement | Iterable[BlockEntanglement]]) – The indices specifying on which qubits the input blocks act. This is specified by string describing an entanglement strategy (see the additional info) or a list of qubit connections. If a list of entanglement blocks is passed, different entanglement for each block can be specified by passing a list of entanglements. To specify varying entanglement for each repetition, pass a callable that takes as input the layer and returns the entanglement for that layer. Defaults to "full", meaning an all-to-all entanglement structure.
• reps (int) – Specifies how often the rotation blocks and entanglement blocks are repeated.
• insert_barriers (bool) – If True, barriers are inserted in between each layer. If False, no barriers are inserted.
• parameter_prefix (str) – The prefix used if default parameters are generated.
• overwrite_block_parameters (bool) – If the parameters in the added blocks should be overwritten. If False, the parameters in the blocks are not changed.
• skip_final_rotation_layer (bool) – Whether a final rotation layer is added to the circuit.
• skip_unentangled_qubits (bool) – If True, the rotation gates act only on qubits that are entangled. If False, the rotation gates act on all qubits.
• name (str | None) – The name of the circuit.

Returns

An n-local circuit.

Return type

QuantumCircuit