fuzzybits-server 0.17.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. fuzzybits_server/.dockerignore +64 -0
  2. fuzzybits_server/__init__.py +15 -0
  3. fuzzybits_server/app.py +93 -0
  4. fuzzybits_server/config.py +310 -0
  5. fuzzybits_server/convergence/__init__.py +100 -0
  6. fuzzybits_server/convergence/gbas.py +229 -0
  7. fuzzybits_server/convergence/metrics.py +164 -0
  8. fuzzybits_server/convergence/policies.py +387 -0
  9. fuzzybits_server/convergence/runner.py +398 -0
  10. fuzzybits_server/convergence/sampling.py +409 -0
  11. fuzzybits_server/convergence/special.py +280 -0
  12. fuzzybits_server/convergence/tally.py +179 -0
  13. fuzzybits_server/event_hub.py +58 -0
  14. fuzzybits_server/event_log.py +16 -0
  15. fuzzybits_server/fault_tree_payload.py +899 -0
  16. fuzzybits_server/model_oracle_p.json +44 -0
  17. fuzzybits_server/native.py +536 -0
  18. fuzzybits_server/routes.py +408 -0
  19. fuzzybits_server/state.py +67 -0
  20. fuzzybits_server/supervisor.py +193 -0
  21. fuzzybits_server/ui.py +84 -0
  22. fuzzybits_server/webui/.vite/manifest.json +26 -0
  23. fuzzybits_server/webui/assets/Playground-B6V8NzhX.css +1 -0
  24. fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js +5481 -0
  25. fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js.map +1 -0
  26. fuzzybits_server/webui/assets/index-BnegRRhI.css +1 -0
  27. fuzzybits_server/webui/assets/index-C3oGCBE0.js +13 -0
  28. fuzzybits_server/webui/assets/index-C3oGCBE0.js.map +1 -0
  29. fuzzybits_server/webui/index.html +24 -0
  30. fuzzybits_server/worker.py +64 -0
  31. fuzzybits_server-0.17.0.dist-info/METADATA +281 -0
  32. fuzzybits_server-0.17.0.dist-info/RECORD +34 -0
  33. fuzzybits_server-0.17.0.dist-info/WHEEL +4 -0
  34. fuzzybits_server-0.17.0.dist-info/entry_points.txt +2 -0
@@ -0,0 +1,229 @@
1
+ r"""Huber's Gamma Bernoulli Approximation Scheme (GBAS, 2017).
2
+
3
+ GBAS estimates a Bernoulli mean :math:`p` with a relative error whose *exact*
4
+ distribution is known and **independent of** :math:`p`. Concretely, fix a target
5
+ number of successes :math:`k`; draw Bernoulli(:math:`p`) trials, attaching to each
6
+ an independent ``Exp(1)`` clock, until the :math:`k`-th success; let
7
+ :math:`R=\sum A_i` be the accumulated clock. Then
8
+
9
+ .. math::
10
+
11
+ R \sim \mathrm{Gamma}(k, p), \qquad
12
+ \hat p_{\mathrm{GBAS}} = \frac{k-1}{R}, \qquad
13
+ \frac{p}{\hat p_{\mathrm{GBAS}}} \sim \mathrm{Gamma}(k, k-1).
14
+
15
+ The estimator is unbiased (:math:`\mathbb E[\hat p]=p` for :math:`k\ge 2`) and has
16
+ relative standard deviation :math:`1/\sqrt{k-2}` regardless of :math:`p`. Because
17
+ the relative-error law is known exactly, :math:`k` can be sized for an
18
+ :math:`(\varepsilon,\delta)`-relative-approximation guarantee
19
+ (:math:`\Pr(|\hat p/p-1|>\varepsilon)\le\delta`) by a pure numerical search on the
20
+ ``Gamma`` CDF -- no normal approximation -- and an *exact* confidence interval is
21
+ available at the stopping time.
22
+
23
+ Reference: M. Huber, "A Bernoulli mean estimate with known relative error
24
+ distribution," *Random Structures & Algorithms* 50:173-182, 2017
25
+ (arXiv:1309.5413).
26
+
27
+ Batched device adaptation
28
+ -------------------------
29
+ The native sampler reports only *cumulative* counters per pass, so the :math:`k`-th
30
+ success lands somewhere inside the batch that first pushes the success count to
31
+ :math:`\ge k` -- we never observe its exact trial index :math:`N^\*`. Conditioned
32
+ on a batch having :math:`s` successes among :math:`m` trials the success positions
33
+ are a uniformly random :math:`s`-subset, so the index of the :math:`j`-th success is
34
+ the negative-hypergeometric order statistic, sampled *exactly* via the
35
+ Beta-Binomial identity :math:`F\sim\mathrm{BetaBinom}(m-s;\,j,\,s-j+1)` (draw
36
+ :math:`\theta\sim\mathrm{Beta}(j,s-j+1)`, then :math:`F\sim\mathrm{Binom}(m-s,
37
+ \theta)`). Given the reconstructed :math:`N^\*`, the per-trial ``Exp(1)`` clocks
38
+ are independent of the Bernoulli outcomes, so :math:`R\mid N^\*\sim
39
+ \mathrm{Gamma}(N^\*,1)` and drawing a fresh ``Gamma`` is distributionally identical
40
+ to having accumulated the clocks online. Marginalizing over :math:`N^\*` (which is
41
+ ``NegativeBinomial(k,p)``) recovers :math:`R\sim\mathrm{Gamma}(k,p)` exactly, so the
42
+ known relative-error law is preserved despite batching.
43
+
44
+ This module is intentionally the only place in the engine that depends on
45
+ ``numpy``/``scipy``; the policy layer imports it lazily so the default
46
+ (Wald/Bayes) path stays dependency-light.
47
+ """
48
+
49
+ from __future__ import annotations
50
+
51
+ import math
52
+ from dataclasses import dataclass
53
+
54
+ import numpy as np
55
+ from scipy.special import gammainc, gammaincc, gammaincinv, ndtri
56
+
57
+ from .special import DELTA_EPSILON
58
+
59
+ __all__ = [
60
+ "K_MIN",
61
+ "relative_error_tail",
62
+ "solve_k",
63
+ "relative_sd",
64
+ "relative_interval",
65
+ "confidence_interval",
66
+ "GBASEstimate",
67
+ "estimate_at_crossing",
68
+ ]
69
+
70
+ # Need k > 2 for a finite relative variance 1/(k-2); k >= 2 for unbiasedness.
71
+ K_MIN: int = 3
72
+ # Generous cap so a degenerate (epsilon, delta) cannot spin the search forever.
73
+ _K_MAX: int = 1 << 42
74
+
75
+
76
+ def _clamp_unit(value: float) -> float:
77
+ return min(max(value, DELTA_EPSILON), 1.0 - DELTA_EPSILON)
78
+
79
+
80
+ def relative_error_tail(k: float, epsilon: float) -> float:
81
+ r"""Two-sided failure probability of GBAS(``k``) at relative tolerance ``epsilon``.
82
+
83
+ Returns :math:`\Pr(|\hat p/p - 1| > \varepsilon)`. With the relative error
84
+ :math:`X=p/\hat p\sim\mathrm{Gamma}(k,k-1)` and :math:`W=(k-1)X\sim
85
+ \mathrm{Gamma}(k,1)`,
86
+
87
+ .. math::
88
+
89
+ \Pr\!\Big(X<\tfrac1{1+\varepsilon}\Big) + \Pr\!\Big(X>\tfrac1{1-\varepsilon}\Big)
90
+ = P\!\big(k, \tfrac{k-1}{1+\varepsilon}\big) + Q\!\big(k, \tfrac{k-1}{1-\varepsilon}\big),
91
+
92
+ where :math:`P,Q` are the regularized lower/upper incomplete gamma functions.
93
+ """
94
+ eps = _clamp_unit(epsilon)
95
+ lower = gammainc(k, (k - 1.0) / (1.0 + eps)) # P(W < (k-1)/(1+eps))
96
+ upper = gammaincc(k, (k - 1.0) / (1.0 - eps)) # P(W > (k-1)/(1-eps))
97
+ return float(lower + upper)
98
+
99
+
100
+ def solve_k(epsilon: float, delta_fail: float) -> int:
101
+ r"""Smallest integer ``k >= K_MIN`` making GBAS an :math:`(\varepsilon,\delta)`-ras.
102
+
103
+ The tail :func:`relative_error_tail` is monotone decreasing in ``k``; we seed a
104
+ bracket from the normal approximation :math:`k\approx (z_{\delta/2}/\varepsilon)^2`,
105
+ gallop until the tail drops below ``delta_fail``, then binary-search the exact
106
+ minimal ``k`` (Huber's recommended logarithmic-overhead search).
107
+ """
108
+ eps = _clamp_unit(epsilon)
109
+ df = _clamp_unit(delta_fail)
110
+
111
+ if relative_error_tail(K_MIN, eps) <= df:
112
+ return K_MIN
113
+
114
+ z = float(ndtri(1.0 - df / 2.0))
115
+ hi = max(K_MIN + 1, int((z / eps) ** 2) + 2)
116
+ while relative_error_tail(hi, eps) > df:
117
+ hi *= 2
118
+ if hi >= _K_MAX:
119
+ return _K_MAX
120
+
121
+ lo = K_MIN # tail(lo) > df (checked above)
122
+ while hi - lo > 1:
123
+ mid = (lo + hi) // 2
124
+ if relative_error_tail(mid, eps) <= df:
125
+ hi = mid
126
+ else:
127
+ lo = mid
128
+ return hi
129
+
130
+
131
+ def relative_sd(k: float) -> float:
132
+ r"""Relative standard deviation of the GBAS estimate, :math:`1/\sqrt{k-2}`.
133
+
134
+ Defined for ``k > 2``; returns ``+inf`` otherwise (too few successes to bound
135
+ the relative variance).
136
+ """
137
+ return 1.0 / math.sqrt(k - 2.0) if k > 2.0 else math.inf
138
+
139
+
140
+ def confidence_interval(k: int, gamma_r: float, ci_alpha: float) -> tuple[float, float]:
141
+ r"""Exact central ``(1 - ci_alpha)`` confidence interval for :math:`p`.
142
+
143
+ Pivots on :math:`p = W/R` with :math:`W\sim\mathrm{Gamma}(k,1)` and the realized
144
+ :math:`R=` ``gamma_r``: :math:`[\,G^{-1}_k(a/2)/R,\ G^{-1}_k(1-a/2)/R\,]`. Unlike
145
+ :func:`relative_interval` (a data-independent *relative* band scaled by the point
146
+ estimate), this is the actual interval on :math:`p` at the stopping time.
147
+ """
148
+ a = _clamp_unit(ci_alpha)
149
+ lo = float(gammaincinv(k, a / 2.0)) / gamma_r
150
+ hi = float(gammaincinv(k, 1.0 - a / 2.0)) / gamma_r
151
+ return lo, hi
152
+
153
+
154
+ def relative_interval(k: int, ci_alpha: float) -> tuple[float, float]:
155
+ r"""Central ``(1 - ci_alpha)`` interval for the relative error :math:`X=p/\hat p`.
156
+
157
+ :math:`X\sim\mathrm{Gamma}(k,k-1)`, i.e. :math:`X=W/(k-1)` with
158
+ :math:`W\sim\mathrm{Gamma}(k,1)`; the interval brackets ``1`` and is independent
159
+ of the data (a property of GBAS).
160
+ """
161
+ a = _clamp_unit(ci_alpha)
162
+ lo = float(gammaincinv(k, a / 2.0)) / (k - 1.0)
163
+ hi = float(gammaincinv(k, 1.0 - a / 2.0)) / (k - 1.0)
164
+ return lo, hi
165
+
166
+
167
+ @dataclass(frozen=True, slots=True)
168
+ class GBASEstimate:
169
+ """The GBAS estimate materialized at the stopping time (``successes >= k``)."""
170
+
171
+ k: int
172
+ n_star: int # reconstructed trial index of the k-th success
173
+ gamma_r: float # R ~ Gamma(n_star, 1) == Gamma(k, p) marginally
174
+ p_hat: float # (k-1)/R: unbiased, relative error ~ Gamma(k, k-1)
175
+ ci_low: float # exact lower confidence bound on p
176
+ ci_high: float # exact upper confidence bound on p
177
+ rel_low: float # relative-error lower quantile (data-independent)
178
+ rel_high: float # relative-error upper quantile (data-independent)
179
+
180
+
181
+ def estimate_at_crossing(
182
+ *,
183
+ k: int,
184
+ prev_total: int,
185
+ prev_ones: int,
186
+ cur_total: int,
187
+ cur_ones: int,
188
+ ci_alpha: float,
189
+ rng: np.random.Generator,
190
+ ) -> GBASEstimate:
191
+ r"""Reconstruct :math:`N^\*` within the crossing batch and draw the GBAS estimate.
192
+
193
+ ``prev_*`` are the cumulative counters at the last pre-crossing pass and
194
+ ``cur_*`` the counters at the first pass with ``cur_ones >= k``. The exact CI
195
+ pivots on :math:`p=W/R` with :math:`W\sim\mathrm{Gamma}(k,1)`:
196
+ :math:`[\,G^{-1}_{k}(a/2)/R,\ G^{-1}_{k}(1-a/2)/R\,]`.
197
+ """
198
+ m = cur_total - prev_total # trials in the crossing batch
199
+ s = cur_ones - prev_ones # successes in the crossing batch
200
+ j = k - prev_ones # the k-th overall success is the j-th of this batch
201
+
202
+ if s <= 0 or j < 1 or j > s:
203
+ # Not a well-formed first crossing (e.g. policy attached mid-run); treat the
204
+ # whole accumulation as one batch from a zero baseline.
205
+ n_star = max(k, cur_total)
206
+ else:
207
+ theta = float(rng.beta(j, s - j + 1)) # Beta(j, s-j+1) order-stat fraction
208
+ failures_before = int(rng.binomial(m - s, theta))
209
+ position = j + failures_before # 1-indexed position within batch
210
+ n_star = prev_total + position
211
+ n_star = max(int(n_star), k)
212
+
213
+ gamma_r = float(rng.standard_gamma(n_star)) # Gamma(n_star, 1) == Gamma(k, p)
214
+ p_hat = (k - 1.0) / gamma_r
215
+
216
+ a = _clamp_unit(ci_alpha)
217
+ ci_low, ci_high = confidence_interval(k, gamma_r, a)
218
+ rel_low, rel_high = relative_interval(k, a)
219
+
220
+ return GBASEstimate(
221
+ k=k,
222
+ n_star=n_star,
223
+ gamma_r=gamma_r,
224
+ p_hat=p_hat,
225
+ ci_low=ci_low,
226
+ ci_high=ci_high,
227
+ rel_low=rel_low,
228
+ rel_high=rel_high,
229
+ )
@@ -0,0 +1,164 @@
1
+ """Metrics: auxiliary host-side quantities derived from the tally trajectory.
2
+
3
+ A :class:`Metric` maps an immutable ``(NodeState, RunContext)`` to a flat dict of
4
+ named values. Metrics are *non-stopping*: they describe the run but never decide
5
+ when to halt (that is the job of :mod:`.policies`). The runner attaches any
6
+ number of metrics and merges their outputs into each progress frame, so several
7
+ families of statistics are produced simultaneously every pass.
8
+
9
+ Provided metrics:
10
+
11
+ * :class:`PointEstimate` — ``mean`` (p_hat), ``std_err``, raw counters.
12
+ * :class:`InfoGainMetric` — Shannon information gain (bits) of a ``Beta(1/2,1/2)``
13
+ posterior, matching the native ``info_gain`` tracker.
14
+ * :class:`OracleDiagnostics` — accuracy + sampling-theory diagnostics versus a
15
+ known ground-truth ``oracle_p`` (only when diagnostics are enabled).
16
+
17
+ Adding a new metric is a single class with a ``compute`` method; no other layer
18
+ changes.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import math
24
+ from typing import Any, Protocol, runtime_checkable
25
+
26
+ from . import special
27
+ from .tally import NodeState, RunContext
28
+
29
+
30
+ @runtime_checkable
31
+ class Metric(Protocol):
32
+ """A named, stateless producer of derived statistics for one node."""
33
+
34
+ name: str
35
+
36
+ def compute(self, node: NodeState, ctx: RunContext) -> dict[str, Any]:
37
+ ...
38
+
39
+
40
+ class PointEstimate:
41
+ """Sample proportion and its binomial standard error."""
42
+
43
+ name = "point_estimate"
44
+
45
+ def compute(self, node: NodeState, ctx: RunContext) -> dict[str, Any]:
46
+ return {
47
+ "mean": node.mean,
48
+ "std_err": node.std_err,
49
+ "num_one_bits": node.num_one_bits,
50
+ "total_bits": node.total_bits,
51
+ "trials": node.total_bits,
52
+ }
53
+
54
+
55
+ class InfoGainMetric:
56
+ r"""Shannon information gain (bits) for a ``Beta(alpha0, beta0)`` posterior.
57
+
58
+ Mirrors ``mc/stats/info_gain.h``: with a Jeffreys prior ``Beta(1/2, 1/2)`` the
59
+ cumulative information gained from the prior to the current posterior is the
60
+ entropy reduction ``H(prior) - H(posterior)``; the per-pass gain compares the
61
+ previous and current posteriors.
62
+ """
63
+
64
+ def __init__(self, *, alpha0: float = 0.5, beta0: float = 0.5) -> None:
65
+ self.name = "info_gain"
66
+ self._alpha0 = alpha0
67
+ self._beta0 = beta0
68
+ self._prior_entropy = special.beta_entropy_bits(alpha0, beta0)
69
+
70
+ def _posterior_entropy(self, ones: int, total: int) -> float:
71
+ return special.beta_entropy_bits(self._alpha0 + ones, self._beta0 + (total - ones))
72
+
73
+ def compute(self, node: NodeState, ctx: RunContext) -> dict[str, Any]:
74
+ if node.total_bits <= 0:
75
+ return {"info_bits_last": None, "info_bits_total": None}
76
+ current_entropy = self._posterior_entropy(node.num_one_bits, node.total_bits)
77
+ total_gain = self._prior_entropy - current_entropy
78
+ previous = node.previous_point()
79
+ last_gain: float | None = None
80
+ if previous is not None and previous.total_bits > 0:
81
+ previous_entropy = self._posterior_entropy(previous.num_one_bits, previous.total_bits)
82
+ last_gain = previous_entropy - current_entropy
83
+ return {
84
+ "info_bits_last": last_gain if last_gain is None or math.isfinite(last_gain) else None,
85
+ "info_bits_total": total_gain if math.isfinite(total_gain) else None,
86
+ }
87
+
88
+
89
+ class OracleDiagnostics:
90
+ """Accuracy + sampling-theory diagnostics versus a known ground truth.
91
+
92
+ Active only when ``ctx.diagnostics_enabled`` (i.e. an ``oracle_p >= 0`` was
93
+ supplied). Mirrors ``mc/stats/diagnostics.h``.
94
+ """
95
+
96
+ name = "oracle_diagnostics"
97
+
98
+ def compute(self, node: NodeState, ctx: RunContext) -> dict[str, Any]:
99
+ if not ctx.diagnostics_enabled or ctx.oracle_p is None:
100
+ return {}
101
+ p_true = ctx.oracle_p
102
+ mean = node.mean
103
+ std_err = node.std_err
104
+ z = ctx.z
105
+
106
+ bias = mean - p_true
107
+ abs_error = abs(bias)
108
+ rel_error = abs_error / p_true if p_true != 0.0 else math.nan
109
+ mse = bias * bias
110
+ log10_abs_error = math.log10(abs_error) if abs_error > 0.0 else math.nan
111
+ abs_log10_error = (
112
+ abs(math.log10(mean) - math.log10(p_true)) if (mean > 0.0 and p_true > 0.0) else math.nan
113
+ )
114
+
115
+ z_score = bias / std_err if std_err > 0.0 else math.nan
116
+ p_value = special.two_sided_p_value(z_score) if std_err > 0.0 else math.nan
117
+
118
+ # Wald 95/99 coverage (mirrors populate_point_estimates ci layout).
119
+ hw95 = 1.959963984540054 * std_err
120
+ hw99 = 2.5758293035489004 * std_err
121
+ ci95_covered = (mean - hw95) <= p_true <= (mean + hw95)
122
+ ci99_covered = (mean - hw99) <= p_true <= (mean + hw99)
123
+
124
+ eps_target = ctx.delta * max(mean, special.DELTA_EPSILON)
125
+ n_required = (
126
+ special.required_trials_two_sided(p_true, eps_target, z)
127
+ if 0.0 < ctx.confidence < 1.0
128
+ else 0
129
+ )
130
+ n_ratio = node.total_bits / n_required if n_required > 0 else math.nan
131
+
132
+ return {
133
+ "oracle_p": p_true,
134
+ "bias": bias,
135
+ "abs_error": abs_error,
136
+ "rel_error": rel_error,
137
+ "mse": mse,
138
+ "log10_abs_error": log10_abs_error,
139
+ "abs_log10_error": abs_log10_error,
140
+ "z_score": z_score,
141
+ "p_value": p_value,
142
+ "ci95_covered": ci95_covered,
143
+ "ci99_covered": ci99_covered,
144
+ "n_required": n_required,
145
+ "n_ratio": n_ratio,
146
+ }
147
+
148
+
149
+ def default_metrics(*, with_info_gain: bool = True) -> list[Metric]:
150
+ """Convenience: the standard metric stack used by the live demo."""
151
+ metrics: list[Metric] = [PointEstimate()]
152
+ if with_info_gain:
153
+ metrics.append(InfoGainMetric())
154
+ metrics.append(OracleDiagnostics())
155
+ return metrics
156
+
157
+
158
+ __all__ = [
159
+ "Metric",
160
+ "PointEstimate",
161
+ "InfoGainMetric",
162
+ "OracleDiagnostics",
163
+ "default_metrics",
164
+ ]