gea-program 0.1.0__py3-none-any.whl

gea/accuracy_statement.py

@@ -0,0 +1,181 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""accuracy_statement — the accuracy statement in the client's statistic.
+
+A production-operations client states tool accuracy as MAPE (mean absolute
+percentage error) at a stated confidence interval, per predicted quantity,
+per well, with n and the back-test window, and reads the result against an
+accuracy band. This module produces exactly that from per-trial back-test
+results, and a back-test runner that re-scores the library's blind
+(leave-one-out) predictions trial by trial so the statistic is computed on
+the raw errors, never on a summary.
+
+Definitions in force (printed on every statement; client-configurable):
+
+    APE_i      = |estimate_i - truth_i| / |truth_i| x 100
+    MAPE       = mean(APE_i)
+    Accuracy   = 100 - MAPE
+    CI         = bootstrap percentile interval on MAPE (default 90 %,
+                 2,000 resamples, fixed seed - reproducible)
+    Coverage90 = fraction of trials whose truth lies inside the estimate's
+                 own +/- 1.645 sigma band (calibration check; ~0.90 expected)
+    Band       = accuracy read against the thresholds
+                 MEETS_TARGET >= 95 / BAND_2 90-95 / BAND_3 85-90 /
+                 NOT_ACCEPTABLE < 85, using the CONSERVATIVE end of the CI
+                 (accuracy at the upper CI bound of MAPE) so a statement
+                 never claims a band the interval does not support.
+
+Trials below MIN_TRIALS are reported PENDING with n, never scored.
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass, asdict
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+
+MIN_TRIALS = 10
+DEFAULT_CI = 0.90
+N_BOOT = 2000
+SEED = 20260928
+Z90 = 1.6448536269514722
+
+BANDS = [(95.0, 'MEETS_TARGET'), (90.0, 'BAND_2'), (85.0, 'BAND_3'), (-1e9, 'NOT_ACCEPTABLE')]
+
+
+def band_for(accuracy_pct: float) -> str:
+    for thr, name in BANDS:
+        if accuracy_pct >= thr:
+            return name
+    return 'NOT_ACCEPTABLE'
+
+
+@dataclass
+class Trial:
+    truth: float
+    estimate: float
+    std: float            # the estimate's own 1-sigma spread (0 if none)
+
+
+def statement_from_trials(trials: Sequence[Trial], ci: float = DEFAULT_CI,
+                          n_boot: int = N_BOOT, seed: int = SEED) -> dict:
+    """MAPE with a bootstrap CI, coverage at the CI level, and the band."""
+    n = len(trials)
+    if n < MIN_TRIALS:
+        return {'status': 'PENDING', 'n': n, 'min_n': MIN_TRIALS}
+    truth = np.array([t.truth for t in trials], dtype=float)
+    est = np.array([t.estimate for t in trials], dtype=float)
+    std = np.array([t.std for t in trials], dtype=float)
+    nz = np.abs(truth) > 0
+    if nz.sum() < MIN_TRIALS:
+        return {'status': 'PENDING', 'n': int(nz.sum()), 'min_n': MIN_TRIALS,
+                'note': 'truth values at zero cannot carry a percentage error'}
+    ape = np.abs(est[nz] - truth[nz]) / np.abs(truth[nz]) * 100.0
+    mape = float(ape.mean())
+    rng = np.random.default_rng(seed)
+    idx = rng.integers(0, len(ape), size=(n_boot, len(ape)))
+    boots = ape[idx].mean(axis=1)
+    alpha = (1.0 - ci) / 2.0
+    lo, hi = float(np.percentile(boots, 100 * alpha)), float(np.percentile(boots, 100 * (1 - alpha)))
+    z = Z90 if abs(ci - 0.90) < 1e-9 else float(_z_for(ci))
+    with_std = std > 0
+    cov = float(np.mean(np.abs(est[with_std] - truth[with_std]) <= z * std[with_std])) if with_std.any() else None
+    acc = 100.0 - mape
+    acc_conservative = 100.0 - hi
+    return {
+        'status': 'OK', 'n': int(len(ape)), 'ci': ci,
+        'mape_pct': round(mape, 3), 'mape_ci_lo_pct': round(lo, 3), 'mape_ci_hi_pct': round(hi, 3),
+        'accuracy_pct': round(acc, 3), 'accuracy_conservative_pct': round(acc_conservative, 3),
+        'coverage_at_ci': (round(cov, 3) if cov is not None else None),
+        'n_with_spread': int(with_std.sum()),
+        'band': band_for(acc_conservative), 'band_point': band_for(acc),
+        'max_ape_pct': round(float(ape.max()), 3), 'median_ape_pct': round(float(np.median(ape)), 3),
+    }
+
+
+def _z_for(ci: float) -> float:
+    # two-sided normal quantile by bisection on the error function (no scipy)
+    import math
+    target = ci
+    lo, hi = 0.0, 10.0
+    for _ in range(80):
+        mid = (lo + hi) / 2
+        if math.erf(mid / math.sqrt(2)) < target:
+            lo = mid
+        else:
+            hi = mid
+    return (lo + hi) / 2
+
+
+# ---------------------------------------------------------------------------
+# Back-test runner: the library's blind predictions, trial by trial
+# ---------------------------------------------------------------------------
+def _loo_trials(pairs: List[tuple], k: int = 7) -> List[Trial]:
+    from .inverse_engine import _conditional_from_pairs
+    out: List[Trial] = []
+    for i in range(len(pairs)):
+        rest = pairs[:i] + pairs[i + 1:]
+        g, t = pairs[i]
+        c = _conditional_from_pairs(rest, g, k)
+        if c['status'] != 'OK':
+            continue
+        out.append(Trial(truth=float(t), estimate=float(c['estimate']), std=float(c['std'])))
+    return out
+
+
+def library_backtest(ci: float = DEFAULT_CI, k: int = 7) -> dict:
+    """Leave-one-out back-test of every supported property pair in the
+    library, scored as an accuracy statement per pair. Same estimator, same
+    library, same hold-out as the standing blind harness; the difference is
+    that the raw trials are kept so MAPE and its CI can be computed."""
+    from . import strata_join as SJ
+    from .inverse_engine import _site_native_pairs
+    rows = []
+    for well, (_, props) in SJ.WELL_GROUPS.items():
+        names = sorted(props)
+        for i, a in enumerate(names):
+            for b in names[i + 1:]:
+                pairs, _bin = SJ._colocated(well, a, b, None)
+                st = statement_from_trials(_loo_trials(pairs, k), ci=ci)
+                st.update({'well': well, 'given': a, 'target': b, 'source': 'strata_join',
+                           'n_pairs': len(pairs)})
+                rows.append(st)
+    try:
+        pairs, washouts = _site_native_pairs('ktb_hb_complog_6020_excerpt')
+        st = statement_from_trials(_loo_trials(pairs, k), ci=ci)
+        st.update({'well': 'ktb_complog', 'given': 'rho (g/cc)', 'target': 'Vp (m/s)',
+                   'source': 'site_pairs', 'n_pairs': len(pairs), 'washouts_excluded': washouts})
+        rows.append(st)
+    except KeyError:
+        pass
+    ok = [r for r in rows if r['status'] == 'OK']
+    pending = [r for r in rows if r['status'] != 'OK']
+    ok.sort(key=lambda r: r['mape_pct'])
+    bands: Dict[str, int] = {}
+    for r in ok:
+        bands[r['band']] = bands.get(r['band'], 0) + 1
+    return {
+        'method': {'hold_out': 'leave-one-out', 'estimator': f'k-nearest empirical conditional, k={k}',
+                   'ci': ci, 'bootstrap_resamples': N_BOOT, 'seed': SEED, 'min_trials': MIN_TRIALS,
+                   'band_rule': 'band from accuracy at the upper CI bound of MAPE (conservative)'},
+        'statements': ok, 'pending': pending, 'n_ok': len(ok), 'n_pending': len(pending),
+        'bands': bands,
+        'worst_mape_pct': (ok[-1]['mape_pct'] if ok else None),
+        'best_mape_pct': (ok[0]['mape_pct'] if ok else None),
+        'median_coverage_at_ci': (statistics.median([r['coverage_at_ci'] for r in ok if r['coverage_at_ci'] is not None])
+                                  if any(r['coverage_at_ci'] is not None for r in ok) else None),
+    }
+
+
+def statement_from_arrays(truth, estimate, std=None, ci: float = DEFAULT_CI) -> dict:
+    """Convenience: arrays -> statement (for any predictor, gauge track included)."""
+    truth = np.asarray(truth, dtype=float)
+    estimate = np.asarray(estimate, dtype=float)
+    std = np.zeros_like(truth) if std is None else np.asarray(std, dtype=float)
+    m = ~(np.isnan(truth) | np.isnan(estimate))
+    return statement_from_trials([Trial(float(t), float(e), float(s)) for t, e, s in zip(truth[m], estimate[m], std[m])], ci=ci)

