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_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.FeatureEncoder(feature_count)

Bases: object

Utility class for encoding classical features into quantum circuit parameters.

This class provides methods to encode normalized classical features into parameters that can be used to configure quantum circuits. Different encoding strategies are supported depending on the circuit type.

encode(X_norm, circuit_type, n_modes, bandwidth_coeffs=None, total_shifters=None)

Encode normalized features into quantum circuit parameters.

Return type:

Tensor

Args:

X_norm: Normalized input features of shape (batch_size, num_features) circuit_type: Type of quantum circuit architecture n_modes: Number of modes in the quantum circuit bandwidth_coeffs: Optional bandwidth tuning coefficients for each feature dimension total_shifters: Optional total number of phase shifters (unused in current implementation)

Returns:

Encoded parameters tensor of shape (batch_size, num_parameters)

Raises:

ValueError: If circuit_type is not supported

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.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.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