merlin.measurement.mappers module

Output mapping implementations for quantum-to-classical conversion.

Quantum outputs are expected to be: 1. Per state amplitudes, if the processing was a simulation 2. Per state probabilities, if the processing was on hardware

class merlin.measurement.mappers.Amplitudes

Bases: Module

Output the Fock state vector (also called amplitudes) directly. This can only be done with a simulator because amplitudes cannot be retrieved from the per state probabilities obtained with a QPU.

forward(x)

Return the fock state vector amplitudes.

Return type:

Tensor

enum merlin.measurement.mappers.ComputationSpace(value)

Bases: str, Enum

Enumeration of supported computational subspaces.

Member Type:

str

Valid values are as follows:

FOCK = <ComputationSpace.FOCK: 'fock'>

UNBUNCHED = <ComputationSpace.UNBUNCHED: 'unbunched'>

DUAL_RAIL = <ComputationSpace.DUAL_RAIL: 'dual_rail'>

The Enum and its members also have the following methods:

classmethod default(*, no_bunching)

Derive the default computation space from the legacy no_bunching flag.

Return type:

ComputationSpace

classmethod coerce(value)

Normalize user-provided values (enum instances or case-insensitive strings).

Return type:

ComputationSpace

enum merlin.measurement.mappers.MeasurementStrategy(value)

Bases: Enum

Strategy for measuring quantum states or counts and possibly apply mapping to classical outputs.

Valid values are as follows:

PROBABILITIES = <MeasurementStrategy.PROBABILITIES: 'probabilities'>

MODE_EXPECTATIONS = <MeasurementStrategy.MODE_EXPECTATIONS: 'mode_expectations'>

AMPLITUDES = <MeasurementStrategy.AMPLITUDES: 'amplitudes'>

class merlin.measurement.mappers.ModeExpectations(computation_space, keys)

Bases: Module

Maps quantum state amplitudes or probabilities to the per mode expected number of photons.

forward(x)

Convert the per state amplitudes to per state probabilities if x are amplitudes. Then, marginalize the per state probability distribution into a per mode expected value.

Return type:

Tensor

Args:

x: Input Fock states amplitudes or probabilities of shape (n_batch, num_states) or (num_states,)

Returns:

Expected value tensor of shape (batch_size, num_modes)

marginalize_per_mode(probability_distribution)

Marginalize Fock state probabilities to get per-mode occupation expected values.

Return type:

Tensor

Args:

probability_distribution (torch.Tensor): Tensor of shape (N, num_keys) with probabilities

for each Fock state, with requires_grad=True

Returns:

torch.Tensor: Shape (N, num_modes) with marginal per mode expected number of photons

class merlin.measurement.mappers.OutputMapper

Bases: object

Handles mapping quantum state amplitudes or probabilities to classical outputs.

This class provides factory methods for creating different types of output mappers that convert quantum state amplitudes or probabilities to classical outputs.

static create_mapping(strategy, computation_space=ComputationSpace.FOCK, keys=None)

Create an output mapping based on the specified strategy.

Args:

strategy: The measurement mapping strategy to use no_bunching: (Only used for ModeExpectations measurement strategy) If True (default), the per-mode probability of finding at least one photon is returned.

Otherwise, it is the per-mode expected number of photons that is returned.

keys: (Only used for ModeExpectations measurement strategy) List of tuples that represent the possible quantum Fock states.

For example, keys = [(0,1,0,2), (1,0,1,0), …]

Returns:

A PyTorch module that maps the per state amplitudes or probabilities to the desired format.

Raises:

ValueError: If strategy is unknown

class merlin.measurement.mappers.Probabilities

Bases: Module

Maps quantum state amplitudes or probabilities to the complete Fock state probability distribution.

forward(x)

Compute the probability distribution of possible Fock states from amplitudes or probabilities.

Args:

x: Input Fock states amplitudes or probabilities of shape (n_batch, num_states) or (num_states,)

Returns:

Fock states probability tensor of shape (batch_size, num_states) or (num_states,)