dadl-quantum 0.0.2__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+dadl/__init__.py,sha256=EnugLErrkt54qQdtO_nrBD_GR2A5YkqPOLXxd2E4bDw,433
+dadl/cli.py,sha256=ovXAJjjkRjXLC984Pb4Zvri97wA8XSZgdjOxY9BghFU,2987
+dadl/closed_form.py,sha256=G5j9p9zAG27qigOd0AGCHFjGFfF-9JNXXjB-gI4cJng,2728
+dadl/coincidences.py,sha256=UKSmS3d87QbhLqnO0vmXcUguKRj883LDBaUo-tZP1QA,1094
+dadl/config.py,sha256=pV25pF4R_kXiPBrDd9xJEOKrQN3YaWq3ByRAnYPVLJY,1523
+dadl/deadtime.py,sha256=wbLHBXoYMB2RTvLxXUxa6C2ZaeUhqo3Z5MYjU3_E-cw,1241
+dadl/errors.py,sha256=q7_9FN3LlfkKu9OkdExjhRES06PqvEKlfjTiSA3wV3k,495
+dadl/guardrails.py,sha256=mCaA5P2DP4JUY0hVPDkAr2_i-jSd-YpTbxRAwIpAlnQ,5748
+dadl/result.py,sha256=pqJlfcMaUJsMDFoXwDH5Ic_AyEMn7OgKpV5rj03V6OQ,2000
+dadl/sim.py,sha256=tN4CMeCwQgAzJRsNjNRi1UTVfSnsWTPqyddHzkJjWzw,5225
+dadl/analysis/__init__.py,sha256=wbeH0n_KKHBEfYZsuviZFpqKD7pDx5kYRs8YCwpUh84,230
+dadl/analysis/chsh.py,sha256=CMW7eu2cqlW9sD99qgW7uhEVQ1N85kdt7j83H0SlK0c,2390
+dadl/analysis/visibility.py,sha256=mcvjIGYFMrn0-3Uhml4vbI1cu0ZgNhPnJwMjH9ISEc4,1764
+dadl_quantum-0.0.2.dist-info/METADATA,sha256=7m36g-y50w-CRQ1bDuJ_2HBbs81LR53QJUDqo_bDWkU,1286
+dadl_quantum-0.0.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dadl_quantum-0.0.2.dist-info/entry_points.txt,sha256=Gl-09w4WNOdJJnnBKjbVGWvzAwVK1iJT5AFyhPrWEJA,39
+dadl_quantum-0.0.2.dist-info/RECORD,,

dadl_quantum-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dadl_quantum-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dadl = dadl.cli:main