SERPENT Guide

❮ Cell DefinitionsUniverse Concept ❯

Lattice Structures in Serpent

Lattice Fundamentals

Lattices in Serpent are powerful tools for creating repeated geometric structures, such as fuel assemblies in nuclear reactors. They allow you to define a pattern once and replicate it across space, greatly simplifying geometry definitions for complex systems.

The Lattice Concept

A lattice in Serpent is a regular arrangement of universes. Each universe can contain its own set of cells and materials. By using universes and lattices together, you can create complex hierarchical geometries with minimal input.

Key Concept: In Serpent, lattices are collections of universes arranged in a regular pattern. Each universe can contain any valid geometry configuration, allowing for complex nested structures.

Universe and Lattice Relationship

Before diving into lattices, it's important to understand the universe concept in Serpent:

  • Universe: A self-contained geometry definition that can be reused
  • Base Universe: The top-level universe (0) that contains everything
  • Lattice: A regular arrangement of universes in a defined pattern
  • Lattice Cell: A cell that is filled with a lattice rather than a material

Basic Lattice Types

Serpent supports several lattice types to accommodate different geometric arrangements:

Rectangular (Cartesian) Lattices

Rectangular lattices arrange universes in a regular grid pattern:

text
% Define a rectangular lattice
lat square_lattice 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 syntax for a rectangular lattice is:

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

Where:

  • NAME: Lattice name
  • ID: Lattice ID number
  • x0 y0: Coordinates of the lattice center
  • nx ny: Number of lattice elements in x and y directions
  • pitch: Lattice element pitch (width/height)
  • universe map: 2D map of universe IDs to fill the lattice

Hexagonal Lattices

Hexagonal lattices are used for modeling reactors with hexagonal fuel assemblies:

text
% Define a hexagonal lattice
lat hex_lattice 2 0.0 0.0 7 7 2.1
5 5 5 5 5 5 5
 5 5 5 5 5 5 5
  5 5 1 1 1 5 5
   5 5 1 2 1 5 5
    5 5 1 1 1 5 5
     5 5 5 5 5 5 5
      5 5 5 5 5 5 5

The syntax for a hexagonal lattice is similar to rectangular lattices, but with a different layout:

text
lat NAME ID x0 y0 nx ny pitch
[universe map with staggered rows]

Tip: For hexagonal lattices, pay close attention to the indentation in the universe map. Each row is indented to reflect the staggered nature of a hexagonal grid. The number of spaces at the beginning of each line is important for correct interpretation.

Circular Lattices

Circular lattices arrange universes in concentric rings:

text
% Define a circular lattice
lat circ_lattice 3 0.0 0.0 8
3 % Center universe
6 % Number of universes in the first ring
1 1 1 1 1 1 % Universe IDs for first ring
6 % Number of universes in the second ring
2 2 2 2 2 2 % Universe IDs for second ring

The syntax for a circular lattice is different from the rectangular and hexagonal types:

text
lat NAME ID x0 y0 NR
center_universe
n_universes_ring_1
universe_ids_ring_1
n_universes_ring_2
universe_ids_ring_2
...

Where:

  • NR: Number of rings in the lattice
  • center_universe: Universe ID at the center
  • n_universes_ring_i: Number of universes in ring i
  • universe_ids_ring_i: List of universe IDs in ring i

Creating Universe Structures

Before creating lattices, you need to define the universes that will be placed in the lattice:

Basic Universe Definition

Universes are collections of cells with a unique ID:

text
% Define surfaces
surf fuel_rad cylz 0.0 0.0 0.41
surf clad_rad cylz 0.0 0.0 0.47

% Define pin universe (ID 1)
cell fuel1 1 fuel   -fuel_rad      % Fuel in universe 1
cell clad1 1 zirc   -clad_rad fuel_rad  % Cladding in universe 1
cell mod1  1 water  clad_rad           % Moderator in universe 1

% Define guide tube universe (ID 2)
surf guide_in  cylz 0.0 0.0 0.56
surf guide_out cylz 0.0 0.0 0.60
cell guide2 2 zirc   -guide_out guide_in  % Guide tube in universe 2
cell water2 2 water  -guide_in            % Water inside guide in universe 2
cell mod2   2 water  guide_out            % Water outside guide in universe 2

% Define outer water universe (ID 3)
cell water3 3 water  -1000           % Just water everywhere in universe 3

Universe Nesting

Universes can be nested by using the fill keyword in a cell definition:

text
% Define a boundary for a pin cell
surf pin_bound rect -0.63 0.63 -0.63 0.63 -10 10

% Create universe 10 containing a fuel pin from universe 1
cell pin_cell 10 fill 1 -pin_bound
cell outside 10 outside pin_bound

