class serpentTools.ResultsReader(filePath)

Parser responsible for reading and working with result files.

When inspecting keys of universes, it is preferable to use an attribute based approach rather than positional. For example:

>>> for key in res.universes:
...     break
>>> key.universe
# rather than
>>> key[0]

metadata

Dictionary with serpent descriptive variables as keys and the corresponding description. Within the _res.m file this data is printed multiple times, but contains the same description and thus is stored only once. e.g., ‘version’: ‘Serpent 2.1.29’

Type

dict

resdata

Dictionary with serpent time-dependent variables as keys and the corresponding values. The data is unique for each burnup step. Some variables also contain uncertainties. e.g., ‘absKeff’: [[9.91938E-01, 0.00145],[1.81729E-01, 0.00240]]

Type

dict

universes

Dictionary of universe identifiers UnivTuple and their corresponding HomogUniv objects. The keys describe a unique state: ‘universe’, burnup (MWd/kg), burnup index, time (days) (‘0’, 0.0, 0, 0.0). Burnup indexes are zero-indexed, meaning the first step is index 0.

Type

dict

Parameters

filePath (str) – path to the results file

Raises
• SerpentToolsException – Serpent version is not supported, No universes are found in the file, No results are collected, Corrupted results

• IOError – file is unexpectedly closes while reading:

__getitem__(key)

Retrieve an item from resdata only

Universes data like group constants should be pulled from universes directly with getUniv()

Parameters

key (str) – mixedCase variable name like "absKeff" that may exist in resdata

Returns

Requested quantity

Return type

numpy.ndarray

Raises

KeyError – If key does not exist in resdata

compare(other, lower=0, upper=10, sigma=2, verbosity=None)

Compare the results of this reader to another.

For values without uncertainties, the upper and lower arguments control what passes and what messages get raised. If a quantity in other is less than lower percent different that the same quantity on this object, consider this allowable and make no messages. Quantities that are greater than upper percent different will have a error messages printed and the comparison will return False, but continue. Quantities with difference between these ranges will have warning messages printed.

Parameters
• other – Other reader instance against which to compare. Must be a similar class as this one.

• lower (float or int) – Lower limit for relative tolerances in percent Differences below this will be considered allowable

• upper (float or int) – Upper limit for relative tolerances in percent. Differences above this will be considered failure and errors messages will be raised

• sigma (int) – Size of confidence interval to apply to quantities with uncertainties. Quantities that do not have overlapping confidence intervals will fail

• verbosity (None or str) – If given, update the verbosity just for this comparison.

Returns

True if the objects are in agreement with each other according to the parameters specified

Return type

bool

Raises
• TypeError – If other is not of the same class as this class nor a subclass of this class

• ValueError – If upper > lower, If sigma, lower, or upper are negative

compareMetadata(other, header=False)

Return True if the metadata (settings) are identical.

Parameters
Returns

Return type

bool

Raises

TypeError – If other is not of the same class as this class nor a subclass of this class

compareResults(other, lower=0, upper=10, sigma=2, header=False)

Compare the contents of the results dictionary

Parameters
• other (ResultsReader) – Class against which to compare

• lower (float or int) – Lower limit for relative tolerances in percent Differences below this will be considered allowable

• upper (float or int) – Upper limit for relative tolerances in percent. Differences above this will be considered failure and errors messages will be raised

• sigma (int) – Size of confidence interval to apply to quantities with uncertainties. Quantities that do not have overlapping confidence intervals will fail

• header (bool) – Print/log an info message about this comparison.

Returns

If the results data agree to given tolerances

Return type

bool

Raises

TypeError – If other is not of the same class as this class nor a subclass of this class

compareUniverses(other, lower=0, upper=10, sigma=2)

Compare the contents of the universes dictionary

Parameters
• other (ResultsReader) – Reader by which to compare

• lower (float or int) – Lower limit for relative tolerances in percent Differences below this will be considered allowable

• upper (float or int) – Upper limit for relative tolerances in percent. Differences above this will be considered failure and errors messages will be raised

• sigma (int) – Size of confidence interval to apply to quantities with uncertainties. Quantities that do not have overlapping confidence intervals will fail

Returns

If the contents of the universes agree to given tolerances

Return type

bool

Raises

TypeError – If other is not of the same class as this class nor a subclass of this class

get(key, default=None)

Retrieve an item from resdata or default

Parameters
• key (str) – mixedCase variable name that may or may not exist in resdata

• default (optional) – Object to be returned in key is not found

Returns

numpy.ndarray if key is found. Otherwise default is returned

Return type

object

getUniv(univ, burnup=None, index=None, timeDays=None)

