andalus package

Submodules

andalus.application module

Module containing the Application and ApplicationSuite classes, which are used to represent and manage application data.

class andalus.application.Application(title: str, kind: str, c: float, dc: float, s: Sensitivity, m: float | None = None, dm: float | None = None, flux: FluxSpectrum | None = None)

Bases: object

An application is a calculation without an associated measurement.

title

The unique name or identifier for the application.

Type:

str

kind

The kind of the observable (e.g., “keff”, “void”).

Type:

str

c

The calculated value (Nominal).

Type:

float

dc

The uncertainty of the calculation.

Type:

float

s

The energy-dependent sensitivity profiles.

Type:

Sensitivity

m

The measured value, if available.

Type:

float or None, optional

dm

The measurement uncertainty, if available.

Type:

float or None, optional

flux

The energy-dependent flux spectrum. None when not available.

Type:

FluxSpectrum or None, optional

c: float

dc: float

dm: float | None = None

flux: FluxSpectrum | None = None

classmethod from_hdf5(file_path, title: str, kind: str = 'keff')

Create an Application instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the application data.

• title (str) – Title of the application to load.

• kind (str, optional) – Type of application (e.g., “keff”). Default is “keff”.

Returns:

A new Application instance with the loaded data.

Return type:

Application

classmethod from_serpent(title: str, sens0_path: str, results_path: str, kind: str = 'keff', materials=None, zailist=None, pertlist=None, m: float | None = None, dm: float | None = None, flux_det: tuple[str, str] | None = None)

Create an Application from Serpent output files.

Parameters:

• title (str) – Title of the application.

• sens0_path (str) – Path to the Serpent _sens0.m sensitivity file.

• results_path (str) – Path to the Serpent _res.m results file.

• kind (str, optional) – Kind of observable, by default "keff".

• materials (list of str, optional) – Materials for which the sensitivity is extracted. Defaults to ["total"].

• zailist (list of int, optional) – ZAIs to extract from the sensitivity file. Defaults to all ZAIs present in the file.

• pertlist (list of str, optional) – Perturbations to extract from the sensitivity file. Defaults to the standard set of reactions.

• m (float, optional) – Measured value for the application. Default is None.

• dm (float, optional) – Measurement uncertainty. Default is None.

• flux_det (tuple of (str, str), optional) – A (det_name, det_path) pair identifying the Serpent detector whose tally is used to build a FluxSpectrum. When None (default) no flux spectrum is attached.

Returns:

An Application with the calculated value, sensitivity, and (optionally) flux spectrum extracted from the Serpent files.

Return type:

Application

kind: str

m: float | None = None

plot_sensitivity(zais, perts, ax=None, **kwargs)

Plot the sensitivity profiles for the application.

Parameters:

• zais (list) – List of zais to be included in the plot.

• perts (list) – List of perts to be included in the plot.

• ax (plt.Axes, optional) – Ax for the plot to be displayed. If None, a new figure and axis will be created.

• **kwargs – Additional keyword arguments to be passed to the plotting function.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

print_summary()

Print a quick summary of an application object.

s: Sensitivity

title: str

to_hdf5(file_path='benchmarks.h5')

Save the application data to an HDF5 file.

Parameters:

file_path (str, optional) –

The path to the HDF5 file where the application data will be saved.

Default is ‘benchmarks.h5’.

class andalus.application.ApplicationSuite(applications: dict[str, ~andalus.application.Application]=<factory>)

Bases: object

A applicationsuite is a combined set of application objects.

applications

A dictionary of application objects, indexed by their title.

Type:

dict[str, Application]

applications: dict[str, Application]

property c: Series

Returns a pd.Series of application calculated values in the suite.

Returns:

Series of application calculated values in the suite.

Return type:

pd.Series of float

property dc: Series

Returns a pd.Series of application calculated uncertainties in the suite.

Returns:

Series of application calculated uncertainties in the suite.

Return type:

pd.Series of float

property dm: Series

Returns a pd.Series of application measured uncertainties in the suite.

Returns:

Series of application measured uncertainties in the suite.

Return type:

pd.Series of float

property ds: DataFrame

Returns a pd.DataFrame of sensitivity uncertainties in the suite.

Returns:

DataFrame of sensitivity uncertainties in the suite.

Return type:

pd.DataFrame

filter(filter_fn) → ApplicationSuite

Filter the ApplicationSuite based on a filter function.

Parameters:

filter_fn (function) –

A function that takes an Application object as input and returns a boolean

indicating whether to include the application in the filtered suite.

classmethod from_hdf5(file_path: str, titles: list, kind: str = 'keff')

Retrieve a set of applications from a database.

Parameters:

• file_path (str) – file path where the database is located.

• titles (list, optional) – Titles which have to be extracted from the database, if None return all the applications available in the database, by default None.

Returns:

Returns a BenchmarkSuite object containing the imported Benchmark objects.

Return type:

BenchmarkSuite

classmethod from_list(applications: list[Application])

Method to create an ApplicationSuite instance from a list of Application objects.

Parameters:

applications (list[Application]) – A list of Application objects to be included in the suite.

Returns:

An instance of ApplicationSuite containing the provided applications.

Return type:

ApplicationSuite

classmethod from_yaml(path: str)

Factory method to create an ApplicationSuite instance from a YAML configuration file.

Parameters:

path (str) – The path to the YAML configuration file.

Returns:

An instance of ApplicationSuite populated with data from the YAML file.

Return type:

ApplicationSuite

get(title: str) → Application | None

Get an application from the suite.

Parameters:

title (str) – Title of the application to be retrieved.

Returns:

Application object.

Return type:

Application

items()

Return the suite’s applications as (title, Application) pairs.

Returns:

A view of the internal application dictionary items, which are of type Application.

Return type:

dict_items

keys()

Return an iterator over the application titles.

property kinds: Series

Returns a pd.Series of application types in the suite.

Returns:

Series of application types in the suite.

Return type:

pd.Series of str

property m: Series

Returns a pd.Series of application measured values in the suite.

Returns:

Series of application measured values in the suite.

Return type:

pd.Series of float

remove(title: str)

Remove application from the suite.

Parameters:

title (str) – Title of the application to be removed.

property s: DataFrame

Returns a pd.DataFrame of sensitivity objects in the suite.

Returns:

DataFrame of sensitivity objects in the suite.

Return type:

pd.DataFrame

property titles: list

Returns a list of application titles in the suite.

Returns:

List of application titles in the suite.

Return type:

list of str

update_c(new_c: Series) → ApplicationSuite

Create a new ApplicationSuite with updated calculated values.

This method is typically used to generate a posterior suite after an assimilation update (e.g., GLLS).

Parameters:

new_c (pd.Series) – A series containing the updated ‘c’ values, indexed by application title.

Returns:

A new instance of the suite containing updated Application objects.

Return type:

ApplicationSuite

Raises:

KeyError – If an applicaiton title in the suite is missing from the index of new_c.

values()

Return an iterator over the application objects.

property zais: list

Returns a list of unique ZAIs in the sensitivity data of the applications in the suite.

Returns:

List of unique ZAIs in the sensitivity data of the applications in the suite.

Return type:

list of int

andalus.assimilation module

Module containing the AssimilationSuite class, which is used to manage a collection of benchmark, application and covariance data for assimilation purposes.

class andalus.assimilation.AssimilationSuite(benchmarks: BenchmarkSuite, applications: ApplicationSuite, covariances: CovarianceSuite, xs_adjustment: Series | None = None, prior_c: Series | None = None)

Bases: object

Class to manage a collection of benchmark, application and covariance data for assimilation purposes. This class can be used to assemble a complete dataset for assimilation, and to perform operations on the entire suite.

applications: ApplicationSuite

benchmarks: BenchmarkSuite

property c

Concatenate calculated values from all benchmarks and applications.

This property gathers calculated values from available benchmark and application suites, aligns them by their titles, and fills missing values with zeros to create a unified calculated value vector.

Returns:

A combined Series containing calculated values, aligned by index.

Return type:

pd.Series

Raises:

ValueError – If both benchmarks and applications are None or empty.

chi_squared(nuclear_data: bool = False) → float

Calculate the total chi-squared for the suite.

\[\]

chi^2 = (m - c)^T C^{-1} (m - c)

Parameters:

nuclear_data (bool, optional) – Whether to include the contribution of the nuclear data uncertainty in the chi² calculation, by default False.

ck_matrix() → DataFrame

Generate a ck-similarity matrix for the current assimilation suite.

Returns:

A dataframe containing the similarity coefficients between all benchmarks and applications in the AssimilationSuite.

Return type:

pd.DataFrame

ck_target(target: str) → Series

Calculate the ck-similarity of all sensitivities in the suite with a specified target sensitivity profile.

Parameters:

target (str) – The name of the target sensitivity profile to compare against.

