Tools and Utils

NDLibrary

class NDLibrary

This class acts as an interface to easily retrieve nuclear data for the desried isotope or thermal scattering law, at the desired temperature. This interface makes sure that data is only ever loaded from an ACE file once, and all scattering distributions for all STNeutron instances of the same nuclide are shared, conserving memory.

Warning

Due to historical reasons, in many ACE libraries (mostly those distributed for use with MCNP by LANL), Am242m1 has been given a ZAID of 95242, and Am242 has been given a ZAID of 95642. If this is the case for the ACE library you are using, then these two evaluations will be switched, and looking up the symbol “Am242” will actually provide the evaluation for Am242m1. This can be corrected by modifying the xsdir file itself, swaping the ZAID identifiers for the two evaluations.

Subclassed by pndl::MCNPLibrary, pndl::SerpentLibrary

Public Functions

virtual ~NDLibrary() = default
double atomic_weight_ratio(const std::string &symbol) const

Returns the atomic weight ratio for the nuclide associated with symbol, which was tabulated in the xsdir file.

Parameters

symbol – String contianing the symbol for the nucldie.

const std::vector<double> &temperatures(const std::string &symbol) const

@breif Returns a reference to a vector of all temperatures for which data is given for the provided symbol.

Parameters

symbol – String containing the symbol for the nuclide, or the name of the thermal scattering law.

double nearest_temperature(const std::string &symbol, double temperature) const

Returns the closest nearest provided temperature for the given symbol-temperature combination.

Parameters

  • symbol – String contianing the symbol for the nuclide, or the name of the thermal scattering law to be queried.

  • temperature – Desired temperature for data.

std::shared_ptr<STNeutron> load_STNeutron(const std::string &symbol, double temperature, double tolerance = 1.)

Returns a shared pointer to an STNeutron instance.

Parameters

  • symbol – String for the symbol of the desired nuclide.

  • temperature – Desired temperature for the returned STNeutron data in Kelvin.

  • tolerance – Temperature tolerance in Kelvin for the returned data. If no data is found at the desired temperature, the data at the closest temerature, within +/- tolerance will be returned instead.

std::shared_ptr<STThermalScatteringLaw> load_STTSL(const std::string &symbol, double temperature, double tolerance = 1.)

Returns a shared pointer to an STThermalScatteringLaw instance.

Parameters

  • symbol – String for the name of the desired thermal scattering law.

  • temperature – Desired temperature for the returned scattering law in Kelvin.

  • tolerance – Temperature tolerance in Kelvin for the returned data. If no data is found at the desired temperature, the data at the closest temerature, within +/- tolerance will be returned instead.

inline const std::vector<std::string> &list_STNeutron() const

@breif Returns a vector containing all of the available symbols for STNeutron data.

inline const std::vector<std::string> &list_STTSL() const

@breif Returns a vector containing all of the available symbols for STThermalScatteringLaw data.

inline const std::string &directory_file() const

Returns the path to the file containing the library directory.

MCNPLibrary

class MCNPLibrary : public pndl::NDLibrary

This class is a specialization of the NDLibrary class, which is constructed from an MCNP formated xsdir file.

Warning

Due to historical reasons, in many ACE libraries (mostly those distributed for use with MCNP by LANL), Am242m1 has been given a ZAID of 95242, and Am242 has been given a ZAID of 95642. If this is the case for the ACE library you are using, then these two evaluations will be switched, and looking up the symbol “Am242” will actually provide the evaluation for Am242m1. This can be corrected by modifying the xsdir file itself, swaping the ZAID identifiers for the two evaluations.

Public Functions

MCNPLibrary(const std::string &fname)
Parameters

fname – String with the path to the xsdir file.

SerpentLibrary

class SerpentLibrary : public pndl::NDLibrary

This class is a specialization of the NDLibrary class, which is constructed from a Serpent formated xsdir file.

Warning

Due to historical reasons, in many ACE libraries (mostly those distributed for use with MCNP by LANL), Am242m1 has been given a ZAID of 95242, and Am242 has been given a ZAID of 95642. If this is the case for the ACE library you are using, then these two evaluations will be switched, and looking up the symbol “Am242” will actually provide the evaluation for Am242m1. This can be corrected by modifying the xsdir file itself, swaping the ZAID identifiers for the two evaluations.

