SERPENT Guide

❮ Cell DefinitionsUniverse Concept ❯

Lattice Structures in Serpent

Arranging universes into regular patterns for reactor geometry modeling

The Lattice Concept

Lattices are Serpent's mechanism for creating regular arrays of repeated geometric structures. A fuel assembly containing 264 fuel pins does not require 264 separate geometry definitions — instead, you define a single fuel pin as a universe and arrange copies of it in a lattice. Each position in the lattice is filled by a universe, and different positions can contain different universes (fuel pins, guide tubes, instrument tubes, water holes).

This approach mirrors the physical organization of a reactor: pins are arranged in assemblies, and assemblies are arranged in a core. Serpent supports rectangular (square), hexagonal, and circular lattice types, covering the geometry conventions of essentially all commercial and research reactor designs.

Rectangular Lattices

Rectangular lattices arrange universes in a Cartesian grid and are used for PWR and BWR fuel assembly models. The lattice card specifies the lattice type (1 for rectangular), the center coordinates, the number of positions in the x and y directions, and the pitch. A universe map then assigns a universe identifier to each position.

Rectangular Lattice Syntax

text
lat NAME 1 x0 y0 nx ny pitch
[universe map rows]

% Example: 5x5 lattice with fuel (1), guide tubes (2), and instrument (3)
lat assy 1 0.0 0.0 5 5 1.26
2 2 2 2 2
2 1 1 1 2
2 1 3 1 2
2 1 1 1 2
2 2 2 2 2

The universe map is read row by row from bottom to top (matching the y-axis direction). Each integer in the map references a universe defined elsewhere in the input. The pitch value gives the center-to-center distance between adjacent positions.

Hexagonal Lattices

Hexagonal lattices are used for reactor designs with hexagonal fuel assemblies, such as the Russian VVER series. The lattice type is 2 for X-type hexagonal (vertices along the x-axis) or 3 for Y-type hexagonal (flats along the x-axis). The syntax is lat UNI 2 X0 Y0 NR PITCH, where NR is the number of rings. The universe map has a hexagonal shape, with rows of increasing then decreasing length.

Hexagonal Lattice Example

text
lat hex_assy 2 0.0 0.0 4 1.3
   2 2 2 2
  2 1 1 1 2
 2 1 1 1 1 2
2 1 1 3 1 1 2
 2 1 1 1 1 2
  2 1 1 1 2
   2 2 2 2

With 4 rings, the universe map has rows with 4, 5, 6, 7, 6, 5, 4 entries. The outer positions (universe 2) are typically filled with water or a dummy universe, while interior positions contain fuel (1) and a central instrument tube (3).

Defining Pin Universes

Before creating a lattice, you need the universes that will populate it. In reactor modeling, the most common universe is a fuel pin — concentric cylindrical regions of fuel, gap, cladding, and moderator. Serpent provides the pin shorthand for this common geometry, but you can also define pin universes manually with surf and cell cards.

Pin Universes for a Lattice

text
% Fuel pin surfaces
surf fuel_r cylz 0.0 0.0 0.41
surf clad_r cylz 0.0 0.0 0.475

% Universe 1: Fuel pin
cell fuel  1 uo2   -fuel_r
cell clad  1 zirc  -clad_r fuel_r
cell water 1 h2o    clad_r

% Guide tube surfaces
surf gin cylz 0.0 0.0 0.56
surf gout cylz 0.0 0.0 0.60

% Universe 2: Guide tube
cell gtube  2 zirc  -gout gin
cell gwater 2 h2o   -gin
cell gmod   2 h2o    gout

% Universe 3: Instrument tube (same geometry, different ID)
cell itube  3 zirc  -gout gin
cell iwater 3 h2o   -gin
cell imod   3 h2o    gout

Each universe is a self-contained geometry defined at its own local origin. When the lattice places these universes, Serpent translates each one to the appropriate grid position. The outermost cell in each universe (here, the water cell) must extend to infinity or at least fill the entire lattice pitch — Serpent clips it to the lattice cell boundaries automatically.

