Source code for osprey_connectors.simulation.series

"""Pure time-series synthesis primitives for the simulated archive and texture.

These functions turn a baseline series plus a scenario's archiver events
(step/ramp/spike/burst/loss, positioned by window fraction, wall-clock offset, or daily
time-of-day) into a concrete value series, and supply the keyed draws and the
band-limited texture the texture engine layers on a served value. They hold no
state: the caller supplies the channel values and events and these functions
do the math (see ``tests/simulation/test_series_primitives.py``).
"""

import hashlib
from collections.abc import Iterable, Mapping, Sequence
from datetime import datetime, timedelta
from datetime import time as dtime
from typing import Any
from zoneinfo import ZoneInfo

import numpy as np

from osprey_connectors.logger import get_logger
from osprey_connectors.relative_time import RelativeTimestamp, resolve_relative_timestamp

__all__ = [
    "anchored_instant",
    "BURST_WINDOW_TAUS",
    "apply_events",
    "loss_refill_bound",
    "channel_key_bytes",
    "clamp",
    "daily_occurrences",
    "driver_key_bytes",
    "epoch_seconds_array",
    "event_positions",
    "keyed_normals",
    "step_end",
    "wander",
]

logger = get_logger("simulation_series")

# splitmix64 mixing constants: an odd increment (the golden-ratio word) and the
# two finalizer multipliers. The finalizer is a bijection on uint64, so distinct
# counters can never collide onto the same word for a given key.
_GAMMA = np.uint64(0x9E3779B97F4A7C15)
_MIX_A = np.uint64(0xBF58476D1CE4E5B9)
_MIX_B = np.uint64(0x94D049BB133111EB)
_SHIFT_30 = np.uint64(30)
_SHIFT_27 = np.uint64(27)
_SHIFT_31 = np.uint64(31)
_SHIFT_11 = np.uint64(11)
_ONE = np.uint64(1)
# 53 significand bits scaled into the unit interval.
_TWO_POW_M53 = 2.0**-53
_TWO_PI = 2.0 * np.pi

# Texture: a stack of sinusoids log-spaced downward from the declared slowest
# period. The per-channel weight jitter is applied in log space and is narrower
# than half the decay step, so the slowest component dominates for every
# channel rather than only on average.
_WANDER_SUBKEY = b":wander"
_WANDER_COMPONENTS = 5
_WANDER_OCTAVE_SPAN = 3.5
_WANDER_DECAY_PER_OCTAVE = 0.5
_WANDER_JITTER_OCTAVES = 0.15

#: How many of a ``burst``'s slowest time constants count as inside its window:
#: ``exp(-10)`` leaves under 0.005% of the burst outside it.
BURST_WINDOW_TAUS = 10.0
#: Injector shots per second while top-off refills a ``loss``.
_REFILL_RATE_HZ = 1.0
#: Charge one refill shot adds, as a fraction of the top-off ``ceiling``
#: (0.75 mA on a 500 mA ring).
_REFILL_SHOT_FRACTION = 0.0015


