Source code for osprey_connectors.simulation.channel_faults
"""The faults of a simulated channel itself, applied by the composite's channel layer.
A scenario's ``channel_faults`` maps an address to one word of
:data:`CHANNEL_FAULTS`. A fault acts on the channel whether a physics model
wires it or the texture holds it, while its scenario is active:
* ``stuck`` faults a setpoint. A write is accepted and held, and forwarded to
nothing; the setpoint reads the value last written, its start value before
any write. Its readback shows the machine where it was: a wired readback
the model's reading, a texture readback its held value, with no echo.
* ``frozen`` faults a reading (a readback or a ``none`` channel). It reads
the value it served when the fault became active, with no motion and no
model update.
* ``disconnected`` faults any channel. A float reading reads not-a-number, a
reading of any other type the value it served when the fault became
active, and the reading reports the ``udf`` condition. A disconnected
setpoint holds its writes as ``stuck`` does and reads its demand; its
readback is the disconnected reading. A setpoint with no readback of its
own reads its demand and reports the condition itself.
No fault withholds a reply: a read always answers.
The module imports only the standard library, so the build's validator and
the composite share one table.
"""
from __future__ import annotations
import math
from collections.abc import Callable, Mapping
from dataclasses import dataclass
from types import MappingProxyType
from osprey_connectors.simulation.view import READBACK, SETPOINT
__all__ = [
"CHANNEL_FAULTS",
"STUCK",
"ChannelFault",
]
#: Holds a setpoint's writes.
STUCK = "stuck"
#: Holds a reading at the value it served when the fault became active.
_FROZEN = "frozen"
#: Reads not-a-number, or the activation value, with the ``udf`` condition.
_DISCONNECTED = "disconnected"
_NONE = "none"
_FLOAT = "float"
_UNDEFINED = "udf"
def _snapshot(value_type: str, snapshot: object) -> object:
del value_type
return snapshot
def _not_a_number(value_type: str, snapshot: object) -> object:
return math.nan if value_type == _FLOAT else snapshot
[docs]
@dataclass(frozen=True)
class ChannelFault:
"""One channel fault's semantics.
Attributes:
roles: The facility channel roles the fault may name.
write: Whether a write to a faulted setpoint is held and forwarded to
nothing.
read: What a faulted reading answers, given its ``value_type`` and the
value it served when the fault became active; ``None`` when the
fault changes no reading.
severity: The condition a faulted reading reports, or ``None``.
"""
roles: frozenset[str]
write: bool
read: Callable[[str, object], object] | None
severity: str | None
#: Every channel fault, by its word.
CHANNEL_FAULTS: Mapping[str, ChannelFault] = MappingProxyType(
{
STUCK: ChannelFault(roles=frozenset({SETPOINT}), write=True, read=None, severity=None),
_FROZEN: ChannelFault(
roles=frozenset({READBACK, _NONE}), write=False, read=_snapshot, severity=None
),
_DISCONNECTED: ChannelFault(
roles=frozenset({SETPOINT, READBACK, _NONE}),
write=True,
read=_not_a_number,
severity=_UNDEFINED,
),
}
)