DADL: A Detector-Aware Data Layer for Single-Photon Experiments

Making detector imperfections known, bounded and auditable

The DADL contributors

Technical report · Version 0.1.1 · November 2026 · github.com/usecommon/dadl

Abstract

Results in quantum optics, from Bell tests and Hong–Ou–Mandel interference to state tomography and quantum key distribution, are computed from coincidence counts recorded by imperfect single-photon detectors. Efficiency loss, dark counts, dead time, afterpulsing, crosstalk and timing drift all shift the reported numbers, yet the corrections applied for them are rarely recorded, rarely carried into the stated uncertainty, and occasionally large enough to manufacture a result. We describe DADL, an open-source data layer designed to keep a versioned, uncertainty-carrying model of every detector channel, compute analyses through a single forward model of the detection process, always report raw and corrected values together, and refuse corrections that are invalid for the analysis at hand. Version 0.1.0 provides a detector simulator, raw Bell and visibility analyses on simulated or recorded time tags, the guardrails, and calibrations of dark counts, afterpulsing, dead time, delay and timing response, accidentals and heralding efficiency with simulation-checked intervals; corrected values follow. We explain the problem it addresses, how it is used in an experiment, its guardrails, and its current status.

Keywords: single-photon detection; detector calibration; coincidence counting; Bell inequalities; uncertainty propagation; reproducibility.


1Introduction

A single-photon experiment does not observe photons directly. It observes time tags: the instants at which detectors produced an electrical pulse. Correlations between those time tags carry the physics, and every imperfection of the detectors enters the data before any analysis begins (Figure 1).

A+ A− B+ B− 0 10 20 30 40 time (ns)
Figure 1. Schematic time tags on four channels of a polarization-entangled pair source over 40 ns. Vertical strokes are recorded detections; shaded columns are fixed 2 ns coincidence slots in which both sides fired. Hatched bands mark the 22 ns dead time following each detection; the photon marked × arrives during dead time and is lost. The filled diamond on A+ is an afterpulse, a spurious count triggered by the earlier avalanche; the open circle on B− is a dark count. None of these events is labelled as such in the recorded data.

The methods for characterizing these effects are mature. At NIST, correlated-photon (Klyshko) calibration and conventional substitution calibration agree within the comparison's uncertainty, differing by 0.14(14)%, with relative standard uncertainties near 0.2% [1], and the relevant vocabulary has been standardized [2]. What is missing is not physics but practice: a consistent way to apply these methods to the data of a running experiment, record what was applied, and carry the resulting uncertainty into the published number. DADL is an attempt to provide that practice as reusable, open-source software.

2Sources of error in photon counting

Error enters a coincidence measurement at every stage between the source and the analysis (Figure 2). The detector stage contributes the largest number of distinct effects, and the least visible: they depend on temperature, bias, count rate and device age, and they differ markedly between detector families.

Pair source Fiber and optics Detectors Time tagger Analysis pump-power drift multi-pair emission coupling loss connector reseats polarization drift channel delays TDC dead time trigger thresholds window choice accidental subtraction MLE bias efficiency < 1 dark counts (T, bias) dead time afterpulsing crosstalk, jitter latching, blinding each shifts the reported S, visibility, fidelity or key rate
Figure 2. Principal sources of error in a coincidence measurement, by stage. The detector stage (bold outline) is the focus of DADL; the analysis stage is where corrections for the other stages are applied, and where they can be misapplied.

Typical magnitudes illustrate the range. A commercial silicon SPAD module is graded between 25 and 1500 dark counts per second, with a dead time of 22–42 ns and afterpulsing of 0.5–1% [3]. A recent waveguide-integrated visible SPAD reported 25–30% afterpulsing [4]. Silicon photomultipliers show optical crosstalk of about 25% as bare devices at high bias, rising toward 40–49% with reflective packaging [5]. An analysis that ignores effects of this size is not reporting the state of the photons; it is reporting the state of the detectors.

3Failure modes in current practice

3.1 Silent drift

Dark counts rise with temperature; a reseated fiber connector changes coupling; a cable delay shifts by a hundred picoseconds as the room warms. Each degrades the result, and without a record of the detector's state alongside the data the cause cannot be identified after the fact.

3.2 Overcorrection

Corrections can create results as well as repair them. In one published example, subtracting accidental coincidences raised a measured two-photon visibility from about 45% to 82%, past the 1/√2 ≈ 71% that, for a Werner state with that visibility in two conjugate bases, implies a Bell violation [6]. In another, a classical source analysed with coincidence windows chosen from the data produced an apparent violation of the CH inequality of over 2700σ, and no significant violation with a predefined window [7]. Maximum-likelihood tomography, the standard estimator, has been shown to underestimate fidelity and overestimate entanglement [8]. These are not errors of calculation; they are errors of procedure, and they recur because nothing in the usual toolchain prevents them.

3.3 Unreproducible numbers

Corrections are typically applied in notebooks or spreadsheets. Which calibration was used, from when, in what order, and with what uncertainty is seldom recorded with the result, so a published number can be neither traced to its inputs nor recomputed by a colleague or referee.

Existing software addresses parts of this chain but not the chain itself. Time-tagger software computes coincidences without a model of the detectors; detector controllers tune bias without reference to the experiment's figure of merit; tomography libraries estimate states without a record of the detectors behind the counts. We know of no open tool that connects detector state, correction, uncertainty, result and explanation across vendors; that connection is the purpose of DADL, and most of it is still planned (Section 10). A comparison with existing tools (time-tagger software, Photon-HDF5 tooling, tttrlib, Bell-test statistics packages) is in preparation.

4Design

DADL is a layer between the instruments and the analysis (Figure 3). Data arrive through vendor adapters; a registry holds a fitted, versioned model of every detector channel; calibration routines update the registry from the experiment's own data; and all corrections, analyses and explanations are computed through the same registry entries.

Experimental setup DADL Outputs Time taggers Swabian, PicoQuant Detectors SPAD, SNSPD, SiPM Telemetry temperature, bias Simulator identical interface Vendor adapters Detector registry Calibration engine Forward model and analyses Attribution engine Agent interface (MCP) Raw and corrected values Full uncertainty Calibration records Health alerts Attribution of drift
Figure 3. Architecture (design; most components are planned, see Table 2). The detector registry (bold outline) holds, for each channel, posterior samples of efficiency, dark-count rate as a function of temperature and bias, dead time, afterpulse kernel, crosstalk, delay and timing response, each stored as an immutable, content-addressed record (signing planned). Because every downstream component reads the same records, no effect is corrected twice and every result can cite exactly the calibration it used.

Three design commitments follow from Section 3. First, corrections are derived from one generative model of the detection process, fitted to the data, rather than from a sequence of independent subtractions that may count the same event twice. Second, raw values are never discarded: every result carries its raw value, its corrected value where one is permitted, and its labels. Third, explanations of a change in a result are computed numerically before any text is produced.

For a polarization-entangled source, the CHSH parameter is formed from four correlators,

S = E(a, b) − E(a, b′) + E(a′, b) + E(a′, b′),   E = (N++ + N−− − N+− − N−+) / N,(1)

and uniform accidental coincidences A dilute every correlator equally, so that for a Werner-like state of visibility V with C true coincidences

Sraw = 2√2 V · C / (C + A).(2)

Equation (2) is one of the closed-form results against which the DADL simulator and analyses are tested; with the parameters of the bundled example it predicts S = 2.686, and the simulation returns 2.694 ± 0.011 (Listing 2).

5Use in an experiment

DADL is designed to fit the measurement loop a laboratory already runs (Figure 4). Most calibration data are by-products of ordinary acquisitions: the cross-correlation peak yields channel delays and timing response, off-peak bins yield the accidental rate, and the heralding ratio yields a heralded detection probability for the declared window (not system efficiency: it includes the window capture and live fraction, and is diluted by herald dark counts).

(i) Plan setup file, fixed window (ii) Acquire time tags (iii) Calibrate from the same data (iv) Correct and fit raw with corrected (v) Explain attribution of change Detector registry versioned, content-addressed records write read
Figure 4. The measurement loop. Solid arrows give the order of operations in each run; dashed arrows show calibration writing new records to the registry and the analysis reading them. A planned health monitor (not shown, not yet built) would compare every run with the current model and flag drift and latching. Today DADL flags interruptions such as a latch within an acquisition.

In practice a measurement proceeds as follows. The status of each step in the current release is given in italics.

  1. Describe the setup. A single configuration file names the source, each detector channel and its family, the time tagger and the analysis (Listing 1). Available: dadl init copies the example and dadl quickstart setup.yaml runs the edited copy.
  2. Declare the analysis before acquisition. The coincidence window, sample size and any data-exclusion rules are fixed in advance. For Bell-type analyses a window derived from the data is rejected, since this is the mechanism of the coincidence-time loophole [7]. Window rule available; the declared window is recorded but cannot be verified until signed analysis plans (planned).
  3. Acquire. Time tags are read from a tagger, a recorded file or the built-in simulator. Configuration changes, buffer overflows and dropped data are logged as events. Simulator, generic tag files (dadl analyze) and PicoQuant PTU files (T2 mode, on the 0.1.0) available; other vendor adapters planned.
  4. Calibrate. Dark counts and afterpulsing are fitted jointly from dark inter-arrival data; delays and timing response from the cross-correlation peak; a window-specific heralded detection probability from the heralding ratio. Each fit is stored with its posterior uncertainty, and a new record never overwrites the previous one. Dark counts, afterpulsing, dead time, DCR(T), delay and timing response, off-peak accidentals and heralding efficiency available in 0.1.0 (dadl calibrate dark, dadl calibrate pairs), with content-addressed records; supersession and validity are recorded, not yet enforced.
  5. Correct and fit. CHSH, HOM visibility and tomography are computed through the forward model, with calibration uncertainty propagated by joint Monte Carlo sampling. Every result returns its raw value first, its corrected value where permitted, and its labels (Listing 2). Raw CHSH and visibility available; corrected values planned.
  6. Explain. When a result changes between runs, the analysis is recomputed with each identifiable cause held at its earlier value (Section 7). Planned.
  7. Archive. Time tags from calibration windows and declared runs are stored in Photon-HDF5 [9] with a calibration group (under /user until a /calibration group is accepted upstream) recording which records were applied, in what order, and with which software versions. Schema available; export planned.
Listing 1. Excerpt of the bundled example configuration, examples/chsh-spad/setup.yaml.
schema_version: 1
name: chsh-spad
detectors:
  A+: { family: si-spad-module, efficiency: 0.5, dark_rate_cps: 500, dead_time_ps: 22000 }
analysis:
  type: chsh
  window: { width_ps: 2000, source: plan }   # declared before acquisition
Listing 2. Excerpt of the output of the bundled example on simulated data (version 0.1.0).
$ dadl quickstart chsh-spad
  Raw S = 2.6941 ± 0.0105   (statistical only (Gaussian, 1 sigma))
  Labels: fair sampling and fair coincidence assumed (post-selected on coincidences);
    static settings: locality, freedom-of-choice and memory loopholes open; not a loophole-free test
  Coincidences per singles, arm A/arm B (what post-selection kept; compare the smaller with a
    detection-loophole threshold): a,b 0.396/0.393, a,b' 0.392/0.392, a',b 0.387/0.387, a',b' 0.390/0.392
  Window: 2000 ps, delays none, source 'plan' (declared, not verified)
  Closed-form expectation (ignores dead time, which can raise S, and afterpulsing): S = 2.6863

6Guardrails

A tool that improves reported numbers will be used to improve reported numbers. DADL therefore treats the validity of a correction as a property of the analysis, enforced in code. Each analysis type declares which corrections may appear, always as a labelled secondary value; a forbidden correction raises an error rather than a warning. Figure 5 shows the case from Section 3.2 as it is handled by the current release.

Raw counts Accidentals subtracted 0.45 0.82 refused 1/√2 ≈ 0.71 0 0.25 0.50 0.75 1 two-photon fringe visibility V
Figure 5. Visibility from the same counts before (solid) and after (hatched) subtracting accidentals, after Ref. [6]; the dashed line is the threshold 1/√2 for a CHSH violation under fair sampling. For Bell-type analyses DADL rejects the subtraction. If a user loosens the policy, the result is still returned with the raw value 0.45 first and the labels policy modified and threshold crossed only after correction. This case is part of the automated test suite.

