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

Parameters:

None –

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

Create an output mapping for the requested measurement strategy.

Parameters:

  • strategy (MeasurementStrategyLike) – Measurement mapping strategy to use.

  • computation_space (ComputationSpace) – Computation space for the measurement.

  • keys (list[tuple[int, ...]] | None) – List of Fock states. Required for mode-expectation mappings. For example, keys = [(0,1,0,2), (1,0,1,0), …]

  • dtype (torch.dtype | None) – Target dtype for internal tensors.

Returns:

PyTorch module mapping amplitudes or probabilities to the desired output representation.

Return type:

torch.nn.Module

Raises:

ValueError – If strategy is unknown or required keys are missing.

class merlin.measurement.mappers.Probabilities

Bases: Module

Map amplitudes or probabilities to a full Fock-state distribution.

Parameters:

None –

forward(x)

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

Parameters:

x (torch.Tensor) – Input amplitudes or probabilities with shape (num_states,) or (batch_size, num_states).

Returns:

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

Return type:

torch.Tensor

class merlin.measurement.mappers.ModeExpectations(computation_space, keys, *, dtype=None)

Bases: Module

Map amplitudes or probabilities to per-mode expected photon counts.

Parameters:

  • computation_space (ComputationSpace) – Computation space used to interpret the keys.

  • keys (list[tuple[int, ...]]) – List of tuples describing the possible Fock states output from the circuit preceding the output mapping. e.g., [(0,1,0,2), (1,0,1,0), …]

  • dtype (torch.dtype | None) – Target dtype for internal tensors.

forward(x)

Compute per-mode expectations from amplitudes or probabilities.

Parameters:

x (torch.Tensor) – Input amplitudes or probabilities with shape (num_states,) or (batch_size, num_states).

Returns:

Expected photon counts per mode.

Return type:

torch.Tensor

marginalize_per_mode(probability_distribution)

Marginalize Fock-state probabilities into per-mode expectations.

Parameters:

probability_distribution (torch.Tensor) – Tensor of probabilities for each Fock state.

Returns:

Per-mode expected photon counts.

Return type:

torch.Tensor

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