FermionicCircuit¶

class FermionicCircuit(num_modes)¶

Bases: object

A wrapper around QuantumCircuit for expressing fermionic circuits.

This class maintains a reduced API compared to the full API of the underlying QuantumCircuit. This is done to avoid exposing (among other methods) the ability to apply qubit-based gates onto a fermionic circuit, which would not be a well-defined operation in the general case.

barrier() is re-exposed because it is an exception to that rule: a barrier acts on modes without interpreting them and carries no unitary content, so it is as well-defined on a fermionic register as it is on a qubit one.

Measurements are likewise available, via measure() and measure_all(). They are the one non-unitary operation this circuit carries, so they are reached through those methods rather than through append(), which stays restricted to unitary gates. Whether the resulting bit is meaningful depends on the fermion-to-qubit encoding chosen later, during transpilation, rather than on this circuit (see FermionicMeasure).

Initializing a circuit instance can be done with the arguments listed below.

Parameters:: num_modes (int) – the number of fermionic modes on which this circuit acts.

Attributes

metadata¶: Re-exposes metadata.

modes¶: The fermionic mode bits that this circuit acts upon.

register: FermionicRegister¶: The inner circuit’s FermionicRegister.

Methods

add_register(*cregs)¶

Adds classical registers to this circuit.

Only classical registers can be added: the fermionic mode register is fixed at construction and is available as register.

Parameters:: cregs (ClassicalRegister) – the classical registers to add.
Raises:: ValueError – if any of the provided registers is not a ClassicalRegister.
Return type:: None

append(gate, fargs, cargs=None, *, copy=True)¶

Appends a FermionicGate to this circuit.

Parameters:

gate (FermionicGate) – the fermionic gate to apply.
fargs (Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]) – the fermionic modes on which this gate acts.
cargs (None) –
the classical bits on which this gate acts.

Warning

No gates of this kind are currently supported. A FermionicGate is unitary and so takes no classical bits; use measure() to add the one instruction that does.
copy (bool) – forwarded to append().

Raises:

ValueError – if the provided gate is not an instance of FermionicGate.

Return type:

None

barrier(*fargs, label=None)¶

Re-exposes barrier().

A barrier carries no unitary effect. It marks a synchronization point that the optimization passes will not fuse gates across, which is how you keep a pass such as MergeOrbitalRotations or MergeSlaterDeterminantPreparation from combining the gates on either side of it.

Parameters:

fargs (Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]) – the fermionic modes on which to place the barrier. When omitted, the barrier spans every mode of this circuit.
label (str | None) – the string label of the barrier.

Return type:

None

compose(other, fargs=None, *, front=False, inplace=False)¶

Composes another FermionicCircuit onto this one.

The instructions of other are inlined into this circuit, rather than wrapped into a single gate. This mirrors compose() with its default wrap=False. The wrap=True counterpart is deliberately not offered: a dedicated encapsulation mechanism is planned instead, so adding a second way to box up a block of instructions here would leave two patterns solving the same problem.

Parameters:

other (FermionicCircuit) – the circuit to compose onto this one. It may act on fewer modes than this circuit, in which case fargs selects the modes it is placed on.
fargs (Qubit | QuantumRegister | int | slice | Sequence[Qubit | int] | None) – the fermionic modes of this circuit onto which other is placed. Defaults to all of this circuit’s modes, in order.
front (bool) – whether to compose other before rather than after this circuit’s instructions.
inplace (bool) – whether to modify this circuit rather than return a new one.

Returns:

The composed circuit, or None if inplace is set.

Raises:

ValueError – if other is not an instance of FermionicCircuit. Only fermionic circuits are accepted because the plain compose() would happily inline qubit-based instructions, bypassing the type guard that append() enforces.
CircuitError – if other acts on more modes than this circuit, or fargs does not match its width.

Return type:

FermionicCircuit | None

count_ops()¶

Re-exposes count_ops().

Return type:: OrderedDict[str, int]

decompose(gates_to_decompose=None, reps=1)¶

Re-exposes decompose().

Parameters:

gates_to_decompose (str | type[Instruction] | Sequence[str | type[Instruction]] | None)
reps (int)

Return type:

FermionicCircuit

draw(*args, **kwargs)¶

Directly exposes the inner circuit’s draw() method.

Return type:: Any

measure(fargs, cargs)¶

Measures the given fermionic modes into the given classical bits.

This appends one FermionicMeasure per mode. The classical bits must already exist; add them with add_register(), or use measure_all(), which creates a register for you.

The pairing of modes to classical bits is yours, and it is preserved through transpilation: the mode a measurement acts on is permuted by a pass such as RelabelModes, but the classical bit it writes into is not.

Parameters:

fargs (FermionicSpecifier) – the fermionic modes to measure.
cargs (ClbitSpecifier) – the classical bits to write the outcomes into.

Raises:

CircuitError – if the number of modes and classical bits differ, or if a specifier does not resolve against this circuit.

Return type:

None

measure_all(*, add_bits=True, inplace=True)¶

Measures every mode of this circuit, in order, into one classical bit each.

Mode i is measured into classical bit i, so a sampled bitstring is indexed by mode.

Note

Unlike measure_all(), this inserts no barrier() before the measurements. Call barrier() yourself beforehand if you want one there.

