You're reading the documentation of the 0.2. For the latest released version, please have a look at 0.4.

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:

  • 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_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, …]]

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