symop.devices.registry

Kernel registry implementation.

This module provides the concrete implementation of the device kernel registry used by the device runtime. The registry maps semantic device operations to representation-specific kernel functions.

Kernels are resolved using the following key:

(device_kind, rep, in_kind, out_kind)

This allows a single semantic device to support multiple state representations and state kinds. For example, the same device may operate on both polynomial and Gaussian states, or transform a ket state into a density state.

Classes

KernelRegistry(_table, ~typing.Literal[, ], ...)

Concrete registry for representation-specific device kernels.

MeasurementKernelRegistry(_table, str, ...)

Concrete registry for representation-specific measurement kernels.
class KernelRegistry(_table: dict[tuple[~symop.devices.types.device_kind.DeviceKind, ~typing.Literal['poly', 'gaussian'], ~typing.Literal['ket', 'density'], ~typing.Literal['ket', 'density']], ~symop.devices.protocols.kernel.KernelFn] = <factory>) → None

Bases: KernelRegistry

Concrete registry for representation-specific device kernels.

The registry stores kernel functions that implement device actions for a specific combination of:

  • device kind

  • state representation

  • input state kind

  • output state kind

Notes

A single semantic device may have multiple kernels registered for different representations or state transformations. For example:

  • Polynomial ket → polynomial ket

  • Polynomial ket → polynomial density

  • Gaussian ket → Gaussian ket

The registry ensures that a unique kernel exists for each (device_kind, rep, in_kind, out_kind) combination.

Parameters:

_table (dict[tuple[DeviceKind, Literal['poly', 'gaussian'], ~typing.Literal['ket', 'density'], ~typing.Literal['ket', 'density']], ~symop.devices.protocols.kernel.KernelFn])

_table

Internal lookup table mapping kernel keys to kernel functions.

Type:

dict[KernelKey, KernelFn]

_abc_impl = <_abc._abc_data object>
_is_protocol = False
_table: dict[tuple[DeviceKind, Literal['poly', 'gaussian'], Literal['ket', 'density'], Literal['ket', 'density']], KernelFn]
register(*, device_kind: DeviceKind, rep: Literal['poly', 'gaussian'], in_kind: Literal['ket', 'density'], out_kind: Literal['ket', 'density'], fn: KernelFn) → None

Register a kernel function.

Parameters:

  • device_kind (DeviceKind) – Semantic device identifier.

  • rep (Literal['poly', 'gaussian']) – State representation (e.g., polynomial, Gaussian).

  • in_kind (Literal['ket', 'density']) – Kind of the input state.

  • out_kind (Literal['ket', 'density']) – Kind of the output state.

  • fn (KernelFn) – Kernel function implementing the device action.

Raises:

KeyError – If a kernel is already registered for the given key.

Return type:

None

Notes

Each (device_kind, rep, in_kind, out_kind) combination may only have one registered kernel.

resolve(*, device_kind: DeviceKind, rep: Literal['poly', 'gaussian'], in_kind: Literal['ket', 'density'], out_kind: Literal['ket', 'density']) → KernelFn

Resolve a kernel function.

Parameters:

  • device_kind (DeviceKind) – Semantic device identifier.

  • rep (Literal['poly', 'gaussian']) – State representation of the input state.

  • in_kind (Literal['ket', 'density']) – Kind of the input state.

  • out_kind (Literal['ket', 'density']) – Desired kind of the output state.

Returns:

The registered kernel function implementing the requested device action.

Return type:

KernelFn

Raises:

KeyError – If no kernel is registered for the requested signature.

Notes

The error message includes a list of available kernel keys for the requested device kind to aid debugging.

class MeasurementKernelRegistry(_table: dict[tuple[~symop.devices.types.device_kind.DeviceKind, str, ~typing.Literal['poly', 'gaussian'], ~typing.Literal['ket', 'density']], ~symop.devices.protocols.kernel.MeasurementKernelFn] = <factory>) → None

Bases: MeasurementKernelRegistry

Concrete registry for representation-specific measurement kernels.

The registry stores kernel functions that implement measurement actions for a specific combination of: - device kind - measurement intent - state representation - input state kind

Notes

A single semantic measurement device may have multiple kernels registered for different intents or representations. For example:

  • number detector / observe / polynomial / ket

  • number detector / observe / polynomial / density

  • number detector / postselect / polynomial / density

The registry ensures that a unique kernel exists for each (device_kind, intent, rep, in_kind) combination.

Parameters:

_table (dict[tuple[DeviceKind, str, Literal['poly', 'gaussian'], ~typing.Literal['ket', 'density']], ~symop.devices.protocols.kernel.MeasurementKernelFn])

_abc_impl = <_abc._abc_data object>
_is_protocol = False
_table: dict[tuple[DeviceKind, str, Literal['poly', 'gaussian'], Literal['ket', 'density']], MeasurementKernelFn]
register(*, device_kind: DeviceKind, intent: Literal['observe', 'detect', 'postselect'], rep: Literal['poly', 'gaussian'], in_kind: Literal['ket', 'density'], fn: MeasurementKernelFn) → None

Register a measurement kernel function.

Parameters:

  • device_kind (DeviceKind)

  • intent (Literal['observe', 'detect', 'postselect'])

  • rep (Literal['poly', 'gaussian'])

  • in_kind (Literal['ket', 'density'])

  • fn (MeasurementKernelFn)

Return type:

None

resolve(*, device_kind: DeviceKind, intent: Literal['observe', 'detect', 'postselect'], rep: Literal['poly', 'gaussian'], in_kind: Literal['ket', 'density']) → MeasurementKernelFn

Resolve a measurement kernel function.

Parameters:
Return type:

MeasurementKernelFn