fudge.gnds.covariances package

Submodules

fudge.gnds.covariances.base module

Base classes for covariances: matrix, axes.

class fudge.gnds.covariances.base.covarianceMatrix(label, type='absolute', matrix=None, productFrame=None)[source]

Bases: xData.ancestry.ancestry

Base class for all covariances. covarianceMatrix contains a label, a covariance ‘type’ which might be ‘absolute’, ‘relative’ or ‘correlation’, and an optional ‘productFrame’ for outgoing distribution covariances. Matrix data is stored in an xData.gridded.gridded2d class. May be diagonal, symmetric, sparse, etc

check(info)[source]

Check if uncertainty in the bounds passed into the checker. Requires specification of the data (“theData”) if the covariance is not relative. I was not creative when I coded this, so it will fail when theData.getValue( x ) doesn’t exist or is a function of more than one value.

convertAxesToUnits(units)[source]

Converts all the axes’ units. The parameter units should be a list of units with the same length as self.axes

convertUnits(unitMap)[source]
fix(**kw)[source]

Fix uncertainty using the bounds passed into the fixer. Requires specification of the data (“theData”) if the covariance is not relative. I was not creative when I coded this, so it will fail when theData.getValue( x ) doesn’t exist or is a function of more than one value.

getColumnBounds(unit=None)[source]

Get the bounds of the column. If unit is specified, return the bounds in that unit.

getCorrelationMatrix()[source]

Returns the correlation matrix generated from self’s covariance matrix. This is essentially a copy of self, but renormalized by the uncertainty:

correlation[i,j] = covariance[i,j]/sqrt(covariance[i,i])/sqrt(covariance[j,j])

We reuse the covariance matrix class so that we can do plotting, etc. If you have a correlation matrix, you can safely recover it provided you have the uncertainty vector.

Currently only works for a square covariance matrix and not a off-diagonal part of another covariance.

getRowBounds(unit=None)[source]

Get the bounds of the row. If unit is specified, return the bounds in that unit.

getUncertaintyVector(theData=None, relative=True)[source]

Get an XYs1d object containing uncertainty for this matrix. Convert relative/absolute if requested (if so, must also pass central values as theData)

Examples:

  • if the covariance matrix is relative and we want relative uncertainty vector, just do:

    > matrix.getUncertaintyVector()

  • if we want the absolute matrix instead:

    > matrix.getUncertaintyVector( theData=<XYs1d instance>, relative=False )

getValue(x, y)[source]
group(groupBoundaries=(None, None), groupUnit=(None, None))[source]

Group the matrix in self

Parameters:
  • groupBoundaries – a 2 element list containing the group boundaries for the rows and columns (respectively) of the covariance to be regrouped rows go in the first element, columns in the second
  • groupUnit – a 2 element list containing the units in which group boundaries are specified for the rows and columns (respectively) of the covariance to be regrouped
Returns:

the regrouped matrix (an xData.array.full as the array in a gridded2d.matrix)

Note

We still need to do flux weighting

Regrouping Theory

Given a function f(E), we write the grouped data using fudge’s flat interpolation scheme. We note that we could write this scheme as an expansion over basis functions:

f(E) = \sum_{i=0}^{N+1} w_i(E) * f_i

where the weight functions w_i(E) are

w_i(E) = 1  \;\text{for}\; E_i <= E <= E_{i+1}; \;\; 0 \;\textrm{otherwise}

These weights are an orthogonal (bot not orthonormal) basis, with

(E_{i+1}-E_i) \delta_{ij} = \int dE w_i(E) * w_j(E)

