Source code for osprey_connectors.simulation.view

"""The simulator view a build writes, and the one reader of it.

``osprey build`` writes each render's simulator view into
``<render>/data/simulator/``; this module names its files and their schemas
and opens it. Every reader of a view opens it through :class:`SimulatorView`,
which refuses a file whose ``schema`` is not the one this OSPREY reads, so a
render from an older OSPREY is rebuilt rather than misread.

A wiring record of a physics model carries what its engine's ``describe()``
stated at build time: its ``engine_role`` (one of :data:`ENGINE_ROLES`), the transverse
``plane`` it steers or reads (``x``, ``y`` or ``None``), its ``refresh``
(one of :data:`REFRESH`) and, when it carries any, its ``marks`` (of
:data:`MARKS`). The words are the facility schema's. A ``readback`` is any read of an element's setting, paired
with a setpoint or not; a reader wanting the readback of a setpoint reads that
setpoint channel's ``pair``.

The module imports only the standard library and ``osprey_connectors``, so a
reader that must not load a model can open a view.
"""

from __future__ import annotations

import copy
import json
from collections.abc import Iterator, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
from types import MappingProxyType
from typing import TYPE_CHECKING, Any, overload

if TYPE_CHECKING:  # pragma: no cover - typing only
    from osprey_connectors.simulation._records import (
        ChannelRecord,
        ModelEntry,
        ScenarioRecord,
        SeedRecord,
    )

__all__ = [
    "ADDRESSES_FILE",
    "ADDRESSES_SCHEMA",
    "COMMAND_MARK",
    "DECKS_DIR",
    "ENGINEER",
    "ENGINE_ROLES",
    "HEARTBEAT",
    "IOC_HEALTH_SIGNALS",
    "MARKS",
    "MONITOR",
    "OUTPUT",
    "PERIODIC",
    "PERIODIC_IOC_HEALTH",
    "PLANES",
    "READBACK",
    "REFRESH",
    "SCENARIOS_DIR",
    "SCENARIOS_FILE",
    "SCENARIOS_SCHEMA",
    "SERVED_SIGNAL_PROPERTY",
    "SCHEMAS",
    "SEEDS_FILE",
    "SEEDS_SCHEMA",
    "SERVED_MODELS_FILE",
    "SERVED_MODELS_SCHEMA",
    "SETPOINT",
    "STATUS_SIGNAL",
    "UPTIME",
    "VARIABLES_FILE",
    "VARIABLES_SCHEMA",
    "VIEW_RELPATH",
    "Binding",
    "Channel",
    "Model",
    "NoSimulatorView",
    "SimulatorView",
    "ViewSchemaError",
]

#: The view's directory under a render.
VIEW_RELPATH = PurePosixPath("data/simulator")

SERVED_MODELS_FILE = "served_models.json"
SERVED_MODELS_SCHEMA = "osprey.facility.served_models/1"
ADDRESSES_FILE = "addresses.json"
ADDRESSES_SCHEMA = "osprey.facility.addresses/1"
VARIABLES_FILE = "variables.json"
VARIABLES_SCHEMA = "osprey.facility.simulator/4"
SEEDS_FILE = "seeds.json"
SEEDS_SCHEMA = "osprey.facility.seeds/2"
SCENARIOS_FILE = "scenarios.json"
SCENARIOS_SCHEMA = "osprey.facility.scenarios/3"
#: The directory holding a byte copy of each deck-bearing model's deck.
DECKS_DIR = "decks"
#: The directory holding each scenario's attached files, ``scenarios/<name>/``,
#: under the facility tree and under the view alike.
SCENARIOS_DIR = "scenarios"

#: Each view file and the schema it carries.
SCHEMAS: Mapping[str, str] = MappingProxyType(
    {
        SERVED_MODELS_FILE: SERVED_MODELS_SCHEMA,
        ADDRESSES_FILE: ADDRESSES_SCHEMA,
        VARIABLES_FILE: VARIABLES_SCHEMA,
        SEEDS_FILE: SEEDS_SCHEMA,
        SCENARIOS_FILE: SCENARIOS_SCHEMA,
    }
)

#: The schemas this OSPREY reads besides the one it writes, per file: a released
#: ``/3`` facility file reads as one whose models declare no inputs.
_ALSO_READ: Mapping[str, frozenset[str]] = MappingProxyType(
    {VARIABLES_FILE: frozenset({"osprey.facility.simulator/3"})}
)

#: The engine of the model that serves every channel no physics model wires.
_TEXTURE = "texture"

