merlin.sampling package

Sampling and autodiff utilities.

class merlin.sampling.AutoDiffProcess(sampling_method='multinomial')

Bases: object

Handles automatic differentiation backend and sampling noise integration.

autodiff_backend(needs_gradient, apply_sampling, shots)

Determine sampling configuration based on gradient requirements.

Return type:

tuple[bool, int]

class merlin.sampling.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.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.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.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'>
class merlin.sampling.SamplingProcess(method='multinomial')

Bases: object

Handles quantum measurement sampling with different methods.

This class provides functionality to simulate quantum measurement noise by applying different sampling strategies to probability distributions.

pcvl_sampler(distribution, shots, method=None)

Apply sampling noise to a probability distribution.

Return type:

Tensor

Args:

distribution: Input probability distribution tensor method: Sampling method to use (‘multinomial’, ‘binomial’, or ‘gaussian’), defaults to the initialized method shots: Number of measurement shots to simulate

Returns:

Noisy probability distribution after sampling

Raises:

ValueError: If method is not one of the valid options

Submodules