Public Functions

SerpentLibrary(const std::string &fname)
Parameters

fname – String with the path to the xsdir file.

ACE

class ACE

Contains data from A Compact ENDF file.

Public Types

enum class Type

Enum to describe the format of the ACE file.

Values:

enumerator ASCII

ACE stored as ASCII text.

enumerator BINARY

ACE stored in NJOY binary format.

Public Functions

ACE(std::string fname, Type type = Type::ASCII)
Parameters

  • fname – Name of the file to be loaded.

  • type – Format of ACE file. Default is ASCII.

ACE(std::istream &data, Type type)
Parameters

  • data – Input stream providing data.

  • type – Format of the data.

~ACE() = default
inline const ZAID &zaid() const

Gets the ZAID of nuclide represented.

inline double temperature() const

Gets the temperature for which the data was prepared, in kelvins.

inline double awr() const

Gets the Atomic Weight Ratio (AWR) of the nuclide.

inline bool fissile() const

Returns true for a fissile nuclide, false for a non-fissile nuclide.

inline const std::pair<int32_t, double> &izaw(std::size_t i) const

Retrieves an (int32_t, double) pair from the IZAW array.

Parameters

i – index to a pair in the IZAW array. Must be in the range [0,16).

inline std::pair<int32_t, double> &izaw(std::size_t i)

Retrieves an (int32_t, double) pair from the IZAW array.

Parameters

i – index to a pair in the IZAW array. Must be in the range [0,16).

inline const int32_t &nxs(std::size_t i) const

Retrieves a value from the NXS array.

Parameters

i – index to element in the NXS array. Must be in the range [0,16).

inline int32_t &nxs(std::size_t i)

Retrieves a value from the NXS array.

Parameters

i – index to element in the NXS array. Must be in the range [0,16).

inline const int32_t &jxs(std::size_t i) const

Retrieves a value from the JXS array.

Parameters

i – index to element in the JXS array. Must be in the range [0,32).

inline int32_t &jxs(std::size_t i)

Retrieves a value from the JXS array.

Parameters

i – index to element in the JXS array. Must be in the range [0,32).

inline const double &xss(std::size_t i) const

Retrieves a value from the XSS array as a double.

Parameters

i – index to element in the XSS array.

inline double &xss(std::size_t i)

Retrieves a value from the XSS array as a double.

Parameters

i – index to element in the XSS array.

template<class T>
inline T xss(std::size_t i) const

Retrieves a value from the XSS array, cast to type T.

Parameters

i – index to element in the XSS array.

std::vector<std::pair<int32_t, double>> izaw(std::size_t i, std::size_t len) const

Retrieves a vector contianing a continuous segment of (int32_t,double) pairs from the IZAW array.

Parameters

  • i – Starting index in the IZAW array.

  • len – Number of elements to return.

std::vector<int32_t> nxs(std::size_t i, std::size_t len) const

Retrieves a vector contianing a continuous segment of values from the NXS array.

Parameters

  • i – Starting index in the NXS array.

  • len – Number of elements to return.

std::vector<int32_t> jxs(std::size_t i, std::size_t len) const

Retrieves a vector contianing a continuous segment of values from the JXS array.

Parameters

  • i – Starting index in the JXS array.

  • len – Number of elements to return.

std::vector<double> xss(std::size_t i, std::size_t len) const

Retrieves a vector contianing a continuous segment of values from the XSS array.

Parameters

  • i – Starting index in the XSS array.

  • len – Number of elements to return.

template<class T>
inline std::vector<T> xss(std::size_t i, std::size_t len) const

Retrieves a vector contianing a continuous segment of values from the XSS array, all cast to type T.

Parameters

  • i – Starting index in the XSS array.

  • len – Number of elements to return.

inline const std::string &zaid_id() const

Returns the ZAID string from the ACE header.

inline const std::string &comment() const

Returns the comment string from the ACE header.

inline const std::string &mat() const

Returns the ENDF MAT string from the ACE header.

inline const std::string &date() const

Returns the processing date string from the ACE header.

void save_binary(const std::string &fname) const

Saves a copy of the ACE file in the type 2 binary format.

Parameters

fname – Name of file where binary data will be saved.

void save_binary(std::ostream &data) const

Writes the ACE file in the type 2 binary format to a stream.

Parameters

data – Output stream to where data is written.

const double *xss_data() const

Returns a pointer to the beginning of the XSS array.

inline int32_t ESZ() const

Returns the index to the beginning of the ESZ block.

inline int32_t NU() const

Returns the index to the beginning of the NU block.

inline int32_t MTR() const

Returns the index to the beginning of the MTR block.

inline int32_t LQR() const

Returns the index to the beginning of the LQR block.

inline int32_t TYR() const

Returns the index to the beginning of the TYR block.

inline int32_t LSIG() const

Returns the index to the beginning of the LSIG block.

inline int32_t SIG() const

Returns the index to the beginning of the SIG block.

inline int32_t LAND() const

Returns the index to the beginning of the LAND block.

inline int32_t AND() const

Returns the index to the beginning of the AND block.

inline int32_t LDLW() const

Returns the index to the beginning of the LDLW block.

inline int32_t DLW() const

Returns the index to the beginning of the DLW block.

inline int32_t LUNR() const

Returns the index to the beginning of the UNR block.

inline int32_t DNEDL() const

Returns the index to the beginning of the DNEDL block.

inline int32_t DNED() const

Returns the index to the beginning of the DNED block.

inline int32_t DNU() const

Returns the index to the beginning of the DNU block.

inline int32_t BDD() const

Returns the index to the beginning of the BDD block.

inline int32_t GPD() const

Returns the index to the beginning of the GPD block.

XSPacket

struct XSPacket

A struct to hold the set of basic cross sections.

Public Functions

inline XSPacket &operator+=(const XSPacket &other)
inline XSPacket &operator-=(const XSPacket &other)
inline XSPacket &operator*=(const double &C)
inline XSPacket &operator/=(const double &C)
inline XSPacket operator+(const XSPacket &other) const
inline XSPacket operator-(const XSPacket &other) const
inline XSPacket operator*(const double &C) const
inline XSPacket operator/(const double &C) const
inline XSPacket operator+() const
inline XSPacket operator-() const

Public Members

double total

Total cross section (MT 1)

double elastic

Elastic cross section (MT 2)

double inelastic

Inelastic cross section (MT 3)

double absorption

Absorption cross section (MT 27)

double fission

Fission cross section (MT 18)

double capture

Radiative capture cross section (MT 102)

double heating

Heating number

PCTable

class PCTable

Contains a tabulated PDF and CDF for any quantity.

Public Functions

PCTable(const ACE &ace, std::size_t i, double normalization = 1.)
Parameters

  • ace – ACE file to take data from.

  • i – Starting index of distribution in the XSS array.

  • normalization – Value by which all y-grid points will be divided. Default value is 1.

PCTable(const std::vector<double> &values, const std::vector<double> &pdf, const std::vector<double> &cdf, Interpolation interp)
Parameters

  • values – Vector of values for which the PDF and CDF are provided.

  • pdf – The Probability Density Function for the provided values.

  • cdf – The Cumulative Density Function for the provided values.

  • interp – Interpolation rule for the data. May be either Histogram or LinLin.

~PCTable() = default
inline double sample_value(double xi) const

Samples a value from the distribution.

Parameters

xi – Random value on the interval [0,1).

inline double pdf(double value) const

Returns the value of the PDF for the queried value.

Parameters

value – Value at which to evaluate the PDF.

inline double min_value() const

Returns the lowest possible value that can be sampled.

inline double max_value() const

Returns the highest possible value that can be sampled.

inline std::size_t size() const

Returns the number of grid points.

inline const std::vector<double> &values() const

Returns a vector of the value grid points.

inline const std::vector<double> &pdf() const

Returns a vector of the PDF grid points.

inline const std::vector<double> &cdf() const

Returns a vector of the CDF grid points.

inline Interpolation interpolation() const

Returns the method of interpolation used for the distribution.

Frame

enum class pndl::Frame : uint32_t

Enum to indicate the frame of reference for secondary data angle and energy data.

Values:

enumerator Lab

Laboratory frame

enumerator CM

Center of Mass frame

CMToLab

struct CMToLab

A struct contianing helper methods to convert scattering angle and energies provided in the center of mass frame, to the lab frame.

Public Static Functions

static inline void transform(double Ein, double A, double &mu, double &Eout)

Transfrom mu and Eout from the CM frame to the Lab frame.

Parameters

  • Ein – Incident energy of the particle.

  • A – Atomic weight ratio of the target nuclide.

  • mu – Scattering angle in the center of mass frame. The value is changed to the scattering angle in the lab frame upon return.

  • Eout – Scattering energy in the center of mass frame. The value is changed to the scattering energy in the lab frame upon return.

static inline void transform(double Ein, double A, AngleEnergyPacket &ae)

Transfrom an AngleEnergyPacket from the CM frame to the Lab frame.

Parameters

  • Ein – Incident energy of the particle.

  • A – Atomic weight ratio of the target nuclide.

  • ae – AngleEnergyPacket which initially contains the scattering angle and energy in the CM frame, which is changed to the lab frame upon return.

static inline double angle_jacobian(double Ein, double A, double mu, double Eout)

Computes the Jacobian to transform the angular PDF from the center of mass frame, to the lab frame. This quantity is dmu_cm/dmu_lab. This formula comes from the public MCNP theory manual.

Parameters

  • Ein – Incident energy in the lab frame.

  • A – Atomic weight ratio of the target nuclide.

  • mu – Cosine of the scattering angle in the lab frame.

  • Eout – Scattering energy in the lab frame.

static inline double angle_jacobian(double Ein, double A, AngleEnergyPacket ae)

Computes the Jacobian to transform the angular PDF from the center of mass frame, to the lab frame. This quantity is dmu_cm/dmu_lab. This formula comes from the public MCNP theory manual.

Parameters

  • Ein – Incident energy in the lab frame.

  • A – Atomic weight ratio of the target nuclide.

  • ae – AngleEnergyPacket which contains the scattering angle and energy in the lab frame.

static inline double angle_jacobian(double Ein, double A, double Q, double mu, double mu_cm)

Computes the Jacobian to transform the angular PDF from the center of mass frame, to the lab frame. This quantity is dmu_cm/dmu_lab.

Parameters

  • Ein – Incident energy in the lab frame.

  • A – Atomic weight ratio of the target nuclide.

  • Q – Q-value of the reaction.

  • mu – Cosine of the scattering angle in the lab frame.

  • mu_cm – Cosine of the scattering angle in the center of mass frame.

static inline double jacobian(double Eout, double Eout_cm)

Computes the Jacobian to transform the joint PDF from the center of mass frame, to the lab frame. This quantity is (dmu_cm/dmu_lab) * (dE_cm/dE_lab).

Parameters

  • Eout – Scattering energy in the lab frame.

  • Eout_cm – Scattering energy in the center of mass frame.

Interpolation

enum class pndl::Interpolation : uint32_t

Enum to indicate the type of interpolation to use when evaluating tabulated data.

Values:

enumerator Histogram

y is constant in x

enumerator LinLin

y is linear in x

enumerator LinLog

y is linear in ln(x)

enumerator LogLin

ln(y) is linear in x

enumerator LogLog

ln(y) is linear in ln(x)

Interpolator

class Interpolator

A generic interface for any Interpolation rule.

Public Functions

inline Interpolator(Interpolation interp)
Parameters

interp – Interpolation rule to use for all functions.

template<class T>
inline T interpolate(T x, T x1, T y1, T x2, T y2) const

Interpolates between (x1,y1) and (x2,y2), calculating y for a given x.

Parameters

  • x – Value at which to perform the interpolation.

  • x1 – x coordinate of the first known point.

  • y1 – y coordinate of the first known point.

  • x2 – x coordinate of the second known point.

  • y2 – y coordinate of the second known point.

template<class T>
inline T invert(T y, T x1, T y1, T x2, T y2) const

Reverse interpolates between (x1,y1) and (x2,y2), calculating x for a given y.

Parameters

  • y – Value at which to perform the inversion.

  • x1 – x coordinate of the first known point.

  • y1 – y coordinate of the first known point.

  • x2 – x coordinate of the second known point.

  • y2 – y coordinate of the second known point.

template<class T>
inline T integrate(T x_low, T x_hi, T x1, T y1, T x2, T y2) const

Integrates between x_low and x_hi according to the provided interpolation rule, and the known points (x1,y1) and (x2,y2).