Placing Lattices in the Model

A lattice by itself is just a pattern definition. To include it in your geometry, you place it inside a cell using the fill keyword. The cell's bounding surfaces determine where the lattice appears in the model, and Serpent clips the lattice to those boundaries.

Placing a Lattice

text
% Assembly boundary
surf assy_bound cuboid -10.71 10.71 -10.71 10.71 -180 180

% Fill the assembly region with the lattice
cell assembly 0 fill assy -assy_bound
cell exterior  0 outside    assy_bound

The lattice named assy fills the rectangular region defined by assy_bound. Everything outside that boundary is the problem exterior. For a full-core model, you would define the lattice as a universe (not universe 0) and then place it inside another cell at the core level of the hierarchy.

Complete PWR Assembly Example

A realistic 17x17 PWR fuel assembly combines fuel pins, guide tubes, and a central instrument tube in a rectangular lattice. The guide tube positions follow the standard Westinghouse layout, with 24 guide tubes and one central instrument tube.

text
% 17x17 PWR lattice (1=fuel, 2=guide tube, 3=instrument tube)
lat pwr 1 0.0 0.0 17 17 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 1 1 1 1 1 1 1 1 1 1
1 1 1 1 1 2 1 1 2 1 1 2 1 1 1 1 1
1 1 1 2 1 1 1 1 1 1 1 1 1 2 1 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 2 1 1 2 1 1 2 1 1 2 1 1 2 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 2 1 1 2 1 1 3 1 1 2 1 1 2 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 2 1 1 2 1 1 2 1 1 2 1 1 2 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 1 2 1 1 1 1 1 1 1 1 1 2 1 1 1
1 1 1 1 1 2 1 1 2 1 1 2 1 1 1 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1

surf assy_bound cuboid -10.71 10.71 -10.71 10.71 -180 180
cell assembly 0 fill pwr -assy_bound
cell exterior  0 outside   assy_bound

Universe 3 at position (9,9) — the center of the assembly — is the instrument tube. The 24 positions marked with 2 are the guide tubes where control rods can be inserted. All remaining positions are fuel pins. This compact representation replaces what would otherwise be hundreds of individual surface and cell definitions.

Nested Lattices for Full-Core Models

For full-core models, assembly-level lattices become universes that are themselves arranged in a core-level lattice. This hierarchical nesting mirrors the physical structure of the reactor and keeps each level of the model manageable. A typical hierarchy has three levels: pin universes, assembly lattices, and a core lattice.

Core-Level Lattice

text
% Assembly lattice defined as universe 10 (not shown in full)
% ...

% Core lattice arranging assemblies
lat core 1 0.0 0.0 5 5 21.42
11 11 11 11 11
11 10 10 10 11
11 10 12 10 11
11 10 10 10 11
11 11 11 11 11

% Universe 10: standard fuel assembly
% Universe 11: reflector assembly (water-filled)
% Universe 12: control assembly

surf core_bound cuboid -53.55 53.55 -53.55 53.55 -180 180
surf refl_bound cuboid -75.0 75.0 -75.0 75.0 -200 200

cell core_region 0 fill core -core_bound
cell reflector   0 water     -refl_bound core_bound
cell exterior    0 outside    refl_bound

Common Errors and Debugging

The most frequent lattice error is a mismatch between the declared dimensions and the actual number of entries in the universe map. If you declare a 17x17 lattice but provide only 16 rows or a row with 16 entries, Serpent will report a parsing error. Count your rows and columns carefully.

Referencing an undefined universe in the lattice map produces an error during initialization. Make sure every integer in the map corresponds to a universe with at least one cell defined. For positions outside the active assembly region in hexagonal lattices, define a "filler" universe containing only water or void.

When debugging lattice geometries, start with a smaller lattice (3x3 or 5x5) to verify that the pin universes and the lattice placement work correctly. Once the small model runs without geometry errors, scale up to the full size. The geometry plotting capability is essential for verifying lattice-based models — always generate a plot before running a production calculation.

Related Topics

❮ Cell DefinitionsUniverse Concept ❯