symop.devices.models.base

Abstract base class for semantic devices.

Defines the common interface for device objects that participate in the device planning and runtime-application pipeline.

A device declares its kind and port interface, provides a semantic planning step via plan(), and can be applied to a state through a runtime that resolves the appropriate representation-specific kernel.

Classes

DeviceBase()

Abstract base class for semantic devices.
class DeviceBase

Bases: ABC

Abstract base class for semantic devices.

Subclasses define a stable device kind, a declared port interface, and a planning method that converts a device invocation into a semantic DeviceAction.

Notes

Device application is performed via a runtime. If no runtime is provided explicitly, the default runtime is used.

_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(...).

abstract property kind: DeviceKind

Return the device kind identifier.

Returns:

Stable kind identifier for this device.

Return type:

DeviceKind

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

Plan a semantic device action for the given invocation.

Parameters:

  • state (State) – Input state for which the device action is planned.

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

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

  • ctx (ApplyContext | None) – Optional apply context that may be used during planning.

Returns:

Semantic action describing how the device should be applied.

Return type:

DeviceAction

Notes

Subclasses implement this method to translate high-level device invocation into a representation-independent action.

abstract property port_specs: Sequence[PortSpec]

Return the declared port specifications for the device.

Returns:

Ordered collection of port specifications describing the device interface.

Return type:

Sequence[PortSpecProtocol]