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

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

# 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, sample_fn, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor) – Probability distribution before final post-processing.
amplitudes (torch.Tensor) – Raw amplitudes before measurement-specific processing.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sample_fn (Callable[[torch.Tensor, int], torch.Tensor]) – Sampling function.
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

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, sample_fn, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor) – Probability distribution before final post-processing.
amplitudes (torch.Tensor) – Raw amplitudes before measurement-specific processing.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sample_fn (Callable[[torch.Tensor, int], torch.Tensor]) – Sampling function.
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

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, **kwargs)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor) – Probability distribution before final post-processing.
amplitudes (torch.Tensor) – Raw amplitudes before measurement-specific processing.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sample_fn (Callable[[torch.Tensor, int], torch.Tensor]) – Sampling function.
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

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, sample_fn, apply_photon_loss, apply_detectors, grouping=None)

Return the processed result for the selected measurement strategy.

Parameters:

distribution (torch.Tensor) – Probability distribution before final post-processing.
amplitudes (torch.Tensor) – Raw amplitudes before measurement-specific processing.
apply_sampling (bool) – Whether sampling should be applied.
effective_shots (int) – Effective number of shots used for sampling.
sample_fn (Callable[[torch.Tensor, int], torch.Tensor]) – Sampling function.
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

class merlin.measurement.strategies.MeasurementKind(*values)

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)

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.

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: Union[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

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)

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.

Returns:

Probability measurement strategy.

Return type:

MeasurementStrategy

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