<commit_before>.. _usersguide_troubleshoot:

===============
Troubleshooting
===============

-------------------------
Problems with Compilation
-------------------------

If you are experiencing problems trying to compile OpenMC, first check if the
error you are receiving is among the following options.

-------------------------
Problems with Simulations
-------------------------

Segmentation Fault
******************

A segmentation fault occurs when the program tries to access a variable in
memory that was outside the memory allocated for the program. The best way to
debug a segmentation fault is to re-compile OpenMC with debug options turned
on. Create a new build directory and type the following commands:

.. code-block:: sh

    mkdir build-debug && cd build-debug
    cmake -Ddebug=on /path/to/openmc
    make

Now when you re-run your problem, it should report exactly where the program
failed. If after reading the debug output, you are still unsure why the program
failed, post a message on the `OpenMC Discourse Forum
<https://openmc.discourse.group/>`_.

ERROR: No cross_sections.xml file was specified in settings.xml or in the OPENMC_CROSS_SECTIONS environment variable.
*********************************************************************************************************************

OpenMC needs to know where to find cross section data for each nuclide.
Information on what data is available and in what files is summarized in a
cross_sections.xml file. You need to tell OpenMC where to find the
cross_sections.xml file either with the :ref:`cross_sections` in settings.xml or
with the :envvar:`OPENMC_CROSS_SECTIONS` environment variable. It is recommended
to add a line in your ``.profile`` or ``.bash_profile`` setting the
:envvar:`OPENMC_CROSS_SECTIONS` environment variable.

RuntimeError: Failed to open HDF5 file with mode 'w': summary.h5
****************************************************************

This often occurs when working with the Python API and executing multiple OpenMC
runs in a script. If an :class:`openmc.StatePoint` is open in the Python interpreter,
the file handle of the statpoint file as well as the linked `summary.h5` file will
be unavailable for writing, causing this error to appear. To avoid the situation,
it is recommended that data be extracted from statepoint files in a context manager:

.. code-block:: python

    with openmc.StatePoint('statepoint.10.h5') as sp:
        k_eff = sp.k_combined

or that the :meth:`StatePoint.close` method is called before executing a subsequent
OpenMC run.

Geometry Debugging
******************

Overlapping Cells<commit_msg>Apply suggestions from code review<commit_after>.. _usersguide_troubleshoot:

===============
Troubleshooting
===============

-------------------------
Problems with Compilation
-------------------------

If you are experiencing problems trying to compile OpenMC, first check if the
error you are receiving is among the following options.

-------------------------
Problems with Simulations
-------------------------

Segmentation Fault
******************

A segmentation fault occurs when the program tries to access a variable in
memory that was outside the memory allocated for the program. The best way to
debug a segmentation fault is to re-compile OpenMC with debug options turned
on. Create a new build directory and type the following commands:

.. code-block:: sh

    mkdir build-debug && cd build-debug
    cmake -Ddebug=on /path/to/openmc
    make

Now when you re-run your problem, it should report exactly where the program
failed. If after reading the debug output, you are still unsure why the program
failed, post a message on the `OpenMC Discourse Forum
<https://openmc.discourse.group/>`_.

ERROR: No cross_sections.xml file was specified in settings.xml or in the OPENMC_CROSS_SECTIONS environment variable.
*********************************************************************************************************************

OpenMC needs to know where to find cross section data for each nuclide.
Information on what data is available and in what files is summarized in a
cross_sections.xml file. You need to tell OpenMC where to find the
cross_sections.xml file either with the :ref:`cross_sections` in settings.xml or
with the :envvar:`OPENMC_CROSS_SECTIONS` environment variable. It is recommended
to add a line in your ``.profile`` or ``.bash_profile`` setting the
:envvar:`OPENMC_CROSS_SECTIONS` environment variable.

RuntimeError: Failed to open HDF5 file with mode 'w': summary.h5
****************************************************************

This often occurs when working with the Python API and executing multiple OpenMC
runs in a script. If an :class:`openmc.StatePoint` is open in the Python interpreter,
the file handle of the statepoint file as well as the linked `summary.h5` file will
be unavailable for writing, causing this error to appear. To avoid this situation,
it is recommended that data be extracted from statepoint files in a context manager:

.. code-block:: python

    with openmc.StatePoint('statepoint.10.h5') as sp:
        k_eff = sp.k_combined

or that the :meth:`StatePoint.close` method is called before executing a subsequent
OpenMC run.

Geometry Debugging
******************

Overlapping Cells
{'fraction_non_alphanumeric': 0.17437252311756934, 'fraction_numerical': 0.0022645782223060956, 'mean_word_length': 4.07177033492823, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7235027', 'n_tokens_mistral': 1317, 'n_tokens_neox': 1242, 'n_words': 635}