Detector Class#

Bases: object

Class for neutron detector operations and spectrum unfolding.

This class provides methods for neutron spectrum unfolding using various algorithms and includes tools for dose rate calculations based on ICRP-116 conversion coefficients.

Parameters:

response_functions (pd.DataFrame, dict, optional) – Response functions data. Can be: - pandas DataFrame with ‘E_MeV’ column and detector columns. - dict with ‘E_MeV’ key (array) and detector names as keys (arrays). If None, default GSF response functions are used.
E_MeV (np.ndarray, optional) – Energy grid in MeV. Required if response_functions is not provided and sensitivities is provided.
sensitivities (dict or np.ndarray, optional) – Detector sensitivities. If dict, keys are detector names and values are arrays of same length as E_MeV. If 2D array, shape (n_energy, n_detectors). Required if response_functions is not provided and E_MeV is provided.

Variables:

Amat (np.ndarray) – Response matrix with logarithmic energy step corrections
E_MeV (np.ndarray) – Energy grid in MeV
detector_names (List[str]) – Names of available detectors/spheres
log_steps (np.ndarray) – Logarithmic steps for each energy point
sensitivities (Dict[str, np.ndarray]) – Dictionary mapping detector names to their sensitivity arrays
cc_icrp116 (Dict[str, np.ndarray]) – Raw (non-interpolated) conversion coefficients for dose calculation
cc_type (str) – Name of the dose conversion coefficient dataset (default: “ICRP116”)
n_detectors (int) – Number of available detectors (property)
n_energy_bins (int) – Number of energy bins (property)

Examples

>>> from bssunfold import Detector
>>> # Create detector with default GSF response functions
>>> detector = Detector()
>>> # Perform unfolding
>>> readings = {'sphere_1': 100.5, 'sphere_2': 85.3}
>>> result = detector.unfold_cvxpy(readings)

Initialize Detector with response functions.

Parameters:

response_functions (pd.DataFrame, dict, optional) – Response functions data.
E_MeV (np.ndarray, optional) – Energy grid in MeV.
sensitivities (dict or np.ndarray, optional) – Detector sensitivities.
cc_type (str, optional) – Name of the dose conversion coefficient dataset to use. Options: “ICRP116”, “ICRP74_effective”, “NRB99_2009_effective”, “ICRP74_operational”. Default: “ICRP116”.

Raises:

ValueError – If E_MeV is not a 1D array or has less than 2 energy points, or if input data is inconsistent.

_process_input(response_functions: DataFrame | Dict | None, E_MeV: ndarray | None, sensitivities: Dict | ndarray | None) → DataFrame[source]#: Convert various input formats to a unified DataFrame.

__str__() → str[source]#: User-friendly string representation.

__repr__() → str[source]#: Technical string representation.

property n_detectors: int#: Number of available detectors.

property n_energy_bins: int#: Number of energy bins.

set_dose_coefficients(name: str) → None[source]#

Change the dose conversion coefficient dataset.

Parameters:

name (str) –

Name of the coefficient dataset. Options:

"ICRP116": ICRP-116 effective dose (default)
"ICRP74_effective": ICRP-74 effective dose
"NRB99_2009_effective": NRB99-2009 effective dose
"ICRP74_operational": ICRP-74 operational quantities

Raises:

ValueError – If the coefficient name is not found.

Examples

>>> detector = Detector()
>>> detector.set_dose_coefficients("ICRP74_effective")
>>> detector.cc_type
'ICRP74_effective'

_get_interpolated_cc() → Dict[str, ndarray][source]#

Get conversion coefficients interpolated to this detector’s energy grid.

Returns:: Interpolated conversion coefficients on self.E_MeV.
Return type:: Dict[str, np.ndarray]

_validate_readings(readings: Dict[str, float]) → Dict[str, float][source]#: Validate detector readings.

_build_system(readings: Dict[str, float]) → Tuple[ndarray, ndarray, List[str]][source]#: Build response matrix A and measurement vector b.

_standardize_output(spectrum: ndarray, A: ndarray, b: ndarray, selected: List[str], method: str, **kwargs) → Dict[str, Any][source]#: Create standardized output dictionary.

_convert_rf_to_matrix_variable_step(rf_df: DataFrame, Emin: float = 1e-09) → Tuple[ndarray, ndarray, List[str], ndarray][source]#: Convert response functions to matrix with variable step correction.

_save_result(result: Dict[str, Any]) → str[source]#: Save unfolding result to history.

get_result(key: str | None = None) → Dict[str, Any] | None[source]#: Get unfolding result from history.

list_results() → List[str][source]#: List all saved result keys.

clear_results() → None[source]#: Clear all saved results.

_normalize_initial_spectrum(initial_spectrum: ndarray | Dict | DataFrame | None) → ndarray | None[source]#: Normalize initial spectrum to detector’s energy grid.

_cosine_similarity(spectrum1: ndarray, spectrum2: ndarray) → float[source]#: Compute cosine similarity between two spectra.

_add_noise(readings: Dict[str, float], noise_level: float = 0.01, random_state: int | None = None) → Dict[str, float][source]#

Add Gaussian noise to readings.

Parameters:

readings (Dict[str, float]) – Original readings.
noise_level (float, optional) – Relative noise level (default: 0.01).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Noisy readings.

Return type:

Dict[str, float]

