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 (amongst 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.

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

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.

• copy (bool) – forwarded to append().

Raises:

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

Return type:

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

Protocol Methods

_apply_unitary_(vec, norb, nelec, copy)

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

This walks the circuit in topological order and applies each instruction’s unitary effect to the state vector via ffsim’s ffsim.SupportsApplyUnitary protocol (mirrored locally as SupportsApplyUnitary). Each instruction acting on a subset of the register has its fermionic modes relabeled to their absolute (global) indices before being applied.

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 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_ (SupportsApplyUnitary) – 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.

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 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