merlin.utils.combinadics module

Combinatorial ranking and unranking for optical Fock states.

This module implements the Combinadics utility class, providing a unified interface to enumerate photonic occupation patterns under different constraints.

The implementation complexity is bounded O(n*m) for both ranking and unranking, where n is the number of photons and m is the number of modes. Could be optimized further using numba, and caching of binomial coefficients.

class merlin.utils.combinadics.Combinadics(scheme, n, m)

Bases: object

Rank/unrank Fock states in descending lexicographic order.

Parameters:

• scheme (str) – Enumeration strategy. Supported values are "fock", "unbunched", and "dual_rail".

• n (int) – Number of photons. Must be non-negative.

• m (int) – Number of modes. Must be at least one.

Raises:

ValueError – If an unsupported scheme is provided or the parameters violate the constraints of the selected scheme.

compute_space_size()

Return the number of admissible Fock states for this configuration.

Returns:

Cardinality of the state space.

Return type:

int

enumerate_states()

Return all admissible states in descending lexicographic order.

Returns:

State list matching iter_states().

Return type:

list[tuple[int, …]]

fock_to_index(counts)

Map a Fock state to its index under the configured scheme.

Parameters:

counts (Iterable[int]) – Photon counts per mode.

Returns:

Rank of the Fock state in descending lexicographic order.

Return type:

int

Raises:

ValueError – If counts violates the scheme-specific constraints.

index(state)

Return the rank for a given state (tuple.index compatible).

Parameters:

state (Iterable[int]) – Photon counts per mode.

Returns:

Rank of the provided state.

Return type:

int

Raises:

ValueError – If the state violates the configured scheme.

index_to_fock(index)

Map an index to its corresponding Fock state.

Parameters:

index (int) – Rank to decode.

Returns:

Photon counts per mode.

Return type:

tuple[int, …]

Raises:

ValueError – If index is outside the valid range for the configured scheme.

iter_states()

Yield admissible states in descending lexicographic order.

Returns:

Generator over states matching the configured scheme.

Return type:

Iterator[tuple[int, …]]