Returns:

A Series containing the ck-similarity values for each sensitivity profile in the suite compared to the target.

Return type:

pd.Series

covariances: CovarianceSuite

property dc

Concatenate calculated value uncertainties from all benchmarks and applications.

This property gathers calculated value uncertainties from available benchmark and application suites, aligns them by their titles, and fills missing values with zeros to create a unified calculated value uncertainty vector.

Returns:

A combined Series containing calculated value uncertainties, aligned by index.

Return type:

pd.Series

Raises:

ValueError – If both benchmarks and applications are None or empty.

property dm

Return experimental uncertainty values from the benchmark and application suites.

Returns:

A Series containing the experimental uncertainty values from the benchmark and application suites.

Return type:

pd.Series

property ds

Concatenate sensitivity uncertainties data from all benchmarks and applications.

This property gathers sensitivity uncertainty vectors from available benchmark and application suites, aligns them by their MultiIndex, and fills missing values with zeros to create a unified sensitivity uncertainty matrix.

Returns:

A combined DataFrame containing sensitivity uncertainties, aligned along the columns (axis=1).

Return type:

pd.DataFrame

Raises:

ValueError – If both benchmarks and applications are None or empty.

e_index_matrix() → DataFrame

Generate an E-index similarity matrix for the assimilation suite.

The E-index measures the physical similarity between two sensitivity profiles without the influence of a covariance matrix:

\[E_{ij} = \frac{S_i^T S_j}{\sqrt{S_i^T S_i \cdot S_j^T S_j}}\]

This is the cosine similarity of the sensitivity vectors.

Returns:

A DataFrame with shape (N, N) containing the E-index values between every pair of benchmarks and applications in the suite. Entries are NaN when either sensitivity vector is all zeros.

Return type:

pd.DataFrame

filter(filter_fn) → AssimilationSuite

Filter the benchmarks available in the assimilation suite based on a provided filter function.

Parameters:

filter_fn (function or Filter) – A function that takes a Benchmark object and returns True if it should be included in the filtered suite.

classmethod from_yaml(path: str = 'assimilation_suite.yaml')

Factory method to create an AssimilationSuite instance from a YAML configuration file.

Parameters:

path (str, optional) – The path to the YAML configuration file, by default “assimilation_suite.yaml”.

Returns:

An instance of AssimilationSuite populated with data from the YAML file.

Return type:

AssimilationSuite

glls(include_sensitivity_uncertainty: bool = False) → AssimilationSuite

Perform a GLLS update [1] on the assimilation suite using the sensitivity profiles and covariance data loaded in the AssimilationSuite. This method updates the calculated response and the covariance matrices.

Returns:

A new AssimilationSuite instance with updated sensitivity profiles.

Return type:

AssimilationSuite

References

[1]

B. L. Broadhead, B. T. Rearden, C. M. Hopper, J. J. Wagschal, and C. V. Parks, “Sensitivity- and Uncertainty-Based Criticality Safety Validation Techniques,” Nuclear Science and Engineering, vol. 146, no. 3, pp. 340–366, Mar. 2004, doi: 10.13182/NSE03-2.

individual_chi_squared(nuclear_data: bool = False) → Series

Calculate individual chi-squared for each benchmark in the suite.

\[\]

chi^2 = frac{(m - c)^2}{sigma_m^2 + sigma_c^2 + s^T C s}

Parameters:

nuclear_data (bool, optional) – Whether to include the contribution of the nuclear data uncertainty in the chi² calculation, by default False.

property is_posterior: bool

Check if the assimilation suite contains posterior data by checking if nd_adjustments is not None.

Returns:

True if the suite contains posterior data, False otherwise.

Return type:

bool

property m

Return experimental values from the benchmark and application suites.

Returns:

A Series containing the experimental values from the benchmark and application suites.

Return type:

pd.Series

prior_c: Series | None = None

property prior_discrepancy: Series

Return the prior discrepancy between calculated and measured responses for the benchmarks.

Returns:

A Series containing the prior discrepancy for each benchmark in the suite.

Return type:

pd.Series

propagate_nuclear_data_uncertainty()

Propagate the nuclear data uncertainty through the sensitivity profiles to calculate the contribution of the nuclear data uncertainty to the overall uncertainty in the calculated values.

Returns:

A Series containing the propagated nuclear data uncertainty for each case in the suite.

Return type:

pd.Series

property s

Concatenate sensitivity data from all benchmarks and applications.

This property gathers sensitivity vectors from available benchmark and application suites, aligns them by their MultiIndex, and fills missing values with zeros to create a unified sensitivity matrix.

Returns:

A combined DataFrame containing sensitivities, aligned along the columns (axis=1).

Return type:

pd.DataFrame

Raises:

ValueError – If both benchmarks and applications are None or empty.

summarize()

Print a summary of the assimilation suite, including the number of benchmarks and applications, the titles of the cases included, and the chi-squared values with and without nuclear data.

property titles

Get a list of all case titles in the assimilation suite, including both benchmarks and applications.

Returns:

A list of strings representing the titles of all cases in the suite.

Return type:

list

to_ace(library: str, reaction_dict=None, verbose: bool = False, temperature: int = 300, create_xsdata: bool = False, parallel: bool = False, max_workers: int | None = None, only_zais_applications: bool = False)

Export the current assimilation suite to an adjusted ACE library format via SANDY.

This method iterates through the unique ZAIs in the cross-section adjustments, retrieves the base ENDF6 files from the specified library, applies the calculated perturbations, and generates ACE files. Optionally, it can append entries to a Serpent-style ‘xsdata’ directory file.

Parameters:

• library (str) – Path to the base ENDF6 library or the name of the library recognized by sandy.

• reaction_dict (dict, optional) – A dictionary mapping ENDF6 MT numbers to reaction types. Default handles standard cross-sections (MF31, 33, 34, 35). Format: {MF: [MT_list]}.

• verbose (bool, default False) – If True, prints detailed progress and SANDY execution logs.

• temperature (int, default 300) – The temperature in Kelvin for the ACE file generation.

• create_xsdata (bool, default False) – If True, appends isotope definitions to ‘adjusted.xsdata’ formatted for the Serpent Monte Carlo code.

• parallel (bool, default False) – If True, process ZAIs concurrently using a thread pool.

• max_workers (int | None, default None) – Maximum number of worker threads used when parallel=True. If None, Python chooses a default.

• only_zais_applications (bool, default False) – If True, only process ZAIs that are present in the application suite,

Raises:

ValueError – If self.xs_adjustment is None, indicating no posterior has been calculated.

Notes

• Currently the method supports perturbations to nubar, cross sections

and prompt fission neutron energy spectrum.

See also

sandy.get_endf6_file

The underlying function for library retrieval.

sandy.Samples

Object used to containerize perturbations.

sandy.Endf6.apply_perturbations

The function that applies perturbations and generates ACE files.

xs_adjustment: Series | None = None

andalus.benchmark module

Module containing the Benchmark and BenchmarkSuite classes, which are used to represent and manage benchmark data.

class andalus.benchmark.Benchmark(title: str, kind: str, m: float, dm: float, c: float, dc: float, s: Sensitivity, flux: FluxSpectrum | None = None)

Bases: object

A benchmark is an application that has an associated measurement.

title

The unique name or identifier for the application.

Type:

str

kind

The kind of the observable (e.g., “keff”, “void”).

Type:

str

m

The measured value (Nominal).

Type:

float

dm

The uncertainty of the measurement.

Type:

float

c

The calculated value (Nominal).

Type:

float

dc

The uncertainty of the calculation.

Type:

float

s

The energy-dependent sensitivity profiles.

Type:

Sensitivity

flux

The energy-dependent flux spectrum. None when not available.

Type:

FluxSpectrum or None, optional

c: float

chi_squared() → float

Calculate the experimental chi-squared value for the benchmark.

Returns:

The experimental chi-squared value calculated as ((m - c) / dm)^2.

Return type:

float

dc: float

dm: float

flux: FluxSpectrum | None = None

classmethod from_hdf5(file_path, title: str, kind: str = 'keff')

Create a Benchmark instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the benchmark data.

• title (str) – Title of the benchmark to load.

• kind (str, optional) – Type of benchmark (e.g., "keff"). Default is "keff".

Returns:

A new Benchmark instance with the loaded data.

Return type:

Benchmark

classmethod from_serpent(title: str, m: float, dm: float, sens0_path: str, results_path: str, kind: str = 'keff', materials=None, zailist=None, pertlist=None, flux_det: tuple[str, str] | None = None)

Create a Benchmark from Serpent output files.

Parameters:

• title (str) – Title of the benchmark.

• m (float) – Measured value.

• dm (float) – Measurement uncertainty.

• sens0_path (str) – Path to the Serpent _sens0.m sensitivity file.