Parameters

  • x_low – Lower bound of integration.

  • x_hi – Upper bound of integration.

  • x1 – x coordinate of the first known point.

  • y1 – y coordinate of the first known point.

  • x2 – x coordinate of the second known point.

  • y2 – y coordinate of the second known point.

template<class ForwardIt>
inline void verify_x_grid(ForwardIt first, ForwardIt last) const

Checks that the x-grid is valid for the given interpolation rule.

Parameters

  • first – Iterator to the first x value.

  • last – Iterator to one after the last x value.

template<class ForwardIt>
inline void verify_y_grid(ForwardIt first, ForwardIt last) const

Checks that the y-grid is valid for the given interpolation rule.

Parameters

  • first – Iterator to the first y value.

  • last – Iterator to one after the last y value.

inline Interpolation interpolation() const

Returns the current Interpolation rule.

Linearization

Tabulated1D pndl::linearize(const std::vector<double> &x, const std::vector<double> &y, std::function<double(double)> f, double tolerance = 0.001)

Linearizes the function f, keeping the user provided points in x and y. The resulting linearized function is returnedd as a Tabulated1D.

Warning

The values y[i] MUST agree with the values of f(x[i]). This is not checked however, due to the fact that the function f is allowed to be discontinuous. A discontinuity is represented with two adjacent values in the x array which are equal, each having a difference associated y value. If the values y[i] do not equal f(x[i]) (barring discontinuities), this function may not finish, or may yield unexpected results.

Parameters

  • x – Reference to the vector of x values which will be kept for linear interpolation. This vector must be sorted.

  • y – Reference to the vector of y values which will be kept for linear interpolation. Must be the same length as x.

  • f – Function to be linearized.

  • tolerance – Maximum relative absolute error for linear interpolation. The default tolerance is 0.001, or 0.1%.

Tabulated1D pndl::linearize(double x_min, double x_max, std::function<double(double)> f, double tolerance = 0.001)

Linearizes the function f over the interval [x_min, x_max]. The resulting function is returned as a Tabulated1D.

Warning

This function may not finish, or may yield unexpected results if the function f is discontinuous over the interval.

Parameters

  • x_min – Minimum x value for linearization.

  • x_max – Maximum x value for linearization.

  • f – Function to linearize.

  • tolerance – Maximum relative absolute error for linear interpolation. The default tolerance is 0.001, or 0.1%.

Random Number Generation

double pndl::rng()

Returns a pseudo random number on the interval [0,1).

void pndl::rng_seed(std::uint64_t seed)

Sets the seed of rng to a specific value.

Parameters

seed – New seed for rng.

void pndl::rng_reset()

Resets the seed of rng to the default value.

void pndl::rng_advance(std::uint64_t n)

Advances rng by a specified number of steps.

n Number of steps to advance rng.

ZAID

class ZAID

Class which represents a ZAID identifier.

Public Functions

inline ZAID(uint8_t Z, uint32_t A)
Parameters

  • Z – Atomic number for ZAID.

  • A – Atomic mass for ZAID.

inline uint8_t Z() const

Returns the atomic number of ZAID.

inline uint32_t A() const

Returns the atomic mass of ZAID.

inline uint32_t zaid() const

Returns the ZAID as an unsigned integer.

inline bool operator==(const ZAID &rhs) const

Returns true if two ZAIDs are equal, and false if not.

inline bool operator<(const ZAID &rhs) const

Returns true if one ZAID’s atomic number is less than the other’s. If the atomic numbers are equal and the ZAID’s atomic mass is less than the other’s, true is also returned. Otherwise, flase is returned.

Element

class Element

Class which identifies an element.

Public Functions

inline Element(uint8_t Z)
Parameters

Z – Atomic number of the element. Must be in the interval [1,118].

inline Element(const ZAID &zaid)
Parameters

zaid – ZAID identifier. Requires zaid.Z() be in the interval [1,118].

Element(const std::string &name_or_symbol)
Parameters

name_or_symbol – String containing either the name or the symbol of the desired element.

inline uint8_t Z() const

Returns the atomic number of the element.

inline uint8_t atomic_number() const

Returns the atomic number of the element.

inline uint32_t largest_isotope() const

@breif Returns the lartgest possible atomic mass number for the element.

inline const std::string &symbol() const

Returns the symbol of the element.

inline const std::string &name() const

Returns the name of the element.

inline ZAID zaid() const

