symop.devices.models.filters.polarizing_filter

Polarizing filter device.

This module defines PolarizingFilter, a path-based device that projects mode polarizations onto a selected transmitted polarization and records the corresponding attenuation parameters for backend execution.

For each mode on the selected input path, the planning stage computes an effective transmissivity from the overlap between the input polarization label and the configured transmitted polarization. The physical attenuation is not applied during planning. Instead, the planner stores per-mode transmissivities in action.params["eta_by_mode"] for the backend kernel and emits label edits that update output mode descriptors.

Notes

For an ideal polarizing filter with transmitted polarization \(|\psi\rangle\) and input polarization \(|\phi\rangle\), the effective transmissivity is

\[\eta = |\langle \psi \mid \phi \rangle|^2.\]

The backend kernel is expected to realize the attenuation channel, for example through a pure-loss dilation followed by tracing out the environment mode.

Classes

PolarizingFilter(passed_polarization)

Ideal polarizing filter device.
class PolarizingFilter(passed_polarization: Polarization) → None

Bases: DeviceBase

Ideal polarizing filter device.

A polarizing filter acts on all modes on a selected input path by projecting their polarization content onto a configured transmitted polarization. The updated mode labels are routed to the output path, while the corresponding attenuation strengths are recorded for the backend kernel.

Parameters:

passed_polarization (Polarization) – Polarization transmitted by the filter.

Notes

Planning performs descriptor updates only. The actual physical attenuation is delegated to the runtime kernel through action.params["eta_by_mode"].

_abc_impl = <_abc._abc_data object>
apply(state: State, *, ports: Mapping[str, Path], selection: object | None = None, runtime: DeviceRuntime | None = None, ctx: ApplyContext | None = None, out_kind: Literal['ket', 'density'] | None = None) → State

Apply the device to a state through a runtime.

Parameters:

  • state (State) – Input state to which the device is applied.

  • ports (Mapping[str, Path]) – Mapping from logical port names to path labels.

  • selection (object | None) – Optional device-specific selection or configuration object.

  • runtime (DeviceRuntime | None) – Runtime used to execute the device application. If None, the default runtime is used.

  • ctx (ApplyContext | None) – Optional apply context shared across planning and execution.

  • out_kind (Optional[Literal['ket', 'density']]) – Optional requested output state kind.

Returns:

Output state returned by the runtime.

Return type:

StateProtocol

Notes

This method first selects a runtime and then delegates execution to runtime.apply(...).

property kind: DeviceKind

Return the device kind identifier.

Returns:

The polarizing-filter device kind.

Return type:

DeviceKind

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

Plan ideal polarization filtering on all modes of the input path.

For every mode on ports["in"], this method:

  1. computes the overlap with the transmitted polarization,

  2. converts that overlap into an effective transmissivity,

  3. emits a label edit redirecting the mode to ports["out"] with the transmitted polarization label.

Parameters:

  • state (State) – Input state whose mode labels are inspected.

  • ports (Mapping[str, Path]) – Mapping from device-port names to physical or logical paths. Must contain the keys "in" and "out".

  • selection (object | None) – Optional selection object forwarded by the runtime. It is not used by this device.

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

Returns:

Planned action containing:

  • params["eta_by_mode"]: transmissivity per affected mode

  • edits: label updates for all transformed modes

Return type:

DeviceAction

Raises:

TypeError – If the state does not support label editing and path-based mode lookup.

Notes

The attenuation channel itself is not applied here. This method only prepares the semantic and kernel parameters required for execution.

property port_specs: tuple[PortSpec, ...]

Return the port specification of the device.

Returns:

Two-port specification consisting of one input port named "in" and one output port named "out".

Return type:

tuple[PortSpec, …]