Private API Documentation

NOTE: This is the private API documentation for the tsunami_ip_utils package. This documentation is intended for developers who are working on the Tsunami IP Utils package itself. If you are a user of the tsunami_ip_utils package, you should refer to the Public API Documentation instead.

Subpackages

Submodules

tsunami_ip_utils._error module

tsunami_ip_utils._error._unit_vector_uncertainty_propagation(vector)[source]

Performs error propagation for the components of a vector \(\boldsymbol{v}\) that is normalized to a unit vector via \(\hat{\boldsymbol{v}} = \frac{\boldsymbol{v}}{\lVert\boldsymbol{v}\rVert}\). To calculate the uncertainty of \(\hat{\boldsymbol{v}}\equiv \boldsymbol{u}\), recall from linear error propagation theory (see this equation)

\[\sigma_{u_i} = \sqrt{ \sum_j \left( \frac{\partial u_i}{\partial v_j} \sigma_{v_j} \right)^2 }\]

since

\[u_i = \frac{v_i}{\sqrt{\sum_j v_j^2}}\]

we have for \(i=j\):

\[\begin{split}\frac{\partial u_i}{\partial v_j} &= \frac{1}{\sqrt{\sum_j v_j^2}} - \frac{1}{2}\frac{v_i\cdot 2v_i}{\left(\sum_j v_j^2\right)^{\frac{3}{2}}}\\ &=\frac{1}{\lVert \boldsymbol{v}\rVert} - \frac{v_i^2}{\lVert \boldsymbol{v}\rVert^3}\\ &=\frac{\lVert \boldsymbol{v}\rVert^2 - v_i^2}{\lVert \boldsymbol{v}\rVert^3}\end{split}\]

For \(i\neq j\):

\[\frac{\partial u_i}{\partial v_j} = -\frac{v_iv_j}{\lVert\boldsymbol{v}\rVert^3}\]

Examples

>>> _unit_vector_uncertainty_propagation(unumpy.uarray([1, 2, 3], [0.1, 0.2, 0.3]))
array([0.03113499, 0.05150788, 0.03711537])

>>> _unit_vector_uncertainty_propagation(unumpy.uarray([0, 0, 0], [0.1, 0.2, 0.3]))
array([0., 0., 0.])

>>> _unit_vector_uncertainty_propagation(unumpy.uarray([0, 0, 0], [0.0, 0.0, 0.0]))
array([0., 0., 0.])
Parameters:

vector (uarray) – The vector \(\boldsymbol{v}\) (with uncertainties) whose normalization the error propagation is calculated for.

Return type:

ndarray

Returns:

Uncertainties of the unit vector components.

tsunami_ip_utils._error._dot_product_uncertainty_propagation(vect1, vect2)[source]

Calculates the uncertainty in the dot product of two vectors with uncertainties

Parameters:

  • vect1 (uarray) – First vector in dot product.

  • vect2 (uarray) – Second vector in dot product.

Return type:

float

Returns:

Uncertainty in the dot product of the two vectors.

tsunami_ip_utils.comparisons module

Tools for generating comparisons between TSUNAMI-IP calculated integral parameters (e.g. \(c_k\), \(E\)) and calculated values using correlation methods with either cross section sampling or uncertainty contributions.

tsunami_ip_utils.comparisons._update_annotation(fig, integral_index, index_name)[source]

Update the annotation on the plot to include the TSUNAMI-IP c_k value and the percent difference from the Pearson correlation coefficient. If the percent difference is greater than 5%, the annotation will be colored red.

Parameters:

  • fig (EnhancedPlotlyFigure) – The plotly figure object.

  • integral_index (float) – The TSUNAMI-IP integral_index value.

  • index_name (str) – The name of the integral index.

Return type:

Tuple[EnhancedPlotlyFigure, float, float]

Returns:

  • fig

    The plotly figure object with the updated annotation.

  • calculated_value

    The calculated value of the integral index.

  • percent_difference

    The percent difference between the TSUNAMI-IP integral_index value and the Pearson correlation coefficient.

tsunami_ip_utils.comparisons._process_pair(args)[source]

tsunami_ip_utils.config module

A package level configuration module.

tsunami_ip_utils.integral_indices module

tsunami_ip_utils.integral_indices._calculate_E_from_sensitivity_vecs(application_vector, experiment_vector, application_filename=None, experiment_filename=None, uncertainties='automatic', experiment_norm=None, application_norm=None)[source]

Calculates the integral index: E given the sensitivity vectors for an application and an experiment. NOTE: the application and experiment filenames are used to break the correlation between the application and experiment vectors (that should not exist). This is because the vectors are only correlated if the application and experiment are the same.

Parameters:

  • application_vector (uarray) – Sensitivity vector for the application.

  • experiment_vector (uarray) – Sensitivity vector for the experiment.

  • application_filename (Path) – Filename of the application sdf file (only needed for automatic uncertianty propagation).

  • experiment_filename (Path) – Filename of the experiment sdf file (only needed for automatic uncertianty propagation).

  • uncertainties (str) – Type of error propagation to use. Default is ‘automatic’ which uses the uncertainties package. If set to ‘manual’, then manual error propagation is used which is generally faster

  • experiment_norm (Variable) – Norm of the experiment vector. If not provided, it is calculated. This is mainly used for calculating E contributions, where the denominator is not actually the norm of the application and experiment vectors.

  • application_norm (Variable) – Norm of the application vector. If not provided, it is calculated. This is mainly used for calculating E contributions, where the denominator is not actually the norm of the application and experiment vectors.

Return type:

Variable

Returns:

Similarity parameter between the application and the experiment

tsunami_ip_utils.integral_indices._create_sensitivity_vector(sdfs)[source]

Creates a senstivity vector from all of the sensitivity profiles from a specific application or experiment by concatenating them together.

Examples

>>> sdfs = [ unumpy.uarray( [1, 2, 3], [0.1, 0.2, 0.3] ), unumpy.uarray( [4, 5, 6], [0.4, 0.5, 0.6] ) ]
>>> _create_sensitivity_vector(sdfs)
array([1.0+/-0.1, 2.0+/-0.2, 3.0+/-0.3, 4.0+/-0.4, 5.0+/-0.5, 6.0+/-0.6],
      dtype=object)
Parameters:

consideration. (List of sensitivity profiles for each nuclide-reaction pair in)

Return type:

uarray

Returns:

Sensitivities from all of the sensitivity profiles combined into a single vector of length sum( [ len(sdf_profile) for sdf_profile in sdfs ] )

tsunami_ip_utils.integral_indices._get_reaction_wise_E_contributions(application, experiment, isotope, all_reactions, application_norm, experiment_norm)[source]

Calculate contributions to the similarity parameter E for each reaction type for a given isotope.

Parameters:

  • application (dict) – Dictionary of application sensitivity profiles.

  • experiment (dict) – Dictionary of experiment sensitivity profiles.

  • isotope (str) – Isotope to consider.

  • all_reactions (List[str]) – List of all possible reaction types.

  • application_norm (Variable) – Norm of the application sensitivity vector.

  • experiment_norm (Variable) – Norm of the experiment sensitivity vector.

Return type:

List[dict]

Returns:

List of dictionaries containing the contribution to the similarity parameter E for each reaction type.

tsunami_ip_utils.integral_indices._add_missing_reactions_and_nuclides(application, experiment, all_isotopes, mode='sdfs')[source]

Add missing reactions and nuclides to the application and experiment dictionaries with an sdf profile of all zeros. The set of all isotopes NOTE: since dictionaries are passed by reference, this function does not return anything, but modifies the application and experiment dictionaries in place.

Parameters:

  • application (dict) – Dictionary of application sensitivity profiles.

  • experiment (dict) – Dictionary of experiment sensitivity profiles.

  • all_isotopes (List[str]) – List of all isotopes in the application and experiment dictionaries.

  • mode (str) – The mode to use for adding missing reactions and nuclides. Default is 'sdfs' which adds sdf profiles to missing reactions and nuclides. If set to 'contribution', then the contributions to the similarity parameter E are set to zero for missing nuclides and reactions.