• results_path (str) – Path to the Serpent _res.m results file.

• kind (str, optional) – Kind of observable, by default "keff".

• materials (list of str, optional) – Materials for which the sensitivity is extracted. Defaults to ["total"].

• zailist (list of int, optional) – ZAIs to extract from the sensitivity file. Defaults to all ZAIs present in the file.

• pertlist (list of str, optional) – Perturbations to extract from the sensitivity file. Defaults to the standard set of reactions.

• flux_det (tuple of (str, str), optional) – A (det_name, det_path) pair identifying the Serpent detector whose tally is used to build a FluxSpectrum. When None (default) no flux spectrum is attached.

Returns:

A Benchmark with the calculated value, sensitivity, and (optionally) flux spectrum extracted from the Serpent files.

Return type:

Benchmark

kind: str

m: float

plot_sensitivity(zais, perts, ax=None, **kwargs)

Plot the sensitivity profiles for the specified ZAIs and perturbations.

Parameters:

• zais (list of int) – List of ZAIs to include in the plot.

• perts (list of str) – List of perturbations to include in the plot.

• ax (matplotlib.axes.Axes, optional) – Matplotlib Axes object to plot on. If None, a new figure and axes will be created.

• **kwargs – Additional keyword arguments to pass to the plotting function.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

print_summary()

Print a quick summary of a benchmark object.

s: Sensitivity

title: str

to_hdf5(file_path='benchmarks.h5')

Save the benchmark data to an HDF5 file.

Parameters:

file_path (str, optional) –

The path to the HDF5 file where the benchmark data will be saved.

Default is ‘benchmarks.h5’.

class andalus.benchmark.BenchmarkSuite(benchmarks: dict[str, ~andalus.benchmark.Benchmark]=<factory>)

Bases: object

A benchmarksuite is a combined set of benchmark objects.

benchmarks

A dictionary of benchmark objects, indexed by their title.

Type:

dict[str, Benchmark]

benchmarks: dict[str, Benchmark]

property c: Series

Returns a pd.Series of benchmark calculated values in the suite.

Returns:

Series of benchmark calculated values in the suite.

Return type:

pd.Series of float

property cov_m: DataFrame

Returns a pd.DataFrame of benchmark measurement covariance in the suite.

Returns:

DataFrame of benchmark measurement covariance in the suite.

Return type:

pd.DataFrame

property dc: Series

Returns a pd.Series of benchmark calculated uncertainties in the suite.

Returns:

Series of benchmark calculated uncertainties in the suite.

Return type:

pd.Series of float

property dm: Series

Returns a pd.Series of benchmark measurement uncertainties in the suite.

Returns:

Series of benchmark measurement uncertainties in the suite.

Return type:

pd.Series of float

property ds: DataFrame

Returns a pd.DataFrame of sensitivity uncertainties in the suite.

Returns:

DataFrame of sensitivity uncertainties in the suite.

Return type:

pd.DataFrame

filter(filter_fn) → BenchmarkSuite

Filter the BenchmarkSuite based on a filter function and print a summary of the benchmarks removed.

Parameters:

filter_fn (function) –

A function that takes a Benchmark object as input and returns a boolean

indicating whether to include the benchmark in the filtered suite.

Returns:

A new BenchmarkSuite instance containing only the benchmarks for which filter_fn returns True.

Return type:

BenchmarkSuite

classmethod from_hdf5(file_path: str, titles: list | None, kind: str = 'keff')

Retrieve a set of benchmarks from a database.

Parameters:

• file_path (str) – file path where the database is located.

• titles (list, optional) – Titles which have to be extracted from the database, if None return all the benchmarks available in the database, by default None.

Returns:

Returns a BenchmarkSuite object containing the imported Benchmark objects.

Return type:

BenchmarkSuite

Notes

If titles is None, the method will attempt to load all benchmarks of the specified kind from the HDF5 file.

classmethod from_list(benchmarks: list[Benchmark])

Factory method to create a BenchmarkSuite instance from a list of Benchmark objects.

Parameters:

benchmarks (list[Benchmark]) – A list of Benchmark objects to be included in the suite.

Returns:

An instance of BenchmarkSuite containing the provided Benchmark objects.

Return type:

BenchmarkSuite

classmethod from_yaml(path: str)

Factory method to create a BenchmarkSuite instance from a YAML configuration file.

Parameters:

path (str) – The path to the YAML configuration file.

Returns:

An instance of BenchmarkSuite populated with data from the YAML file.

Return type:

BenchmarkSuite

get(title: str) → Benchmark | None

Get a benchmark from the suite.

Parameters:

title (str) – Title of the benchmark to be retrieved.

Returns:

Benchmark object.

Return type:

Benchmark

items()

Return the suite’s benchmarks as (title, Benchmark) pairs.

Returns:

A view of the internal benchmarks dictionary items.

Return type:

dict_items

keys()

Return an iterator over the benchmark titles.

property kinds: Series

Returns a pd.Series of benchmark types in the suite.

Returns:

Series of benchmark types in the suite.

Return type:

pd.Series of str

property m: Series

Returns a pd.Series of benchmark measurements in the suite.

Returns:

Series of benchmark measurements in the suite.

Return type:

pd.Series of float

remove(title: str)

Remove benchmark from the suite.

Parameters:

title (str) – Title of the benchmark to be removed.

property s: DataFrame

Returns a pd.DataFrame of sensitivity objects in the suite.

Returns:

DataFrame of sensitivity objects in the suite.

Return type:

pd.DataFrame

property titles: list

Returns a list of benchmark titles in the suite.

Returns:

List of benchmark titles in the suite.

Return type:

list of str

update_c(new_c: Series) → BenchmarkSuite

Create a new BenchmarkSuite with updated calculated values.

This method is typically used to generate a posterior suite after an assimilation update (e.g., GLLS).

Parameters:

new_c (pd.Series) – A series containing the updated ‘c’ values, indexed by benchmark title.

Returns:

A new instance of the suite containing updated Benchmark objects.

Return type:

BenchmarkSuite

Raises:

KeyError – If a benchmark title in the suite is missing from the index of new_c.

values()

Return an iterator over the benchmark objects.

property zais: list

Returns a list of unique ZAIs in the sensitivity data of the benchmarks in the suite.

Returns:

List of unique ZAIs in the sensitivity data of the benchmarks in the suite.

Return type:

list of int

andalus.cli module

Console script for andalus.

andalus.cli.main() → None

Console script for andalus.

andalus.constants module

Global constants and nuclear data translation mappings for the andalus package.

andalus.constants.get_mt_number(label: str) → int

Safely convert a Serpent reaction string to an integer MT number.

Parameters:

label (str) – The reaction string from Serpent output.

Returns:

The corresponding MT number. Returns 999 if unknown to preserve integer type for HDF5 serialization.

Return type:

int

andalus.covariance module

Module containing the Covariance class, which is used to represent and manage covariance data. Covariances inherit from pandas DataFrames. Covariance objects can be saved to a sparse HDF5 format and reconstructed from it. A covariance suite can be assembled from multiple Covariance objects, creating a block-diagonal matrix.

class andalus.covariance.Covariance(data=None, index: Axes | None = None, columns: Axes | None = None, dtype: Dtype | None = None, copy: bool | None = None)

Bases: DataFrame

Subclass of pd.DataFrame for handling individual nuclide covariance data.

zai

Nuclide identifier (ZAI).

Type:

int

temperature

Temperature at which the covariance was generated.

Type:

float, optional

err

Associated error or tolerance.

Type:

float, optional

correlation() → DataFrame

Calculate the correlation matrix from the covariance matrix.

Returns:

Correlation matrix with values between -1 and 1.

Return type:

pd.DataFrame

classmethod from_errorr(files: dict[str, str], zai: int, mts: list[int] | None = None, temperature: float | None = None, err: float | None = None) → Covariance

Construct a Covariance object from NJOY errorr output files.

Parameters:

• files (dict[str, str]) – Dictionary mapping section names (e.g., ‘errorr33’) to file paths.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

• temperature (float, optional) – Temperature at which the covariance was generated.

• err (float, optional) – Associated error or tolerance.

Returns:

Reconstructed covariance matrix from errorr data.

Return type:

Covariance

classmethod from_hdf5(file_path: str, zai: int, mts: list[int] | None = None) → Covariance

Load a covariance matrix from HDF5 and reconstruct from sparse storage.

Parameters:

• file_path (str) – Path to the HDF5 file.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

Returns:

Reconstructed symmetric covariance matrix.

Return type:

Covariance

classmethod from_store(store: HDFStore, zai: int, mts: list[int] | None = None) → Covariance

Extract and reconstruct a Covariance object from an open HDFStore.

Parameters:

• store (pd.HDFStore) – The open HDF5 store object.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

Returns:

Reconstructed symmetric covariance matrix.

