FermionicCircuit

Re-exposes metadata.

The fermionic mode bits that this circuit acts upon.

Type: FermionicRegister

The inner circuit’s FermionicRegister.

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.

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.

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

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