Pro Tip: When working with universes, it's helpful to use a consistent naming convention. For example, use universe IDs 1-99 for pin-level definitions, 100-199 for assembly-level, and 200+ for core-level structures.

Using Lattices in Cells

Once you've defined your lattices, you need to place them in cells:

Basic Lattice Placement

Place a lattice in a cell using the fill keyword with the lattice ID:

text
% Define a boundary for the lattice
surf assy_bound rect -10.5 10.5 -10.5 10.5 -100 100

% Create a cell filled with lattice 1
cell assy 0 fill 1 -assy_bound   % Fill with lattice ID 1
cell outside 0 outside assy_bound

Lattice Transformations

You can apply transformations to lattices within cells:

text
% Define a boundary for the lattice
surf assy_bound rect -10.5 10.5 -10.5 10.5 -100 100

% Create a cell filled with lattice 1, rotated 90 degrees around z-axis
cell assy 0 fill 1 -assy_bound    % Fill with lattice ID 1
trcl assy 0.0 0.0 0.0 0.0 0.0 90.0  % Rotate the cell (and its lattice)

Important Note: The trcl transformation applies to the cell, not the lattice directly. When a cell containing a lattice is transformed, the entire lattice structure within the cell is transformed.

Practical Lattice Examples

Example 1: PWR Fuel Assembly

A complete example of a 17×17 PWR fuel assembly using lattices:

text
% Define pin surfaces
surf fuel_rad cylz 0.0 0.0 0.41
surf clad_rad cylz 0.0 0.0 0.475

% Define guide tube surfaces
surf guide_in cylz 0.0 0.0 0.56
surf guide_out cylz 0.0 0.0 0.60

% Define pin universes
% Fuel pin (universe 1)
cell fuel_pellet 1 uo2    -fuel_rad
cell fuel_clad   1 zirc4  -clad_rad fuel_rad
cell fuel_water  1 water  clad_rad

% Guide tube (universe 2)
cell guide_tube  2 zirc4  -guide_out guide_in
cell guide_water_in 2 water -guide_in
cell guide_water_out 2 water guide_out

% Instrument tube (universe 3) - similar to guide tube but different material
cell instr_tube  3 zirc4  -guide_out guide_in
cell instr_water_in 3 water -guide_in
cell instr_water_out 3 water guide_out

% Define 17x17 PWR lattice
lat pwr_lattice 10 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

% Define assembly boundary
surf assy_bound rect -10.71 10.71 -10.71 10.71 -180 180

% Create assembly universe
cell assembly 0 fill 10 -assy_bound
cell exterior 0 outside assy_bound

Example 2: VVER Hexagonal Assembly

An example of a VVER-style hexagonal fuel assembly:

text
% Define pin surfaces
surf fuel_rad cylz 0.0 0.0 0.38
surf clad_rad cylz 0.0 0.0 0.455

% Define universes
cell fuel_pin 1 uo2   -fuel_rad
cell clad     1 zirc  -clad_rad fuel_rad
cell water1   1 h2o   clad_rad

cell water2   2 h2o   -1000  % Water-only universe

% Define hexagonal lattice (VVER-style)
lat hex_assy 10 0.0 0.0 11 11 0.7
2 2 2 2 2 2 2 2 2 2 2
 2 2 2 2 2 2 2 2 2 2 2
  2 2 2 2 1 1 1 2 2 2 2
   2 2 2 1 1 1 1 1 2 2 2
    2 2 1 1 1 1 1 1 1 2 2
     2 2 1 1 1 1 1 1 1 2 2
      2 2 1 1 1 1 1 1 1 2 2
       2 2 1 1 1 1 1 2 2 2 2
        2 2 2 1 1 1 2 2 2 2 2
         2 2 2 2 2 2 2 2 2 2 2
          2 2 2 2 2 2 2 2 2 2 2

% Define hexagonal assembly boundary
surf hex_bound hexxc 0.0 0.0 8.0

% Place the lattice in the assembly
cell hex_cell  0 fill 10 -hex_bound
cell exterior  0 outside hex_bound

Example 3: Full Core with Nested Lattices

A simplified reactor core model using nested lattices:

text
% [Pin and assembly definitions as above]

% Define core lattice (assembly pattern)
lat core_lat 20 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

% Where universe 10 is the fuel assembly defined earlier
% Universe 11 is a reflector assembly
% Universe 12 might be a control assembly

% Define core boundary
surf core_bound rect -55.0 55.0 -55.0 55.0 -180.0 180.0
surf refl_bound rect -75.0 75.0 -75.0 75.0 -200.0 200.0

% Place core lattice
cell core      0 fill 20 -core_bound
cell reflector 0 water  -refl_bound core_bound
cell outside   0 outside refl_bound

Modeling Strategy: When building complex reactor models, consider a bottom-up approach:

  1. Start with pin-level universes (fuel, guide tubes, etc.)
  2. Build assembly-level lattices using these pin universes
  3. Create core-level lattices using the assembly universes
