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]) – ICRP-116 conversion coefficients for dose calculation
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.

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.

_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 = True, 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 = True, 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 = True, 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 = True, 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_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 = True, 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 = True, 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_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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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]

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]

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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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_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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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 = True, 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_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 = True, 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 = True, 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]

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_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_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

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