Returns the ZAID which represents the natural element.

inline bool operator==(const Element &rhs) const

Returns true if two elements are the same, and false if not.

inline bool operator<(const Element &rhs) const

Returns true if the Element’s atomic number is less than the other’s, and false if otherwise.

Isotope

class Isotope

Class which identifies an isotope. The atomic mass number must be at least equal to the atomic number, and can be no larger than 300.

Public Functions

inline Isotope(const Element &element, uint32_t A)
Parameters
inline Isotope(uint8_t Z, uint32_t A)
Parameters

  • Z – Atomic number of the Isotope.

  • A – Atomic mass of the Isotope.

inline Isotope(const ZAID &zaid)
Parameters

zaid – ZAID of the Isotope.

inline Isotope(const std::string &symbol)
Parameters

symbol – String containing the symbol for the isotope. The symbol must be in SSAAA format, such as Al27, or U235.

inline uint8_t Z() const

Returns atomic number of isotope.

inline uint8_t atomic_number() const

Returns atomic number of isotope.

inline uint32_t A() const

Returns atomic mass of isotope.

inline uint32_t atomic_mass() const

Returns atomic mass of isotope.

inline ZAID zaid() const

Returns ZAID of isotope.

inline std::string symbol() const

Returns the symbol of the isotope.

inline const std::string &element_symbol() const

Returns the Element symbol of the isotope.

inline const std::string &element_name() const

Returns the Element name of the isotope.

inline bool operator==(const Isotope &rhs) const

Returns true if two isotopes are the same, and false if not.

inline bool operator<(const Isotope &rhs) const

Returns true if one Isotope’s atomic number is less than the other’s. If the atomic numbers are equal and the Isotope’s atomic mass is less than the other’s, true is also returned. Otherwise, flase is returned.

Nuclide

class Nuclide

Class which identifies a nuclide. The isomer level may be no greater than 2.

Public Functions

inline Nuclide(const Isotope &isotope, uint8_t level = 0)
Parameters

  • isotope – Isotope of the nuclide.

  • level – Isomer level of the nuclide.

inline Nuclide(uint8_t Z, uint32_t A, uint8_t level = 0)
Parameters

  • Z – Atomic number of nuclide.

  • A – Atomic mass of nuclide.

  • level – Isomer level of nuclide.

inline Nuclide(const ZAID &zaid)
Parameters

zaid – ZAID of nuclide.

inline Nuclide(const std::string &symbol)
Parameters

symbol – String containing the symbol for the nuclide. The symbol must be in SSAAA format. If the nuclide is an isomer, the isomer level can be added as SSAAAmL. The level can be 0, 1, or 2.

inline uint8_t Z() const

Returns atomic number of isotope.

inline uint8_t atomic_number() const

Returns atomic number of isotope.

inline uint32_t A() const

Returns atomic mass of isotope.

inline uint32_t atomic_mass() const

Returns atomic mass of isotope.

inline uint8_t level() const

Returns the isomer level of the nuclide.

inline ZAID zaid() const

Returns the ZAID for the nuclide.

inline std::string symbol() const

Returns the symbol of the nuclide.

inline std::string isotope_symbol() const

Returns the symbol of the isotope.

inline const std::string &element_symbol() const

Returns the element symbol of the nuclide.

inline const std::string &element_name() const

Returns the element name of the nuclide.

inline bool operator==(const Nuclide &rhs) const

Returns true if two Nuclide are the same, and false if not.

inline bool operator<(const Nuclide &rhs) const

Returns true if one Nuclides’s atomic number is less than the other’s. If the atomic numbers are equal and the Nuclides’s atomic mass is less than the other’s, true is also returned. If the atomic masses are equal, and the isomer level is less than the other’s, true is returned. Otherwise, flase is returned.

PNDLException

class PNDLException : public std::exception

Class used for exceptions by the library.

Public Functions

inline PNDLException()
inline PNDLException(const std::string &mssg, std::source_location location = std::source_location::current())
Parameters

  • mssg – Error message.

  • file – Location where the error occurred;

~PNDLException() = default
inline void add_to_exception(const std::string &mssg, std::source_location location = std::source_location::current())

Adds details to the exception message as it is passed up the stack.

Parameters

  • mssg – Error message.

  • location – Location where the error was thrown.

inline const char *what() const noexcept override