--- title: InitializeModes (latest version) description: API reference for qiskit_fermions.circuit.library.InitializeModes in the latest version of qiskit-fermions source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-fermions/circuit-library-initialize-modes --- # InitializeModes *class* `InitializeModes(occupation)` Bases: [`FermionicGate`](/docs/api/qiskit-fermions/circuit-fermionic-gate "qiskit_fermions.circuit.fermionic_gate.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`](#qiskit_fermions.circuit.library.InitializeModes.occupation "qiskit_fermions.circuit.library.InitializeModes.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`](#qiskit_fermions.circuit.library.InitializeModes "qiskit_fermions.circuit.library.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_()`](#qiskit_fermions.circuit.library.InitializeModes._apply_unitary_placed_ "qiskit_fermions.circuit.library.InitializeModes._apply_unitary_placed_")). Use [`from_hartree_fock()`](#qiskit_fermions.circuit.library.InitializeModes.from_hartree_fock "qiskit_fermions.circuit.library.InitializeModes.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*](https://docs.python.org/3/library/functions.html#bool)*]*) – a sequence of booleans indicating the occupation for each mode in the [`FermionicRegister`](/docs/api/qiskit-fermions/circuit-fermionic-register "qiskit_fermions.circuit.FermionicRegister") being initialized by this gate. ## Attributes ### occupation The sequence of booleans indicating the occupation for each mode in the [`FermionicRegister`](/docs/api/qiskit-fermions/circuit-fermionic-register "qiskit_fermions.circuit.FermionicRegister") being initialized by this gate. ## Methods ### from\_hartree\_fock *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*](https://docs.python.org/3/library/functions.html#int)) – the number of spatial orbitals. - **nelec** ([*int*](https://docs.python.org/3/library/functions.html#int) *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#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`](#qiskit_fermions.circuit.library.InitializeModes "qiskit_fermions.circuit.library.InitializeModes") gate whose occupation is the Hartree-Fock determinant. **Raises** [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if the electron count exceeds the `norb` orbitals available in a sector. **Return type** [*Self*](https://docs.python.org/3/library/typing.html#typing.Self) **Protocol Methods** ### \_apply\_unitary\_placed\_ `_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`](#qiskit_fermions.circuit.library.InitializeModes.occupation "qiskit_fermions.circuit.library.InitializeModes.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`](#qiskit_fermions.circuit.library.InitializeModes "qiskit_fermions.circuit.library.InitializeModes") gates. The gate’s local [`occupation`](#qiskit_fermions.circuit.library.InitializeModes.occupation "qiskit_fermions.circuit.library.InitializeModes.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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)) – the state vector to validate. Its length must match the `(norb, nelec)` sector dimension. - **norb** ([*int*](https://docs.python.org/3/library/functions.html#int)) – the number of spatial orbitals of the *global* state vector. - **nelec** ([*int*](https://docs.python.org/3/library/functions.html#int) *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#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*](https://docs.python.org/3/library/functions.html#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*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*int*](https://docs.python.org/3/library/functions.html#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**](https://docs.python.org/3/library/exceptions.html#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*](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray)