Covariance API

Author: N. Abrate.

File: covariance.py

Description: tools to produce, read, and extract multi-group relative: covariance matrices with SANDY and NJOY.

class pyNDUS.covariance.Covariance(zaid, temperature=300, group_structure=None, egridname=None, lib='endfb_80', process_resonances=True, author=None, njoy_ver=None, database=False, cwd=None, energy_unit='eV')[source]

Bases: object

Class to process and extract multi-group relative covariance matrices for nuclear data using NJOY and SANDY codes, respectively.

This class manages the workflow for:

Validating user input for nuclide, temperature, group structure, energy grid, library, and working directory.
Creating the necessary directory structure for storing ENDF-6 and ERRORR formatted files (considering different libraries and energy group structures).
Downloading or reading ENDF-6 formatted files for the requested nuclide and library.
Running NJOY (via SANDY) to produce multi-group covariance matrices if not already available.
Extracting and storing covariance data in a structured way for further application.
Providing properties for accessing key attributes (e.g., ZAID, temperature, MAT, covariance matrices).
Plotting covariance or correlation matrices.

Parameters:

zaid (int) – ZAID (Z*1000 + A if Z < 10 or Z*100+A) identifier of the nuclide.
temperature (float, optional) – Temperature in Kelvin (default: 300).
group_structure (iterable, optional) – Energy group structure (list, numpy array, tuple etc.).
energy_unit (str, optional) – Unit used by group_structure. Supported values are "eV" and "MeV". Defaults to "eV".
egridname (str, optional) – Name of the energy grid (default: None).
lib (str, optional) – Nuclear data library to use (default: “endfb_80”).
cwd (str or pathlib.Path, optional) – Working directory for storing files (default: current directory).

zaid

ZAID of the nuclide.

Type:: int

zais

String identifier for the nuclide.

Type:: str

temperature

Temperature in Kelvin for processing the ENDF-6 file with the BROADR module of NJOY.

Type:: float

group_structure

Energy group structure.

Type:: iterable

energy_unit

Unit used by the stored energy group structure.

Type:: str

egridname

Name of the energy grid.

Type:: str

library

Nuclear data library.

Type:: str

path

Working directory for storing files.

Type:: pathlib.Path

MFs2MTs

Mapping from MF numbers to lists of MT numbers (excluding the header, i.e. MT=451).

Type:: dict

mat

MAT number for the nuclide.

Type:: int

rcov

Dictionary with extracted covariance matrices in pandas.DataFrame objects. Available MF: - MF=31 for neutron multiplicities - MF=33 for cross sections - MF=34 for angular distributions - MF=35 for energy distributions

Type:: dict

__init__(zaid, temperature=300, group_structure=None, egridname=None, lib='endfb_80', process_resonances=True, author=None, njoy_ver=None, database=False, cwd=None, energy_unit='eV')[source]

Initialize the Covariance object, create necessary directories, and extract covariance matrices.

Parameters:

zaid (int) – ZAID (Z*1000 + A) identifier of the nuclide.
temperature (float, optional) – Temperature in Kelvin (default: 300).
group_structure (iterable, optional) – Energy group structure.
energy_unit (str, optional) – Unit used by group_structure. Supported values are "eV" and "MeV".
egridname (str, optional) – Name of the energy grid.
lib (str, optional) – Nuclear data library to use.
process_resonances (bool, optional) – If True, process resonance parameter covariances in ERRORR.
author (str, optional) – Author name for logging.
njoy_ver (str, optional) – NJOY version for logging.
database (bool, optional) – If True, use cwd as a database root and create/read the library and energy-grid subdirectories. If False, read existing ERRORR files from cwd or generate missing files there.
cwd (str or pathlib.Path, optional) – Working directory for storing or reading files.

property temperature

Temperature in Kelvin for processing the ENDF-6 file.

Returns:: Temperature in Kelvin.
Return type:: float

property zaid

ZAID (Z*1000 + A) identifier of the nuclide.

Returns:: ZAID value.
Return type:: int

property energy_unit

Unit used by the stored energy group structure.

Returns:: Canonical unit label, either "eV" or "MeV".
Return type:: str

property energy_grid

Energy group structure with unit metadata.

Returns:: Stored energy group boundaries and their unit.
Return type:: utils.EnergyGrid

group_structure_as(unit)[source]

Return the energy group structure converted to a requested unit.

Parameters:: unit (str) – Target energy unit. Supported values are "eV" and "MeV".
Returns:: Energy group boundaries converted to unit.
Return type:: numpy.ndarray

property group_structure_ev

Energy group structure converted to eV.

Returns:: Energy group boundaries in eV.
Return type:: numpy.ndarray

property group_structure_mev

Energy group structure converted to MeV.

Returns:: Energy group boundaries in MeV.
Return type:: numpy.ndarray

property group_structure

Energy group structure.

Returns:: Energy group structure.
Return type:: iterable

property egridname

Name of the energy grid.

Returns:: Energy grid name.
Return type:: str

property library

Nuclear data library name.

Returns:: Library name.
Return type:: str

property path

Working directory for storing files.

Returns:: Path to working directory.
Return type:: pathlib.Path

property zais

String identifier for the nuclide.

Returns:: ZAIS string.
Return type:: str

property MFs2MTs

Mapping from MF numbers to lists of MT numbers (excluding MT=451).

Returns:: Mapping of MF to MT list.
Return type:: dict

property mat

MAT number for the nuclide.

Returns:: MAT number.
Return type:: int

property rcov

Dictionary with extracted covariance matrices.

Returns:: Covariance matrices as pandas.DataFrame objects.
Return type:: dict

get(MT, *, MF, to_numpy=False)[source]

Extract a covariance matrix or submatrix for specified MT(s) and MF.

Parameters:

MT (int, tuple, or list) – MT number(s) or tuple of two MTs for off-diagonal covariance, e.g. (MT1, MT2) or [MT1, MT2]. If a tuple is provided, it must contain exactly two MTs, and it will return the covariance between them. If a list is provided, it will return the full covariance matrix for all specified MTs, e.g. MT1-MT1, MT1-MT2, MT2-MT1, MT2-MT2.
MF (int or str) – Required keyword-only MF number or ‘errorr<MF>’ string, for example 33 or ‘errorr35’.
to_numpy (bool, optional) – If True, return as numpy array. If False, return as pandas.DataFrame.

Returns:

out_cov – Covariance matrix or submatrix.

Return type:

pandas.DataFrame or np.ndarray

static sandy_calls_errorr(endf6_tape, zaid, temperature, group_structure, egridname, errorr_dir, errorr_name, process_resonances, lib, author, njoy_ver)[source]

Run the ERRORR module of NJOY via SANDY and save output files.

Parameters:

endf6_tape (sandy.Endf6) – ENDF-6 formatted tape.
zaid (int) – ZAID identifier.
temperature (float) – Temperature in Kelvin.
group_structure (iterable) – Energy group structure in eV, as expected by NJOY/ERRORR.
egridname (str) – Name of the energy grid.
errorr_dir (pathlib.Path) – Directory where ERRORR output files are saved.
errorr_name (str) – Base name used for generated ERRORR files.
process_resonances (bool) – If True, set ERRORR to process resonance parameter covariances.
lib (str) – Nuclear data library.
author (str) – Author name for logging.
njoy_ver (str) – NJOY version for logging.

Returns:

errorr – Dictionary of ERRORR objects.

Return type:

dict

static write_log_header(fname, author, njoy_ver)[source]

Write .log file header with info for reproducibility.

Parameters:

fname (str or Path) – Path to log file.
author (str) – Author name.
njoy_ver (str) – NJOY version.

Return type:

None

exception pyNDUS.covariance.CovarianceError[source]

Bases: Exception

Custom exception raised for covariance extraction and validation errors.