Troubleshooting Guide

General Debugging Approach

The recommended debugging order is: input syntax checking, geometry verification, materials and cross section data, source convergence, and finally performance optimization. Working through them in this order prevents the common mistake of investigating complex physics problems when the root cause is a simple typo in the input file.

% Increase output verbosity for debugging
set his 1               % Detailed history output
set printm 1            % Print material information  
% Use sss2 -plot input to verify geometry (generates plots and exits)

set lost 100            % Lost particle limit (default: 10)

% Memory debugging
set memfrac 0.5         % Reduce memory usage for testing
set pcc 0               % Disable predictor-corrector calculation (for burnup debugging)

Common Input File Errors

Input file errors are the most frequent source of problems and the easiest to diagnose. Serpent's error messages for syntax issues generally point to the specific line and keyword where parsing failed.

The "Unknown keyword" or "Syntax error" message indicates that Serpent encountered a command it does not recognize, most commonly due to misspelling, incorrect parameter ordering, or missing whitespace between values. The solution is to check the command spelling against the Serpent manual, verify proper spacing and parameter order, ensure that comments use the percent symbol, and confirm that multi-line definitions are properly terminated. The "Unexpected end of file" error occurs when a definition is incomplete, such as a material card without any nuclide composition entries or a surface card missing its dimensional parameters.

% Common mistakes:
mat fuel -10.4          % Missing material composition
% Should be:
mat fuel -10.4
92235.09c  0.045
92238.09c  0.955
8016.09c   2.0

% Incomplete surface definition  
surf cyl                % Missing parameters
% Should be:
surf cyl cylz 0.0 0.0 5.0

% Wrong - mass fractions don't sum to 1.0:
mat fuel -10.4
92235.09c -0.05         % 5%
92238.09c -0.95         % 95% 
8016.09c  -2.0          % This should be atom ratio, not mass

% Correct for UO2:
mat fuel -10.4
92235.09c  0.045        % 4.5 at% U-235
92238.09c  0.955        % 95.5 at% U-238
8016.09c   2.0          % Stoichiometric oxygen (2 atoms per UO2)

% Check available nuclear data:
% Use correct ZAID format: ZZZAAA.nnx
% ZZZ = atomic number, AAA = mass number, nn = library, x = class

% Wrong:
92235.09                % Missing class identifier
u235.09c                % Invalid format

% Correct:
92235.09c               % U-235 with .09c library

Geometry Problems

The "Geometry error - overlapping cells" message indicates that two or more cells claim ownership of the same spatial region, creating an ambiguous material assignment. This typically results from incorrect Boolean logic in cell definitions, surfaces that do not properly divide space, or transformation errors that cause regions to intersect.

% Use sss2 -plot input to generate plots and exit without transport
plot 3 1000 1000        % Material-colored XY geometry plot

% Run with single particle to isolate geometry issues:
set pop 1 1 0           % 1 neutron, 1 cycle, 0 inactive

Common sources of geometry errors include incorrect surface orientation (confusing the positive and negative sides of a surface), errors in Boolean logic where AND and OR operators are not properly parenthesized, inconsistent units (Serpent expects centimeters throughout), and mismatches between boundary conditions and the physical extent of the geometry. When working with lattices and universes, the "Universe not found" error indicates that a lattice references a universe number that has not been defined. Each integer appearing in the lattice definition must correspond to a universe that has been created through cell and surface definitions.

% Ensure all referenced universes are defined:
lat assembly 1 0.0 0.0 3 3 1.26
1 2 1
2 1 2  
1 2 1

% Each number must correspond to a defined universe:
cell u1 1 fill fuel_pin   % Universe 1
cell u2 2 fill guide_tube % Universe 2

% Not defined: Universe 3 would cause error

Convergence and Statistical Issues

Source convergence is a fundamental concern in Monte Carlo criticality calculations. The fission source distribution must reach a stationary state before meaningful results can be tallied. The "Source not converged" warning indicates that the spatial distribution of fission neutrons is still evolving, meaning that results accumulated during this period will be biased. The primary remedy is to increase the number of inactive cycles, allowing the source more time to equilibrate before active tallying begins. Monitoring Shannon entropy as a function of cycle number provides a quantitative measure of source convergence: the entropy trace should reach a stable plateau before the transition from inactive to active cycles.

% Increase inactive cycles:
set pop 20000 1000 500  % 500 inactive cycles

% Monitor convergence:
set entr 10 10 1        % Shannon entropy mesh (10x10x1 spatial bins)

% Plot convergence:
set his 1               % Enable history output
% Then plot k-eff vs cycle number in MATLAB/Python

Large statistical uncertainties in tally results indicate that the Monte Carlo sampling has not accumulated sufficient history to produce a reliable estimate. For integral quantities like k-effective, production calculations typically target a relative uncertainty below 10 pcm (0.00010). Reaction rates should generally be resolved to within 1-2%, flux distributions to within 3-5%, and power peaking factors to within 2-3%. When results fall short of these targets, the most direct remedy is to increase the neutron population per cycle or the number of active cycles in the set pop card. For localized tallies in low-flux regions, variance reduction techniques may be necessary to achieve acceptable statistics within practical computation times.

% Target uncertainties for production calculations:
% k-effective:     < 10 pcm (0.00010)
% Reaction rates:  < 1-2%
% Fluxes:          < 3-5%
% Power peaking:   < 2-3%

% Examine cycle-by-cycle data in the _his file to ensure stability.

Cross Section and Physics Issues

Nuclear data problems manifest as either explicit error messages during initialization or as subtle inaccuracies in the simulation results. The "Temperature out of range" error occurs when a material is assigned a temperature outside the range covered by the available cross section library. Most continuous-energy libraries provide data from 293 K to approximately 1200 K. The solution is to use realistic operating temperatures that fall within the library range or, if necessary, to increase the temperature tolerance with the set tmplimcard.