[docs] def channel_key_bytes(channel: str) -> bytes: """Per-channel key for the counter-based draw primitives. The key is the SHA-256 digest of the UTF-8 channel name. The builtin ``hash()`` is deliberately not used: it is salted per process, so draws keyed on it would differ between runs of the same scenario. Callers derive independent streams for the same channel by appending a subkey (e.g. ``channel_key_bytes(channel) + b":noise_abs"``). Args: channel: Channel name. Returns: A 32-byte digest suitable as the ``channel_key`` argument of :func:`keyed_normals`. """ return hashlib.sha256(channel.encode("utf-8")).digest()
[docs] def driver_key_bytes(driver: str) -> bytes: """Key for a scenario's shared latent driver, addressed by the driver's name. A driver is the common cause behind several channels, so its draws must not depend on which channel asks for them: every channel coupled to the driver evaluates :func:`wander` under this one key and sees the identical value at the same instant. The ``driver:`` namespace keeps a driver that happens to share a channel's name from replaying that channel's own texture stream. Args: driver: Driver name, as declared in a scenario's ``drivers`` block. Returns: A 32-byte digest usable wherever a ``channel_key`` is expected. """ return hashlib.sha256(b"driver:" + driver.encode("utf-8")).digest()
def _key_words(channel_key: bytes) -> tuple[np.uint64, np.uint64]: """Two uint64 lane keys derived from an arbitrary-length key.""" digest = hashlib.sha256(channel_key).digest() return ( np.uint64(int.from_bytes(digest[0:8], "big")), np.uint64(int.from_bytes(digest[8:16], "big")), ) def _mix64(z: "np.ndarray") -> "np.ndarray": """splitmix64 avalanche finalizer over a uint64 array (wrapping arithmetic).""" z = (z ^ (z >> _SHIFT_30)) * _MIX_A z = (z ^ (z >> _SHIFT_27)) * _MIX_B return np.asarray(z ^ (z >> _SHIFT_31)) def _as_counter_array(counters: "np.ndarray") -> "np.ndarray": """Normalize counters to uint64, rounding floats to the nearest integer. Epoch-millisecond counters usually arrive as float64 (``epoch_s * 1000``); signed integers (sample-index fallback, pre-epoch timestamps) wrap into uint64 modularly, which keys deterministically like any other value. """ array = np.asarray(counters) if array.dtype.kind == "f": array = np.rint(array).astype(np.int64) if array.dtype != np.uint64: array = array.astype(np.uint64) return array def _keyed_words(channel_key: bytes, counters_ms: "np.ndarray") -> "tuple[np.ndarray, np.ndarray]": """The two uint64 words each sample consumes, as a pair of arrays. Exactly two words per sample, addressed by that sample's own counter — no stream position is involved, which is what makes the draws pointwise reproducible across differently-shaped windows. """ counters = _as_counter_array(counters_ms) k0, k1 = _key_words(channel_key) base = counters * _GAMMA return _mix64(base ^ k0), _mix64(base ^ k1)
[docs] def keyed_normals(channel_key: bytes, counters_ms: "np.ndarray") -> "np.ndarray": """Standard normal draws addressed by ``(channel key, counter)``. Each sample's draw is a pure function of its own counter, so two windows that share a timestamp get the same value, in any order, in any batch size, from any process. This is the pinned construction for all synthesis noise: 1. a uint64 avalanche mix of the counter against two key-derived lane words (exactly two words per sample, fixed consumption by construction); 2. an **open**-interval mapping of the log argument, ``u1 = ((w >> 11) | 1) * 2**-53``, so ``u1 > 0`` always and ``log(u1)`` can never be ``-inf`` — a frozen calendar timestamp that produced ``-inf`` would fail permanently rather than transiently; 3. the Box-Muller cosine branch. The ziggurat rejection sampler behind numpy's batch normal draws consumes a *variable* number of words per sample, so a batch drawn from a window-start counter does not equal the corresponding per-sample draws — it is forbidden on this path, and ``tests/simulation/test_series_primitives.py`` pins the equivalence against a per-sample reference implementation. Args: channel_key: Channel key, typically :func:`channel_key_bytes` output optionally suffixed with a subkey to get an independent stream. counters_ms: Per-sample counters, conventionally epoch milliseconds. Floats are rounded to the nearest integer; any shape is accepted. Returns: A float64 array of standard normal draws with the shape of ``counters_ms``. """ w0, w1 = _keyed_words(channel_key, counters_ms) u1 = ((w0 >> _SHIFT_11) | _ONE).astype(np.float64) * _TWO_POW_M53 u2 = (w1 >> _SHIFT_11).astype(np.float64) * _TWO_POW_M53 return np.sqrt(-2.0 * np.log(u1)) * np.cos(_TWO_PI * u2)
def _unit_interval(words: "np.ndarray") -> "np.ndarray": """Map uint64 words onto float64 in the half-open interval ``[0, 1)``.""" return np.asarray((words >> _SHIFT_11).astype(np.float64) * _TWO_POW_M53) def _wander_components( channel_key: bytes, period_s: float ) -> "tuple[np.ndarray, np.ndarray, np.ndarray]": """Periods, phases and normalized weights of one channel's texture stack. Periods are log-spaced downward from ``period_s`` (the slowest) across :data:`_WANDER_OCTAVE_SPAN` octaves. Phases and weight jitter come from the channel key, so the declared parameters can stay family-uniform while every channel still gets its own apparent offset and motion. Args: channel_key: Channel key, as for :func:`keyed_normals`. period_s: Slowest period in seconds. Returns: ``(periods, phases, weights)``, each of length :data:`_WANDER_COMPONENTS`, with ``weights`` summing to 1. """ index = np.arange(_WANDER_COMPONENTS, dtype=np.uint64) phase_words, weight_words = _keyed_words(channel_key + _WANDER_SUBKEY, index) octaves = np.arange(_WANDER_COMPONENTS, dtype=np.float64) * ( _WANDER_OCTAVE_SPAN / (_WANDER_COMPONENTS - 1) ) periods = period_s * 2.0**-octaves phases = _unit_interval(phase_words) * _TWO_PI jitter = (2.0 * _unit_interval(weight_words) - 1.0) * _WANDER_JITTER_OCTAVES weights = 2.0 ** (-_WANDER_DECAY_PER_OCTAVE * octaves + jitter) return periods, phases, np.asarray(weights / weights.sum())
[docs] def wander( channel_key: bytes, t_abs_s: "np.ndarray", amplitude: float, period_s: float ) -> "np.ndarray": """Band-limited quasi-random baseline texture, evaluated on absolute time. A seeded sum of :data:`_WANDER_COMPONENTS` sinusoids whose periods are log-spaced downward from ``period_s``. One declaration therefore covers two timescales: with ``period_s`` of many hours the slowest terms read as a distinct quasi-static offset inside any short query window, while the faster octaves supply visible motion — which is what lets a whole channel family share one set of declared parameters and still look individual. The envelope is bounded structurally rather than by clipping: the weights are positive and sum to 1, so ``|wander| <= amplitude`` follows from the triangle inequality and the output stays linear in ``amplitude``. Being a pure function of absolute epoch seconds is what makes overlapping archiver windows agree exactly on their shared timestamps. Args: channel_key: Channel key, as for :func:`keyed_normals`. t_abs_s: Absolute epoch seconds; any shape. amplitude: Envelope bound, in the channel's declared units. period_s: Slowest period in seconds; must be positive. Returns: A float64 array of texture offsets with the shape of ``t_abs_s``. Raises: ValueError: If ``period_s`` is not positive; the guard keeps a caller from turning a division by zero into silent ``NaN`` in the series. """ if period_s <= 0.0: raise ValueError(f"wander period_s must be > 0, got {period_s!r}") times = np.asarray(t_abs_s, dtype=np.float64) periods, phases, weights = _wander_components(channel_key, period_s) total = np.zeros(times.shape, dtype=np.float64) for period, phase, weight in zip(periods, phases, weights, strict=True): total += weight * np.sin(_TWO_PI * times / period + phase) return amplitude * total
[docs] def clamp(value: float, min_value: float | None, max_value: float | None) -> float: """Clamp a scalar into ``[min_value, max_value]`` (either bound optional). The result is a float whichever side is hit, because ``clamp`` applies to float channels only. """ if min_value is not None and value < min_value: return float(min_value) if max_value is not None and value > max_value: return float(max_value) return value
[docs] def epoch_seconds_array(timestamps: "Iterable[object]") -> "np.ndarray | None": """Convert timestamps to epoch seconds, or None when not convertible.""" values: list[float] = [] for ts in timestamps: if hasattr(ts, "timestamp"): values.append(float(ts.timestamp())) elif isinstance(ts, (int, float)) and not isinstance(ts, bool): values.append(float(ts)) else: return None return np.asarray(values, dtype=np.float64)
[docs] def anchored_instant(event: Mapping[str, Any], anchor: float, tz: ZoneInfo | None = None) -> float: """Epoch seconds of an event placed relative to the activation anchor. ``at_offset`` is seconds from the anchor. ``at_when`` is the logbook's own ``{days_ago, time}``: the calendar day ``days_ago`` days before the anchor's date, at ``time``, both read in ``tz`` (UTC when omitted) -- the same rule a scenario's logbook entries resolve by, so an event and the entry narrating it name one instant. Args: event: An event carrying ``at_offset`` or ``at_when``. anchor: The activation anchor T0, in epoch seconds. tz: The facility timezone calendar days are counted in. Returns: The event's instant in epoch seconds. """ if "at_offset" in event: return anchor + float(event["at_offset"]) when = event["at_when"] zone = tz if tz is not None else ZoneInfo("UTC") spec = RelativeTimestamp( days_ago=int(when["days_ago"]), time=dtime.fromisoformat(str(when["time"])) ) return resolve_relative_timestamp(spec, datetime.fromtimestamp(anchor, zone)).timestamp()
[docs] def step_end(event: Mapping[str, Any], anchor: float, tz: ZoneInfo | None = None) -> float | None: """Where a bounded ``step`` ends, on the same axis as its start; ``None`` when unbounded. ``until`` is a window fraction (paired with ``at``), ``until_offset`` is seconds from the anchor (paired with ``at_offset``) and ``until_when`` is a ``{days_ago, time}`` placed exactly as ``at_when`` is (paired with it). Args: event: A ``step`` event. anchor: The activation anchor T0, in epoch seconds. tz: The facility timezone ``until_when`` calendar days are counted in. Returns: The end position, or ``None`` when the step states no end. """ if "until_offset" in event: return anchor + float(event["until_offset"]) if "until_when" in event: return anchored_instant({"at_when": event["until_when"]}, anchor, tz) if "until" in event: return float(event["until"]) return None
[docs] def event_positions( event: Mapping[str, Any], t_frac: "np.ndarray", t_abs: "np.ndarray | None", anchor: float, tz: ZoneInfo | None = None, ) -> "list[tuple[np.ndarray, float]]": """Coordinate axis and event position(s) for one event. Fraction-positioned (``at``) and anchored (``at_offset``, ``at_when``) events yield one position, on the normalized window axis and the epoch-seconds axis respectively. Daily ``at_time`` events yield one epoch-seconds position per calendar date whose time-of-day occurrence falls inside the window, placed in the facility timezone (``tz``). Returns an empty list when an anchored or time-of-day event cannot be placed because the timestamps were not convertible to epoch seconds. """ if "at_offset" in event or "at_when" in event: if t_abs is None: logger.debug("Skipping anchored event: timestamps not convertible to epoch seconds") return [] return [(t_abs, anchored_instant(event, anchor, tz))] if "at_time" in event: if t_abs is None: logger.debug("Skipping time-of-day event: timestamps not convertible to epoch seconds") return [] return [(t_abs, at) for at in daily_occurrences(str(event["at_time"]), t_abs, tz)] return [(t_frac, float(event["at"]))]
[docs] def daily_occurrences(at_time: str, t_abs: "np.ndarray", tz: ZoneInfo | None = None) -> list[float]: """Epoch-second positions of a daily time-of-day within ``[t_abs[0], t_abs[-1]]``. Walks calendar dates from the window start to its end (in timezone ``tz``) and keeps every occurrence of ``at_time`` that falls inside the window. Placing the time-of-day in an explicit zone — rather than the deploy host's local zone — makes the result independent of the box ``$TZ``. ``tz`` defaults to UTC; callers resolve and pass the facility zone, so this module stays free of config. Assumes ascending timestamps (the same contract ``apply_events`` relies on via ``np.searchsorted``). """ zone = tz if tz is not None else ZoneInfo("UTC") tod = dtime.fromisoformat(at_time) start = datetime.fromtimestamp(float(t_abs[0]), zone) end = datetime.fromtimestamp(float(t_abs[-1]), zone) cursor = start.replace(hour=0, minute=0, second=0, microsecond=0) positions: list[float] = [] while cursor <= end: candidate = cursor.replace( hour=tod.hour, minute=tod.minute, second=tod.second, microsecond=tod.microsecond ) if start <= candidate <= end: positions.append(candidate.timestamp()) cursor += timedelta(days=1) return positions
def _burst_profile(event: Mapping[str, Any], dt: "np.ndarray") -> "np.ndarray": """A ``burst``'s excursion at ``dt`` seconds after its instant. Zero before the instant, ``amplitude`` at it, then a fast exponential pump-down with ``decay_s`` plus, when ``tail_share`` and ``tail_decay_s`` are stated, a slower exponential carrying that share of the amplitude:: amplitude * ((1 - share) * exp(-dt / decay_s) + share * exp(-dt / tail_decay_s)) Args: event: A ``burst`` event. dt: Seconds since the event instant; negative is before it. Returns: The excursion, same shape as ``dt``. """ amplitude = float(event["amplitude"]) share = float(event.get("tail_share", 0.0)) tail = float(event.get("tail_decay_s", event["decay_s"])) after = np.maximum(dt, 0.0) shape = (1.0 - share) * np.exp(-after / float(event["decay_s"])) + share * np.exp(-after / tail) return np.where(dt >= 0.0, amplitude * shape, 0.0) def _loss_deficit( event: Mapping[str, Any], at: float, x: "np.ndarray", topoff: Mapping[str, Any] | None, ) -> "np.ndarray": """How far a ``loss`` holds a channel below its level at each instant of ``x``. The channel drops by ``amount`` in one step at ``at`` and nothing brings it back but top-off: from the first top-off refill instant after ``at`` (an epoch-aligned multiple of the seed's ``period_s``) the injector adds one shot of ``_REFILL_SHOT_FRACTION * ceiling`` every ``1 / _REFILL_RATE_HZ`` seconds until the amount is replaced. A channel without a ``topoff`` seed never recovers. Args: event: A ``loss`` event. at: Its instant, in epoch seconds. x: Epoch seconds, ascending. topoff: The channel's ``topoff`` seed record, or None. Returns: The deficit, ``amount`` right after ``at`` and 0 before it and once refilled. """ amount = float(event["amount"]) deficit = np.where(x >= at, amount, 0.0) if topoff is None: return deficit period = float(topoff["period_s"]) shot = _REFILL_SHOT_FRACTION * abs(float(topoff["ceiling"])) refill = (np.floor(at / period) + 1.0) * period shots = np.where(x >= refill, np.floor((x - refill) * _REFILL_RATE_HZ) + 1.0, 0.0) return np.maximum(deficit - shot * shots, 0.0)
[docs] def loss_refill_bound(event: Mapping[str, Any], topoff: Mapping[str, Any] | None) -> float | None: """Seconds after its instant by which a ``loss`` is surely refilled; None if never. One top-off period to the first refill, wherever in the period the loss falls, plus the shots the amount takes. """ if topoff is None: return None shot = _REFILL_SHOT_FRACTION * abs(float(topoff["ceiling"])) shots = np.ceil(float(event["amount"]) / shot) if shot > 0 else 0.0 return float(topoff["period_s"]) + float(shots) / _REFILL_RATE_HZ
[docs] def apply_events( series: "np.ndarray", events: Sequence[Mapping[str, Any]], n: int, t_abs: "np.ndarray | None", anchor: float, tz: ZoneInfo | None = None, topoff: Mapping[str, Any] | None = None, ) -> "np.ndarray": """Apply step/ramp/spike/burst/loss events in order (window-fraction or wall-clock). A step with an end (see :func:`step_end`) holds ``to`` over ``[start, end)`` and leaves later samples on the baseline; without one it holds to the end. A ``burst`` (:func:`_burst_profile`) and a ``loss`` (:func:`_loss_deficit`) start at their instant and never move a sample before it; ``topoff`` is the channel's ``topoff`` seed record, which alone refills a loss. """ if not events: return series t_frac = np.linspace(0.0, 1.0, n) series = series.copy() for event in events: shape = event["shape"] offset_anchored = "at_offset" in event for x, at in event_positions(event, t_frac, t_abs, anchor, tz): if shape == "step": end = step_end(event, anchor, tz) inside = x >= at if end is None else (x >= at) & (x < end) series[inside] = float(event["to"]) elif shape == "ramp": until = ( anchor + float(event["until_offset"]) if offset_anchored else float(event["until"]) ) to = float(event["to"]) if until <= at: series[x >= at] = to continue idx = int(np.searchsorted(x, at)) start = float(series[min(idx, n - 1)]) mask = (x >= at) & (x <= until) series[mask] = start + (to - start) * (x[mask] - at) / (until - at) series[x > until] = to elif shape == "burst": series = series + _burst_profile(event, x - at) elif shape == "loss": series = series - _loss_deficit(event, at, x, topoff) else: # spike (gaussian bump; width as window fraction, or seconds when anchored) amplitude = float(event["amplitude"]) width = float(event["width"]) series = series + amplitude * np.exp(-((x - at) ** 2) / (2.0 * width**2)) return series