merlin.utils package

Utility subpackages for Merlin.

This module exposes commonly used utility helpers so they can be imported from merlin.utils.

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

Bases: object

Rank/unrank Fock states in descending lexicographic order.

Parameters

schemestr

Enumeration strategy. Supported values are "fock", "unbunched", and "dual_rail".

nint

Number of photons. Must be non-negative.

mint

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.

Return type:

int

Returns

int

Cardinality of the state space.

enumerate_states()

Return all admissible states in descending lexicographic order.

Return type:

list[tuple[int, ...]]

Returns

list[Tuple[int, …]]

State list matching iter_states().

fock_to_index(counts)

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

Return type:

int

Parameters

countsIterable[int]

Photon counts per mode.

Returns

int

Rank of the Fock state in descending lexicographic order.

Raises

ValueError

If counts violates the scheme-specific constraints.

index(state)

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

Return type:

int

Parameters

stateIterable[int]

Photon counts per mode.

Returns

int

Rank of the provided state.

Raises

ValueError

If the state violates the configured scheme.

index_to_fock(index)

Map an index to its corresponding Fock state.

Return type:

tuple[int, ...]

Parameters

indexint

Rank to decode.

Returns

Tuple[int, …]

Photon counts per mode.

Raises

ValueError

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

iter_states()

Yield admissible states in descending lexicographic order.

Return type:

Iterator[tuple[int, ...]]

Returns

Iterator[Tuple[int, …]]

Generator over states matching the configured scheme.

class merlin.utils.LexGrouping(input_size, output_size)

Bases: Module

Maps tensor to a lexical grouping of its components.

This mapper groups consecutive elements of the input tensor into equal-sized buckets and sums them to produce the output. If the input size is not evenly divisible by the output size, padding is applied.

forward(x)

Map the input tensor to the desired output_size utilizing lexical grouping.

Args:

x: Input tensor of shape (n_batch, input_size) or (input_size,)

Returns:

Grouped tensor of shape (batch_size, output_size) or (output_size,)

class merlin.utils.ModGrouping(input_size, output_size)

Bases: Module

Maps tensor to a modulo grouping of its components.

This mapper groups elements of the input tensor based on their index modulo the output size. Elements with the same modulo value are summed together to produce the output.

forward(x)

Map the input tensor to the desired output_size utilizing modulo grouping.

Args:

x: Input tensor of shape (n_batch, input_size) or (input_size,)

Returns:

Grouped tensor of shape (batch_size, output_size) or (output_size,)

merlin.utils.normalize_probabilities(probabilities, computation_space)

Normalize probabilities for computation spaces that require it.

Return type:

Tensor

merlin.utils.normalize_probabilities_and_amplitudes(amplitudes, computation_space)

Return probabilities and renormalized amplitudes when required.

Return type:

tuple[Tensor, Tensor]

merlin.utils.probabilities_from_amplitudes(amplitudes)

Convert complex amplitudes into probabilities.

Return type:

Tensor

merlin.utils.resolve_float_complex(dtype)

Given a torch dtype representing either the float or complex side, return the matching pair.

Return type:

tuple[dtype, dtype]

Args:

dtype: torch float or complex dtype.

Returns:

Tuple (float_dtype, complex_dtype) ensuring the pair is internally consistent.

Raises:

TypeError: If the dtype is not one of the supported float/complex types.

merlin.utils.sanitize_parameters(*args, **_kw)

Decorator to centralize parameter sanitization for method calls.

Usage: - As a plain decorator: @sanitize_parameters (no parentheses) - As a factory with processors: @sanitize_parameters(proc1, proc2, …)

Behavior: - Emits standardized warnings/errors based on the global deprecation registry. - Applies converter functions registered for present deprecated params. - Applies any additional processors(qual, kwargs) provided, sequentially, each receiving and returning kwargs.

Return type:

Any

merlin.utils.to_torch_dtype(dtype_like, *, default=None)

Convert common dtype representations (strings, numpy dtypes, torch dtypes) into torch dtypes.

Return type:

dtype

Args:

dtype_like: Input representation to convert. default: Fallback dtype if the representation is unknown. Defaults to torch.float32.

Returns:

torch.dtype corresponding to the requested representation.

Raises:

TypeError: If the value cannot be mapped and no default is provided.

Modules