Return a specific universe given the ID and time of interest

Parameters
• univ (str) – Unique str for the desired universe

• burnup (float or int, optional) – Burnup [MWd/kgU] of the desired universe

• timeDays (float or int, optional) – Time [days] of the desired universe

• index (int, optinal) – Point of interest in the burnup/days index

Returns

Requested universe

Return type

serpentTools.objects.HomogUniv

Raises
• KeyError – If the requested universe could not be found

• ValueError – If burnup, days and index are not given

plot(x, y=None, right=None, sigma=3, ax=None, legend=None, ncol=None, xlabel=True, ylabel=None, logx=False, logy=False, loglog=False, rightlabel=None)

Plot quantities over time

Parameters
• x (str or iterable of strings) – y is not given, then plot these quantites against burnup in days. Otherwise, plot this quantity as the x axis with same rules as if called by plot('burndays', x). Burnup options are {'burnup', 'days', 'burnDays', 'burnStep'}

• y (str or iterable of strings) – Quantity or quantities to plot. For all entries, only the first column, with respect to time, will be plotted. If the second column exists, and sigma is > 0, that column will be treated as the relative uncertainty for an errorbar plot. If a dictionary is passed, then plots will be labeled by the values of that dictionary, e.g. {'anaKeff': $k_{eff}$} would plot the first column of anaKeff with a LaTeX-ready $$k_{eff}$$

• right (str or iterable of strings) – Quantites to plot on the same plot, but with a different y axis and common x axis. Same rules apply as for arguments to y. Each label will modified to have a unique identifier indicating the plot uses the right y-axis

• ax (matplotlib.axes.Axes, optional) – Ax on which to plot the data. If not provided, create a new plot

• sigma (int) – Confidence interval to apply to errors. If not given or 0, no errors will be drawn.

• legend (bool or str or None) – Automatically label the plot. No legend will be made if a single item is plotted. Pass one of the following values to place the legend outside the plot: above, right

• ncol (int) – Integer number of columns to apply to the legend.

• xlabel (str or bool, optional) – Label to apply to the x-axis. If given as None, a label will be determined from other arguments. If not None but evaluates to False, do not label.

• ylabel (str or bool, optional) – Label to apply to the y-axis. If given as None, a label will be determined from other arguments. If not None but evaluates to False, do not label.

• logx (bool) – Apply a log scale to x axis.

• logy (bool or list or tuple) – Apply a log scale to the y-axis. If passing values to right, this can be a two item list or tuple, corresponding to log-scaling the left and right axis, respectively.

• loglog (bool) – Apply a log scale to both axes.

• rlabel (str or None) – If given and passing values to right, use this to label the y-axis.

Returns

If right is not given, then only the primary axes object is returned. Otherwise, the primary and the “right” axes object are returned

Return type

matplotlib.axes.Axes or tuple of axes

read()

The main method for reading that not only parses data, but also runs pre and post checks.

toMatlab(fileP, reconvert=True, append=True, format='5', longNames=True, compress=True, oned='row')

Write a binary MATLAB file from the contents of this reader

The group constant data will be presented as a multi-dimensional array, rather than a stacked 2D matrix. The axis are ordered burnup, universeIndex, group, value/uncertainty

The ordering of the universes can be found in the 'UNIVERSES' vector if reconvert==True, otherwise 'universes'. Each universe ID is present in this vector, ordered to their position along the second axis in the matrix.

Parameters
• fileP (str or file-like object) – Name of the file to write

• reconvert (bool) – If this evaluates to true, convert values back into their original form as they appear in the output file.

• append (bool) – If true and a file exists under output, append to that file. Otherwise the file will be overwritten

• format ({'5', '4'}) – Format of file to write. '5' for MATLAB 5 to 7.2, '4' for MATLAB 4

• longNames (bool) – If true, allow variable names to reach 63 characters, which works with MATLAB 7.6+. Otherwise, maximum length is 31 characters

• compress (bool) – If true, compress matrices on write

• oned ({'row', 'col'}:) – Write one-dimensional arrays as row vectors if oned=='row' (default), or column vectors

Examples

>>> import serpentTools
# convert to original variable names
>>> r.toMatlab('pwr_res.mat', True)
array([[0.991938, 0.00145 ],
[0.181729, 0.0024  ]])
>>> kinf.shape
(2, 1, 1, 2)
>>> kinf[:, 0, 0, 0]
array([0.993385, 0.181451])
>>> tot.shape
(2, 1, 2, 2)
>>> tot[:, 0, :, 0]
array([[0.496553, 1.21388 ],
[0.481875, 1.30993 ]])
# use the universes key to identify ordering of universes