Return type:

Set[str]

Returns:

Set of all isotopes in the application and experiment dictionaries.

tsunami_ip_utils.integral_indices._get_nuclide_and_reaction_wise_E_contributions(application, experiment)[source]

Calculate the contributions to the similarity parameter E for each nuclide and for each reaction type for a given application and experiment.

Parameters:
Return type:

Tuple[List[dict], List[dict]]

Returns:

  • nuclide_wise_contributions

    List of dictionaries containing the contribution to the similarity parameter E. for each nuclide

  • nuclide_reaction_wise_contributions

    List of dictionaries containing the contribution to the similarity.

tsunami_ip_utils.perturbations module

This module is used for generating cross section perturbations and combining them with the sensitivity profiles for a given application experiment pair to generate a similarity scatter plot

tsunami_ip_utils.perturbations._generate_and_read_perturbed_library(base_library, perturbation_factors, sample_number, all_nuclide_reactions)[source]

Generates and reads perturbed multigroup cross section libraries.

Parameters:

  • base_library (Union[str, Path]) – Path to the base cross section library.

  • perturbation_factors (Union[str, Path]) – Path to the perturbation factors directory (corresponding to the base library).

  • sample_number (int) – The sample number to use for generating the perturbed library. Must be from 1 - NUM_SAMPLES, where NUM_SAMPLES = 1000 is the number of perturbation factor samples provided in the user’s current version of SCALE. (0 \(\leq\) sample_number \(\leq\) 1000)

  • all_nuclide_reactions (dict) – A dictionary containing the nuclide reactions that are read from the perturbed library.

Return type:

dict

Returns:

A dictionary containing the perturbed cross section libraries for each nuclide reaction.

tsunami_ip_utils.perturbations._cache_perturbed_library(args)[source]

Caches a single perturbed cross section library.

Parameters:

args (Tuple[int, Path, Path, int, Dict[str, List[str]], Path]) –

A tuple containing all necessary components to perform the caching of a perturbed library.

  • i (int):

    The sample number to use for generating the perturbed library.

  • base_library (str | Path):

    Path to the base cross section library.

  • perturbation_factors (str | Path):

    Path to the cross section perturbation factors (used to generate the perturbed libraries).

  • sample_number (int):

    The sample number to use for generating the perturbed library. Must be from 1 - NUM_SAMPLES, where NUM_SAMPLES is the number of perturbation factor samples provided in the user’s current version of SCALE. (0 \(\leq\) sample_number \(\leq\) NUM_SAMPLES)

  • available_nuclide_reactions (Dict[str, List[str]]):

    A dictionary containing the nuclide reactions that are read from the perturbed library.

Return type:

float

Returns:

The time taken to cache the perturbed library.

tsunami_ip_utils.readers module

class tsunami_ip_utils.readers.SdfReader(filename)[source]

Bases: object

A class for reading TSUNAMI-B Sentitivity Data Files (SDFs, i.e. .sdf files produced by TSUNAMI-3D monte carlo transport simulations).

The format for TSUNAMI-B SDF files is given here.

Notes

The SDF reader currently does not support TSUNAMI-A formatted SDF files (produced by deterministic transport simulations).

_read_sdf(filename)[source]

Reads the SDF file and returns a dictionary of nuclide-reaction pairs and energy-dependent sensitivities (with uncertainties)

Parameters:

Filename – Path to the sdf file.

Return type:

Tuple[ndarray, List[dict]]

Returns:

  • energy_boundaries – Energy boundaries for the energy groups.

  • sdf_data – List of dictionaries containing the sensitivity profiles and other derived/descriptive data. The dictionary keys are given by SDF_DATA_NAMES = ['isotope', 'reaction_type', 'zaid', 'reaction_mt', 'zone_number', 'zone_volume', 'energy_integrated_sensitivity', 'abs_sum_groupwise_sensitivities', 'sum_opposite_sign_groupwise_sensitivities', 'sensitivities', 'uncertainties'].

class tsunami_ip_utils.readers.RegionIntegratedSdfReader(filename)[source]

Bases: SdfReader

Reads region integrated TSUNAMI-B sensitivity data files produced by TSUNAMI-3D. Useful when the spatial dependence of sensitivty is not important.

_read_sdf(filename)

Reads the SDF file and returns a dictionary of nuclide-reaction pairs and energy-dependent sensitivities (with uncertainties)

Parameters:

Filename – Path to the sdf file.

Return type:

Tuple[ndarray, List[dict]]

Returns:

  • energy_boundaries – Energy boundaries for the energy groups.

  • sdf_data – List of dictionaries containing the sensitivity profiles and other derived/descriptive data. The dictionary keys are given by SDF_DATA_NAMES = ['isotope', 'reaction_type', 'zaid', 'reaction_mt', 'zone_number', 'zone_volume', 'energy_integrated_sensitivity', 'abs_sum_groupwise_sensitivities', 'sum_opposite_sign_groupwise_sensitivities', 'sensitivities', 'uncertainties'].

tsunami_ip_utils.readers._read_ck_contributions(filename)[source]

tsunami_ip_utils.utils module

tsunami_ip_utils.utils._isotope_reaction_list_to_nested_dict(isotope_reaction_list, field_of_interest)[source]

Converts a list of dictionaries containing isotope-reaction pairs (and some other key that represents a value of interest, e.g. an sdf profile or a contribution) to a nested dictionary

Parameters:

  • isotope_reaction_list (-)

  • field_of_interest (-)

Returns:

- nested_dict

Return type:

dict, nested dictionary containing the isotope-reaction pairs and the value of interest

tsunami_ip_utils.utils._filter_redundant_reactions(data_dict, redundant_reactions=['chi', 'capture', 'nubar', 'total'])[source]

Filters out redundant reactions from a nested isotope-reaction dictionary

Parameters:

  • data_dict (-)

  • redundant_reactions (-)

tsunami_ip_utils.utils._filter_by_nuclie_reaction_dict(data_dict, nuclide_reactions)[source]

Filters out isotopes that are not in the nuclide_reactions dictionary

Parameters:

  • data_dict (-)

  • nuclide_reactions (-)

tsunami_ip_utils.utils._parse_ufloats(array_of_strings)[source]

Parses a 2D array of strings into a 2D array of ufloats, assuming zero uncertainty if ‘+/-’ is not found.

tsunami_ip_utils.utils._convert_paths(func)[source]

Decorator to ensure that any list argument passed to the decorated function, which contains strings, has those strings converted to pathlib.Path objects.

Return type:

Callable

tsunami_ip_utils.utils._run_and_read_TSUNAMI_IP(application_filenames, experiment_filenames, coverx_library)[source]

Runs TSUNAMI-IP and reads the output file using the tsunami_ip_utils.readers.read_integral_indices() function.

Parameters:

  • application_filenames (Union[List[str], List[Path]]) – List of paths to the application SDF files.

  • experiment_filenames (Union[List[str], List[Path]]) – List of paths to the experiment SDF files.

  • coverx – The coverx library to use for TSUNAMI-IP.

Returns:

Integral matrices for each integral index type. The shape of the matrices are (num_applications, num_experiments). Keys are 'c_k', 'E_total', 'E_fission', 'E_capture', and 'E_scatter'.

tsunami_ip_utils.xs module

This module contains the functions necessary for processing the binary SCALE multigroup cross section libraries (using the AMPX tools: charmin and tabasco) into python friendly dictionaries of numpy arrays.

tsunami_ip_utils.xs._parse_nuclide_reaction(filename, energy_boundaries=False)[source]

Reads a multigroup cross section .txt file produced by the extractor function and returns the energy-dependent cross sections as a numpy array.

