Metadata-Version: 2.5
Name: quantumbox-sdk
Version: 2026.10.15.6
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://public-repo.pages.nuclearinstruments.eu/quantum-optics/quantumbox-sdk/python-sdk/
Project-URL: Repository, https://gitlab.nuclearinstruments.eu/public-repo/quantum-optics/quantumbox-sdk
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: <https://public-repo.pages.nuclearinstruments.eu/quantum-optics/quantumbox-sdk/python-sdk/> (Python SDK chapter of the QUANTA user manual)

Source: <https://gitlab.nuclearinstruments.eu/public-repo/quantum-optics/quantumbox-sdk>

## License

MIT — © Nuclear Instruments
