tldecpy 1.0.0

TLDecPy core library for thermoluminescence glow-curve deconvolution.

TLDecPy: Thermoluminescence Glow-Curve Deconvolution in Python

tldecpy is an open-source scientific Python library for thermoluminescence (TL) glow-curve analysis, nonlinear deconvolution, and kinetic-model benchmarking.

The project is designed for reproducible research workflows in radiation dosimetry and TL materials analysis, with typed APIs and physically motivated models.

Supported Kinetic Models

TLDecPy includes single-peak and multi-peak deconvolution with:

• First-order (FO): fo_rq, fo_ka, fo_wp, fo_rb
• Second-order (SO): so_ks, so_la
• General-order (GO): go_kg, go_rq, go_ge
• One-Trap One-Recombination center (OTOR): otor_lw (Lambert W), otor_wo (Wright Omega)
• Mixed-order families: mo_kitis, mo_quad, mo_vej
• Continuous trap-distribution models (Gaussian and Exponential forms)

Highlights

• Multi-component deconvolution with robust losses and optional Poisson weighting
• Automatic initialization helpers (autoinit_multi, peak detection, preprocessing)
• Uncertainty metrics and diagnostics in fit outputs
• Synthetic data generation utilities for method validation
• Bundled Refglow benchmark datasets (x001 to x010)
• Typed models and results (py.typed, Pydantic v2 schemas)

Installation

From source

git clone https://github.com/HideOnParadise/TLDecPy.git
cd TLDecPy
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Planned PyPI install

pip install tldecpy

Quickstart

import tldecpy as tl

# 1) Load a reference glow curve (Refglow)
T, I = tl.load_refglow("x001")

# 2) Automatic initialization of peaks and optional background
peaks, bg = tl.autoinit_multi(
    T,
    I,
    max_peaks=3,
    allow_models=("fo_rq", "go_kg", "otor_lw"),
    bg_mode="auto",
)

# 3) Run deconvolution
result = tl.fit_multi(
    T,
    I,
    peaks=peaks,
    bg=bg,
    beta=1.0,
    robust=tl.RobustOptions(loss="soft_l1", f_scale=2.0, weights="poisson"),
    options=tl.FitOptions(local_optimizer="trf"),
)

print("Converged:", result.converged)
print("R2:", f"{result.metrics.R2:.4f}", "FOM:", f"{result.metrics.FOM:.3f}%")
for peak in result.peaks:
    print(peak.name, peak.model, peak.params)

For an end-to-end OTOR demonstration, see:

• examples/example_otor_fit.py
• examples/example_refglow002_manual_fit.py (manual Refglow x002 deconvolution)

Development Quality Checks

make lint
make typecheck
make test
make qa

Citation

If TLDecPy contributes to your research, please cite the software archive (Zenodo DOI once released).

Suggested BibTeX entry:

@software{romero2026tldecpy,
  title   = {TLDecPy},
  author  = {Romero, Cesar},
  year    = {2026},
  url     = {https://github.com/HideOnParadise/TLDecPy},
  note    = {Zenodo DOI to be added after first release}
}

License

This project is distributed under the BSD 3-Clause License. See LICENSE.