Return type:

Covariance

is_unrealistic_uncertainty(threshold=10)

Check if diagonal elements (variances) exceed a threshold.

property nuclide: str | None

Return a string representation of the isotope based on ZAI.

to_hdf5(file_path: str)

Save the matrix to HDF5 using sparse lower-triangular storage.

Parameters:

file_path (str) – Path to save the HDF5 file.

class andalus.covariance.CovarianceSuite(matrix: DataFrame)

Bases: object

Container for global nuclear data covariance systems.

This class manages the transition from independent nuclide matrices to a fully correlated global system, often used in Least Squares adjustments.

Parameters:

matrix (pd.DataFrame) – The unified global covariance matrix with a 5-level MultiIndex: (ZAI, MF, MT, E_min, E_max).

classmethod from_df(df: DataFrame) → CovarianceSuite

Construct a suite directly from a DataFrame. Useful for loading adjusted/correlated matrices.

Parameters:

df (pd.DataFrame) – The global covariance matrix.

Returns:

A suite wrapping the provided DataFrame.

Return type:

CovarianceSuite

classmethod from_dict(items: dict[int, Covariance]) → CovarianceSuite

Construct a suite from a dictionary of independent Covariance objects.

This creates a block-diagonal matrix where off-diagonal blocks (cross-nuclide correlations) are initialized to zero.

Parameters:

items (Dict[int, Covariance]) – Dictionary mapping ZAI to Covariance objects.

Returns:

A suite containing the assembled block-diagonal matrix.

Return type:

CovarianceSuite

classmethod from_hdf5(file_path: str, zais: list[int] | None = None, mts: list[int] | None = None) → CovarianceSuite

Load a suite from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file.

• zais (Optional[List[int]]) – List of ZAI values to include in the suite.

• mts (Optional[List[int]]) – List of MT values to include in the suite.

Returns:

The loaded suite.

Return type:

CovarianceSuite

classmethod from_yaml(path: str, zais: list[int], mts: list[int] | None = None) → CovarianceSuite

Factory method to create a CovarianceSuite instance from a YAML configuration file.

Parameters:

• path (str) – The path to the YAML configuration file, by default “assimilation_suite.yaml”.

• zais (list[int]) – List of ZAI values to include in the suite.

• mts (list[int]) – List of MT values to include in the suite.

Returns:

An instance of CovarianceSuite populated with data from the YAML file.

Return type:

CovarianceSuite

get_correlation_matrix() → DataFrame

Calculate the correlation matrix from the current covariance matrix.

Returns:

Matrix of correlation coefficients (-1 to 1).

Return type:

pd.DataFrame

get_uncertainties() → Series

Return the standard deviations (sqrt of diagonal) for all bins.

Returns:

Standard deviation values.

Return type:

pd.Series

matrix: DataFrame

plot_uncertainty(zai: int, mt: int, ax=None, **kwargs)

Plot the uncertainty (standard deviation) for a specific ZAI and MT.

Parameters:

• zai (int) – The ZAI of the nuclide to plot.

• mt (int) – The MT number to plot.

• ax (matplotlib.axes.Axes, optional) – An existing matplotlib Axes to plot on. If None, a new figure will be created.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

andalus.sensitivity module

Module containing the Sensitivity class, which is used to represent and manage sensitivity data. Sensitivities inherit from pandas DataFrames, and have some additional methods for plotting and loading from Serpent output.

class andalus.sensitivity.Sensitivity(data=None, *args, **kwargs)

Bases: DataFrame

Data structure for nuclear data sensitivity analysis.

Inherits from pandas.DataFrame and maintains metadata across slicing and transformation operations.

Parameters:

• data (array-like, Iterable, dict, or scalar value) – Contains data to be stored in the DataFrame.

• title (str, optional) – The name of the benchmark or experiment (e.g., ‘HMF001’).

• kind (str, optional) – The response type, by default ‘keff’.

• *args (list) – Additional positional arguments for pd.DataFrame.

• **kwargs (dict) – Additional keyword arguments for pd.DataFrame.

title

The identifier for the sensitivity data.

Type:

str

kind

The type of observable the sensitivity relates to.

Type:

str

classmethod from_hdf5(file_path, title, kind: str = 'keff')

Create a Sensitivity instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the sensitivity data.

• title (str) – Title of the sensitivity data to load.

• kind (str, optional) – Type of sensitivity data (e.g., “keff”). Default is “keff”.

Returns:

Sensitivity object containing the loaded sensitivity data.

Return type:

Sensitivity

classmethod from_serpent(sens0_path: str, title: str, kind: str = 'keff', materiallist=None, zailist=None, pertlist=None)

Returns a sensitivity object from a Serpent sensitivity file.

Parameters:

• sens0_path (str) – Path to the Serpent sensitivity file.

• title (str) – Title for the sensitivity data.

• materiallist (list, optional) – List of materials to include. Default is [‘total’].

• zailist (list, optional) – List of ZAIs to include. Default is None, which includes all ZAIs.

• pertlist (list, optional) – List of perturbations to include. Default is None, which corresponds to all perturbations in the sensitivity file.

Returns:

Sensitivity object containing the sensitivity data.

Return type:

Sensitivity

Raises:

SensitivityError – If there is an error reading the sensitivity file.

property isotopes

Returns a list of human readable isotopes.

Returns:

List of human readable isotopes.

Return type:

list of str

plot_sensitivity(zais, perts, ax=None, **kwargs)

Return a plot of the sensitivity profile normalized by unit lethargy

Parameters:

• zais (list) – List of zais to be included in the plot.

• perts (list) – List of perts to be included in the plot.

• ax (plt.Axes, optional) – Ax for the plot to be displayed. If None, a new figure and axis will be created.

• **kwargs – Additional keyword arguments to be passed to the plotting function.

rename_sensitivity(new_title: str) → Sensitivity

Rename the benchmark columns and update the title metadata.

Parameters:

new_title (str) – The new identifier for the benchmark columns.

Returns:

A new Sensitivity object with updated columns and title metadata.

Return type:

Sensitivity

to_hdf5(file_path)

Save the Sensitivity instance to an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file where the sensitivity data will be saved.

• title (str) – Title of the sensitivity data to save.

• kind (str, optional) – Type of sensitivity data (e.g., “keff”). Default is “keff”.

andalus.utils module

andalus.utils.read_serpent(path)

Read a Serpent file while suppressing a known upstream NumPy deprecation warning.

andalus.utils.sandwich(s1, cov, s2=None)

Perform the sandwich formula to propagate uncertainties using first-order Taylor expansion.

Parameters:

• s1 (pd.DataFrame or pd.Series) – First sensitivity matrix or vector.

• cov (pd.DataFrame) – Covariance matrix.

• s2 (pd.DataFrame or pd.Series, optional) – Second sensitivity matrix or vector.

Returns:

Result of the sandwich formula.

Return type:

pd.DataFrame or pd.Series

andalus.utils.sandwich_binwise(s1, cov, s2=None)

Calculate the variance contribution ZAI/MT/E pairs.

Parameters:

• s1 (pd.Series or pd.DataFrame) – First sensitivity vector. Must have a MultiIndex (ZAI, MT, E_min_eV, E_max_eV).

• cov (pd.DataFrame) – Square covariance matrix with MultiIndex (ZAI, MT, E_min_eV, E_max_eV).

• s2 (pd.Series or pd.DataFrame, optional) – Second sensitivity vector. If None, s2 is assumed to be s1.

Returns:

A Series with a 4-level MultiIndex: (ZAI_1, MT_1, E_min_eV_1, E_max_eV_1, ZAI_2, MT_2, E_min_eV_2, E_max_eV_2) representing the contribution of the correlation between those specific bins.

Return type:

pd.Series

andalus.utils.uncertainty_reactionwise(s1, cov, s2=None)

Calculate the variance contribution for each reaction.

Parameters:

• s1 (pd.Series or pd.DataFrame) – First sensitivity vector. Must have a MultiIndex (ZAI, MT, E_min_eV, E_max_eV).

• cov (pd.DataFrame) – Square covariance matrix with MultiIndex (ZAI, MT, E_min_eV, E_max_eV).

• s2 (pd.Series or pd.DataFrame, optional) – Second sensitivity vector. If None, s2 is assumed to be s1.

Returns:

A Series with a MultiIndex (ZAI_1, MT_1, ZAI_2, MT_2) representing the uncertainty contribution of each reaction.

Return type:

pd.Series

Module contents

Top-level package for ANDALUS.

class andalus.Application(title: str, kind: str, c: float, dc: float, s: Sensitivity, m: float | None = None, dm: float | None = None, flux: FluxSpectrum | None = None)

Bases: object

An application is a calculation without an associated measurement.

title

The unique name or identifier for the application.

Type:

str

kind

The kind of the observable (e.g., “keff”, “void”).

