Fermionic modes, sectors, and basis states#

FermionModes#

class edinpy.fermion.FermionModes(*dofs)[source]#

Ordered fermionic modes generated by discrete degrees of freedom.

Parameters:: *dofs (DoF) – Degrees of freedom whose Cartesian product labels the fermionic modes. The first degree of freedom is the fastest-varying index.

Notes

For degrees of freedom with sizes (N0, N1, ...), the tuple (i0, i1, ...) is mapped to a single fermionic mode using shared mixed-radix indexing. No single-particle wavefunctions are constructed or stored.

The shared indexing properties and methods are listed under Degrees of freedom and mode indexing.

NParticleSector#

class edinpy.fermion.NParticleSector(modes, N)[source]#

Fixed-particle-number sector of fermionic Fock space.

Parameters:

modes (FermionModes) – Fermionic modes defining the occupation-number representation.
N (int) – Number of fermions in the sector.

Notes

Construction records the sector specification but does not generate the many-body basis. Additional particle-number constraints associated with named degrees of freedom can be imposed with project_particles() before build() is called.

property is_built#

Whether the many-body basis has been generated.

Type:: bool

project_particles(dof_name, /, **particle_numbers)[source]#

Fix particle numbers for labeled values of a degree of freedom.

Parameters:

dof_name (str) – Name of a degree of freedom in self.modes.
**particle_numbers (int) – Required particle number for each labeled value of the selected degree of freedom. The labels must have been supplied when the DoF was constructed.

Returns:

This unbuilt sector, allowing method chaining before build().

Return type:

NParticleSector

Examples

Particle numbers can be fixed for one degree of freedom:

sector = (
    NParticleSector(modes, N=4)
    .project_particles("spin", up=2, down=2)
    .build()
)

Multiple constraints are solved jointly rather than applied sequentially:

sector = (
    NParticleSector(modes, N=4)
    .project_particles("spin", up=2, down=2)
    .project_particles("layer", top=2, bottom=2)
    .project_particles("orbital", a=2, b=2)
    .build()
)

Notes

The constrained basis is generated directly at build() time. The complete fixed-N basis is not constructed and filtered.

build()[source]#

Generate the many-body basis and return this sector.

Returns:: This sector, with its basis available through basis.
Return type:: NParticleSector

Notes

Calling build() more than once is safe. The existing basis is retained rather than regenerated.

property basis#

Ordered basis of the built sector.

Raises:: RuntimeError – If build() has not been called.
Type:: FockBasis

property dimension#

Hilbert-space dimension of the built sector.

Type:: int

from_vector(coefficients)[source]#

Construct a basis-backed Fock vector from coefficient coordinates.

Parameters:: coefficients (array_like) – One-dimensional coefficient array in self.basis ordering.
Returns:: Ket represented in the fixed-N Fock basis of this sector.
Return type:: FockVector
Raises:: RuntimeError – If build() has not been called.

FockBasis#

class edinpy.fermion.FockBasis(n_modes, N)[source]#

Occupation-number basis for a fixed number of fermions.

Parameters:

n_modes (int) – Number of fermionic modes.
N (int) – Number of fermions. Must satisfy 0 <= N <= n_modes.

Notes

Complete fixed-particle-number bases are represented implicitly. Their dimension and state-index maps follow combinatorial ranking, so the full tuple of occupation bit strings is created only when states is requested. Bases with additional particle-number constraints retain only the allowed occupation states.

Basis states are ordered by ascending occupation bit string, equivalent to combinadic colex order at fixed particle number.

property is_complete#

Whether this is the complete fixed-particle-number basis.

Type:: bool

property is_materialized#

Whether any explicit state storage has been allocated.

Type:: bool

property estimated_execution_storage_bytes#

Persistent compact storage expected by matrix-free execution.

Complete bases up to 64 modes use one uint64 per state. Complete wider bases remain implicit. Projected bases report their existing compact storage. Calling this property never materializes states.

Type:: int

property storage_bytes#

Bytes used by cached explicit basis-state storage.

The value is zero for a freshly constructed implicit complete basis. It excludes the small fixed-size Python FockBasis object itself.

Type:: int

state_at(index)[source]#

Return the integer occupation bit string at one basis index.

Parameters:: index (int) – Zero-based basis index. Negative indices follow Python indexing.
Returns:: Integer whose set bits mark occupied fermionic modes.
Return type:: int

index(state)[source]#

Return the basis index of an occupation-number state.

Parameters:: state (int or FockState) – Fermionic occupation bit string or basis ket.
Returns:: Zero-based position in this basis.
Return type:: int
Raises:: ValueError – If the occupation state does not belong to the basis.

property states#

Integer occupation states in basis order.

For an implicit or compact basis this compatibility tuple is created lazily on first access.

Type:: tuple[int, …]

property dimension#

Number of basis states.

Type:: int

state(index)[source]#

Return one unit-amplitude basis ket.

Parameters:: index (int) – Zero-based basis index. Negative indices follow Python indexing.
Returns:: Basis ket with its index field set to the resolved index.
Return type:: FockState

static expected_dimension(n_modes, N)[source]#

Return the dimension of the complete fixed-particle-number basis.

Parameters:

n_modes (int) – Number of fermionic modes.
N (int) – Number of fermions.

Returns:

Exact binomial coefficient binomial(n_modes, N).

Return type:

int

FockState#

class edinpy.fermion.FockState(state, amp=1, n_modes=None, index=None)[source]#

Fermionic occupation-number basis ket represented by an integer bit string.

Parameters:

state (int) – Non-negative integer whose set bits indicate occupied fermionic modes.
amp (numbers.Number, optional) – State amplitude. The default is one.
n_modes (int, optional) – Number of fermionic modes used for formatting and validation.
index (int, optional) – Basis index associated with the state.

Notes

Bit p records the occupation of fermionic mode p. FockState represents one occupation-number basis ket with an optional amplitude. Basis-backed superpositions such as eigensolver vectors are represented by FockVector.

property dag#

Hermitian adjoint of the ket.

Type:: FockBra

inner(other)[source]#

Return the inner product with another fermionic ket.

Parameters:: other (FockState, StateSum, FockVector, or NullState) – Ket on the right-hand side of the inner product.
Returns:: Inner product <self|other>.
Return type:: numbers.Number

norm()[source]#: Return the Hilbert-space norm of the state.

normalized()[source]#

Return a unit-normalized copy of the state.

Raises:: ValueError – If the state has zero amplitude.

is_occupied(mode)[source]#

Return whether a fermionic mode is occupied.

Parameters:: mode (int) – Zero-based fermionic-mode index.
Returns:: True when the mode is occupied.
Return type:: bool