So, to transform from basis w_i(E) to v_i(E) (which has group boundaries [ E'_0, ... ]), do:

f'_j = \sum_i m_{ji} f_i

where f' is the regrouped function coefficients and m_{ji} is the matrix

m_{ij} = (E'_{i+1}-E'_i)^{-1} \int dE v_i(E) w_j(E)

Applying regrouping theory to covariance matrices

When we are given a covariance matrix c_{ij} in ENDF, it is meant to be interpreted as a grouped covariance in both the direction of the matrix rows and the matrix columns. Therefore, we must regroup in both the row direction and the column direction. The ENDF format gives both the group boundaries for the rows and columns. In other words, ENDF gives us the following rule for evaluating the continuous row- column covariance:

c( E1, E2 ) = \sum_{ij} w_i(E1) w_j(E2) c_{ij}

Computing m_{ij} as before,

cc_{ij} = \sum_{i',j'} m_{ii'} c_{i'j'} m_{j'j}

It is straightforward to generalize to the case where the row and column bases are different.

In the routine below, we abuse xData.XYs1d to specify the functions w_i(E) and use the XYs1d.groupOneFunction() method to perform the integrals to get the regrouping matrix. We do this separately for the rows and the columns. The matrix multiplication that converts a covariance from one pair of bases (group structures) to another is accomplished using numpy.

An explanation of fudge’s ‘flat’ interpolation

Suppose we have a function f(E) specified using fudge’s ‘flat’ interpolation. Then we have N entries [f_0, f_1, ..., f_{N-1}] and a set of group boundaries [E_0, E_1, ..., E_N] and the following rule for interpolation:

  • Below E_0, f(E) evaluates to 0.0
  • From E_0 \rightarrow E_1, f(E) evaluates to f_0
  • From E_1 \rightarrow E_2, f(E) evaluates to f_1
  • From E_{i} \rightarrow E_{i+1}, f(E) evaluates to f_i
  • From E_{N-1} \rightarrow E_N, f(E) evaluates to f_{N-1}
  • Above E_N, f(E) evaluates to 0.0
isSymmetric()[source]

Simple test to determin if an underlying matrix is symmetric :return:

label
matrix = None

a xData.gridded.gridded2d instance containing the matrix

moniker = 'covarianceMatrix'
static parseXMLNode(element, xPath, linkData)[source]

Translate <covarianceMatrix> element from xml into python class.

plot(title=None, scalelabel=None, xlim=None, ylim=None, xlog=False, ylog=False)[source]
Parameters:
  • title
  • scalelabel
  • xlim
  • ylim
  • xlog
  • ylog
Returns:

removeExtraZeros(verbose=False)[source]

Remove all extra zeros from the underlying matrix :return:

toAbsolute(rowData=None, colData=None)[source]

Rescales self (if it is a relative covariance) using XYs1d rowData and colData to convert self into an absolute covariance matrix.

Parameters:
  • rowData (XYs1d) – an XYs1d instance containing data to rescale covariance in the “row direction” if it isn’t given, we’ll compute it from the corresponding data in the reactionSuite
  • colData (XYs1d) – an XYs1d instance containing data to rescale covariance in the “col direction” if it isn’t given, we’ll compute it from the corresponding data in the reactionSuite
Returns:a copy of self, but rescaled and with the type set to absoluteToken
toCovarianceMatrix()[source]

Return self, converted to a base instance. Since it already is one, we just return a copy. :return:

toRelative(rowData=None, colData=None)[source]

Rescales self (if it is a absolute covariance) using XYs1d rowData and colData to convert self into a relative covariance matrix.

Parameters:
  • rowData (XYs1d) – an XYs1d instance containing data to rescale covariance in the “row direction” if it isn’t given, we’ll compute it from the corresponding data in the reactionSuite
  • colData (XYs1d) – an XYs1d instance containing data to rescale covariance in the “col direction” if it isn’t given, we’ll compute it from the corresponding data in the reactionSuite

Note

If the column axis is a link, only rowData is needed. If neither rowData nor colData are specified, you’d better hope that the covariance is already relative because this will throw an error.

Returns:a copy of self, but rescaled and with the type set to relativeToken
toXMLList(indent='', **kwargs)[source]
Parameters:
  • indent
  • kwargs
Returns:

type = None

‘relative’ or ‘absolute’

fudge.gnds.covariances.covarianceSuite module

Module with containers for covariances in several different forms

class fudge.gnds.covariances.covarianceSuite.covarianceSections[source]

Bases: fudge.gnds.suites.suite

Most covariances are stored in ‘sections’, each representing either the internal covariance for a single quantity (i.e. cross section) or the cross-term between two quantities

moniker = 'covarianceSections'
class fudge.gnds.covariances.covarianceSuite.covarianceSuite(projectile, target, evaluation, GNDS_version='1.9')[source]

Bases: xData.ancestry.ancestry

All covariances for a target/projectile combination are stored in a covarianceSuite in gnds. The covarianceSuite is stored in a separate file from the reactionSuite.

Within the covarianceSuite, data is sorted into sections (see the section module), each of which contains one section of the full covariance matrix.

check(**kwargs)[source]

Check all covariance sections, returning a list of warnings.

Parameters:
  • checkUncLimits (bool) – Should we check the uncertainty limits? (default: True)
  • minRelUnc (float) – Minimum allowable relative uncertainty (default: 0.0)
  • maxRelUnc (float) – Maximum allowable relative uncertainty (default: 10.0)
  • theData – A reference to the data for this covariance. This is useful for converting between relative and absolute covariance (default: None)
  • negativeEigenTolerance (float) – Ignore negative eigenvalues smaller than this (default: -1e-6)
  • eigenvalueRatioTolerance (float) – Warn if smallest eigenvalue < this value * biggest (default: 1e-8)
  • eigenvalueAbsoluteTolerance (float) – Warn if smallest eigenvalue < this value (default: 1e-14)
Return type:

warning.context

convertUnits(unitMap)[source]

unitMap is a dictionary with old/new unit pairs where the old unit is the key (e.g., { ‘eV’ : ‘MeV’, ‘b’ : ‘mb’ }).

covarianceSections
externalFiles
fix(**kwargs)[source]

Apply basic fixes to a covariance

Parameters:
  • removeNegativeEVs (bool) – Should we remove eigenspaces corresponding to negative eigenvalues? (Default: True)
  • removeSmallEVs (bool) – Should we remove eigenspaces corresponding to small eigenvalues? (Default: False)
  • fixUncLimits (bool) – Should we fix the uncertainties to lie within bounds imposed by minRelUnc and maxRelUnc? (Default: False)
  • minRelUnc (float or None) – Minimum allowable uncertainty for this covariance
  • maxRelUnc (float or None) – Maximum allowable uncertainty for this covariance
  • theData (instance or None) – Reference to the data that accompanies this covariance so that we may convert between absolute and relative covariance as needed.
moniker = 'covarianceSuite'
parameterCovariances
static parseXMLNode(element, xPath, linkData)[source]
projectile = None

The projectile

removeExtraZeros()[source]

Checks all covariance matrices for rows/columns of all zero, removes them if found.

saveToFile(fileName, **kwargs)[source]
saveToOpenedFile(fOut, **kwargs)[source]
styles
target = None

The target

toXMLList(indent='', **kwargs)[source]

Write self out to GNDS-XML

class fudge.gnds.covariances.covarianceSuite.parameterCovariances[source]

Bases: fudge.gnds.suites.suite

Resolved and unresolved resonance parameters are stored inside the parameterCovariances

moniker = 'parameterCovariances'
fudge.gnds.covariances.covarianceSuite.readXML(gndsCovariancesFile, reactionSuite=None)[source]

fudge.gnds.covariances.distributions module

class fudge.gnds.covariances.distributions.LegendreLValue(L1, L2, frame)[source]

Bases: fudge.gnds.suites.suite

Represents one subsection of the Legendre coefficient covariance matrix: covariance between coefficients for two Legendre orders at various energies

L1 = None
L2 = None
check(info)[source]
fix(**kw)[source]
frame = None
moniker = 'LegendreLValue'
classmethod parseXMLNode(element, xPath, linkData)[source]
toXMLList(indent='', **kwargs)[source]
class fudge.gnds.covariances.distributions.LegendreOrderCovarianceForm(label=None, lvalues=None)[source]

Bases: xData.ancestry.ancestry

Stores covariance between energy-dependent Legendre coefficients for a reaction. This class contains one or more LegendreLValue sections, each section containing the matrix between a pair of L-values

addLegendreOrder(LValue)[source]
check(info)[source]
convertUnits(unitMap)[source]
fix(**kw)[source]
label
lvalues = None

the l values of course

moniker = 'LegendreOrderCovariance'
classmethod parseXMLNode(element, xPath, linkData)[source]
toXMLList(indent='', **kwargs)[source]

fudge.gnds.covariances.mixed module

class fudge.gnds.covariances.mixed.mixedForm(label=None, components=None)[source]

Bases: xData.ancestry.ancestry

Covariance for a single quantity, stored as several separate matrices that must be summed together. In general, the energy bounds for these matrices can overlap (unlike regions1d cross section data).

addComponent(covariance)[source]
Parameters:covariance – an instance of covariance (or inherited class)
check(info)[source]
components = None

a Python list containing instances of mixedForm, summedCovariance, and covarianceMatrix

convertUnits(unitMap)[source]
fix(**kw)[source]
getColumnBounds(unit=None)[source]

Get the bounds of the column. If unit is specified, return the bounds in that unit. Otherwise, take unit from the first sub-matrix.

getCorrelationMatrix()[source]
getMatchingComponent(rowBounds=None, columnBounds=None)[source]
Parameters:
  • rowBounds
  • columnBounds
Returns:

getRowBounds(unit=None)[source]

Get the bounds of the row. If unit is specified, return the bounds in that unit. Otherwise, take unit from first sub-matrix.

getUncertaintyVector(theData=None, relative=True)[source]

Combines all subsections into single uncertainty vector, converting to relative if requested.

Returns:an XYs1d instance
label
makeSafeBounds()[source]

Go through all the components and make sure the bounds don’t overlap. If they do, it is likely a bug.

moniker = 'mixed'
classmethod parseXMLNode(element, xPath, linkData)[source]

Translate <mixed> element from xml.

plot(title=None, scalelabel=None, xlim=None, ylim=None, xlog=False, ylog=False)[source]
toAbsolute(rowData=None, colData=None)[source]

Rescales self (if it is a relative covariance) using XYs1d rowData and colData to convert self into an absolute covariance matrix.

Parameters:
  • rowData – an XYs1d instance containing data to rescale covariance in the “row direction”
  • colData – an XYs1d instance containing data to rescale covariance in the “col direction”

Note

If the column axis is set to ‘mirrorOtherAxis’, only rowData is needed. If neither rowData nor colData are specified, you’d better hope that the covariance is already absolute because this will throw an error.

Returns:a copy of self, but rescaled and with the type set to absoluteToken
toCovarianceMatrix(label='composed')[source]

Sum all parts together to build a single matrix.

toRelative(label='composed', rowData=None, colData=None)[source]

Rescales self (if it is a absolute covariance) using XYs1d rowData and colData to convert self into a relative covariance matrix.

Parameters:
  • rowData – an XYs1d instance containing data to rescale covariance in the “row direction”
  • colData – an XYs1d instance containing data to rescale covariance in the “col direction”

Note

If the column axis is set to ‘mirrorOtherAxis’, only rowData is needed. If neither rowData nor colData are specified, you’d better hope that the covariance is already relative because this will throw an error.

Returns:a copy of self, but rescaled and with the type set to relativeToken
toXMLList(indent='', **kwargs)[source]

fudge.gnds.covariances.modelParameters module

class fudge.gnds.covariances.modelParameters.averageParameterCovariance(label, rowData=None, columnData=None)[source]

Bases: fudge.gnds.covariances.section.section

For storing unresolved resonance parameter covariances. Very similar to covariances for cross section, nubar, etc.: they require an energy grid + matrix.

Each average parameter (e.g. elastic width, capture width, etc.) has its own averageParameterCovariance section.

moniker = 'averageParameterCovariance'
class fudge.gnds.covariances.modelParameters.parameterCovariance(label, rowData=None, columnData=None)[source]

Bases: fudge.gnds.suites.suite

For storing unresolved resonance parameter covariances. Very similar to covariances for cross section, nubar, etc.: they require an energy grid + matrix.

Each average parameter (e.g. elastic width, capture width, etc.) has its own averageParameterCovariance section.

check(info)[source]

check each section

crossTerm
moniker = 'parameterCovariance'
classmethod parseXMLNode(element, xPath, linkData)[source]

Translate <section> element from xml.

toXMLList(indent='', **kwargs)[source]
class fudge.gnds.covariances.modelParameters.parameterCovarianceMatrix(label, matrix, parameters_=None, type='relativeCovariance')[source]

Bases: fudge.gnds.abstractClasses.form

Store covariances (or correlations, depending on ‘type’) between model parameters

check(info)[source]
convertUnits(unitMap)[source]
fix(**kw)[source]

assemble some useful info, to be handed down to children’s fix() functions

moniker = 'parameterCovarianceMatrix'
classmethod parseXMLNode(element, xPath, linkData)[source]
toXMLList(indent='', **kwargs)[source]

Bases: xData.link.link

Establishes a link between one or more rows of a parameterCovariance and corresponding parameter(s). Supports linking to specific parameters inside a table or list.

For example, if we have a 2x4 table
|A B C D| |E F G H|

and wish to give a 4x4 covariance matrix for elements in the 2nd and 4th column of the table, we can create a parameterLink pointing to the table, with ‘matrixStartIndex=0’, ‘nParameters=4’, ‘parameterStartIndex=1’, ‘parameterStride=2’.

The corresponding covariance matrix rows would then correspond to ‘B, D, F, H’.

moniker = 'parameterLink'
toXMLList(indent='', **kwargs)[source]
class fudge.gnds.covariances.modelParameters.parameters[source]

Bases: fudge.gnds.suites.suite

moniker = 'parameters'
nParameters

fudge.gnds.covariances.section module

A covarianceSuite is organized into sections, where each section contains either - a covariance matrix for a single reaction quantity (cross section, multiplicity, etc), or - a covariance matrix between two different quantities (off-diagonal block)

class fudge.gnds.covariances.section.columnData(link=None, root=None, path=None, label=None, relative=False, **attributes)[source]

Bases: xData.link.link

moniker = 'columnData'
class fudge.gnds.covariances.section.rowData(link=None, root=None, path=None, label=None, relative=False, **attributes)[source]

Bases: xData.link.link

moniker = 'rowData'
class fudge.gnds.covariances.section.section(label, rowData=None, columnData=None)[source]

Bases: fudge.gnds.suites.suite

A covarianceSuite contains sections, where each section represents either a self-covariance for one quantity, or a cross-covariance between two quantities

More generally, the covarianceSuite can be thought of as a single covariance matrix with all covariance data for a target/projectile. It is broken into sections, where each section holds a chunk of the full matrix.

Within each section, covariance data can take multiple forms: covarianceMatrix is the most common, but ‘summed’, ‘mixed’ are also possible.

Valid values in the forms dictionary are:
  • mixedForm
  • summedCovariance
  • covarianceMatrix
check(info)[source]

check each section

columnData = None

xData.link.link pointing to the corresponding data for the covariance column

crossTerm
fix(**kw)[source]

assemble some useful info, to be handed down to children’s check() functions

label = None

a str label that gets used on plots, etc.

moniker = 'section'
classmethod parseXMLNode(element, xPath, linkData)[source]

Translate <section> element from xml.

rowData = None

xData.link.link pointing to the corresponding data for the covariance row

toXMLList(indent='', **kwargs)[source]

fudge.gnds.covariances.summed module

class fudge.gnds.covariances.summed.summand(link=None, root=None, path=None, label=None, relative=False, **attributes)[source]

Bases: xData.link.link

moniker = 'summand'
class fudge.gnds.covariances.summed.summedCovariance(label, domainMin, domainMax, domainUnit='eV', pointerList=None, coefficients=None)[source]

Bases: xData.ancestry.ancestry

Covariance matrix stored as sum/difference of other matrices.

check(info)[source]
convertUnits(unitMap)[source]
domainMax = None

upper bound of row/column direction.

domainMin = None

lower bound of row/column direction.

fix(**kw)[source]
getColumnBounds(unit=None)[source]

Get the bounds of the column. If unit is specified, return the bounds in that unit.

getReferredCovariance(pointer)[source]
Parameters:pointer
Returns:
getRowBounds(unit=None)[source]

Get the bounds of the row. If unit is specified, return the bounds in that unit.

getUncertaintyVector(theData=None, relative=True)[source]

Combine all subsections into single uncertainty vector, converting to relative if requested.

Returns:an XYs1d instance
label
moniker = 'sum'
static parseXMLNode(element, xPath, linkData)[source]
plot(title=None, scalelabel=None, xlim=None, ylim=None, xlog=False, ylog=False)[source]
toAbsolute(rowData=None, colData=None)[source]

Rescales self (if it is a relative covariance) using XYs1d rowData and colData to convert self into an absolute covariance matrix.

Parameters:
  • rowData – an XYs1d instance containing data to rescale covariance in the “row direction”
  • colData – an XYs1d instance containing data to rescale covariance in the “col direction”

Note

If the column axis is set to ‘mirrorOtherAxis’, only rowData is needed. If neither rowData nor colData are specified, you’d better hope that the covariance is already absolute because this will throw an error.

Returns:a copy of self, but rescaled and with the type set to absoluteToken
toCorrelationMatrix()[source]
toCovarianceMatrix(label='composed')[source]

Sum the parts to construct the covariance matrix. Note, each part must be converted to an absolute covariance before summing.

toRelative(rowData=None, colData=None)[source]

Rescales self (if it is a absolute covariance) using XYs1d rowData and colData to convert self into a relative covariance matrix.

Parameters:
  • rowData – an XYs1d instance containing data to rescale covariance in the “row direction”
  • colData – an XYs1d instance containing data to rescale covariance in the “col direction”

Note

If the column axis is set to ‘mirrorOtherAxis’, only rowData is needed. If neither rowData nor colData are specified, you’d better hope that the covariance is already relative because this will throw an error.

Returns:a copy of self, but rescaled and with the type set to relativeToken
toXMLList(indent='', **kwargs)[source]
Parameters:
  • indent
  • kwargs
Returns:

fudge.gnds.covariances.tokens module

Define tokens to identify covariance elements in GNDS

Module contents