symop.devices.models.sources.number_state_source

Number-state source device.

This module defines NumberStateSource, a source device that prepares a fixed photon-number state in a designated output mode.

The planning stage constructs the emitted mode label on the selected output path and records the requested excitation count for backend kernels.

Notes

This first implementation models a pure number-state source. It does not sample, mix, or condition on measurement outcomes.

Classes

NumberStateSource(envelope, polarization, n)

Photon number-state source.
class NumberStateSource(envelope: Envelope, polarization: Polarization, n: int) → None

Bases: DeviceBase

Photon number-state source.

This device prepares a pure number state on a single emitted output mode. The mode is defined by an envelope and a polarization label and is placed on the path connected to the "out" port.

Parameters:

  • envelope (Envelope) – Envelope assigned to the emitted output mode.

  • polarization (Polarization) – Polarization assigned to the emitted output mode.

  • n (int) – Number of excitations emitted into the output mode.

Raises:

ValueError – If n < 0.

_abc_impl = <_abc._abc_data object>
envelope: Envelope
property kind: DeviceKind

Return the device kind identifier.

Returns:

The number-state source device kind.

Return type:

DeviceKind

n: int
plan(*, state: State, ports: Mapping[str, Path], selection: object | None = None, ctx: ApplyContext | None = None) → DeviceAction

Plan emission of a fixed number state.

Parameters:

  • state (State) – Input state forwarded by the runtime. It is not used by this source planner.

  • ports (Mapping[str, Path]) – Mapping from device-port names to paths. Must contain "out".

  • selection (object | None) – Optional selection object forwarded by the runtime. It is stored unchanged in the returned action.

  • ctx (ApplyContext | None) – Optional apply context forwarded by the runtime. It is not used by this source planner.

Returns:

Planned action containing emitted source modes and excitation counts for backend kernels.

The returned action stores:

  • params["source_modes"]: tuple containing the emitted mode

  • params["excitations_by_mode"]: mapping from emitted mode signature to photon number

Return type:

DeviceAction

Notes

This planner creates the emitted mode directly on the output path. No label edits are required, because the source introduces a fresh mode rather than relabeling an existing one.

polarization: Polarization
property port_specs: tuple[PortSpec, ...]

Return the port specification of the device.

Returns:

Single output port named "out".

Return type:

tuple[PortSpec, …]