Package Overview

BSSUnfold is a Python package for neutron spectrum unfolding from Bonner Sphere Spectrometers (BSS). It provides 17 unfolding algorithms, 25 spectrum comparison metrics, ICRP-116 dose calculations, and Monte Carlo uncertainty quantification.

Unfolding Methods

All 17 methods are accessible as instance methods on the bssunfold.Detector class. They are organised into the following categories:

        graph TD
    A["Unfolding Methods"] --> B["Tikhonov-type"]
    A --> C["Iterative"]
    A --> D["Bayesian"]
    A --> E["Maximum Entropy"]
    A --> F["Statistical Regularization"]
    A --> G["Optimization-based"]
    A --> H["Pipeline"]

    B --> B1["unfold_cvxpy"]
    B --> B2["unfold_qpsolvers"]
    B --> B3["unfold_tsvd"]
    B --> B4["unfold_tikhonov_legendre"]

    C --> C1["unfold_landweber"]
    C --> C2["unfold_mlem"]
    C --> C3["unfold_mlem_odl"]
    C --> C4["unfold_gravel"]
    C --> C5["unfold_doroshenko"]
    C --> C6["unfold_kaczmarz"]

    D --> D1["unfold_bayes"]
    D --> D2["unfold_bayes_spline_regularization"]

    E --> E1["unfold_maxed"]
    F --> F1["unfold_statreg"]

    G --> G1["unfold_lmfit"]
    G --> G2["unfold_scipy_direct_method"]

    H --> H1["unfold_combined"]

    style A fill:#4a90d9,color:#fff
    style B fill:#e8f0fe
    style C fill:#e8f0fe
    style D fill:#e8f0fe
    style E fill:#e8f0fe
    style F fill:#e8f0fe
    style G fill:#e8f0fe
    style H fill:#e8f0fe
    

Method Reference

Complete method reference

#	Method	Category	Unique Parameters	Dependencies	Description
1	unfold_cvxpy	Tikhonov	regularization, norm (1/2), solver, regularization_method	cvxpy	Convex optimization with Tikhonov regularization
2	unfold_qpsolvers	Tikhonov	regularization, norm (1/2), solver, smoothness_order, smoothness_weight, regularization_method	qpsolvers	QP-based unfolding with L1/L2/smoothness norms
3	unfold_tsvd	Tikhonov	method (l_curve/gcv/discrepancy/energy/median/donoho), k, threshold, noise_level	—	Truncated SVD with automatic k-selection
4	unfold_tikhonov_legendre	Tikhonov	delta, n_polynomials	—	Tikhonov regularization in Legendre polynomial basis
5	unfold_landweber	Iterative	max_iterations, tolerance	—	Landweber fixed-point iteration
6	unfold_mlem	Iterative	max_iterations, tolerance	—	Pure-NumPy MLEM (expectation maximization)
7	unfold_mlem_odl	Iterative	max_iterations, tolerance	odl	MLEM via ODL operator framework
8	unfold_gravel	Iterative	max_iterations, tolerance, regularization	—	GRAVEL with relative entropy weighting
9	unfold_doroshenko	Iterative	max_iterations, tolerance, regularization	—	Coordinate-update iterative method
10	unfold_kaczmarz	Iterative	max_iterations, omega, tolerance	—	ART (Algebraic Reconstruction Technique)
11	unfold_bayes	Bayesian	max_iterations, tolerance	—	D’Agostini Bayesian iterative unfolding
12	unfold_bayes_spline_regularization	Bayesian	max_iterations, tolerance, spline_degree, spline_smooth	—	Bayes with spline smoothing on log10-spectrum
13	unfold_maxed	MaxEnt	sigma_factor, max_iterations, tolerance	—	Maximum entropy deconvolution
14	unfold_statreg	Statistical Reg.	unfoldermethod (EmpiricalBayes/…), regularization, basis_name, boundary, derivative_degree	—	Turchin’s statistical regularization
15	unfold_lmfit	Optimization	method (lbfgsb/leastsq/…), model_name (elastic/lasso/ridge), regularization, regularization2, l1_weight	lmfit	L1/L2/Elastic Net via lmfit
16	unfold_scipy_direct_method	Optimization	method (cg/gmres/lsqr/lsmr/minres), tolerance, max_iterations	—	Direct SciPy linear solvers
17	unfold_combined	Pipeline	pipeline (list of {"method", "params"} dicts)	—	Sequential multi-method pipeline

