Metadata-Version: 2.4
Name: sparq-triage
Version: 0.2.0
Summary: Spiking physics-in-the-loop autonomous reinforcement triage of single-photon emitters (SPARQ)
Author-email: Tanvir Mahmud Mahim <tanvir.mahim@bracu.ac.bd>
License: Apache-2.0
Project-URL: Homepage, https://github.com/TaN-MM-Org/sparq-triage
Project-URL: Issues, https://github.com/TaN-MM-Org/sparq-triage/issues
Keywords: single-photon emitters,g2,HBT,spiking neural networks,reinforcement learning,quantum optics,digital twin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: ml
Requires-Dist: torch>=2.0; extra == "ml"
Provides-Extra: figures
Requires-Dist: matplotlib>=3.7; extra == "figures"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: torch>=2.0; extra == "test"
Dynamic: license-file

# SPARQ

[![Tests](https://github.com/TaN-MM-Org/sparq-triage/actions/workflows/tests.yml/badge.svg)](https://github.com/TaN-MM-Org/sparq-triage/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/sparq-triage)](https://pypi.org/project/sparq-triage/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22278041-blue)](https://doi.org/10.5281/zenodo.22278041)

**S**piking **P**hysics-in-the-loop **A**utonomous **R**einforcement triage
of **Q**uantum emitters: the installable `sparq` package behind the manuscript
*"Closed-loop, event-driven machine learning for autonomous triage of
single-photon emitters."* The manuscript's companion repository,
[a-spiking-RL-triage-of-solid-state-single-photon-emitters](https://github.com/Tanvir-Mahmud-Mahim/a-spiking-RL-triage-of-solid-state-single-photon-emitters),
holds the experiment scripts, figure scripts and results that reproduce the
paper; this repository is the software's home for development, releases and
support.

## Installation

```bash
pip install sparq-triage        # physics core (numpy, scipy)
pip install sparq-triage[ml]    # adds PyTorch for the estimators, twin and RL
```

The core (`sparq.physics`, `sparq.exact`, `sparq.pulsed`) imports without
PyTorch: the analytic HBT correlation functions, the exact-statistics
histogram twin, the master-equation reference and the pulsed comb analysis.

```python
import numpy as np
from sparq import HBTConfig, sample_site, expected_histogram

rng = np.random.default_rng(0)
site = sample_site(rng, platform="NV")     # literature-anchored priors
mu = expected_histogram(site, T_s=5.0, cfg=HBTConfig())
print(site.g2_0, site.is_good, mu.shape)
```

## Analyzing your own data

`analyze_histogram` runs the full conventional pipeline on any measured CW
HBT histogram (dip centering, re-binning, flat-level normalization,
multi-start fit) and reports g2(0) with a parametric-bootstrap confidence
interval that propagates shot noise through every analysis step;
`analyze_pulsed` does the same for pulsed combs via the peak-area method.
Neither needs PyTorch.

```python
from sparq import analyze_histogram
res = analyze_histogram(delay_ns, counts, T_s=30.0, n_bootstrap=200)
print(res["g2_0"], (res["g2_0_low"], res["g2_0_high"]),
      res["single_emitter_confident"])
```

## Registering your own platform

The built-in priors (NV, hBN, GaN, SiV) are literature-anchored defaults,
not a limit: `register_platform` adds any emitter with your own
photophysical ranges, after which it works everywhere a platform name is
accepted (site sampling, the dataset generators, the triage environment,
the graph encoder's template).

```python
from sparq import Platform, register_platform, sample_site
register_platform(Platform("MyQD", (0.5, 2.0), (20, 400), (0.0, 0.5),
                           (50, 500), (0.7, 0.99), 0.05, (5, 100), (0.5, 10)))
site = sample_site(rng, platform="MyQD")
```

## What is in the package

```
sparq/
  physics.py            emitter photophysics, platform priors, HBT twin
                        (exact Poisson histogram statistics) and the full
                        Monte-Carlo photon-stream simulator w/ detector
                        impairments
  exact.py              numerically exact master-equation g2(tau)
  pulsed.py             pulsed-excitation twin + comb calibration +
                        conventional peak-area analysis
  analysis.py           g2 analysis of measured data with bootstrap
                        uncertainties (CW and pulsed; torch-free)
  datasets.py           synthetic acquisition generators + loader for the
                        real sps-quality quantum-dot HBT data
  estimators.py         LM-fit baseline, CNN, surrogate-gradient spiking
                        network, physics-in-the-loop training
  twin_torch.py         differentiable twin (adjoint/pathwise gradients
                        through the measurement protocol) + profile
                        Fisher information
  sac_per.py            discrete-action Soft Actor-Critic + prioritized
                        experience replay (sum-tree)
  rl_env.py             closed-loop emitter-triage environment + baselines
  gnn.py                level-structure template graphs + message-passing
                        encoder for cross-platform transfer
```

## Tests

```bash
pip install -e .[test]
pytest tests -q     # a few seconds; ML tests skip when torch is absent
```

The suite pins the physics to exact references: the two-exponential g2 law
against the master-equation eigen-decomposition, the closed-form IRF
convolution against brute-force quadrature, Poisson statistics of the
histogram twin, comb calibration and peak-area recovery, sum-tree replay
proportionality, and the shape/gradient contracts of the estimators, the
differentiable protocol twin and the triage environment. It runs in CI on
every push and pull request.

## Real data

The experimental quantum-dot HBT measurements used by
`sparq.datasets.load_fisequr` are from the openly licensed
[sps-quality](https://github.com/UTS-CASLab/sps-quality) repository
(Kedziora et al., *Mach. Learn.: Sci. Technol.* **4**, 045042 (2023));
they are not redistributed here.

## Contributing and support

Bug reports, questions and pull requests are welcome through
[GitHub issues](https://github.com/TaN-MM-Org/sparq-triage/issues); see
[CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and the design
rules. Tagged releases are published to PyPI by CI.

## License and citation

Apache-2.0 (see LICENSE). Please cite the associated paper if you use this
code; citation metadata is in [CITATION.cff](CITATION.cff).