Type:

str

c

The calculated value (Nominal).

Type:

float

dc

The uncertainty of the calculation.

Type:

float

s

The energy-dependent sensitivity profiles.

Type:

Sensitivity

m

The measured value, if available.

Type:

float or None, optional

dm

The measurement uncertainty, if available.

Type:

float or None, optional

flux

The energy-dependent flux spectrum. None when not available.

Type:

FluxSpectrum or None, optional

c: float

dc: float

dm: float | None = None

flux: FluxSpectrum | None = None

classmethod from_hdf5(file_path, title: str, kind: str = 'keff')

Create an Application instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the application data.

• title (str) – Title of the application to load.

• kind (str, optional) – Type of application (e.g., “keff”). Default is “keff”.

Returns:

A new Application instance with the loaded data.

Return type:

Application

classmethod from_serpent(title: str, sens0_path: str, results_path: str, kind: str = 'keff', materials=None, zailist=None, pertlist=None, m: float | None = None, dm: float | None = None, flux_det: tuple[str, str] | None = None)

Create an Application from Serpent output files.

Parameters:

• title (str) – Title of the application.

• sens0_path (str) – Path to the Serpent _sens0.m sensitivity file.

• results_path (str) – Path to the Serpent _res.m results file.

• kind (str, optional) – Kind of observable, by default "keff".

• materials (list of str, optional) – Materials for which the sensitivity is extracted. Defaults to ["total"].

• zailist (list of int, optional) – ZAIs to extract from the sensitivity file. Defaults to all ZAIs present in the file.

• pertlist (list of str, optional) – Perturbations to extract from the sensitivity file. Defaults to the standard set of reactions.

• m (float, optional) – Measured value for the application. Default is None.

• dm (float, optional) – Measurement uncertainty. Default is None.

• flux_det (tuple of (str, str), optional) – A (det_name, det_path) pair identifying the Serpent detector whose tally is used to build a FluxSpectrum. When None (default) no flux spectrum is attached.

Returns:

An Application with the calculated value, sensitivity, and (optionally) flux spectrum extracted from the Serpent files.

Return type:

Application

kind: str

m: float | None = None

plot_sensitivity(zais, perts, ax=None, **kwargs)

Plot the sensitivity profiles for the application.

Parameters:

• zais (list) – List of zais to be included in the plot.

• perts (list) – List of perts to be included in the plot.

• ax (plt.Axes, optional) – Ax for the plot to be displayed. If None, a new figure and axis will be created.

• **kwargs – Additional keyword arguments to be passed to the plotting function.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

print_summary()

Print a quick summary of an application object.

s: Sensitivity

title: str

to_hdf5(file_path='benchmarks.h5')

Save the application data to an HDF5 file.

Parameters:

file_path (str, optional) –

The path to the HDF5 file where the application data will be saved.

Default is ‘benchmarks.h5’.

class andalus.ApplicationSuite(applications: dict[str, ~andalus.application.Application]=<factory>)

Bases: object

A applicationsuite is a combined set of application objects.

applications

A dictionary of application objects, indexed by their title.

Type:

dict[str, Application]

applications: dict[str, Application]

property c: Series

Returns a pd.Series of application calculated values in the suite.

Returns:

Series of application calculated values in the suite.

Return type:

pd.Series of float

property dc: Series

Returns a pd.Series of application calculated uncertainties in the suite.

Returns:

Series of application calculated uncertainties in the suite.

Return type:

pd.Series of float

property dm: Series

Returns a pd.Series of application measured uncertainties in the suite.

Returns:

Series of application measured uncertainties in the suite.

Return type:

pd.Series of float

property ds: DataFrame

Returns a pd.DataFrame of sensitivity uncertainties in the suite.

Returns:

DataFrame of sensitivity uncertainties in the suite.

Return type:

pd.DataFrame

filter(filter_fn) → ApplicationSuite

Filter the ApplicationSuite based on a filter function.

Parameters:

filter_fn (function) –

A function that takes an Application object as input and returns a boolean

indicating whether to include the application in the filtered suite.

classmethod from_hdf5(file_path: str, titles: list, kind: str = 'keff')

Retrieve a set of applications from a database.

Parameters:

• file_path (str) – file path where the database is located.

• titles (list, optional) – Titles which have to be extracted from the database, if None return all the applications available in the database, by default None.

Returns:

Returns a BenchmarkSuite object containing the imported Benchmark objects.

Return type:

BenchmarkSuite

classmethod from_list(applications: list[Application])

Method to create an ApplicationSuite instance from a list of Application objects.

Parameters:

applications (list[Application]) – A list of Application objects to be included in the suite.

Returns:

An instance of ApplicationSuite containing the provided applications.

Return type:

ApplicationSuite

classmethod from_yaml(path: str)

Factory method to create an ApplicationSuite instance from a YAML configuration file.

Parameters:

path (str) – The path to the YAML configuration file.

Returns:

An instance of ApplicationSuite populated with data from the YAML file.

Return type:

ApplicationSuite

get(title: str) → Application | None

Get an application from the suite.

Parameters:

title (str) – Title of the application to be retrieved.

Returns:

Application object.

Return type:

Application

items()

Return the suite’s applications as (title, Application) pairs.

Returns:

A view of the internal application dictionary items, which are of type Application.

Return type:

dict_items

keys()

Return an iterator over the application titles.

property kinds: Series

Returns a pd.Series of application types in the suite.

Returns:

Series of application types in the suite.

Return type:

pd.Series of str

property m: Series

Returns a pd.Series of application measured values in the suite.

Returns:

Series of application measured values in the suite.

Return type:

pd.Series of float

remove(title: str)

Remove application from the suite.

Parameters:

title (str) – Title of the application to be removed.

property s: DataFrame

Returns a pd.DataFrame of sensitivity objects in the suite.

Returns:

DataFrame of sensitivity objects in the suite.

Return type:

pd.DataFrame

property titles: list

Returns a list of application titles in the suite.

Returns:

List of application titles in the suite.

Return type:

list of str

update_c(new_c: Series) → ApplicationSuite

Create a new ApplicationSuite with updated calculated values.

This method is typically used to generate a posterior suite after an assimilation update (e.g., GLLS).

Parameters:

new_c (pd.Series) – A series containing the updated ‘c’ values, indexed by application title.

Returns:

A new instance of the suite containing updated Application objects.

Return type:

ApplicationSuite

Raises:

KeyError – If an applicaiton title in the suite is missing from the index of new_c.

values()

Return an iterator over the application objects.

property zais: list

Returns a list of unique ZAIs in the sensitivity data of the applications in the suite.

Returns:

List of unique ZAIs in the sensitivity data of the applications in the suite.

Return type:

list of int

class andalus.AssimilationSuite(benchmarks: BenchmarkSuite, applications: ApplicationSuite, covariances: CovarianceSuite, xs_adjustment: Series | None = None, prior_c: Series | None = None)

Bases: object

Class to manage a collection of benchmark, application and covariance data for assimilation purposes. This class can be used to assemble a complete dataset for assimilation, and to perform operations on the entire suite.

applications: ApplicationSuite

benchmarks: BenchmarkSuite

property c

Concatenate calculated values from all benchmarks and applications.

This property gathers calculated values from available benchmark and application suites, aligns them by their titles, and fills missing values with zeros to create a unified calculated value vector.

Returns:

A combined Series containing calculated values, aligned by index.

Return type:

pd.Series

Raises:

ValueError – If both benchmarks and applications are None or empty.

chi_squared(nuclear_data: bool = False) → float

Calculate the total chi-squared for the suite.

\[\]

chi^2 = (m - c)^T C^{-1} (m - c)

Parameters:

nuclear_data (bool, optional) – Whether to include the contribution of the nuclear data uncertainty in the chi² calculation, by default False.

ck_matrix() → DataFrame

Generate a ck-similarity matrix for the current assimilation suite.

Returns:

A dataframe containing the similarity coefficients between all benchmarks and applications in the AssimilationSuite.

Return type:

pd.DataFrame

ck_target(target: str) → Series

Calculate the ck-similarity of all sensitivities in the suite with a specified target sensitivity profile.

Parameters:

target (str) – The name of the target sensitivity profile to compare against.

Returns:

A Series containing the ck-similarity values for each sensitivity profile in the suite compared to the target.

Return type:

pd.Series

covariances: CovarianceSuite

property dc

Concatenate calculated value uncertainties from all benchmarks and applications.

This property gathers calculated value uncertainties from available benchmark and application suites, aligns them by their titles, and fills missing values with zeros to create a unified calculated value uncertainty vector.

Returns:

A combined Series containing calculated value uncertainties, aligned by index.

Return type:

pd.Series

Raises:

ValueError – If both benchmarks and applications are None or empty.

property dm

Return experimental uncertainty values from the benchmark and application suites.

