BSSunfold

BSSUnfold is a Python package for neutron spectrum unfolding from measurements obtained with Bonner Sphere Spectrometers (BSS). The package implements several mathematical algorithms for solving the inverse problem of unfolding neutron energy spectra from detector readings, with applications in radiation protection, nuclear physics research, and accelerator facilities.

Features

Multiple Unfolding Algorithms:
- Tikhonov regularization with convex optimization (CVXPY)
- Landweber iterative method
- Combined approach for improved accuracy
Radiation Dose Calculations:
- INTERNATIONAL COMMISSION ON RADIOLOGICAL PROTECTION (ICRP), publication 116: conversion coefficients for effective dose
Comprehensive Data Management:
- Automatic response function processing
- Uncertainty quantification via Monte Carlo methods
Advanced Visualization:
- Spectrum plotting with uncertainty bands
- Detector reading comparisons

Installation

Using pip

Using uv (recommended)

From Source

Quick Start

Input Data Structure

Response Functions

Response functions must be provided as a CSV file with the following format:

E_MeV,0in,2in,3in,5in,8in,10in,12in
1.00E-09,0.001,0.005,0.01,0.02,0.03,0.04,0.05
1.00E-08,0.002,0.006,0.012,0.022,0.032,0.042,0.052
...

Detector Readings

Readings should be provided as a dictionary mapping sphere names to measured values:

Available Methods

1. `unfold_cvxpy()`

Tikhonov regularization with convex optimization for stable spectrum reconstruction.

2. `unfold_landweber()`

Iterative Landweber method with convergence control.

Output Data

The package provides comprehensive output in standardized formats:

Spectrum Results

Energy grid in MeV
Unfolded neutron spectrum for the grid of energy bins
Uncertainty estimates (if calculated)

Dose Calculations

Effective dose rates for different geometries:
- AP (Anterior-Posterior)
- PA (Posterior-Anterior)
- LLAT (Left Lateral)
- RLAT (Right Lateral)
- ROT (Rotational)
- ISO (Isotropic)

Quality Metrics

Residual norms
Convergence status
Iteration counts
Monte Carlo statistics

Application Areas

Nuclear Research Facilities

Neutron spectroscopy at particle accelerators
Reactor neutron field characterization
Fusion device diagnostics

Radiation Protection

Workplace monitoring at nuclear power plants
Medical accelerator facilities
Industrial radiography installations

Scientific Research

Space radiation studies
Cosmic ray neutron measurements
Nuclear physics experiments

Advanced Features

Result Management

Custom Uncertainty Analysis

Data Structure

bssunfold/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── data/
│   └── response_functions/
│       └── rf_GSF.csv
├── docs/
│   ├── conf.py
│   ├── makefile
│   ├── requirements.txt
│   └── source/
│       ├── conf.py
│       ├── detector.rst
│       ├── examples.rst
│       └── index.rst
├── example/
│   └── 01-basic-example.ipynb
├── favicon.ico
├── LICENSE
├── pyproject.toml
├── README.md
├── requirements.txt
├── src/
│   └── bssunfold/
│       ├── __init__.py
│       ├── constants.py
│       └── detector.py
├── tests/
│   └── test_detector.py

Technical Requirements

Minimum Requirements

Python 3.12 or higher
NumPy >= 1.21.0
SciPy >= 1.7.0
Pandas >= 1.3.0

Optional Dependencies

CVXPY >= 1.1.0 (for convex optimization)
Matplotlib >= 3.5.0 (for visualization)

Performance

Matrix Operations: Optimized NumPy operations for response matrices
Memory Efficient: Sparse matrix support for large energy grids
Parallel Processing: Monte Carlo simulations can be parallelized
Caching: Response matrices are cached for repeated use

Citation

If you use BSSUnfold in your research, please cite:

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Documentation

Documentation and API reference is available in /docs folder. Theory and methodology in the research paper, example of usage in /examples folder.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Support

For questions, bug reports, or feature requests:

Open an issue on GitHub
Contact: kchizhov@jinr.ru

Acknowledgments

ICRP and IAEA for data
Contributors and testers
Joint institure for Nuclear Research

References

Compendium of neutron spectra and detector responses for radiation protection purposes: supplement to technical reports series no. 318. — Vienna: International Atomic Energy Agency, 2001. — Technical reports series no. 403. — STI/DOC/010/403. — ISBN 92-0-102201-8.
Chizhov K., Beskrovnaya L., Chizhov A. Neutron spectra unfolding from Bonner spectrometer readings by the regularization method using the Legendre polynomials // Phys. Part. Nucl. — 2024. — V. 55. — P. 532–534. — DOI: https://doi.org/10.1134/S1063779624030298
Chizhov K., Beskrovnaya L., Chizhov A. Neutron spectrum unfolding method based on shifted Legendre polynomials, its application to the IREN facility // Phys. Part. Nucl. Lett. — 2025. — V. 22, no. 2. — P. 337–340. — DOI: https://doi.org/10.1134/S154747712470239X
Chizhov K., Chizhov A. Optimization approach to neutron spectra unfolding with Bonner multi-sphere spectrometer // Math. Model. — 2024. — V. 7. — P. 89–90.
Чижов А. В., Чижов К. А. Восстановление спектров опорных нейтронных полей на Фазотроне (ОИЯИ) на основе показаний многошарового спектрометра Боннера методом усеченного сингулярного разложения Тезисы Трудов LXI Всероссийской конференции по физике РУДН 19 - 23 мая 2025.
Chizhov, K., Chizhov, A., TSVD-based neutron spectra unfolding by Bonner multi-sphere spectrometer readings with iteration procedure, proceedings of the International Conference "Distributed Computing and Grid-technologies in Science and Education".

BSSUnfold - Professional neutron spectrum unfolding for radiation science and nuclear applications.