Pitfalls and troubleshooting

Serpent produces two types of error messages:

1. Input errors, identified by text "Input error", followed by the error message. If the error can be related to a specific input parameter, then also the name of the parameter and the line number in the input file are printed.
2. Run-time errors, in which case the name of the associated subroutine is printed, along with some additional information.

The first class of errors are (ideally) related to a problem in the input file. It should be noted, however, that the parameter name and line number may not reflect the original cause of the error, but rather the point where things started going wrong. Incorrectly typed input card names, for example, cause the parser to ignore the card altogether, and the following values are interpreted as entries belonging to the previous card.

Run-time errors should not occur, and they should always be reported to the developer team. This is also the case if the calculation crashes (segmentation fault or similar). In such case repeating the calculation in debug mode may reveal some additional information on what went wrong.

Serpent also produces a number of warning messages that may or may not be important. The code is pretty meticulous about errors, so problems let off with a warning are usually not too severe.

Things to check in case of suspicious results

Material volumes

Material volumes are not necessarily needed for most transport simulations, but they do affect the results of burnup calculation. Serpent prints an error message if the volume of an irradiated material is not available.

It is important to note, however, that these problems may also occur even if an error message is not printed. The most typical case is that the code attempts to calculate the volumes of two-dimensional pin-structures automatically, but for some reason this calculation produces incorrect results. This happens, for example, when:

• The geometry has axial dimension (3D geometry is assumed to be 2D)
• Some parts of the fuel pins are located outside the geometry (pins are clipped by cell, universe or geometry boundary)
• When universe symmetries are used (unable to account for pins in symmetry positions)

Serpent cannot identify these problems, so no error message is printed.

Material volumes should always be checked using the Monte Carlo based volume checker routine before running the calculation. If the values are incorrect, or the calculation produces an error message on missing values, the volumes must be set manually.

Unresolved resonance probability table sampling

Unresolved resonance probability table sampling is not used by default. This method is needed to account for self-shielding effects in the unresolved resonance region. The effect is usually not significant in thermal systems, but can lead to noticeable discrepancies in fast-spectrum systems.

Probability table sampling is switched on using the set ures option.

The methodology for probability table sampling is not complete (as of version 2.1.25), and some nuclides contain data that cannot be processed by Serpent. In such case, a warning message is printed and smooth infinite-dilute cross sections are used instead. This is typical for natural elements, and may cause small discrepancies in results, e.g. when compared to MCNP.

Mass vs. atomic densities

The densities and compositions of materials can be entered in atomic or mass units (see the input syntax of the material card), and using incorrect units may lead to unexpected results. The difference may not be clearly noticeable if the material consists nuclides with similar atomic weight, but if there are both light and heavy nuclides the results can be off by tens of percent.

In particular, using incorrect units for isotopes in water causes a major distortion in the flux spectrum in LWR calculations. In burnup calculation this results in completely unexpected depletion rate of ²³⁵U and build-up rate of ²³⁹Pu.

The material and nuclide densities used in the calculation can be checked from the nuclide and material output file ([input].out).

MPI parallelization without MPI mode

MPI scripts such as mpirun allow running Serpent even if the source code was not compiled in MPI mode. Instead of starting a single parallel simulation, the result is multiple independent simulations that read and write the same input and output files. If two or more writing operations happen to overlap, identical sections are repeated in the output files. If the tasks are sufficiently off-sync, the writing operations do not overlap, and it may actually seem like everything is OK - the correct number of CPU's are working and the results look reasonable. The only thing that seems to be wrong is that the running time does not reflect the speed-up expected from the parallelization.

When MPI parallelization is executed correctly, the run-time output shows the number of mpi tasks, for example (MPI=10). The number of tasks is also printed in variable MPI_TASKS in the main output file ([input]_res.m). Whether the source code was compiled in MPI mode or not can be checked with sss2 -version.

Unable to start or maintain criticality source simulation

Criticality source simulation requires an initial guess for the fission source distribution. If no source definition is provided, Serpent samples source points uniformly throughout all fissile materials, i.e. materials with fissile isotopes. This creates a few potential problems:

1. If the fissile zone covers only a small volume of the total geometry, the efficiency of the source sampling routine becomes extremely poor. If the population size is large, the code may be stuck in the source sampling routine for a very long time, or the sampling of the initial source may fail completely.
2. If the geometry contains both very active and inactive fissile zones (e.g. seed and blanket), the calculation may fail after the first generation because the majority of source points are placed in the inactive zone.

The solution to both problems is to use explicit source definition that puts sufficient number of points in the active parts of the fuel. This is most conveniently done using the sx, sy and sz parameters of the source card. It should be noted that the use of an explicit source definition does not affect the results of the simulations, provided that the fission source is allowed to converge by skipping a sufficient number of inactive neutron generations.

Low production rate of higher actinides in burnup calculation

Serpent forms the transmutation paths for burnup calculation automatically, starting from the initial composition defined in the material input. To avoid including everything available, the procedure applies a cut-off that after a certain chain length discards all neutron reactions. The result is that some higher actinides, in particular berkelium and californium isotopes, are not produced through all possible chains, and some isotopes may not be included in the calculation at all.

Discarding these higher actinides should have a negligible effect on the results of the calculation, but in some cases their concentrations are of particular interest. The transmutation chains can be extended further by adding nuclides at zero concentration in the material compositions. Including isotopes ²⁴⁰Cm to ²⁵⁰Cm, ²⁴⁷Bk to ²⁵⁰Bk and ²⁴⁹Cf to ²⁵⁴Cf Should force Serpent to include the necessary data for the high end of the actinide transmutation chains.

Isomeric branching ratios

The production of metastable nuclides in burnup calculation requires isomeric branching ratio data. This data is one of the major sources of uncertainty as well as differences between burnup calculation codes. Serpent uses default constant values and provides options to apply user-defined constant values as well as energy-dependent ratios read from ENDF format data files.

Boundary conditions

Serpent handles reflective and periodic boundary conditions different from other Monte Carlo codes. Instead of stopping the particle at the boundary surface, reflections and translations are handled by coordinate transformations. This poses some limitations to how repeated boundary conditions can be used. For more information, see detailed description on Boundary conditions.

Replicating zero importance regions

MCNP and other Monte Carlo codes have the option to define cells with zero importance, which means that all particles entering the zone are immediately killed. This is basically equivalent with the "outside" type cells in Serpent. Because of delta-tracking, however, the particle has some probability to pass through such zone without encountering any virtual collisions, which means that the particle history is not killed either. For this reason the geometry should always be defined in such way that the boundary with outside cells is non-re-entrant. This also means that outside cells should not be used inside the geometry. In case this cannot be avoided, the use of delta-tracking should be switched off (set dt 0).

Photon production in coupled neutron/photon transport calculations

Coupled neutron/photon transport mode is still a relatively new feature in Serpent 2 (implemented in version 2.1.29). Based on some preliminary test calculations it seems that the production rate of secondary photons varies significantly depending on which neutron transport cross sections are used in the calculation. The differences in photon reaction rates may consequently increase to tens of percent. Serpent prints out the nuclides for which secondary photon production cross sections are available. It should be noted that if the data is missing for some significant isotopes, the results will be correspondingly under-estimated.

Photon production was not considered when the current cross section libraries were prepared for Serpent. Therefore it may be necessary to use some other data source (e.g. MCNP libraries) to obtain accurate results for coupled neutron/photon transport calculations.

Detector volumes

All cell detectors are integrated over volume, and surface detectors over surface area. The results are divided by volume/area, but the divisor is by default set to 1.0. This can be changed using the dv entry of the detector card. Some other codes, in particular MCNP, calculate this volume automatically, or if not possible, require the user to enter a value.

Normalization with variance reduction

By default, Serpent normalizes all reaction rates to unit total loss rate (absorption + leak). This loss rate may not be preserved when weight-window based variance reduction is use, which means that tally results will not match a calculation run without weight windows. It is therefore important to fix the normalization to source, instead of loss rate when using weight windows.

Discontinuity factor calculation with universe symmetries

If a discontinuity factor calculation surface is in the same position as a reflective universe symmetry boundary with actual symmetry transformations, the heterogeneous surface fluxes and incoming and outgoing partial currents will be erroneously zero.

Geometry boundaries

The geometry is not checked for overlaps. If geomety plotter is used, the overlaps are checked for the plotted area. However, if for example the geometry is bounded by outside region coincident with the plotter area, overlaps with the outside area are not checked. In this case, for example if the outermost part of the actual geometry is by mistake infinite, or does not have a boundary coincident with the outside area, the boundary conditions may not be correctly used. This may for example cause zero leakage in the results even if black boundary conditions are used. Overlaps in the outside regions may be checked by including geometry plots with minimum and maximum coordinates extending in the outside region instead of using the default limits.

Debugging the input model

Error and warning messages

Serpent prints out two types of error and two types of warning messages. Input errors, such as:

***** Thu Feb 25 14:53:56 2016

Input error in parameter "cell" on line 8 in file "geometry.inp":

Surface s1 is not defined

indicate that there is some identified problem in the input model, and it is up to the user to fix it. The message is often (but not always) accompanied by the name of an input parameter, and the file name and line number where this parameter was defined. Potential problems that do not require immediate termination of the calculation are notified with a warning message, such as:

 ***** Warning: Nest FUE1 is not used in geometry

These warnings may or may not be related to actual problems, and they can often be ignored.

Fatal errors in the calculation routines produce messages of type:

***** Thu Feb 25 15:05:16 2016:

 - MPI task         = 0
 - OpenMP thread    = 0
 - RNG parent seed  = 1456405516

Fatal error in function LevelScattering:

Now, I am become Death, the destroyer of worlds!

Simulation aborted.

In addition to an ominous (and often unintelligible) error message, the code prints the name of a subroutine and some additional debug information. These errors should not occur at all, and it is important that they are reported to the Serpent developer team (preferably by writing to the Serpent discussion forum). There are also warning messages that include the name of a subroutine, such as:

***** Mon Feb 22 19:34:30 2016 (seed = 1456162439)
Warning message from function CheckNuclideData:

Stable nuclide 40096.09c has 1 decay modes

These messages are related to suspicious values or other problems in the input data or calculation routines, that may affect the outcome of the simulation, but do not require immediate termination. It is not uncommon that the code prints several warning messages, especially in burnup calculation, and usually they can be ignored. Serpent is still a developing code, and several potential problems, that may not turn out to be problems after all, are checked. This is especially the case when the code is run in the DEBUG mode.

Running the calculation in DEBUG mode

When the calculation crashes or produces completely unrealistic results despite no evident problems in the input, it is advised to repeat the calculation in the DEBUG mode. Since this requires recompiling the source code, it is good practice to keep two separate executables available at all times.

The DEBUG mode switches on several pointer and value checks, which are likely to catch the root cause of the error early on. Performing this check before reporting the error helps tracking down the problem. It should be noted, however, that the calculation runs significantly slower when compiled in the DEBUG mode (by a factor of two or more). When compiled in this mode the code prints text "DBG" in the run-time output log.

Performance

This section contains miscellaneous tips for improving Serpent calculation times.

• Disable calculation of group constants if not needed.
• Disable calculation of cumulative migration method diffusion coefficients if not needed.
• Use private result array if there is enough memory.
• Disable OpenMP result reproducibility if not needed.
• Use lattice geometries is possible.
• Use fewer micro energy groups if no critical spectrum calculations or out-scattering diffusion coefficients are needed. This option should be explored together with the private result array option, as with the shared result array this might lead to longer calculation times.
• Remove unnecessary mesh plots if not needed during production calculations.
• Remove unnecessary detectors if not needed during production calculations.
• Tune the ratio of neutrons per generation and number of cycles or number of batches. Running many cycles with relatively small populations is generally slower than running fewer cycles with greater populations. However, this may also change the accumulation of statistics, equilibrium xenon iteration etc.

Memory consumption

This section contains miscellaneous tips for reducing Serpent memory consumption.

• If running a high number of neutrons per generation, the default value of neutron buffer factor will lead to unnecessarily high memory consumption. Reducing the factor to a low number will reduce the memory consumption. However, if the value is too small for a given calculation case, the program will terminate itself (with an error message).