TDCRPy
A Photo-Physical Stochastic Model for Liquid Scintillation Counting
📖 Overview
TDCRPy is a Python package developed and maintained by the BIPM (Bureau International des Poids et Mesures). It estimates detection efficiencies of liquid scintillation counters using the TDCR (Triple to Double Coincidence Ratio) or CIEMAT/NIST methods.
The calculation is based on a photo-physical stochastic Monte Carlo model, allowing users to address:
- Complex decay schemes (beta spectra via BetaShape, gamma interactions via MCNP matrices).
- Radionuclide mixtures with arbitrary activity fractions.
- Ionisation quenching via the Birks model (electrons and alpha particles).
- Reverse micelle effects in cocktails used for aqueous samples.
- Asymmetric PMT configurations (per-channel free parameters).
- Full optical Monte Carlo transport (
opticalTransport=True). - C/N (CIEMAT/NIST) 2-PMT efficiency curves.
Technical details are described in:
📦 Installation
TDCRPy requires Python ≥ 3.11 and a standard scientific environment.
pip install TDCRPy
To upgrade to the latest version:
pip install TDCRPy --upgrade
Run Tests
Verify the installation by running the unit tests:
python -m unittest tdcrpy.test.test_tdcrpy
⚡ Quick Start
Estimate detection efficiencies for Co-60 using the full stochastic model.
import tdcrpy
L = 1.2 # free parameter (photons keV⁻¹)
Rad = "Co-60" # radionuclide
pmf = "1" # activity fraction (100 %)
N = 10000 # Monte Carlo trials (≥ 10 000 recommended)
kB = 1.0e-5 # Birks constant (cm keV⁻¹)
V = 10 # scintillator volume (mL)
result = tdcrpy.TDCRPy.TDCRPy(L, Rad, pmf, N, kB, V)
print(f"eff_S = {result[0]:.4f} ± {result[1]:.4f}") # single events
print(f"eff_D = {result[2]:.4f} ± {result[3]:.4f}") # double coincidences
print(f"eff_T = {result[4]:.4f} ± {result[5]:.4f}") # triple coincidences
Find L from a Measured TDCR Ratio
TD = 0.9776 # measured T/D ratio
result = tdcrpy.TDCRPy.eff(TD, Rad, pmf, kB, V)
print(f"L = {result[0]:.4f} photons/keV")
print(f"eff_T = {result[6]:.4f} ± {result[7]:.4f}")
🛠 Advanced Features
Asymmetric PMT Configuration
Pass a 3-tuple for the free parameter to model per-channel asymmetry:
L = (1.1, 1.3, 1.2) # (L_A, L_B, L_C) in photons keV⁻¹
result = tdcrpy.TDCRPy.TDCRPy(L, "Co-60", "1", N, kB, V)
print(f"eff_AB = {result[6]:.4f}") # A–B double coincidences
print(f"eff_BC = {result[8]:.4f}")
print(f"eff_AC = {result[10]:.4f}")
Radionuclide Mixtures
Provide comma-separated nuclides and their relative activity fractions:
result = tdcrpy.TDCRPy.TDCRPy(L, "Co-60, H-3", "0.8, 0.2", N, kB, V)
Analytical Model (Pure Beta Emitters)
A faster, deterministic alternative for pure β⁻ nuclides:
# Returns (L0, L_opt, eff_S, eff_D, eff_T)
result = tdcrpy.TDCRPy.effA(TD, "H-3", "1", kB, V)
print(f"L0 = {result[0]:.4f} photons/keV")
print(f"eff_T = {result[4]:.4f}")
Full Optical Monte Carlo Transport
Enable stochastic photon-transport for each event: photons are sampled from a Poisson distribution, distributed equally among PMTs, and converted to photoelectrons via Binomial draws (quantum efficiency):
result = tdcrpy.TDCRPy.TDCRPy(L, Rad, pmf, N, kB, V, opticalTransport=True)
C/N Efficiency Curve
Compute the CIEMAT/NIST efficiency curve — detection efficiency as a function of the free parameter L for a 2-PMT coincidence system:
import numpy as np
import matplotlib.pyplot as plt
import tdcrpy.TDCR_model_lib as tl
rad = "H-3"
kB = 1e-5 # Birks constant (cm keV⁻¹)
V = 10 # volume (mL)
ne = 1000 # quenching integration bins
L_vec = np.linspace(1, 20, 80)
eff_D = np.array([tl.modelAnalyticalCN(L, rad, kB, V, ne)[2] for L in L_vec])
plt.plot(L_vec, eff_D)
plt.xlabel("L (photons keV⁻¹)")
plt.ylabel("eff_D (double coincidence)")
plt.title(f"C/N efficiency curve — {rad}")
plt.grid(True)
plt.show()
To find L from a measured C/N counting ratio CN (counts_D / counts_S):
from scipy.optimize import brentq
CN_meas = 0.62 # measured D/S ratio
def residual(L):
eA, eB, eD = tl.modelAnalyticalCN(L, rad, kB, V, ne)
return eD / ((eA + eB) / 2) - CN_meas
L0 = brentq(residual, 0.5, 30)
_, _, eff_D = tl.modelAnalyticalCN(L0, rad, kB, V, ne)
print(f"L = {L0:.3f} photons/keV, eff_D = {eff_D:.5f}")
⚙️ Configuration & Physics
Display the current physics settings:
import tdcrpy as td
td.TDCR_model_lib.readParameters(disp=True)
Configuration Reference
| Parameter | Setter | Default | Unit | Description |
|---|---|---|---|---|
| Electron bins | modifynE_electron(n) |
1000 | — | Integration bins for electron quenching |
| Alpha bins | modifynE_alpha(n) |
1000 | — | Integration bins for alpha quenching |
| Stopping power | modifysp_model(m) |
tan_xia |
— | Low-energy model (tan_xia, joy_luo, …) |
| Birks parameter | modifyChou_param(k) |
0 | cm²/MeV² | Chou bimolecular quenching constant |
| Density | modifyDensity(ρ) |
0.98 | g/cm³ | Scintillator density (Ultima Gold) |
| Mean Z / A | modifyZ(z), modifyA(a) |
3.25 / 5.94 | — | Effective atomic/mass number |
| Cocktail | modifyLScocktail(name, fAq) |
Ultima Gold |
— | LS cocktail + aqueous fraction |
| Micelle correction | modifyMicCorr(b) |
False | — | Activate reverse-micelle correction |
| Micelle diameter | modifyDiam_micelle(d) |
2 | nm | Mean micelle diameter |
| Quantum efficiency | modifyEffQ(q) |
0.25,0.25,0.25 |
— | PMT quantum efficiencies (A, B, C) |
| Optical transport | modifyOpticalTransport(b) |
False | — | Enable full optical MC transport |
| Resolving time | modifyTau(τ) |
50 | ns | Coincidence resolving time |
| Dead time | modifyDeadTime(t) |
30 | µs | Extended dead time |
| Measurement time | modifyMeasTime(T) |
60 | min | Measurement duration |
📓 Notebooks
Notebooks are organised in subfolders by topic under notebooks/.
Getting started — notebooks/getting_started/
| Notebook | Description |
|---|---|
| tuturial.ipynb | End-to-end tutorial: fixed-L efficiencies, TDCR fitting (symmetric and asymmetric), radionuclide mixtures, full optical MC transport |
| changeParameters.ipynb | Configuration: how to modify every physics parameter (quenching bins, stopping power model, cocktail, PMT efficiencies, dead time…) |
Detection models — notebooks/models/
| Notebook | Description |
|---|---|
| analyticalModel.ipynb | Analytical model (effA): fast beta-spectrum-based efficiency for pure β emitters; symmetric and asymmetric PMT configurations |
| CNmethod.ipynb | CIEMAT/NIST (C/N) method: 2-PMT coincidence efficiency curve using modelAnalyticalCN; L-fitting from measured C/N ratio |
| cerenkovModel.ipynb | Čerenkov counting model: Frank-Tamm-based efficiency for high-energy beta emitters |
| cerenkovY90.ipynb | Čerenkov model, worked example (Y-90): threshold physics, Frank-Tamm photon yield, efficiency vs L, fitting L from a measured TDCR (symmetric and 3-PMT), optical parameters, and ⁹⁰Sr/⁹⁰Y discrimination |
| opticalTransport.ipynb | Optical MC transport: comparison of semi-analytical vs full photon-transport model (opticalTransport=True) for H-3, Fe-55, Co-60 |
Nuclide case studies — notebooks/nuclides/
| Notebook | Description |
|---|---|
| H-3.ipynb | Tritium (H-3): low-energy pure β; analytical and stochastic efficiency, micelle correction effect |
| Co-60.ipynb | Co-60: γ-emitter with complex decay; analytical approximation vs full stochastic model |
| Fe-55.ipynb | Fe-55: electron-capture nuclide producing Mn K-α X-rays and Auger electrons |
| Sr-90_Y-90.ipynb | Sr-90/Y-90 mixture: secular equilibrium of two pure β emitters (0.546 and 2.28 MeV endpoints) |
| Zr-93.ipynb | Zr-93: β/EC branching ratio nuclide with X-ray emission |
Physics sub-models — notebooks/physics/
| Notebook | Description |
|---|---|
| quenchingModel.ipynb | Birks quenching: quenched energy vs initial energy for electrons and α particles as a function of kB |
| stoppingPower.ipynb | Stopping power models: comparison of tan_xia, joy_luo, ashley and other models for electrons |
| readBetaSpectrum.ipynb | Beta spectra: reading and visualising deposited-energy spectra from BetaShape + MCNP calculations |
| interaction.ipynb | Radiation–matter interactions: photon and electron energy deposition via MCNP response matrices |
| micelleEffects.ipynb | Micellar quenching: stochastic reverse-micelle model (micCorr); microscopic energy-retention factor and its impact on efficiency for H-3, Fe-55, Ni-63, C-14, Tc-99, at fixed L and with eff() TDCR calibration |
Advanced — notebooks/advanced/
| Notebook | Description |
|---|---|
| mixture.ipynb | Radionuclide mixtures: efficiency of arbitrary multi-component samples with activity fractions |
| efficiencyCuve.ipynb | TDCR efficiency curve: eff_D and eff_T vs light yield L for a series of kB values |
| distrubutionTDCR.ipynb | TDCR distribution: histogram of per-event efficiency values over MC trials; statistical characterisation |
| cocktailComposition.ipynb | Cocktail composition: effect of aqueous fraction (H₂O / HCl) on detection efficiency for H-3 and Sr-90 |
| cocktailResponse.ipynb | Cocktail comparison: eff_D for 12 commercial LS cocktails × 6 nuclides (H-3, C-14, Fe-55, Cr-51, Co-60, Cd-109) |
Sensitivity — notebooks/sensitivity/
| Notebook | Description |
|---|---|
| parameterSensitivity.ipynb | Parameter sensitivity study: sweeps every tunable model parameter (L, kB, PMT quantum efficiency, cocktail composition, stopping-power model, quenching numerics, micelle correction, counting-chain parameters, optical transport, MC convergence) around its nominal value for H-3 and Sr-90, with a summary tornado chart |
Validation — notebooks/validation/
| Notebook | Description |
|---|---|
| functional_validation.ipynb | Cross-version validation: compare two TDCRPy versions side-by-side for H-3, Fe-55, Co-60, Sr-90, Cd-109 across analytical and stochastic models; configurable VERSION_REF / VERSION_NEW |
📚 Citation
If you use TDCRPy in your work, please cite:
R. Coulon, J. Hu — TDCRPy: A Python package for TDCR measurements
Applied Radiation and Isotopes (2024)
DOI: 10.1016/j.apradiso.2024.111518
⚖️ License
This project is licensed under the MIT License.
Copyright © BIPM (Bureau International des Poids et Mesures).
1 maintainer
Release files for TDCRPy 2.20.21
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tdcrpy-2.20.21.tar.gz | 22.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tdcrpy-2.20.21-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 46.0 MB
Release files / tdcrpy-2.20.21.tar.gz
| Download URL | tdcrpy-2.20.21.tar.gz |
|---|---|
| Size | 22.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1dd24342760808cdd1d903056c769ba327851068849642724428b558e0adf31
|
|
BLAKE2b-256 checksum How to use checksums |
bd48b870b98b4e28066e0dec7ea2ba9b09dc59ede128985c924b7bf7d3068ade
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / tdcrpy-2.20.21-py3-none-any.whl
| Download URL | tdcrpy-2.20.21-py3-none-any.whl |
|---|---|
| Size | 23.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc2d9a11f0de744425c81dfb24d64f38dd183fc7c88aafb2f27ebc6c1167c967
|
|
BLAKE2b-256 checksum How to use checksums |
3937f0d836f71d84e9fed7a8e26fda1e5e277acdf7c8151294f09784cbb9ba12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
