dadl-quantum 0.0.2__tar.gz

dadl_quantum-0.0.2/.gitignore

@@ -0,0 +1,36 @@
+# Rust
+/target/
+**/target/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Data: raw time tags and replay files are never committed
+*.h5
+*.hdf5
+*.ptu
+*.ttbin
+data/
+
+# Keys: site signing keys are never committed
+*.key
+*.pem
+keys/
+
+# Docs build
+/site/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

dadl_quantum-0.0.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: dadl-quantum
+Version: 0.0.2
+Summary: Detector-Aware Data Layer for quantum optics experiments
+Project-URL: Homepage, https://github.com/usecommon/dadl
+Project-URL: Documentation, https://github.com/usecommon/dadl/blob/main/docs/design.md
+Project-URL: Issues, https://github.com/usecommon/dadl/issues
+License: MIT OR Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# dadl (Python package)
+
+Detector-Aware Data Layer for quantum optics experiments.
+
+Phase 1 is pure NumPy: a time-tag simulator with injected detector
+imperfections, fixed-grid coincidence counting, CHSH and two-photon
+visibility analyses, the guardrail policy, and the labelled result type.
+
+```bash
+pip install -e ".[test]"
+dadl quickstart chsh-spad
+pytest
+```
+
+See the repository README and `docs/design.md` for the full design.

dadl_quantum-0.0.2/README.md

@@ -0,0 +1,15 @@
+# dadl (Python package)
+
+Detector-Aware Data Layer for quantum optics experiments.
+
+Phase 1 is pure NumPy: a time-tag simulator with injected detector
+imperfections, fixed-grid coincidence counting, CHSH and two-photon
+visibility analyses, the guardrail policy, and the labelled result type.
+
+```bash
+pip install -e ".[test]"
+dadl quickstart chsh-spad
+pytest
+```
+
+See the repository README and `docs/design.md` for the full design.

dadl_quantum-0.0.2/dadl/__init__.py

@@ -0,0 +1,18 @@
+"""DADL: Detector-Aware Data Layer for quantum optics experiments."""
+
+from dadl.errors import ConfigError, DadlError, GuardrailRefusal, InsufficientCounts
+from dadl.guardrails import Policy
+from dadl.result import Estimate, LabelledValue
+
+__version__ = "0.0.2"
+
+__all__ = [
+    "ConfigError",
+    "DadlError",
+    "Estimate",
+    "GuardrailRefusal",
+    "InsufficientCounts",
+    "LabelledValue",
+    "Policy",
+    "__version__",
+]

dadl_quantum-0.0.2/dadl/analysis/__init__.py

@@ -0,0 +1,6 @@
+"""Analyses. Each returns a LabelledValue with the raw value first."""
+
+from dadl.analysis.chsh import Window, chsh
+from dadl.analysis.visibility import two_photon_visibility
+
+__all__ = ["Window", "chsh", "two_photon_visibility"]

dadl_quantum-0.0.2/dadl/analysis/chsh.py

