InitializeModes

class InitializeModes(occupation)

Bases: FermionicGate

Prepares (or, under simulation, certifies) a fermionic mode occupation.

This gate declares an intended occupation of the modes it is placed on. Its behavior depends on how the circuit is consumed:

  • Transpiled (synthesized to qubit gates): it produces the state – the synthesis plugin emits the gates that set the named modes to their occupation, as one would expect of an initialization gate.

  • Simulated (_apply_unitary_()): it acts as a validator rather than a producer. Given a state vector it checks that the vector’s amplitude is confined to the subspace its occupation defines and returns the vector unchanged, certifying – without mutating – that the incoming state is the intended reference so the transforms that follow act on it.

In both modes the gate constrains only the orbitals the occupation names (and, per spin sector, only along that sector’s axis), so several InitializeModes gates can be placed in parallel to seed disjoint fragments of a state independently – e.g. one gate per spin sector, or one per orbital group. A spinful gate may cover a single sector (any fragment of it) or fully specify both sectors, but a partial straddle of both is rejected (see _apply_unitary_placed_()).

Use from_hartree_fock() to construct the occupation of a Hartree-Fock reference.

Caution

This is an early development prototype. Beware of changes to its interface without warning during the pre-release development of this package.

Initializing an instance of this gate can be done with the arguments listed below.

Parameters:

occupation (Sequence[bool]) – a sequence of booleans indicating the occupation for each mode in the FermionicRegister being initialized by this gate.

Attributes

occupation

The sequence of booleans indicating the occupation for each mode in the FermionicRegister being initialized by this gate.

Methods

classmethod from_hartree_fock(norb, nelec)

Builds the gate for the Hartree-Fock reference occupation of (norb, nelec).

The Hartree-Fock determinant fills the lowest-indexed orbitals of each spin sector. Whether the reference is spinless or spinful is inferred from nelec (an int selects the spinless interpretation of the norb modes; a (n_alpha, n_beta) pair selects the spinful block-spin interpretation of the 2 * norb modes). Place the returned gate on the matching register to certify a Hartree-Fock reference state.

Parameters:

  • norb (int) – the number of spatial orbitals.

  • nelec (int | tuple[int, int]) – either a single integer for a spinless system, or a pair of integers storing the numbers of spin alpha and spin beta fermions.

Returns:

An InitializeModes gate whose occupation is the Hartree-Fock determinant.

Raises:

ValueError – if the electron count exceeds the norb orbitals available in a sector.

Return type:

Self

Protocol Methods

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

Asserts that vec is confined to this gate’s occupation subspace, returning it unchanged.

Unlike a transform gate, this gate does not modify the state: it checks that vec’s amplitude lives entirely in the subspace its occupation defines, and if so returns vec untouched. The subspace is the set of determinants whose occupation agrees with this gate on the orbitals it names, with every unnamed orbital left free – so a partial occupation (a fragment of a sector) accepts a whole family of determinants and the check composes with other parallel InitializeModes gates.

The gate’s local occupation (one flag per local mode) is placed onto the global register via freg_indices: local mode i constrains global mode freg_indices[i]. The global modes are then interpreted under the (norb, nelec) convention:

  • Spinless (nelec is an int): the norb modes are orbitals directly; the check is over the C(norb, nelec)-dimensional space.

  • Spinful (nelec is a pair): under the block-spin convention modes 0..norb are alpha orbitals and modes norb..2*norb are beta orbitals. A gate touching a single sector constrains that sector’s axis of the (dim_a, dim_b) state (a set of full rows for an alpha gate, or full columns for a beta gate) and leaves the other axis free, so it composes with parallel gates on the other sector. A gate may also cover both sectors, but only when it pins a complete determinant (every orbital of both sectors named, none left free); a partial straddle – constraining some orbitals of both sectors while leaving others free – is rejected, since it is not a product of per-axis subspaces and cannot compose (use one gate per sector instead).

The check is on confinement, not equality: an incoming amplitude may carry any phase and any magnitude within the subspace (a global phase or normalization is physically irrelevant), so this validates the reference without pinning it to a specific determinant vector.

Parameters:

  • vec (ndarray) – the state vector to validate. Its length must match the (norb, nelec) sector dimension.

  • norb (int) – the number of spatial orbitals of the global state vector.

  • nelec (int | tuple[int, int]) – either a single integer for a spinless system, or a pair of integers storing the numbers of spin alpha and spin beta fermions. An integer selects the spinless mode interpretation (the norb modes are orbitals); a pair selects the spinful (orb, spin) block-spin interpretation of the 2 * norb modes.

  • copy (bool) – accepted for protocol conformance but has no effect – this gate does not mutate the state, so vec is returned as-is regardless.

  • freg_indices (list[int]) – the absolute (global) mode indices that this gate’s local modes map onto.

Returns:

The input vec, unchanged, once its confinement to the occupation subspace is verified.

Raises:

ValueError – if an occupied mode falls outside the range implied by norb; if a spinful gate partially straddles both spin sectors (without pinning a full determinant); if vec’s length does not match the (norb, nelec) sector dimension; or if vec has amplitude outside the subspace the occupation defines.

Return type:

ndarray