Source code for osprey_connectors.simulation.topoff
"""The top-off sawtooth: a stored current that decays with a lifetime and refills on a period.
A ``topoff`` seed ``{ceiling, lifetime_h, period_s}`` describes a float
channel that starts each period at ``ceiling`` and decays exponentially with
the lifetime ``tau = lifetime_h * 3600`` seconds until the next refill. The
unit shape is a pure function of epoch seconds::
s(t) = exp(-((t mod period_s) / tau))
so every channel with the same seed refills at the same instants, and a live
read and an archived sample at the same instant agree. Its mean over one
period is::
m = (tau / period_s) * (1 - exp(-period_s / tau))
The channel HOLDS the level ``ceiling * m`` -- the value a limits band and
an archive's start state see -- and the sawtooth is MOTION around it: the
tooth ``level * (s(t) / m - 1)``, added on the level it rides, so at the held
level the reading is ``ceiling * s(t)``, and a level moved to zero carries no
tooth at all.
A ``topoff_lifetime`` seed ``{of}`` names a channel whose seed is ``topoff``
and holds that seed's ``lifetime_h`` as a constant: the lifetime readback that
produces the decay.
The module imports only the standard library, so the envelope rule and the
facility build share it with the texture model. :data:`SHAPE_VERSION` is a
digest of the shape constants; the archive seed fingerprint consumes it, so a
change to the shape re-seeds the stored history.
"""
from __future__ import annotations
import hashlib
import math
from collections.abc import Callable, Mapping
from typing import Any
__all__ = [
"SHAPE_VERSION",
"held_value",
"period_mean",
"tau_period",
"tooth_depth",
"topoff_record",
]
#: The seed key of a decaying, refilling channel.
_TOPOFF_KEY = "topoff"
#: The seed key of a channel holding a ``topoff`` seed's lifetime.
_LIFETIME_KEY = "topoff_lifetime"
#: Seconds per lifetime hour.
_SECONDS_PER_HOUR = 3600.0
#: Form of the decay between refills; part of the shape digest.
_DECAY_FORM = "exponential"
#: Where in a period the refill lands; part of the shape digest.
_REFILL_PHASE = "period_start"
#: The constants :data:`SHAPE_VERSION` digests, in a fixed order. Each is
#: digested under its name without the leading underscore, the spelling it had
#: while it was public, so making them private left the digest unchanged.
_SHAPE_CONSTANT_NAMES: tuple[str, ...] = ("_SECONDS_PER_HOUR", "_DECAY_FORM", "_REFILL_PHASE")
def _shape_version() -> str:
"""Digest of the current shape constants (see :data:`_SHAPE_CONSTANT_NAMES`)."""
module = globals()
text = ";".join(f"{name.lstrip('_')}={module[name]!r}" for name in _SHAPE_CONSTANT_NAMES)
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16]
#: Digest of the shape constants; the archive seed fingerprint consumes it.
SHAPE_VERSION = _shape_version()
[docs]
def topoff_record(seed: Mapping[str, Any] | None) -> Mapping[str, Any] | None:
"""The ``topoff`` record of a seed, or None when it has none."""
if not seed:
return None
record = seed.get(_TOPOFF_KEY)
return record if isinstance(record, Mapping) else None
[docs]
def tau_period(record: Mapping[str, Any]) -> tuple[float, float]:
"""``(tau, period_s)`` of a ``topoff`` record, both in seconds."""
return float(record["lifetime_h"]) * _SECONDS_PER_HOUR, float(record["period_s"])
[docs]
def period_mean(record: Mapping[str, Any]) -> float:
"""The mean ``m`` of the unit sawtooth over one period."""
tau, period = tau_period(record)
return (tau / period) * -math.expm1(-period / tau)
[docs]
def tooth_depth(record: Mapping[str, Any]) -> float:
"""How far the sawtooth carries a reading from its held level ``ceiling * m``.
Returns:
``|ceiling| * max(1 - m, m - exp(-period_s / tau))``: the larger of
the overshoot at a refill and the undershoot just before one.
"""
tau, period = tau_period(record)
mean = period_mean(record)
return abs(float(record["ceiling"])) * max(1.0 - mean, mean - math.exp(-period / tau))
[docs]
def held_value(
seed: Mapping[str, Any] | None,
lookup: Callable[[str], Mapping[str, Any] | None] | None = None,
) -> float | None:
"""The value a ``topoff`` or ``topoff_lifetime`` seed holds.
Args:
seed: A channel's seed, or None.
lookup: Returns the seed of an address, or None; resolves the channel
a ``topoff_lifetime`` names. Without one a ``topoff_lifetime``
holds nothing.
Returns:
``ceiling * m`` for a ``topoff`` seed; the referenced seed's
``lifetime_h`` for a ``topoff_lifetime`` seed whose channel carries
``topoff``; None for any other seed.
"""
record = topoff_record(seed)
if record is not None:
return float(record["ceiling"]) * period_mean(record)
lifetime = (seed or {}).get(_LIFETIME_KEY)
if not isinstance(lifetime, Mapping) or lookup is None:
return None
source = topoff_record(lookup(str(lifetime.get("of"))))
if source is None:
return None
return float(source["lifetime_h"])