The rules enforced in the current release are:

Because DADL is distributed as a starter kit, its policy can be edited. Loosening a rule requires a written reason. Every result records the fingerprint of the policy it was computed under, which covers both the rules and the thresholds, together with any overrides and their reasons, and a result computed under a non-default policy is labelled as such. The first phase trusts the counts and time tags it is given; dataset identifiers computed from raw tags are planned.

7Attribution of drift

When a result changes between runs, the usual explanation is a conjecture. DADL is designed to replace it with a computation: the analysis is repeated with each identifiable group of parameters held at its earlier value, the change is divided among those groups by Shapley attribution, and any part not reproduced by the model is reported as misfit. Figure 6 illustrates the intended output.

2.2 2.3 2.4 2.5 2.6 S 2.60 −0.21 ± 0.04 −0.04 ± 0.02 −0.03 ± 0.02 −0.02 2.30 run 1 dark counts detector B delay drift pump power misfit not explained run 2
Figure 6. Illustrative attribution of a decrease in S from 2.60 to 2.30 between two runs; values are hypothetical. Shaded bars are contributions with intervals; causal wording is reported only where an interval, adjusted for the number of parameter groups, excludes zero. The hatched bar is the difference between the observed change and the change predicted by the model. Because S = 2√2·V·C/(C + A) with V ≤ 1, a baseline of 2.60 means accidentals are at most 8.8% of true coincidences, and reaching 2.30 needs them to grow 2.6-fold. A 40% rise in one detector's dark-count rate therefore gives at most S ≈ 2.52; a tripling produces the drop only if that detector's dark counts already caused about 80% of the accidentals, as on long, lossy links. On a bright source the same rise has a negligible effect, and the attribution would show this. The observed change itself carries the shot noise of both runs, about √2 σS. Parameters that the data cannot separate, such as source brightness and fiber coupling without a heralding reference, are reported jointly as indistinguishable rather than divided arbitrarily.

8Benefits

Table 1 summarizes the practical difference DADL is intended to make to routine questions in a single-photon laboratory.

Table 1. Routine questions with and without DADL, as designed; the "With DADL" column describes the planned system (status in Table 2).
QuestionCommon practiceWith DADL
What is the detector efficiency now?Datasheet value or an old calibrationVersioned record from current data, with uncertainty and provenance
How large are the error bars?Poisson errors on countsCounting and calibration uncertainty propagated jointly (counting only in the first phase)
Did a correction inflate the result?Depends on the analysis scriptRaw value always reported; invalid corrections rejected; threshold crossings labelled
Why did the result change?Conjecture and re-measurementAttribution with intervals and an explicit unexplained part
Can the number be reproduced?Rarely; corrections undocumentedEach result cites its calibration records and software versions
Does it work across hardware?Each vendor tool covers its own devicesOne model across taggers and detector families; extensible adapters

The benefits differ by user. For quantum network testbeds, where availability is the figure of merit, a planned continuous health monitor would track each channel, flag latching and export metrics to an orchestrator, with each alert linked to its evidence. For research laboratories running Bell, HOM and tomography experiments, the gains are honest uncertainties, protection against loophole-prone procedures, and less time spent rebuilding calibration scripts. For quantum key distribution developers, detector characterization along the lines of ETSI GS QKD 011 [10] and signed monitoring records for each key session are planned; gated detectors, efficiency mismatch and side-channel characterization (blinding, after-gate, time-shift and dead-time attacks) are not supported today, and nothing DADL produces belongs in a QKD security argument. For teaching laboratories, the simulator injects known imperfections, so that the effect of a dark count or of accidentals on a Bell parameter can be observed and checked against closed-form results such as Eq. (2); dead time and afterpulsing are simulated but not in that closed form, and dead time can raise S.

9Limitations

