Bosonic modes, sectors, and basis states#

BosonModes#

class edinpy.boson.BosonModes(*dofs)[source]#

Ordered bosonic modes generated by discrete degrees of freedom.

Parameters:: *dofs (DoF) – Degrees of freedom whose Cartesian product labels the bosonic 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 bosonic 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.boson.NParticleSector(modes, N)[source]#

Fixed-particle-number sector of bosonic Fock space.

Parameters:

modes (BosonModes) – Bosonic modes defining the occupation-number representation.
N (int) – Number of bosons 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. The constrained basis is generated directly rather than by filtering the complete fixed-N sector.

property is_built#

Whether the many-body basis has been generated.

Type:: bool

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

Fix particle numbers for values of one degree of freedom.

Parameters:

dof_name (str) – Name of the degree of freedom to constrain.
particle_numbers (mapping, optional) – Mapping from DoF value indices or string labels to particle numbers. Integer keys work even when the DoF has no descriptive labels.
**named_particle_numbers (int) – Convenience form for string-labeled DoFs. For example, project_particles("species", up=2, down=2) is equivalent to project_particles("species", {"up": 2, "down": 2}).

Returns:

This sector, so constraints can be chained before build().

Return type:

NParticleSector

Examples

Default integer DoF values can be constrained without inventing labels:

site = DoF(2, name="site")
modes = BosonModes(site)
sector = (
    NParticleSector(modes, N=2)
    .project_particles("site", {0: 1, 1: 1})
    .build()
)

Descriptive labels retain the keyword shorthand:

species = DoF(2, name="species", labels=("a", "b"))
modes = BosonModes(species)
sector = (
    NParticleSector(modes, N=3)
    .project_particles("species", a=2, b=1)
    .build()
)

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 retains the existing basis. When particle-number constraints are present, the constrained basis is generated directly.

property basis#

Ordered basis of the built sector.

Type:: FockBasis

property dimension#

Hilbert-space dimension of the built sector.

Type:: int

from_vector(coefficients)[source]#

Construct a basis-backed bosonic ket from coefficient coordinates.

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

FockBasis#

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

Occupation-number basis for a fixed number of bosons.

Parameters:

n_modes (int) – Number of bosonic modes.
N (int) – Total number of indistinguishable bosons in every basis state.

Notes

Complete fixed-particle-number bases are represented implicitly using the weak-composition structure of bosonic occupations. Decoded occupation tuples are created only when states is requested. Bases with additional particle-number constraints retain only the allowed occupation configurations. Packed integer keys provide an exact compact encoding for indexing and storage.

property is_complete#

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

Type:: bool

property is_materialized#

Whether explicit packed-state storage has been allocated.

Type:: bool

property estimated_execution_storage_bytes#

Persistent compact storage expected by matrix-free execution.

Bosonic matrix-free kernels cache a little-endian multiword uint64 state view. Projected ranked execution may additionally cache one int64 complete-basis rank per retained state. The estimate is computed without materializing either array.

Type:: int

property storage_bytes#

Bytes used by cached explicit basis-state storage.

Type:: int

property dimension#

Number of basis states.

Type:: int

property bits_per_mode#

Number of bits allocated to each occupation field.

Type:: int

property packed_width#

Total number of logical bits in each packed key.

Type:: int

packed_at(index)[source]#

Return the packed occupation key at one basis index.

Parameters:: index (int) – Zero-based basis index. Negative indices follow Python indexing.
Returns:: Exact packed representation of the bosonic occupation vector.
Return type:: int

property packed_states#

Exact packed occupation keys in basis order.

This compatibility tuple is created lazily. Matrix-free execution uses the compact multiword view directly and does not require it.

Type:: tuple[int, …]

property states#

Decoded occupation vectors.

Type:: tuple[tuple[int, …], …]

pack(occupations)[source]#

Encode a bosonic occupation vector as an exact integer key.

Parameters:: occupations (iterable of int) – Non-negative occupation of each mode. The occupations must sum to this basis’s particle number N.
Returns:: Packed occupation key.
Return type:: int

unpack(packed_state)[source]#

Decode an exact packed state key.

Parameters:: packed_state (int) – Packed bosonic occupation key.
Returns:: Occupation number of every mode.
Return type:: tuple[int, …]

occupation(packed_state, mode)[source]#

Return one mode occupation from a packed state key.

Parameters:

packed_state (int) – Packed bosonic occupation key.
mode (int) – Zero-based bosonic mode index.

Returns:

Occupation number of mode.

Return type:

int

index(state)[source]#

Return the basis index of a bosonic occupation state.

Parameters:: state (FockState, int, or iterable of int) – Basis ket, packed state key, or occupation-number vector.
Returns:: Zero-based position in this basis.
Return type:: int
Raises:: ValueError – If the state does not belong to the basis.

state(index)[source]#

Return one unit-amplitude bosonic 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

state_at(index)[source]#

Return one basis ket at index without materializing states.

Parameters:: index (int)
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 bosonic modes.
N (int) – Number of bosons.

Returns:

Exact binomial coefficient binomial(N + n_modes - 1, N).

Return type:

int

FockState#

class edinpy.boson.FockState(occupations, amp=1, index=None)[source]#

Bosonic occupation-number basis ket.

Parameters:

occupations (iterable of int) – Non-negative occupation number for each bosonic mode.
amp (numbers.Number, optional) – State amplitude. The default is one.
index (int, optional) – Basis index associated with the state.

property state#

Occupation-number tuple.

Type:: tuple[int, …]

property N#

Total particle number in the state.

Type:: int

property n_modes#

Number of bosonic modes represented by the state.

Type:: int

occupation(mode)[source]#

Return the occupation number of one bosonic mode.

Parameters:: mode (int) – Zero-based bosonic mode index.
Returns:: Occupation number of mode.
Return type:: int

is_occupied(mode)[source]#

Return whether one bosonic mode has nonzero occupation.

Parameters:: mode (int) – Zero-based bosonic mode index.
Returns:: True when the occupation of mode is nonzero.
Return type:: bool

property dag#

Hermitian adjoint of the ket.

Type:: FockBra

inner(other)[source]#

Return the Hilbert-space inner product with another bosonic 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.