bssunfold Documentation

bssunfold is a Python package for neutron spectrum unfolding using various algorithms.

Contents:

• Package Overview
  • Unfolding Methods
  • Regularization Parameter Selection
  • Built-in Response Functions
  • Dose Conversion Coefficients
  • Spectrum Comparison Metrics
  • Performance
• Mathematical Formulation
  • General Inverse Problem
  • Parameter Selection and Stopping Criteria
  • Variational (Tikhonov-Type) Methods
  • Spectral Filtering and Krylov Methods
  • Algebraic Iterative Methods
  • First-Order Optimisation Methods (MIPT Course Port)
  • Iterative Ratio Methods (SAND-II Family)
  • Maximum Entropy and Information Divergence
  • Poisson-Likelihood (EM) Family
  • Quadratic Methods with Full Covariance Treatment
  • Bayesian and Stochastic Methods
  • Parametric Models
  • Meta-Strategies and Ensembles
  • References
  • Integration Notes
  • Integration Notes
• Detector Class
  • Detector
• Unfold Methods
  • unfold_cvxpy()
  • unfold_landweber()
  • unfold_mlem()
  • unfold_qpsolvers()
  • unfold_mystic()
  • unfold_mystic_hybrid()
  • unfold_genetic()
  • unfold_gnowee()
  • unfold_nnqp()
  • unfold_qpmad()
  • unfold_pgd()
  • unfold_frank_wolfe()
  • unfold_mirror_descent()
  • unfold_admm()
  • unfold_lbfgsb()
  • unfold_coordinate_descent()
  • unfold_subgradient()
  • unfold_extragradient()
  • unfold_smt()
  • unfold_scip()
  • unfold_docplex()
  • unfold_epic()
  • unfold_cs()
  • unfold_doroshenko()
  • unfold_directed_divergence()
  • unfold_kaczmarz()
  • unfold_lmfit()
  • unfold_mlem_odl()
  • unfold_mlem_stop()
  • unfold_combined()
  • unfold_interpret()
  • unfold_gravel()
  • unfold_maxed()
  • unfold_tikhonov_legendre()
  • unfold_bayes()
  • unfold_bayes_spline_regularization()
  • unfold_statreg()
  • unfold_reconst()
  • unfold_scipy_direct_method()
  • unfold_tsvd()
  • unfold_lanczos()
  • unfold_cgls()
  • unfold_gks()
  • unfold_tikhonov_tv()
  • unfold_sandii()
  • unfold_crystal_ball()
  • unfold_rfsp_jul()
  • unfold_staysl()
  • unfold_express()
  • unfold_bunki()
  • unfold_bunkiut()
  • unfold_osem()
  • unfold_mapem()
  • unfold_bsrem()
  • unfold_sart()
  • unfold_ferdor()
  • unfold_rebunki()
  • unfold_nsduaz()
  • unfold_parametric()
  • solve_parametric_cvxpy()
  • solve_parametric_qpsolvers()
  • solve_parametric_combined()
  • unfold_parametric2()
  • solve_parametric2()
  • solve_bon95_parametric()
  • directed_divergence_iteration()
  • solve_bon95_cvxpy()
  • solve_bon95_qpsolvers()
  • solve_bon95_combined()
  • unfold_fruit_like()
  • unfold_hybrid_parametric()
  • unfold_bayesian_parametric()
  • unfold_imaxed()
  • unfold_amaxed()
  • unfold_amaxed_regularization()
  • unfold_fista()
  • unfold_hybrid_gmres()
  • unfold_mcmc()
  • unfold_cuqi()
  • solve_cuqi_bayesian()
  • unfold_zfit()
  • unfold_qubo()
  • unfold_maeo()
  • unfold_odl_pdhg()
  • unfold_odl_douglas_rachford()
  • unfold_cascade()
  • unfold_composite()
  • unfold_binned()
  • unfold_ensemble()
  • unfold_iterative_refinement()
  • unfold_randomized_kaczmarz()
  • unfold_eki()
  • unfold_nnksvd()