Parameters:

  • filename (Union[str, Path]) – The filename of the cross section file

  • energy_boundaries (bool) – If True, the energies at which the cross sections are defined are returned as well

Return type:

Union[ndarray, Tuple[ndarray, ndarray]]

Returns:

  • If energy_boundaries is False, a numpy array of cross sections

  • If energy_boundaries is True, a numpy array of cross sections and a numpy array of energy boundaries

tsunami_ip_utils.xs._parse_reactions_from_nuclide(filename, **kwargs)[source]

Reads a set of reactions (given by the list of reaction mt’s) from a dump of all reactions for a single nuclide from a SCALE library. Note this function requires that the dump included headers

Parameters:

  • filename (Union[str, Path]) – The filename of the dump file.

  • **kwargs (dict) –

    Additional keyword arguments:

    • reaction_mts (List[str])

      The list of reaction MTs to read (required kwarg).

    • energy_boundaries (bool)

      If True, the energies at which the cross sections are defined are returned as well (optional kwarg).

Return type:

Dict[str, ndarray]

Returns:

A dictionary containing the cross sections for each reaction MT

tsunami_ip_utils.xs._parse_from_total_library(filename, **kwargs)[source]

Parse selected nuclide-reactions from an entire cross section library dump.

Parameters:

  • filename (Union[str, Path]) – Path to the file containing the library dump.

  • **kwargs (dict) –

    Additional keyword arguments:

    • nuclide_reaction_dict (dict)

      A dictionary mapping nuclides to a list of reaction MTs to read (required kwarg).

    • return_available_nuclide_reactions (bool)

      If True, the available nuclide reactions (i.e. all of the nuclide reactions for which data exists in the given multigroup librari) are returned as well (optional kwarg).

    • energy_boundaries (bool)

      If True, the energies at which the cross sections are defined are returned as well (optional kwarg).

Return type:

Union[Dict[str, ndarray], Tuple[Dict[str, ndarray], Dict[str, list]]]

Returns:

  • If return_available_nuclide_reactions is False, a doubly nested dictionary containing the cross sections for each nuclide-reaction pair. Keyed first by nuclide, then by reaction.

  • If return_available_nuclide_reactions is True, a tuple containing the above dictionary and a dictionary containing all available nuclide reactions.

tsunami_ip_utils.xs._read_nuclide_reaction_from_multigroup_library(multigroup_library_path, nuclide_zaid, reaction_mt, parsing_function=<function _parse_nuclide_reaction>, plot_option='plot', energy_boundaries=False, **kwargs)[source]

Uses SCALE to dump a binary multigroup library to a text file, and then calls the specified parsing function on the output file.

Parameters:

  • multigroup_library_path (Path) – The path to the SCALE multigroup library file.

  • nuclide_zaid (str) – The ZAID of the nuclide.

  • reaction_mt (str) – The reaction MT to read.

  • parsing_function (Callable[[Union[str, Path], bool, dict], Any]) – The function to call on the output file. This function takes the filename of the output file as its first argument, and whether or not energy boundaries should be returned as its second argument. Additional keyword arguments can be passed to the parsing function using the kwargs argument.

  • plot_option (str) – The plot option to use when running the MG reader. For example 'plot' or 'fido'.

  • energy_boundaries (bool) – If True, the energies at which the cross sections are defined are returned as well.

Return type:

Any

Returns:

An output that is the result of the parsing function

tsunami_ip_utils.xs._read_reactions_from_nuclide(multigroup_library_path, nuclide_zaid, reaction_mts)[source]

Function for reading a set of reactions from a given nuclide in a SCALE multigroup library.

Parameters:

  • multigroup_library_path (Path) – The path to the SCALE multigroup library file.

  • nuclide_zaid (str) – The ZAID of the nuclide.

  • reaction_mts (List[str]) – The list of reaction MTs to read.

Return type:

Dict[str, ndarray]

Returns:

A dictionary containing the cross sections for each reaction MT

Module contents