gea/alarm_engine.py

@@ -0,0 +1,307 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""alarm_engine — alarm definitions, the alarm state machine, the event log
+and the alarm-management KPIs (SOW 4.2.4; ISA-18.2 / IEC 62682 practice).
+
+Definitions are engineering configuration: each alarm names its tag, kind,
+setpoint, deadband (return-to-normal hysteresis in engineering units),
+on-delay (seconds the condition must persist before the alarm activates),
+priority (P1 highest .. P5 lowest) and the BASIS of the setpoint (a
+datasheet, a client setting, the record layer). Nothing here invents a
+setpoint: `defaults_from_catalogue` derives only instrument over-range
+alarms from the engineering range the tag catalogue already carries, plus a
+quality alarm per tag; every other setpoint is loaded from the client's
+definitions file.
+
+State machine per alarm (ISA-18.2 states, simplified):
+
+    NORMAL --condition true for >= on_delay--> ACTIVE_UNACKED
+    ACTIVE_UNACKED --acknowledge--> ACTIVE_ACKED
+    ACTIVE_* --condition false past the deadband--> NORMAL (event CLEARED;
+              an unacknowledged alarm that clears is logged RTN_UNACKED)
+    any --shelve--> SHELVED (suppressed, logged) --unshelve--> NORMAL
+
+Kinds: HIGH, HIGH_HIGH, LOW, LOW_LOW (value vs setpoint with deadband),
+RATE (|dv/dt| vs setpoint per second), QUALITY (sample flag not GOOD).
+
+Event log: one line per transition - timestamp, alarm, tag, kind, priority,
+event (ACTIVATED / ACKNOWLEDGED / CLEARED / RTN_UNACKED / SHELVED /
+UNSHELVED), value, operator, note. Append-only JSON lines when a path is
+given; always kept in memory.
+
+KPIs over a window (targets as commonly stated in ISA-18.2 practice, printed
+as targets, not as this program's claims): average alarm rate per 10 min
+(target <= 1, manageable <= 2), peak 10-min rate, alarm floods (> 10 alarms
+in 10 min) and time in flood, standing alarms (active longer than 24 h),
+chattering alarms (>= 5 activations in 10 min), priority distribution
+(target about 80 / 15 / 5 for P3 / P2 / P1 when three priorities are used),
+top-10 most frequent alarms.
+
+Headless-safe: numpy only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timedelta, timezone
+from typing import Dict, Iterable, List, Optional
+
+import numpy as np
+
+from .sample_record import SampleRecord, TagCatalogue, parse_utc
+
+KINDS = ('HIGH', 'HIGH_HIGH', 'LOW', 'LOW_LOW', 'RATE', 'QUALITY')
+PRIORITIES = ('P1', 'P2', 'P3', 'P4', 'P5')
+EVENTS = ('ACTIVATED', 'ACKNOWLEDGED', 'CLEARED', 'RTN_UNACKED', 'SHELVED', 'UNSHELVED')
+
+
+@dataclass
+class AlarmDefinition:
+    alarm_id: str
+    tag_id: str
+    kind: str
+    priority: str = 'P3'
+    setpoint: Optional[float] = None
+    deadband: float = 0.0
+    on_delay_s: float = 0.0
+    description: str = ''
+    basis: str = 'client setting'
+    enabled: bool = True
+
+    def __post_init__(self):
+        if self.kind not in KINDS:
+            raise ValueError(f'unknown alarm kind {self.kind}; kinds {KINDS}')
+        if self.priority not in PRIORITIES:
+            raise ValueError(f'unknown priority {self.priority}; priorities {PRIORITIES}')
+        if self.kind != 'QUALITY' and self.setpoint is None:
+            raise ValueError(f'{self.alarm_id}: {self.kind} needs a setpoint')
+
+    def row(self) -> dict:
+        return asdict(self)
+
+
+def load_alarm_definitions(path) -> List[AlarmDefinition]:
+    with open(path, encoding='utf-8') as f:
+        d = json.load(f)
+    return [AlarmDefinition(**x) for x in (d['alarms'] if isinstance(d, dict) else d)]
+
+
+def write_alarm_definitions(defs: Iterable[AlarmDefinition], path) -> str:
+    with open(path, 'w', encoding='utf-8') as f:
+        json.dump({'alarms': [d.row() for d in defs]}, f, indent=1)
+    return str(path)
+
+
+def defaults_from_catalogue(catalogue: TagCatalogue, quality_priority: str = 'P4',
+                            range_priority: str = 'P2') -> List[AlarmDefinition]:
+    """Instrument over-range alarms at the tag's engineering range (basis:
+    the catalogue / datasheet) and one QUALITY alarm per tag. No process
+    setpoints - those come from the client's definitions file."""
+    out: List[AlarmDefinition] = []
+    for r in catalogue.rows():
+        tag = r['tag_id']
+        lo, hi = r['eng_range_lo'], r['eng_range_hi']
+        unit = r['unit']
+        if hi != '':
+            out.append(AlarmDefinition(alarm_id=f'{tag}.HH_RANGE', tag_id=tag, kind='HIGH_HIGH', priority=range_priority,
+                                       setpoint=float(hi), deadband=abs(float(hi)) * 0.005,
+                                       description=f'{tag} above instrument range {hi:g} {unit}',
+                                       basis=f"engineering range upper bound ({r['limits_basis'].split(';')[0]})"))
+        if lo != '':
+            out.append(AlarmDefinition(alarm_id=f'{tag}.LL_RANGE', tag_id=tag, kind='LOW_LOW', priority=range_priority,
+                                       setpoint=float(lo), deadband=max(abs(float(hi)) * 0.005 if hi != '' else 0.0, 0.0),
+                                       description=f'{tag} below instrument range {lo:g} {unit}',
+                                       basis=f"engineering range lower bound ({r['limits_basis'].split(';')[0]})"))
+        out.append(AlarmDefinition(alarm_id=f'{tag}.QUALITY', tag_id=tag, kind='QUALITY', priority=quality_priority,
+                                   description=f'{tag} sample quality not GOOD', basis='record layer quality rules'))
+    return out
+
+
+def _iso(dt: datetime) -> str:
+    return dt.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+@dataclass
+class _State:
+    state: str = 'NORMAL'
+    cond_since: Optional[datetime] = None
+    active_since: Optional[datetime] = None
+    activations: List[datetime] = field(default_factory=list)
+    last_value: Optional[float] = None
+    last_time: Optional[datetime] = None
+
+
+class AlarmEngine:
+    """Feeds SampleRecords through every enabled definition on their tag."""
+
+    def __init__(self, definitions: Iterable[AlarmDefinition], event_log_path: Optional[str] = None,
+                 operator_positions: int = 1):
+        self.defs: Dict[str, AlarmDefinition] = {d.alarm_id: d for d in definitions}
+        self.by_tag: Dict[str, List[AlarmDefinition]] = {}
+        for d in self.defs.values():
+            self.by_tag.setdefault(d.tag_id, []).append(d)
+        self.states: Dict[str, _State] = {a: _State() for a in self.defs}
+        self.events: List[dict] = []
+        self.log_path = event_log_path
+        self.operator_positions = max(1, int(operator_positions))
+        if event_log_path and os.path.exists(event_log_path):
+            with open(event_log_path, encoding='utf-8') as f:
+                self.events = [json.loads(l) for l in f if l.strip()]
+
+    # -- events -----------------------------------------------------------------
+    def _event(self, now: datetime, d: AlarmDefinition, event: str, value=None, operator: str = '', note: str = '') -> dict:
+        e = {'timestamp_utc': _iso(now), 'alarm_id': d.alarm_id, 'tag_id': d.tag_id, 'kind': d.kind,
+             'priority': d.priority, 'event': event, 'value': (None if value is None else float(value)),
+             'setpoint': d.setpoint, 'operator': operator, 'note': note}
+        self.events.append(e)
+        if self.log_path:
+            with open(self.log_path, 'a', encoding='utf-8') as f:
+                f.write(json.dumps(e, sort_keys=True) + '\n')
+        return e
+
+    # -- condition evaluation ------------------------------------------------------
+    @staticmethod
+    def _condition(d: AlarmDefinition, rec: SampleRecord, st: _State, now: datetime) -> Optional[bool]:
+        """True = in alarm, False = clearly normal (past deadband), None = inside the deadband (hold)."""
+        if d.kind == 'QUALITY':
+            return rec.quality_flag != 'GOOD'
+        v = rec.value
+        if v is None or (isinstance(v, float) and np.isnan(v)):
+            return None
+        sp, db = float(d.setpoint), float(d.deadband)
+        if d.kind in ('HIGH', 'HIGH_HIGH'):
+            return True if v >= sp else (False if v < sp - db else None)
+        if d.kind in ('LOW', 'LOW_LOW'):
+            return True if v <= sp else (False if v > sp + db else None)
+        if d.kind == 'RATE':
+            if st.last_value is None or st.last_time is None:
+                return False
+            dt = (now - st.last_time).total_seconds()
+            if dt <= 0:
+                return None
+            r = abs((v - st.last_value) / dt)
+            return True if r >= sp else (False if r < max(sp - db, 0.0) else None)
+        return None
+
+    def process(self, records: Iterable[SampleRecord]) -> List[dict]:
+        """Process records in time order per tag. Returns the events raised."""
+        start = len(self.events)
+        recs = sorted(records, key=lambda r: (r.timestamp_utc, r.tag_id))
+        for rec in recs:
+            for d in self.by_tag.get(rec.tag_id, []):
+                if not d.enabled:
+                    continue
+                st = self.states[d.alarm_id]
+                now = parse_utc(rec.timestamp_utc)
+                if st.state == 'SHELVED':
+                    st.last_value, st.last_time = rec.value, now
+                    continue
+                cond = self._condition(d, rec, st, now)
+                if cond is True:
+                    if st.cond_since is None:
+                        st.cond_since = now
+                    if st.state == 'NORMAL' and (now - st.cond_since).total_seconds() >= d.on_delay_s:
+                        st.state = 'ACTIVE_UNACKED'
+                        st.active_since = now
+                        st.activations.append(now)
+                        self._event(now, d, 'ACTIVATED', rec.value, note=(rec.rule_fired if d.kind == 'QUALITY' else ''))
+                elif cond is False:
+                    st.cond_since = None
+                    if st.state in ('ACTIVE_UNACKED', 'ACTIVE_ACKED'):
+                        self._event(now, d, 'CLEARED' if st.state == 'ACTIVE_ACKED' else 'RTN_UNACKED', rec.value)
+                        st.state = 'NORMAL'
+                        st.active_since = None
+                # cond None: inside the deadband - hold the current state
+                if rec.value is not None and not (isinstance(rec.value, float) and np.isnan(rec.value)):
+                    st.last_value, st.last_time = rec.value, now
+        return self.events[start:]
+
+    # -- operator actions -------------------------------------------------------------
+    def acknowledge(self, alarm_id: str, operator: str, now: datetime, note: str = '') -> dict:
+        st, d = self.states[alarm_id], self.defs[alarm_id]
+        if st.state != 'ACTIVE_UNACKED':
+            raise ValueError(f'{alarm_id} is {st.state}, nothing to acknowledge')
+        st.state = 'ACTIVE_ACKED'
+        return self._event(now, d, 'ACKNOWLEDGED', st.last_value, operator, note)
+
+    def shelve(self, alarm_id: str, operator: str, now: datetime, note: str = '') -> dict:
+        st, d = self.states[alarm_id], self.defs[alarm_id]
+        st.state = 'SHELVED'
+        st.cond_since = None
+        return self._event(now, d, 'SHELVED', st.last_value, operator, note)
+
+    def unshelve(self, alarm_id: str, operator: str, now: datetime) -> dict:
+        st, d = self.states[alarm_id], self.defs[alarm_id]
+        st.state = 'NORMAL'
+        return self._event(now, d, 'UNSHELVED', st.last_value, operator)
+
+    def active(self) -> List[dict]:
+        return [{'alarm_id': a, 'state': s.state, 'priority': self.defs[a].priority, 'tag_id': self.defs[a].tag_id,
+                 'active_since_utc': _iso(s.active_since) if s.active_since else None, 'last_value': s.last_value}
+                for a, s in self.states.items() if s.state.startswith('ACTIVE')]
+
+    # -- KPIs -------------------------------------------------------------------------
+    def kpis(self, window_start: Optional[datetime] = None, window_end: Optional[datetime] = None,
+             standing_hours: float = 24.0) -> dict:
+        acts = [e for e in self.events if e['event'] == 'ACTIVATED']
+        if not acts:
+            return {'n_activations': 0, 'window': None, 'note': 'no activations in the window'}
+        times = [parse_utc(e['timestamp_utc']) for e in acts]
+        ws = window_start or min(times)
+        we = window_end or max(times)
+        span_min = max((we - ws).total_seconds() / 60.0, 10.0)
+        acts_w = [(t, e) for t, e in zip(times, acts) if ws <= t <= we]
+        n = len(acts_w)
+        # 10-minute bins
+        nb = int(np.ceil(span_min / 10.0))
+        bins = np.zeros(nb, dtype=int)
+        for t, _ in acts_w:
+            bins[min(int((t - ws).total_seconds() // 600), nb - 1)] += 1
+        per_pos = bins / self.operator_positions
+        flood_bins = int(np.sum(per_pos > 10))
+        # chattering: >= 5 activations of one alarm within any 10-minute span
+        chatter = []
+        for a, s in self.states.items():
+            ts = sorted(s.activations)
+            for i in range(len(ts)):
+                if i + 4 < len(ts) and (ts[i + 4] - ts[i]).total_seconds() <= 600:
+                    chatter.append(a)
+                    break
+        # standing alarms
+        standing = [a for a, s in self.states.items() if s.active_since and (we - s.active_since).total_seconds() > standing_hours * 3600]
+        # priority distribution
+        pr = {p: 0 for p in PRIORITIES}
+        for _, e in acts_w:
+            pr[e['priority']] += 1
+        counts: Dict[str, int] = {}
+        for _, e in acts_w:
+            counts[e['alarm_id']] = counts.get(e['alarm_id'], 0) + 1
+        top = sorted(counts.items(), key=lambda kv: -kv[1])[:10]
+        unacked = [a for a, s in self.states.items() if s.state == 'ACTIVE_UNACKED']
+        return {
+            'window': [_iso(ws), _iso(we)], 'window_hours': round(span_min / 60.0, 2),
+            'operator_positions': self.operator_positions,
+            'n_activations': n, 'per_day': round(n / (span_min / 1440.0), 1),
+            'avg_per_10min_per_position': round(float(per_pos.mean()), 3),
+            'peak_per_10min_per_position': round(float(per_pos.max()), 2),
+            'flood_10min_bins': flood_bins, 'pct_time_in_flood': round(100.0 * flood_bins / nb, 2),
+            'standing_alarms_over_24h': standing, 'chattering_alarms': chatter,
+            'active_unacknowledged': unacked,
+            'priority_distribution': pr,
+            'priority_distribution_pct': {p: round(100.0 * c / n, 1) for p, c in pr.items()} if n else pr,
+            'top_alarms': [{'alarm_id': a, 'activations': c, 'pct_of_total': round(100.0 * c / n, 1)} for a, c in top],
+            'targets': {'avg_per_10min': '<= 1 acceptable, <= 2 manageable', 'per_day': '<= 150 acceptable, <= 300 manageable',
+                        'flood': '> 10 alarms in 10 min per operator position', 'chattering': '>= 5 activations in 10 min',
+                        'standing': f'active > {standing_hours:g} h', 'priority_split': 'about 80 / 15 / 5 (P3 / P2 / P1) for a three-priority scheme',
+                        'basis': 'targets as commonly stated in ISA-18.2 / IEC 62682 alarm-management practice; printed as targets, not as results'},
+        }
+
+
+def records_from_series(tag_id: str, times: List[str], values: List[float], unit: str = '',
+                        flags: Optional[List[str]] = None) -> List[SampleRecord]:
+    """Convenience for tests and for feeding a single series."""
+    return [SampleRecord(tag_id=tag_id, timestamp_utc=t, value=v, unit=unit,
+                         quality_flag=(flags[i] if flags else 'GOOD')) for i, (t, v) in enumerate(zip(times, values))]

gea/bench.py

@@ -0,0 +1,144 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+"""Bench-test analysis (v1.48.0) - field-tier step 8.
+
+The analysis half of BENCH_TEST_PROTOCOL.md: fit each leg's drift slope,
+propagate uncertainties into the conventional/GEA ratio, and return a
+verdict from the protocol's vocabulary (MEASURED_CONFIRMS /
+MEASURED_REFUTES / INSUFFICIENT_SPAN / INSUFFICIENT_SNR).
+
+Honesty rules:
+- The 18-day span floor is READ FROM the reconciler's own configuration -
+  the bench cannot be rushed past the product's standing rule.
+- The self-test is labeled SIMULATION_SELF_TEST in its own output: it
+  verifies the analysis arithmetic against the engine's twin models, and
+  proves NOTHING about physical gauges.
+- A refutation is a first-class outcome, not an error.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import numpy as np
+
+from .quartz_hpht_extension import (calculate_quartz_transducer_hpht_program,
+                                         canonical_suppression,
+                                         conventional_drift)
+from .reconciler import ReconcilerConfig
+
+YEAR_S = 365.25 * 86400.0
+
+
+def _leg_slope(times_s: np.ndarray, p_psi: np.ndarray,
+               full_scale_psi: float) -> dict:
+    """OLS drift slope of one leg at constant setpoint: %FS/yr with the
+    standard error of the slope propagated from the fit residuals."""
+    t = np.asarray(times_s, dtype=float) / YEAR_S
+    p = np.asarray(p_psi, dtype=float)
+    m = ~(np.isnan(t) | np.isnan(p))
+    t, p = t[m], p[m]
+    n = len(t)
+    if n < 8:
+        raise ValueError(f"leg needs >= 8 finite samples (got {n})")
+    span_years = float(t.max() - t.min())
+    A = np.vstack([t - t.mean(), np.ones(n)]).T
+    coef, res, _, _ = np.linalg.lstsq(A, p, rcond=None)
+    slope_psi_yr = float(coef[0])
+    dof = max(n - 2, 1)
+    sigma2 = float(res[0]) / dof if len(res) else float(np.var(p - A @ coef))
+    se_slope = float(np.sqrt(sigma2 / np.sum((t - t.mean()) ** 2)))
+    return {"n": n, "span_years": round(span_years, 4),
+            "slope_psi_yr": round(slope_psi_yr, 3),
+            "se_slope_psi_yr": round(se_slope, 3),
+            "drift_pct_fs_yr": round(slope_psi_yr / full_scale_psi * 100.0, 5),
+            "se_drift_pct_fs_yr": round(se_slope / full_scale_psi * 100.0, 5)}
+
+
+def bench_analysis(times_s, p_psi, conv_times_s, conv_p_psi,
+                   full_scale_psi: float = 30000.0,
+                   k_sigma: float = 2.0) -> dict:
+    """The protocol section 5 analysis. Inputs are the two legs' raw
+    pressure series at a constant setpoint; output carries the measured
+    ratio, its propagated uncertainty, the prediction, and the verdict."""
+    cfg = ReconcilerConfig()
+    uq = _leg_slope(times_s, p_psi, full_scale_psi)
+    cv = _leg_slope(conv_times_s, conv_p_psi, full_scale_psi)
+    prediction = canonical_suppression()
+    out = {"protocol": "BENCH_TEST_PROTOCOL.md section 5",
+           "prediction_ratio": round(prediction, 4),
+           "prediction_status": ("DERIVED_HYBRID composition - the quantity "
+                                 "this bench exists to confirm or refute"),
+           "leg": uq, "conventional_leg": cv,
+           "full_scale_psi": full_scale_psi}
+    min_span = float(cfg.min_trend_span_years)
+    if uq["span_years"] < min_span or cv["span_years"] < min_span:
+        out["verdict"] = "INSUFFICIENT_SPAN"
+        out["detail"] = (f"span floor {min_span:g} yr "
+                         f"(the reconciler's own >=18-day slope rule) not met "
+                         f"- no verdict; the bench cannot be rushed")
+        return out
+    if uq["slope_psi_yr"] <= 0:
+        out["verdict"] = "INSUFFICIENT_SNR"
+        out["detail"] = ("program-model-leg slope is non-positive - a drift ratio has "
+                         "no meaning here; check setpoint stability")
+        return out
+    r = cv["slope_psi_yr"] / uq["slope_psi_yr"]
+    se_r = abs(r) * float(np.sqrt(
+        (cv["se_slope_psi_yr"] / cv["slope_psi_yr"]) ** 2
+        + (uq["se_slope_psi_yr"] / uq["slope_psi_yr"]) ** 2))
+    out["measured_ratio"] = round(r, 4)
+    out["se_ratio"] = round(se_r, 4)
+    lo, hi = r - k_sigma * se_r, r + k_sigma * se_r
+    contains_pred = lo <= prediction <= hi
+    contains_unity = lo <= 1.0 <= hi
+    if contains_pred and contains_unity:
+        out["verdict"] = "INSUFFICIENT_SNR"
+        out["detail"] = (f"the {k_sigma:.0f}-sigma band [{lo:.4f}, {hi:.4f}] "
+                         "contains BOTH the prediction and 1.0 - suppression "
+                         "cannot be distinguished from no-suppression; more "
+                         "data required, no verdict")
+    elif contains_pred:
+        out["verdict"] = "MEASURED_CONFIRMS"
+        out["detail"] = (f"measured R = {r:.4f} +/- {se_r:.4f} contains the "
+                         f"predicted {prediction:.4f} and excludes 1.0 - on "
+                         "REAL bench data this outcome would support "
+                         "relabeling per protocol section 6")
+    else:
+        out["verdict"] = "MEASURED_REFUTES"
+        out["detail"] = (f"measured R = {r:.4f} +/- {se_r:.4f} excludes the "
+                         f"predicted {prediction:.4f} - a first-class "
+                         "outcome: the composition is falsified at these "
+                         "conditions; the label stays DERIVED_HYBRID with "
+                         "this refutation on record (protocol section 6)")
+    return out
+
+
+def bench_selftest(days: int = 120, setpoint_psi: float = 10000.0,
+                   setpoint_temp_C: float = 150.0,
+                   noise_psi: float = 0.5, seed: int = 8,
+                   conv_scale: float = 1.0) -> dict:
+    """SIMULATION_SELF_TEST: synthesize both legs from the engine's own
+    drift models at the protocol's setpoint class and run the analysis.
+    Verifies the ARITHMETIC, proves nothing about gauges - and says so in
+    its own output. conv_scale != 1 exercises the refutation path."""
+    r_uq = float(calculate_quartz_transducer_hpht_program(
+        depth_m=3000.0, temp_c=setpoint_temp_C,
+        pressure_psi=setpoint_psi)["value"]["drift_pct"])
+    r_cv = conventional_drift(setpoint_temp_C, setpoint_psi) * conv_scale
+    fs = 30000.0
+    rng = np.random.default_rng(seed)
+    t = np.arange(days) * 86400.0
+    ty = t / YEAR_S
+    p_uq = setpoint_psi + r_uq / 100.0 * fs * ty + rng.normal(0, noise_psi, days)
+    p_cv = setpoint_psi + r_cv / 100.0 * fs * ty + rng.normal(0, noise_psi, days)
+    out = bench_analysis(t, p_uq, t, p_cv, full_scale_psi=fs)
+    out["mode"] = ("SIMULATION_SELF_TEST: both legs synthesized from the "
+                   "engine's own models - this verifies the analysis "
+                   "arithmetic and the bench pipeline, NOT the physics; "
+                   "no gauge was measured")
+    out["synth_inputs"] = {"days": days, "setpoint_psi": setpoint_psi,
+                           "setpoint_temp_C": setpoint_temp_C,
+                           "noise_psi": noise_psi, "seed": seed,
+                           "conv_scale": conv_scale}
+    return out