Software cannot recover lost efficiency or timing resolution; DADL makes the imperfections of an inexpensive detector known, bounded and auditable, which is not the same as making it equivalent to a better one. Correcting for efficiency is equivalent to assuming fair sampling, so DADL cannot close the detection loophole: a loophole-free CHSH test requires a detection efficiency of about 82.84% [11], or about 2/3 with Eberhard's inequality, non-maximally entangled states and near-zero background [12]. In a QKD security path DADL would only monitor and record; it has no side-channel detection today. Finally, review to date has been AI-agent role-play reviews (see the review registers in the repository); there has been no independent human review yet. Published numbers (e.g. the Tittel et al. visibility as analysed by Thompson) are reproduced in automated tests, so that the guardrails are checked against them on every change.

10Status and roadmap

DADL is pre-alpha (version 0.1.1): the first phase is partly done and the second is done. Its tests, including the published guardrail cases, closed-form checks and test cases shared by the Rust and Python implementations, run in continuous integration on Windows, Linux and macOS. Table 2 copies the canonical phase plan in the design document; the project is maintained by a small team, so later phases are scoped to what it can sustain. All review to date has been AI-agent role-play review, with no independent human review yet, recorded in the review records.

Table 2. Development phases.
PhaseScopeStatus
1. Simulator and starter kitTime-tag simulator with injected imperfections; configuration-driven quickstart; raw CHSH and visibility from simulated or recorded tags; guardrail policy with recorded provenance; Rust core held to shared test casespartial
2. Calibration engineDark counts, dead time, afterpulsing, delay and timing response, heralding efficiency, off-peak accidentals; one tagger adapter (PicoQuant PTU); dataset and detector-model interfaces; Python bindings to the Rust coredone (0.1.0)
3. InferenceForward model; joint Monte Carlo uncertainty; corrected CHSH and HOM visibility; signed analysis plansplanned
4. Attribution and agentsAttribution engine; typed MCP tools with human approval for hazardous instrument changes; artifact signingseeking contributors
5. Hardware pilotOne research laboratory and one network testbed; comparison of inexpensive and reference detectors, published including disagreementsneeds a partner

Availability

Source code, documentation and the design document are at github.com/usecommon/dadl, dual-licensed under MIT or Apache-2.0. The Python package is published as dadl-quantum on PyPI and the Rust core as dadl on crates.io; the import name and the command-line tool are both dadl. The example in Listing 2 is reproduced by pip install dadl-quantum followed by dadl quickstart; dadl analyze runs the same analysis on recorded time tags.

References

  1. A. Migdall et al., “High accuracy calibration of photon-counting detectors ‘on demand’,” Proc. SPIE 6583. NIST
  2. National Institute of Standards and Technology, Single-Photon Sources and Detectors, NIST IR 8486r1 (2025). doi/pdf
  3. Excelitas Technologies, SPCM-AQRH single-photon counting module datasheet, Rev. 2023-1. pdf
  4. “Free-running waveguide-integrated single-photon avalanche detectors for visible light,” arXiv:2606.22863 (2026). arXiv
  5. Optical crosstalk in SiPM-based detectors, Frontiers in Physics (2025), doi:10.3389/fphy.2025.1603556. link
  6. C. H. Thompson, “Subtraction of ‘accidentals’ and the validity of Bell tests,” arXiv:quant-ph/9903066 (1999). arXiv
  7. B. G. Christensen et al., “Analysis of coincidence-time loopholes in experimental Bell tests,” arXiv:1503.07573 (2015). arXiv
  8. C. Schwemmer et al., “Systematic errors in current quantum state tomography tools,” Phys. Rev. Lett. 114, 080403 (2015). doi
  9. A. Ingargiola et al., Photon-HDF5 format definition, version 0.4. docs
  10. ETSI, Quantum Key Distribution; Component characterization: characterizing optical components for QKD systems, GS QKD 011 V1.1.1 (2016). record
  11. A. Garg and N. D. Mermin, “Detector inefficiencies in the Einstein–Podolsky–Rosen experiment,” Phys. Rev. D 35, 3831 (1987). doi
  12. P. H. Eberhard, “Background level and counter efficiencies required for a loophole-free Einstein–Podolsky–Rosen experiment,” Phys. Rev. A 47, R747 (1993). doi