symop.devices.runtime¶

Device runtime for applying planned device actions to states.

This module provides the concrete runtime responsible for validating device port assignments, planning device actions, dispatching to the appropriate representation-specific kernel, and applying any resulting label edits to the output state.

It also exposes a lazily initialized default runtime with automatic kernel registration.

Functions

get_default_runtime()

Return the lazily initialized default device runtime.

Classes

DeviceRuntime(device_registry, ...)

Concrete runtime for executing device actions on states.

class DeviceRuntime(device_registry: KernelRegistry, measurement_registry: MeasurementKernelRegistry) → None¶

Bases: object

Concrete runtime for executing device actions on states.

Parameters:

registry – Kernel registry used to resolve representation- and device-specific apply kernels.
device_registry (KernelRegistry)
measurement_registry (MeasurementKernelRegistry)

Notes

The runtime performs four main steps:

validate device ports
construct or reuse an apply context
request a semantic action from the device planner
dispatch to the kernel layer and apply any label edits

static _apply_label_edits(state: State, action: DeviceAction) → State¶

Apply label edits from a device action to a state.

Parameters:

state (State) – State to update.
action (DeviceAction) – Device action carrying label edits.

Returns:

Either the unchanged input state, or an updated state with label edits applied.

Return type:

StateProtocol

Raises:

TypeError – If label edits are present but the state does not implement the required label-editing interface.

Notes

If action.edits is empty, the input state is returned unchanged.

apply(*, device: Device, state: State, ports: Mapping[str, Path], selection: object | None = None, ctx: ApplyContext | None = None, out_kind: Literal['ket', 'density'] | None = None) → State¶

Apply a device to a state through planning and kernel dispatch.

Parameters:

device (Device) – Device to apply.
state (State) – Input quantum state.
ports (Mapping[str, Path]) – Mapping from device port names to path labels.
selection (object | None) – Optional device-specific selection or configuration object forwarded to the planning stage.
ctx (ApplyContext | None) – Optional apply context. If omitted, a fresh SimpleApplyContext is created.
out_kind (Optional[Literal['ket', 'density']]) – Optional requested output state kind.

Returns:

Output state after optional kernel execution and any label edits.

Return type:

StateProtocol

Raises:

KeyError – If the supplied port mapping is invalid.
TypeError – If label edits are requested for a state type that does not support them.

Notes

The device is first asked to produce a semantic action via device.plan(...). That action is then executed by the kernel dispatch layer.

detect(*, device: MeasurementDevice, state: State, ports: Mapping[str, Path], selection: object | None = None, ctx: ApplyContext | None = None) → DetectionResult¶

Evaluate a detection query on the given state.

Parameters:

device (MeasurementDevice)
state (State)
ports (Mapping[str, Path])
selection (object | None)
ctx (ApplyContext | None)

Return type:

DetectionResult

device_registry: KernelRegistry¶

measurement_registry: MeasurementKernelRegistry¶

observe(*, device: MeasurementDevice, state: State, ports: Mapping[str, Path], selection: object | None = None, ctx: ApplyContext | None = None) → ObservationResult¶

Evaluate an obesrvation query on the given state.

Parameters:

device (MeasurementDevice)
state (State)
ports (Mapping[str, Path])
selection (object | None)
ctx (ApplyContext | None)

Return type:

ObservationResult

postselect(*, device: MeasurementDevice, state: State, outcome: MeasurementOutcome, ports: Mapping[str, Path], selection: object | None = None, ctx: ApplyContext | None = None) → PostselectionResult¶

Evaluate a postselection query on the given state.

Parameters:

device (MeasurementDevice)
state (State)
outcome (MeasurementOutcome)
ports (Mapping[str, Path])
selection (object | None)
ctx (ApplyContext | None)

Return type:

PostselectionResult

_register_all_kernels(rt: DeviceRuntime) → None¶

Parameters:: rt (DeviceRuntime) – Runtime whose device and measurement kernel registries will be populated.
Return type:: None

Notes

Registration currently delegates to the polynomial kernel registry.

_validate_ports(*, device: Device | MeasurementDevice, ports: Mapping[str, Path]) → None¶

Validate the provided port mapping against device port specs.

Parameters:

device (Device | MeasurementDevice) – Device whose declared port specifications are used for validation.
ports (Mapping[str, Path]) – Mapping from port name to bound path label.

Return type:

None

Raises:

KeyError – If an unknown port name is supplied or if a required port is missing.

Notes

Validation checks that:

all provided port names are declared by the device
all required device ports are present in ports

get_default_runtime() → DeviceRuntime¶

Return the lazily initialized default device runtime.

Returns:: Shared default runtime instance.
Return type:: DeviceRuntimeProtocol

Notes

The default runtime is created on first access and its kernels are registered exactly once.