"""Binomial deployment evidence under independent, exchangeable one-shot trials.
Statistical evidence is not certification or a substitute for physics-based
qualification. Repeated cycles on one unit are not independent hardware trials.
"""
from __future__ import annotations
import math
import operator
import pandas as pd
def _count(value: int, name: str) -> int:
if isinstance(value, bool):
raise ValueError(f"{name} must be a nonnegative integer")
try:
result = operator.index(value)
except TypeError as exc:
raise ValueError(f"{name} must be a nonnegative integer") from exc
if result < 0:
raise ValueError(f"{name} must be a nonnegative integer")
return result
def _probability(value: float, name: str) -> None:
if not math.isfinite(value) or not 0 < value < 1:
raise ValueError(f"{name} must lie strictly between zero and one")
def _failure_cdf(n: int, failures: int, reliability: float) -> float:
# Binomial lower tail in log space; only called with 0 < reliability < 1.
terms = [
math.lgamma(n + 1)
- math.lgamma(k + 1)
- math.lgamma(n - k + 1)
+ k * math.log1p(-reliability)
+ (n - k) * math.log(reliability)
for k in range(failures + 1)
]
maximum = max(terms)
return math.exp(maximum) * math.fsum(math.exp(x - maximum) for x in terms)
[docs]
def deployment_reliability_lower_bound(
successes: int, failures: int, *, confidence: float = 0.95
) -> float:
"""Exact one-sided Clopper-Pearson lower bound on per-unit success probability.
Solve P(F <= observed_failures | R=lower) = 1-confidence for n trials.
All-success bound is (1-confidence)**(1/n). All-failure bound is zero.
Confidence describes repeated-sampling coverage, not a posterior probability.
Counts must be independently justified; no pooling across design/protocols.
"""
s, f = _count(successes, "successes"), _count(failures, "failures")
_probability(confidence, "confidence")
n = s + f
if n == 0:
raise ValueError("At least one completed trial is required")
if s == 0:
return 0.0
if f == 0:
return math.exp(math.log1p(-confidence) / n)
low, high = 0.0, 1.0
for _ in range(80):
mid = (low + high) / 2
if _failure_cdf(n, f, mid) < 1 - confidence:
low = mid
else:
high = mid
return (low + high) / 2
[docs]
def zero_failure_sample_size(reliability: float, *, confidence: float = 0.95) -> int:
"""Smallest fixed campaign with zero failures supporting the requested bound.
n = ceil(log(1-confidence)/log(reliability)). This is not a sequential
stopping rule. No number of repetitions proves unmodeled common-cause risks.
"""
_probability(reliability, "reliability")
_probability(confidence, "confidence")
n = math.ceil(math.log1p(-confidence) / math.log(reliability))
# Correct floating-point rounding at exact integer boundaries.
while (
n > 1 and deployment_reliability_lower_bound(n - 1, 0, confidence=confidence) >= reliability
):
n -= 1
while deployment_reliability_lower_bound(n, 0, confidence=confidence) < reliability:
n += 1
return n
[docs]
def summarize_deployment_trials(frame: pd.DataFrame, *, confidence: float = 0.95) -> pd.DataFrame:
"""Screen a one-shot trial registry by design and protocol, without pooling.
Columns: unit_id, design_id, protocol_id (nonempty strings), success (0/1).
Duplicate unit IDs within a design/protocol fail even if outcomes agree.
Unique IDs cannot establish physical independence: the caller must establish
representative hardware, comparable stress exposure and absence of shared
failure causes. Incomplete/censored records must not be encoded as successes.
"""
required = {"unit_id", "design_id", "protocol_id", "success"}
_probability(confidence, "confidence")
if not required.issubset(frame.columns) or frame.empty:
raise ValueError("Provide a nonempty registry with unit/design/protocol/success columns")
ids = ["design_id", "protocol_id", "unit_id"]
for column in ids:
if not frame[column].map(lambda x: isinstance(x, str) and bool(x.strip())).all():
raise ValueError("Identifiers must be nonempty strings")
if frame.duplicated(ids).any():
raise ValueError("Repeated hardware within a protocol cannot count as independent trials")
if not frame.success.isin([0, 1]).all():
raise ValueError("success must contain only completed binary outcomes 0/1")
rows = []
for _, group in frame.groupby(["design_id", "protocol_id"], sort=True):
design = str(group["design_id"].iloc[0])
protocol = str(group["protocol_id"].iloc[0])
successes = int(group.success.sum())
failures = len(group) - successes
rows.append(
{
"design_id": design,
"protocol_id": protocol,
"units": len(group),
"successes": successes,
"failures": failures,
"confidence": confidence,
"reliability_lower": deployment_reliability_lower_bound(
successes, failures, confidence=confidence
),
}
)
return pd.DataFrame(rows)