.. toctree::
   :maxdepth: 1
   :caption: Overview
   :hidden:

   overview/philosophy
   overview/mapping_endf_recipes
   overview/endf_navigation

.. toctree::
   :maxdepth: 1
   :caption: Tutorials & Guides
   :hidden:

   guide/getting_started
   guide/python_and_cpp_parser
   guide/command_line_interface
   guide/reading_writing_endf
   guide/multimaterial_files
   guide/endf_format_validation
   guide/comparing_endf_files
   guide/format_translation
   guide/endf_plumbing
   guide/creation_endf_scratch
   guide/pendf_and_format_flavors
   guide/format_extensions
   guide/working_with_legacy_formats
   guide/high_level_functionality
   guide/perfect_precision
   guide/arrays_as_list
   guide/accelerated_parsing_and_writing

.. toctree::
   :maxdepth: 1
   :caption: Reference
   :hidden:

   reference/modules
   reference/classes
   reference/endf6_recipes
   reference/related_software


.. _ENDF-6 format: https://www.nndc.bnl.gov/endfdocs/ENDF-102-2023.pdf

Welcome to endf-parserpy's documentation!
=========================================

endf-parserpy is a Python package for reading
and writing `ENDF <https://www.nndc.bnl.gov/endfdocs/ENDF-102-2023.pdf>`_ files.
This functionality in combination with Python's
powerful facilities for data handling enables you to
perform various actions on ENDF files, such as:

- Easily access any information
- Modify, delete and insert data
- Perform format validation
- Convert from and to other file formats, such as JSON
- Merge data from various ENDF-6 files into a single one
- Read and write files that bundle several materials
- Compare ENDF-6 files with meaningful reporting on differences
- Construct ENDF-6 files from scratch


Many of these actions can be performed via the command line.
The support for the `ENDF-6 format`_ is comprehensive and
some special NJOY output formats are also supported.
The package has been tested on the various sublibraries
of the major nuclear data libraries, such as
`ENDF/B <https://www.nndc.bnl.gov/endf/>`_,
`JEFF <https://www.oecd-nea.org/dbdata/jeff/>`_,
and `JENDL <https://wwwndc.jaea.go.jp/jendl/jendl.html>`_.
Files that bundle several materials, including PENDF
tapes, are supported as well; see the guide on
:doc:`multi-material files <guide/multimaterial_files>`.


Install endf-parserpy
---------------------

.. code:: bash

   python -m pip install endf-parserpy --upgrade


.. note::

   :ref:`Accelerated parsing <accelerated_parsing_and_writing_sec>`
   relies on compiled C++ code.
   If a suitable binary wheel isn't available for your platform,
   an attempt will be made to compile the C++ source files during
   installation, which can take up to ten minutes.
   The default optimization level aims to strike a balance between
   compile time and parsing speed. Power users can alter the
   optimization flag by setting the ``INSTALL_ENDF_PARSERPY_CPP_OPTIM``
   environment variable before installation. For instance, under Linux and macOS,
   where the default compiler is GNU C++, you could disable all optimizations by:

   .. code:: bash

      export INSTALL_ENDF_PARSERPY_CPP_OPTIM="-O0"

   Under Windows (assuming Microsoft Visual C++), you can do:

   .. code:: bash

      set INSTALL_ENDF_PARSERPY_CPP_OPTIM="/Od"

   If you want to disable the compilation of the C++ modules entirely,
   you can set the environment variable ``INSTALL_ENDF_PARSERPY_CPP``
   to ``no`` before executing the ``pip install`` command.


.. note::

   The :doc:`multi-material file interface <guide/multimaterial_files>`
   indexes tapes with a structural scan that is faster when
   `NumPy <https://numpy.org/>`_ is available. To install this
   optional dependency, add the ``fast`` extra:

   .. code:: bash

      python -m pip install "endf-parserpy[fast]"

   Without NumPy a pure-Python fallback is used, so the
   dependency is not required.


.. note::

   The package is still evolving and will be
   extended with convenience functions to enhance
   the user experience. You can always check for updated versions
   `on PyPI <https://pypi.org/project/endf-parserpy/>`_.


Resources
---------

- :doc:`overview/philosophy`
- :doc:`overview/mapping_endf_recipes`
- :doc:`overview/endf_navigation`
- Guides

  - :doc:`guide/getting_started`
  - :doc:`guide/python_and_cpp_parser`
  - :doc:`guide/command_line_interface`
  - :doc:`guide/reading_writing_endf`
  - :doc:`guide/multimaterial_files`
  - :doc:`guide/endf_format_validation`
  - :doc:`guide/comparing_endf_files`
  - :doc:`guide/format_translation`
  - :doc:`guide/endf_plumbing`
  - :doc:`guide/creation_endf_scratch`
  - :doc:`guide/pendf_and_format_flavors`
  - :doc:`guide/format_extensions`
  - :doc:`guide/working_with_legacy_formats`
  - :doc:`guide/high_level_functionality`
  - :doc:`guide/perfect_precision`
  - :doc:`guide/arrays_as_list`
  - :doc:`guide/accelerated_parsing_and_writing`

- Reference

  - :doc:`reference/modules`
  - :doc:`reference/classes`
  - :doc:`reference/endf6_recipes`
  - :doc:`reference/related_software`