SERPENT Guide
Basic Output Analysis in Serpent
Interpreting simulation results, statistical uncertainties, and convergence diagnostics from Serpent output files.
Serpent Output File Overview
Serpent generates several output files. The main results file (_res.m) contains criticality eigenvalue estimates, neutron balance data, energy-integrated reaction rates, and group constant data. It uses MATLAB/Octave syntax, loadable directly in those environments and easily parsed from Python.
The detector output (_det0.m) stores user-defined tallies: flux and reaction rates, energy spectra, and spatial distributions. For burnup calculations, _dep.mrecords material compositions vs. irradiation time and isotopic inventories. The log file (_out) contains processing times, memory usage, and warning/error messages — review it first whenever unexpected results arise.
Reading the Main Results File
For criticality calculations, the most important quantities in *_res.m are the implicit and analog k-effective estimates. Serpent computes both independently; their agreement indicates simulation quality.
Criticality Eigenvalue Results
IMP_KEFF (implicit) and ANA_KEFF (analog) are independent eigenvalue estimates, each reported as [mean, relative uncertainty]. In a well-converged simulation, they agree within their combined uncertainties.
% Output from pin_cell_res.m
% -- Criticality eigenvalue (k-eff) --
IMP_KEFF = [ 1.34721 0.00095 ];
ANA_KEFF = [ 1.34728 0.00091 ];Neutron Balance
The neutron balance accounts for all production and loss mechanisms. Total production and loss should be nearly equal; large discrepancies indicate geometry errors, insufficient histories, or material problems. Losses include capture, fission, and leakage; production includes fission source and (n,xn) reactions.
% -- Neutron balance (illustrative) --
% NOTE: Variable names below are illustrative. Check your
% actual _res.m output file for exact names, which depend
% on the Serpent 2 version (e.g., ANA_KEFF, IMP_KEFF,
% COL_KEFF, CONVERSION_RATIO, FISS_FRAC, etc.).
LOSS_CAPT = 3.25933E-01; % Capture
LOSS_FISS = 6.74215E-01; % Fission
LOSS_LEAK = 0.00000E+00; % Leakage
TOT_LOSS = 1.00015E+00; % Total loss
PROD_FISS = 1.00000E+00; % Fission source
PROD_NXN = 1.47723E-04; % (n,xn) reactions
TOT_PROD = 1.00015E+00; % Total productionEnergy-Integrated Reaction Rates
Material-wise reaction rates — total fission rate, nu-bar, and material-specific absorption and fission rates — show which regions dominate neutron production and loss.
% -- Reaction rates by material (illustrative) --
% NOTE: Variable names are illustrative. Verify exact names
% in your _res.m output file, as Serpent 2 naming conventions
% may differ between versions.
TOT_FISSRATE = [ 6.74215E-01 0.00083 ]; % Total fission rate
NUBAR = [ 2.43943E+00 0.00000 ]; % Average neutrons per fission
% Material-wise data
MAT_fuel_FISSRATE = [ 6.74215E-01 0.00083 ]; % Fission rate in fuel
MAT_fuel_ABSRATE = [ 1.00015E+00 0.00000 ]; % Absorption rate in fuel
MAT_water_ABSRATE = [ 0.00000E+00 0.00000 ]; % Absorption rate in waterDetector Output
Detector outputs (*_det*.m) contain user-defined tallies: energy-dependent spectra, spatial flux distributions, reaction rate maps, and other integral quantities. An excessive number of finely binned detectors can substantially increase computation time without proportional benefit, so design detectors with appropriate resolution.
Energy-Dependent Flux Spectrum
The energy-dependent flux spectrum reports energy bin boundaries and flux values paired with relative errors. Flux is typically normalized per unit lethargy for comparison across energy groups spanning orders of magnitude.
% -- Flux spectrum detector --
% In Serpent 2, detector outputs are named DETdetname (values)
% and DETdetnameE (energy bins), where "detname" is the
% user-defined detector name from the input file.
% Example: a detector named "FluxSpec" produces DETFluxSpec
% and DETFluxSpecE in the _det0.m file.
DETFluxSpec = [
4.53211E-3 0.012; % First energy bin (flux + rel. error)
7.82145E-3 0.009; % Second energy bin
...
];
DETFluxSpecE = [ 1.00000E-11 1.00000E-10 ... 1.00000E+2 ]; % Energy bin boundariesSpatial Distribution Detectors
Mesh detectors provide spatial distributions across Cartesian or cylindrical grids, outputting mesh boundaries and tally values with relative errors. Applications include power peaking analysis, shielding assessments, and symmetry verification.
% -- Mesh detector (2D) --
DET_MESH_X = [ -0.63 -0.42 -0.21 0.0 0.21 0.42 0.63 ]; % X-mesh boundaries
DET_MESH_Y = [ -0.63 -0.42 -0.21 0.0 0.21 0.42 0.63 ]; % Y-mesh boundaries
DET_MESH_VAL = [ % Values for each mesh element (flux, reaction rate, etc.)
1.23456E-3 0.012, 2.34567E-3 0.010, ... ; % First row
3.45678E-3 0.009, 4.56789E-3 0.008, ... ; % Second row
...
];Evaluating Statistical Errors
Serpent reports most results as a pair: estimated value and relative statistical error. For example, [ 1.34721 0.00095 ] means k-effective = 1.34721 with relative uncertainty 0.00095. The absolute uncertainty is value × relative error = 0.00128.
Relative errors below 0.1% are excellent for high-precision work. Between 0.1–0.5% is acceptable for most engineering applications. Between 0.5–1% is adequate for scoping studies. Above 1%, results should be treated with caution. Statistical error scales as 1/sqrt(N) — halving the error requires four times as many histories.
Visualizing Results
Serpent generates geometry plots during execution when plot cards are included, producing cross-sectional images in the XY, XZ, and YZ planes. More sophisticated post-processing uses MATLAB, Octave, or Python.
MATLAB/Octave Visualization
Serpent output files load directly into MATLAB/Octave. The following example plots a flux spectrum from detector output.
% MATLAB/Octave script to plot flux spectrum
% Run the _det0.m file first (it defines DETdetname variables)
run('pin_cell_det0.m');
% Replace "FluxSpec" with your actual detector name
figure;
semilogx(DETFluxSpecE(1:end-1), DETFluxSpec(:,11), 'b-', 'LineWidth', 2);
xlabel('Energy (MeV)');
ylabel('Flux per unit lethargy');
title('Neutron Flux Spectrum');
grid on;Python Visualization
For Python workflows, the MATLAB-formatted output requires parsing. The following script extracts arrays with regular expressions and plots with matplotlib.
# Python script to plot flux spectrum
import numpy as np
import matplotlib.pyplot as plt
import re
# Function to extract values from Serpent output
def extract_serpent_array(filename, array_name):
with open(filename, 'r') as f:
text = f.read()
pattern = array_name + r'\s*=\s*\[(.*?)\];'
match = re.search(pattern, text, re.DOTALL)
if match:
data_str = match.group(1)
# Convert to numpy array
data = np.array([float(x) for x in data_str.split() if x.strip()])
return data
return None
# Extract energy bins and flux
# Replace "FluxSpec" with your actual detector name
energy = extract_serpent_array('pin_cell_det0.m', 'DETFluxSpecE')
flux_data = extract_serpent_array('pin_cell_det0.m', 'DETFluxSpec')
flux = flux_data[::2] # Values are at even indices
error = flux_data[1::2] # Errors are at odd indices
# Plot
plt.figure(figsize=(10, 6))
plt.semilogx(energy[:-1], flux, 'b-', linewidth=2)
plt.xlabel('Energy (MeV)')
plt.ylabel('Flux per unit lethargy')
plt.title('Neutron Flux Spectrum')
plt.grid(True)
plt.show()Developing reusable scripts for parsing and plotting common Serpent output quantities ensures consistent analysis across projects.
Convergence Assessment
An unconverged simulation produces results that appear reasonable but are biased, particularly for systems with complex geometries or weakly coupled regions. Serpent provides several built-in convergence diagnostics.
Shannon Entropy
Shannon entropy measures the uniformity and spatial extent of the fission source. A converged simulation shows a stable entropy plateau after the initial transient. If entropy is still trending at the end of inactive cycles, more inactive cycles are needed.
% Shannon entropy data from _res.m file
SRC_ENT = [
4.59813E+00; % First inactive cycle
4.61247E+00; % Second inactive cycle
...
4.63576E+00; % Final active cycle
];k-effective Convergence
Cycle-by-cycle k-effective should stabilize once active cycles begin, with fluctuations consistent with reported uncertainty. Warning signs of poor convergence: trending k-effective during active cycles, unstable Shannon entropy, excessive cycle-to-cycle variation, and systematic disagreement between analog and implicit estimators.
% k-effective by cycle
ANA_KEFF_CYCLE = [
1.32145 0; % First inactive cycle (zero error)
1.34023 0; % Second inactive cycle
...
1.34683 0.00435; % First active cycle (with error)
1.34795 0.00312; % Second active cycle
...
];Practical Analysis Examples
A typical criticality assessment examines k-effective, the neutron energy spectrum (thermal-to-fast ratio), spatial fission distribution (power peaking), and the neutron balance (dominant production and loss mechanisms).
Parameter studies vary a design variable (e.g., fuel enrichment) across simulations, extract k-effective from each case, and plot the trend. Interpolation identifies the value required for criticality.
Parameter Study: Enrichment vs. Criticality
When conducting parameter studies, using a consistent random number seed across simulations (via the set seed card) reduces statistical noise and makes physical trends more apparent in the results.
% MATLAB example for parameter study
enrichment = [2.0, 3.0, 4.0, 5.0]; % Enrichment values
keff = [0.942, 1.023, 1.099, 1.168]; % k-effective results
errors = [0.0009, 0.0008, 0.0008, 0.0007]; % Statistical errors
figure;
errorbar(enrichment, keff, errors, 'o-', 'LineWidth', 2);
xlabel('Enrichment (%)');
ylabel('k-effective');
title('Effect of Fuel Enrichment on Criticality');
grid on;
% Find enrichment for k=1.0 using linear interpolation
crit_enrich = interp1(keff, enrichment, 1.0);
fprintf('Estimated critical enrichment: %.2f%%\n', crit_enrich);Common Analysis Challenges
Large models with many detectors produce very large output files. Use targeted detectors with appropriate resolution rather than excessively fine meshes. For large datasets, generate visualizations during post-processing rather than working with raw numerical data directly.
To reduce statistical errors: increase neutrons per cycle (first set popparameter) or active cycles (second parameter). For deep-penetration problems, variance reduction techniques (weight windows, implicit capture) dramatically improve tally statistics.
Validation requires reporting statistical uncertainties alongside mean values. Systematic uncertainties from nuclear data evaluations, geometric approximations, and material tolerances must also be considered. When comparing codes, consistent biases across test cases typically indicate differences in nuclear data, angular quadrature, or resonance treatment rather than code errors.