Returns:

A Series containing the experimental uncertainty values from the benchmark and application suites.

Return type:

pd.Series

property ds

Concatenate sensitivity uncertainties data from all benchmarks and applications.

This property gathers sensitivity uncertainty vectors from available benchmark and application suites, aligns them by their MultiIndex, and fills missing values with zeros to create a unified sensitivity uncertainty matrix.

Returns:

A combined DataFrame containing sensitivity uncertainties, aligned along the columns (axis=1).

Return type:

pd.DataFrame

Raises:

ValueError – If both benchmarks and applications are None or empty.

e_index_matrix() → DataFrame

Generate an E-index similarity matrix for the assimilation suite.

The E-index measures the physical similarity between two sensitivity profiles without the influence of a covariance matrix:

\[E_{ij} = \frac{S_i^T S_j}{\sqrt{S_i^T S_i \cdot S_j^T S_j}}\]

This is the cosine similarity of the sensitivity vectors.

Returns:

A DataFrame with shape (N, N) containing the E-index values between every pair of benchmarks and applications in the suite. Entries are NaN when either sensitivity vector is all zeros.

Return type:

pd.DataFrame

filter(filter_fn) → AssimilationSuite

Filter the benchmarks available in the assimilation suite based on a provided filter function.

Parameters:

filter_fn (function or Filter) – A function that takes a Benchmark object and returns True if it should be included in the filtered suite.

classmethod from_yaml(path: str = 'assimilation_suite.yaml')

Factory method to create an AssimilationSuite instance from a YAML configuration file.

Parameters:

path (str, optional) – The path to the YAML configuration file, by default “assimilation_suite.yaml”.

Returns:

An instance of AssimilationSuite populated with data from the YAML file.

Return type:

AssimilationSuite

glls(include_sensitivity_uncertainty: bool = False) → AssimilationSuite

Perform a GLLS update [1] on the assimilation suite using the sensitivity profiles and covariance data loaded in the AssimilationSuite. This method updates the calculated response and the covariance matrices.

Returns:

A new AssimilationSuite instance with updated sensitivity profiles.

Return type:

AssimilationSuite

References

[1]

B. L. Broadhead, B. T. Rearden, C. M. Hopper, J. J. Wagschal, and C. V. Parks, “Sensitivity- and Uncertainty-Based Criticality Safety Validation Techniques,” Nuclear Science and Engineering, vol. 146, no. 3, pp. 340–366, Mar. 2004, doi: 10.13182/NSE03-2.

individual_chi_squared(nuclear_data: bool = False) → Series

Calculate individual chi-squared for each benchmark in the suite.

\[\]

chi^2 = frac{(m - c)^2}{sigma_m^2 + sigma_c^2 + s^T C s}

Parameters:

nuclear_data (bool, optional) – Whether to include the contribution of the nuclear data uncertainty in the chi² calculation, by default False.

property is_posterior: bool

Check if the assimilation suite contains posterior data by checking if nd_adjustments is not None.

Returns:

True if the suite contains posterior data, False otherwise.

Return type:

bool

property m

Return experimental values from the benchmark and application suites.

Returns:

A Series containing the experimental values from the benchmark and application suites.

Return type:

pd.Series

prior_c: Series | None = None

property prior_discrepancy: Series

Return the prior discrepancy between calculated and measured responses for the benchmarks.

Returns:

A Series containing the prior discrepancy for each benchmark in the suite.

Return type:

pd.Series

propagate_nuclear_data_uncertainty()

Propagate the nuclear data uncertainty through the sensitivity profiles to calculate the contribution of the nuclear data uncertainty to the overall uncertainty in the calculated values.

Returns:

A Series containing the propagated nuclear data uncertainty for each case in the suite.

Return type:

pd.Series

property s

Concatenate sensitivity data from all benchmarks and applications.

This property gathers sensitivity vectors from available benchmark and application suites, aligns them by their MultiIndex, and fills missing values with zeros to create a unified sensitivity matrix.

Returns:

A combined DataFrame containing sensitivities, aligned along the columns (axis=1).

Return type:

pd.DataFrame

Raises:

ValueError – If both benchmarks and applications are None or empty.

summarize()

Print a summary of the assimilation suite, including the number of benchmarks and applications, the titles of the cases included, and the chi-squared values with and without nuclear data.

property titles

Get a list of all case titles in the assimilation suite, including both benchmarks and applications.

Returns:

A list of strings representing the titles of all cases in the suite.

Return type:

list

to_ace(library: str, reaction_dict=None, verbose: bool = False, temperature: int = 300, create_xsdata: bool = False, parallel: bool = False, max_workers: int | None = None, only_zais_applications: bool = False)

Export the current assimilation suite to an adjusted ACE library format via SANDY.

This method iterates through the unique ZAIs in the cross-section adjustments, retrieves the base ENDF6 files from the specified library, applies the calculated perturbations, and generates ACE files. Optionally, it can append entries to a Serpent-style ‘xsdata’ directory file.

Parameters:

• library (str) – Path to the base ENDF6 library or the name of the library recognized by sandy.

• reaction_dict (dict, optional) – A dictionary mapping ENDF6 MT numbers to reaction types. Default handles standard cross-sections (MF31, 33, 34, 35). Format: {MF: [MT_list]}.

• verbose (bool, default False) – If True, prints detailed progress and SANDY execution logs.

• temperature (int, default 300) – The temperature in Kelvin for the ACE file generation.

• create_xsdata (bool, default False) – If True, appends isotope definitions to ‘adjusted.xsdata’ formatted for the Serpent Monte Carlo code.

• parallel (bool, default False) – If True, process ZAIs concurrently using a thread pool.

• max_workers (int | None, default None) – Maximum number of worker threads used when parallel=True. If None, Python chooses a default.

• only_zais_applications (bool, default False) – If True, only process ZAIs that are present in the application suite,

Raises:

ValueError – If self.xs_adjustment is None, indicating no posterior has been calculated.

Notes

• Currently the method supports perturbations to nubar, cross sections

and prompt fission neutron energy spectrum.

See also

sandy.get_endf6_file

The underlying function for library retrieval.

sandy.Samples

Object used to containerize perturbations.

sandy.Endf6.apply_perturbations

The function that applies perturbations and generates ACE files.

xs_adjustment: Series | None = None

class andalus.Benchmark(title: str, kind: str, m: float, dm: float, c: float, dc: float, s: Sensitivity, flux: FluxSpectrum | None = None)

Bases: object

A benchmark is an application that has an associated measurement.

title

The unique name or identifier for the application.

Type:

str

kind

The kind of the observable (e.g., “keff”, “void”).

Type:

str

m

The measured value (Nominal).

Type:

float

dm

The uncertainty of the measurement.

Type:

float

c

The calculated value (Nominal).

Type:

float

dc

The uncertainty of the calculation.

Type:

float

s

The energy-dependent sensitivity profiles.

Type:

Sensitivity

flux

The energy-dependent flux spectrum. None when not available.

Type:

FluxSpectrum or None, optional

c: float

chi_squared() → float

Calculate the experimental chi-squared value for the benchmark.

Returns:

The experimental chi-squared value calculated as ((m - c) / dm)^2.

Return type:

float

dc: float

dm: float

flux: FluxSpectrum | None = None

classmethod from_hdf5(file_path, title: str, kind: str = 'keff')

Create a Benchmark instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the benchmark data.

• title (str) – Title of the benchmark to load.

• kind (str, optional) – Type of benchmark (e.g., "keff"). Default is "keff".

Returns:

A new Benchmark instance with the loaded data.

Return type:

Benchmark

classmethod from_serpent(title: str, m: float, dm: float, sens0_path: str, results_path: str, kind: str = 'keff', materials=None, zailist=None, pertlist=None, flux_det: tuple[str, str] | None = None)

Create a Benchmark from Serpent output files.

Parameters:

• title (str) – Title of the benchmark.

• m (float) – Measured value.

• dm (float) – Measurement uncertainty.

• sens0_path (str) – Path to the Serpent _sens0.m sensitivity file.

• results_path (str) – Path to the Serpent _res.m results file.

• kind (str, optional) – Kind of observable, by default "keff".

• materials (list of str, optional) – Materials for which the sensitivity is extracted. Defaults to ["total"].

• zailist (list of int, optional) – ZAIs to extract from the sensitivity file. Defaults to all ZAIs present in the file.

• pertlist (list of str, optional) – Perturbations to extract from the sensitivity file. Defaults to the standard set of reactions.

• flux_det (tuple of (str, str), optional) – A (det_name, det_path) pair identifying the Serpent detector whose tally is used to build a FluxSpectrum. When None (default) no flux spectrum is attached.

Returns:

A Benchmark with the calculated value, sensitivity, and (optionally) flux spectrum extracted from the Serpent files.