• Core Functions
  • solve_cvxpy()
  • solve_landweber()
  • solve_mlem()
  • solve_mlem_stop()
  • solve_qpsolvers()
  • solve_mystic()
  • solve_mystic_hybrid()
  • solve_genetic()
  • solve_smt()
  • solve_scip()
  • solve_docplex()
  • solve_epic()
  • solve_interpret()
  • interpret_qp()
  • build_interpretation_qp()
  • solve_cs()
  • solve_omp()
  • solve_ksvd()
  • solve_sl0()
  • solve_doroshenko()
  • solve_directed_divergence()
  • solve_kaczmarz()
  • solve_lmfit()
  • select_regularization_aic_bic()
  • solve_gravel()
  • solve_maxed()
  • solve_tikhonov_legendre()
  • solve_bayes()
  • solve_bayes_spline()
  • solve_statreg()
  • solve_reconst()
  • solve_scipy_direct()
  • solve_tsvd()
  • solve_lanczos()
  • solve_cgls()
  • solve_gks()
  • solve_tikhonov_tv()
  • solve_sandii()
  • solve_crystal_ball()
  • solve_rfsp_jul()
  • solve_staysl()
  • solve_express()
  • solve_bunki()
  • solve_bunkiut()
  • solve_osem()
  • solve_mapem()
  • solve_bsrem()
  • solve_sart()
  • solve_ferdor()
  • solve_rebunki()
  • solve_nsduaz()
  • solve_randomized_kaczmarz()
  • solve_eki()
  • solve_binned()
  • build_bin_lookup()
  • solve_nnksvd_unfold()
  • solve_nnksvd()
  • solve_nnls_topk()
  • solve_nn_omp()
  • solve_tikhonov_nnls()
• Comparison Methods
  • compare_spectra()
  • compare_multiple()
• Comparison Metrics
  • Entropy-based
  • Distribution distances
  • Correlation
  • Error metrics
  • Kernel / similarity
  • Chi-squared family
  • Statistical tests
  • Integral quantity metrics
  • Spectral diagnostics (energy grid required)
• Regularization Selection
  • select_regularization_parameter()
  • lcurve_selection()
  • gcv_selection()
  • discrepancy_principle_selection()
  • cosine_similarity_selection()
  • quasi_optimality_selection()
  • ncp_selection()
  • snr_criterion_selection()
  • weighted_gcv_poisson_selection()
  • kfold_cv_selection()
• N-spline unfolding (Islamgulov & Lartsev, 2008)
  • Method outline
  • Stopping criteria and quality control
  • Knots
  • API
  • Usage
  • Notes and limitations
• B-spline MLEM unfolding (MLEM-BS)
  • Method outline
  • Penalty strength
  • Automatic parameter selection
  • Confidence intervals
  • Usage
• CUQIpy Bayesian unfolding: uncertainty-quantified MCMC
  • Bayesian model
  • Samplers
  • Diagnostics
  • Interpreting the posterior (CUQIpy interpretability)
  • Example
  • References
• P-spline mixed-model unfolding with REML smoothing selection
  • Method outline
  • Usage
  • Notes
• SSR unfolding: Sign-Simplicity-Regression solver (sisireg port)
  • Sign criteria
  • Unfolding scheme
  • Usage
  • Notes
  • Spatial regression: ssr3d
  • Neural regression: ssrMLP
• GEE unfolding: generalized estimating equations (gee port)
  • Working correlation structures
  • Quasi-likelihood families
  • Robust (sandwich) uncertainties
  • Example
  • Notes
• Uno unfolding: Lagrange-Newton NLP presets (Uno port)
  • Unfolding NLP
  • Presets
  • Diagnostics
  • Example
  • Notes
• Interpreting Unfolding Results
  • What the interpretation answers
  • API overview
  • Basic usage
  • How to use it to interpret a spectrum
  • How to use it to choose the detector sphere set
  • Worked example