@@ -0,0 +1,69 @@
+"""CHSH from fixed-grid coincidences.
+
+Headline S uses raw counts only. Every coincidence-normalized S is labelled
+"fair sampling assumed", because normalizing by coincidences post-selects on
+detection.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from dadl.coincidences import grid_coincidences
+from dadl.errors import InsufficientCounts
+from dadl.guardrails import Policy
+from dadl.result import Estimate, LabelledValue
+
+FAIR_SAMPLING = "fair sampling assumed (post-selected on coincidences)"
+
+#: Below this many coincidences per setting the Gaussian error is not trusted.
+MIN_COUNTS_PER_SETTING = 100
+
+SIGNS: dict[tuple[str, str], int] = {("a", "b"): 1, ("a", "b'"): -1, ("a'", "b"): 1, ("a'", "b'"): 1}
+
+
+@dataclass(frozen=True)
+class Window:
+    """A coincidence window. `source` must be "plan" for Bell-type analyses."""
+
+    width_ps: int
+    source: str = "plan"
+    delays_ps: dict[str, int] = field(default_factory=dict)
+
+
+def correlator(tags: dict[str, np.ndarray], window: Window) -> tuple[float, float, int]:
+    """E = (N++ + N-- - N+- - N-+) / N and its variance (1 - E^2) / N."""
+    d = window.delays_ps
+
+    def n(a: str, b: str) -> int:
+        return grid_coincidences(tags[a], tags[b], window.width_ps, d.get(a, 0), d.get(b, 0))
+
+    npp, nmm, npm, nmp = n("A+", "B+"), n("A-", "B-"), n("A+", "B-"), n("A-", "B+")
+    total = npp + nmm + npm + nmp
+    if total < MIN_COUNTS_PER_SETTING:
+        raise InsufficientCounts(f"{total} coincidences in a setting; need at least {MIN_COUNTS_PER_SETTING}.")
+    e = (npp + nmm - npm - nmp) / total
+    return e, (1.0 - e * e) / total, total
+
+
+def chsh(
+    runs: dict[tuple[str, str], dict[str, np.ndarray]],
+    window: Window,
+    policy: Policy | None = None,
+) -> LabelledValue:
+    """Raw CHSH S from one run per setting pair, with fixed windows from the analysis plan."""
+    policy = policy or Policy.default()
+    policy.check_window("chsh", window.source)
+    s = 0.0
+    var = 0.0
+    for key, sign in SIGNS.items():
+        if key not in runs:
+            raise ValueError(f"missing run for setting pair {key}")
+        e, v, _ = correlator(runs[key], window)
+        s += sign * e
+        var += v
+    labels = (FAIR_SAMPLING,) + policy.labels_for("chsh")
+    return LabelledValue(analysis="chsh", raw=Estimate(s, math.sqrt(var)), labels=labels)

dadl_quantum-0.0.2/dadl/analysis/visibility.py

@@ -0,0 +1,47 @@
+"""Two-photon fringe visibility, with optional accidental subtraction.
+
+For Bell-type visibility claims (analysis "bell_visibility") accidental
+subtraction is refused: it can move a non-violating dataset past the 71%
+threshold. For HOM it is allowed, as a labelled secondary value.
+"""
+
+from __future__ import annotations
+
+import math
+
+from dadl.guardrails import Policy, threshold_labels
+from dadl.result import Estimate, LabelledValue
+
+
+def _visibility(n_max: float, n_min: float) -> tuple[float, float]:
+    total = n_max + n_min
+    if total <= 0:
+        raise ValueError("counts must be positive")
+    v = (n_max - n_min) / total
+    # Poisson counts: var(V) = 4 n_max n_min / (n_max + n_min)^3
+    return v, math.sqrt(4.0 * n_max * n_min / total**3)
+
+
+def two_photon_visibility(
+    n_max: float,
+    n_min: float,
+    *,
+    analysis: str,
+    accidentals: float | None = None,
+    policy: Policy | None = None,
+) -> LabelledValue:
+    """Raw visibility, and the accidental-subtracted value only where the policy allows it."""
+    policy = policy or Policy.default()
+    raw_v, raw_err = _visibility(n_max, n_min)
+    corrected: Estimate | None = None
+    if accidentals is not None:
+        policy.check_correction(analysis, "accidental_subtraction")
+        denom = n_max + n_min - 2.0 * accidentals
+        if denom <= 0:
+            raise ValueError("accidentals exceed the measured counts")
+        cor_v = (n_max - n_min) / denom
+        corrected = Estimate(cor_v, raw_err * (n_max + n_min) / denom)
+    labels = policy.labels_for(analysis) + threshold_labels(
+        analysis, raw_v, None if corrected is None else corrected.value
+    )
+    return LabelledValue(analysis=analysis, raw=Estimate(raw_v, raw_err), corrected=corrected, labels=labels)

dadl_quantum-0.0.2/dadl/cli.py

@@ -0,0 +1,86 @@
+"""Command-line interface: `dadl quickstart <example>` and `dadl version`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+
+from dadl import __version__
+from dadl.analysis.chsh import Window, chsh
+from dadl.closed_form import chsh_expected_grid
+from dadl.sim import CHANNELS, DetectorParams, PairSource, simulate_chsh
+
+#: Phase 1 keeps the example parameters in code; examples/chsh-spad/setup.yaml mirrors them.
+CHSH_SPAD = {
+    "seed": 2026,
+    "duration_s": 1.0,
+    "pair_rate": 1e5,
+    "visibility": 0.95,
+    "detector": {
+        "efficiency": 0.5,
+        "dark_rate": 500.0,
+        "dead_time_ps": 22_000,
+        "jitter_ps": 350.0,
+        "afterpulse_prob": 0.005,
+        "afterpulse_tau_ps": 50_000.0,
+    },
+    "window_ps": 2_000,
+}
+
+
+def quickstart_chsh_spad() -> int:
+    p = CHSH_SPAD
+    det = DetectorParams(**p["detector"])
+    rng = np.random.default_rng(p["seed"])
+    runs = simulate_chsh(
+        PairSource(pair_rate=p["pair_rate"], visibility=p["visibility"]),
+        {ch: det for ch in CHANNELS},
+        p["duration_s"],
+        rng,
+    )
+    result = chsh(runs, Window(width_ps=p["window_ps"], source="plan"))
+    expected = chsh_expected_grid(
+        pair_rate=p["pair_rate"],
+        duration_s=p["duration_s"],
+        efficiency=det.efficiency,
+        dark_rate=det.dark_rate,
+        jitter_sigma_ps=det.jitter_ps,
+        width_ps=p["window_ps"],
+        visibility=p["visibility"],
+    )
+    print(f"DADL {__version__} quickstart: chsh-spad (simulated data, seed {p['seed']})")
+    print(f"  Source: {p['pair_rate']:.0e} pairs/s, visibility {p['visibility']}, {p['duration_s']} s per setting")
+    print(
+        f"  Detectors: eta {det.efficiency}, dark {det.dark_rate:.0f} cps, dead time {det.dead_time_ps / 1000:.0f} ns, "
+        f"jitter {det.jitter_ps:.0f} ps, afterpulsing {det.afterpulse_prob:.1%}"
+    )
+    print(f"  Fixed window from the analysis plan: {p['window_ps'] / 1000:.1f} ns")
+    print()
+    print(f"  Raw S = {result.raw}")
+    print(f"  Labels: {'; '.join(result.labels)}")
+    print(f"  Closed-form expectation (ignores dead time and afterpulsing): S = {expected:.4f}")
+    print()
+    print("  Next: calibration fits and corrected values arrive in phase 2. See docs/design.md.")
+    return 0
+
+
+EXAMPLES = {"chsh-spad": quickstart_chsh_spad}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dadl", description="Detector-Aware Data Layer for quantum optics experiments")
+    sub = parser.add_subparsers(dest="command", required=True)
+    qs = sub.add_parser("quickstart", help="run an example end to end on simulated data")
+    qs.add_argument("example", choices=sorted(EXAMPLES))
+    sub.add_parser("version", help="print the version")
+    args = parser.parse_args(argv)
+    if args.command == "version":
+        print(__version__)
+        return 0
+    return EXAMPLES[args.example]()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dadl_quantum-0.0.2/dadl/closed_form.py

