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.
- fuzzybits_server/.dockerignore +64 -0
- fuzzybits_server/__init__.py +15 -0
- fuzzybits_server/app.py +93 -0
- fuzzybits_server/config.py +310 -0
- fuzzybits_server/convergence/__init__.py +100 -0
- fuzzybits_server/convergence/gbas.py +229 -0
- fuzzybits_server/convergence/metrics.py +164 -0
- fuzzybits_server/convergence/policies.py +387 -0
- fuzzybits_server/convergence/runner.py +398 -0
- fuzzybits_server/convergence/sampling.py +409 -0
- fuzzybits_server/convergence/special.py +280 -0
- fuzzybits_server/convergence/tally.py +179 -0
- fuzzybits_server/event_hub.py +58 -0
- fuzzybits_server/event_log.py +16 -0
- fuzzybits_server/fault_tree_payload.py +899 -0
- fuzzybits_server/model_oracle_p.json +44 -0
- fuzzybits_server/native.py +536 -0
- fuzzybits_server/routes.py +408 -0
- fuzzybits_server/state.py +67 -0
- fuzzybits_server/supervisor.py +193 -0
- fuzzybits_server/ui.py +84 -0
- fuzzybits_server/webui/.vite/manifest.json +26 -0
- fuzzybits_server/webui/assets/Playground-B6V8NzhX.css +1 -0
- fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js +5481 -0
- fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js.map +1 -0
- fuzzybits_server/webui/assets/index-BnegRRhI.css +1 -0
- fuzzybits_server/webui/assets/index-C3oGCBE0.js +13 -0
- fuzzybits_server/webui/assets/index-C3oGCBE0.js.map +1 -0
- fuzzybits_server/webui/index.html +24 -0
- fuzzybits_server/worker.py +64 -0
- fuzzybits_server-0.17.0.dist-info/METADATA +281 -0
- fuzzybits_server-0.17.0.dist-info/RECORD +34 -0
- fuzzybits_server-0.17.0.dist-info/WHEEL +4 -0
- 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
|
+
]
|