SETPOINT = "setpoint"
READBACK = "readback"
MONITOR = "monitor"
OUTPUT = "output"
#: The engine roles a wiring record's description names. A channel's facility role
#: is ``setpoint`` or ``readback``.
ENGINE_ROLES = (SETPOINT, READBACK, MONITOR, OUTPUT)
#: The planes a wiring record's description names; ``None`` is no plane.
PLANES = ("x", "y")
PERIODIC = "periodic"
#: The refresh a wiring record's description names: ``pass`` with each
#: write's solve, ``periodic`` with the periodic solve alone, ``fast`` at the
#: fast period, ``event`` with each event the engine raises.
REFRESH = ("pass", PERIODIC, "fast", "event")
#: The mark of a record whose write is a command; only a ``write`` record
#: carries it.
COMMAND_MARK = "command"
#: The marks a wiring record's description may set.
MARKS = (COMMAND_MARK,)

#: The signal of a physics model's status address, ``<code>:SIM:<model>:STATUS``.
STATUS_SIGNAL = "STATUS"
HEARTBEAT = "HEARTBEAT"
UPTIME = "UPTIME"
ENGINEER = "ENGINEER"
#: The signals of a model's IOC health addresses, ``<code>:SIM:<model>:<signal>``,
#: in the order a view lists them.
IOC_HEALTH_SIGNALS = (HEARTBEAT, UPTIME, ENGINEER)
#: The IOC health signals each periodic pass publishes.
PERIODIC_IOC_HEALTH = (HEARTBEAT, UPTIME)
#: The directory property the simulator sets on each status and IOC health row,
#: valued with that row's signal; channel rows carry none.
SERVED_SIGNAL_PROPERTY = "signal"

#: The text a missing view reports.
_NO_VIEW_MESSAGE = "no simulator view at {path}: run osprey build"

#: The keys a wiring record's description adds.
_DESCRIPTION_KEYS = ("engine_role", "plane", "refresh")
#: The key listing the marks a wiring record carries; absent when it carries none.
_MARKS_KEY = "marks"


