"""The active scenario set and the composition rule scenarios must obey.
Every reader of the active set — ``sim apply``, the archive, the composite
and the stand-in — resolves it and checks it here, so they cannot
disagree on which scenarios run or on which sets compose; ``sim apply`` writes
it here too, with :func:`write_active_state`.
Scenarios compose only when they write disjoint targets: two scenarios writing
one target would apply in an order-dependent way, so such a set is refused as
an :class:`Overlap` naming the target. A scenario's ``still`` meets only the
motion other scenarios set: it overlaps the ``noise`` or ``couple`` of the
readings it stills, never another target and never another ``still``. An
``archiver`` entry writes no target: events several scenarios script on one
channel compose in set order in the archive, so they never refuse a set. A
process that serves without a scenario because of an overlap logs one
:func:`overlap_record`, and readers print it with :func:`format_overlap_record`.
The module imports neither numpy nor lume.
"""
from __future__ import annotations
from collections.abc import Collection, Mapping, Sequence
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import Any
from osprey_connectors.config import get_facility_timezone
from osprey_connectors.logger import get_logger
from osprey_connectors.safety_file import atomic_replace
__all__ = [
"ACTIVE_SCENARIOS_FILENAME",
"DEFAULT_SCENARIO",
"OVERLAP_EVENT",
"STILL_SCENARIO",
"Overlap",
"composed_set",
"format_overlap_record",
"overlap_record",
"parse_active_state",
"read_active_state",
"resolve_active_scenarios",
"scenario_targets",
"validate_composition",
"write_active_state",
]
#: Name of the plain-text file holding the active scenario set.
ACTIVE_SCENARIOS_FILENAME = "active_scenarios"
#: The baseline scenario, active in every set.
DEFAULT_SCENARIO = "nominal"
#: The scenario every view lists, which stills every reading.
STILL_SCENARIO = "still"
#: The ``event`` an overlap record carries in a simulator log.
OVERLAP_EVENT = "scenario-overlap"
logger = get_logger("simulation_state")
#: Marks a target of the motion namespace, which ``noise``, ``couple`` and
#: ``still`` share; no address holds the character.
_MOTION_MARK = "\x00"
_SETS_MOTION = _MOTION_MARK + "sets:"
_STILLS = _MOTION_MARK + "stills:"
[docs]
def parse_active_state(text: str) -> tuple[list[str], float | None]:
"""The scenario names and the anchor an ``active_scenarios`` file records.
Blank lines and ``#`` comments are skipped. A ``key=value`` line is
metadata, of which only ``anchor=<ISO 8601>`` is read; every other line is
a scenario name, kept in file order. A naive anchor is read in the
facility timezone; a malformed one is logged and ignored.
Args:
text: The file's contents.
Returns:
The names, and the anchor as epoch seconds or ``None`` when the file
records none.
"""
names: list[str] = []
anchor_epoch: float | None = None
for line in text.splitlines():
stripped = line.strip()
if not stripped or stripped.startswith("#"):
continue
if "=" in stripped:
key, _, value = stripped.partition("=")
if key.strip() == "anchor":
try:
parsed = datetime.fromisoformat(value.strip())
if parsed.tzinfo is None:
parsed = parsed.replace(tzinfo=get_facility_timezone())
anchor_epoch = parsed.timestamp()
except ValueError:
logger.warning(f"Ignoring malformed anchor in state file: {stripped!r}")
continue
names.append(stripped)
return names, anchor_epoch
[docs]
def read_active_state(state_dir: Path) -> tuple[list[str], float | None]:
"""The scenario names and the anchor the ``active_scenarios`` file in *state_dir* records.
Args:
state_dir: The directory holding the file.
Returns:
What :func:`parse_active_state` reads from the file, or ``([], None)``
when the file is absent.
"""
path = state_dir / ACTIVE_SCENARIOS_FILENAME
if not path.is_file():
return [], None
return parse_active_state(path.read_text(encoding="utf-8"))
[docs]
def write_active_state(
path: Path,
scenarios_view: Mapping[str, Collection[str]],
names: Sequence[str],
*,
anchor: datetime | None = None,
) -> list[str]:
"""Activate a scenario set by writing the ``active_scenarios`` file.
The file holds an ``anchor=<ISO 8601>`` line when ``anchor`` is given, then
the set's scenarios other than ``nominal``, or ``nominal`` alone. It is
replaced whole through ``safety_file.atomic_replace``, so a reader polling
it never reads a half-written set.
Args:
path: The state file.
scenarios_view: Each scenario's name mapped to the targets it writes.
names: The requested scenario names; ``nominal`` is always active.
anchor: The instant the set is applied at.
Returns:
The resolved set, ``nominal`` first.
Raises:
ValueError: If a name is unknown or the set does not compose; nothing
is written.
"""
resolved = resolve_active_scenarios(names)
try:
overlaps = validate_composition(scenarios_view, resolved)
except ValueError as exc:
raise ValueError(f"Cannot activate scenarios: {exc}") from None
if overlaps:
raise ValueError("Cannot activate scenarios: " + "; ".join(map(str, overlaps)))
body = [] if anchor is None else [f"anchor={anchor.isoformat()}"]
body.extend([name for name in resolved if name != DEFAULT_SCENARIO] or [DEFAULT_SCENARIO])
path.parent.mkdir(parents=True, exist_ok=True)
atomic_replace(path, ("\n".join(body) + "\n").encode("utf-8"), mode=0o644, sync="best_effort")
return resolved
[docs]
def resolve_active_scenarios(names: Sequence[str]) -> list[str]:
"""The active scenario set a request for ``names`` really means.
``nominal`` is the machine's baseline, not a fault: it is always active, so
it is prepended whether or not the caller named it. The rest keep the
caller's order and are deduplicated, because activating a scenario twice
would compose its physics twice.
One function for a rule two callers depend on — activation writes the state
file from it, and physics-fault rendering derives ``VA_*`` variables from
it — so the environment a project is built with and the scenarios its
engine runs cannot describe different machines.
"""
resolved: list[str] = [DEFAULT_SCENARIO]
for name in names:
if name != DEFAULT_SCENARIO and name not in resolved:
resolved.append(name)
return resolved
[docs]
@dataclass(frozen=True)
class Overlap:
"""One target written by two scenarios of one set.
Attributes:
target: The address or variable both scenarios write.
first: The scenario that claimed the target first, in set order.
second: The scenario that writes it again.
motion: True when one scenario stills the reading at ``target`` and
the other sets its motion.
"""
target: str
first: str
second: str
motion: bool = False
def __str__(self) -> str:
if self.motion:
return (
f"Scenarios {self.first!r} and {self.second!r} both set the motion of "
f"{self.target!r}; active scenarios must not"
)
return (
f"Channel {self.target!r} is touched by both {self.first!r} and {self.second!r}; "
f"active scenarios must touch disjoint channel sets"
)
[docs]
def scenario_targets(scenario: Mapping[str, Any]) -> set[str]:
"""The targets a scenario writes: addresses, engine variables and coupled channels.
Args:
scenario: One entry of the simulator view's scenario list.
Returns:
The keys of its ``overrides``, the keys of every fault's ``writes``,
the keys of its ``channel_faults``, and the keys of ``couple`` and
``noise``; a block the scenario does not state contributes nothing.
``archiver`` entries are not targets: the archive merges the events
of every active scenario on a channel in set order.
The ``couple`` and ``noise`` keys and the ``still`` readings are also
targets of the motion namespace, which :func:`validate_composition`
reads apart.
"""
targets: set[str] = set(scenario.get("overrides") or {})
for fault in (scenario.get("faults") or {}).values():
targets.update(fault.get("writes") or {})
targets.update(str(address) for address in scenario.get("channel_faults") or {})
moved = {str(address) for slot in ("couple", "noise") for address in scenario.get(slot) or {}}
targets.update(moved)
targets.update(_SETS_MOTION + address for address in moved)
targets.update(_STILLS + str(address) for address in scenario.get("still") or ())
return targets
[docs]
def validate_composition(
scenarios_view: Mapping[str, Collection[str]], names: Sequence[str]
) -> list[Overlap]:
"""Return the overlaps of a scenario set; an empty list means it composes.
``nominal`` writes nothing, so it is skipped when the view does not list
it.
Args:
scenarios_view: Each scenario's name mapped to the targets it writes.
names: Scenario names to check, in set order.
Returns:
One :class:`Overlap` per target a later scenario writes again, sorted
by target within each scenario, then one per reading and scenario pair
where one scenario stills the reading and the other sets its motion.
Raises:
ValueError: If a name is not in ``scenarios_view``.
"""
unknown = [n for n in names if n not in scenarios_view and n != DEFAULT_SCENARIO]
if unknown:
raise ValueError(f"Unknown scenarios {unknown!r}. Available: {sorted(scenarios_view)}")
overlaps: list[Overlap] = []
owner: dict[str, str] = {}
for name in names:
for target in sorted(scenarios_view.get(name, ())):
if target.startswith(_MOTION_MARK):
continue
if target in owner and owner[target] != name:
overlaps.append(Overlap(target=target, first=owner[target], second=name))
else:
owner[target] = name
return overlaps + _motion_overlaps(scenarios_view, names)
def _motion_overlaps(
scenarios_view: Mapping[str, Collection[str]], names: Sequence[str]
) -> list[Overlap]:
"""One motion :class:`Overlap` per reading one scenario stills and another moves."""
movers: list[tuple[str, set[str]]] = []
stillers: list[tuple[str, set[str]]] = []
for name in names:
targets = scenarios_view.get(name, ())
moved = {t.removeprefix(_SETS_MOTION) for t in targets if t.startswith(_SETS_MOTION)}
if moved:
movers.append((name, moved))
if stilled := {t.removeprefix(_STILLS) for t in targets if t.startswith(_STILLS)}:
stillers.append((name, stilled))
order = {name: index for index, name in enumerate(names)}
found: dict[tuple[str, str, str], Overlap] = {}
for mover, addresses in movers:
for stiller, readings in stillers:
if stiller == mover:
continue
first, second = sorted((mover, stiller), key=order.__getitem__)
for address in sorted(addresses & readings):
found.setdefault(
(first, second, address),
Overlap(target=address, first=first, second=second, motion=True),
)
return sorted(found.values(), key=lambda o: (order[o.second], order[o.first], o.target))
[docs]
def composed_set(
scenarios_view: Mapping[str, Collection[str]], names: Sequence[str]
) -> tuple[list[str], list[Overlap]]:
"""The set a reader serves for ``names``: the set itself, or ``nominal`` alone.
A set whose scenarios write one target twice does not compose, and a
reader serves the machine without its scenarios rather than in an
order-dependent state.
Args:
scenarios_view: Each scenario's name mapped to the targets it writes.
names: The resolved set, ``nominal`` first.
Returns:
The set to serve, and the overlaps that kept its scenarios out.
Raises:
ValueError: If a name is not in ``scenarios_view``.
"""
overlaps = validate_composition(scenarios_view, names)
if overlaps:
return resolve_active_scenarios([]), overlaps
return list(names), []
[docs]
def overlap_record(overlap: Overlap, *, instance: str, pid: int) -> dict[str, str | int]:
"""The log record a process writes when it serves without a scenario.
Args:
overlap: The overlap that kept the scenario out.
instance: The serving instance that logs it.
pid: The process id of that instance.
Returns:
The record, one JSON line in the simulator log.
"""
return {"instance": instance, "pid": pid, "event": OVERLAP_EVENT, "target": overlap.target}