This hierarchical approach makes the model more maintainable and follows the physical organization of a reactor.

Advanced Lattice Techniques

3D Lattices

Serpent supports 3D lattices by extending the 2D lattice definition:

text
% 3D rectangular lattice
lat 3d_lattice 30 0.0 0.0 0.0 5 5 3 1.26 20.0
% x-y plane, z-level 1
1 1 1 1 1
1 2 2 2 1
1 2 3 2 1
1 2 2 2 1
1 1 1 1 1
% x-y plane, z-level 2
2 2 2 2 2
2 3 3 3 2
2 3 4 3 2
2 3 3 3 2
2 2 2 2 2
% x-y plane, z-level 3
1 1 1 1 1
1 2 2 2 1
1 2 3 2 1
1 2 2 2 1
1 1 1 1 1

Partial Lattices and Boundaries

Sometimes you need lattices with irregular boundaries or missing elements:

text
% Define surfaces for an irregular boundary
surf bound1 cylz 0.0 0.0 15.0    % Circular boundary
surf cut1 px 0.0              % Cut plane

% Define universe 999 as "outside"
cell outside_cell 999 outside -1000

% Define partial lattice 
lat partial 40 0.0 0.0 7 7 2.0
999 999 999  10  10  10 999
 999  10  10  10  10  10 999
  10  10  10  10  10  10  10
   10  10  10  10  10  10 999
    10  10  10  10  10 999 999
     10  10  10  10 999 999 999
      999 999 999 999 999 999 999

% Place lattice in a cell with the irregular boundary
cell core_region 0 fill 40 -bound1 cut1    % Inside cylinder, right of cut plane
cell outside     0 outside bound1 : -cut1  % Outside the active region

Lattice Colorization for Visualization

You can set colors for different universes to improve visualization:

text
% Set RGB colors for different universes
rgb 1 255 200 200   % Fuel pins (reddish)
rgb 2 150 200 255   % Guide tubes (bluish)
rgb 3 255 255 150   % Instrument tube (yellowish)

% Use the 'set gcu' command to generate a geometry plot
set gcu 10

Debugging Tip: When working with complex lattices, visualization is key. Use the set gcu command with the universe ID to generate plots of your lattice structure at different levels. These plots can help identify errors in your lattice definitions.

Common Lattice Errors and Pitfalls

Working with lattices can introduce specific challenges:

Lattice Indexing Errors

  • Make sure the number of elements in your lattice definition matches the dimensions
  • Check for typos in the universe IDs within the lattice map
  • For hexagonal lattices, ensure proper indentation of each row

Universe Definition Issues

  • Ensure all universes used in the lattice are properly defined
  • Check that each universe is self-contained with proper boundary conditions
  • Avoid conflicting cell definitions within the same universe

Boundary Problems

  • Make sure the cell containing the lattice is large enough to accommodate the entire lattice
  • Check for overlaps between the lattice and other geometry components
  • Ensure proper boundary conditions where the lattice meets other structures

Troubleshooting Tip: If you encounter issues with lattices, try simplifying the problem. Start with a smaller lattice (e.g., 3×3 instead of 17×17) to verify the basic structure works, then expand gradually to the full size.

Performance Considerations

Lattices can affect the computational efficiency of your simulations:

Memory Usage

  • Large lattices can consume significant memory, especially with many unique universes
  • Use the same universe ID for identical structures to reduce memory usage
  • Consider using the set opt command to optimize memory usage for large models

Tracking Efficiency

  • Particle tracking in lattices is generally very efficient in Serpent
  • Nested lattices (lattices within lattices) can slow down tracking somewhat
  • Very deep nesting levels (more than 3-4) should be avoided if possible

Optimization Strategies

Some strategies to optimize lattice-based models:

text
% Set geometry optimization options
set opt 1  % Enable geometry optimization

% Use symmetry when possible
set sym 4  % Quarter-core symmetry (for square lattices)

Performance Tip: When working with very large reactor core models, consider whether you need to model every pin explicitly. For some applications, homogenized regions may be sufficient and much more computationally efficient.

Summary

Lattices are essential tools for efficient reactor modeling in Serpent:

  • Serpent supports rectangular, hexagonal, and circular lattice types
  • Lattices are collections of universes arranged in a regular pattern
  • Universe definitions allow for reuse of geometric components
  • Nested lattices enable hierarchical modeling from pins to assemblies to full cores
  • Proper visualization and debugging are crucial for complex lattice structures
  • Memory usage and tracking efficiency should be considered for large models

In the next section, we'll explore the universe concept in more detail, including advanced techniques for universe transformations and nesting.

Related Topics

❮ Cell DefinitionsUniverse Concept ❯