merlin.measurement.strategies module

Measurement strategy definitions for quantum-to-classical conversion.

Overview

The measurement API is now centered on MeasurementStrategy, an immutable object that fully describes how quantum outputs are converted into classical outputs. The new API uses explicit factory methods instead of enum-style access.

New API (recommended)

Factory methods (preferred):

from merlin.core.computation_space import ComputationSpace
from merlin.measurement.strategies import MeasurementStrategy
from merlin.utils.grouping import LexGrouping

# Full measurement probabilities
strategy = MeasurementStrategy.probs(ComputationSpace.FOCK)

# Collapse count-resolved Fock outputs to occupied/unoccupied readout bins
strategy = MeasurementStrategy.probs(
    ComputationSpace.FOCK,
    occupancy_readout=True,
)

# Grouping can still be applied after the occupancy readout
# input_size must match the occupancy-reduced output width for the layer.
strategy = MeasurementStrategy.probs(
    ComputationSpace.FOCK,
    grouping=LexGrouping(input_size=16, output_size=4),
    occupancy_readout=True,
)

# Per-mode expectations
strategy = MeasurementStrategy.mode_expectations(ComputationSpace.UNBUNCHED)

# Raw amplitudes (no detectors, no sampling)
strategy = MeasurementStrategy.amplitudes(ComputationSpace.UNBUNCHED)

Partial measurement

Partial measurement is explicit and validated. It returns a PartialMeasurement.

from merlin.core.computation_space import ComputationSpace
from merlin.measurement.strategies import MeasurementStrategy

# Measure only modes 0 and 2
strategy = MeasurementStrategy.partial(
    modes=[0, 2],
    computation_space=ComputationSpace.FOCK,
)

Deprecations and Migration Guide

Enum-style access is deprecated and will be removed in v0.4:

MeasurementStrategy.PROBABILITIES
MeasurementStrategy.MODE_EXPECTATIONS
MeasurementStrategy.AMPLITUDES
MeasurementStrategy.NONE (aliases amplitudes)

Passing measurement_strategy as a string is also deprecated (e.g. "PROBABILITIES").

Old to new mappings

Deprecated	Recommended replacement
`MeasurementStrategy.PROBABILITIES`	`MeasurementStrategy.probs(computation_space=...)`
`MeasurementStrategy.MODE_EXPECTATIONS`	`MeasurementStrategy.mode_expectations(computation_space=...)`
`MeasurementStrategy.AMPLITUDES`	`MeasurementStrategy.amplitudes(computation_space=...)`
`MeasurementStrategy.NONE`	`MeasurementStrategy.amplitudes(computation_space=...)`
`"PROBABILITIES"` (string)	`MeasurementStrategy.probs(computation_space=...)`

Computation space now lives inside the strategy. If you already use the new factory methods, do not also pass computation_space separately in constructors such as QuantumLayer.

# Deprecated (legacy enum + separate computation_space)
# QuantumLayer(..., measurement_strategy=MeasurementStrategy.PROBABILITIES,
#             computation_space=ComputationSpace.FOCK)

# Recommended
QuantumLayer(..., measurement_strategy=MeasurementStrategy.probs(ComputationSpace.FOCK))

Reference

class merlin.measurement.strategies.BaseMeasurementStrategy

Bases: object

New API: internal strategy interface for post-processing implementations.

process(*, distribution, amplitudes, apply_sampling, effective_shots, sampler, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor | SectoredDistribution) – Probability distribution before final post-processing, or a sectored distribution in the g2 noise case.
amplitudes (torch.Tensor | SectoredDistribution) – Raw amplitudes before measurement-specific processing, or a sectored distribution in the g2 noise case.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sampler (SamplingProcess) – Sampling process object providing sampling methods.
apply_photon_loss (Callable[[torch.Tensor], torch.Tensor]) – Photon-loss transform.
apply_detectors (Callable[[torch.Tensor], torch.Tensor]) – Detector transform.
grouping (Callable[[torch.Tensor], torch.Tensor] | None) – Optional grouping applied to the resulting probabilities.

