merlin.sampling.mappers module

Output mapping implementations for quantum-to-classical conversion.

class merlin.sampling.mappers.LexGroupingMapper(input_size, output_size)

Bases: Module

Maps probability distributions using lexicographical grouping.

This mapper groups consecutive elements of the probability distribution 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(probability_distribution)

Group probability distribution into equal-sized buckets.

Return type:

Tensor

Args:

probability_distribution: Input probability tensor of shape (batch_size, input_size) or (input_size,)

Returns:

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

class merlin.sampling.mappers.ModGroupingMapper(input_size, output_size)

Bases: Module

Maps probability distributions using modulo-based grouping.

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

forward(probability_distribution)

Group probability distribution based on indices modulo output_size.

Return type:

Tensor

Args:

probability_distribution: Input probability tensor of shape (batch_size, input_size) or (input_size,)

Returns:

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

class merlin.sampling.mappers.OutputMapper

Bases: object

Handles mapping quantum probability distributions to classical outputs.

This class provides factory methods for creating different types of output mappers that convert quantum probability distributions to classical neural network outputs.

static create_mapping(strategy, input_size, output_size)

Create an output mapping based on the specified strategy.

Args:

strategy: The output mapping strategy to use input_size: Size of the input probability distribution output_size: Desired size of the output tensor

Returns:

A PyTorch module that maps input_size to output_size

Raises:

ValueError: If strategy is unknown or sizes are incompatible for ‘none’ strategy

enum merlin.sampling.mappers.OutputMappingStrategy(value)

Bases: Enum

Strategy for mapping quantum probability distributions to classical outputs.

Valid values are as follows:

LINEAR = <OutputMappingStrategy.LINEAR: 'linear'>

GROUPING = <OutputMappingStrategy.GROUPING: 'grouping'>

LEXGROUPING = <OutputMappingStrategy.LEXGROUPING: 'lexgrouping'>

MODGROUPING = <OutputMappingStrategy.MODGROUPING: 'modgrouping'>

NONE = <OutputMappingStrategy.NONE: 'none'>