@@ -0,0 +1,72 @@
+"""Closed-form results used as model-independent test oracles."""
+
+from __future__ import annotations
+
+import math
+
+
+def nonparalyzable_measured_rate(true_rate: float, tau_s: float) -> float:
+    """m = n / (1 + n tau)."""
+    return true_rate / (1.0 + true_rate * tau_s)
+
+
+def paralyzable_measured_rate(true_rate: float, tau_s: float) -> float:
+    """m = n exp(-n tau)."""
+    return true_rate * math.exp(-true_rate * tau_s)
+
+
+def series_hybrid_measured_rate(true_rate: float, tau_p_s: float, tau_np_s: float) -> float:
+    """m = n exp(-n tau_p) / (1 + n tau_np)."""
+    return true_rate * math.exp(-true_rate * tau_p_s) / (1.0 + true_rate * tau_np_s)
+
+
+def chsh_werner(visibility: float) -> float:
+    """S = 2 sqrt(2) V for a Werner-like Phi+ state at the optimal settings."""
+    return 2.0 * math.sqrt(2.0) * visibility
+
+
+def chsh_with_accidentals(visibility: float, true_coinc: float, accidentals: float) -> float:
+    """Uniform accidentals scale every correlator, so S = 2 sqrt(2) V C / (C + A)."""
+    return chsh_werner(visibility) * true_coinc / (true_coinc + accidentals)
+
+
+def grid_capture_probability(jitter_sigma_ps: float, width_ps: float) -> float:
+    """Probability that both photons of a pair land in the same fixed slot.
+
+    Each arm has independent Gaussian jitter of sigma `jitter_sigma_ps`, the
+    declared delays are exact, and the pair time is uniform within a slot.
+    With D the arrival difference (sigma s = sigma * sqrt(2)) and w the width,
+    P = E[(1 - |D| / w)+] = erf(u / sqrt 2) - (2 s / (w sqrt(2 pi))) (1 - exp(-u^2 / 2)), u = w / s.
+    """
+    if width_ps <= 0:
+        raise ValueError("width must be positive")
+    s = jitter_sigma_ps * math.sqrt(2.0)
+    if s == 0:
+        return 1.0
+    u = width_ps / s
+    return math.erf(u / math.sqrt(2.0)) - (2.0 * s / (width_ps * math.sqrt(2.0 * math.pi))) * (
+        1.0 - math.exp(-0.5 * u * u)
+    )
+
+
+def chsh_expected_grid(
+    *,
+    pair_rate: float,
+    duration_s: float,
+    efficiency: float,
+    dark_rate: float,
+    jitter_sigma_ps: float,
+    width_ps: float,
+    visibility: float,
+) -> float:
+    """Expected raw S for the simulator with identical detectors, no dead time or afterpulsing.
+
+    True coincidences per setting: C = N T eta^2 P_capture (summed over the four
+    outcome combinations). Accidentals per combination: r^2 w T with singles
+    rate r = N eta / 2 + d; uniform across combinations, so they add nothing to
+    the correlator numerator.
+    """
+    c = pair_rate * duration_s * efficiency**2 * grid_capture_probability(jitter_sigma_ps, width_ps)
+    r = pair_rate * efficiency / 2.0 + dark_rate
+    a = 4.0 * r * r * (width_ps * 1e-12) * duration_s
+    return chsh_with_accidentals(visibility, c, a)

dadl_quantum-0.0.2/dadl/coincidences.py

@@ -0,0 +1,32 @@
+"""Fixed-grid (clock-locked) coincidence counting.
+
+Time is cut into slots of a width declared before the data is seen. A
+coincidence is a slot occupied by both channels after each channel's declared
+delay is removed. This is the only coincidence method allowed for Bell-type
+analyses: windows centred on detection events open the coincidence-time
+loophole.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def occupied_slots(times: np.ndarray, width_ps: int, delay_ps: int = 0) -> np.ndarray:
+    if width_ps <= 0:
+        raise ValueError("slot width must be positive")
+    times = np.asarray(times, dtype=np.int64)
+    return np.unique(np.floor_divide(times - np.int64(delay_ps), np.int64(width_ps)))
+
+
+def grid_coincidences(
+    a: np.ndarray,
+    b: np.ndarray,
+    width_ps: int,
+    delay_a_ps: int = 0,
+    delay_b_ps: int = 0,
+) -> int:
+    """Number of slots occupied by both channels."""
+    slots_a = occupied_slots(a, width_ps, delay_a_ps)
+    slots_b = occupied_slots(b, width_ps, delay_b_ps)
+    return int(np.intersect1d(slots_a, slots_b, assume_unique=True).size)

dadl_quantum-0.0.2/dadl/config.py

@@ -0,0 +1,42 @@
+"""Loading setup.yaml files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from dadl.errors import ConfigError
+
+SUPPORTED_SCHEMA_VERSIONS = {1}
+REQUIRED_KEYS = ("schema_version", "name", "source", "detectors", "analysis")
+
+
+def load_setup(path: str | Path) -> dict[str, Any]:
+    """Load and minimally validate a setup file.
+
+    Full JSON Schema validation (dadl check-config) and migrations
+    (dadl migrate) arrive in a later phase.
+    """
+    path = Path(path)
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigError(f"setup file not found: {path}") from exc
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"setup file is not valid YAML: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError("setup file must be a mapping at the top level")
+    missing = [k for k in REQUIRED_KEYS if k not in data]
+    if missing:
+        raise ConfigError(f"setup file is missing keys: {', '.join(missing)}")
+    if data["schema_version"] not in SUPPORTED_SCHEMA_VERSIONS:
+        raise ConfigError(
+            f"schema_version {data['schema_version']!r} is not supported; "
+            f"supported: {sorted(SUPPORTED_SCHEMA_VERSIONS)}"
+        )
+    window = data["analysis"].get("window", {})
+    if window.get("source") != "plan":
+        raise ConfigError("analysis.window.source must be 'plan': windows are declared before acquisition")
+    return data

dadl_quantum-0.0.2/dadl/deadtime.py