[docs] class NoSimulatorView(LookupError): """The place holds no simulator view: it has no ``addresses.json``."""
[docs] class ViewSchemaError(ValueError): """A view file's ``schema`` is not the one this OSPREY reads, or its shape breaks that schema."""
@overload def _freeze(value: Mapping[str, object]) -> Mapping[str, object]: ... @overload def _freeze(value: object) -> object: ... def _freeze(value: object) -> object: """A read-only copy of a JSON value: mappings as proxies, lists as tuples.""" if isinstance(value, Mapping): return MappingProxyType({key: _freeze(item) for key, item in value.items()}) if isinstance(value, list | tuple): return tuple(_freeze(item) for item in value) return value def _schema_error(path: Path, found: object, expected: str) -> ViewSchemaError: return ViewSchemaError( f"{path} is schema {found!r}; this OSPREY reads {expected!r}: rebuild with osprey build" )
[docs] @dataclass(frozen=True) class Channel: """One channel of the view, as ``variables.json`` states it. Attributes: address: The channel's address. role: The facility file's role, ``readback`` when it states none. pair: A setpoint's readback, itself when it names none; ``None`` on any other role. value_type: The channel's value type. unit: The channel's unit, or ``None``. description: The channel's description, or ``None``. writable: Whether a write to the channel is allowed. value_range: ``(min, max)`` from the channel's limits record, or ``None``. owner: The model wiring the address, else ``texture``. on: The node the channel is on, ``{device: id}`` or ``{place: id}``, or ``None``. options: An enum channel's options, or ``None``. shape: A waveform channel's shape, or ``None``. precision: A float channel's display precision, or ``None``. """ address: str role: str pair: str | None value_type: str unit: str | None description: str | None writable: bool value_range: tuple[float, float] | None owner: str on: Mapping[str, str] | None options: tuple[str, ...] | None shape: tuple[int, ...] | None precision: int | None
[docs] @classmethod def from_entry(cls, entry: Mapping[str, Any]) -> Channel: """Read one channel entry of ``variables.json``. Raises: ViewSchemaError: the entry lacks a key every channel carries. """ try: return cls( address=str(entry["address"]), role=entry["role"], pair=entry["pair"], value_type=entry["value_type"], unit=entry["unit"], description=entry["description"], writable=bool(entry["writable"]), value_range=_freeze(entry["value_range"]), owner=entry["owner"], on=_freeze(entry["on"]), options=_freeze(entry["options"]) if "options" in entry else None, shape=_freeze(entry["shape"]) if "shape" in entry else None, precision=entry.get("precision"), ) except KeyError as missing: raise ViewSchemaError( f"channel {entry.get('address')!r} lacks {missing}: rebuild with osprey build" ) from None
[docs] @dataclass(frozen=True) class Binding: """One wiring record of a physics model: the address it serves and what it is. Attributes: id: The wiring record's id. model: The model the record belongs to. address: The channel address the record serves. direction: ``write`` or ``read``. engine_role: One of :data:`ENGINE_ROLES`. A ``readback`` reads an element's setting, paired with a setpoint or not; the setpoint channel's ``pair`` names its readback. plane: ``x`` or ``y`` for a record steering or reading one transverse plane, else ``None``. refresh: One of :data:`REFRESH`. element: The element the record names, or ``None`` (a record naming slices, or none). record: The wiring record as the view states it, read-only; the engine's ``build`` takes it verbatim. marks: The :data:`MARKS` the record carries; empty when it carries none. """ id: str model: str address: str direction: str engine_role: str plane: str | None refresh: str element: str | None record: Mapping[str, Any] marks: frozenset[str] = frozenset()
[docs] @classmethod def from_record(cls, model: str, record: Mapping[str, Any]) -> Binding: """Read one wiring record of ``variables.json``. Raises: ViewSchemaError: the record lacks ``engine_role``, ``plane`` or ``refresh``. """ missing = [key for key in _DESCRIPTION_KEYS if key not in record] if missing: raise ViewSchemaError( f"wiring record {record.get('address')!r} of model {model!r} lacks " f"{', '.join(missing)}: rebuild with osprey build" ) return cls( id=str(record.get("id")), model=model, address=str(record["address"]), direction=str(record.get("direction")), engine_role=record["engine_role"], plane=record["plane"], refresh=record["refresh"], element=record.get("element"), record=MappingProxyType(copy.deepcopy(dict(record))), marks=frozenset(str(mark) for mark in record.get(_MARKS_KEY) or ()), )
[docs] @dataclass(frozen=True) class Model: """One model of the view. Attributes: name: The model's name. engine: The engine the model names. served: Whether the render serves the model. settings: The model's settings, read-only. deck: The path of the view's copy of the model's deck, or ``None``. bindings: The model's wiring records, in wiring order; empty for a ``texture`` model or one without wiring. inputs: The model's inputs, in declared order, each a read-only ``{address, engine}`` record: the producer channel's address and the engine block the consuming engine reads; empty when the model declares none. """ name: str engine: str | None served: bool settings: Mapping[str, object] deck: Path | None bindings: tuple[Binding, ...] inputs: tuple[Mapping[str, object], ...] = ()
[docs] class SimulatorView: """A render's simulator view, opened from its directory. ``addresses.json`` is read when the view opens; every other file is read once, on first use, and each is refused when its ``schema`` is not the one this OSPREY reads. Attributes: path: The view's directory. render_root: The render the view sits in, when the view is at ``<render>/data/simulator``; else ``None``. """
[docs] def __init__(self, path: Path) -> None: self.path = Path(path) parts = PurePosixPath(*self.path.parts[-len(VIEW_RELPATH.parts) :]) self.render_root = self.path.parents[1] if parts == VIEW_RELPATH else None self._raw: dict[str, dict[str, Any]] = {} self._documents: dict[str, Mapping[str, Any]] = {} self._models: tuple[Model, ...] | None = None self._channel_records: Mapping[str, Channel] | None = None self._envelopes: dict[tuple[str, ...], dict[str, float]] = {} if not (self.path / ADDRESSES_FILE).is_file(): raise NoSimulatorView(_NO_VIEW_MESSAGE.format(path=self.path)) self.document(ADDRESSES_FILE)
[docs] @classmethod def open(cls, view_dir: Path | str) -> SimulatorView: """Open the view in ``view_dir``. Raises: NoSimulatorView: ``view_dir`` has no ``addresses.json``. ViewSchemaError: its ``addresses.json`` is not schema :data:`ADDRESSES_SCHEMA`. """ return cls(Path(view_dir))
[docs] @classmethod def of_render(cls, render_root: Path | str) -> SimulatorView: """Open the view of the render rooted at ``render_root``.""" return cls.open(Path(render_root) / VIEW_RELPATH)
[docs] @classmethod def path_for_project(cls, project_dir: Path | str) -> Path: """Where the view of ``project_dir``'s render is, read or not. A deployment repo keeps its render under ``build/``, beside the rendered ``config.yml``; a container's project directory is the render itself. """ from osprey_connectors.workspace import rendered_config_path project = Path(project_dir) rendered = rendered_config_path(project) render = rendered.parent if rendered.is_file() else project return render / VIEW_RELPATH
[docs] @classmethod def of_project(cls, project_dir: Path | str) -> SimulatorView: """Open the view of ``project_dir``'s render (:meth:`path_for_project`).""" return cls.open(cls.path_for_project(project_dir))
[docs] @classmethod def find(cls, project_dir: Path | str) -> SimulatorView | None: """Open the view of ``project_dir``'s render, or ``None`` when it has none. Raises: ViewSchemaError: the view is there but from another schema. """ try: return cls.of_project(project_dir) except NoSimulatorView: return None
[docs] def document(self, name: str) -> Mapping[str, Any]: """One view file, parsed once and read-only. Args: name: The file's name, one of :data:`SCHEMAS`. Raises: ViewSchemaError: the file's ``schema`` is absent or neither ``SCHEMAS[name]`` nor an older one this OSPREY still reads. """ if name not in self._documents: self._documents[name] = _freeze(self._parsed(name)) return self._documents[name]
def _parsed(self, name: str) -> dict[str, Any]: if name not in self._raw: path = self.path / name parsed = json.loads(path.read_text(encoding="utf-8")) expected = SCHEMAS[name] found = parsed.get("schema") if isinstance(parsed, dict) else None if found != expected and found not in _ALSO_READ.get(name, ()): raise _schema_error(path, found, expected) self._raw[name] = parsed return self._raw[name] @property def code(self) -> str: """The facility's identity code.""" return str(self.document(VARIABLES_FILE)["code"])
[docs] def models(self) -> tuple[Model, ...]: """Every model of the facility file, sorted by name.""" if self._models is None: entries: Sequence[ModelEntry] = self._parsed(VARIABLES_FILE)["models"] self._models = tuple(self._model(entry) for entry in entries) return self._models
def _model(self, entry: ModelEntry) -> Model: name = str(entry["name"]) engine = entry.get("engine") deck = entry.get("deck") wiring = entry.get("wiring") or () return Model( name=name, engine=engine, served=bool(entry.get("served")), settings=MappingProxyType(copy.deepcopy(entry.get("settings") or {})), deck=self.path / deck if deck else None, bindings=() if engine == _TEXTURE else tuple(Binding.from_record(name, record) for record in wiring), inputs=tuple(_freeze(copy.deepcopy(record)) for record in entry.get("inputs") or ()), )
[docs] def model(self, name: str) -> Model: """The model named ``name``. Raises: KeyError: the view has no such model. """ for model in self.models(): if model.name == name: return model raise KeyError(f"the simulator view has no model {name!r}")
[docs] def served(self) -> tuple[str, ...]: """The names of the models the render serves, in ``served_models.json`` order.""" names: Sequence[str] = self.document(SERVED_MODELS_FILE)["models"] return tuple(str(name) for name in names)
[docs] def physics_models(self) -> tuple[Model, ...]: """The served models whose engine is not ``texture``, sorted by name.""" return tuple(model for model in self.models() if model.served and model.engine != _TEXTURE)
[docs] def channels(self) -> tuple[str, ...]: """Every channel address of the facility file, sorted.""" addresses: Sequence[str] = self.document(ADDRESSES_FILE)["channels"] return tuple(str(address) for address in addresses)
[docs] def status_addresses(self) -> Mapping[str, str]: """Each served physics model's status address, ``<code>:SIM:<model>:STATUS``.""" status: Sequence[str] = self.document(ADDRESSES_FILE)["status"] listed = set(status) return MappingProxyType( { model.name: address for model in self.physics_models() if (address := f"{self.code}:SIM:{model.name}:{STATUS_SIGNAL}") in listed } )
[docs] def ioc_health_by_model(self) -> Mapping[str, Mapping[str, str]]: """Each listed model's IOC health addresses by signal, ``{model: {signal: address}}``. An address is ``<code>:SIM:<model>:<signal>`` with ``<signal>`` one of :data:`IOC_HEALTH_SIGNALS`; each model's signals keep the list's order. ``ioc_health`` is optional under :data:`ADDRESSES_SCHEMA`: a view from a build without it yields an empty mapping. Unlike the status addresses, it lists the ``texture`` model too. Raises: ViewSchemaError: a listed entry is not such an address. """ listed: Sequence[str] = self.document(ADDRESSES_FILE).get("ioc_health", ()) if not listed: return MappingProxyType({}) prefix = f"{self.code}:SIM:" by_model: dict[str, dict[str, str]] = {} for address in listed: model, _, signal = str(address).removeprefix(prefix).rpartition(":") if not model or not str(address).startswith(prefix) or signal not in IOC_HEALTH_SIGNALS: raise ViewSchemaError( f"{self.path / ADDRESSES_FILE} lists {address!r} under ioc_health, " f"which is not {prefix}<model>:<signal> with <signal> one of " f"{', '.join(IOC_HEALTH_SIGNALS)}: rebuild with osprey build" ) by_model.setdefault(model, {})[signal] = str(address) return MappingProxyType( {model: MappingProxyType(signals) for model, signals in by_model.items()} )
def _channels(self) -> Mapping[str, Channel]: if self._channel_records is None: entries: Sequence[ChannelRecord] = self._parsed(VARIABLES_FILE)["channels"] self._channel_records = MappingProxyType( { channel.address: channel for channel in (Channel.from_entry(entry) for entry in entries) } ) return self._channel_records def _channel_entries(self) -> Sequence[ChannelRecord]: """Every channel entry of ``variables.json``, read-only, in file order.""" entries: Sequence[ChannelRecord] = self.document(VARIABLES_FILE)["channels"] return entries def _seeds(self) -> Mapping[str, SeedRecord]: """Every seed record of ``seeds.json``, read-only, by address.""" seeds: Mapping[str, SeedRecord] = self.document(SEEDS_FILE)["seeds"] return seeds
[docs] def channel(self, address: str) -> Channel: """The channel at ``address``. Raises: KeyError: the view has no channel at ``address``. """ return self._channels()[address]
[docs] def bindings( self, *, model: str | None = None, engine_role: str | None = None, plane: str | None = None, node: str | None = None, served_only: bool = True, ) -> tuple[Binding, ...]: """The physics models' wiring records, model by name, then in wiring order. Args: model: Only this model's records. engine_role: Only records of this engine role. plane: Only records of this plane. node: Only records whose channel is on this node (a value of the channel's ``on``). served_only: Only the served models' records. """ channels = self._channels() return tuple( binding for binding in self._all_bindings(served_only) if (model is None or binding.model == model) and (engine_role is None or binding.engine_role == engine_role) and (plane is None or binding.plane == plane) and (node is None or node in _on_nodes(channels.get(binding.address))) )
def _all_bindings(self, served_only: bool) -> Iterator[Binding]: for model in self.models(): if model.engine == _TEXTURE or (served_only and not model.served): continue yield from model.bindings
[docs] def binding(self, address: str) -> Binding | None: """The served physics model's wiring record of ``address``, or ``None``.""" for binding in self._all_bindings(served_only=True): if binding.address == address: return binding return None
[docs] def seed(self, address: str) -> Mapping[str, Any] | None: """The seed record of the channel at ``address``, or ``None``.""" return self._seeds().get(address)
[docs] def scenarios(self) -> tuple[Mapping[str, Any], ...]: """Every scenario of ``scenarios.json``, sorted by name. Raises: ViewSchemaError: A scenario's ``still`` is not a list of addresses. """ return self._scenarios()
def _scenarios(self) -> tuple[ScenarioRecord, ...]: """:meth:`scenarios`, each record typed as the schema states it.""" scenarios: tuple[ScenarioRecord, ...] = self.document(SCENARIOS_FILE)["scenarios"] for scenario in scenarios: still = scenario.get("still") if still is not None and not ( isinstance(still, tuple) and all(isinstance(address, str) for address in still) ): raise ViewSchemaError( f"{self.path / SCENARIOS_FILE}: scenario {scenario.get('name')!r} states " f"`still` as {still!r}, not a list of addresses: run osprey build" ) return scenarios
[docs] def motion_envelope(self, address: str, active: Sequence[str] = ()) -> float: """The band ``address``'s served motion keeps it within around its held value. Args: address: A channel address. active: The active scenario names, in order; ``nominal`` always counts, as the composite counts it. Returns: The channel's envelope under ``active`` (:func:`osprey_connectors.simulation.envelope.active_envelopes`); 0.0 for a channel that declares no motion. """ from osprey_connectors.simulation.envelope import active_envelopes from osprey_connectors.simulation.state import resolve_active_scenarios key = tuple(resolve_active_scenarios(active)) if key not in self._envelopes: self._envelopes[key] = active_envelopes( self._seeds(), {str(scenario["name"]): scenario for scenario in self._scenarios()}, key, ) return self._envelopes[key].get(address, 0.0)
[docs] def scenario_dir(self, name: str) -> Path: """The view's copy of a scenario's attached files, ``scenarios/<name>/``.""" return self.path / SCENARIOS_DIR / name
def _on_nodes(channel: Channel | None) -> tuple[str, ...]: if channel is None or channel.on is None: return () return tuple(str(node) for node in channel.on.values())