Return type:

Benchmark

kind: str

m: float

plot_sensitivity(zais, perts, ax=None, **kwargs)

Plot the sensitivity profiles for the specified ZAIs and perturbations.

Parameters:

• zais (list of int) – List of ZAIs to include in the plot.

• perts (list of str) – List of perturbations to include in the plot.

• ax (matplotlib.axes.Axes, optional) – Matplotlib Axes object to plot on. If None, a new figure and axes will be created.

• **kwargs – Additional keyword arguments to pass to the plotting function.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

print_summary()

Print a quick summary of a benchmark object.

s: Sensitivity

title: str

to_hdf5(file_path='benchmarks.h5')

Save the benchmark data to an HDF5 file.

Parameters:

file_path (str, optional) –

The path to the HDF5 file where the benchmark data will be saved.

Default is ‘benchmarks.h5’.

class andalus.BenchmarkSuite(benchmarks: dict[str, ~andalus.benchmark.Benchmark]=<factory>)

Bases: object

A benchmarksuite is a combined set of benchmark objects.

benchmarks

A dictionary of benchmark objects, indexed by their title.

Type:

dict[str, Benchmark]

benchmarks: dict[str, Benchmark]

property c: Series

Returns a pd.Series of benchmark calculated values in the suite.

Returns:

Series of benchmark calculated values in the suite.

Return type:

pd.Series of float

property cov_m: DataFrame

Returns a pd.DataFrame of benchmark measurement covariance in the suite.

Returns:

DataFrame of benchmark measurement covariance in the suite.

Return type:

pd.DataFrame

property dc: Series

Returns a pd.Series of benchmark calculated uncertainties in the suite.

Returns:

Series of benchmark calculated uncertainties in the suite.

Return type:

pd.Series of float

property dm: Series

Returns a pd.Series of benchmark measurement uncertainties in the suite.

Returns:

Series of benchmark measurement uncertainties in the suite.

Return type:

pd.Series of float

property ds: DataFrame

Returns a pd.DataFrame of sensitivity uncertainties in the suite.

Returns:

DataFrame of sensitivity uncertainties in the suite.

Return type:

pd.DataFrame

filter(filter_fn) → BenchmarkSuite

Filter the BenchmarkSuite based on a filter function and print a summary of the benchmarks removed.

Parameters:

filter_fn (function) –

A function that takes a Benchmark object as input and returns a boolean

indicating whether to include the benchmark in the filtered suite.

Returns:

A new BenchmarkSuite instance containing only the benchmarks for which filter_fn returns True.

Return type:

BenchmarkSuite

classmethod from_hdf5(file_path: str, titles: list | None, kind: str = 'keff')

Retrieve a set of benchmarks from a database.

Parameters:

• file_path (str) – file path where the database is located.

• titles (list, optional) – Titles which have to be extracted from the database, if None return all the benchmarks available in the database, by default None.

Returns:

Returns a BenchmarkSuite object containing the imported Benchmark objects.

Return type:

BenchmarkSuite

Notes

If titles is None, the method will attempt to load all benchmarks of the specified kind from the HDF5 file.

classmethod from_list(benchmarks: list[Benchmark])

Factory method to create a BenchmarkSuite instance from a list of Benchmark objects.

Parameters:

benchmarks (list[Benchmark]) – A list of Benchmark objects to be included in the suite.

Returns:

An instance of BenchmarkSuite containing the provided Benchmark objects.

Return type:

BenchmarkSuite

classmethod from_yaml(path: str)

Factory method to create a BenchmarkSuite instance from a YAML configuration file.

Parameters:

path (str) – The path to the YAML configuration file.

Returns:

An instance of BenchmarkSuite populated with data from the YAML file.

Return type:

BenchmarkSuite

get(title: str) → Benchmark | None

Get a benchmark from the suite.

Parameters:

title (str) – Title of the benchmark to be retrieved.

Returns:

Benchmark object.

Return type:

Benchmark

items()

Return the suite’s benchmarks as (title, Benchmark) pairs.

Returns:

A view of the internal benchmarks dictionary items.

Return type:

dict_items

keys()

Return an iterator over the benchmark titles.

property kinds: Series

Returns a pd.Series of benchmark types in the suite.

Returns:

Series of benchmark types in the suite.

Return type:

pd.Series of str

property m: Series

Returns a pd.Series of benchmark measurements in the suite.

Returns:

Series of benchmark measurements in the suite.

Return type:

pd.Series of float

remove(title: str)

Remove benchmark from the suite.

Parameters:

title (str) – Title of the benchmark to be removed.

property s: DataFrame

Returns a pd.DataFrame of sensitivity objects in the suite.

Returns:

DataFrame of sensitivity objects in the suite.

Return type:

pd.DataFrame

property titles: list

Returns a list of benchmark titles in the suite.

Returns:

List of benchmark titles in the suite.

Return type:

list of str

update_c(new_c: Series) → BenchmarkSuite

Create a new BenchmarkSuite with updated calculated values.

This method is typically used to generate a posterior suite after an assimilation update (e.g., GLLS).

Parameters:

new_c (pd.Series) – A series containing the updated ‘c’ values, indexed by benchmark title.

Returns:

A new instance of the suite containing updated Benchmark objects.

Return type:

BenchmarkSuite

Raises:

KeyError – If a benchmark title in the suite is missing from the index of new_c.

values()

Return an iterator over the benchmark objects.

property zais: list

Returns a list of unique ZAIs in the sensitivity data of the benchmarks in the suite.

Returns:

List of unique ZAIs in the sensitivity data of the benchmarks in the suite.

Return type:

list of int

class andalus.Chi2Filter(threshold: float)

Bases: Filter

Filter based on the standard experimental chi-squared criterion.

class andalus.Chi2NuclearDataFilter(threshold: float, covariance_matrix: DataFrame)

Bases: Filter

Filter an benchmark based on the chi2 value calculated including the nuclear data covariance matrix.

class andalus.Covariance(data=None, index: Axes | None = None, columns: Axes | None = None, dtype: Dtype | None = None, copy: bool | None = None)

Bases: DataFrame

Subclass of pd.DataFrame for handling individual nuclide covariance data.

zai

Nuclide identifier (ZAI).

Type:

int

temperature

Temperature at which the covariance was generated.

Type:

float, optional

err

Associated error or tolerance.

Type:

float, optional

correlation() → DataFrame

Calculate the correlation matrix from the covariance matrix.

Returns:

Correlation matrix with values between -1 and 1.

Return type:

pd.DataFrame

classmethod from_errorr(files: dict[str, str], zai: int, mts: list[int] | None = None, temperature: float | None = None, err: float | None = None) → Covariance

Construct a Covariance object from NJOY errorr output files.

Parameters:

• files (dict[str, str]) – Dictionary mapping section names (e.g., ‘errorr33’) to file paths.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

• temperature (float, optional) – Temperature at which the covariance was generated.

• err (float, optional) – Associated error or tolerance.

Returns:

Reconstructed covariance matrix from errorr data.

Return type:

Covariance

classmethod from_hdf5(file_path: str, zai: int, mts: list[int] | None = None) → Covariance

Load a covariance matrix from HDF5 and reconstruct from sparse storage.

Parameters:

• file_path (str) – Path to the HDF5 file.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

Returns:

Reconstructed symmetric covariance matrix.

Return type:

Covariance

classmethod from_store(store: HDFStore, zai: int, mts: list[int] | None = None) → Covariance

Extract and reconstruct a Covariance object from an open HDFStore.

Parameters:

• store (pd.HDFStore) – The open HDF5 store object.

• zai (int) – Nuclide identifier (ZAI).

• mts (list of int, optional) – Filter for specific MT numbers.

Returns:

Reconstructed symmetric covariance matrix.

Return type:

Covariance

is_unrealistic_uncertainty(threshold=10)

Check if diagonal elements (variances) exceed a threshold.

property nuclide: str | None

Return a string representation of the isotope based on ZAI.

to_hdf5(file_path: str)

Save the matrix to HDF5 using sparse lower-triangular storage.

Parameters:

file_path (str) – Path to save the HDF5 file.

class andalus.CovarianceSuite(matrix: DataFrame)

Bases: object

Container for global nuclear data covariance systems.

This class manages the transition from independent nuclide matrices to a fully correlated global system, often used in Least Squares adjustments.

Parameters:

matrix (pd.DataFrame) – The unified global covariance matrix with a 5-level MultiIndex: (ZAI, MF, MT, E_min, E_max).

classmethod from_df(df: DataFrame) → CovarianceSuite

Construct a suite directly from a DataFrame. Useful for loading adjusted/correlated matrices.

Parameters:

df (pd.DataFrame) – The global covariance matrix.

Returns:

A suite wrapping the provided DataFrame.

Return type:

CovarianceSuite

