Serpenttools Documentation
Total Page:16
File Type:pdf, Size:1020Kb
serpentTools Documentation The serpentTools developer team Feb 20, 2020 CONTENTS: 1 Project Overview 3 2 Installation 7 3 Changelog 11 4 Examples 19 5 File-parsing API 77 6 Containers 97 7 Samplers 129 8 Settings 137 9 Miscellaneous 143 10 Variable Groups 147 11 Command Line Interface 161 12 Developer’s Guide 165 13 License 201 14 Developer Team 203 15 Glossary 205 16 Indices and tables 207 Bibliography 209 Index 211 i ii serpentTools Documentation A suite of parsers designed to make interacting with SERPENT [serpent] output files simple and flawless. The SERPENT Monte Carlo code is developed by VTT Technical Research Centre of Finland, Ltd. More information, including distribution and licensing of SERPENT can be found at http://montecarlo.vtt.fi The Annals of Nuclear Energy article should be cited for all work using SERPENT. Preferred citation for attribution Andrew Johnson, Dan Kotlyar, Gavin Ridley, Stefano Terlizzi, & Paul Romano. (2018, June 29). “serpent-tools: A collection of parsing tools and data containers to make interacting with SERPENT outputs easy, intuitive, and flawless.,”. CONTENTS: 1 serpentTools Documentation 2 CONTENTS: CHAPTER ONE PROJECT OVERVIEW The serpentTools package contains a variety of parsing utilities, each designed to read a specific output from the SERPENT Monte Carlo code [serpent]. Many of the parsing utilities store the outputs in custom container objects, while other store or return a collection of arrays. This page gives an overview of what files are currently supported, including links to examples and relevant documentation. Unless otherwise noted, all the files listed below can be read using serpentTools.read(). For example: >>> import serpentTools >>> res= serpentTools.read('my_resFile_res.m') would return a ResultsReader Some file-types have an additional reader that is capable of reading multiple files and computing actual uncertainties. These samplers are detailed in Samplers and listed under the supported files. Many of the readers have examples present in the Examples section. Each example is present as a Jupyter notebook at Github: examples. These can be used as a launching point for tutorials or for your own analysis. 1.1 Main output File • File Description: Primary output file for transport calculation - [input]_res.m • SERPENT wiki: result wiki • Primary Reader: ResultsReader • Example - notebook: ResultsReader • Example - manual: Results Reader 1.2 Depletion File • File Description: Output from burnup calculations, showing quantities for various materials - [input]_dep. m • SERPENT wiki: depletion wiki • Primary Reader: DepletionReader • Example - notebook: DepletionReader • Example - manual: Depletion Reader • Sampler - serpentTools.samplers.DepletionSampler 3 serpentTools Documentation 1.3 Detector/ Tally File • File Description: Output generated by creating detectors - [input]_det[N].m • SERPENT wiki: detector definition • Primary Reader: DetectorReader • Example - notebook: Detector • Example - manual: Detector Reader • Sampler - serpentTools.samplers.DetectorSampler 1.4 Sensitivity File • File Description: Output giving sensitivities of defined responses to perturbations - [input]_sens[N].m • SERPENT wiki: sensitivity wiki • Primary Reader: SensitivityReader • Example - notebook: Sensitivity • Example - manual: Sensitivity Reader 1.5 Branching Coefficient File • File Description: Selected homogenized group constants across a variety of defined branch states - [input]. coe • SERPENT wiki: branching wiki • Primary Reader: BranchingReader • Secondary Read function: serpentTools.BranchCollector.fromFile() • Example - notebook: Branching • Example - manual: Branching Reader 1.6 Micro-depletion File • File Description: • SERPENT wiki: microxs wiki • Primary Reader: MicroXSReader • Example - notebook: MicroXSReader • Example - manual: Micro cross section reader 4 Chapter 1. Project Overview serpentTools Documentation 1.7 Cross Section Plot File • File Description: Cross section data and energy grids for various reactions - [input]_xs0.m • SERPENT wiki: xsplot wiki_ • Primary Reader: XSPlotReader • Example - notebook: XSPlot • Example - manual: Cross Section Reader/Plotter 1.8 Depletion Matrix File • File Description: Data pertaining to depletion for a single burnable material at a single point in time - depmtx_[material-identifier]-s[step].m • Primary Reader: DepmtxReader • Example - notebook: DepletionMatrix • Example - manual: Depletion Matrix Reader 1.7. Cross Section Plot File 5 serpentTools Documentation 6 Chapter 1. Project Overview CHAPTER TWO INSTALLATION In order to properly install this package, you need a version of python that plays well with libraries like numpy and matplotlib. This is easy or less easy depending on your operating system, but we have a brief walk through at Obtaining a Python Distribution. 2.1 Terminal terminology Commands below that begin with $ must be run from the terminal containing your preferred python distribution, neglecting the $. Depending on operating system, this could be the normal terminal, or a modified prompt. See Obtaining a Python Distribution for more information if you are not sure. Commands that begin with >>> should be run inside of a python environment. The following would be a valid set of instructions to pass to your terminal, printing a very basic python command: $ python -m "print('hello world')" hello world $ python >>> print('hello world') hello world 2.2 Installing from pip pip is the easiest way to install the latest version of serpentTools. First, ensure that you have numpy installed, as this is one of the required packages that is tricky to install. You can check by opening up a your preferred terminal and executing $ python -c "import numpy" If this fails, please consult Obtaining a Python Distribution. Next, installation with pip can be completed with: $ python -m pip install --user --upgrade pip serpentTools This installs the dependencies of the package, the latest serpentTools release, and upgrades your version of pip along the way. When a new release is issued, run the command again to install the updated version. If you wish to install the development branch to get the latest updates as they happen, use the following command: $ python -m pip install -e git+https://www.github.com/CORE-GATECH-GROUP/serpent-tools. ,!git@develop#egg=serpentTools 7 serpentTools Documentation Note: Changes to the development branch may not always be back-compatible and may cause non-ideal outcomes. Be sure to check the Changelog before/after updating from the develop branch See also pip install from git 2.3 Installing from a Release 1. Download the source code for the latest release from GitHub releases as a .zip or .tar.gz compressed file. 2. Extract/decompress the contents somewhere convenient and memorable 3. Open your terminal and navigate to this directory: $ cd path/to/release 4. Install using our setup script: $ python setup.py install 5. Verify the install by running our test suite: $ python setup.py test 2.4 Installing via git The newest features are available on the develop branch before getting pushed to the master branch. We try to give decent notice when features are going to change via warning messages and our Changelog, but changes to the API and other functionality can occur across the develop branch. 1. Clone the repository and checkout the branch of your choosing. The default is develop: $ git clone https://github.com/CORE-GATECH-GROUP/serpent-tools.git $ cd serpent-tools $ git checkout master 2. Install using our setup script: $ python setup.py install 3. Verify the install by running our test suite: $ python setup.py test 8 Chapter 2. Installation serpentTools Documentation 2.5 Obtaining a Python Distribution Obtaining a version of python into which serpent-tools can be installed varies by operating system, with Win- dows requiring the most finesse. 2.5.1 Linux/Mac/Unix-like Operating Systems If you don’t have numpy installed, you will have to obtain it from your package manager or from pip: # ubuntu $ sudo apt-get install python-numpy # pip $ sudo pip install --upgrade numpy If you already have numpy, then the pip installtion process will take care of our other dependencies. 2.5.2 Windows The easiest and most painless way to obtain packages like numpy on Windows is with either the Anaconda or Mini- conda distributions. Each of these also includes the Anaconda Prompt which is a modified terminal that plays better with Python. The former comes with a few hundred packages, included most of the ones needed for this project, bundled for you. The latter is a very small distribution and requires you to install the packages you want via conda. Should you choose this route, then you need to launch the Anaconda Prompt and install with: $ conda install setuptools numpy matplotlib pyyaml This prompt is what you should use when following the instructions in in Installation. 2.5. Obtaining a Python Distribution 9 serpentTools Documentation 10 Chapter 2. Installation CHAPTER THREE CHANGELOG 3.1 0.9.2 • Officially support installing under Python 3.8 • Support for passing threshold values to hexagonal detector plots - #351 3.1.1 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. • Colorbars for mesh plots are placed next to their corresponding plot, rather than near the last drawn plot - #372 3.2 0.9.1 3.2.1 Bug Fixes • Sensitivity arrays generated with sens opt history 1 will no longer overwrite