@@ -0,0 +1,38 @@
+"""Dead-time filters (pure-Python reference; the Rust core has the fast versions).
+
+Timestamps are int64 picoseconds, sorted ascending.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def apply_nonparalyzable(times: np.ndarray, tau_ps: int) -> np.ndarray:
+    """Drop arrivals within `tau_ps` of the last recorded event."""
+    if tau_ps < 0:
+        raise ValueError("dead time must be non-negative")
+    times = np.asarray(times, dtype=np.int64)
+    if tau_ps == 0 or times.size == 0:
+        return times.copy()
+    out = np.empty_like(times)
+    n = 0
+    next_allowed: int | None = None
+    for t in times.tolist():
+        if next_allowed is None or t >= next_allowed:
+            out[n] = t
+            n += 1
+            next_allowed = t + tau_ps
+    return out[:n]
+
+
+def apply_paralyzable(times: np.ndarray, tau_ps: int) -> np.ndarray:
+    """Record an arrival only if the previous arrival (recorded or not) is at least `tau_ps` earlier."""
+    if tau_ps < 0:
+        raise ValueError("dead time must be non-negative")
+    times = np.asarray(times, dtype=np.int64)
+    if times.size == 0:
+        return times.copy()
+    gaps = np.diff(times)
+    keep = np.concatenate(([True], gaps >= tau_ps))
+    return times[keep]

dadl_quantum-0.0.2/dadl/errors.py

@@ -0,0 +1,17 @@
+"""Typed errors. The same types are raised by the library and, later, over MCP."""
+
+
+class DadlError(Exception):
+    """Base class for all DADL errors."""
+
+
+class GuardrailRefusal(DadlError):
+    """A correction, window or analysis choice is invalid for the analysis type."""
+
+
+class InsufficientCounts(DadlError):
+    """Counts are below the estimator's validity threshold."""
+
+
+class ConfigError(DadlError):
+    """A setup or policy file is missing, malformed or of an unsupported version."""

dadl_quantum-0.0.2/dadl/guardrails.py

