merlin.measurement.detectors module

class merlin.measurement.detectors.DetectorTransform(simulation_keys, detectors, *, dtype=None, device=None, partial_measurement=False)

Bases: Module

Linear map applying per-mode detector rules to a Fock probability vector.

Parameters:

  • simulation_keys (Iterable[Sequence[int]] | torch.Tensor) – Raw Fock states produced by the simulator (as tuples or lists of integers).

  • detectors (Sequence[pcvl.Detector | None]) – One detector per optical mode. Each detector must expose a detect method compatible with pcvl.Detector.

  • dtype (torch.dtype | None) – Torch dtype for the transform matrix. Defaults to torch.float32.

  • device (torch.device | str | None) – Device used to stage the transform matrix.

  • partial_measurement (bool) – When True, only the modes whose detector entry is not None are measured.

forward(tensor)

Apply the detector transform.

Parameters:

tensor (torch.Tensor) – Probability distribution in complete mode or amplitudes in partial measurement mode. The last dimension must match the simulator basis.

Returns:

  • Complete mode: real probability tensor expressed in the detector basis.

  • Partial mode: list indexed by remaining photon count. Each entry is a

    dictionary whose keys are full-length mode tuples (unmeasured modes set to None) and whose values are lists of (probability, normalized remaining-mode amplitudes) pairs – one per perfect measurement branch.

Return type:

torch.Tensor | list[dict[tuple[int, …], list[tuple[torch.Tensor, torch.Tensor]]]]

property is_identity: bool

Whether the transform reduces to the identity (ideal PNR detectors).

property output_keys: list[tuple[int, ...]]

Return the classical detection outcome keys.

property output_size: int

Number of classical outcomes produced by the detectors.

Type:

int

property partial_measurement: bool

Return True when the transform runs in partial measurement mode.

remaining_basis(remaining_n=None)

Return the ordered Fock-state basis for the unmeasured modes.

Parameters:

remaining_n (int | None) – Optional photon count used to select a specific block. When omitted, the concatenation of every remaining-mode basis is returned.

Returns:

Photon distributions over the unmeasured modes.

Return type:

list[tuple[int, …]]

row(index, *, dtype=None, device=None)

Return a single detector transform row as a dense tensor.

Parameters:

  • index (int) – Row index in the detector transform.

  • dtype (torch.dtype | None) – Optional target dtype.

  • device (torch.device | str | None) – Optional target device.

Returns:

Dense row of the detector transform.

Return type:

torch.Tensor

merlin.measurement.detectors.resolve_detectors(experiment, n_modes)

Build a per-mode detector list from a Perceval experiment.

Parameters:

  • experiment (pcvl.Experiment) – Perceval experiment carrying detector configuration.

  • n_modes (int) – Number of photonic modes to cover.

Returns:

Normalized detector list (defaulting to ideal PNR where unspecified) and a flag indicating whether the experiment originally defined any detectors.

Return type:

tuple[list[pcvl.Detector], bool]