% Check temperature specifications:
mat fuel -10.4 tmp 900  % 900K is reasonable for fuel
mat water -0.714 tmp 574 % 574K is reasonable for water

% Common temperature ranges in nuclear data:
% 293K-1200K for most materials
% Use realistic operating temperatures

% Increase tolerance if needed:
set tmplim 50.0         % Allow ±50K temperature difference (verify against Serpent 2 docs)

% Use moder keyword in material + therm card to define S(α,β):
mat water -0.714 tmp 574 moder lwtr 1001
1001.09c -0.111894
8016.09c -0.888106

therm lwtr lwj3.22t     % Light water S(α,β)

% Common S(α,β) libraries:
% lwtr = light water, dwtr = heavy water, grph = graphite

Unrealistic k-effective values indicate physics modeling errors rather than code bugs. Systematically verify material compositions (particularly fuel enrichment and moderator density), geometry dimensions (especially the fuel-to-moderator ratio), boundary conditions (reflective vs. vacuum), temperature specifications, and consistency with published benchmark results for similar configurations.

Performance and Memory Issues

Memory exhaustion and poor computational performance become significant concerns for large or complex models. The "Out of memory" error indicates that the simulation's memory requirements exceed the available system resources. Several strategies can reduce memory usage: reducing the memory fraction with set memfrac, disabling the predictor-corrector calculation with set pcc 0 (useful for burnup debugging), reducing sort buffer sizes, and enabling memory optimization mode. For large geometries, limiting the neutron population with reducing the population size prevents excessive memory allocation for particle storage.

% Reduce memory usage:
set memfrac 0.8         % Use 80% of available memory
set pcc 0               % Disable predictor-corrector calculation (for burnup debugging)
set sfbuf 50            % Smaller sort buffer

% For large geometries:
set opti 1              % Memory optimization mode

% Monitor memory usage during run:
set his 1               % Track memory in history file

Parallel scaling efficiency depends on proper configuration of thread counts and particle populations. The number of OpenMP threads should generally match the number of physical CPU cores, and the neutron population per cycle should be evenly divisible by the thread count to ensure balanced workload distribution. Poor parallel scaling often results from population sizes that divide unevenly across threads, excessive memory contention on shared data structures, or I/O bottlenecks when writing large output files.

% Thread count set via command line: sss2 -omp 8 input

% Population should be divisible by thread count:
set pop 32000 200 40    % Good for 8 threads (4000 per thread)
set pop 30000 200 40    % Bad - uneven distribution

% Performance tuning for production runs:

% Reduce physics detail for scoping studies:
set ures 0              % Disable unresolved resonance probability tables
set opti 1              % Enable optimization mode

% Variance reduction for shielding:
% Use wwgen and wwin cards to define weight window meshes
% set roulette 0.001 0.5  % Weight cutoff and survival probability

% Criticality calculations:
set pop 30000 1500 300  % Larger population, more cycles
% Review the _his file to ensure stable cycle statistics

Burnup and Depletion Problems

Burnup calculations introduce additional failure modes beyond those present in static transport problems. The "Burnup calculation failed" error typically results from missing or incorrect configuration of the depletion setup. A valid burnup calculation requires a power specification (set power or set powdens), at least one material flagged with the burn keyword, a depletion schedule (via dep cards), and access to decay and fission yield data libraries. The time step progression should be physically reasonable, with finer steps during periods of rapid composition change and coarser steps as the system approaches quasi-equilibrium.

% Check burnup setup:
set power 3400E6        % 3400 MW thermal power (in watts)
set powdens 40.0        % Power density (W/g of heavy metal)

% Verify burnable materials:
mat fuel -10.4 burn 1   % 'burn' flag is required
92235.09c  0.045
92238.09c  0.955
8016.09c   2.0

% Check time steps:
dep daystep
10 20 50 100            % Reasonable progression
% Avoid: 0.1 1000       % Too large jump

% Ensure nuclear data libraries exist:
set declib "endfb71_dec"
set nfylib "endfb71_nfy"

To speed up slow burnup calculations: reduce the neutron population per transport step (maintaining adequate statistics for cross section generation), use larger time steps in the equilibrium depletion region, limit the isotope inventory to key nuclides (reducing the Bateman equation system size), or use predictor-corrector methods to improve accuracy without reducing step size.

Output and Visualization Issues

Missing or corrupted output files typically result from insufficient disk space, incorrect write permissions, or abnormal termination. Check the log file (.out) for error messages. If the calculation completed but output files are missing, verify that the expected output types were enabled in the input (e.g., detector output requires detector definitions, burnup output requires burnup mode activation).

% Common plotting issues and solutions:

% Geometry plots don't appear:
plot 3 1000 1000        % 2D XY cross-section plot, 1000x1000 pixels
% Check that geometry is in the plot plane

% Wrong plot orientation:
plot 3 1000 1000 0.0 -20.0 20.0 -20.0 20.0
%    ^type ^x-res ^y-res ^z-pos ^xmin ^xmax ^ymin ^ymax

% No material colors:
% Materials appear as white - this is normal
% Use plot boundaries to highlight geometry

% Detector plots:
% Ensure detector regions overlap with geometry
% Check detector energy and spatial bins

Getting Help and Further Resources

The Serpent Wiki is the primary documentation source, with detailed command references, worked examples, and descriptions of all code features. The user forum provides community-based support. The validation suite includes benchmark problems for verifying code installation and testing modeling techniques against known results.

When reporting bugs or seeking help, include: the Serpent version number and operating system, the complete input file (or a minimal reproducing example), all error messages from the output file, and a clear description of expected versus actual behavior.