@@ -0,0 +1,155 @@
+"""Guardrail policy.
+
+Guardrails are refusals in code, not warnings. Each analysis type declares
+which corrections may appear (always as a labelled secondary value, never as
+the headline) and where its coincidence window may come from.
+
+Users may loosen a rule, but never silently: an override needs a written
+reason, and any policy whose content differs from the shipped default is
+labelled "policy modified" on every result. In later phases an override also
+needs a human approval token, and agents cannot write policy files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass, field
+
+from dadl.errors import GuardrailRefusal
+
+POLICY_MODIFIED = "policy modified"
+THRESHOLD_AFTER_CORRECTION = "threshold crossed only after correction"
+UNVALIDATED_ANALYSIS = "unvalidated analysis"
+
+#: Thresholds that carry a physical claim, per analysis type.
+THRESHOLDS: dict[str, float] = {
+    "chsh": 2.0,
+    "bell_visibility": 1.0 / math.sqrt(2.0),
+    "hom_visibility": 0.5,
+}
+
+
+@dataclass(frozen=True)
+class AnalysisRule:
+    allowed_corrections: frozenset[str]
+    window_sources: frozenset[str]
+
+    def to_json(self) -> dict[str, list[str]]:
+        return {
+            "allowed_corrections": sorted(self.allowed_corrections),
+            "window_sources": sorted(self.window_sources),
+        }
+
+
+#: Applied to any analysis type the policy does not know, e.g. plugin analyses.
+STRICTEST = AnalysisRule(allowed_corrections=frozenset(), window_sources=frozenset({"plan"}))
+
+DEFAULT_RULES: dict[str, AnalysisRule] = {
+    # Bell-type: raw counts only, fixed windows declared in the analysis plan.
+    "chsh": STRICTEST,
+    "bell_visibility": STRICTEST,
+    # HOM and tomography: corrections allowed as labelled secondary values.
+    "hom_visibility": AnalysisRule(
+        allowed_corrections=frozenset({"accidental_subtraction", "afterpulse"}),
+        window_sources=frozenset({"plan"}),
+    ),
+    "tomography": AnalysisRule(
+        allowed_corrections=frozenset({"accidental_subtraction"}),
+        window_sources=frozenset({"plan"}),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class Override:
+    analysis: str
+    correction: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Policy:
+    rules: dict[str, AnalysisRule] = field(default_factory=lambda: dict(DEFAULT_RULES))
+    overrides: tuple[Override, ...] = ()
+
+    @classmethod
+    def default(cls) -> Policy:
+        return cls()
+
+    # -- content hashing ---------------------------------------------------
+
+    def fingerprint(self) -> str:
+        """SHA-256 of the canonical rule content (overrides applied)."""
+        content = {name: rule.to_json() for name, rule in sorted(self._effective_rules().items())}
+        blob = json.dumps(content, sort_keys=True, separators=(",", ":")).encode()
+        return hashlib.sha256(blob).hexdigest()
+
+    @property
+    def is_modified(self) -> bool:
+        return self.fingerprint() != _DEFAULT_FINGERPRINT
+
+    # -- loosening ---------------------------------------------------------
+
+    def allow(self, analysis: str, correction: str, reason: str) -> Policy:
+        """Return a new policy that allows `correction` for `analysis`.
+
+        A written reason is mandatory. Results under the new policy carry the
+        "policy modified" label.
+        """
+        if not reason or not reason.strip():
+            raise ValueError("A policy override needs a written reason.")
+        return Policy(rules=dict(self.rules), overrides=self.overrides + (Override(analysis, correction, reason.strip()),))
+
+    # -- checks ------------------------------------------------------------
+
+    def rule_for(self, analysis: str) -> AnalysisRule:
+        return self._effective_rules().get(analysis, STRICTEST)
+
+    def check_correction(self, analysis: str, correction: str) -> None:
+        if correction not in self.rule_for(analysis).allowed_corrections:
+            raise GuardrailRefusal(
+                f"Correction '{correction}' is not allowed for '{analysis}'. "
+                "Bell-type headline numbers use raw counts only; see docs/design.md, "
+                "'Scientific guardrails'."
+            )
+
+    def check_window(self, analysis: str, window_source: str) -> None:
+        if window_source not in self.rule_for(analysis).window_sources:
+            raise GuardrailRefusal(
+                f"A coincidence window from '{window_source}' is not allowed for '{analysis}'. "
+                "Windows must be fixed and declared in the analysis plan before acquisition; "
+                "windows chosen from the data open the coincidence-time loophole."
+            )
+
+    def labels_for(self, analysis: str) -> tuple[str, ...]:
+        labels: list[str] = []
+        if self.is_modified:
+            labels.append(POLICY_MODIFIED)
+        if analysis not in DEFAULT_RULES:
+            labels.append(UNVALIDATED_ANALYSIS)
+        return tuple(labels)
+
+    def _effective_rules(self) -> dict[str, AnalysisRule]:
+        rules = dict(self.rules)
+        for o in self.overrides:
+            base = rules.get(o.analysis, STRICTEST)
+            rules[o.analysis] = AnalysisRule(
+                allowed_corrections=base.allowed_corrections | {o.correction},
+                window_sources=base.window_sources,
+            )
+        return rules
+
+
+_DEFAULT_FINGERPRINT = Policy().fingerprint()
+
+
+def threshold_labels(analysis: str, raw: float, corrected: float | None) -> tuple[str, ...]:
+    """Label a result whose corrected value crosses a physical threshold that raw does not."""
+    threshold = THRESHOLDS.get(analysis)
+    if threshold is None or corrected is None:
+        return ()
+    if raw < threshold <= corrected:
+        return (THRESHOLD_AFTER_CORRECTION,)
+    return ()

dadl_quantum-0.0.2/dadl/result.py

@@ -0,0 +1,59 @@
+"""The labelled result type.
+
+A DADL result always carries its raw value, an optional corrected value and
+the labels that qualify it. It deliberately refuses to become a bare float, so
+a corrected number cannot be quoted without its raw value and labels by
+accident (see docs/design.md, "Labels travel with numbers").
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Estimate:
+    """A value with its one-sigma standard error."""
+
+    value: float
+    stderr: float
+
+    def __str__(self) -> str:
+        return f"{self.value:.4f} ± {self.stderr:.4f}"
+
+
+@dataclass(frozen=True)
+class LabelledValue:
+    """Raw value first, optional corrected value, and labels."""
+
+    analysis: str
+    raw: Estimate
+    corrected: Estimate | None = None
+    labels: tuple[str, ...] = field(default_factory=tuple)
+    artifact_ids: tuple[str, ...] = field(default_factory=tuple)
+
+    def __float__(self) -> float:
+        raise TypeError(
+            "A DADL result is not a bare number: use .raw.value or .corrected.value "
+            "explicitly, and keep .labels with it."
+        )
+
+    def __str__(self) -> str:
+        parts = [f"{self.analysis}: raw {self.raw}"]
+        if self.corrected is not None:
+            parts.append(f"corrected {self.corrected}")
+        if self.labels:
+            parts.append("[" + "; ".join(self.labels) + "]")
+        return "  ".join(parts)
+
+    def as_record(self) -> dict[str, object]:
+        """Flat record for CSV or DataFrame export. Labels are a mandatory column."""
+        return {
+            "analysis": self.analysis,
+            "raw_value": self.raw.value,
+            "raw_stderr": self.raw.stderr,
+            "corrected_value": None if self.corrected is None else self.corrected.value,
+            "corrected_stderr": None if self.corrected is None else self.corrected.stderr,
+            "labels": "; ".join(self.labels),
+            "artifact_ids": "; ".join(self.artifact_ids),
+        }

dadl_quantum-0.0.2/dadl/sim.py

