quantumbox-sdk 2026.10.15.3__tar.gz

quantumbox_sdk-2026.10.15.3/.gitignore

@@ -0,0 +1,7 @@
+# Copied from ../../json-map at build time (single source of truth)
+quantumbox/data/daq1x1.json
+dist/
+*.egg-info/
+.venv/
+__pycache__/
+.pytest_cache/

quantumbox_sdk-2026.10.15.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nuclear Instruments s.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantumbox_sdk-2026.10.15.3/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: quantumbox-sdk
+Version: 2026.10.15.3
+Summary: Python SDK for the Nuclear Instruments QuantumBOX: settings, calibration, photon counting and timing
+Project-URL: Homepage, https://www.nuclearinstruments.eu
+Project-URL: Documentation, https://nuclear-instruments.pages.nuclearinstruments.eu/prodotti/daq121-2/application-software/quantumbox/quantumbox-go/
+Project-URL: Bug Tracker, https://support.nuclearinstruments.eu
+Author-email: Nuclear Instruments <info@nuclearinstruments.eu>
+License: MIT
+License-File: LICENSE
+Keywords: CAEN,NIDAQ121,Nuclear Instruments,QUANTA,QuantumBOX,SciSDK,SiPM,photon counting,photon timing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.20
+Requires-Dist: scisdk>=1.5
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.3; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# QuantumBOX SDK for Python
+
+Python control of the **Nuclear Instruments QuantumBOX** (NIDAQ121): everything the
+QUANTA application does, from your own scripts.
+
+- **Settings**: global, per-channel and common trigger configuration, input routing,
+  validation, operating mode (photon counting / photon timing), GUI settings files
+- **Oscilloscopes**: trigger scope and one scope per channel, analog and digital traces
+- **Calibration**: hardware energy spectra, zero peak, multi-peak fit, PE thresholds
+- **Photon counting** (List_0): 8-channel energies per trigger, PE classification,
+  mean / variance / Fano / g²(0), channel-pair correlations (g₁₁, NRF, γ)
+- **Photon timing** (List_1): per-channel timestamps (leading edge or CFD, ~2 ps),
+  inter-arrival and channel-difference histograms
+- **HW counters and coincidence units**
+- **Data saving** in the same formats as QUANTA (bin, csv, txt, npy), and loaders for
+  files written by QUANTA
+
+## Requirements
+
+- Python 3.8 or later, with `numpy`
+- The **SciSDK** native library installed on the PC (SciSDK setup on Windows, `scisdk`
+  package on Linux). The `scisdk` Python wrapper is installed automatically with this
+  package.
+- A QuantumBOX reachable over Ethernet (default `192.168.102.199`, port `8888`)
+
+## Installation
+
+```bash
+pip install quantumbox-sdk
+```
+
+The default firmware register map (`daq1x1.json`) is included: you do not need to pass a
+register file unless your firmware uses a different one.
+
+## Quick start
+
+```python
+from quantumbox import QuantumBox
+
+with QuantumBox("192.168.102.199") as box:          # port 8888 by default
+    print(box.operating_mode)                        # 'counting' or 'timing'
+
+    cfg = box.get_global_config()
+    cfg.trigger_type = "le"                          # common / le / cfd
+    cfg.qdc_tq_long = 100                            # integration time (ns)
+    box.set_global_config(cfg)
+
+    box.update_channels(None, pol=0, qdc_gain_value=1.0)   # all channels
+
+    with box.counting_list() as lst:                 # photon counting run
+        events = lst.acquire(duration_s=5)
+    print(len(events), "events, CH0 energies:", events["energy"][:5, 0])
+```
+
+### Calibration and PE thresholds
+
+```python
+from quantumbox import QuantumBox, SpectrumAnalysisConfig, analyze_spectrum, Thresholds
+import time
+
+with QuantumBox("192.168.102.199") as box:
+    box.spectra.reset(); box.spectra.start()
+    time.sleep(30)
+    spectra = box.spectra.read()
+    box.spectra.stop()
+
+cfg = SpectrumAnalysisConfig(zero_roi_left=2500, zero_roi_right=3400, min_peak_distance=50,
+                             peak_tail=True, fit_background=True)
+thresholds = Thresholds()
+for ch, counts in spectra.items():
+    result = analyze_spectrum(counts, cfg)
+    thresholds[ch] = result.threshold_entries()
+thresholds.save("thresholds.json")
+```
+
+### Photon statistics
+
+```python
+from quantumbox import classify_pe, pe_histogram, pe_statistics, correlation
+
+pe0 = classify_pe(events["energy"][:, 0], thresholds[0])
+pe1 = classify_pe(events["energy"][:, 1], thresholds[1])
+print(pe_statistics(pe_histogram(pe0)))     # mean, variance, fano, g2
+print(correlation(pe0, pe1))                 # g11, nrf, gamma, unbalance, coincidences
+```
+
+### Photon timing
+
+```python
+from quantumbox import interarrival_histogram, difference_histogram
+
+with QuantumBox("192.168.102.199") as box:
+    box.set_operating_mode("timing")
+    with box.timing_list() as lst:               # CFD/LE encoding read from the board
+        ev = lst.acquire(duration_s=10)
+
+counts, edges = difference_histogram(ev["time_ns"], ev["channel"], 0, 1, range_ns=20, bins=2000, signed=True)
+```
+
+## Examples
+
+The `examples/` folder of the source distribution contains complete scripts:
+connection and settings, oscilloscope capture, calibration, photon counting and timing
+runs with data saving, HW counters and coincidences, offline analysis of saved files.
+
+## Documentation
+
+Full user guide: see the **QuantumBOX SDK User Guide** (link in the package page).
+
+## License
+
+MIT — © Nuclear Instruments