unfold_cvxpy(readings: Dict[str, float], initial_spectrum: ndarray | None = None, regularization: float = 0.0001, norm: int = 2, solver: str = 'default', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, regularization_method: str = 'manual', noise_var: float | None = None, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using convex optimization (cvxpy).

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
regularization (float, optional) – Regularization parameter (default: 1e-4).
norm (int, optional) – Norm type (1 for L1, 2 for L2), default: 2.
solver (str, optional) – Solver to use (‘ECOS’ or ‘default’).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
regularization_method (str, optional) – Method for selecting regularization parameter.
noise_var (float, optional) – Noise variance for discrepancy principle.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_landweber(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using Landweber iteration method.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_mlem(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM algorithm.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_qpsolvers(readings: Dict[str, float], initial_spectrum: ndarray | None = None, regularization: float = 0.0001, norm: int = 2, solver: str = 'osqp', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, regularization_method: str = 'manual', noise_var: float | None = None, smoothness_order: int = 0, smoothness_weight: float = 1.0, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using qpsolvers with regularization selection.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (np.ndarray, optional) – Initial spectrum guess.
regularization (float, optional) – Regularization parameter, default: 1e-4.
norm (int, optional) – Norm type (1 for L1, 2 for L2), default: 2.
solver (str, optional) – QP solver name, default: ‘osqp’.
calculate_errors (bool, optional) – If True, calculate Monte-Carlo uncertainty, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples, default: 100.
save_result (bool, optional) – Save result to history, default: True.
regularization_method (str, optional) – Method for selecting regularization parameter. Options: ‘manual’, ‘cosine’, ‘gcv’, ‘lcurve’, ‘dp’.
noise_var (float, optional) – Noise variance for discrepancy principle (‘dp’ method).
smoothness_order (int, optional) – Smoothness constraint order (0, 1, or 2), default: 0.
smoothness_weight (float, optional) – Weight for smoothness term, default: 1.0.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results including spectrum, residuals, and metadata.

Return type:

Dict[str, Any]

unfold_reconst(readings: Dict[str, float], initial_spectrum: ndarray | None = None, pp: float = 0.001, alpha: float = -1.0, beta: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Turchin’s statistical regularization.

Pure numpy port of the RECONST.FOR algorithm (STREG1). Solves (B * beta + Omega * alpha) * f = A_vec * beta with automatic alpha/beta selection.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Ignored (for API compatibility).
pp (float, optional) – PP parameter for the smoothing matrix (default: 1e-3).
alpha (float, optional) – Regularization parameter. >0 fixed, <0 auto-select absolute value (default: -1).
beta (float, optional) – Data fidelity weight. >0 fixed, <=0 auto-select (default: 0).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_lmfit(readings: Dict[str, float], initial_spectrum: ndarray | None = None, method: str = 'lbfgsb', model_name: str = 'elastic', regularization: float = 0.0001, regularization2: float = 0.0001, l1_weight: float = 0.5, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using lmfit with L1/L2/Elastic regularization.

Parameters:

readings (Dict[str, float]) – Detector readings (counts or dose rates)
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
method (str, optional) – lmfit solver name (leastsq, lbfgsb, etc.), default: “lbfgsb”.
model_name (str, optional) – Regularization model: elastic, lasso, ridge, default: “elastic”.
regularization (float, optional) – L1 regularization strength, default: 1e-4.
regularization2 (float, optional) – L2 regularization strength for elastic net, default: 1e-4.
l1_weight (float, optional) – L1 weight for elastic net (0=pure L2, 1=pure L1), default: 0.5.
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100.
save_result (bool, optional) – If True, save result to internal history, default: True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

unfold_mlem_odl(readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-06, max_iterations: int = 1000, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM with ODL (Operator Discretization Library).

Requires the ‘odl’ package to be installed.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum approximation.
tolerance (float, optional) – Convergence tolerance. Default is 1e-6.
max_iterations (int, optional) – Maximum number of iterations. Default is 1000.
calculate_errors (bool, optional) – Flag for calculating restoration errors. Default is False.
noise_level (float, optional) – Noise level for error calculation. Default is 0.01.
n_montecarlo (int, optional) – Number of Monte Carlo samples for error calculation. Default is 100.
save_result (bool, optional) – If True, save result to internal history. Default is True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing the spectrum restoration results.

Return type:

Dict

unfold_mlem_stop(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 15000, cps_crossover: float = 30000.0, j_threshold: float | None = None, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM-STOP with J-factor early stopping criterion.

Uses the modified MLEM-STOP method from Montgomery et al. (2020). The J-factor indicator (Bouallegue et al. 2013) is computed at each iteration: J = sum((meas - est)^2) / sum(est). The algorithm stops when J falls below the threshold (mean(measurements) / cps_crossover).

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 15000).
cps_crossover (float, optional) – Crossover CPS value for automatic J threshold (default: 30000).
j_threshold (float, optional) – Explicit J threshold. If None, computed from cps_crossover.
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_combined(readings: Dict[str, float], pipeline: List[Dict[str, Any]], calculate_errors: bool = False, verbose: bool = True) → Dict[str, Any] | None[source]#

Combined unfolding method applying multiple methods sequentially.

Parameters:

readings (Dict[str, float]) – Detector readings
pipeline (List[Dict[str, Any]]) – List of methods for sequential application.
calculate_errors (bool, optional) – Flag to calculate errors for the last method.
verbose (bool, optional) – Flag to print debug information.

Returns:

Dictionary with unfolding results.

Return type:

Dict

discretize_spectra(spectra: DataFrame | Dict) → DataFrame[source]#: Interpolate spectra onto target energy grid.

get_effective_readings_for_spectra(spectra: DataFrame | Dict) → Dict[str, float][source]#: Calculate effective readings for a given spectrum.

static _import_optional(module_name: str, purpose: str) → Any[source]#: Import optional dependency with informative error message.

_save_figure(fig: Any, save_to: str | None = None, dpi: int = 300, bbox_inches: str = 'tight', **savefig_kwargs) → None[source]#: Save figure to file with support for multiple formats.

unfold_doroshenko(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, regularization: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the Doroshenko coordinate update method.

Parameters:

readings (Dict[str, float]) – Detector readings (counts or dose rates)
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, uniform spectrum is used
max_iterations (int, optional) – Maximum number of iterations, default: 1000
tolerance (float, optional) – Convergence tolerance for solution change, default: 1e-6
regularization (float, optional) – Regularization strength to prevent division by zero, default: 0.0
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100
save_result (bool, optional) – If True, save result to internal history, default: True
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

unfold_kaczmarz(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, omega: float = 1.0, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the Kaczmarz algorithm (ART).

Parameters:

readings (Dict[str, float]) – Detector readings (counts or dose rates)
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, zero spectrum is used
max_iterations (int, optional) – Maximum number of iterations, default: 1000
omega (float, optional) – Relaxation parameter (0 < omega <= 2), default: 1.0
tolerance (float, optional) – Convergence tolerance for solution change, default: 1e-6
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100
save_result (bool, optional) – If True, save result to internal history, default: True
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

unfold_gravel(readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-08, max_iterations: int = 1000, regularization: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the GRAVEL algorithm.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, default initial spectrum is used.
tolerance (float, optional) – Convergence tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum iterations (default: 1000).
regularization (float, optional) – Regularization parameter (default: 0.0).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_maxed(readings: Dict[str, float], initial_spectrum: ndarray | None = None, sigma_factor: float = 0.01, max_iterations: int = 5000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the MAXED algorithm.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Reference spectrum. If None, a flat reference is used.
sigma_factor (float, optional) – Relative measurement uncertainty (default: 0.01).
max_iterations (int, optional) – Maximum L-BFGS-B iterations (default: 5000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_tikhonov_legendre(readings: Dict[str, float], initial_spectrum: ndarray | None = None, delta: float = 0.05, n_polynomials: int = 15, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Tikhonov regularization with Legendre basis.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Not used (provided for API consistency).
delta (float, optional) – Regularization parameter (default: 0.05).
n_polynomials (int, optional) – Number of Legendre polynomials (default: 15).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_bayes(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayesian iterative unfolding (D’Agostini).

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Prior spectrum. If None, uniform prior is used.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Convergence tolerance (default: 1e-3).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_bayes_spline_regularization(readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001, spline_degree: int = 3, spline_smooth: float = 0.01, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayesian iterative unfolding with spline regularization.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Prior spectrum. If None, uniform prior is used.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Convergence tolerance (default: 1e-3).
spline_degree (int, optional) – Spline degree (default: 3).
spline_smooth (float, optional) – Spline smoothing parameter (default: 1e-2).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_statreg(readings: Dict[str, float], initial_spectrum: ndarray | None = None, unfoldermethod: str = 'EmpiricalBayes', regularization: float | None = None, basis_name: str = 'CubicSplines', boundary: str | None = None, derivative_degree: int = 2, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Turchin’s method of statistical regularization.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
unfoldermethod (str, optional) – Regularization method: ‘EmpiricalBayes’ or ‘User’ (default: ‘EmpiricalBayes’).
regularization (float, optional) – Regularization parameter for ‘User’ method.
basis_name (str, optional) – Basis type (default: ‘CubicSplines’).
boundary (str, optional) – Boundary condition, None or ‘dirichlet’.
derivative_degree (int, optional) – Derivative degree (1, 2, 3), default: 2.
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_scipy_direct_method(readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-08, max_iterations: int = 4000, method: str = 'cg', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using scipy linear solvers.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
tolerance (float, optional) – Solver tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum solver iterations (default: 4000).
method (str, optional) – Solver method: ‘cg’, ‘cgs’, ‘bicgstab’, ‘gmres’, etc. (default: ‘cg’).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_tsvd(readings: Dict[str, float], initial_spectrum: ndarray | None = None, method: str = 'discrepancy', k: int | None = None, threshold: float | None = None, noise_level: float | None = None, calculate_errors: bool = False, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Truncated SVD (TSVD).

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
method (str, optional) – K-selection method: ‘discrepancy’, ‘l_curve’, ‘gcv’, ‘energy’, ‘threshold_ratio’, ‘median_threshold’, ‘donoho’ (default: ‘discrepancy’).
k (int, optional) – Fixed number of singular values to keep.
threshold (float, optional) – Threshold ratio for singular value truncation.
noise_level (float, optional) – Noise level for discrepancy principle.
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_fruit_like(readings: Dict[str, float], initial_spectrum: ndarray | None = None, initial_params: Dict[str, float] | None = None, method: str = 'leastsq', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using FRUIT-like parametric method.

Uses a parametric model with Maxwellian thermal component, 1/E epithermal component, and evaporation spectrum for fast neutrons.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
initial_params (Optional[Dict[str, float]], optional) – Initial parameter values for the parametric model. Keys: A_th, T_th, A_epi, A_f, T_ev.
method (str, optional) – lmfit solver method (default: “leastsq”).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_hybrid_parametric(readings: Dict[str, float], initial_spectrum: ndarray | None = None, refinement_method: str = 'landweber', max_iterations: int = 100, tolerance: float = 1e-06, step_size: float = 0.01, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using hybrid parametric-nonparametric method.

Combines parametric initial guess with iterative refinement using Landweber or MLEM iteration.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
refinement_method (str, optional) – Refinement method: “landweber” or “mlem” (default: “landweber”).
max_iterations (int, optional) – Maximum iterations (default: 100).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
step_size (float, optional) – Step size for Landweber (default: 0.01).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_bayesian_parametric(readings: Dict[str, float], initial_spectrum: ndarray | None = None, sigma: float = 0.02, n_samples: int = 1000, burn_in: int = 200, proposal_scale: float = 0.1, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayesian parametric method.

Uses Bayesian inference with MCMC sampling to estimate spectral parameters and quantify uncertainty.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused).
sigma (float, optional) – Measurement uncertainty (default: 0.02).
n_samples (int, optional) – Number of MCMC samples (default: 1000).
burn_in (int, optional) – Burn-in samples (default: 200).
proposal_scale (float, optional) – Proposal scale (default: 0.1).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_parametric(readings: Dict[str, float], initial_spectrum: ndarray | None = None, initial_params: Dict[str, float] | None = None, method: str = 'leastsq', optimizer: str = 'lmfit', alpha: float = 0.0001, alpha_auto: bool = False, solver_backend: str = 'auto', max_iter: int = 50, tol: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the FRUIT-based parametric method.

Uses the three-component parameterization from Bedogni FRUIT / Pyshkina B3S: thermal (Maxwellian), epithermal (1/E with exponential cutoffs), and fast (power-law x exponential).

The optimizer parameter selects the backend:

"lmfit" – classic lmfit least-squares (default).
"cvxpy" – sequential QP via cvxpy (SQP).
"qpsolvers" – sequential QP via qpsolvers (SQP).
"combined" – lmfit first, then QP refinement.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
initial_params (Optional[Dict[str, float]], optional) – Initial parameter values for the parametric model. Keys: b, beta_prime, alpha, beta, P_th, P_epi.
method (str, optional) – lmfit solver method (default: “leastsq”).
optimizer (str, optional) – Backend optimizer (default: “lmfit”).
alpha (float, optional) – Regularization weight for QP-based optimizers (default: 1e-4).
alpha_auto (bool, optional) – If True, select alpha automatically via GCV for the lmfit optimizer (default: False).
solver_backend (str, optional) – QP solver backend: “auto”, “cvxpy”, “cvxpy:ECOS”, “qpsolvers”, “qpsolvers:osqp”, etc. (default: “auto”).
max_iter (int, optional) – Max SQP iterations (default: 50).
tol (float, optional) – Convergence tolerance for SQP (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

unfold_parametric2(readings: Dict[str, float], initial_spectrum: ndarray | None = None, optimizer: str = 'grid', b_range: Tuple[float, float, int] = (0.5, 2.0, 5), Tf_range: Tuple[float, float, int] = (0.5, 10.0, 5), c_range: Tuple[float, float, int] = (0.5, 3.0, 4), alpha: float = 0.0001, solver_backend: str = 'auto', max_iter_qp: int = 50, tol_qp: float = 1e-06, noise_level: float = 0.05, max_iter: int = 200, tol_chi2: float = 1.0, calculate_errors: bool = False, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the BON95 parametric method.

Uses the four-component parameterization from Sannikov BON95: thermal (Maxwellian), epithermal (1/E), intermediate, and fast (evaporation/cascade) components. After parametric fitting, the result is refined by directed-divergence iterations.

The optimizer parameter selects the parametric fit backend:

"grid" – grid search + NLS (default, no extra deps).
"cvxpy" – SQP via cvxpy.
"qpsolvers" – SQP via qpsolvers.
"combined" – grid search + SQP refinement.

Parameters:

readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
optimizer (str) – Parametric fit optimizer (default: “grid”).
b_range (tuple) – Grid range for b: (min, max, n_points). Used by “grid”/”combined”.
Tf_range (tuple) – Grid range for Tf (MeV): (min, max, n_points). Used by “grid”/”combined”.
c_range (tuple) – Grid range for c: (min, max, n_points). Used by “grid”/”combined”.
alpha (float) – Tikhonov regularization for SQP (default: 1e-4).
solver_backend (str) – QP backend for SQP (default: “auto”).
max_iter_qp (int) – Max SQP iterations (default: 50).
tol_qp (float) – SQP convergence tolerance (default: 1e-6).
noise_level (float) – Relative uncertainty for measurements (default: 0.05 = 5%).
max_iter (int) – Max directed-divergence iterations (default: 200).
tol_chi2 (float) – Chi-squared convergence threshold (default: 1.0).
calculate_errors (bool) – Calculate Monte-Carlo errors (default: False).
n_montecarlo (int) – Number of Monte-Carlo samples (default: 100).
save_result (bool) – Save result to history (default: False).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

plot_response_functions(save_to: str | None = None, show: bool = True, dpi: int = 300, bbox_inches: str = 'tight', **savefig_kwargs) → None[source]#: Plot all detector response functions.

plot_with_uncertainty(result: Dict[str, Any], reference_spectrum: Dict[str, ndarray] | None = None, save_to: str | None = None, show: bool = True, **plot_kwargs) → Tuple[Any, Any][source]#

Plot unfolded spectrum with uncertainty range.

Parameters:

result (Dict[str, Any]) – Unfolding result dictionary containing ‘energy’, ‘spectrum’, and optionally ‘spectrum_uncert_min’, ‘spectrum_uncert_max’, ‘spectrum_uncert_std’.
reference_spectrum (Dict[str, np.ndarray], optional) – Reference spectrum with ‘E_MeV’ and ‘Phi’ keys.
save_to (str, optional) – Path to save figure.
show (bool, optional) – Call plt.show() (default: True).
**plot_kwargs (dict) – Additional keyword arguments for plotting.

Returns:

Figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

compare_regularization_methods(readings: Dict[str, float], noise_var: float | None = None, plot: bool = False, plot_path: str | None = None) → Dict[str, Any][source]#

Compare regularization selection methods for given readings.

Parameters:

readings (Dict[str, float]) – Detector readings.
noise_var (float, optional) – Noise variance for discrepancy principle.
plot (bool, optional) – If True, generate comparison plot.
plot_path (str, optional) – Path to save the plot.

Returns:

Comparison results.

Return type:

Dict[str, Any]

randomization_experiment(readings: Dict[str, float], noise_var: float | None = None, n_samples: int = 10, rseed: int = 0, methods: List[str] | None = None) → Dict[str, Any][source]#

Run randomization experiments for given readings.

Parameters:

readings (Dict[str, float]) – Detector readings.
noise_var (float, optional) – Noise variance for generating perturbed measurements.
n_samples (int, optional) – Number of random samples for each method, default 10.
rseed (int, optional) – Random seed for reproducibility, default 0.
methods (list of str, optional) – List of methods to run: ‘lcurve’, ‘dp’, ‘gcv’, ‘lcurve_full’.

Returns:

Randomization experiment results.

Return type:

Dict[str, Any]

Compare two or more spectra using comparison metrics.

Each spectrum can be provided as: - np.ndarray of length matching self.n_energy_bins - dict with a 'spectrum' key (e.g. an unfolding result) - result dictionary returned by any unfold_* method

When the energy grid is available, EURADOS-style metrics (dose differences, peak errors, log-lethargy correlation, etc.) are computed automatically.

Parameters:

*spectra (np.ndarray or dict) – Two or more spectra to compare.
metrics (str, list of str, or None) – Metric(s) to compute. If None, all metrics are used.
labels (list of str, optional) – Labels for each spectrum. Required for 3+ spectra.
readings1 (np.ndarray, optional) – Measured readings for response-matrix consistency check. If a spectrum is a result dict containing 'readings', those values are used as a fallback.
readings2 (np.ndarray, optional) – Measured readings for response-matrix consistency check. If a spectrum is a result dict containing 'readings', those values are used as a fallback.
response_matrix (np.ndarray, optional) – Response matrix for the consistency check. If a spectrum is a result dict containing 'response_matrix', that value is used as a fallback.
plot (bool, optional) – If True, generate a comparison figure with spectra overlay and metric bar chart.
save_to (str, optional) – Path to save the figure (png/jpg/eps/pdf).
dpi (int, optional) – Figure DPI (default: 300).
figsize (tuple, optional) – Figure size (default: (14, 5)).
return_fig (bool, optional) – If True, return (result, fig, ax) tuple.
**plot_kwargs (dict) – Additional keyword arguments passed to matplotlib/seaborn plots.

Returns:

If two spectra: dict {metric: value}. If three or more: pd.DataFrame with metrics as rows and comparison pairs as columns. If return_fig=True: (result, fig, ax).

Return type:

dict or pd.DataFrame or tuple

Unfold Methods#

The following unfolding methods are available through the Detector class:

bssunfold.core.unfold_cvxpy.unfold_cvxpy(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, regularization: float = 0.0001, norm: int = 2, solver: str = 'default', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, regularization_method: str = 'manual', noise_var: float | None = None, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using convex optimization (cvxpy).

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
regularization (float, optional) – Regularization parameter (default: 1e-4).
norm (int, optional) – Norm type (1 for L1, 2 for L2), default: 2.
solver (str, optional) – Solver to use (‘ECOS’ or ‘default’).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
regularization_method (str, optional) – Method for selecting regularization parameter.
noise_var (float, optional) – Noise variance for discrepancy principle.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_landweber.unfold_landweber(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using Landweber iteration method.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_mlem.unfold_mlem(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM algorithm.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_qpsolvers.unfold_qpsolvers(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, regularization: float = 0.0001, norm: int = 2, solver: str = 'osqp', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, regularization_method: str = 'manual', noise_var: float | None = None, smoothness_order: int = 0, smoothness_weight: float = 1.0, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using qpsolvers with regularization selection.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (np.ndarray, optional) – Initial spectrum guess.
regularization (float, optional) – Regularization parameter, default: 1e-4.
norm (int, optional) – Norm type (1 for L1, 2 for L2), default: 2.
solver (str, optional) – QP solver name, default: ‘osqp’.
calculate_errors (bool, optional) – If True, calculate Monte-Carlo uncertainty, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples, default: 100.
save_result (bool, optional) – Save result to history, default: True.
regularization_method (str, optional) – Method for selecting regularization parameter.
noise_var (float, optional) – Noise variance for discrepancy principle (‘dp’ method).
smoothness_order (int, optional) – Smoothness constraint order (0, 1, or 2), default: 0.
smoothness_weight (float, optional) – Weight for smoothness term, default: 1.0.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results including spectrum, residuals, and metadata.

Return type:

Dict[str, Any]

bssunfold.core.unfold_doroshenko.unfold_doroshenko(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, tolerance: float = 1e-06, regularization: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the Doroshenko coordinate update method.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, uniform spectrum is used.
max_iterations (int, optional) – Maximum number of iterations, default: 1000.
tolerance (float, optional) – Convergence tolerance for solution change, default: 1e-6.
regularization (float, optional) – Regularization strength to prevent division by zero, default: 0.0.
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100.
save_result (bool, optional) – If True, save result to internal history, default: True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

bssunfold.core.unfold_kaczmarz.unfold_kaczmarz(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 1000, omega: float = 1.0, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the Kaczmarz algorithm (ART).

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, zero spectrum is used.
max_iterations (int, optional) – Maximum number of iterations, default: 1000.
omega (float, optional) – Relaxation parameter (0 < omega <= 2), default: 1.0.
tolerance (float, optional) – Convergence tolerance for solution change, default: 1e-6.
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100.
save_result (bool, optional) – If True, save result to internal history, default: True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

bssunfold.core.unfold_lmfit.unfold_lmfit(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, method: str = 'lbfgsb', model_name: str = 'elastic', regularization: float = 0.0001, regularization2: float = 0.0001, l1_weight: float = 0.5, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using lmfit with L1/L2/Elastic regularization.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess. If None, uniform spectrum based on mean readings.
method (str, optional) – lmfit solver name (leastsq, lbfgsb, etc.), default: “lbfgsb”.
model_name (str, optional) – Regularization model: elastic, lasso, ridge, default: “elastic”.
regularization (float, optional) – L1 regularization strength, default: 1e-4.
regularization2 (float, optional) – L2 regularization strength for elastic net, default: 1e-4.
l1_weight (float, optional) – L1 weight for elastic net (0=pure L2, 1=pure L1), default: 0.5.
calculate_errors (bool, optional) – Flag to calculate uncertainty via Monte-Carlo, default: False.
noise_level (float, optional) – Noise level for Monte-Carlo uncertainty calculation, default: 0.01.
n_montecarlo (int, optional) – Number of Monte-Carlo samples for error estimation, default: 100.
save_result (bool, optional) – If True, save result to internal history, default: True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing unfolding results.

Return type:

Dict[str, Any]

bssunfold.core.unfold_mlem_odl.unfold_mlem_odl(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-06, max_iterations: int = 1000, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM with ODL (Operator Discretization Library).

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum approximation. If None, uniform spectrum is used.
tolerance (float, optional) – Convergence tolerance. Default is 1e-6.
max_iterations (int, optional) – Maximum number of iterations. Default is 1000.
calculate_errors (bool, optional) – Flag for calculating restoration errors. Default is False.
noise_level (float, optional) – Noise level for error calculation. Default is 0.01.
n_montecarlo (int, optional) – Number of Monte Carlo samples for error calculation. Default is 100.
save_result (bool, optional) – If True, save result to internal history. Default is True.
random_state (int, optional) – Random seed for reproducibility.

Returns:

Dictionary containing the spectrum restoration results.

Return type:

Dict

bssunfold.core.unfold_mlem_stop.unfold_mlem_stop(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 15000, cps_crossover: float = 30000.0, j_threshold: float | None = None, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold using MLEM-STOP algorithm with J-factor stopping criterion.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
max_iterations (int, optional) – Maximum iterations (default: 15000).
cps_crossover (float, optional) – Crossover CPS value for automatic J threshold (default: 30000).
j_threshold (float, optional) – J-factor stopping threshold. If None, computed automatically.
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_combined.unfold_combined(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], pipeline: List[Dict[str, Any]], calculate_errors: bool = False, verbose: bool = True) → Dict[str, Any] | None[source]#

Combined unfolding method applying multiple methods sequentially.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
pipeline (List[Dict[str, Any]]) – List of methods for sequential application. Each dict should contain: - ‘method’: str - method name (e.g., ‘cvxpy’, ‘landweber’, ‘mlem’) - ‘params’: dict - parameters for the method - ‘use_as_initial’: bool (optional) - use result as initial guess - ‘store_intermediate’: bool (optional) - store intermediate result
calculate_errors (bool, optional) – Flag to calculate errors for the last method.
verbose (bool, optional) – Flag to print debug information.

Returns:

Dictionary with unfolding results.

Return type:

Dict

bssunfold.core.unfold_gravel.unfold_gravel(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-08, max_iterations: int = 1000, regularization: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the GRAVEL algorithm.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
tolerance (float, optional) – Convergence tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum iterations (default: 1000).
regularization (float, optional) – Regularization parameter (default: 0.0).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_maxed.unfold_maxed(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, sigma_factor: float = 0.1, max_iterations: int = 5000, tolerance: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the MAXED algorithm.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Reference spectrum. If None, a flat reference is used.
sigma_factor (float, optional) – Relative measurement uncertainty (default: 0.1). Larger values → smoother spectrum.
max_iterations (int, optional) – Maximum L-BFGS-B iterations (default: 5000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_tikhonov_legendre.unfold_tikhonov_legendre(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, delta: float = 0.05, n_polynomials: int = 15, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Tikhonov regularization with Legendre basis.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Not used (provided for API compatibility).
delta (float, optional) – Regularization parameter (default: 0.05).
n_polynomials (int, optional) – Number of Legendre polynomials (default: 15).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_bayes.unfold_bayes(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayesian iterative unfolding.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Prior spectrum.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Convergence tolerance (default: 1e-3).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_bayes_spline_regularization.unfold_bayes_spline_regularization(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001, spline_degree: int = 3, spline_smooth: float = 0.01, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayes with spline regularization.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Prior spectrum.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Convergence tolerance (default: 1e-3).
spline_degree (int, optional) – Spline degree (default: 3).
spline_smooth (float, optional) – Spline smoothing parameter (default: 1e-2).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_statreg.unfold_statreg(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, unfoldermethod: str = 'EmpiricalBayes', regularization: float | None = None, basis_name: str = 'CubicSplines', boundary: str | None = None, derivative_degree: int = 2, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Turchin’s statistical regularisation.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
unfoldermethod (str, optional) – Regularisation method (default: 'EmpiricalBayes').
regularization (float, optional) – Regularisation parameter for 'User' method.
basis_name (str, optional) – Ignored (kept for API compatibility).
boundary (str, optional) – Ignored (kept for API compatibility).
derivative_degree (int, optional) – Derivative degree (default: 2).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_reconst.unfold_reconst(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, pp: float = 0.001, alpha: float = -1.0, beta: float = 0.0, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Turchin’s statistical regularization.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Ignored (API compatibility).
pp (float, optional) – PP parameter (default: 1e-3).
alpha (float, optional) – Regularization. <0 auto, >0 fixed (default: -1).
beta (float, optional) – Data fidelity. 0 auto, >0 fixed (default: 0).
calculate_errors (bool, optional) – Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result (default: True).
random_state (int, optional) – Random seed.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_scipy_direct_method.unfold_scipy_direct_method(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, tolerance: float = 1e-08, max_iterations: int = 4000, method: str = 'cg', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using scipy direct solvers.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
tolerance (float, optional) – Solver tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum solver iterations (default: 4000).
method (str, optional) – Solver method (default: ‘cg’).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_tsvd.unfold_tsvd(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, method: str = 'discrepancy', k: int | None = None, threshold: float | None = None, noise_level: float | None = None, calculate_errors: bool = False, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Truncated SVD (TSVD).

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
method (str, optional) – K-selection method (default: ‘discrepancy’).
k (int, optional) – Fixed truncation parameter.
threshold (float, optional) – Threshold ratio for truncation.
noise_level (float, optional) – Noise level estimate.
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_parametric.unfold_parametric(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, initial_params: Dict[str, float] | None = None, method: str = 'leastsq', optimizer: str = 'lmfit', alpha: float = 0.0001, alpha_auto: bool = False, solver_backend: str = 'auto', max_iter: int = 50, tol: float = 1e-06, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the FRUIT-based parametric method.

The spectrum is modelled as a weighted superposition of thermal, epithermal and fast components (Bedogni FRUIT / Pyshkina B3S).

The optimizer parameter selects the backend:

"lmfit" – classic lmfit least-squares (default).
"cvxpy" – sequential QP via cvxpy (SQP).
"qpsolvers" – sequential QP via qpsolvers (SQP).
"combined" – lmfit first, then QP refinement.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid in MeV.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
initial_params (Optional[Dict[str, float]], optional) – Initial parameter values for the parametric model. Keys: b, beta_prime, alpha, beta, P_th, P_epi.
method (str, optional) – lmfit solver method (default: “leastsq”).
optimizer (str, optional) – Backend optimizer: “lmfit”, “cvxpy”, “qpsolvers”, or “combined” (default: “lmfit”).
alpha (float, optional) – Regularization weight for QP-based optimizers (default: 1e-4). Also used as initial alpha for lmfit when alpha_auto is True.
alpha_auto (bool, optional) – If True, select alpha automatically via GCV for the lmfit optimizer (default: False).
solver_backend (str, optional) – QP solver backend string: “auto”, “cvxpy”, “cvxpy:ECOS”, “qpsolvers”, “qpsolvers:osqp”, etc. (default: “auto”).
max_iter (int, optional) – Max SQP iterations for cvxpy/qpsolvers (default: 50).
tol (float, optional) – Convergence tolerance for SQP (default: 1e-6).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_parametric.solve_parametric_cvxpy(A_matrix, b_readings, E, log_steps, initial_params=None, alpha=0.0001, solver_backend='auto', max_iter=50, tol=1e-06)[source]#

Solve parametric unfolding via sequential QP using cvxpy.

The nonlinear parametric model is linearized at each iteration and the resulting QP is solved with cvxpy, including parameter bounds and a Tikhonov penalty on the parameter update.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_detectors x n_energy).
b_readings (np.ndarray) – Measured readings (n_detectors,).
E (np.ndarray) – Energy grid in MeV.
log_steps (np.ndarray) – Logarithmic energy steps (d(ln E)).
initial_params (dict, optional) – Initial parameter values.
alpha (float, optional) – Regularization weight for parameter penalty (default: 1e-4).
solver_backend (str, optional) – CVXPY solver backend: “auto”, “cvxpy”, or “cvxpy:ECOS” etc. (default: “auto”).
max_iter (int, optional) – Maximum SQP iterations (default: 50).
tol (float, optional) – Convergence tolerance on parameter update norm (default: 1e-6).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric.solve_parametric_qpsolvers(A_matrix, b_readings, E, log_steps, initial_params=None, alpha=0.0001, solver_backend='auto', max_iter=50, tol=1e-06)[source]#

Solve parametric unfolding via sequential QP using qpsolvers.

The nonlinear parametric model is linearized at each iteration and the resulting QP is solved with qpsolvers, including parameter bounds and a Tikhonov penalty on the parameter update.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_detectors x n_energy).
b_readings (np.ndarray) – Measured readings (n_detectors,).
E (np.ndarray) – Energy grid in MeV.
log_steps (np.ndarray) – Logarithmic energy steps (d(ln E)).
initial_params (dict, optional) – Initial parameter values.
alpha (float, optional) – Regularization weight (default: 1e-4).
solver_backend (str, optional) – QP solver backend: “auto”, “qpsolvers”, or “qpsolvers:osqp” etc. (default: “auto”).
max_iter (int, optional) – Maximum SQP iterations (default: 50).
tol (float, optional) – Convergence tolerance on parameter update norm (default: 1e-6).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric.solve_parametric_combined(A_matrix, b_readings, E, log_steps, initial_params=None, method='leastsq', alpha=0.0001, solver_backend='auto')[source]#

Solve parametric unfolding: lmfit first, then QP refinement.

Use lmfit to find the best-fit parametric shape parameters.
Take the resulting spectrum as a starting point and refine it with a QP solver (cvxpy or qpsolvers) that adds non-negativity and a penalty toward the lmfit solution.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_detectors x n_energy).
b_readings (np.ndarray) – Measured readings (n_detectors,).
E (np.ndarray) – Energy grid in MeV.
log_steps (np.ndarray) – Logarithmic energy steps (d(ln E)).
initial_params (dict, optional) – Initial parameter values for lmfit.
method (str, optional) – lmfit method (default: “leastsq”).
alpha (float, optional) – Regularization weight for QP refinement (default: 1e-4).
solver_backend (str, optional) – QP backend for refinement: “auto”, “cvxpy”, “qpsolvers”, etc. (default: “auto”).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric2.unfold_parametric2(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, optimizer: str = 'grid', b_range: Tuple[float, float, int] = (0.5, 2.0, 5), Tf_range: Tuple[float, float, int] = (0.5, 10.0, 5), c_range: Tuple[float, float, int] = (0.5, 3.0, 4), alpha: float = 0.0001, solver_backend: str = 'auto', max_iter_qp: int = 50, tol_qp: float = 1e-06, noise_level: float = 0.05, max_iter: int = 200, tol_chi2: float = 1.0, calculate_errors: bool = False, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using the BON95 parametric method.

The optimizer parameter selects the parametric fit backend:

"grid" – grid search + NLS (default, no extra deps).
"cvxpy" – SQP via cvxpy.
"qpsolvers" – SQP via qpsolvers.
"combined" – grid search + SQP refinement.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid in MeV.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
optimizer (str) – Parametric fit optimizer (default: “grid”).
b_range (tuple) – Grid range for b: (min, max, n_points). Used by “grid”/”combined”.
Tf_range (tuple) – Grid range for Tf (MeV): (min, max, n_points). Used by “grid”/”combined”.
c_range (tuple) – Grid range for c: (min, max, n_points). Used by “grid”/”combined”.
alpha (float) – Tikhonov regularization for SQP (default: 1e-4).
solver_backend (str) – QP backend for SQP (default: “auto”).
max_iter_qp (int) – Max SQP iterations (default: 50).
tol_qp (float) – SQP convergence tolerance (default: 1e-6).
noise_level (float) – Relative uncertainty for measurements (default: 0.05 = 5%).
max_iter (int) – Max directed-divergence iterations (default: 200).
tol_chi2 (float) – Chi-squared convergence threshold (default: 1.0).
calculate_errors (bool) – Calculate Monte-Carlo errors (default: False).
n_montecarlo (int) – Number of Monte-Carlo samples (default: 100).
save_result (bool) – Save result to history (default: False).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_parametric2.solve_parametric2(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, b_meas: ndarray | None = None, optimizer: str = 'grid', b_range: Tuple[float, float, int] = (0.5, 2.0, 5), Tf_range: Tuple[float, float, int] = (0.5, 10.0, 5), c_range: Tuple[float, float, int] = (0.5, 3.0, 4), alpha: float = 0.0001, solver_backend: str = 'auto', max_iter_qp: int = 50, tol_qp: float = 1e-06, max_iter: int = 200, tol_chi2: float = 1.0) → Tuple[ndarray, bool, str, int][source]#

Solve unfolding using the full BON95 parametric pipeline.

Parametric fit using the selected optimizer.
Directed-divergence iteration refinement.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_det x n_energy).
b_readings (np.ndarray) – Measured readings (n_det,).
E (np.ndarray) – Energy grid in MeV.
ln_steps (np.ndarray) – Logarithmic bin widths.
b_meas (np.ndarray, optional) – Measurement uncertainties for weighted NLS.
optimizer (str) – Parametric fit optimizer (default: “grid”): - "grid" – grid search + NLS (default, no extra deps). - "cvxpy" – SQP via cvxpy. - "qpsolvers" – SQP via qpsolvers. - "combined" – grid search + SQP refinement.
b_range (tuple) – Grid search ranges for shape parameters (used by “grid” and “combined”).
Tf_range (tuple) – Grid search ranges for shape parameters (used by “grid” and “combined”).
c_range (tuple) – Grid search ranges for shape parameters (used by “grid” and “combined”).
alpha (float) – Tikhonov regularization for SQP optimizers (default: 1e-4).
solver_backend (str) – QP backend for SQP optimizers (default: “auto”).
max_iter_qp (int) – Max SQP iterations for QP-based optimizers (default: 50).
tol_qp (float) – SQP convergence tolerance (default: 1e-6).
max_iter (int) – Max directed-divergence iterations (default: 200).
tol_chi2 (float) – Chi-squared convergence threshold (default: 1.0).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric2.solve_bon95_parametric(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, b_range: Tuple[float, float, int] = (0.5, 2.0, 5), Tf_range: Tuple[float, float, int] = (0.5, 10.0, 5), c_range: Tuple[float, float, int] = (0.5, 3.0, 4), b_meas: ndarray | None = None, top_n: int = 5) → Tuple[Dict[str, float], float, List[Dict[str, float]]][source]#

Grid search + NLS for the BON95 parametric model.

Scans over (b, Tf, c) shape parameters, solves for optimal linear coefficients (a1..a4) at each grid point via weighted NLS, and returns the best result.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_det x n_energy).
b_readings (np.ndarray) – Measured readings (n_det,).
E (np.ndarray) – Energy grid in MeV.
ln_steps (np.ndarray) – Logarithmic bin widths.
b_range (tuple) – (min, max, n_points) for each shape parameter.
Tf_range (tuple) – (min, max, n_points) for each shape parameter.
c_range (tuple) – (min, max, n_points) for each shape parameter.
b_meas (np.ndarray, optional) – Measurement uncertainties (sigma_i). Used as weights.
top_n (int) – Number of top candidates to return.

Returns:

(best_params, best_chi2, top_candidates) best_params keys: b, Tf, c, a1, a2, a3, a4

Return type:

Tuple[dict, float, list]

bssunfold.core.unfold_parametric2.directed_divergence_iteration(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, phi0: ndarray, b_meas: ndarray | None = None, max_iter: int = 200, tol_chi2: float = 1.0, tol_rel: float = 1e-06) → Tuple[ndarray, int, float, bool][source]#

Refine spectrum via directed-divergence (I-divergence) iterations.

Multiplicative update rule (Itakura-Saito / Csiszar-Tusnady):

phi_{k+1}(E_j) = phi_k(E_j) * numerator / denominator

where:: numerator = sum_i [ A_i(E_j) * M_i / M_p_i ] denominator = sum_i [ A_i(E_j) ]

and M_p_i = sum_j A_i(E_j) * phi_k(E_j) * d(ln E)_j is the computed reading for detector i.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_det x n_energy).
b_readings (np.ndarray) – Measured readings (n_det,).
E (np.ndarray) – Energy grid in MeV.
ln_steps (np.ndarray) – Logarithmic bin widths.
phi0 (np.ndarray) – Initial spectrum guess (n_energy,).
b_meas (np.ndarray, optional) – Measurement uncertainties. If None, uniform weights.
max_iter (int) – Maximum iterations (default: 200).
tol_chi2 (float) – Stop when chi2 < tol_chi2 (default: 1.0).
tol_rel (float) – Stop when relative change in spectrum < tol_rel (default: 1e-6).

Returns:

(spectrum, n_iterations, final_chi2, converged)

Return type:

Tuple[np.ndarray, int, float, bool]

bssunfold.core.unfold_parametric2.solve_bon95_cvxpy(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, b_meas: ndarray | None = None, initial_params: Dict[str, float] | None = None, alpha: float = 0.0001, solver_backend: str = 'auto', max_iter: int = 50, tol: float = 1e-06) → Tuple[ndarray, bool, str, int][source]#

Solve BON95 parametric fitting via sequential QP using cvxpy.

Optimizes shape parameters (b, Tf, c) via SQP. At each iteration, the nonlinear model is linearized w.r.t. shape params and the resulting QP is solved with cvxpy. The linear coefficients (a1..a4) are re-solved by NLS at each step.

Parameters:

A_matrix (np.ndarray) – Response matrix (n_det x n_energy).
b_readings (np.ndarray) – Measured readings (n_det,).
E (np.ndarray) – Energy grid in MeV.
ln_steps (np.ndarray) – Logarithmic bin widths.
b_meas (np.ndarray, optional) – Measurement uncertainties for weighting.
initial_params (dict, optional) – Starting shape params {b, Tf, c}. If None, grid scan is used.
alpha (float) – Tikhonov regularization weight (default: 1e-4).
solver_backend (str) – CVXPY solver backend (default: “auto”).
max_iter (int) – Maximum SQP iterations (default: 50).
tol (float) – Convergence tolerance on parameter update norm (default: 1e-6).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric2.solve_bon95_qpsolvers(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, b_meas: ndarray | None = None, initial_params: Dict[str, float] | None = None, alpha: float = 0.0001, solver_backend: str = 'auto', max_iter: int = 50, tol: float = 1e-06) → Tuple[ndarray, bool, str, int][source]#

Solve BON95 parametric fitting via sequential QP using qpsolvers.

Same algorithm as solve_bon95_cvxpy but uses qpsolvers backends (OSQP, ECOS, etc.).

Parameters:

A_matrix (np.ndarray) – Response matrix (n_det x n_energy).
b_readings (np.ndarray) – Measured readings (n_det,).
E (np.ndarray) – Energy grid in MeV.
ln_steps (np.ndarray) – Logarithmic bin widths.
b_meas (np.ndarray, optional) – Measurement uncertainties for weighting.
initial_params (dict, optional) – Starting shape params {b, Tf, c}.
alpha (float) – Tikhonov regularization weight (default: 1e-4).
solver_backend (str) – QP solver backend (default: “auto”).
max_iter (int) – Maximum SQP iterations (default: 50).
tol (float) – Convergence tolerance (default: 1e-6).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_parametric2.solve_bon95_combined(A_matrix: ndarray, b_readings: ndarray, E: ndarray, ln_steps: ndarray, b_meas: ndarray | None = None, alpha: float = 0.0001, solver_backend: str = 'auto', max_iter_qp: int = 50, tol_qp: float = 1e-06) → Tuple[ndarray, bool, str, int][source]#

Solve BON95: grid search first, then SQP refinement.

Grid search for best starting (b, Tf, c).
SQP refinement via cvxpy or qpsolvers.

Parameters:

A_matrix (as usual.)
b_readings (as usual.)
E (as usual.)
ln_steps (as usual.)
b_meas (np.ndarray, optional) – Measurement uncertainties.
alpha (float) – Tikhonov regularization for SQP (default: 1e-4).
solver_backend (str) – QP backend: “auto”, “cvxpy:ECOS”, “qpsolvers:osqp”, etc.
max_iter_qp (int) – Max SQP iterations (default: 50).
tol_qp (float) – SQP convergence tolerance (default: 1e-6).

Returns:

(spectrum, success, message, nfev)

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_fruit_like.unfold_fruit_like(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, initial_params: Dict[str, float] | None = None, method: str = 'leastsq', calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using FRUIT-like parametric method.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid in MeV.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused in parametric method).
initial_params (Optional[Dict[str, float]], optional) – Initial parameter values for the parametric model.
method (str, optional) – lmfit solver method (default: “leastsq”).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_hybrid_parametric.unfold_hybrid_parametric(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, refinement_method: str = 'landweber', max_iterations: int = 100, tolerance: float = 1e-06, step_size: float = 0.01, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using hybrid parametric-nonparametric method.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid in MeV.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess.
refinement_method (str, optional) – Refinement method: “landweber” or “mlem” (default: “landweber”).
max_iterations (int, optional) – Maximum iterations (default: 100).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
step_size (float, optional) – Step size for Landweber (default: 0.01).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

bssunfold.core.unfold_bayesian_parametric.unfold_bayesian_parametric(detector_names: List[str], n_energy_bins: int, E_MeV: ndarray, sensitivities: Dict[str, ndarray], cc_icrp116: Dict[str, ndarray], save_result_callback, readings: Dict[str, float], initial_spectrum: ndarray | None = None, sigma: float = 0.02, n_samples: int = 1000, burn_in: int = 200, proposal_scale: float = 0.1, calculate_errors: bool = False, noise_level: float = 0.01, n_montecarlo: int = 100, save_result: bool = False, random_state: int | None = None) → Dict[str, Any][source]#

Unfold neutron spectrum using Bayesian parametric method.

Parameters:

detector_names (List[str]) – Names of available detectors.
n_energy_bins (int) – Number of energy bins.
E_MeV (np.ndarray) – Energy grid in MeV.
sensitivities (Dict[str, np.ndarray]) – Detector sensitivity arrays.
cc_icrp116 (Dict[str, np.ndarray]) – ICRP-116 conversion coefficients.
save_result_callback (callable) – Callback to save result to history.
readings (Dict[str, float]) – Detector readings.
initial_spectrum (Optional[np.ndarray], optional) – Initial spectrum guess (unused).
sigma (float, optional) – Measurement uncertainty (default: 0.02).
n_samples (int, optional) – Number of MCMC samples (default: 1000).
burn_in (int, optional) – Burn-in samples (default: 200).
proposal_scale (float, optional) – Proposal scale (default: 0.1).
calculate_errors (bool, optional) – Calculate Monte-Carlo errors (default: False).
noise_level (float, optional) – Noise level for Monte-Carlo (default: 0.01).
n_montecarlo (int, optional) – Number of Monte-Carlo samples (default: 100).
save_result (bool, optional) – Save result to history (default: True).
random_state (int, optional) – Random seed for reproducibility.

Returns:

Unfolding results dictionary.

Return type:

Dict[str, Any]

Core Functions#

Underlying solver functions:

bssunfold.core.unfold_cvxpy.solve_cvxpy(A: ndarray, b: ndarray, alpha: float, norm: int = 2, solver: str = 'ECOS', x0: ndarray | None = None) → ndarray[source]#

Solve unfolding problem using cvxpy.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
alpha (float) – Regularization parameter.
norm (int, optional) – Norm type (1 for L1, 2 for L2).
solver (str, optional) – CVXPY solver name.
x0 (np.ndarray, optional) – Not used (provided for API compatibility).

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

bssunfold.core.unfold_landweber.solve_landweber(A: ndarray, b: ndarray, x0: ndarray, max_iterations: int = 1000, tolerance: float = 1e-06) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using Landweber iteration.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_mlem.solve_mlem(A: ndarray, b: ndarray, x0: ndarray, max_iterations: int = 1000, tolerance: float = 1e-06) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using MLEM iteration.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_mlem_stop.solve_mlem_stop(A: ndarray, b: ndarray, x0: ndarray, max_iterations: int = 15000, cps_crossover: float = 30000.0, j_threshold: float | None = None) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using MLEM with J-factor stopping criterion.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
max_iterations (int, optional) – Maximum iterations (default: 15000).
cps_crossover (float, optional) – Crossover CPS value for automatic J threshold (default: 30000). Used only when j_threshold is None.
j_threshold (float, optional) – J-factor stopping threshold. If None, computed as mean(b) / cps_crossover.

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_qpsolvers.solve_qpsolvers(A: ndarray, b: ndarray, alpha: float, norm: int = 2, solver: str = 'osqp', x0: ndarray | None = None, smoothness_order: int = 0, smoothness_weight: float = 1.0) → ndarray | None[source]#

Solve unfolding problem using qpsolvers.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
alpha (float) – Regularization parameter.
norm (int, optional) – Norm type (1 for L1, 2 for L2).
solver (str, optional) – QP solver name (default: ‘osqp’).
x0 (np.ndarray, optional) – Initial values.
smoothness_order (int, optional) – Smoothness constraint order (0, 1, or 2).
smoothness_weight (float, optional) – Weight for smoothness term.

Returns:

Unfolded spectrum or None if solving failed.

Return type:

Optional[np.ndarray]

bssunfold.core.unfold_doroshenko.solve_doroshenko(A: ndarray, b: ndarray, x0: ndarray, max_iterations: int = 1000, tolerance: float = 1e-06, regularization: float = 0.0) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using Doroshenko coordinate update method.

Uses incremental residual update for O(n) per-coordinate complexity instead of O(n^2) from full matrix-vector products.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
max_iterations (int, optional) – Maximum iterations (default: 1000).
tolerance (float, optional) – Convergence tolerance (default: 1e-6).
regularization (float, optional) – Regularization strength to prevent division by zero (default: 0.0).

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_kaczmarz.solve_kaczmarz(A: ndarray, b: ndarray, x0: ndarray, max_iterations: int = 1000, omega: float = 1.0, tolerance: float = 1e-06) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using Kaczmarz algorithm (ART).

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
max_iterations (int, optional) – Maximum iterations (default: 1000).
omega (float, optional) – Relaxation parameter (0 < omega <= 2), default: 1.0.
tolerance (float, optional) – Convergence tolerance (default: 1e-6).

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_lmfit.solve_lmfit(A: ndarray, b: ndarray, x0: ndarray, method: str = 'lbfgsb', model_name: str = 'elastic', regularization: float = 0.0001, regularization2: float = 0.0001, l1_weight: float = 0.5) → Tuple[ndarray, bool, str, int][source]#

Solve unfolding problem using lmfit with L1/L2/Elastic regularization.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial guess (n,).
method (str, optional) – lmfit solver name (leastsq, lbfgsb, etc.), default: “lbfgsb”.
model_name (str, optional) – Regularization model: elastic, lasso, ridge, default: “elastic”.
regularization (float, optional) – L1 regularization strength, default: 1e-4.
regularization2 (float, optional) – L2 regularization strength for elastic net, default: 1e-4.
l1_weight (float, optional) – L1 weight for elastic net (0=pure L2, 1=pure L1), default: 0.5.

Returns:

Tuple of (solution, success, message, nfev).

Return type:

Tuple[np.ndarray, bool, str, int]

bssunfold.core.unfold_gravel.solve_gravel(A: ndarray, b: ndarray, x0: ndarray, tolerance: float = 1e-08, max_iterations: int = 1000, regularization: float = 0.0) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using the GRAVEL algorithm.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Initial spectrum guess (n,).
tolerance (float, optional) – Convergence tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum iterations (default: 1000).
regularization (float, optional) – Regularization parameter (default: 0.0).

Returns:

Tuple of (solution, iterations, converged).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_maxed.solve_maxed(A: ndarray, b: ndarray, x0: ndarray, sigma_factor: float = 0.1, max_iterations: int = 5000, tolerance: float = 1e-06) → Tuple[ndarray, int, bool][source]#

Solve unfolding problem using MAXED (Maximum Entropy Deconvolution).

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray) – Reference (prior) spectrum (n,).
sigma_factor (float, optional) – Relative measurement uncertainty (default: 0.1). Larger values → smoother spectrum (weaker data term).
max_iterations (int, optional) – Maximum L-BFGS-B iterations (default: 5000).
tolerance (float, optional) – Gradient convergence tolerance (default: 1e-6).

Returns:

(solution spectrum, iterations used, converged flag).

Return type:

Tuple[np.ndarray, int, bool]

bssunfold.core.unfold_tikhonov_legendre.solve_tikhonov_legendre(A: ndarray, b: ndarray, x0: ndarray | None = None, delta: float = 0.05, n_polynomials: int = 15) → ndarray[source]#

Solve unfolding using Tikhonov regularization with Legendre basis.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Not used (provided for API compatibility).
delta (float, optional) – Regularization parameter (default: 0.05).
n_polynomials (int, optional) – Number of Legendre polynomials (default: 15).

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

bssunfold.core.unfold_bayes.solve_bayes(A: ndarray, b: ndarray, x0: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001) → ndarray[source]#

Solve unfolding problem using Bayesian iterative unfolding (D’Agostini).

Pure numpy implementation of the D’Agostini algorithm. The response matrix is column-normalised so each column sums to 1 (conditional probability P(D_j | E_i)), then the result is rescaled to physical units via division by the column sums.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Prior spectrum. If None, uniform prior is used.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Relative L2 convergence tolerance (default: 1e-3).

Returns:

Unfolded spectrum (n,) in physical units.

Return type:

np.ndarray

bssunfold.core.unfold_bayes_spline_regularization.solve_bayes_spline(A: ndarray, b: ndarray, x0: ndarray | None = None, max_iterations: int = 4000, tolerance: float = 0.001, spline_degree: int = 3, spline_smooth: float = 0.01) → ndarray[source]#

Solve unfolding problem using Bayes with spline regularization.

Implements the D’Agostini iterative Bayesian unfolding from scratch. The response matrix is column-normalised (each column sums to 1) so the algorithm works in effective-count space, but the UnivariateSpline smoother is applied to the physical spectrum to avoid boundary artifacts that appear when rescaling low-sensitivity bins back to physical units.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Prior spectrum.
max_iterations (int, optional) – Maximum iterations (default: 4000).
tolerance (float, optional) – Relative L2 convergence tolerance (default: 1e-3).
spline_degree (int, optional) – Spline degree (default: 3).
spline_smooth (float, optional) – Spline smoothing parameter (default: 1e-2).

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

bssunfold.core.unfold_statreg.solve_statreg(A: ndarray, b: ndarray, x0: ndarray | None = None, E_MeV: ndarray | None = None, unfoldermethod: str = 'EmpiricalBayes', regularization: float | None = None, basis_name: str = 'CubicSplines', boundary: str | None = None, derivative_degree: int = 2) → ndarray[source]#

Solve unfolding problem using Turchin’s statistical regularisation.

Parameters:

A (np.ndarray) – Response matrix (m × n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Not used (provided for API compatibility).
E_MeV (np.ndarray, optional) – Energy grid (n,). Used for log-energy penalty scaling.
unfoldermethod (str, optional) – Regularisation method: 'EmpiricalBayes' (L-curve, default) or 'User' (fixed α).
regularization (float, optional) – Regularisation parameter α for 'User' method (default: 1e-4).
basis_name (str, optional) – Ignored (kept for API compatibility).
boundary (str, optional) – Ignored (kept for API compatibility).
derivative_degree (int, optional) – Derivative order for penalty. Only 2 is implemented.

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

bssunfold.core.unfold_reconst.solve_reconst(A: ndarray, b: ndarray, x0: ndarray | None = None, E_MeV: ndarray | None = None, pp: float = 0.001, alpha: float = -1.0, beta: float = 0.0, sigma_b: ndarray | None = None) → ndarray[source]#

Solve unfolding problem using Turchin’s statistical regularization.

Pure numpy implementation of the RECONST.FOR algorithm (STREG1). Solves (B * beta + Omega * alpha) * f = A_vec * beta.

Parameters:

A (np.ndarray) – Response matrix (M, N).
b (np.ndarray) – Measurement vector (M,).
x0 (np.ndarray, optional) – Ignored (API compatibility).
E_MeV (np.ndarray, optional) – Ignored (API compatibility).
pp (float, optional) – PP parameter (default: 1e-3).
alpha (float, optional) – Regularization. >0 fixed, <0 auto (default: -1).
beta (float, optional) – Data fidelity. >0 fixed, <=0 auto (default: 0).
sigma_b (np.ndarray, optional) – Measurement uncertainties (M,). If None, sqrt(b) used.

Returns:

Unfolded spectrum (N,).

Return type:

np.ndarray

bssunfold.core.unfold_scipy_direct_method.solve_scipy_direct(A: ndarray, b: ndarray, x0: ndarray | None = None, tolerance: float = 1e-08, max_iterations: int = 4000, method: str = 'cg') → ndarray[source]#

Solve unfolding problem using scipy sparse linear solvers.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Not used (provided for API compatibility).
tolerance (float, optional) – Solver tolerance (default: 1e-8).
max_iterations (int, optional) – Maximum solver iterations (default: 4000).
method (str, optional) – Solver method. One of: ‘cg’, ‘cgs’, ‘bicgstab’, ‘gmres’, ‘lgmres’, ‘minres’, ‘gcrotmk’, ‘qmr’, ‘tfqmr’, ‘lsqr’, ‘lsmr’ (default: ‘cg’).

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

bssunfold.core.unfold_tsvd.solve_tsvd(A: ndarray, b: ndarray, x0: ndarray | None = None, method: str = 'discrepancy', k: int | None = None, threshold: float | None = None, noise_level: float | None = None) → ndarray[source]#

Solve unfolding problem using Truncated SVD (TSVD).

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
x0 (np.ndarray, optional) – Not used (provided for API compatibility).
method (str, optional) – K-selection method: ‘discrepancy’, ‘l_curve’, ‘gcv’, ‘energy’, ‘threshold_ratio’, ‘median_threshold’, ‘donoho’ (default: ‘discrepancy’).
k (int, optional) – Fixed number of singular values to keep. Overrides method.
threshold (float, optional) – Threshold ratio for singular value truncation.
noise_level (float, optional) – Noise level estimate for discrepancy principle.

Returns:

Unfolded spectrum (n,).

Return type:

np.ndarray

Comparison Methods#

Compare two spectra using selected metrics.

Parameters:

spectrum1 (np.ndarray) – 1-D arrays of the same length.
spectrum2 (np.ndarray) – 1-D arrays of the same length.
metrics (str, list of str, or None) – Metric name(s). If None, all available metrics are computed (simple metrics only; pass energy to include EURADOS metrics).
bins (np.ndarray, optional) – Energy bins (unused, reserved for future use).
energy (np.ndarray, optional) – Energy grid in MeV. When provided, EURADOS-style metrics (dose differences, peak errors, etc.) are included automatically.
cc_icrp116 (np.ndarray, optional) – ICRP-116 conversion coefficients for dose calculations.
readings1 (np.ndarray, optional) – Measured readings for response-matrix consistency check.
readings2 (np.ndarray, optional) – Measured readings for response-matrix consistency check.
response_matrix (np.ndarray, optional) – Response matrix for consistency check.

Returns:

Mapping from metric name (short key) to computed value.

Return type:

Dict[str, float]

bssunfold.utils.comparison.compare_multiple(spectra: List[ndarray], metrics: str | List[str] | None = None, labels: List[str] | None = None) → Dict[str, Dict[str, float]][source]#

Compare multiple spectra pairwise against the first one.

Parameters:

spectra (list of np.ndarray) – List of spectra. First entry is treated as reference.
metrics (str, list of str, or None) – Metric name(s). If None, all available metrics are computed.
labels (list of str, optional) – Labels for each spectrum.

Returns:

{label: {metric: value}} for each non-reference spectrum.

Return type:

Dict[str, Dict[str, float]]

Comparison Metrics#

Entropy-based#

bssunfold.utils.comparison.kl_divergence(p: ndarray, q: ndarray) → float[source]#

Kullback–Leibler divergence D_KL(p || q).

Both inputs are normalized to probability distributions internally.

bssunfold.utils.comparison.cross_entropy(p: ndarray, q: ndarray) → float[source]#: Cross-entropy H(p, q) = -sum(p * log(q)).

bssunfold.utils.comparison.entropy(p: ndarray) → float[source]#: Shannon entropy H(p) = -sum(p * log(p)).

bssunfold.utils.comparison.entropy_difference_percent(p: ndarray, q: ndarray) → float[source]#

Relative difference between cross-entropy and entropy in percent.

100 * (H(p,q) - H(p)) / H(p)

Distribution distances#

bssunfold.utils.comparison.wasserstein_dist(p: ndarray, q: ndarray) → float[source]#

Wasserstein (earth mover’s) distance between two distributions.

Uses scipy.stats.wasserstein_distance.

bssunfold.utils.comparison.energy_dist(p: ndarray, q: ndarray) → float[source]#

Energy distance between two distributions.

Uses scipy.stats.energy_distance.

bssunfold.utils.comparison.kolmogorov_smirnov_stat(p: ndarray, q: ndarray) → float[source]#: Kolmogorov-Smirnov test statistic (D statistic).

Correlation#

bssunfold.utils.comparison.pearson_r(p: ndarray, q: ndarray) → float[source]#

Pearson correlation coefficient.

Returns 0.0 if either input is constant (variance = 0).

bssunfold.utils.comparison.spearman_r(p: ndarray, q: ndarray) → float[source]#

Spearman rank correlation coefficient.

Returns 0.0 if either input is constant (variance = 0).

Error metrics#

bssunfold.utils.comparison.mean_squared_error(p: ndarray, q: ndarray) → float[source]#: Mean squared error.

bssunfold.utils.comparison.root_mean_squared_error(p: ndarray, q: ndarray) → float[source]#: Root mean squared error.

bssunfold.utils.comparison.mean_absolute_error(p: ndarray, q: ndarray) → float[source]#: Mean absolute error.

bssunfold.utils.comparison.mape(p: ndarray, q: ndarray) → float[source]#

Mean absolute percentage error.

Returns percentage (0–100). Skips elements where p is near zero.

bssunfold.utils.comparison.r2_score(p: ndarray, q: ndarray) → float[source]#: R-squared (coefficient of determination).

bssunfold.utils.comparison.max_error(p: ndarray, q: ndarray) → float[source]#: Maximum residual error.

bssunfold.utils.comparison.median_absolute_error(p: ndarray, q: ndarray) → float[source]#: Median absolute error.

Kernel / similarity#

bssunfold.utils.comparison.cosine_similarity(p: ndarray, q: ndarray) → float[source]#

Cosine similarity between two vectors.

Returns 0 if either vector is zero-norm.

bssunfold.utils.comparison.mmd_rbf(p: ndarray, q: ndarray, gamma: float | None = None) → float[source]#

Maximum Mean Discrepancy with RBF kernel.

Parameters:

p (np.ndarray) – 1-D arrays.
q (np.ndarray) – 1-D arrays.
gamma (float, optional) – RBF kernel width. If None, uses 1 / (2 * median_distance**2).

Chi-squared family#

bssunfold.utils.comparison.chi_squared(p: ndarray, q: ndarray) → float[source]#

Pearson’s chi-squared test statistic.

Internally normalizes both inputs as probability distributions.

bssunfold.utils.comparison.g_test(p: ndarray, q: ndarray) → float[source]#: G-test (log-likelihood ratio) statistic.

bssunfold.utils.comparison.freeman_tukey(p: ndarray, q: ndarray) → float[source]#: Freeman-Tukey statistic.

bssunfold.utils.comparison.cressie_read(p: ndarray, q: ndarray) → float[source]#: Cressie-Read statistic.

Statistical tests#

bssunfold.utils.comparison.anderson_darling(p: ndarray, q: ndarray) → float[source]#

Anderson-Darling test statistic for k-samples.

Returns 0.0 if either input is constant (all identical values).

bssunfold.utils.comparison.wilcoxon_test(p: ndarray, q: ndarray) → float[source]#

Wilcoxon signed-rank test statistic.

Returns 0.0 if both inputs are identical (all differences zero).

bssunfold.utils.comparison.mannwhitneyu_test(p: ndarray, q: ndarray) → float[source]#: Mann-Whitney U test statistic.

bssunfold.utils.comparison.standardized_mean_difference(p: ndarray, q: ndarray) → float[source]#

Standardized mean difference (Cohen’s d).

SMD = (mean(p) - mean(q)) / sqrt((var(p) + var(q)) / 2)

Regularization Selection#

bssunfold.core.regularization.select_regularization_parameter(A: ndarray, b: ndarray, method: str = 'lcurve', noise_var: float | None = None, initial_spectrum: ndarray | None = None, **kwargs) → float[source]#

Select regularization parameter using specified method.

Parameters:

A (np.ndarray) – Response matrix (m x n).
b (np.ndarray) – Measurement vector (m,).
method (str, optional) – Selection method: ‘lcurve’, ‘gcv’, ‘dp’, ‘cosine’ (default: ‘lcurve’).
noise_var (float, optional) – Noise variance for discrepancy principle.
initial_spectrum (np.ndarray, optional) – Initial spectrum for cosine similarity method.
**kwargs (dict) – Additional method-specific arguments.

Returns:

Selected regularization parameter (lambda).

Return type:

float

Raises:

ValueError – If method is unknown or selection fails.

bssunfold.core.regularization.lcurve_selection(A: ndarray, b: ndarray, n_alphas: int = 50, alpha_range: Tuple[float, float] = (1e-09, 100.0)) → float[source]#

Select regularization parameter using L-curve corner heuristic.

Parameters:

A (np.ndarray) – Response matrix.
b (np.ndarray) – Measurement vector.
n_alphas (int, optional) – Number of alpha values to test (default: 50).
alpha_range (Tuple[float, float], optional) – Range of alpha values (default: (1e-9, 1e2)).

Returns:

Selected regularization parameter.

Return type:

float

bssunfold.core.regularization.gcv_selection(A: ndarray, b: ndarray, n_alphas: int = 50, alpha_range: Tuple[float, float] = (1e-09, 100.0)) → float[source]#

Select regularization parameter using Generalized Cross Validation.

Parameters:

A (np.ndarray) – Response matrix.
b (np.ndarray) – Measurement vector.
n_alphas (int, optional) – Number of alpha values to test (default: 50).
alpha_range (Tuple[float, float], optional) – Range of alpha values (default: (1e-9, 1e2)).

Returns:

Selected regularization parameter.

Return type:

float

bssunfold.core.regularization.discrepancy_principle_selection(A: ndarray, b: ndarray, noise_var: float | None = None, n_alphas: int = 50, alpha_range: Tuple[float, float] = (1e-09, 100.0)) → float[source]#

Select regularization parameter using Discrepancy Principle.

Parameters:

A (np.ndarray) – Response matrix.
b (np.ndarray) – Measurement vector.
noise_var (float, optional) – Noise variance. If None, estimated from data.
n_alphas (int, optional) – Number of alpha values to test (default: 50).
alpha_range (Tuple[float, float], optional) – Range of alpha values (default: (1e-9, 1e2)).

Returns:

Selected regularization parameter.

Return type:

float

bssunfold.core.regularization.cosine_similarity_selection(A: ndarray, b: ndarray, initial_spectrum: ndarray, n_alphas: int = 100, alpha_range: Tuple[float, float] = (-9, 2), norm: int = 2) → float[source]#

Select regularization parameter by maximizing cosine similarity.

Uses precomputed SVD for efficient evaluation across alpha values.

Parameters:

A (np.ndarray) – Response matrix.
b (np.ndarray) – Measurement vector.
initial_spectrum (np.ndarray) – Initial/reference spectrum for similarity comparison.
n_alphas (int, optional) – Number of alpha values to test (default: 100).
alpha_range (Tuple[float, float], optional) – Log range of alpha values (default: (-9, 2)).
norm (int, optional) – Norm type for regularization (default: 2).

Returns:

Selected regularization parameter.

Return type:

float