classmethod from_dict(items: dict[int, Covariance]) → CovarianceSuite

Construct a suite from a dictionary of independent Covariance objects.

This creates a block-diagonal matrix where off-diagonal blocks (cross-nuclide correlations) are initialized to zero.

Parameters:

items (Dict[int, Covariance]) – Dictionary mapping ZAI to Covariance objects.

Returns:

A suite containing the assembled block-diagonal matrix.

Return type:

CovarianceSuite

classmethod from_hdf5(file_path: str, zais: list[int] | None = None, mts: list[int] | None = None) → CovarianceSuite

Load a suite from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file.

• zais (Optional[List[int]]) – List of ZAI values to include in the suite.

• mts (Optional[List[int]]) – List of MT values to include in the suite.

Returns:

The loaded suite.

Return type:

CovarianceSuite

classmethod from_yaml(path: str, zais: list[int], mts: list[int] | None = None) → CovarianceSuite

Factory method to create a CovarianceSuite instance from a YAML configuration file.

Parameters:

• path (str) – The path to the YAML configuration file, by default “assimilation_suite.yaml”.

• zais (list[int]) – List of ZAI values to include in the suite.

• mts (list[int]) – List of MT values to include in the suite.

Returns:

An instance of CovarianceSuite populated with data from the YAML file.

Return type:

CovarianceSuite

get_correlation_matrix() → DataFrame

Calculate the correlation matrix from the current covariance matrix.

Returns:

Matrix of correlation coefficients (-1 to 1).

Return type:

pd.DataFrame

get_uncertainties() → Series

Return the standard deviations (sqrt of diagonal) for all bins.

Returns:

Standard deviation values.

Return type:

pd.Series

matrix: DataFrame

plot_uncertainty(zai: int, mt: int, ax=None, **kwargs)

Plot the uncertainty (standard deviation) for a specific ZAI and MT.

Parameters:

• zai (int) – The ZAI of the nuclide to plot.

• mt (int) – The MT number to plot.

• ax (matplotlib.axes.Axes, optional) – An existing matplotlib Axes to plot on. If None, a new figure will be created.

Returns:

The Axes object containing the plot.

Return type:

matplotlib.axes.Axes

class andalus.FluxSpectrum(data=None, *args, **kwargs)

Bases: DataFrame

Energy-dependent flux spectrum.

Inherits from pandas.DataFrame with a 2-level MultiIndex (E_min_eV, E_max_eV) and columns flux and flux_std.

Parameters:

• data (array-like, Iterable, dict, or scalar value) – Contains data to be stored in the DataFrame.

• title (str, optional) – The name of the benchmark or experiment (e.g., 'HMF001').

• *args (list) – Additional positional arguments forwarded to pd.DataFrame.

• **kwargs (dict) – Additional keyword arguments forwarded to pd.DataFrame.

title

The identifier for the flux spectrum data.

Type:

str

property ealf: float

Energy of Average Lethargy causing Fission (EALF) in eV.

Computed as the flux-weighted geometric mean energy:

\[\text{EALF} = \exp\!\left( \frac{\sum_i \phi_i \ln \bar{E}_i}{\sum_i \phi_i} \right)\]

where \(\bar{E}_i = \sqrt{E_{\min,i} \cdot E_{\max,i}}\) is the geometric mean energy of bin i.

Returns:

The EALF in electronvolts (eV).

Return type:

float

Raises:

ValueError – If the total flux is zero.

classmethod from_hdf5(file_path: str, title: str, kind: str = 'keff') → FluxSpectrum

Create a FluxSpectrum from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file.

• title (str) – Title of the case to load.

• kind (str, optional) – Observable kind used as the top-level HDF5 group (e.g., "keff"). Default is "keff".

Returns:

A FluxSpectrum loaded from the HDF5 file.

Return type:

FluxSpectrum

classmethod from_serpent(det_path: str, det_name: str, title: str | None = None) → FluxSpectrum

Create a FluxSpectrum from a Serpent detector output file.

Parameters:

• det_path (str) – Path to the Serpent detector output file (e.g., *_det0.m).

• det_name (str) – Name of the detector to read from the file.

• title (str, optional) – Title for the returned object. Defaults to det_name.

Returns:

A FluxSpectrum populated with the tally values and uncertainties from the detector.

Return type:

FluxSpectrum

property mean_energy: float

Flux-weighted arithmetic mean energy in eV.

\[\langle E \rangle = \frac{\sum_i \phi_i \bar{E}_i}{\sum_i \phi_i}\]

where \(\bar{E}_i = \sqrt{E_{\min,i} \cdot E_{\max,i}}\).

Returns:

The flux-weighted mean energy in electronvolts (eV).

Return type:

float

Raises:

ValueError – If the total flux is zero.

plot_spectrum(ax=None, normalize: bool = True, **kwargs)

Plot the flux spectrum per unit lethargy.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axes to plot on. A new figure and axes are created when None.

• normalize (bool, optional) – When True (default) the flux is normalized so that the sum over all bins equals 1 before dividing by the lethargy width.

• **kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.step.

Returns:

The axes containing the plot.

Return type:

matplotlib.axes.Axes

to_hdf5(file_path: str, title: str = '', kind: str = 'keff') → None

Save the FluxSpectrum to an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file.

• title (str, optional) – Title of the case to save.

• kind (str, optional) – Observable kind used as the top-level HDF5 group (e.g., "keff"). Default is "keff".

class andalus.Sensitivity(data=None, *args, **kwargs)

Bases: DataFrame

Data structure for nuclear data sensitivity analysis.

Inherits from pandas.DataFrame and maintains metadata across slicing and transformation operations.

Parameters:

• data (array-like, Iterable, dict, or scalar value) – Contains data to be stored in the DataFrame.

• title (str, optional) – The name of the benchmark or experiment (e.g., ‘HMF001’).

• kind (str, optional) – The response type, by default ‘keff’.

• *args (list) – Additional positional arguments for pd.DataFrame.

• **kwargs (dict) – Additional keyword arguments for pd.DataFrame.

title

The identifier for the sensitivity data.

Type:

str

kind

The type of observable the sensitivity relates to.

Type:

str

classmethod from_hdf5(file_path, title, kind: str = 'keff')

Create a Sensitivity instance from an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file containing the sensitivity data.

• title (str) – Title of the sensitivity data to load.

• kind (str, optional) – Type of sensitivity data (e.g., “keff”). Default is “keff”.

Returns:

Sensitivity object containing the loaded sensitivity data.

Return type:

Sensitivity

classmethod from_serpent(sens0_path: str, title: str, kind: str = 'keff', materiallist=None, zailist=None, pertlist=None)

Returns a sensitivity object from a Serpent sensitivity file.

Parameters:

• sens0_path (str) – Path to the Serpent sensitivity file.

• title (str) – Title for the sensitivity data.

• materiallist (list, optional) – List of materials to include. Default is [‘total’].

• zailist (list, optional) – List of ZAIs to include. Default is None, which includes all ZAIs.

• pertlist (list, optional) – List of perturbations to include. Default is None, which corresponds to all perturbations in the sensitivity file.

Returns:

Sensitivity object containing the sensitivity data.

Return type:

Sensitivity

Raises:

SensitivityError – If there is an error reading the sensitivity file.

property isotopes

Returns a list of human readable isotopes.

Returns:

List of human readable isotopes.

Return type:

list of str

plot_sensitivity(zais, perts, ax=None, **kwargs)

Return a plot of the sensitivity profile normalized by unit lethargy

Parameters:

• zais (list) – List of zais to be included in the plot.

• perts (list) – List of perts to be included in the plot.

• ax (plt.Axes, optional) – Ax for the plot to be displayed. If None, a new figure and axis will be created.

• **kwargs – Additional keyword arguments to be passed to the plotting function.

rename_sensitivity(new_title: str) → Sensitivity

Rename the benchmark columns and update the title metadata.

Parameters:

new_title (str) – The new identifier for the benchmark columns.

Returns:

A new Sensitivity object with updated columns and title metadata.

Return type:

Sensitivity

to_hdf5(file_path)

Save the Sensitivity instance to an HDF5 file.

Parameters:

• file_path (str) – Path to the HDF5 file where the sensitivity data will be saved.

• title (str) – Title of the sensitivity data to save.

• kind (str, optional) – Type of sensitivity data (e.g., “keff”). Default is “keff”.

andalus.sandwich(s1, cov, s2=None)

Perform the sandwich formula to propagate uncertainties using first-order Taylor expansion.

Parameters:

• s1 (pd.DataFrame or pd.Series) – First sensitivity matrix or vector.

• cov (pd.DataFrame) – Covariance matrix.

• s2 (pd.DataFrame or pd.Series, optional) – Second sensitivity matrix or vector.

Returns:

Result of the sandwich formula.

Return type:

pd.DataFrame or pd.Series