SERPENT Guide

❮ Tutorial: Fuel Assembly

Troubleshooting Guide

General Debugging Approach

When Serpent calculations fail or produce unexpected results, systematic debugging is essential. This guide covers the most common issues and their solutions, organized from basic input errors to advanced performance problems.

Debugging Strategy: Start with syntax checking, then verify geometry, check materials and cross sections, examine source convergence, and finally optimize performance. Most issues fall into these categories.

Essential Debugging Commands

text
% Increase output verbosity for debugging
set his 1               % Detailed history output
set printm 1            % Print material information  
set checkgeo 10000      % Check geometry with 10k test points

% Enable warning messages
set warn 1              % Enable all warnings
set lost 100            % Lost particle limit (default: 10)

% Memory debugging
set memfrac 0.5         % Reduce memory usage for testing
set pcc 0               % Disable probability cache

Common Input File Errors

Syntax and Format Errors

Error: "Unknown keyword" or "Syntax error"

Cause: Typos in command names or incorrect syntax

Solution:

  • Check command spelling against Serpent manual
  • Verify proper spacing and parameter order
  • Ensure comments use % symbol at line start
  • Check for missing end statements in definitions

Error: "Unexpected end of file"

Cause: Incomplete definitions or missing parameters

text
% 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

Material Definition Issues

Error: "Material composition does not sum to unity"

Cause: Incorrect mass or atom fractions

text
% 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)

Error: "Nuclear data not found"

Cause: Missing or incorrect nuclide identifiers

text
% 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

Geometry Definition Errors

Error: "Geometry error - overlapping cells"

Diagnosis: Use geometry checking tools

text
% Add geometry debugging to your input:
set checkgeo 10000      % Test 10,000 random points
plot 3 1000 1000        % Create geometry plot

% Check specific regions:
set testpos 0.0 0.0 0.0 % Test point at origin
set testpos 1.0 1.0 1.0 % Test point at (1,1,1)

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

Common Geometry Mistakes

  • Surface orientation: Check positive/negative side definitions
  • Boolean operators: Verify AND/OR logic with parentheses
  • Units: Ensure consistent units (cm) throughout
  • Boundary conditions: Match geometry with boundary settings

Universe and Lattice Issues

Error: "Universe not found"

Solution: Check universe definitions and references

text
% 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 Problems

Warning: "Source not converged"

Symptoms: k-eff still changing, erratic behavior

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

% Monitor convergence:
set entropy 1           % Track Shannon entropy
set entropymat fuel     % Monitor in fuel regions

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

Statistical Uncertainty Issues

Problem: Large statistical uncertainties

Solutions:

  • Increase neutron population or active cycles: set pop 50000 800 200
  • Use variance reduction for detectors
  • Check for source/tally correlation
text
% 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

Error: "Temperature out of range"

Cause: Material temperature outside available data range

text
% 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

Error: "S(α,β) library not found"

Solution: Check thermal scattering data

text
% 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

Physics Model Issues

Problem: Unrealistic k-effective values

Diagnostic steps:

  • Check material compositions (especially enrichment)
  • Verify geometry (fuel/moderator ratio)
  • Confirm boundary conditions
  • Review temperature specifications
  • Compare with established benchmarks

Performance and Memory Issues

Memory Management

Error: "Out of memory" or slow performance

Memory optimization strategies:

text
% Reduce memory usage:
set memfrac 0.8         % Use 80% of available memory
set pcc 0               % Disable probability table cache
set sfbuf 50            % Smaller sort buffer (MB)

% For large geometries:
set opti 1              % Memory optimization mode
set maxpop 20000        % Limit population size

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

Parallel Processing Issues

Problem: Poor parallel scaling

text
% Optimize for your system:
set omp 8               % Number of OpenMP threads
                        % Usually = number of CPU cores

% For shared memory systems:
set sharedbuf 1         % Use shared memory buffer
set shbuf 100000000     % Shared buffer size (bytes)

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

Calculation Speed Optimization

text
% Performance tuning for production runs:

% Reduce physics detail for scoping studies:
set ncut 1E-8           % Higher energy cutoff
set doppler 1           % Simpler Doppler method
set ures 0              % Disable unresolved resonances

% Optimize for specific problems:
% Shielding calculations:
set wwmin 1E-15         % Lower weight windows
set roulette 1          % Russian roulette

% 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 Calculation Issues

Error: "Burnup calculation failed"

Common causes and solutions:

text
% Check burnup setup:
set power 3400          % Must specify power for burnup
set powdens 1 fuel      % Must specify power-producing materials

% 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"

Problem: Burnup calculation too slow

  • Reduce population for burnup steps: set pop 10000
  • Use larger time steps in equilibrium region
  • Limit tracked isotopes: set inventory with key nuclides
  • Consider predictor-corrector methods

Output and Visualization Issues

Output File Problems

Problem: Missing or corrupted output files

Debugging steps:

  • Check disk space and write permissions
  • Verify calculation completed successfully
  • Look for error messages in .out file
  • Check if calculation was terminated early

Plotting and Visualization

text
% Common plotting issues and solutions:

% Geometry plots don't appear:
plot 3 1000 1000        % 3D 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

Pro Tip: Always create geometry plots when developing new models. Visual inspection catches most geometry errors faster than debugging from error messages alone.

Getting Help and Further Resources

Documentation and Support

Essential Resources:

  • Serpent Wiki: Primary documentation and examples
  • User Forum: Community support and discussions
  • Manual: Complete command reference
  • Validation Suite: Benchmark problems for testing
  • Example Problems: Working input files for learning

Reporting Issues

When seeking help, provide complete information:

  • Serpent version and operating system
  • Complete input file (if possible)
  • Error messages from output file
  • Description of expected vs. actual behavior
  • System specifications (for performance issues)

Success Strategy: Start simple and build complexity gradually. Validate each component (materials, geometry, physics) before combining into complex models. Keep working examples as templates for new problems.

Related Topics

❮ Tutorial: Fuel Assembly