Measurement Strategy Guide

The type of output from a QuantumLayer depends on the measurement strategy. The quantum-to-classical conversion relies on two orthogonal concepts:

MeasurementStrategy selects how results are extracted from the quantum simulation or hardware backend.
LexGrouping and ModGrouping provide optional post-processing of outputs (see Grouping Guide).

PROBABILITIES

Produces the probability of observing each Fock state. In the case of strong simulation (as detailed in the SLOS: Strong Linear Optical Simulator documentation), the SLOS algorithm returns complex amplitudes, which are internally converted into probabilities using the standard quantum operation: \(a \rightarrow |a|^2\).

The output vector contains real numbers and has a size of combination(m + n - 1, n) in the Fock space (many photons can arrive at the same mode), combination(m, n) in the unbunched space, and \(2^{(m/2)}\) in the dual rail computation space where n is the number of photons and m the number of modes. See Computation Spaces for more details on computation spaces.

builder = CircuitBuilder(n_modes=5)
# Add whatever to your builder

quantum_layer = QuantumLayer(.
    input_size=4,
    builder=builder,
    n_photons=2,
    measurement_strategy=MeasurementStrategy.PROBABILITIES,  # Optional because this is its default value
)

Characteristics:

Output shape matches the number of Fock states generated by the experiment.
Values are real, non-negative, and sum to one.
Ideal to exploit nearly all the quantum layer expressivity.

Extensions:

Add torch.nn.Linear or any classical layer after the quantum layer to map the probabilities to logits/regression targets.
Combine with LexGrouping or ModGrouping when you need fewer output features and don’t want to increase the number of parameters.

MODE_EXPECTATIONS

The output vector is real and has a size equal to the number of modes. Each element represents the expected number of photons in the corresponding mode. In the unbunched computation space, the vector instead provides the probability of detecting at least one photon in each respective mode.

builder = CircuitBuilder(n_modes=5)
# Add whatever to your builder

quantum_layer = QuantumLayer(.
    input_size=4,
    builder=builder,
    n_photons=2,
    measurement_strategy=MeasurementStrategy.MODE_EXPECTATIONS,
)

Use MODE_EXPECTATIONS if you only need an m-sized vector that summarizes the quantum layer output by providing expectations values.

Key properties:

ComputationSpace.FOCK returns the expected photon count per mode.
ComputationSpace.UNBUNCHED reports occupancy probabilities per mode.
Output size always equals the number of modes.

AMPLITUDES

Returns the complex amplitudes directly. The output size is the same as with MeasurementStrategy.PROBABILITIES, which is dependent on the computation space. This strategy is only meaningful in simulation, because amplitudes cannot be measured or obtained on hardware. Indeed, returning amplitudes is physically non-realizable and should mainly be used for connecting two quantum layers (e.g. when the second one uses amplitude encoding) or for analytical purposes when studying quantum systems.

builder = CircuitBuilder(n_modes=5)
# Add whatever to your builder

quantum_layer = QuantumLayer(.
    input_size=4,
    builder=builder,
    n_photons=2,
    measurement_strategy=MeasurementStrategy.AMPLITUDES,
)

Use this strategy for debugging, algorithmic research, or when a classical routine manipulates complex amplitudes directly. The output is a complex tensor normalised to unit norm.

Note

Adding photon loss or detectors corresponds to performing a measurement of the quantum state, which collapses it and is therefore incompatible with amplitude retrieval. Thus, this measurement strategy requires that no noise model or detectors are defined.

Photon Loss-aware & Detector-aware execution

When a perceval.Experiment is provided, the QuantumLayer derives a photon loss transform and a detector transform that remaps raw Fock-state probabilities to the classical outcomes defined by the experiment. The photon loss mapping is applied first. Then, the detector mapping is applied. Lastly, the measurement strategy converts the distribution into classical features. As a consequence:

MeasurementStrategy.PROBABILITIES and MeasurementStrategy.MODE_EXPECTATIONS transparently work with any noise model and detector setup.
MeasurementStrategy.AMPLITUDES requires direct access to the complex amplitudes and therefore cannot be used when a noise model or custom detectors are defined (the layer will raise a RuntimeError).

Migrating from OutputMappingStrategy (legacy)

Earlier releases exposed QuantumLayer through OutputMappingStrategy. Newc code should rely on MeasurementStrategy instead. The mapping is:

OutputMappingStrategy.NONE → MeasurementStrategy.PROBABILITIES
OutputMappingStrategy.LINEAR → MeasurementStrategy.PROBABILITIES followed by a torch.nn.Linear layer
OutputMappingStrategy.LEXGROUPING or GROUPING → MeasurementStrategy.PROBABILITIES + LexGrouping
OutputMappingStrategy.MODGROUPING → MeasurementStrategy.PROBABILITIES + ModGrouping

Selection Cheat Sheet

Scenario	Recommended Pipeline	Notes
Classification / Regression	`PROBABILITIES` + classical linear-probing head	Obtain logits or arbitrary ranges with `nn.Linear` or deeper networks.
Structured probability outputs	`PROBABILITIES` + `LexGrouping` / `ModGrouping`	Preserves probability mass while reducing dimensionality.
Hardware-friendly analytics	`MODE_EXPECTATIONS` (`no_bunching` to taste)	Outputs one feature per mode, easy to interpret.
Algorithm debugging	`AMPLITUDES`	Complex amplitudes, simulation only.

Next steps

Experiment with the different measurement strategies.
Explore the two external grouping methods LexGrouping and ModGrouping.
Take a look at the Angle Encoding and Amplitude Encoding documentation to learn about data encoding using MerLin.