@@ -0,0 +1,133 @@
+"""Time-tag simulator with known, injected detector imperfections.
+
+Every parameter that the calibration engine will later estimate is set
+explicitly here, so tests can compare estimates against the truth.
+
+Units: time tags are int64 picoseconds; rates are per second.
+
+Phase 1 approximations, to be replaced by the self-exciting detection model
+in docs/design.md:
+- afterpulses are generated for one generation only (no cascades);
+- crosstalk and breakdown flash are not simulated yet.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from dadl.deadtime import apply_nonparalyzable
+
+PS_PER_S = 10**12
+
+#: Analyzer angles in degrees for the standard CHSH settings on a Phi+ state.
+CHSH_SETTINGS: dict[str, float] = {"a": 0.0, "a'": 45.0, "b": 22.5, "b'": 67.5}
+CHSH_PAIRS: tuple[tuple[str, str], ...] = (("a", "b"), ("a", "b'"), ("a'", "b"), ("a'", "b'"))
+CHANNELS: tuple[str, ...] = ("A+", "A-", "B+", "B-")
+
+
+@dataclass(frozen=True)
+class DetectorParams:
+    """Ground truth for one detector channel."""
+
+    efficiency: float = 0.5  # system efficiency (detector x coupling)
+    dark_rate: float = 100.0  # counts per second
+    dead_time_ps: int = 22_000  # non-paralyzable
+    jitter_ps: float = 350.0  # Gaussian sigma
+    afterpulse_prob: float = 0.0  # per recorded avalanche
+    afterpulse_tau_ps: float = 50_000.0  # exponential delay after the dead time
+    delay_ps: int = 0  # fixed channel delay
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.efficiency <= 1.0:
+            raise ValueError("efficiency must be in [0, 1]")
+        if self.dark_rate < 0 or self.dead_time_ps < 0 or self.jitter_ps < 0:
+            raise ValueError("rates, dead time and jitter must be non-negative")
+        if not 0.0 <= self.afterpulse_prob < 1.0:
+            raise ValueError("afterpulse probability must be in [0, 1)")
+
+
+@dataclass(frozen=True)
+class PairSource:
+    """A CW polarization-entangled SPDC source producing a Werner-like Phi+ state."""
+
+    pair_rate: float = 1e5  # pairs per second at the crystal
+    visibility: float = 0.95  # E(alpha, beta) = V cos 2(alpha - beta)
+
+    def __post_init__(self) -> None:
+        if self.pair_rate < 0:
+            raise ValueError("pair rate must be non-negative")
+        if not 0.0 <= self.visibility <= 1.0:
+            raise ValueError("visibility must be in [0, 1]")
+
+
+def poisson_times(rate: float, duration_s: float, rng: np.random.Generator) -> np.ndarray:
+    """Sorted float64 arrival times (ps) of a homogeneous Poisson process."""
+    n = rng.poisson(rate * duration_s)
+    return np.sort(rng.uniform(0.0, duration_s * PS_PER_S, n))
+
+
+def detect(
+    photon_times_ps: np.ndarray,
+    det: DetectorParams,
+    duration_s: float,
+    rng: np.random.Generator,
+) -> np.ndarray:
+    """Turn photon arrival times into recorded int64 time tags for one detector."""
+    photons = np.asarray(photon_times_ps, dtype=np.float64)
+    kept = photons[rng.random(photons.size) < det.efficiency]
+    if det.jitter_ps > 0:
+        kept = kept + rng.normal(0.0, det.jitter_ps, kept.size)
+    kept = kept + det.delay_ps
+    darks = poisson_times(det.dark_rate, duration_s, rng)
+    arrivals = np.sort(np.rint(np.concatenate([kept, darks]))).astype(np.int64)
+    recorded = apply_nonparalyzable(arrivals, det.dead_time_ps)
+
+    if det.afterpulse_prob > 0 and recorded.size:
+        mask = rng.random(recorded.size) < det.afterpulse_prob
+        n_ap = int(mask.sum())
+        if n_ap:
+            delays = det.dead_time_ps + rng.exponential(det.afterpulse_tau_ps, n_ap)
+            afterpulses = np.rint(recorded[mask] + delays).astype(np.int64)
+            merged = np.sort(np.concatenate([recorded, afterpulses]))
+            recorded = apply_nonparalyzable(merged, det.dead_time_ps)
+    return recorded
+
+
+def simulate_chsh_setting(
+    source: PairSource,
+    alpha_deg: float,
+    beta_deg: float,
+    detectors: dict[str, DetectorParams],
+    duration_s: float,
+    rng: np.random.Generator,
+) -> dict[str, np.ndarray]:
+    """Recorded tags on channels A+, A-, B+, B- for one pair of analyzer angles."""
+    missing = set(CHANNELS) - set(detectors)
+    if missing:
+        raise ValueError(f"missing detector parameters for {sorted(missing)}")
+    t = poisson_times(source.pair_rate, duration_s, rng)
+    n = t.size
+    a_plus = rng.random(n) < 0.5
+    p_same = 0.5 * (1.0 + source.visibility * math.cos(2.0 * math.radians(alpha_deg - beta_deg)))
+    same = rng.random(n) < p_same
+    b_plus = np.where(same, a_plus, ~a_plus)
+    photons = {"A+": t[a_plus], "A-": t[~a_plus], "B+": t[b_plus], "B-": t[~b_plus]}
+    return {ch: detect(photons[ch], detectors[ch], duration_s, rng) for ch in CHANNELS}
+
+
+def simulate_chsh(
+    source: PairSource,
+    detectors: dict[str, DetectorParams],
+    duration_s: float,
+    rng: np.random.Generator,
+    settings: dict[str, float] | None = None,
+) -> dict[tuple[str, str], dict[str, np.ndarray]]:
+    """One acquisition per CHSH setting pair, keyed like ("a", "b'")."""
+    angles = settings or CHSH_SETTINGS
+    return {
+        (sa, sb): simulate_chsh_setting(source, angles[sa], angles[sb], detectors, duration_s, rng)
+        for sa, sb in CHSH_PAIRS
+    }

dadl_quantum-0.0.2/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dadl-quantum"
+version = "0.0.2"
+description = "Detector-Aware Data Layer for quantum optics experiments"
+readme = "README.md"
+license = { text = "MIT OR Apache-2.0" }
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "pyyaml>=6.0",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.urls]
+Homepage = "https://github.com/usecommon/dadl"
+Documentation = "https://github.com/usecommon/dadl/blob/main/docs/design.md"
+Issues = "https://github.com/usecommon/dadl/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[project.scripts]
+dadl = "dadl.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["dadl"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dadl_quantum-0.0.2/tests/test_chsh_closed_form.py

@@ -0,0 +1,53 @@
+"""CHSH from the simulator against closed-form expectations.
+
+Werner-like Phi+ state with Poisson accidentals: S = 2 sqrt(2) V C / (C + A).
+"""
+
+import math
+
+import numpy as np
+import pytest
+
+from dadl.analysis.chsh import FAIR_SAMPLING, Window, chsh
+from dadl.closed_form import chsh_expected_grid, chsh_werner, grid_capture_probability
+from dadl.sim import CHANNELS, DetectorParams, PairSource, simulate_chsh
+
+
+def run(dark_rate: float, seed: int):
+    params = dict(pair_rate=1e5, duration_s=0.5, efficiency=0.5, jitter_sigma_ps=50.0, width_ps=10_000, visibility=0.95)
+    det = DetectorParams(
+        efficiency=params["efficiency"],
+        dark_rate=dark_rate,
+        dead_time_ps=0,
+        jitter_ps=params["jitter_sigma_ps"],
+    )
+    runs = simulate_chsh(
+        PairSource(pair_rate=params["pair_rate"], visibility=params["visibility"]),
+        {ch: det for ch in CHANNELS},
+        params["duration_s"],
+        np.random.default_rng(seed),
+    )
+    result = chsh(runs, Window(width_ps=params["width_ps"]))
+    expected = chsh_expected_grid(dark_rate=dark_rate, **params)
+    return result, expected
+
+
+def test_capture_probability_limits():
+    assert grid_capture_probability(0.0, 1000) == 1.0
+    assert grid_capture_probability(50.0, 10_000) == pytest.approx(1 - 70.71 * math.sqrt(2 / math.pi) / 10_000, rel=1e-3)
+    assert 0.0 < grid_capture_probability(350.0, 2_000) < 1.0
+
+
+def test_negligible_accidentals_gives_werner_value():
+    result, expected = run(dark_rate=0.0, seed=1)
+    assert expected == pytest.approx(chsh_werner(0.95), rel=0.01)
+    assert result.raw.value == pytest.approx(expected, abs=5 * result.raw.stderr + 0.01)
+    assert FAIR_SAMPLING in result.labels
+
+
+def test_accidentals_reduce_s_as_predicted():
+    # Dark counts chosen so accidentals are ~30% of true coincidences: S falls from ~2.69 to ~2.08.
+    result, expected = run(dark_rate=4e5, seed=2)
+    assert 1.9 < expected < 2.2
+    assert result.raw.value == pytest.approx(expected, abs=5 * result.raw.stderr + 0.01)
+    assert result.corrected is None, "Bell headline numbers are raw only"

dadl_quantum-0.0.2/tests/test_coincidences.py

@@ -0,0 +1,28 @@
+"""Fixed-grid coincidences: same cases as the Rust core tests."""
+
+import numpy as np
+
+from dadl.coincidences import grid_coincidences
+
+
+def a(*xs):
+    return np.array(xs, dtype=np.int64)
+
+
+def test_counts_shared_slots():
+    assert grid_coincidences(a(0, 1000, 2500), a(100, 1900, 9000), 1000) == 2
+
+
+def test_declared_delay_shifts_slots():
+    assert grid_coincidences(a(50), a(950), 1000) == 1
+    assert grid_coincidences(a(50), a(1050), 1000) == 0
+    assert grid_coincidences(a(50), a(1050), 1000, delay_b_ps=1000) == 1
+
+
+def test_several_events_in_one_slot_count_once():
+    assert grid_coincidences(a(10, 20, 30), a(40), 1000) == 1
+
+
+def test_negative_times_use_floor_division():
+    assert grid_coincidences(a(-1), a(-999), 1000) == 1
+    assert grid_coincidences(a(-1), a(0), 1000) == 0

dadl_quantum-0.0.2/tests/test_config_and_cli.py

@@ -0,0 +1,47 @@
+"""Example setup file and CLI smoke tests."""
+
+from pathlib import Path
+
+import pytest
+
+from dadl.cli import main
+from dadl.config import load_setup
+from dadl.errors import ConfigError
+
+EXAMPLE = Path(__file__).resolve().parents[2] / "examples" / "chsh-spad" / "setup.yaml"
+
+
+def test_example_setup_loads():
+    setup = load_setup(EXAMPLE)
+    assert setup["schema_version"] == 1
+    assert setup["analysis"]["window"]["source"] == "plan"
+
+
+def test_window_from_data_rejected_in_config(tmp_path):
+    bad = tmp_path / "setup.yaml"
+    bad.write_text(
+        "schema_version: 1\nname: x\nsource: {}\ndetectors: {}\n"
+        "analysis: {type: chsh, window: {width_ps: 1000, source: data}}\n",
+        encoding="utf-8",
+    )
+    with pytest.raises(ConfigError):
+        load_setup(bad)
+
+
+def test_unsupported_schema_version(tmp_path):
+    bad = tmp_path / "setup.yaml"
+    bad.write_text("schema_version: 99\nname: x\nsource: {}\ndetectors: {}\nanalysis: {}\n", encoding="utf-8")
+    with pytest.raises(ConfigError):
+        load_setup(bad)
+
+
+def test_version_command(capsys):
+    assert main(["version"]) == 0
+    assert capsys.readouterr().out.strip()
+
+
+def test_quickstart_runs(capsys):
+    assert main(["quickstart", "chsh-spad"]) == 0
+    out = capsys.readouterr().out
+    assert "Raw S =" in out
+    assert "fair sampling assumed" in out

dadl_quantum-0.0.2/tests/test_deadtime.py

@@ -0,0 +1,46 @@
+"""Dead-time filters against closed-form Poisson results."""
+
+import numpy as np
+import pytest
+
+from dadl.closed_form import nonparalyzable_measured_rate, paralyzable_measured_rate
+from dadl.deadtime import apply_nonparalyzable, apply_paralyzable
+from dadl.sim import poisson_times
+
+TRUE_RATE = 1e6  # per second
+DURATION_S = 0.1
+TAU_S = 500e-9  # n * tau = 0.5, so the two models differ by ~10%
+
+
+@pytest.fixture(scope="module")
+def arrivals():
+    rng = np.random.default_rng(7)
+    return np.rint(poisson_times(TRUE_RATE, DURATION_S, rng)).astype(np.int64)
+
+
+def test_small_examples_match_rust_core():
+    times = np.array([0, 5, 10, 25, 30], dtype=np.int64)
+    assert apply_nonparalyzable(times, 10).tolist() == [0, 10, 25]
+    assert apply_paralyzable(times, 10).tolist() == [0, 25]
+
+
+def test_nonparalyzable_rate_matches_closed_form(arrivals):
+    measured = apply_nonparalyzable(arrivals, int(TAU_S * 1e12)).size / DURATION_S
+    expected = nonparalyzable_measured_rate(TRUE_RATE, TAU_S)
+    assert measured == pytest.approx(expected, rel=0.015)
+
+
+def test_paralyzable_rate_matches_closed_form(arrivals):
+    measured = apply_paralyzable(arrivals, int(TAU_S * 1e12)).size / DURATION_S
+    expected = paralyzable_measured_rate(TRUE_RATE, TAU_S)
+    assert measured == pytest.approx(expected, rel=0.015)
+
+
+def test_models_are_distinguishable(arrivals):
+    tau_ps = int(TAU_S * 1e12)
+    assert apply_paralyzable(arrivals, tau_ps).size < 0.95 * apply_nonparalyzable(arrivals, tau_ps).size
+
+
+def test_negative_dead_time_rejected():
+    with pytest.raises(ValueError):
+        apply_nonparalyzable(np.array([0, 1], dtype=np.int64), -1)

dadl_quantum-0.0.2/tests/test_guardrails.py

@@ -0,0 +1,79 @@
+"""Guardrail regression cases from published results.
+
+These must keep passing. Changing them needs two maintainer approvals
+(see CONTRIBUTING.md).
+"""
+
+import numpy as np
+import pytest
+
+from dadl.analysis.chsh import Window, chsh
+from dadl.analysis.visibility import two_photon_visibility
+from dadl.errors import GuardrailRefusal
+from dadl.guardrails import (
+    POLICY_MODIFIED,
+    THRESHOLD_AFTER_CORRECTION,
+    UNVALIDATED_ANALYSIS,
+    Policy,
+)
+
+# Thompson, quant-ph/9903066: with ~30% accidentals, subtraction moved
+# visibility from about 45% to 82%, past the 71% Bell threshold.
+N_MAX, N_MIN = 145.0, 55.0  # raw V = 0.45
+ACCIDENTALS = 45.12  # corrected V = 90 / (200 - 2 * 45.12) = 0.82
+
+
+def test_raw_visibility_matches_published_case():
+    result = two_photon_visibility(N_MAX, N_MIN, analysis="bell_visibility")
+    assert result.raw.value == pytest.approx(0.45)
+    assert result.corrected is None
+
+
+def test_accidental_subtraction_refused_for_bell_visibility():
+    with pytest.raises(GuardrailRefusal):
+        two_photon_visibility(N_MAX, N_MIN, analysis="bell_visibility", accidentals=ACCIDENTALS)
+
+
+def test_loosened_policy_is_never_silent():
+    policy = Policy.default().allow(
+        "bell_visibility", "accidental_subtraction", reason="reproducing Thompson's example"
+    )
+    result = two_photon_visibility(
+        N_MAX, N_MIN, analysis="bell_visibility", accidentals=ACCIDENTALS, policy=policy
+    )
+    assert result.raw.value == pytest.approx(0.45)
+    assert result.corrected.value == pytest.approx(0.82, abs=1e-3)
+    assert POLICY_MODIFIED in result.labels
+    assert THRESHOLD_AFTER_CORRECTION in result.labels
+
+
+def test_override_needs_a_reason():
+    with pytest.raises(ValueError):
+        Policy.default().allow("bell_visibility", "accidental_subtraction", reason="  ")
+
+
+def test_default_policy_is_not_modified():
+    assert not Policy.default().is_modified
+    assert Policy.default().fingerprint() == Policy().fingerprint()
+
+
+def test_hom_allows_accidental_subtraction_as_labelled_secondary():
+    result = two_photon_visibility(60.0, 40.0, analysis="hom_visibility", accidentals=15.0)
+    assert result.raw.value == pytest.approx(0.2)
+    assert result.corrected is not None
+    assert POLICY_MODIFIED not in result.labels
+
+
+def test_unknown_analysis_gets_strictest_policy():
+    with pytest.raises(GuardrailRefusal):
+        Policy.default().check_correction("my_plugin_analysis", "accidental_subtraction")
+    assert UNVALIDATED_ANALYSIS in Policy.default().labels_for("my_plugin_analysis")
+
+
+def test_window_chosen_from_data_is_refused():
+    # Coincidence-time loophole (arXiv:1503.07573): windows chosen from the data
+    # can fake a violation, so Bell analyses accept only planned windows.
+    empty = {ch: np.array([], dtype=np.int64) for ch in ("A+", "A-", "B+", "B-")}
+    runs = {key: empty for key in (("a", "b"), ("a", "b'"), ("a'", "b"), ("a'", "b'"))}
+    with pytest.raises(GuardrailRefusal):
+        chsh(runs, Window(width_ps=1000, source="data"))

dadl_quantum-0.0.2/tests/test_result.py

@@ -0,0 +1,31 @@
+"""The labelled result type keeps raw values and labels attached."""
+
+import pytest
+
+from dadl.result import Estimate, LabelledValue
+
+
+def make():
+    return LabelledValue(
+        analysis="hom_visibility",
+        raw=Estimate(0.45, 0.02),
+        corrected=Estimate(0.82, 0.04),
+        labels=("policy modified",),
+    )
+
+
+def test_refuses_bare_float():
+    with pytest.raises(TypeError):
+        float(make())
+
+
+def test_string_puts_raw_first_and_keeps_labels():
+    text = str(make())
+    assert text.index("raw") < text.index("corrected")
+    assert "policy modified" in text
+
+
+def test_export_record_has_mandatory_label_column():
+    record = make().as_record()
+    assert record["raw_value"] == 0.45
+    assert record["labels"] == "policy modified"