diff --git a/docs/source/usersguide/troubleshoot.rst b/docs/source/usersguide/troubleshoot.rst index 06e5c57042..888158837f 100644 --- a/docs/source/usersguide/troubleshoot.rst +++ b/docs/source/usersguide/troubleshoot.rst @@ -15,13 +15,15 @@ error you are receiving is among the following options. Problems with Simulations ------------------------- -Segmentation Fault -****************** +RuntimeError: OpenMC aborted unexpectedly. +****************************************** -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: +This error usually indicates that OpenMC experienced a 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 :ref:`compile OpenMC from source ` with +debug options turned on. Create a new build directory and type the following +commands: .. code-block:: sh @@ -34,6 +36,28 @@ failed. If after reading the debug output, you are still unsure why the program failed, post a message on the `OpenMC Discourse Forum `_. +.. _troubleshoot_lost_particles: + +WARNING: After particle __ crossed surface __ it could not be located in any cell and it did not leak. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +During a simulation, particles can become "lost" if they reach a surface and +there is no cell defined on the other side of the surface. It is important to +ensure that 1) proper boundary conditions have been applied to the outer +surfaces of your model and 2) all space in your model is filled with a cell, +even regions that are void and have no material assigned to them. + +Please see the instructions in :ref:`troubleshoot_geometry` on how to resolve +issues with lost particles. + +ERROR: Maximum number of lost particles has been reached. +********************************************************* + +See the above description regarding :ref:`lost particles +`. When too many particles are lost, the simulation +will abort altogether. Again, please see the instructions in +:ref:`troubleshoot_geometry` on how to resolve issues with lost particles. + ERROR: No cross_sections.xml file was specified in settings.xml or in the OPENMC_CROSS_SECTIONS environment variable. ********************************************************************************************************************* @@ -62,22 +86,33 @@ it is recommended that data be extracted from statepoint files in a context mana or that the :meth:`StatePoint.close` method is called before executing a subsequent OpenMC run. +.. _troubleshoot_geometry: + Geometry Debugging ****************** -Overlapping Cells -^^^^^^^^^^^^^^^^^ +To identify issues in your geometry, it is highly recommended to use the `OpenMC +Plot Explorer `_ GUI application. This +application enables you to interactively explore a model, identify regions that +may be missing a cell definition, and identify overlapping cells. -For fast run times, normal simulations do not check if the geometry is -incorrectly defined to have overlapping cells. This can lead to incorrect -results that may or may not be obvious when there are errors in the geometry -input file. The built-in 2D and 3D plotters will check for cell overlaps at -the center of every pixel or voxel position they process, however this might -not be a sufficient check to ensure correctly defined geometry. For instance, -if an overlap is of small aspect ratio, the plotting resolution might not be -high enough to produce any pixels in the overlapping area. +If you are having issues with lost particles, the following procedure may be +helpful. If OpenMC reports, for example, that a particle reaching surface 50 +could not be located, look at your geometry.xml to see which cells have a region +definition that includes surface 50, e.g.: -To reliably validate a geometry input, it is best to run the problem in +.. code-block:: xml + + + +This may indicate that you need to define a cell on the other side of cell 10. +At this point, using the OpenMC Plot Explorer to locate cell 10 may provide a +visual clue as to whether there is a missing or overlapping cell near cell 10. +Working with the unique integer IDs of cells may be cumbersome; if you provide +names to your cells, these names will show up in the Plot Explorer, which will +aid geometry debugging. + +Another method to check for overlapping cells in a geometry is to run the problem in geometry debugging mode with the ``-g``, ``-geometry-debug``, or ``--geometry-debug`` command-line options. This will enable checks for overlapping cells at every move of each simulated particle. Depending on the @@ -92,33 +127,6 @@ output after a geometry debug run to see how many checks were performed in each cell, and then adjust the number of starting particles or starting source distributions accordingly to achieve good coverage. -ERROR: After particle __ crossed surface __ it could not be located in any cell and it did not leak. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This error can arise either if a problem is specified with no boundary -conditions or if there is an error in the geometry itself. First check to ensure -that all of the outer surfaces of your geometry have been given vacuum or -reflective boundary conditions. If proper boundary conditions have been applied -and you still receive this error, it means that a surface/cell/lattice in your -geometry has been specified incorrectly or is missing. - -The best way to debug this error is to turn on a trace for the particle getting -lost. After the error message, the code will display what batch, generation, and -particle number caused the error. In your settings.xml, add a :ref:`trace` -followed by the batch, generation, and particle number. This will give you -detailed output every time that particle enters a cell, crosses a boundary, or -has a collision. For example, if you received this error at cycle 5, generation -1, particle 4032, you would enter: - -.. code-block:: xml - - 5 1 4032 - -For large runs it is often advantageous to run only the offending particle by -using particle restart mode with the ``-r`` command-line option in conjunction -with the particle restart files that are created when particles are lost with -this error. - Depletion *********