Returns:

Processed measurement result.

Return type:

torch.Tensor | PartialMeasurement | SectoredDistribution

supports_sampling()

Return whether the strategy can apply sampling to distributions.

Return type:: bool

class merlin.measurement.strategies.DistributionStrategy

Bases: BaseMeasurementStrategy

New API: shared logic for distribution-based strategies.

process(*, distribution, amplitudes, apply_sampling, effective_shots, sampler, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor | SectoredDistribution) – Probability distribution before final post-processing, or a sectored distribution in the g2 noise case.
amplitudes (torch.Tensor | SectoredDistribution) – Raw amplitudes before measurement-specific processing, or a sectored distribution in the g2 noise case.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sampler (SamplingProcess) – Sampling process object providing sampling methods.
apply_photon_loss (Callable[[torch.Tensor], torch.Tensor]) – Photon-loss transform.
apply_detectors (Callable[[torch.Tensor], torch.Tensor]) – Detector transform.
grouping (Callable[[torch.Tensor], torch.Tensor] | None) – Optional grouping applied to the resulting probabilities.

Returns:

Processed measurement result.

Return type:

torch.Tensor | PartialMeasurement | SectoredDistribution

supports_sampling()

Return whether the strategy can apply sampling to distributions.

Return type:: bool

class merlin.measurement.strategies.ProbabilitiesStrategy

Bases: DistributionStrategy

New API: return output probabilities (optionally sampled).

class merlin.measurement.strategies.ModeExpectationsStrategy

Bases: DistributionStrategy

New API: return per-mode expectations (optionally sampled).

class merlin.measurement.strategies.AmplitudesStrategy

Bases: BaseMeasurementStrategy

New API: return raw amplitudes (sampling is not supported).

process(*, amplitudes, sampler=None, **kwargs)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor | SectoredDistribution) – Probability distribution before final post-processing, or a sectored distribution in the g2 noise case.
amplitudes (torch.Tensor | SectoredDistribution) – Raw amplitudes before measurement-specific processing, or a sectored distribution in the g2 noise case.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sampler (SamplingProcess) – Sampling process object providing sampling methods.
apply_photon_loss (Callable[[torch.Tensor], torch.Tensor]) – Photon-loss transform.
apply_detectors (Callable[[torch.Tensor], torch.Tensor]) – Detector transform.
grouping (Callable[[torch.Tensor], torch.Tensor] | None) – Optional grouping applied to the resulting probabilities.

Returns:

Processed measurement result.

Return type:

torch.Tensor | PartialMeasurement | SectoredDistribution

class merlin.measurement.strategies.PartialMeasurementStrategy(measured_modes)

Bases: BaseMeasurementStrategy

New API: return a PartialMeasurement from detector partial-measurement output.

process(*, distribution, amplitudes, apply_sampling, effective_shots, sampler, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor | SectoredDistribution) – Probability distribution before final post-processing, or a sectored distribution in the g2 noise case.
amplitudes (torch.Tensor | SectoredDistribution) – Raw amplitudes before measurement-specific processing, or a sectored distribution in the g2 noise case.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sampler (SamplingProcess) – Sampling process object providing sampling methods.
apply_photon_loss (Callable[[torch.Tensor], torch.Tensor]) – Photon-loss transform.
apply_detectors (Callable[[torch.Tensor], torch.Tensor]) – Detector transform.
grouping (Callable[[torch.Tensor], torch.Tensor] | None) – Optional grouping applied to the resulting probabilities.

Returns:

Processed measurement result.

Return type:

torch.Tensor | PartialMeasurement | SectoredDistribution

