"""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())