Source code for osprey_connectors.simulation.envelope

"""How far a simulated channel's declared motion can carry its value.

A channel's seed may declare two kinds of motion: ``noise``, a Gaussian draw,
and ``drift``, a slow wander whose ``amplitude`` bounds it (``|wander| <=
amplitude`` by construction). A ``noise`` record states exactly one term:
``{absolute: <sigma>}``, a sigma in the channel's unit, or ``{relative:
<fraction>}``, a sigma as a fraction of the reading. An active scenario may
couple the channel to shared drivers, each adding ``gain * (1 + gain_wander)
* driver`` with ``|driver| <= drive.amplitude``, and may replace its noise.

A served value is therefore the held value plus at most its envelope::

    |drift.amplitude|
      + sum |gain| x (1 + |gain_wander.amplitude|) x |drive.amplitude|
      + _MOTION_SIGMAS x noise sigma
      + tooth depth

where a relative noise sigma is taken at the seed's own ``nominal``, or at
the level a ``topoff`` seed holds, and the tooth depth is how far a
``topoff`` seed's sawtooth carries the reading from that level. A
channel that declares no motion, or that an active scenario stills, has an
envelope of 0.0.

The module imports only the standard library and the standard-library-only
:mod:`~osprey_connectors.simulation.topoff`, so the build, the simulator
view's reader and the texture model share one rule.
"""

from __future__ import annotations

from collections.abc import Iterable, Mapping, Sequence
from typing import Any

from osprey_connectors.simulation import topoff

__all__ = [
    "active_envelopes",
    "declares_motion",
    "motion_envelope",
]

#: Gaussian headroom on a noise sigma: a per-draw miss rate near 1e-9.
_MOTION_SIGMAS = 6.0

_ABSOLUTE = "absolute"
_RELATIVE = "relative"


def _number(value: object) -> float | None:
    """``value`` as a float when it is a real number, else None."""
    if isinstance(value, bool) or not isinstance(value, int | float):
        return None
    return float(value)


def _noise_sigma(noise: Mapping[str, Any] | None, nominal: object = None) -> float:
    """The sigma a noise record draws with, in the channel's unit.

    Args:
        noise: A ``noise`` record, ``{absolute: <sigma>}`` or ``{relative:
            <fraction>}``, or None.
        nominal: The seed's ``nominal``, which a relative term is taken of.

    Returns:
        ``|absolute|``, or ``|relative| x |nominal|``; 0.0 for no record.

    Raises:
        ValueError: The record is relative and ``nominal`` is not a number.
    """
    if not noise:
        return 0.0
    if _ABSOLUTE in noise:
        return abs(float(noise[_ABSOLUTE] or 0.0))
    relative = abs(float(noise.get(_RELATIVE) or 0.0))
    if not relative:
        return 0.0
    base = _number(nominal)
    if base is None:
        raise ValueError(f"a relative noise is taken of a numeric nominal, not {nominal!r}")
    return relative * abs(base)


def _term(noise: Mapping[str, Any] | None) -> float:
    """The noise record's one term, signed as stated; 0.0 for no record."""
    if not noise:
        return 0.0
    return float(noise.get(_ABSOLUTE) or noise.get(_RELATIVE) or 0.0)


[docs] def declares_motion(seed: Mapping[str, Any] | None) -> bool: """Whether a seed states motion: a non-zero noise term, ``drift``, or ``topoff``.""" if not seed: return False return bool( _term(seed.get("noise")) or seed.get("drift") or topoff.topoff_record(seed) is not None )
[docs] def motion_envelope( seed: Mapping[str, Any] | None, *, noise: Mapping[str, Any] | None = None, couplings: Iterable[Mapping[str, Any]] = (), still: bool = False, ) -> float: """The band a channel's motion keeps its value within around the held value. Args: seed: The channel's seed, or None. noise: A scenario's noise record standing in for the seed's, or None for the seed's own. couplings: Resolved couplings, each ``{driver, gain, gain_wander?, drive}`` with ``drive`` the driver's ``{kind, amplitude, period_s}``. still: The active scenarios still the channel. Returns: ``|drift.amplitude| + sum |gain| x (1 + |gain_wander.amplitude|) x |drive.amplitude| + _MOTION_SIGMAS x noise sigma + tooth depth``; 0.0 for an absent seed with no couplings, and for a stilled channel. """ if still: return 0.0 seed = seed or {} drift = seed.get("drift") or {} envelope = abs(float(drift.get("amplitude") or 0.0)) for coupling in couplings: wander = coupling.get("gain_wander") or {} drive = coupling.get("drive") or {} envelope += ( abs(float(coupling.get("gain") or 0.0)) * (1.0 + abs(float(wander.get("amplitude") or 0.0))) * abs(float(drive.get("amplitude") or 0.0)) ) shape = topoff.topoff_record(seed) if shape is not None: envelope += topoff.tooth_depth(shape) held = topoff.held_value(seed) record = noise if noise is not None else seed.get("noise") nominal = held if held is not None else seed.get("nominal") return envelope + _MOTION_SIGMAS * _noise_sigma(record, nominal)
[docs] def active_envelopes( seeds: Mapping[str, Mapping[str, Any]], scenarios: Mapping[str, Mapping[str, Any]], active: Sequence[str], ) -> dict[str, float]: """Every seeded, coupled or noise-replaced channel's envelope under ``active``. The active scenarios' ``noise`` and ``couple`` blocks merge in order, a later scenario's noise record replacing an earlier one's, and each coupling takes its driver's ``drive`` from the merged ``drivers``; a coupling to an undeclared driver adds nothing, as it serves nothing. A reading any active scenario's ``still`` list names has an envelope of 0.0. Args: seeds: Seeds by address. scenarios: Scenario records by name. active: The active scenario names, in order; a name ``scenarios`` lacks adds nothing. Returns: The envelope by address, sorted. """ drivers: dict[str, Mapping[str, Any]] = {} couple: dict[str, list[Mapping[str, Any]]] = {} noise: dict[str, Mapping[str, Any]] = {} still: set[str] = set() for name in active: scenario = scenarios.get(name) or {} still.update(str(address) for address in scenario.get("still") or ()) drivers.update(scenario.get("drivers") or {}) for address, terms in (scenario.get("couple") or {}).items(): couple.setdefault(str(address), []).extend(terms) for address, record in (scenario.get("noise") or {}).items(): noise[str(address)] = record resolved: dict[str, list[Mapping[str, Any]]] = {} for address, terms in couple.items(): for term in terms: drive = drivers.get(str(term["driver"])) if drive is not None: resolved.setdefault(address, []).append({**term, "drive": drive}) addresses = {str(address) for address in seeds} | set(couple) | set(noise) return { address: motion_envelope( seeds.get(address), noise=noise.get(address), couplings=resolved.get(address, ()), still=address in still, ) for address in sorted(addresses) }