symop.devices.models.filters¶

Filtering devices for mode descriptors.

This package provides devices that modify mode descriptors by applying frequency- or polarization-dependent filtering operations.

Filtering devices operate on the semantic layer of the simulation by transforming mode labels and recording physical attenuation parameters. The actual physical channels are applied later by the backend runtime kernels.

Two filtering devices are currently provided:

SpectralFilter: Applies a spectral transfer function to the envelope of every mode on the selected input path. The resulting envelope and transmission efficiency are computed during planning, while the backend kernel realizes the corresponding attenuation channel.
PolarizingFilter: Applies a polarization-selective filtering operation. The planner updates polarization-related mode descriptors and records the corresponding transmissivities for execution by the backend kernel.

Notes

Filtering devices follow the standard device execution pipeline:

Planning stage The device inspects mode descriptors and computes descriptor updates together with device parameters (e.g., transmissivities).
Kernel execution Backend kernels apply the corresponding physical channels to the state representation (e.g., polynomial, Gaussian, or other supported representations).

The devices in this module operate purely at the descriptor level and do not directly manipulate quantum states.

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:

computes the overlap with the transmitted polarization,
converts that overlap into an effective transmissivity,
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, …]

class SpectralFilter(transfer: TransferFunction) → None¶

Bases: DeviceBase

Spectral filter device.

A spectral filter acts on all modes on a selected input path by applying a transfer function to each mode envelope. The updated mode labels are routed to the output path, while the corresponding attenuation strengths are recorded for the backend kernel.

Parameters:: transfer (TransferFunction) – Spectral transfer function applied to each compatible mode envelope.

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, 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 spectral-filter device kind.
Return type:: DeviceKind

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

Plan spectral filtering on all modes of the input path.

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

checks that the mode envelope supports time/frequency access,
applies the transfer function to obtain a filtered envelope,
records the corresponding transmissivity,
emits a label edit redirecting the mode to ports["out"] with the updated envelope.

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.
TypeError – If an affected mode carries an envelope that does not implement TimeFrequencyEnvelope.

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, …]

transfer: TransferFunction¶

Modules

`polarizing_filter`	Polarizing filter device.
`spectral_filter`	Spectral filter device.