openmc.Tally
- class openmc.Tally(tally_id=None, name='', scores=None, filters=None, nuclides=None, estimator=None, triggers=None, derivative=None)[source]
A tally defined by a set of scores that are accumulated for a list of nuclides given a set of filters.
- Parameters:
tally_id (int, optional) – Unique identifier for the tally. If none is specified, an identifier will automatically be assigned
name (str, optional) – Name of the tally. If not specified, the name is the empty string.
scores (list of str, optional) – List of scores, e.g. [‘flux’, ‘fission’]
filters (list of openmc.Filter, optional) – List of filters for the tally
nuclides (list of str, optional) – List of nuclides to score results for
estimator ({'analog', 'tracklength', 'collision'}, optional) – Type of estimator for the tally
triggers (list of openmc.Trigger, optional) – List of tally triggers
derivative (openmc.TallyDerivative, optional) – A material perturbation derivative to apply to all scores in the tally
- Variables:
id (int) – Unique identifier for the tally
name (str) – Name of the tally
multiply_density (bool) –
Whether reaction rates should be multiplied by atom density
Added in version 0.14.0.
filters (list of openmc.Filter) – List of specified filters for the tally
nuclides (list of str) – List of nuclides to score results for
scores (list of str) – List of defined scores, e.g. ‘flux’, ‘fission’, etc.
estimator ({'analog', 'tracklength', 'collision'}) – Type of estimator for the tally. If unset (None), OpenMC will automatically select an appropriate estimator based on the tally filters and scores with a preference for ‘tracklength’.
triggers (list of openmc.Trigger) – List of tally triggers
num_scores (int) – Total number of scores
num_filter_bins (int) – Total number of filter bins accounting for all filters
num_bins (int) – Total number of bins for the tally
shape (3-tuple of int) – The shape of the tally data array ordered as the number of filter bins, nuclide bins and score bins
filter_strides (list of int) – Stride in memory for each filter
num_realizations (int) – Total number of realizations
with_summary (bool) – Whether or not a Summary has been linked
sum (numpy.ndarray) – An array containing the sum of each independent realization for each bin
sum_sq (numpy.ndarray) – An array containing the sum of each independent realization squared for each bin
sum_third (numpy.ndarray) – An array containing the sum of each independent realization to the third power for each bin
sum_fourth (numpy.ndarray) – An array containing the sum of each independent realization to the fourth power for each bin
mean (numpy.ndarray) – An array containing the sample mean for each bin
std_dev (numpy.ndarray) – An array containing the sample standard deviation for each bin
vov (numpy.ndarray) – An array containing the variance of the variance for each tally bin
higher_moments (bool) – Whether or not the tally accumulates the sums third and fourth to compute higher-order moments
figure_of_merit (numpy.ndarray) –
An array containing the figure of merit for each bin
Added in version 0.15.3.
derived (bool) – Whether or not the tally is derived from one or more other tallies
sparse (bool) – Whether or not the tally uses SciPy’s LIL sparse matrix format for compressed data storage
derivative (openmc.TallyDerivative) – A material perturbation derivative to apply to all scores in the tally.
- add_results(statepoint: str | PathLike | StatePoint)[source]
Add results from the provided statepoint file to this tally instance
Added in version 0.15.1.
- Parameters:
statepoint (openmc.PathLike or openmc.StatePoint) – Statepoint used to update tally results
- average(scores=[], filter_type=None, filter_bins=[], nuclides=[], remove_filter=False)[source]
Vectorized average of tally data across scores, filter bins and/or nuclides using tally aggregation.
This method constructs a new tally to encapsulate the average of the data represented by the average of the data in this tally. The tally data average is determined by the scores, filter bins and nuclides specified in the input parameters.
- Parameters:
scores (list of str) – A list of one or more score strings to average across (e.g., [‘absorption’, ‘nu-fission’]; default is [])
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
filter_bins (Iterable of int or tuple) – A list of the filter bins corresponding to the filter_type parameter Each bin in the list is the integer ID for ‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to the energy boundaries of the bin of interest. Each bin is an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest.
nuclides (list of str) – A list of nuclide name strings to average across (e.g., [‘U235’, ‘U238’]; default is [])
remove_filter (bool) – If a filter is being averaged over, this bool indicates whether to remove that filter in the returned tally. Default is False.
- Returns:
A new tally which encapsulates the average of data requested.
- Return type:
- can_merge(other)[source]
Determine if another tally can be merged with this one
If results have been loaded from a statepoint, then tallies are only mergeable along one and only one of filter bins, nuclides or scores.
- Parameters:
other (openmc.Tally) – Tally to check for merging
- contains_filter(filter_type)[source]
Looks for a filter in the tally that matches a specified type
- Parameters:
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
- Returns:
filter_found – True if the tally contains a filter of the requested type; otherwise false
- Return type:
- diagonalize_filter(new_filter, filter_position=-1)[source]
Diagonalize the tally data array along a new axis of filter bins.
This is a helper method for the tally arithmetic methods. This method adds the new filter to a derived tally constructed copied from this one. The data in the derived tally arrays is “diagonalized” along the bins in the new filter. This functionality is used by the openmc.mgxs module; to transport-correct scattering matrices by subtracting a ‘scatter-P1’ reaction rate tally with an energy filter from a ‘scatter’ reaction rate tally with both energy and energyout filters.
- Parameters:
- Returns:
A new derived Tally with data diagonalized along the new filter.
- Return type:
- static ensure_results(f)[source]
- A decorator to be applied to any method that might use tally results.
Results will be loaded if appropriate based on the tally properties.
- Parameters:
function (f) – Tally method to wrap
- Returns:
Wrapped function that reads tally results before calling the methodif necessary
- Return type:
function
- find_filter(filter_type)[source]
Return a filter in the tally that matches a specified type
- Parameters:
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
- Returns:
filter_found – Filter from this tally with matching type, or None if no matching Filter is found
- Return type:
- Raises:
ValueError – If no matching Filter is found
- classmethod from_xml_element(elem, **kwargs)[source]
Generate tally object from an XML element
Added in version 0.13.0.
- Parameters:
elem (lxml.etree._Element) – XML element
- Returns:
Tally object
- Return type:
- get_filter_indices(filters=[], filter_bins=[])[source]
Get indices into the filter axis of this tally’s data arrays.
This is a helper method for the Tally.get_values(…) method to extract tally data. This method returns the indices into the filter axis of the tally’s data array (axis=0) for particular combinations of filters and their corresponding bins.
- Parameters:
filters (Iterable of openmc.FilterMeta) – An iterable of filter types (e.g., [MeshFilter, EnergyFilter]; default is [])
filter_bins (Iterable of tuple) – A list of tuples of filter bins corresponding to the filter_types parameter (e.g., [(1,), ((0., 0.625e-6),)]; default is []). Each tuple contains bins for the corresponding filter type in the filters parameter. Each bin is an integer ID for Material-, Surface-, Cell-, Cellborn-, and Universe- Filters. Each bin is an integer for the cell instance ID for DistribcellFilters. Each bin is a 2-tuple of floats for Energy- and Energyout- Filters corresponding to the energy boundaries of the bin of interest. The bin is an (x,y,z) 3-tuple for MeshFilters corresponding to the mesh cell of interest. The order of the bins in the list must correspond to the filter_types parameter.
- Returns:
A NumPy array of the filter indices
- Return type:
- get_nuclide_index(nuclide)[source]
Returns the index in the Tally’s results array for a Nuclide bin
- get_nuclide_indices(nuclides)[source]
Get indices into the nuclide axis of this tally’s data arrays.
This is a helper method for the Tally.get_values(…) method to extract tally data. This method returns the indices into the nuclide axis of the tally’s data array (axis=1) for one or more nuclides.
- get_pandas_dataframe(filters=True, nuclides=True, scores=True, derivative=True, paths=True, float_format='{:.2e}')[source]
Build a Pandas DataFrame for the Tally data.
This method constructs a Pandas DataFrame object for the Tally data with columns annotated by filter, nuclide and score bin information.
This capability has been tested for Pandas >=0.13.1. However, it is recommended to use v0.16 or newer versions of Pandas since this method uses the Multi-index Pandas feature.
- Parameters:
filters (bool) – Include columns with filter bin information (default is True).
nuclides (bool) – Include columns with nuclide bin information (default is True).
scores (bool) – Include columns with score bin information (default is True).
derivative (bool) – Include columns with differential tally info (default is True).
paths (bool, optional) – Construct columns for distribcell tally filters (default is True). The geometric information in the Summary object is embedded into a Multi-index column with a geometric “path” to each distribcell instance.
float_format (str) – All floats in the DataFrame will be formatted using the given format string before printing.
- Returns:
A Pandas DataFrame with each column annotated by filter, nuclide and score bin information (if these parameters are True), and the mean and standard deviation of the Tally’s data.
- Return type:
- Raises:
KeyError – When this method is called before the Tally is populated with data
- get_reshaped_data(value='mean', expand_dims=False)[source]
Returns an array of tally data with one dimension per filter.
The tally data in OpenMC is stored as a 3D array with the dimensions corresponding to filters, nuclides and scores. As a result, tally data can be opaque for a user to directly index (i.e., without use of
openmc.Tally.get_values()) since one must know how to properly use the number of bins and strides for each filter to index into the first (filter) dimension.This builds and returns a reshaped version of the tally data array with unique dimensions corresponding to each tally filter. For example, suppose this tally has arrays of data with shape (30,5,5) corresponding to two filters (2 and 15 bins, respectively), five nuclides and five scores. This method will return a version of the data array with the with a new shape of (2,15,5,5) such that the first two dimensions correspond directly to the two filters with two and fifteen bins. If expand_dims is True and our filter above with 15 bins is an instance of
openmc.MeshFilterwith a shape of (3,5,1). The resulting tally data array will have a new shape of (2,3,5,1,5,5).- Parameters:
value (str) – A string for the type of value to return - ‘mean’ (default), ‘std_dev’, ‘rel_err’, ‘sum’, or ‘sum_sq’ are accepted
expand_dims (bool, optional) –
Whether or not to expand the dimensions of filters with multiple dimensions. This will result in more than one dimension per filter for the returned data array.
Added in version 0.13.3.
- Returns:
The tally data array indexed by filters, nuclides and scores.
- Return type:
- get_score_index(score)[source]
Returns the index in the Tally’s results array for a score bin
- Parameters:
score (str) – The score string (e.g., ‘absorption’, ‘nu-fission’)
- Returns:
score_index – The index in the Tally data array for this score.
- Return type:
- Raises:
ValueError – When the argument passed to the ‘score’ parameter cannot be found in the Tally.
- get_score_indices(scores)[source]
Get indices into the score axis of this tally’s data arrays.
This is a helper method for the Tally.get_values(…) method to extract tally data. This method returns the indices into the score axis of the tally’s data array (axis=2) for one or more scores.
- get_slice(scores=[], filters=[], filter_bins=[], nuclides=[], squeeze=False)[source]
Build a sliced tally for the specified filters, scores and nuclides.
This method constructs a new tally to encapsulate a subset of the data represented by this tally. The subset of data to include in the tally slice is determined by the scores, filters and nuclides specified in the input parameters.
- Parameters:
scores (list of str) – A list of one or more score strings (e.g., [‘absorption’, ‘nu-fission’]
filters (Iterable of openmc.FilterMeta) – An iterable of filter types (e.g., [MeshFilter, EnergyFilter])
filter_bins (list of Iterables) – A list of iterables of filter bins corresponding to the specified filter types (e.g., [(1,), ((0., 0.625e-6),)]). Each iterable contains bins to slice for the corresponding filter type in the filters parameter. Each bin is the integer ID for ‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to the energy boundaries of the bin of interest. The bin is an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest. The order of the bins in the list must correspond to the filters argument.
nuclides (list of str) – A list of nuclide name strings (e.g., [‘U235’, ‘U238’])
squeeze (bool) – Whether to remove filters with only a single bin in the sliced tally
- Returns:
A new tally which encapsulates the subset of data requested in the order each filter, nuclide and score is listed in the parameters.
- Return type:
- Raises:
ValueError – When this method is called before the Tally is populated with data.
- get_values(scores=[], filters=[], filter_bins=[], nuclides=[], value='mean')[source]
Returns one or more tallied values given a list of scores, filters, filter bins and nuclides.
This method constructs a 3D NumPy array for the requested Tally data indexed by filter bin, nuclide bin, and score index. The method will order the data in the array as specified in the parameter lists.
- Parameters:
scores (list of str) – A list of one or more score strings (e.g., [‘absorption’, ‘nu-fission’]; default is [])
filters (Iterable of openmc.FilterMeta) – An iterable of filter types (e.g., [MeshFilter, EnergyFilter]; default is [])
filter_bins (list of Iterables) – A list of tuples of filter bins corresponding to the filter_types parameter (e.g., [(1,), ((0., 0.625e-6),)]; default is []). Each tuple contains bins for the corresponding filter type in the filters parameter. Each bins is the integer ID for ‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to the energy boundaries of the bin of interest. The bin is an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest. The order of the bins in the list must correspond to the filter_types parameter.
nuclides (list of str) – A list of nuclide name strings (e.g., [‘U235’, ‘U238’]; default is [])
value (str) – A string for the type of value to return - ‘mean’ (default), ‘std_dev’, ‘rel_err’, ‘sum’, or ‘sum_sq’ are accepted
- Returns:
A scalar or NumPy array of the Tally data indexed in the order each filter, nuclide and score is listed in the parameters.
- Return type:
- Raises:
ValueError – When this method is called before the Tally is populated with data, or the input parameters do not correspond to the Tally’s attributes, e.g., if the score(s) do not match those in the Tally.
- hybrid_product(other, binary_op, filter_product=None, nuclide_product=None, score_product=None)[source]
Combines filters, scores and nuclides with another tally.
This is a helper method for the tally arithmetic operator overloaded methods. It is called a “hybrid product” because it performs a combination of tensor (or Kronecker) and entrywise (or Hadamard) products. The filters from both tallies are combined using an entrywise (or Hadamard) product on matching filters. By default, if all nuclides are identical in the two tallies, the entrywise product is performed across nuclides; else the tensor product is performed. By default, if all scores are identical in the two tallies, the entrywise product is performed across scores; else the tensor product is performed. Users can also call the method explicitly and specify the desired product.
- Parameters:
other (openmc.Tally) – The tally on the right hand side of the hybrid product
binary_op ({'+', '-', '*', '/', '^'}) – The binary operation in the hybrid product
filter_product ({'tensor', 'entrywise' or None}) – The type of product (tensor or entrywise) to be performed between filter data. The default is the entrywise product. Currently only the entrywise product is supported since a tally cannot contain two of the same filter.
nuclide_product ({'tensor', 'entrywise' or None}) – The type of product (tensor or entrywise) to be performed between nuclide data. The default is the entrywise product if all nuclides between the two tallies are the same; otherwise the default is the tensor product.
score_product ({'tensor', 'entrywise' or None}) – The type of product (tensor or entrywise) to be performed between score data. The default is the entrywise product if all scores between the two tallies are the same; otherwise the default is the tensor product.
- Returns:
A new Tally that is the hybrid product with this one.
- Return type:
- Raises:
ValueError – When this method is called before the other tally is populated with data.
- kurtosis(fisher=True, bias=False) ndarray[source]
Return the sample kurtosis of each tally bin.
This method computes and returns the sample kurtosis using either Pearson’s or Fisher’s definition, with or without finite-sample bias correction. The value returned depends on the bias and fisher arguments as follows:
bias=True, fisher=False: Returns \(b_2\) (Pearson’s kurtosis) This is the raw fourth standardized moment: \(m_4/m_2^2\). For a normal distribution, \(b_2\approx 3\).
bias=True, fisher=True: Returns \(g_2\) (excess kurtosis) This is \(b_2 - 3\), centered at 0 for normal distributions. Positive values indicate heavier tails, negative values lighter tails.
bias=False, fisher=True (default): Returns \(G_2\) (adjusted excess kurtosis). This applies finite-sample bias correction to \(g_2\). This is the recommended estimator for statistical inference.
bias=False, fisher=False: Returns bias-corrected Pearson’s kurtosis. This is \(G_2 + 3\).
- Parameters:
fisher (bool, optional) – If True (default), Fisher’s definition is used (excess kurtosis). If False, Pearson’s definition is used.
bias (bool, optional) – If False (default), calculations are corrected for statistical bias using finite-sample adjustments. If True, calculations use the biased estimator (population formulas).
- Returns:
The kurtosis of each tally bin
- Return type:
- kurtosistest(alternative: str = 'two-sided')[source]
Perform D’Agostino and Pearson’s test for kurtosis.
This method tests the null hypothesis that the kurtosis of the population that the sample was drawn from is the same as that of a corresponding normal distribution.
- Parameters:
alternative ({'two-sided', 'less', 'greater'}, optional) –
Defines the alternative hypothesis. Default is ‘two-sided’. The following options are available:
’two-sided’: the kurtosis of the distribution is different from that of the normal distribution
’less’: the kurtosis of the distribution is less than that of the normal distribution
’greater’: the kurtosis of the distribution is greater than that of the normal distribution
- Returns:
statistic (np.ndarray) – The computed z-score for the kurtosis test for each tally bin
pvalue (np.ndarray) – The p-value for the hypothesis test for each tally bin
- Raises:
ValueError – If the number of realizations is less than 20, or if an invalid alternative hypothesis is specified.
Notes
This test is based on D’Agostino and Pearson’s test. The test is typically recommended for at least 20 realizations to produce valid results.
- merge(other)[source]
Merge another tally with this one
If results have been loaded from a statepoint, then tallies are only mergeable along one and only one of filter bins, nuclides or scores.
- Parameters:
other (openmc.Tally) – Tally to merge with this one
- Returns:
merged_tally – Merged tallies
- Return type:
- normaltest(alternative: str = 'two-sided')[source]
Perform D’Agostino and Pearson’s omnibus test for normality.
This method tests the null hypothesis that a sample comes from a normal distribution. It combines skewness and kurtosis to produce an omnibus test of normality.
- Parameters:
alternative ({'two-sided', 'less', 'greater'}, optional) –
Defines the alternative hypothesis used for the component skewness and kurtosis tests. Default is ‘two-sided’. The following options are available:
’two-sided’: the distribution is different from normal
’less’: used for the component tests
’greater’: used for the component tests
- Returns:
statistic (np.ndarray) – The computed z-score for the normality test for each tally bin
pvalue (np.ndarray) – The p-value for the hypothesis test for each tally bin
- Raises:
ValueError – If the number of realizations is less than 20, or if an invalid alternative hypothesis is specified.
Notes
This test combines a test for skewness and a test for kurtosis to produce an omnibus test. The test statistic is:
\[K^2 = Z_1^2 + Z_2^2\]where \(Z_1\) is the z-score from the skewness test and \(Z_2\) is the z-score from the kurtosis test. This statistic follows a chi-square distribution with 2 degrees of freedom.
The test requires at least 20 realizations to produce valid results.
- remove_filter(old_filter)[source]
Remove a filter from the tally
- Parameters:
old_filter (openmc.Filter) – Filter to remove
- remove_nuclide(nuclide)[source]
Remove a nuclide from the tally
- Parameters:
nuclide (str) – Nuclide to remove
- remove_score(score)[source]
Remove a score from the tally
- Parameters:
score (str) – Score to remove
- skew(bias=False) ndarray[source]
Return the sample skewness of each tally bin.
This method computes and returns the unadjusted or adjusted Fisher-Pearson coefficient of skewness.
- skewtest(alternative: str = 'two-sided')[source]
Perform D’Agostino and Pearson’s test for skewness.
This method tests the null hypothesis that the skewness of the population that the sample was drawn from is the same as that of a corresponding normal distribution.
- Parameters:
alternative ({'two-sided', 'less', 'greater'}, optional) –
Defines the alternative hypothesis. The following options are available:
’two-sided’: the skewness of the distribution is different from that of the normal distribution (i.e., non-zero)
’less’: the skewness of the distribution is less than that of the normal distribution
’greater’: the skewness of the distribution is greater than that of the normal distribution
- Returns:
statistic (np.ndarray) – The computed z-score for the skewness test for each tally bin
pvalue (np.ndarray) – The p-value for the hypothesis test for each tally bin
Notes
This test is based on D’Agostino and Pearson’s test. The test requires at least 8 realizations to produce valid results.
- summation(scores=[], filter_type=None, filter_bins=[], nuclides=[], remove_filter=False)[source]
Vectorized sum of tally data across scores, filter bins and/or nuclides using tally aggregation.
This method constructs a new tally to encapsulate the sum of the data represented by the summation of the data in this tally. The tally data sum is determined by the scores, filter bins and nuclides specified in the input parameters.
- Parameters:
scores (list of str) – A list of one or more score strings to sum across (e.g., [‘absorption’, ‘nu-fission’]; default is [])
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
filter_bins (Iterable of int or tuple) – A list of the filter bins corresponding to the filter_type parameter Each bin in the list is the integer ID for ‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to the energy boundaries of the bin of interest. Each bin is an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest.
nuclides (list of str) – A list of nuclide name strings to sum across (e.g., [‘U235’, ‘U238’]; default is [])
remove_filter (bool) – If a filter is being summed over, this bool indicates whether to remove that filter in the returned tally. Default is False.
- Returns:
A new tally which encapsulates the sum of data requested.
- Return type: