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,409 @@
1
+ """Samplers: the boundary between the host engine and the bitstream producer.
2
+
3
+ A :class:`Sampler` is the *only* thing the convergence engine needs from the
4
+ outside world. Each :meth:`Sampler.step` runs exactly one device pass and
5
+ returns a :class:`PassObservation` of raw cumulative counters. Two
6
+ implementations are provided:
7
+
8
+ * :class:`NativeSampler` — wraps the ``fuzzybits`` native extension
9
+ (``run_compile`` -> ``Pdag.create_layer_manager`` -> ``single_pass``). It
10
+ prefers the multi-node ``single_pass_all`` binding when present and otherwise
11
+ falls back to the single-event ``single_pass`` (root only), so the engine
12
+ works against existing native builds.
13
+ * :class:`BernoulliSampler` — a pure-Python binomial simulator used to unit-test
14
+ the entire engine (policies, metrics, runner) without a GPU/SYCL build.
15
+
16
+ Because the engine programs only against the protocol, swapping samplers (real
17
+ device, replay, simulation) requires no changes anywhere else.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import random
23
+ import time
24
+ from dataclasses import dataclass
25
+ from pathlib import Path
26
+ from typing import Any, Protocol, runtime_checkable
27
+
28
+ from fuzzybits_server.config import server_engine
29
+ from fuzzybits_server.native import compile_pcfb_to_cache, watch_names_from_options
30
+
31
+ from .tally import NodeCounters, PassObservation
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class SampleShape:
36
+ """Device sampling geometry for a run."""
37
+
38
+ batch_size: int
39
+ bitpacks_per_batch: int
40
+ bits_per_bitpack: int
41
+ trials_per_pass: int
42
+ total_iterations: int
43
+
44
+ @classmethod
45
+ def from_native(cls, shape: dict[str, Any]) -> "SampleShape":
46
+ bits_per_bitpack = int(shape.get("bits_per_bitpack", 64))
47
+ batch_size = int(shape.get("batch_size", 0))
48
+ bitpacks_per_batch = int(shape.get("bitpacks_per_batch", 0))
49
+ trials_per_pass = int(
50
+ shape.get("trials_per_pass", batch_size * bitpacks_per_batch * bits_per_bitpack)
51
+ )
52
+ return cls(
53
+ batch_size=batch_size,
54
+ bitpacks_per_batch=bitpacks_per_batch,
55
+ bits_per_bitpack=bits_per_bitpack,
56
+ trials_per_pass=trials_per_pass,
57
+ total_iterations=int(shape.get("total_iterations", 0)),
58
+ )
59
+
60
+
61
+ # Convergence is decided host-side (see :mod:`.runner`/:mod:`.policies`), so these
62
+ # keys are consumed by the Python engine and must NOT be forwarded to the native
63
+ # compiler -- which validates them against its own (wald|bayes) ci-policy set and
64
+ # would reject host-only values such as "gbas".
65
+ _HOST_ONLY_OPTION_KEYS: frozenset[str] = frozenset(
66
+ {
67
+ "policy",
68
+ "P",
69
+ "early_stop",
70
+ "max_passes",
71
+ "emit_min_interval_s",
72
+ "stream_nodes",
73
+ "convergence_event_ids",
74
+ "watch",
75
+ "watch_nodes",
76
+ "watch_mode",
77
+ "pcfb_path",
78
+ "pcfb_id",
79
+ }
80
+ )
81
+
82
+
83
+ def _native_options(options: dict[str, Any] | None) -> dict[str, Any]:
84
+ """Strip host-only convergence keys before handing options to ``run_compile``."""
85
+ if not options:
86
+ return {}
87
+ return {key: value for key, value in options.items() if key not in _HOST_ONLY_OPTION_KEYS}
88
+
89
+
90
+ @runtime_checkable
91
+ class Sampler(Protocol):
92
+ """Produces raw cumulative tally counters one device pass at a time."""
93
+
94
+ @property
95
+ def shape(self) -> SampleShape: ...
96
+
97
+ @property
98
+ def target_index(self) -> int: ...
99
+
100
+ @property
101
+ def node_indices(self) -> list[int]: ...
102
+
103
+ def step(self) -> PassObservation:
104
+ """Run exactly one pass and return cumulative counters for tracked nodes."""
105
+ ...
106
+
107
+ def close(self) -> None:
108
+ """Release any underlying native resources."""
109
+ ...
110
+
111
+
112
+ def _watch_event_ids(pdag: Any, options: dict[str, Any] | None, event_ids: list[int] | None) -> list[int]:
113
+ ids = list(event_ids or [])
114
+ names = watch_names_from_options(options)
115
+ if not names:
116
+ return ids
117
+ graph = pdag.to_graph()
118
+ for want in names:
119
+ found: int | None = None
120
+ for node in graph.get("nodes") or []:
121
+ index = int(node["index"])
122
+ if want == str(index) or want in {
123
+ str(node.get("id") or ""),
124
+ str(node.get("name") or ""),
125
+ str(node.get("full_path") or ""),
126
+ }:
127
+ found = index
128
+ break
129
+ if found is None:
130
+ raise ValueError(f"watched node not in compiled PDAG: {want}")
131
+ if found not in ids:
132
+ ids.append(found)
133
+ return ids
134
+
135
+
136
+ class NativeSampler:
137
+ """Adapts the ``fuzzybits`` layer manager to the :class:`Sampler` protocol."""
138
+
139
+ def __init__(
140
+ self,
141
+ input_files: list[str],
142
+ options: dict[str, Any] | None = None,
143
+ *,
144
+ event_ids: list[int] | None = None,
145
+ ) -> None:
146
+ import fuzzybits # imported lazily so the engine imports without the ext
147
+
148
+ self._pdag = fuzzybits.native().run_compile(input_files, _native_options(options))
149
+ requested = list(event_ids or [])
150
+ extra = _watch_event_ids(self._pdag, options, [])
151
+ if requested or extra:
152
+ root = int(self._pdag.to_graph()["top"])
153
+ base = requested if requested else [root]
154
+ tally_ids: list[int] | None = list(dict.fromkeys(base + extra))
155
+ else:
156
+ tally_ids = None
157
+ self._manager = self._pdag.create_layer_manager(tally_ids)
158
+ self._shape = SampleShape.from_native(dict(self._manager.sample_shape))
159
+ self._target_index = int(requested[0]) if requested else int(self._manager.root_index)
160
+ self._node_indices = sorted(int(i) for i in self._manager.tally_indices)
161
+ # Detect the multi-node fast path once.
162
+ self._has_pass_all = hasattr(self._manager, "single_pass_all")
163
+ self._pass_index = 0
164
+
165
+ @property
166
+ def shape(self) -> SampleShape:
167
+ return self._shape
168
+
169
+ @property
170
+ def target_index(self) -> int:
171
+ return self._target_index
172
+
173
+ @property
174
+ def node_indices(self) -> list[int]:
175
+ return list(self._node_indices)
176
+
177
+ def step(self) -> PassObservation:
178
+ self._pass_index += 1
179
+ if self._has_pass_all:
180
+ raw = self._manager.single_pass_all()
181
+ nodes = {
182
+ int(index): NodeCounters(
183
+ index=int(index),
184
+ num_one_bits=int(counter["num_one_bits"]),
185
+ total_bits=int(counter["total_bits"]),
186
+ )
187
+ for index, counter in raw.items()
188
+ }
189
+ else:
190
+ counter = self._manager.single_pass(self._target_index)
191
+ nodes = {
192
+ self._target_index: NodeCounters(
193
+ index=self._target_index,
194
+ num_one_bits=int(counter["num_one_bits"]),
195
+ total_bits=int(counter["total_bits"]),
196
+ )
197
+ }
198
+ return PassObservation(
199
+ pass_index=self._pass_index,
200
+ wall_time=time.monotonic(),
201
+ trials_per_pass=self._shape.trials_per_pass,
202
+ target_index=self._target_index,
203
+ nodes=nodes,
204
+ )
205
+
206
+ def close(self) -> None:
207
+ # The native layer manager keeps the compiled PDAG alive via keep_alive;
208
+ # dropping our references lets the extension free device memory.
209
+ self._manager = None
210
+ self._pdag = None
211
+
212
+
213
+ class BernoulliSampler:
214
+ """Pure-Python binomial sampler for testing the engine without a device.
215
+
216
+ Draws ``trials_per_pass`` Bernoulli(p) outcomes per pass per node and
217
+ accumulates them, mimicking the native engine's cumulative counters. Use a
218
+ fixed ``seed`` for deterministic tests.
219
+ """
220
+
221
+ def __init__(
222
+ self,
223
+ *,
224
+ true_p: float | dict[int, float] = 0.1,
225
+ trials_per_pass: int = 1 << 16,
226
+ target_index: int = 1,
227
+ seed: int | None = 1234,
228
+ pass_delay_s: float = 0.0,
229
+ ) -> None:
230
+ if isinstance(true_p, dict):
231
+ self._true_p = dict(true_p)
232
+ if target_index not in self._true_p:
233
+ self._true_p[target_index] = next(iter(true_p.values()))
234
+ else:
235
+ self._true_p = {target_index: float(true_p)}
236
+ self._target_index = target_index
237
+ self._trials_per_pass = int(trials_per_pass)
238
+ self._rng = random.Random(seed)
239
+ self._pass_delay_s = pass_delay_s
240
+ self._pass_index = 0
241
+ self._counts: dict[int, int] = {idx: 0 for idx in self._true_p}
242
+ self._totals: dict[int, int] = {idx: 0 for idx in self._true_p}
243
+ self._shape = SampleShape(
244
+ batch_size=1,
245
+ bitpacks_per_batch=max(1, self._trials_per_pass // 64),
246
+ bits_per_bitpack=64,
247
+ trials_per_pass=self._trials_per_pass,
248
+ total_iterations=0,
249
+ )
250
+
251
+ @property
252
+ def shape(self) -> SampleShape:
253
+ return self._shape
254
+
255
+ @property
256
+ def target_index(self) -> int:
257
+ return self._target_index
258
+
259
+ @property
260
+ def node_indices(self) -> list[int]:
261
+ return sorted(self._true_p)
262
+
263
+ def step(self) -> PassObservation:
264
+ self._pass_index += 1
265
+ nodes: dict[int, NodeCounters] = {}
266
+ for index, p in self._true_p.items():
267
+ successes = self._binomial(self._trials_per_pass, p)
268
+ self._counts[index] += successes
269
+ self._totals[index] += self._trials_per_pass
270
+ nodes[index] = NodeCounters(
271
+ index=index,
272
+ num_one_bits=self._counts[index],
273
+ total_bits=self._totals[index],
274
+ )
275
+ if self._pass_delay_s:
276
+ time.sleep(self._pass_delay_s)
277
+ return PassObservation(
278
+ pass_index=self._pass_index,
279
+ wall_time=time.monotonic(),
280
+ trials_per_pass=self._trials_per_pass,
281
+ target_index=self._target_index,
282
+ nodes=nodes,
283
+ )
284
+
285
+ def _binomial(self, n: int, p: float) -> int:
286
+ if p <= 0.0:
287
+ return 0
288
+ if p >= 1.0:
289
+ return n
290
+ # Exact for the trial counts used in tests; inverse-transform per trial is
291
+ # too slow for 65k trials, so use the normal approximation with a small-n
292
+ # exact fallback. Tests assert on aggregate convergence, not exact draws.
293
+ if n <= 2048:
294
+ return sum(1 for _ in range(n) if self._rng.random() < p)
295
+ mean = n * p
296
+ std = (n * p * (1.0 - p)) ** 0.5
297
+ draw = round(self._rng.gauss(mean, std))
298
+ return max(0, min(n, draw))
299
+
300
+ def close(self) -> None: # noqa: D401 - protocol completeness
301
+ return None
302
+
303
+
304
+ class PcfbSampler:
305
+ """Adapts ``fuzzybits.Session`` (``.pcfb`` runtime) to the :class:`Sampler` protocol."""
306
+
307
+ def __init__(
308
+ self,
309
+ pcfb: bytes,
310
+ options: dict[str, Any] | None = None,
311
+ *,
312
+ event_ids: list[int] | None = None,
313
+ ) -> None:
314
+ import fuzzybits
315
+
316
+ names = watch_names_from_options(options)
317
+ if event_ids:
318
+ names = names + [str(int(i)) for i in event_ids]
319
+ tpp = options.get("requested_trials_per_pass") if options else None
320
+ trials = options.get("num_trials") if options else None
321
+ self._session = fuzzybits.Session(
322
+ pcfb,
323
+ backend="auto",
324
+ trials_per_pass=int(float(tpp)) if tpp else None,
325
+ watch=names,
326
+ num_trials=int(float(trials)) if trials else None,
327
+ )
328
+ self._shape = SampleShape.from_native(self._session.sample_shape)
329
+ graph = self._session.graph()
330
+ queries = list(graph.get("query_nodes") or [])
331
+ self._target_index = int(queries[0]["index"]) if queries else int(graph.get("top") or 0)
332
+ if event_ids:
333
+ self._target_index = int(event_ids[0])
334
+ indices: set[int] = {int(q["index"]) for q in queries if "index" in q}
335
+ if event_ids:
336
+ indices.update(int(i) for i in event_ids)
337
+ for want in names:
338
+ for node in graph.get("nodes") or []:
339
+ index = int(node["index"])
340
+ if want == str(index) or want in {
341
+ str(node.get("id") or ""),
342
+ str(node.get("name") or ""),
343
+ str(node.get("full_path") or ""),
344
+ }:
345
+ indices.add(index)
346
+ break
347
+ self._node_indices = sorted(indices)
348
+ self._pass_index = 0
349
+
350
+ @property
351
+ def shape(self) -> SampleShape:
352
+ return self._shape
353
+
354
+ @property
355
+ def target_index(self) -> int:
356
+ return self._target_index
357
+
358
+ @property
359
+ def node_indices(self) -> list[int]:
360
+ return list(self._node_indices)
361
+
362
+ def step(self) -> PassObservation:
363
+ obs = self._session.step()
364
+ self._pass_index = int(obs.pass_index)
365
+ if not self._node_indices:
366
+ self._node_indices = sorted(int(i) for i in obs.nodes)
367
+ nodes = {
368
+ int(index): NodeCounters(
369
+ index=int(index),
370
+ num_one_bits=int(tally.num_one_bits),
371
+ total_bits=int(tally.total_bits),
372
+ )
373
+ for index, tally in obs.nodes.items()
374
+ }
375
+ return PassObservation(
376
+ pass_index=self._pass_index,
377
+ wall_time=time.monotonic(),
378
+ trials_per_pass=self._shape.trials_per_pass,
379
+ target_index=self._target_index,
380
+ nodes=nodes,
381
+ )
382
+
383
+ def close(self) -> None:
384
+ session = self._session
385
+ self._session = None
386
+ if session is not None:
387
+ session.close()
388
+
389
+
390
+ def make_sampler(
391
+ input_files: list[str],
392
+ options: dict[str, Any] | None = None,
393
+ *,
394
+ event_ids: list[int] | None = None,
395
+ pcfb: bytes | None = None,
396
+ pcfb_path: str | None = None,
397
+ ) -> Sampler:
398
+ """Construct the engine sampler. Default is the ``.pcfb`` Session path."""
399
+ if pcfb is None and pcfb_path:
400
+ pcfb = Path(pcfb_path).read_bytes()
401
+ engine = server_engine()
402
+ if engine == "legacy" and pcfb is None:
403
+ return NativeSampler(input_files, options, event_ids=event_ids)
404
+ if pcfb is None:
405
+ pcfb = compile_pcfb_to_cache(input_files, options)
406
+ return PcfbSampler(pcfb, options, event_ids=event_ids)
407
+
408
+
409
+ __all__ = ["SampleShape", "Sampler", "NativeSampler", "BernoulliSampler", "PcfbSampler", "make_sampler"]
@@ -0,0 +1,280 @@
1
+ """Special functions for host-side Monte-Carlo convergence statistics.
2
+
3
+ This module is a small, dependency-free (stdlib ``math`` only) port of the
4
+ numerical helpers that previously lived in the native C++ engine
5
+ (``mc/stats/ci_utils.h``, ``mc/stats/info_gain.h``, ``mc/stats/diagnostics.h``)
6
+ and the TypeScript client (``lib/liveConvergenceStats.ts``). Keeping these in
7
+ one audited place lets the policies/metrics layers stay terse and lets us unit
8
+ test the numerics in isolation.
9
+
10
+ All functions are pure and operate on Python floats. Accuracy targets:
11
+
12
+ * ``normal_quantile_two_sided`` — Acklam (2003) rational approximation, max abs
13
+ error ~5e-16 over (0, 1); identical coefficients to the C++/TS implementations
14
+ so the three stacks agree to round-off.
15
+ * ``regularized_incomplete_beta`` — Lentz continued fraction (Numerical
16
+ Recipes ``betacf``), relative error ~1e-15.
17
+ * ``beta_quantile`` — bisection on the regularized incomplete beta; converges to
18
+ full double precision in <=128 iterations.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import math
24
+
25
+ # Guard used throughout to keep p strictly inside (0, 1) and avoid log/÷0 blowups.
26
+ DELTA_EPSILON: float = 1.0e-12
27
+
28
+ LN2: float = math.log(2.0)
29
+ LN10: float = math.log(10.0)
30
+ SQRT2: float = math.sqrt(2.0)
31
+
32
+ # Backwards-compatible private aliases.
33
+ _LN2 = LN2
34
+ _LN10 = LN10
35
+ _SQRT2 = SQRT2
36
+
37
+
38
+ def clamp(value: float, low: float, high: float) -> float:
39
+ """Clamp ``value`` into the closed interval ``[low, high]``."""
40
+ return min(high, max(low, value))
41
+
42
+
43
+ # ---------------------------------------------------------------------------
44
+ # Gaussian helpers
45
+ # ---------------------------------------------------------------------------
46
+ def normal_cdf(x: float) -> float:
47
+ r"""Standard-normal CDF :math:`\Phi(x) = \tfrac12 \operatorname{erfc}(-x/\sqrt2)`."""
48
+ return 0.5 * math.erfc(-x / _SQRT2)
49
+
50
+
51
+ def two_sided_p_value(z: float) -> float:
52
+ r"""Two-sided p-value :math:`P(|Z| \ge |z|) = \operatorname{erfc}(|z|/\sqrt2)`."""
53
+ return math.erfc(abs(z) / _SQRT2)
54
+
55
+
56
+ # Acklam (2003) inverse-normal-CDF rational approximation coefficients.
57
+ _ACKLAM_A = (
58
+ -3.969683028665376e+01,
59
+ 2.209460984245205e+02,
60
+ -2.759285104469687e+02,
61
+ 1.383577518672690e+02,
62
+ -3.066479806614716e+01,
63
+ 2.506628277459239e+00,
64
+ )
65
+ _ACKLAM_B = (
66
+ -5.447609879822406e+01,
67
+ 1.615858368580409e+02,
68
+ -1.556989798598866e+02,
69
+ 6.680131188771972e+01,
70
+ -1.328068155288572e+01,
71
+ )
72
+ _ACKLAM_C = (
73
+ -7.784894002430293e-03,
74
+ -3.223964580411365e-01,
75
+ -2.400758277161838e+00,
76
+ -2.549732539343734e+00,
77
+ 4.374664141464968e+00,
78
+ 2.938163982698783e+00,
79
+ )
80
+ _ACKLAM_D = (
81
+ 7.784695709041462e-03,
82
+ 3.224671290700398e-01,
83
+ 2.445134137142996e+00,
84
+ 3.754408661907416e+00,
85
+ )
86
+
87
+
88
+ def normal_quantile_two_sided(confidence: float) -> float:
89
+ r"""Two-sided normal quantile :math:`z = \Phi^{-1}(1 - \alpha/2)`.
90
+
91
+ Given a two-sided confidence level ``confidence`` in (0, 1) returns the
92
+ ``z`` such that ``P(|Z| <= z) = confidence`` for ``Z ~ N(0, 1)``.
93
+ """
94
+ p = clamp(confidence, DELTA_EPSILON, 1.0 - DELTA_EPSILON)
95
+ alpha = 1.0 - p
96
+ q = 1.0 - alpha / 2.0
97
+
98
+ plow = 0.02425
99
+ phigh = 1.0 - plow
100
+ a, b, c, d = _ACKLAM_A, _ACKLAM_B, _ACKLAM_C, _ACKLAM_D
101
+
102
+ if q < plow:
103
+ u = math.sqrt(-2.0 * math.log(q))
104
+ return (((((c[0] * u + c[1]) * u + c[2]) * u + c[3]) * u + c[4]) * u + c[5]) / (
105
+ (((d[0] * u + d[1]) * u + d[2]) * u + d[3]) * u + 1.0
106
+ )
107
+ if q > phigh:
108
+ u = math.sqrt(-2.0 * math.log(1.0 - q))
109
+ return -(((((c[0] * u + c[1]) * u + c[2]) * u + c[3]) * u + c[4]) * u + c[5]) / (
110
+ (((d[0] * u + d[1]) * u + d[2]) * u + d[3]) * u + 1.0
111
+ )
112
+ u = q - 0.5
113
+ t = u * u
114
+ return (((((a[0] * t + a[1]) * t + a[2]) * t + a[3]) * t + a[4]) * t + a[5]) * u / (
115
+ ((((b[0] * t + b[1]) * t + b[2]) * t + b[3]) * t + b[4]) * t + 1.0
116
+ )
117
+
118
+
119
+ def confidence_from_alpha(alpha: float) -> float:
120
+ """Convert a two-sided significance ``alpha`` to a confidence level."""
121
+ clamped = clamp(alpha, DELTA_EPSILON, 1.0 - DELTA_EPSILON) if math.isfinite(alpha) else 0.01
122
+ return 1.0 - clamped
123
+
124
+
125
+ # ---------------------------------------------------------------------------
126
+ # Beta / digamma helpers (Bayesian policy + information gain)
127
+ # ---------------------------------------------------------------------------
128
+ def digamma(x: float) -> float:
129
+ r"""Digamma function :math:`\psi(x)` for ``x > 0`` (recurrence + asymptotic)."""
130
+ value = x
131
+ result = 0.0
132
+ while value < 8.0:
133
+ result -= 1.0 / value
134
+ value += 1.0
135
+ inv = 1.0 / value
136
+ inv2 = inv * inv
137
+ return (
138
+ result
139
+ + math.log(value)
140
+ - 0.5 * inv
141
+ - inv2 * (1.0 / 12.0 - inv2 * (1.0 / 120.0 - inv2 * (1.0 / 252.0 - inv2 / 240.0)))
142
+ )
143
+
144
+
145
+ def log_beta(a: float, b: float) -> float:
146
+ r"""Natural log of the Beta function :math:`\ln B(a, b)`."""
147
+ return math.lgamma(a) + math.lgamma(b) - math.lgamma(a + b)
148
+
149
+
150
+ def beta_entropy_bits(alpha: float, beta: float) -> float:
151
+ r"""Shannon entropy of ``Beta(alpha, beta)`` in bits (``alpha, beta > 0``)."""
152
+ nats = (
153
+ log_beta(alpha, beta)
154
+ - (alpha - 1.0) * digamma(alpha)
155
+ - (beta - 1.0) * digamma(beta)
156
+ + (alpha + beta - 2.0) * digamma(alpha + beta)
157
+ )
158
+ return nats / _LN2
159
+
160
+
161
+ def information_gain_bits(
162
+ alpha_prev: float, beta_prev: float, alpha_new: float, beta_new: float
163
+ ) -> float:
164
+ """Entropy reduction (bits) moving from ``Beta(prev)`` to ``Beta(new)``."""
165
+ return beta_entropy_bits(alpha_prev, beta_prev) - beta_entropy_bits(alpha_new, beta_new)
166
+
167
+
168
+ def _beta_continued_fraction(a: float, b: float, x: float, *, max_iter: int = 300) -> float:
169
+ """Lentz's continued fraction for the regularized incomplete beta (``betacf``)."""
170
+ tiny = 1.0e-300
171
+ eps = 3.0e-16
172
+ qab = a + b
173
+ qap = a + 1.0
174
+ qam = a - 1.0
175
+ c = 1.0
176
+ d = 1.0 - qab * x / qap
177
+ if abs(d) < tiny:
178
+ d = tiny
179
+ d = 1.0 / d
180
+ h = d
181
+ for m in range(1, max_iter + 1):
182
+ m2 = 2 * m
183
+ aa = m * (b - m) * x / ((qam + m2) * (a + m2))
184
+ d = 1.0 + aa * d
185
+ if abs(d) < tiny:
186
+ d = tiny
187
+ c = 1.0 + aa / c
188
+ if abs(c) < tiny:
189
+ c = tiny
190
+ d = 1.0 / d
191
+ h *= d * c
192
+ aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2))
193
+ d = 1.0 + aa * d
194
+ if abs(d) < tiny:
195
+ d = tiny
196
+ c = 1.0 + aa / c
197
+ if abs(c) < tiny:
198
+ c = tiny
199
+ d = 1.0 / d
200
+ delta = d * c
201
+ h *= delta
202
+ if abs(delta - 1.0) < eps:
203
+ break
204
+ return h
205
+
206
+
207
+ def regularized_incomplete_beta(x: float, a: float, b: float) -> float:
208
+ r"""Regularized incomplete beta :math:`I_x(a, b)` (the ``Beta(a,b)`` CDF)."""
209
+ if x <= 0.0:
210
+ return 0.0
211
+ if x >= 1.0:
212
+ return 1.0
213
+ front = math.exp(log_beta(a, b) * -1.0 + a * math.log(x) + b * math.log1p(-x))
214
+ if x < (a + 1.0) / (a + b + 2.0):
215
+ return front * _beta_continued_fraction(a, b, x) / a
216
+ return 1.0 - front * _beta_continued_fraction(b, a, 1.0 - x) / b
217
+
218
+
219
+ def beta_quantile(q: float, a: float, b: float, *, iterations: int = 128) -> float:
220
+ r"""Inverse Beta CDF (percent-point function) via bisection on :math:`I_x(a,b)`.
221
+
222
+ Robust and monotone; ``iterations`` halvings reach full double precision.
223
+ """
224
+ if q <= 0.0:
225
+ return 0.0
226
+ if q >= 1.0:
227
+ return 1.0
228
+ low = 0.0
229
+ high = 1.0
230
+ for _ in range(iterations):
231
+ mid = 0.5 * (low + high)
232
+ if regularized_incomplete_beta(mid, a, b) < q:
233
+ low = mid
234
+ else:
235
+ high = mid
236
+ return 0.5 * (low + high)
237
+
238
+
239
+ # ---------------------------------------------------------------------------
240
+ # Bernoulli sampling-theory formulas (shared by policies and metrics)
241
+ # ---------------------------------------------------------------------------
242
+ def required_trials_two_sided(p: float, epsilon: float, z: float) -> int:
243
+ r"""Wald sample size :math:`N \ge z^2 p(1-p)/\varepsilon^2` (linear scale)."""
244
+ if epsilon <= 0.0:
245
+ return 0
246
+ return math.ceil((z * z * p * (1.0 - p)) / (epsilon * epsilon))
247
+
248
+
249
+ def required_trials_log10_two_sided(p: float, epsilon_log10: float, z: float) -> int:
250
+ r"""Wald sample size for a target half-width on the :math:`\log_{10} p` scale."""
251
+ if p <= 0.0 or epsilon_log10 <= 0.0:
252
+ return 0
253
+ denom = p * epsilon_log10 * epsilon_log10 * _LN10 * _LN10
254
+ return math.ceil(z * z * (1.0 - p) / denom)
255
+
256
+
257
+ def epsilon_from_trials(p: float, n: int, z: float) -> float:
258
+ r"""Achievable half-width :math:`\varepsilon = z\sqrt{p(1-p)/N}` for a fixed budget."""
259
+ if n <= 0:
260
+ return math.inf
261
+ return z * (p * (1.0 - p) / n) ** 0.5
262
+
263
+
264
+ __all__ = [
265
+ "DELTA_EPSILON",
266
+ "clamp",
267
+ "normal_cdf",
268
+ "two_sided_p_value",
269
+ "normal_quantile_two_sided",
270
+ "confidence_from_alpha",
271
+ "digamma",
272
+ "log_beta",
273
+ "beta_entropy_bits",
274
+ "information_gain_bits",
275
+ "regularized_incomplete_beta",
276
+ "beta_quantile",
277
+ "required_trials_two_sided",
278
+ "required_trials_log10_two_sided",
279
+ "epsilon_from_trials",
280
+ ]