Note

Common parameters shared by most methods: readings, initial_spectrum, calculate_errors, noise_level, n_montecarlo, save_result, random_state.

See the Index or Detector Class for complete API signatures.

Spectrum Comparison Metrics

25 metrics organised into 7 categories. All implemented with pure NumPy/SciPy.

        graph TD
    A["Comparison Metrics"] --> B["Entropy"]
    A --> C["Distribution"]
    A --> D["Correlation"]
    A --> E["Error"]
    A --> F["Similarity"]
    A --> G["Chi-squared"]
    A --> H["Statistical"]

    B --> B1["kl_divergence"]
    B --> B2["cross_entropy"]
    B --> B3["entropy_difference_percent"]

    C --> C1["wasserstein_dist"]
    C --> C2["energy_dist"]
    C --> C3["kolmogorov_smirnov_stat"]

    D --> D1["pearson_r"]
    D --> D2["spearman_r"]

    E --> E1["mean_squared_error"]
    E --> E2["root_mean_squared_error"]
    E --> E3["mean_absolute_error"]
    E --> E4["mape"]
    E --> E5["r2_score"]
    E --> E6["max_error"]
    E --> E7["median_absolute_error"]

    F --> F1["cosine_similarity"]
    F --> F2["mmd_rbf"]

    G --> G1["chi_squared"]
    G --> G2["g_test"]
    G --> G3["freeman_tukey"]
    G --> G4["cressie_read"]

    H --> H1["anderson_darling"]
    H --> H2["wilcoxon_test"]
    H --> H3["mannwhitneyu_test"]
    H --> H4["standardized_mean_difference"]

    style A fill:#4a90d9,color:#fff
    

Metrics Reference

Complete metrics reference

Category	Metric Key	Description	Range
Entropy	kl_divergence	Kullback-Leibler divergence D_KL(p‖q)	[0, ∞)
	cross_entropy	Cross-entropy H(p,q) = -∑p·log(q)	[0, ∞)
	entropy_difference_percent	Relative cross-entropy excess (%)	[0, ∞)
Distribution	wasserstein_dist	Earth mover’s / Wasserstein distance	[0, ∞)
	energy_dist	Energy distance between distributions	[0, ∞)
	kolmogorov_smirnov_stat	Kolmogorov-Smirnov D-statistic	[0, 1]
Correlation	pearson_r	Pearson correlation coefficient	[-1, 1]
	spearman_r	Spearman rank correlation	[-1, 1]
Error	mean_squared_error	Mean squared error	[0, ∞)
	root_mean_squared_error	Root mean squared error	[0, ∞)
	mean_absolute_error	Mean absolute error	[0, ∞)
	mape	Mean absolute percentage error (%)	[0, 100]
	r2_score	R² (coefficient of determination)	(-∞, 1]
	max_error	Maximum residual error	[0, ∞)
	median_absolute_error	Median absolute error	[0, ∞)
Similarity	cosine_similarity	Cosine similarity cos(θ)	[0, 1]
	mmd_rbf	Maximum Mean Discrepancy (RBF kernel)	[0, ∞)
Chi-squared	chi_squared	Pearson’s chi-squared statistic	[0, ∞)
	g_test	G-test (log-likelihood ratio)	[0, ∞)
	freeman_tukey	Freeman-Tukey statistic	[0, ∞)
	cressie_read	Cressie-Read power divergence	[0, ∞)
Statistical	anderson_darling	Anderson-Darling k-sample statistic	[0, ∞)
	wilcoxon_test	Wilcoxon signed-rank test statistic	[0, ∞)
	mannwhitneyu_test	Mann-Whitney U test statistic	[0, ∞)
	standardized_mean_difference	Cohen’s d (standardized mean difference)	(-∞, ∞)