symop.devices.models.filters.spectral_filter

Spectral filter device.

This module defines SpectralFilter, a path-based device that updates mode envelopes according to a spectral transfer function and records the corresponding attenuation parameters for backend execution.

The planning stage performs two tasks for every mode on the selected input path:

  1. It applies the transfer function to the mode envelope, producing a new output envelope.

  2. It computes an effective transmissivity \(\eta \in [0, 1]\) for that envelope transformation.

The physical attenuation itself is not applied in the planning stage. Instead, the planner stores per-mode transmissivities in action.params["eta_by_mode"] for the backend kernel and emits label edits that update the output mode descriptors.

Notes

This device requires envelopes that implement the TimeFrequencyEnvelope protocol, because spectral filtering needs frequency-domain access.

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

SpectralFilter(transfer)

Spectral filter device.
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:

  1. checks that the mode envelope supports time/frequency access,

  2. applies the transfer function to obtain a filtered envelope,

  3. records the corresponding transmissivity,

  4. 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