SERPENT Guide
Input File Structure
Organization, syntax, and card types in Serpent input files
Overview
A Serpent input file is a plain text file, typically saved with a .inpextension. Unlike some older Monte Carlo codes that enforce rigid column-based formatting, Serpent uses a free-format input structure where whitespace serves only as a delimiter between values. This makes input files significantly more readable and less prone to formatting errors.
The input is organized into cards — keyword-based commands that define materials, surfaces, cells, settings, and other components of the model. While Serpent is fairly flexible about the order in which cards appear, maintaining a consistent organizational structure across your input files makes them much easier to navigate and debug, especially as models grow in complexity.
Comments and Formatting
Comments in Serpent begin with the percent sign (%) and continue to the end of the line. Everything after the percent sign is ignored by the parser. Comments are your primary tool for documenting the physical meaning of your model parameters, the source of material compositions, and the rationale behind modeling choices.
% This entire line is a comment
mat fuel -10.4 % Inline comment: UO2 at 10.4 g/cm3
% Use section dividers for clarity in large input files:
% =============================================
% MATERIAL DEFINITIONS
% =============================================Good commenting practice focuses on explaining why, not what. A comment like "UO2 fuel at theoretical density with 3% enrichment" is far more useful than "material definition" — the syntax already tells the reader it is a material definition.
Recommended Organization
Although Serpent does not enforce a particular ordering of cards, a consistent structure helps you and others navigate the file efficiently. The recommended order places material definitions first, since they are referenced by name in cell definitions. Surfaces come next, followed by cells, then any lattice and universe definitions. Detector (tally) definitions follow the geometry, and global settings and run parameters close out the file.
Recommended File Layout
% =============================================
% Header: model description, author, date
% =============================================
% --- Material definitions ---
mat fuel -10.4 tmp 900
92235.09c 0.04
92238.09c 0.96
8016.09c 2.0
mat water -0.7 tmp 574 moder lwtr 1001
1001.09c 2
8016.09c 1
therm lwtr lwj3.11t
% --- Surface definitions ---
surf 1 cyl 0.0 0.0 0.4
surf 2 sqc 0.0 0.0 0.63
% --- Cell definitions ---
cell 1 0 fuel -1
cell 2 0 water 1 -2
cell 3 0 outside 2
% --- Detector definitions ---
det flux dm fuel de myenergy
ene myenergy 3 500 1e-9 20.0
% --- Physics and run parameters ---
set acelib "sss_endfb7u.xsdata"
set bc 2
set pop 10000 100 20This layout follows the natural dependency chain: materials are defined before they are referenced in cells, and surfaces are defined before the cells that use them. While Serpent resolves references regardless of order, maintaining this structure makes the input self-documenting.
Card Types
Serpent input consists of several categories of cards, each with its own keyword and syntax. Material cards begin with mat and specify the material name, density, optional parameters like temperature, and a list of nuclide-fraction pairs. Surface cards begin with surf and define geometric surfaces by type and parameters. Cell cards begin with cell and assign materials to volumes bounded by surfaces.
Pin definitions (pin) and lattice definitions (lat) provide a compact syntax for common reactor geometries. Rather than defining individual cylindrical surfaces and cells for each ring of a fuel pin, the pin card lets you specify a sequence of materials and radii in a single definition. Lattice cards arrange pins or other universe-based structures into regular arrays.
Setting cards (set) control global simulation parameters: the neutron population, boundary conditions, cross-section library paths, physics options, and output control. Detector cards (det) define tallies for scoring specific quantities like reaction rates, flux spectra, or spatial distributions during the simulation.
Pin and Lattice Shorthand
% Pin definition: concentric material rings
pin 1
fuel 0.4096 % Fuel pellet to radius 0.4096
clad 0.4750 % Cladding to radius 0.4750
water % Water fills the remainder
% Square lattice of pins
lat 10 1 0.0 0.0 5 5 1.26
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1The pin card replaces what would otherwise require two surface cards and three cell cards. The lattice card arranges 25 copies of pin 1 in a 5x5 square array with 1.26 cm pitch. These shorthand definitions greatly simplify reactor modeling input.
Line Continuation
Material definitions naturally span multiple lines because each nuclide-fraction pair occupies its own line. Serpent determines that the material definition continues as long as it encounters valid nuclide identifiers following the initial mat card. No special continuation character is needed.
For other card types, Serpent generally continues reading parameters until it encounters a new keyword or the end of the file. Long detector energy grids or lattice maps can span as many lines as needed without any special syntax. This behavior makes input files cleaner than codes that require explicit continuation characters.
Input Validation
Serpent performs extensive input validation during initialization. It checks for unknown keywords, missing required parameters, undefined material or surface references, and basic geometric consistency. If an error is found, Serpent prints a message identifying the problem — usually including the offending line number — and terminates before starting the transport calculation.
The most common input errors are typos in material or surface names, incorrect numbers of parameters for a given card type, and geometric inconsistencies such as undefined regions or overlapping cells. When Serpent reports an error, read the message carefully: it usually points directly to the problem. For geometry errors, the plotting capability (plot card) is invaluable for visual debugging.
Complete Example
The following example shows a complete, well-organized Serpent input file for a simple PWR pin cell calculation.
% Simple PWR pin cell example
% Author: Nuclear Monte Carlo Guide
% Units: cm, Kelvin, g/cm3
% =============================================
% MATERIALS
% =============================================
mat fuel -10.4 tmp 900
92235.09c 0.031 % U-235 (3.1 at% of U)
92238.09c 0.969 % U-238
8016.09c 2.0 % Oxygen (2 atoms per UO2 molecule)
mat clad -6.56 tmp 600
40090.09c -0.9845 % Zirconium
50120.09c -0.0155 % Tin
mat water -0.7 tmp 574 moder lwtr 1001
1001.09c 2 % Hydrogen
8016.09c 1 % Oxygen
therm lwtr lwj3.11t
% =============================================
% GEOMETRY
% =============================================
surf 1 cyl 0.0 0.0 0.4096 % Fuel radius
surf 2 cyl 0.0 0.0 0.4178 % Gap radius
surf 3 cyl 0.0 0.0 0.4750 % Clad radius
surf 4 sqc 0.0 0.0 0.63 % Cell boundary
cell 1 0 fuel -1 % Fuel
cell 2 0 void 1 -2 % Gap (helium)
cell 3 0 clad 2 -3 % Cladding
cell 4 0 water 3 -4 % Moderator
cell 5 0 outside 4 % External
% =============================================
% SETTINGS
% =============================================
set acelib "sss_endfb7u.xsdata"
set bc 2 % Reflective BCs
set pop 10000 100 20 % Population parameters
% Energy grid for detector
ene eGrid 3 500 1e-11 20.0
% Flux spectrum detector
det 1 dm fuel de eGrid