• Examples
  • Basic Usage
  • Parametric Unfolding
  • BON95 Parametric Unfolding
  • Compressive Sensing (CS) Unfolding
  • Non-negative K-SVD (NN-KSVD) Unfolding
  • Maximum Neutron Energy Cutoff
• Сравнение с оригинальным кодом RECONST
  • Построение матриц B и A_vec
  • Матрица Omega (сглаживание)
  • Решение системы D·f = A·β
  • Обеспечение неотрицательности
  • Автоматический подбор α и β
  • Производительность
  • Численная устойчивость
  • Ограничения Python-версии
  • Тестирование
  • Идентичность результатов
• Multi-resolution cascades
  • What was implemented
  • Why it can help (assessment)
  • Evidence basis and limitations
  • How to use it

Indices and tables

• Index

• Module Index

• Search Page

Overview

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. Iterative solvers are accelerated with Numba JIT compilation for 3–50x speedups.

Features

• Multiple Unfolding Algorithms (88 methods): - Tikhonov-type: CVXPY, qpsolvers (L1/L2/smoothness), Legendre basis, TSVD, EPIC (Equal Posterior Information Condition) - Krylov/hybrid: Lanczos, GKS (Golub-Kahan bidiagonalization + projected GCV/DP/L-curve), CGLS, FISTA (accelerated proximal gradient), Hybrid GMRES - Iterative: Landweber, MLEM (pure NumPy + ODL), MLEM-STOP (J-factor stopping), GRAVEL, Doroshenko, Kaczmarz - Bayesian: D’Agostini (Bayes), Bayes with spline regularisation, zfit (Poisson likelihood), full Bayesian MCMC (NUTS via pymc), CUQIpy uncertainty-quantified MCMC (pCN, CWMH, ULA, MALA, NUTS, hierarchical Gibbs with Gamma hyperprior — posterior HPD intervals, ESS/R-hat diagnostics) - Maximum Entropy: MAXED (primal log-space dual minimisation), IMAXED, AMAXED, AMAXED-Regularization (Wong 2024 PhD thesis) - Statistical Regularisation: Turchin’s method (StatReg), Fortran STREG1 port (Reconst) - Optimisation-based: lmfit (L1/L2/Elastic Net), Scipy direct (CG, GMRES, LSQR), Mystic (direct-search: fmin, Powell, diffev), SMT (exact constraint solving via Z3), Genetic (meta-heuristic: PSO, GA, DE, ES, EP, ABC, GWO, CMA-ES, NSGA-II via MEALPY), CS (compressive sensing), SCIP (pyscipopt), CPLEX (docplex), QUBO (quantum-inspired simulated annealing) - Advanced proximal: ODL-style Primal-Dual Hybrid Gradient (PDHG) and Douglas-Rachford splitting with TV (pure-NumPy) - Evolutionary: MAEO (multi-island NSGA-III / C-TAEA / AGE-MOEA-II / SPEA2 ensemble) - Pipeline: Combined (chaining), Cascade (sequential coarse-to-fine multi-resolution), Composite (adaptive ensemble / stacked generalization) - Parametric: FRUIT-style thermal/epithermal/fast model (lmfit, cvxpy SQP, qpsolvers SQP, combined); BON95 4-component model with directed-divergence iterations; hybrid parametric + iterative refinement; N-spline directed-divergence unfolding (Islamgulov & Lartsev, Atomic Energy 104(5) 2008) with C0/C1 knot continuity and BARS-5/IGRIK/YAGUAR knot presets

• Numba JIT-Accelerated Iterative Solvers: - @njit(cache=True) compiled inner loops for Doroshenko, Kaczmarz, MLEM, GRAVEL - 3–50x speedup on iterative solvers - Automatic disk caching; graceful fallback when numba is not installed

• Radiation Dose Calculations: - ICRP-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