Parameters:

add_bits (bool) – whether to add a new meas ClassicalRegister sized to this circuit’s modes. When this is False, the existing classical bits are used instead, and calling this method again simply measures into them a second time.
inplace (bool) – whether to modify this circuit rather than return a new one.

Returns:

The measured circuit, or None if inplace is set.

Raises:

CircuitError – if add_bits is set and this circuit already carries a register named meas (which is what a second measure_all() call runs into). Pass add_bits=False to measure into the existing bits instead.
ValueError – if add_bits is not set and this circuit has fewer classical bits than modes.

Return type:

FermionicCircuit | None

repeat(reps, *, insert_barriers=False)¶

Repeats this circuit reps times.

The repetitions are flattened: the returned circuit holds this circuit’s instructions reps times in sequence, rather than one gate wrapping the circuit as repeat() produces. As a consequence count_ops() scales with reps, and decompose() decomposes the repeated body rather than peeling off a repetition.

Flattening also leaves the gates that meet at a repetition boundary adjacent, so the optimization passes can fuse them. Set insert_barriers to keep the repetitions apart instead, which places a barrier() that those passes do not fuse across.

Note

This is unrelated to the reps argument of FermionicSuzukiTrotter, which subdivides a single Evolution into more, shorter factors. Repeating a circuit holding one Evolution merely multiplies its total evolution time.

See also

Work with fermionic circuits works through a repeated Trotter step, including the boundary fusion and how to prevent it.

Parameters:

reps (int) – how often this circuit should be repeated. Repeating it zero times yields an empty circuit, which is the identity.
insert_barriers (bool) – whether to place a barrier() between consecutive repetitions. No barrier is placed after the final repetition, so the returned circuit ends on the same instruction it would without this argument.

Returns:

A new circuit containing reps repetitions of this circuit.

Raises:

ValueError – if reps is negative.

Return type:

FermionicCircuit

Protocol Methods

_apply_unitary_(vec, norb, nelec, copy)¶

Applies this circuit to an ffsim state vector, implementing ffsim’s protocol.

See _apply_unitary_placed_() for the details; this method assumes the circuit’s modes are the vector’s modes 0..num_modes (i.e. an identity mode placement).

Parameters:

vec (ndarray) – the state vector to apply this circuit to. An empty circuit returns it unchanged.
norb (int) – the number of spatial orbitals.
nelec (int | tuple[int, int]) – either a single integer representing the number of fermions for a spinless system, or a pair of integers storing the numbers of spin alpha and spin beta fermions.
copy (bool) – whether to copy the vector before operating on it.

Returns:

The transformed vector.

Raises:

TypeError – if a circuit instruction other than a Barrier does not implement ffsim’s ffsim.SupportsApplyUnitary protocol.
ValueError – if a circuit instruction declines to apply its unitary for the given norb and nelec; or if an instruction implementing only the plain _apply_unitary_ protocol is placed on a non-identity mode subset.

Return type:

ndarray

_apply_unitary_placed_(vec, norb, nelec, copy, freg_indices)¶

Applies this circuit after placing its modes onto the vector’s global modes.

This walks the circuit in topological order and applies each instruction’s unitary effect to the state vector via ffsim’s ffsim.SupportsApplyUnitary protocol. Each instruction’s own modes are first mapped through this circuit’s placement: a circuit-local mode m maps to the global mode freg_indices[m], so a sub-instruction acting on circuit-local modes [m0, m1, ...] is applied on the global modes [freg_indices[m0], freg_indices[m1], ...]. With the identity placement freg_indices == 0..num_modes this is exactly _apply_unitary_(); a subset placement lets this circuit act as the definition of a gate placed on a subset of a larger register (e.g. UCJ). This placement-aware extension is documented as SupportsApplyUnitaryPlaced – a package-specific protocol with no ffsim equivalent.

An instruction is placed onto its absolute modes only if it implements the placement-aware _apply_unitary_placed_ extension (SupportsApplyUnitaryPlaced). An instruction implementing only ffsim’s plain _apply_unitary_ – which has no mode argument and therefore acts on modes 0..k of the vector – can only be honored when its placement is the identity [0, 1, ..., k-1]; on any other subset the placement cannot be expressed and the instruction is rejected rather than silently applied on the wrong modes.

A Barrier is skipped: it carries no unitary effect, so it constrains transpilation without contributing to the state vector.

Parameters:

vec (ndarray) – the state vector to apply this circuit to. An empty circuit returns it unchanged.
norb (int) – the number of spatial orbitals of the global state vector.
nelec (int | tuple[int, int]) – either a single integer representing the number of fermions for a spinless system, or a pair of integers storing the numbers of spin alpha and spin beta fermions.
copy (bool) – whether to copy the vector before operating on it.
freg_indices (list[int]) – the absolute (global) mode indices that this circuit’s modes map onto.

Returns:

The transformed vector.

Raises:

TypeError – if a circuit instruction other than a Barrier does not implement ffsim’s ffsim.SupportsApplyUnitary protocol.
ValueError – if a circuit instruction declines to apply its unitary for the given norb and nelec; or if an instruction implementing only the plain _apply_unitary_ protocol is placed on a non-identity mode subset.

Return type:

ndarray