.. _project-overview:

================
Project Overview
================

The ``serpentTools`` package contains a variety of parsing utilities,
each designed to read a specific output from the :term:`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
|read-full|. 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 :ref:`samplers` and listed under the supported files.

Many of the readers have examples present in the :ref:`ex-toctree`
section. Each example is present as a :term:`Jupyter notebook`
at `Github: examples <https://github.com/CORE-GATECH-GROUP/serpent-tools/tree/develop/examples>`_.
These  can be used as a launching point for tutorials or for
your own analysis.

.. _ov-results:

Main output File
================

* File Description: Primary output file for transport calculation 
  - ``[input]_res.m``
* SERPENT wiki: `result wiki`_
* Primary Reader: |ResultsReader|
* Example - notebook: :ex-notebook:`ResultsReader`
* Example - manual: :ref:`ex-results`

.. _ov-depletion:

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: :ex-notebook:`DepletionReader`
* Example - manual: :ref:`depletion-reader-ex`
* Sampler - :class:`serpentTools.samplers.DepletionSampler`

.. _ov-detector:

Detector/ Tally File
====================

* File Description: Output generated by creating detectors
  - ``[input]_det[N].m``
* SERPENT wiki: `detector definition`_
* Primary Reader: |DetectorReader|
* Example - notebook: :ex-notebook:`Detector`
* Example - manual: :ref:`detector-example`
* Sampler - :class:`serpentTools.samplers.DetectorSampler`

.. _ov-sensitivity:

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: :ex-notebook:`Sensitivity`
* Example - manual: :ref:`ex-sensitivity`
  
.. _ov-branching:

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: :func:`serpentTools.BranchCollector.fromFile`
* Example - notebook: :ex-notebook:`Branching`
* Example - manual: :ref:`branching-ex`

.. _ov-microxs:

Micro-depletion File
====================

* File Description: 
* SERPENT wiki: `microxs wiki`_
* Primary Reader: |MicroXSReader|
* Example - notebook: :ex-notebook:`MicroXSReader`
* Example - manual: :ref:`ex-microXS`

.. _ov-xsplot:

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: :ex-notebook:`XSPlot`
* Example - manual: :ref:`ex-xsplot`

.. _ov-depmtx:

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: :ex-notebook:`DepletionMatrix`
* Example - manual: :ref:`depmtx-reader-ex`

.. _depletion wiki: http://serpent.vtt.fi/mediawiki/index.php/Description_of_output_files#Burnup_calculation_output
.. _detector definition: http://serpent.vtt.fi/mediawiki/index.php/Input_syntax_manual#det_.28detector_definition.29
.. _microxs wiki: http://serpent.vtt.fi/mediawiki/index.php/Description_of_output_files#Micro_depletion_output
.. _result wiki: http://serpent.vtt.fi/mediawiki/index.php/Output_parameters
.. _sensitivity wiki: http://serpent.vtt.fi/mediawiki/index.php/Sensitivity_calculations
.. _branching wiki: http://serpent.vtt.fi/mediawiki/index.php/Automated_burnup_sequence
.. _xsplot wiki: http://serpent.vtt.fi/mediawiki/index.php/Input_syntax_manual#set_xsplot