SERPENT Guide
Cell Definitions in Serpent
Defining volumes, assigning materials, and controlling cell properties
Cell Fundamentals
Cells are the fundamental volumetric elements of a Serpent geometry model. Each cell defines a three-dimensional region of space bounded by surfaces, and every cell must be assigned either a material (which determines how neutrons interact within that volume) or designated as void. Together, the cells must cover the entire problem domain without gaps or overlaps — every point in space must belong to exactly one cell.
Axis-aligned bounding volumes are usually built with a cuboid surface in the surf block (Serpent 2 naming — not rect), then referenced from the cell Boolean expression.
Cell Card Syntax
cell NAME UNIVERSE MATERIAL SURFACE_DEFINITION [OPTIONS]The name is a unique identifier for the cell (a number or descriptive string). The universe specifies which geometric hierarchy the cell belongs to — use 0 for the base (root) universe. The material references a previously defined material name, or void for an empty region, or outside for the external boundary. The surface definition is a Boolean expression that delimits the cell's spatial extent.
Material Assignment and Void Cells
Most cells are filled with a material that determines the nuclear composition and density of the region. The material name in the cell card must match a material defined elsewhere in the input file with a mat card. Void cells contain no material and are used for gas gaps, vacuum regions, or placeholder volumes. Void cells still participate in particle tracking — neutrons pass through them without interacting.
Fuel Pin with Gap and Cladding
% Surfaces
surf fuel_rad cylz 0.0 0.0 0.41
surf gap_rad cylz 0.0 0.0 0.42
surf clad_rad cylz 0.0 0.0 0.475
surf top pz 180.0
surf bot pz -180.0
% Cells with material assignments
cell fuel 0 uo2 -fuel_rad -top bot
cell gap 0 void -gap_rad fuel_rad -top bot
cell cladding 0 zircaloy4 -clad_rad gap_rad -top bot
cell water 0 h2o -top bot clad_rad
cell above 0 void top
cell below 0 void -botThe gap between fuel pellet and cladding is filled with helium at low pressure, which has negligible effect on neutron transport and is modeled as void. The axial extent of each cylindrical region is bounded by the top and bottom planes. Regions above and below the fuel stack are also defined to ensure complete spatial coverage.
Cell Options and Material Properties
In Serpent 2, temperature (tmp), volume (vol), and display color (rgb) are specified on the mat card, not the cell card. To model temperature gradients — for instance, different fuel temperatures at different axial elevations — define separate materials at different temperatures and assign each to its own cell.
Serpent can calculate volumes automatically for many simple geometries, but explicit specification via the vol keyword on the material card is sometimes needed for cells within universe-based lattice structures. The rgb keyword on the material card sets the display color for geometry plots, helping distinguish regions visually during debugging.
Cell Options Examples
% Temperature: define separate materials with different tmp values
mat fuel_800 -10.4 tmp 800
92235.09c 0.031 92238.09c 0.969 8016.09c 2.0
mat fuel_1000 -10.4 tmp 1000
92235.09c 0.031 92238.09c 0.969 8016.09c 2.0
mat fuel_1200 -10.4 tmp 1200
92235.09c 0.031 92238.09c 0.969 8016.09c 2.0
cell fuel_bot 0 fuel_800 -fuel_rad -pz_mid pz_bot
cell fuel_mid 0 fuel_1000 -fuel_rad -pz_top pz_mid
cell fuel_top 0 fuel_1200 -fuel_rad pz_mid -pz_top
% Volume and color are specified on the mat card, not the cell card
mat fuel_zone -10.4 tmp 900 vol 125.6 rgb 255 100 100 burn 1
92235.09c 0.031 92238.09c 0.969 8016.09c 2.0Complex Boolean Logic
The intersection operator (space between surface references) is the most common — it defines cells as the overlap region where all surface conditions are met simultaneously. The union operator (colon) joins disjoint regions into a single cell, useful for modeling structures like flow holes through a tube wall where the water occupies multiple disconnected volumes.
Parentheses control evaluation order when mixing intersections and unions. Without parentheses, Serpent evaluates intersections before unions, analogous to multiplication before addition in arithmetic. Explicit parentheses make the intent clear and prevent subtle errors in complex expressions.
Multi-Component Assembly Cells
% Fuel assembly with guide tubes and instrument tube
surf fuel_pin cylz 0.0 0.0 0.41
surf guide_out cylz 5.0 5.0 0.60
surf guide_in cylz 5.0 5.0 0.56
surf instr_out cylz 10.0 10.0 0.60
surf instr_in cylz 10.0 10.0 0.56
surf box cuboid -10.5 10.5 -10.5 10.5 -50.0 50.0
% Each cell uses intersections to carve out its region
cell fuel_region 0 fuel -fuel_pin
cell guide_tube 0 zirc (-guide_out guide_in)
cell guide_water 0 water -guide_in
cell instr_tube 0 zirc (-instr_out instr_in)
cell instr_water 0 water -instr_in
cell moderator 0 water -box fuel_pin guide_out instr_outThe moderator cell is everything inside the assembly box that is not occupied by any other component. It is defined as the intersection of being inside the box and outside the fuel pin, guide tube, and instrument tube. This "exclusion" approach ensures complete spatial coverage without requiring complex union expressions.
Common Errors in Cell Definitions
Overlapping cells occur when two or more cell definitions claim the same region of space. Serpent cannot determine which material to assign to the overlap region, and the behavior is undefined. The overlap detection mode (set overlap 10000) randomly samples points throughout the geometry and reports any that belong to multiple cells. Always run this check on new or modified geometries.
Undefined regions — gaps where no cell is defined — cause lost particles during the transport calculation. When a neutron enters an undefined region, Serpent terminates that particle history and reports the incident. Even a small number of lost particles indicates a geometry error that must be corrected. The most common cause is forgetting to define the outermost cell that captures everything beyond the model boundary.
Boolean logic errors are subtler. Confusing intersection with union produces cells that are either too large or too small. If a cell defined with -s1 : -s2(union: inside s1 OR inside s2) should have been -s1 -s2 (intersection: inside s1 AND inside s2), the resulting cell encompasses a much larger volume than intended. Geometry plots are the fastest way to catch these errors visually.
Debugging Cell Definitions
Serpent provides several tools for diagnosing geometry problems. Geometry plots (e.g., plot 3 500 500) produce cross-sectional images showing material assignments in color. The overlap checker (set overlap N) tests N random points for multiple cell membership. When particles are lost during transport, the log file reports the coordinates and the last known cell, giving you a starting point for investigation.
A systematic approach to debugging starts with plotting the geometry in all three coordinate planes (xy, xz, yz) at multiple positions. Compare the plots against your intended geometry. If the plots look correct but particles are still lost, the problem is likely in a region not covered by your plot planes — check axial boundaries and corners of the model carefully.
Practical Examples
PWR Fuel Pin with Axial Detail
% Radial surfaces
surf fuel_rad cylz 0.0 0.0 0.41
surf gap_rad cylz 0.0 0.0 0.42
surf clad_rad cylz 0.0 0.0 0.475
% Axial surfaces
surf z_top pz 180
surf z_bot pz -180
% Cells
cell fuel 0 uo2 -fuel_rad -z_top z_bot
cell gap 0 void -gap_rad fuel_rad -z_top z_bot
cell cladding 0 zirc4 -clad_rad gap_rad -z_top z_bot
cell water 0 h2o -z_top z_bot clad_rad
cell top_void 0 void z_top
cell bot_void 0 void -z_botReactor Core with Reflector and Baffle
% Concentric rectangular boundaries
surf core_bound cuboid -85.0 85.0 -85.0 85.0 -180.0 180.0
surf baffle_bound cuboid -90.0 90.0 -90.0 90.0 -185.0 185.0
surf refl_bound cuboid -120.0 120.0 -120.0 120.0 -200.0 200.0
% Nested cells from inside out
cell core 0 fill 1 -core_bound
cell baffle 0 ss304 -baffle_bound core_bound
cell reflector 0 h2o -refl_bound baffle_bound
cell outside 0 outside refl_boundThe core cell uses fill 1 to indicate that it is filled with universe 1, which would contain the detailed fuel assembly lattice definition. This hierarchical approach — defining the core interior as a filled universe — keeps the top-level geometry clean and manageable.