quantumbox_sdk-2026.10.15.3/README.md

@@ -0,0 +1,112 @@
+# QuantumBOX SDK for Python
+
+Python control of the **Nuclear Instruments QuantumBOX** (NIDAQ121): everything the
+QUANTA application does, from your own scripts.
+
+- **Settings**: global, per-channel and common trigger configuration, input routing,
+  validation, operating mode (photon counting / photon timing), GUI settings files
+- **Oscilloscopes**: trigger scope and one scope per channel, analog and digital traces
+- **Calibration**: hardware energy spectra, zero peak, multi-peak fit, PE thresholds
+- **Photon counting** (List_0): 8-channel energies per trigger, PE classification,
+  mean / variance / Fano / g²(0), channel-pair correlations (g₁₁, NRF, γ)
+- **Photon timing** (List_1): per-channel timestamps (leading edge or CFD, ~2 ps),
+  inter-arrival and channel-difference histograms
+- **HW counters and coincidence units**
+- **Data saving** in the same formats as QUANTA (bin, csv, txt, npy), and loaders for
+  files written by QUANTA
+
+## Requirements
+
+- Python 3.8 or later, with `numpy`
+- The **SciSDK** native library installed on the PC (SciSDK setup on Windows, `scisdk`
+  package on Linux). The `scisdk` Python wrapper is installed automatically with this
+  package.
+- A QuantumBOX reachable over Ethernet (default `192.168.102.199`, port `8888`)
+
+## Installation
+
+```bash
+pip install quantumbox-sdk
+```
+
+The default firmware register map (`daq1x1.json`) is included: you do not need to pass a
+register file unless your firmware uses a different one.
+
+## Quick start
+
+```python
+from quantumbox import QuantumBox
+
+with QuantumBox("192.168.102.199") as box:          # port 8888 by default
+    print(box.operating_mode)                        # 'counting' or 'timing'
+
+    cfg = box.get_global_config()
+    cfg.trigger_type = "le"                          # common / le / cfd
+    cfg.qdc_tq_long = 100                            # integration time (ns)
+    box.set_global_config(cfg)
+
+    box.update_channels(None, pol=0, qdc_gain_value=1.0)   # all channels
+
+    with box.counting_list() as lst:                 # photon counting run
+        events = lst.acquire(duration_s=5)
+    print(len(events), "events, CH0 energies:", events["energy"][:5, 0])
+```
+
+### Calibration and PE thresholds
+
+```python
+from quantumbox import QuantumBox, SpectrumAnalysisConfig, analyze_spectrum, Thresholds
+import time
+
+with QuantumBox("192.168.102.199") as box:
+    box.spectra.reset(); box.spectra.start()
+    time.sleep(30)
+    spectra = box.spectra.read()
+    box.spectra.stop()
+
+cfg = SpectrumAnalysisConfig(zero_roi_left=2500, zero_roi_right=3400, min_peak_distance=50,
+                             peak_tail=True, fit_background=True)
+thresholds = Thresholds()
+for ch, counts in spectra.items():
+    result = analyze_spectrum(counts, cfg)
+    thresholds[ch] = result.threshold_entries()
+thresholds.save("thresholds.json")
+```
+
+### Photon statistics
+
+```python
+from quantumbox import classify_pe, pe_histogram, pe_statistics, correlation
+
+pe0 = classify_pe(events["energy"][:, 0], thresholds[0])
+pe1 = classify_pe(events["energy"][:, 1], thresholds[1])
+print(pe_statistics(pe_histogram(pe0)))     # mean, variance, fano, g2
+print(correlation(pe0, pe1))                 # g11, nrf, gamma, unbalance, coincidences
+```
+
+### Photon timing
+
+```python
+from quantumbox import interarrival_histogram, difference_histogram
+
+with QuantumBox("192.168.102.199") as box:
+    box.set_operating_mode("timing")
+    with box.timing_list() as lst:               # CFD/LE encoding read from the board
+        ev = lst.acquire(duration_s=10)
+
+counts, edges = difference_histogram(ev["time_ns"], ev["channel"], 0, 1, range_ns=20, bins=2000, signed=True)
+```
+
+## Examples
+
+The `examples/` folder of the source distribution contains complete scripts:
+connection and settings, oscilloscope capture, calibration, photon counting and timing
+runs with data saving, HW counters and coincidences, offline analysis of saved files.
+
+## Documentation
+
+Full user guide: see the **QuantumBOX SDK User Guide** (link in the package page).
+
+## License
+
+MIT — © Nuclear Instruments

quantumbox_sdk-2026.10.15.3/examples/01_connect_and_configure.py

@@ -0,0 +1,48 @@
+"""Connect, read the configuration, change settings, save and reload a settings file.
+
+    python 01_connect_and_configure.py --ip 192.168.102.199
+"""
+
+from quantumbox import QuantumBox, TriggerConfig
+from _common import parser
+
+args = parser(__doc__).parse_args()
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    print("Connected:", box, "| SciSDK", box.library_version())
+    print("Operating mode:", box.operating_mode)
+
+    # ── global settings (GUI: Settings → Global) ──
+    g = box.get_global_config()
+    print(f"Trigger: {g.trigger_type}, algorithm: {g.algorithm}, pole zero: {g.pole_zero_enabled}")
+    g.algorithm = "qdc"
+    g.trigger_type = "common"          # common trigger for photon counting
+    g.qdc_pre_int = 10                 # ns
+    g.qdc_tq_long = 100                # integration window, ns
+    box.set_global_config(g)
+
+    # common trigger: leading edge on CH0
+    box.set_trigger_config(TriggerConfig(source="le", input_channel=0, polarity="pos",
+                                         threshold=3500, hysteresis=100, inhibit_ns=200))
+
+    # validation: OR of channels 0..3
+    box.set_channel_mask([0, 1, 2, 3])
+    box.set_validation("or")
+
+    # ── per-channel settings (GUI: Settings → Channels) ──
+    box.update_channels(None, pol=0, qdc_gain_value=1.0)      # all channels
+    ch2 = box.get_channel_config(2)
+    ch2.hysteresis = 50
+    ch2.baseline_samples = 256
+    box.set_channel_config(ch2)
+    for c in box.get_channel_configs()[:3]:
+        print(f"CH{c.index}: gain={c.qdc_gain_value:.3f} thr={c.thrs_high} hyst={c.hysteresis} "
+              f"baseline={c.baseline_samples} samples")
+
+    # input router: CH4 reads physical input B_2
+    box.set_input_routing(4, 1)
+
+    # ── settings file, compatible with the GUI (Toolbar → Load settings) ──
+    box.save_settings("my_settings.json")
+    box.load_settings("my_settings.json")
+    print("Settings saved to my_settings.json and re-applied")

quantumbox_sdk-2026.10.15.3/examples/02_oscilloscope.py

@@ -0,0 +1,49 @@
+"""Capture a channel oscilloscope (analog IN / QDC IN and digital traces) and plot it.
+
+    python 02_oscilloscope.py --ip 192.168.102.199 --channel 2
+"""
+
+from quantumbox import QuantumBox
+from quantumbox.oscilloscope import select_second_trace
+from _common import parser
+
+p = parser(__doc__)
+p.add_argument("--channel", default="2", help="0..7 or 'trigger'")
+p.add_argument("--decimator", type=int, default=1)
+args = p.parse_args()
+channel = args.channel if args.channel == "trigger" else int(args.channel)
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    if channel != "trigger":
+        select_second_trace(box, channel, "qdc")        # second trace: QDC IN (or 'cfd')
+    with box.oscilloscope(channel) as scope:
+        scope.configure(decimator=args.decimator, pretrigger=100,
+                        trigger_mode="self" if channel == "trigger" else "ext")
+        scope.start()
+        trace = scope.read(timeout_s=5)
+        scope.stop()
+
+if trace is None:
+    raise SystemExit("No trigger within 5 s")
+
+print(f"{trace.analog.shape[1]} samples, {trace.time_ns[-1]:.0f} ns window, "
+      f"IN min/max {trace.analog[0].min()}/{trace.analog[0].max()}")
+print("digital tracks:", ", ".join(trace.digital))
+
+try:
+    import matplotlib.pyplot as plt
+except ImportError:
+    raise SystemExit("pip install matplotlib to plot")
+
+fig, (ax, axd) = plt.subplots(2, 1, sharex=True, figsize=(10, 6), gridspec_kw={"height_ratios": [3, 1]})
+labels = ["IN", "QDC IN" if channel != "trigger" else "CFD"]
+for i, a in enumerate(trace.analog):
+    ax.plot(trace.time_ns, a, label=labels[i] if i < len(labels) else f"A{i}")
+ax.set_ylabel("ADC")
+ax.legend()
+for k, (name, d) in enumerate(trace.digital.items()):
+    axd.step(trace.time_ns, d * 0.8 + k, where="post", label=name)
+axd.set_yticks([k + 0.4 for k in range(len(trace.digital))], list(trace.digital))
+axd.set_xlabel("Time (ns)")
+plt.tight_layout()
+plt.show()

quantumbox_sdk-2026.10.15.3/examples/03_calibration.py

@@ -0,0 +1,53 @@
+"""Calibration: acquire the hardware spectra, find zero and PE peaks, save PE thresholds.
+
+Same workflow as the GUI Calibration tab (Zero Peak → Fit → Save Thresholds).
+
+    python 03_calibration.py --ip 192.168.102.199 --seconds 30 --zero-roi 2500 3400
+"""
+
+import time
+
+from quantumbox import QuantumBox, SpectrumAnalysisConfig, Thresholds, analyze_spectrum, storage
+from _common import parser
+
+p = parser(__doc__)
+p.add_argument("--seconds", type=float, default=30)
+p.add_argument("--zero-roi", type=float, nargs=2, default=[0, 4000], help="ROI containing the zero peak")
+p.add_argument("--channels", type=int, nargs="*", default=list(range(8)))
+p.add_argument("--tails", action="store_true", help="fit heavy tails + background (non-Gaussian peaks)")
+p.add_argument("--out", default="thresholds.json")
+args = p.parse_args()
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    box.spectra.reset()
+    box.spectra.start()
+    print(f"Acquiring spectra for {args.seconds:.0f} s ...")
+    time.sleep(args.seconds)
+    spectra = box.spectra.read()
+    box.spectra.stop()
+
+cfg = SpectrumAnalysisConfig(
+    zero_roi_left=args.zero_roi[0], zero_roi_right=args.zero_roi[1], zero_sigma_multiplier=3,
+    min_peak_height_fraction=0.02, min_prominence=0.01, min_peak_distance=50, smooth_window=5,
+    peak_tail=args.tails, fit_background=args.tails)
+
+thresholds = Thresholds.load(args.out) if __import__("os").path.exists(args.out) else Thresholds()
+for ch in args.channels:
+    counts = spectra.get(ch)
+    if counts is None or counts.sum() == 0:
+        print(f"CH{ch}: no data")
+        continue
+    storage.save_spectrum(f"spectrum_ch{ch}.csv", counts, channel=ch)
+    res = analyze_spectrum(counts, cfg)
+    if not res.zero_found:
+        print(f"CH{ch}: zero peak not found in ROI {args.zero_roi}")
+        continue
+    entries = res.threshold_entries()
+    thresholds.merge(ch, entries)        # like 'Save Thresholds' choosing the new values
+    print(f"CH{ch}: zero {res.zero_center:.1f} (sigma {res.zero_sigma:.1f}), {len(res.peaks)} peaks, "
+          f"chi2/ndf {res.chi_red:.1f}, {len(entries)} PE windows")
+    for g in res.peaks[:4]:
+        print(f"    peak {g.center:8.1f}  sigma {g.sigma:6.1f}  height {g.amplitude:10.0f}")
+
+thresholds.save(args.out)
+print("Thresholds saved to", args.out)

quantumbox_sdk-2026.10.15.3/examples/04_photon_counting_run.py

@@ -0,0 +1,59 @@
+"""Photon counting run (List_0): save events, compute PE statistics and correlations live.
+
+Needs the thresholds from 03_calibration.py.
+
+    python 04_photon_counting_run.py --ip 192.168.102.199 --seconds 60 --format npy
+"""
+
+import numpy as np
+
+from quantumbox import (QuantumBox, Thresholds, classify_pe, correlation, pe_histogram,
+                        pe_statistics, region_statistics, storage)
+from _common import parser
+
+p = parser(__doc__)
+p.add_argument("--seconds", type=float, default=30)
+p.add_argument("--format", choices=storage.FORMATS, default="bin")
+p.add_argument("--prefix", default="quantumbox_data")
+p.add_argument("--run", type=int, default=1)
+p.add_argument("--thresholds", default="thresholds.json")
+p.add_argument("--pair", type=int, nargs=2, default=[0, 1], help="channel pair for correlations")
+args = p.parse_args()
+
+thr = Thresholds.load(args.thresholds)
+channels = thr.channels()
+pe_hist = {ch: np.zeros(64, dtype=np.int64) for ch in channels}
+energy_hist = {ch: np.zeros(65536, dtype=np.int64) for ch in channels}
+pairs = []                                                     # (peA, peB) batches
+
+
+def process(batch):
+    for ch in channels:
+        e = batch["energy"][:, ch]
+        energy_hist[ch] += np.bincount(e, minlength=65536)[:65536]
+        pe_hist[ch] += pe_histogram(classify_pe(e, thr[ch]), max_pe=63)
+    a, b = args.pair
+    if a in thr and b in thr:
+        pairs.append((classify_pe(batch["energy"][:, a], thr[a]), classify_pe(batch["energy"][:, b], thr[b])))
+
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    box.set_operating_mode("counting")
+    path = storage.run_file_name(args.prefix, args.run, args.format)
+    with storage.CountingWriter(path) as writer, box.counting_list() as lst:
+        lst.acquire(duration_s=args.seconds, writer=writer, on_batch=process)
+        print(f"{writer.events} events saved to {path} ({lst.bytes_read / 1e6:.1f} MB)")
+
+for ch in channels:
+    s = pe_statistics(pe_hist[ch])
+    print(f"CH{ch}: mean {s['mean']:.3f}  var {s['variance']:.3f}  Fano {s['fano']:.3f}  g2 {s['g2']:.3f}")
+    for r in region_statistics(energy_hist[ch], thr[ch])[:4]:
+        extra = f"  dpp {r['delta_pp']:.1f}+/-{r['delta_pp_err']:.1f}" if "delta_pp" in r else ""
+        print(f"    PE {r['pe']}: mean {r['mean']:.1f}+/-{r['mean_err']:.2f}  std {r['std']:.1f}{extra}")
+
+if pairs:
+    a = np.concatenate([x for x, _ in pairs])
+    b = np.concatenate([y for _, y in pairs])
+    c = correlation(a, b)
+    print(f"CH{args.pair[0]}-CH{args.pair[1]}: g11 {c['g11']:.4f}  NRF {c['nrf']:.4f}  gamma {c['gamma']:.4f}  "
+          f"coincidences {c['coincidences']}")

quantumbox_sdk-2026.10.15.3/examples/05_photon_timing_run.py

@@ -0,0 +1,55 @@
+"""Photon timing run (List_1): save events and build inter-arrival / channel-difference histograms.
+
+    python 05_photon_timing_run.py --ip 192.168.102.199 --seconds 30 --pair 0 1
+"""
+
+import numpy as np
+
+from quantumbox import QuantumBox, Thresholds, difference_histogram, interarrival_histogram, storage
+from _common import parser
+
+p = parser(__doc__)
+p.add_argument("--seconds", type=float, default=30)
+p.add_argument("--format", choices=storage.FORMATS, default="bin")
+p.add_argument("--mode", choices=["raw", "processed"], default="raw")
+p.add_argument("--per-channel", action="store_true", help="one file per channel")
+p.add_argument("--thresholds", default=None, help="needed for photons in processed mode")
+p.add_argument("--pair", type=int, nargs=2, default=[0, 1])
+p.add_argument("--run", type=int, default=1)
+args = p.parse_args()
+
+thr = Thresholds.load(args.thresholds) if args.thresholds else None
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    box.set_operating_mode("timing")
+    with storage.TimingWriter(".", run=args.run, fmt=args.format, mode=args.mode,
+                              per_channel=args.per_channel, thresholds=thr) as writer, \
+            box.timing_list() as lst:                      # LE/CFD encoding read from the board
+        print("Timestamp encoding:", "CFD" if lst.cfd else "leading edge")
+        batches = []
+
+        def keep(batch):
+            batches.append(batch)
+
+        lst.acquire(duration_s=args.seconds, writer=writer, on_batch=keep)
+        print(f"{writer.events} events saved:", ", ".join(str(p) for p in writer.paths.values()))
+
+events = np.concatenate(batches) if batches else np.empty(0)
+if len(events) == 0:
+    raise SystemExit("no events")
+
+for ch in np.unique(events["channel"]):
+    n = int(np.sum(events["channel"] == ch))
+    counts, edges = interarrival_histogram(events["time_ns"], events["channel"], int(ch), range_ns=1e5, bins=1000)
+    mean_dt = np.diff(events["time_ns"][events["channel"] == ch]).mean() if n > 1 else float("nan")
+    print(f"CH{ch}: {n} events, mean inter-arrival {mean_dt:.0f} ns")
+
+a, b = args.pair
+counts, edges = difference_histogram(events["time_ns"], events["channel"], a, b, range_ns=20, bins=4000, signed=True)
+if counts.sum():
+    centers = (edges[:-1] + edges[1:]) / 2
+    peak = centers[np.argmax(counts)]
+    sel = np.abs(centers - peak) < 2
+    mu = np.average(centers[sel], weights=counts[sel])
+    sigma = np.sqrt(np.average((centers[sel] - mu) ** 2, weights=counts[sel]))
+    print(f"t(CH{a}) - t(CH{b}): peak {mu * 1000:.1f} ps, sigma {sigma * 1000:.1f} ps ({counts.sum()} pairs)")

quantumbox_sdk-2026.10.15.3/examples/06_hw_counters_coincidence.py

@@ -0,0 +1,28 @@
+"""Hardware counters (rates per channel) and hardware coincidence units.
+
+    python 06_hw_counters_coincidence.py --ip 192.168.102.199 --seconds 10
+"""
+
+from quantumbox import QuantumBox
+from _common import parser
+
+p = parser(__doc__)
+p.add_argument("--seconds", type=float, default=10)
+args = p.parse_args()
+
+with QuantumBox(args.ip, register_file=args.register_file) as box:
+    # coincidence unit 0: CH0 AND CH1; unit 1: CH2 AND CH3
+    coinc = box.coincidence()
+    cfg = coinc.read_config()
+    cfg.widths = [10] * 8          # trigger pulse width per channel (TRG_C_WIDTH)
+    cfg.delays = [0] * 8           # trigger delay per channel (TRG_C_DELAY)
+    coinc.apply(cfg)
+    coinc.set_unit(0, [0, 1])
+    coinc.set_unit(1, [2, 3])
+
+    start = coinc.counts()
+    for r in box.counters().monitor(interval_s=1.0, duration_s=args.seconds):
+        rates = "  ".join(f"CH{i}:{v:9.0f}" for i, v in enumerate(r["rate_1s"]))
+        print(f"t={r['t']:5.1f}s  {rates} Hz")
+    end = coinc.counts()
+    print("Coincidences in the run:", [e - s for s, e in zip(start, end)][:2], "(units 0, 1)")

quantumbox_sdk-2026.10.15.3/examples/07_offline_analysis.py

@@ -0,0 +1,47 @@
+"""Offline analysis of files saved by QUANTA or by the SDK — no hardware needed.
+
+    python 07_offline_analysis.py spectrum_ch2.csv
+    python 07_offline_analysis.py quantumbox_data_run1.bin --thresholds thresholds.json
+"""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from quantumbox import (SpectrumAnalysisConfig, Thresholds, analyze_spectrum, classify_pe,
+                        pe_histogram, pe_statistics, storage)
+
+p = argparse.ArgumentParser(description=__doc__)
+p.add_argument("file")
+p.add_argument("--thresholds", default=None)
+p.add_argument("--zero-roi", type=float, nargs=2, default=[0, 4000])
+p.add_argument("--plot", action="store_true")
+args = p.parse_args()
+path = Path(args.file)
+
+if path.name.startswith("spectrum"):
+    counts = storage.load_spectrum(path)
+    cfg = SpectrumAnalysisConfig(zero_roi_left=args.zero_roi[0], zero_roi_right=args.zero_roi[1],
+                                 min_peak_distance=50, peak_tail=True, fit_background=True)
+    res = analyze_spectrum(counts, cfg)
+    print(f"zero {res.zero_center:.1f}, {len(res.peaks)} peaks, chi2/ndf {res.chi_red:.1f}")
+    for e in res.threshold_entries()[:8]:
+        print(f"  PE {e.pe}: [{e.low}, {e.high})")
+    if args.plot:
+        import matplotlib.pyplot as plt
+        plt.semilogy(np.maximum(counts, 0.1), label="data")
+        plt.semilogy(np.maximum(res.fit_curve, 0.1), label="fit")
+        for t in res.thresholds:
+            plt.axvline(t, color="orange", lw=0.6, ls="--")
+        plt.legend()
+        plt.xlabel("ADC bin")
+        plt.show()
+else:
+    events = storage.load_counting(path)
+    print(f"{len(events)} events, {events['timestamp'][-1] * 4e-9 - events['timestamp'][0] * 4e-9:.1f} s")
+    if args.thresholds:
+        thr = Thresholds.load(args.thresholds)
+        for ch in thr.channels():
+            s = pe_statistics(pe_histogram(classify_pe(events["energy"][:, ch], thr[ch])))
+            print(f"CH{ch}: mean PE {s['mean']:.3f}, Fano {s['fano']:.3f}, g2 {s['g2']:.3f}")

quantumbox_sdk-2026.10.15.3/examples/_common.py

@@ -0,0 +1,10 @@
+"""Shared command line options for the examples."""
+
+import argparse
+
+
+def parser(description: str) -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description=description)
+    p.add_argument("--ip", default="192.168.102.199", help="QuantumBOX address (IP or IP:PORT)")
+    p.add_argument("--register-file", default=None, help="firmware register map (default: bundled daq1x1.json)")
+    return p