class merlin.measurement.strategies.MeasurementKind(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

New API: internal measurement kinds used by MeasurementStrategy.

AMPLITUDES = 'AMPLITUDES'

MODE_EXPECTATIONS = 'MODE_EXPECTATIONS'

PARTIAL = 'PARTIAL'

PROBABILITIES = 'PROBABILITIES'

class merlin.measurement.strategies.MeasurementStrategy(type, measured_modes=(), computation_space=None, grouping=None, occupancy_readout=False)

Bases: object

New API: immutable definition of a measurement strategy for output post-processing.

Parameters:

type (MeasurementKind) – Measurement strategy kind.
measured_modes (tuple[int, ...]) – Measured modes for partial measurement.
computation_space (ComputationSpace | None) – Computation space used by the strategy.
grouping (LexGrouping | ModGrouping | None) – Optional grouping applied to probability outputs. If occupancy_readout is True, grouping is applied after the occupancy readout.
occupancy_readout (bool) – Whether probability outputs are collapsed to binary occupied/unoccupied output keys. Default value is False.

static amplitudes(computation_space=ComputationSpace.UNBUNCHED)

Create an amplitude-output measurement strategy.

Parameters:: computation_space (ComputationSpace) – Computation space used to enumerate the output basis.
Returns:: Amplitude measurement strategy.
Return type:: MeasurementStrategy

computation_space: Optional[ComputationSpace]

get_unmeasured_modes(n_modes)

Return the complement of the measured modes after validation.

Return type:: tuple[int, ...]

grouping: UnionType[LexGrouping, ModGrouping, None]

measured_modes: tuple[int, ...]

static mode_expectations(computation_space=ComputationSpace.UNBUNCHED)

Create a per-mode expectation measurement strategy.

Parameters:: computation_space (ComputationSpace) – Computation space used to enumerate the output basis.
Returns:: Mode-expectation measurement strategy.
Return type:: MeasurementStrategy

occupancy_readout: bool

static partial(modes, computation_space=ComputationSpace.UNBUNCHED, grouping=None)

Create a partial measurement on the given mode indices. Note that the specified grouping only applies on the resulting probabilities, not on the amplitudes.

Parameters:

modes (list[int]) – Mode indices to measure.
computation_space (ComputationSpace) – Computation space used to enumerate the output basis.
grouping (LexGrouping | ModGrouping | None) – Optional grouping applied to the resulting probabilities only.

Returns:

Partial-measurement strategy.

Return type:

MeasurementStrategy

Raises:

ValueError – If modes is empty, contains duplicates, or contains negative indices.

static probs(computation_space=ComputationSpace.UNBUNCHED, grouping=None, *, occupancy_readout=False)

Create a probability-output measurement strategy.

Parameters:

computation_space (ComputationSpace) – Computation space used to enumerate the output basis.
grouping (LexGrouping | ModGrouping | None) – Optional grouping applied to the resulting probabilities. If occupancy_readout is True, grouping is applied after the occupancy readout.
occupancy_readout (bool) – Whether to collapse count-resolved Fock output keys into binary occupied/unoccupied keys before returning probabilities. Only supported with ComputationSpace.FOCK. Default value is False.

Returns:

Probability measurement strategy.

Return type:

MeasurementStrategy

Raises:

TypeError – If occupancy_readout is not a bool.
ValueError – If occupancy readout is requested outside ComputationSpace.FOCK.

type: MeasurementKind

validate_modes(n_modes)

Validate mode indices and warn when the selection covers all modes.

Return type:: None

merlin.measurement.strategies.MeasurementStrategyLike: TypeAlias = merlin.measurement.strategies.MeasurementStrategy | merlin.measurement.strategies._LegacyMeasurementStrategy

Represent a PEP 604 union type

E.g. for int | str

merlin.measurement.strategies.resolve_measurement_strategy(measurement_strategy)

Return the concrete strategy implementation for the enum value.

Parameters:: measurement_strategy (MeasurementStrategyLike) – Measurement strategy definition or legacy enum alias.
Returns:: Concrete runtime strategy implementation.
Return type:: BaseMeasurementStrategy