Development will be limited to bug fixes for future 0.9.x releases. Release 0.10.0 will introduce new and improved parsers and containers alongside existing structures. For more information, see Updated Data Model


  • Data files used for testing and examples are now found using the environment variable SERPENT_TOOLS_DATA and are no longer distributed with the package.

  • Installation also provides a serpentTools executable that can be used to access the Command Line Interface


Bug Fixes

  • Support xsplot files with branching fractions - #387, #388

Pending Deprecations


  • Officially support installing under Python 3.8

  • Support for passing threshold values to hexagonal detector plots - #351

Bug Fixes

  • Detector reader can handle sequential detectors with very similar names - #374.

  • serpentTools doesn’t make any modifications to the logging state, other than introducing package-wide logger - #380

  • Colorbars for mesh plots are placed next to their corresponding plot, rather than near the last drawn plot - #372


Bug Fixes

  • Sensitivity arrays generated with sens opt history 1 will no longer overwrite the primary result arrays - #366. These arrays are not currently stored - #367


  • Python 2 support has been dropped.

  • Add support for installing and testing against Python 3.7


  • Use six>=1.13.0

  • Use yaml>=5.1.1

Bug Fixes



Serpent 1 detectors are no longer supported - #327. Version 0.9.0 will remove support for python 2 - #328

  • Better handling of discontinuity factors - #329

  • HomogUniv objects no longer automatically convert data to arrays

  • Serpent 2.1.31 is the default version for serpentVersion setting

  • Detectors and related subclasses are now standalone classes that can be imported as serpentTools.Detector - #341

  • BranchContainer now inherits from dict - #344

  • Keys for universes in ResultsReader.universes are UnivTuple

  • Keys for microscopic cross sections in MicroXSReader.xsVal and MicroXSReader.xsUnc are MicroXSTuple

  • Spread plots for sampled detector and depletion containers allow changing how the mean data and sampled data are plotted by passing dictionary of matplotlib commands, e.g. meanKwargs={"c": "r", "marker": x"} would plot the mean data in red with crosses as markers.

Bug Fixes

  • Burnup and days are properly set on homogenized universes when reading a result file with multiple universes but no burnup - #346

  • Modifications made to detector tally data will be reflected in later plots - #337, #341

  • Variable groups for version 2.1.31 are properly expanded - #347

Incompatible API Changes


  • Add __getitem__() and __setitem__() convenience methods for accessing expected values on HomogUniv objects

  • Add thresh argument to Detector meshPlot where only data greater than thresh is plotted.

  • Mitigate pending deprecated imports from collections - #313

  • Increase required version of yaml to 5.1.1

  • Include SERPENT 2.1.31 support in serpentVersion setting

Bug fixes

Pending Deprecations

  • Keys to BranchedUniv objects stored in serpentTools.xs.BranchCollector.universes are stored as strings, rather than integers, e.g. 0 is replaced with "0". A workaround is in-place, but will be removed in future versions.

  • SERPENT 1 style detectors with additional score column will not be supported starting at version 0.8.0.


Incompatible API Changes

  • HomogUniv objects are now stored on ResultsReader with zero-based indexing for burnup. The previous first value of burnup step was one. All burnup indices are now decreased by one. Similarly, if no burnup was present in the file, the values of burnup and days for all universes is zero - #288

  • When reading Detectors with a single tally, the value of tallies, errors, and scores are stored as floats, rather than numpy arrays - #289


Bug Fixes

  • BranchingReader is now capable of reading .coe files with uncertainties - #272

  • Fixed a bug that caused some plots not to return the axes object of the plot - #297

  • HomogUniv plots are plotted against energy group when no group structure can be determined, and now labeled as such - #299

  • Removed a non-zero exit code from a successful use of the Random Seed Generation command line command - #300

  • ResultsReader can process files with assembly discontinuity factors (ADFs) - #305


  • Data files are bundled in source distribution

  • CLI interface for converting some output files to matlab files - Conversion to Binary .mat files

  • Add module for converting objects to other data types. Currently a general function for converting toMatlab()

  • DetectorReader and Detector objects can be written to MATLAB files using

  • ResultsReader can plot data using plot()

  • Experimental BranchCollector for collecting group constants from coefficient files. Collects group constants in in multi-dimensional matrices according to perturbations, universes, and burnup.

  • Plotting routines now use attach to the active plot or generate a new plot figure if ax argument not given - #267

  • BranchingReader can read coefficient files with uncertainties - #270


The API for the BranchCollector may be subject to change through revisions until 0.7.0

Pending Deprecations

  • saveAsMatlab() in favor of with:

    >>> from import toMatlab
    >>> toMatlab(depR)
  • Depletion plot routines will no longer accept timePoints arguments, instead plotting against all points in time



  • #174 - Added parent object BaseObject with basic comparison method from which all objects inherit. Comparison method contains upper and lower bounds for values w/o uncertainties, #191

  • #196 - Add comparison methods for ResultsReader and HomogUniv objects

  • #228 - Add comparison methods for DetectorReader and Detector objects

  • #236 - Add comparison methods for DepletionReader and DepletedMaterial objects

  • #241 - Fix a bug in the CLI that rendered the ability to generate files with unique random seeds. python -m serpentTools seed <input> <N> can now be properly used.

  • #249 - Better sparse support for depletion matrix, depmtx files with a DepmtxReader

  • #252 - Better axis and colorbar labeling for Detector mesh plots

  • #254 - Better plotting of single concentrations with DepmtxReader

  • #255 - DepletionReader can capture material with underscores now!


  • depmtx() is deprecated in favor of either readDepmtx() or the class-based DepmtxReader


  • #239 - Update python dependencies to continue use of python 2


  • #221 - Expanded utils module to better assist developers

  • #227 - Better documentation of our Command Line Interface. Better documentation and testing of functions for generating input files with unique random seeds - serpentTools.seed

  • #229 - serpentTools.SensitivityReader.plot() now respects the option to not set x nor y labels.

  • #231 - ResultsReader objects can now read files that do not contain group constant data. The setting results-expectGcu should be used to inform the reader that no group constant data is anticipated


    This setting was removed in 0.8.0 and in #324


API Changes


  • #180 - Add capability to pass isotope zzaaai for getValues() and associated plot routines

  • #187 - Import all readers and samplers from the main package:

    >>> from serpentTools import ResultsReader
    >>> from serpentTools import DetectorSampler
  • #189 - Support for reading Detectors with hexagonal, cylindrical, and spherical meshes.

API Changes

  • zzaaai data is stored on zai as a list of integers, not strings


  • #131 Updated variable groups between 2.1.29 and 2.1.30 - include poison cross section, kinetic parameters, six factor formula (2.1.30 exclusive), and minor differences

  • #141 - Setting xs.reshapeScatter can be used to reshape scatter matrices on HomogUniv objects to square matrices

  • #145 - hasData() added to check if HomogUniv objects have any data stored on them

  • #146 - HomogUniv object stores group structure on the object. New dictionaries for storing group constant data that is not INF nor B1 - gc and gcUnc

  • #130 Added the ability to read results file

  • #149 - Add the ability to read sensitivity files

  • #161 - Add the utils module

  • #165 - Add the serpentTools.objects.HomogUniv.plot() method

API Changes


  • Variable group xs-yields is removed. Use poisons instead

  • Branches of a single name are only be accessible through branches['nom'], not branches[('nom'), ] as per #114


  • #95 Add xsplot file reader - XSPlotReader

  • #121 Samplers will raise more warnings/errors if no files are loaded from * wildcards

  • #122 Better Detector labeling

  • #135 Added instructions for better converting Jupyter notebooks to .rst files. Plotting guidelines


  • #118 - Support for SERPENT 2.1.30

  • #119 - SampledDepletedMaterial now respects the value of xUnits - #120

  • #114 - Standalone branches in the coefficient files are stored and accessed using a single string, rather than a single-entry tuple branches['myBranch'] vs. branches[('myBranch', )]



  • #82 - Command line interface and some sub-commands

  • #88 - Pre- and post-check methods for readers

  • #93 - Detector and Depletion Samplers

  • #96 - Better mesh plotting for Detector

  • #99 - Negative universe burnup with branching reader - #100

  • serpentTools.objects.Detector.indexes are now zero-indexed

  • The PDF manual is no longer tracked in this repository