Visualization Tools in Serpent

The Role of Visualization in Monte Carlo Modeling

Visualization is the first and most effective line of defense against geometry errors in Monte Carlo particle transport modeling. A single mistake in cell definitions, surface equations, or universe placement can silently invalidate an entire calculation, often producing results that appear plausible but are in fact wrong. Visual inspection catches errors that are nearly impossible to identify by reading input text alone.

The types of errors that visualization readily reveals include undefined regions (gaps in the geometry where no cell is defined), overlapping cells that create ambiguous material assignments, incorrect surface orientations that swap the inside and outside of a region, lattice placement errors where periodic structures do not tile correctly, wrong material assignments to cells, and boundary condition mismatches between the geometry and the problem specification. Most of these errors will not generate explicit error messages from the code but will instead produce subtly incorrect results.

Basic Geometry Plots

Serpent generates geometry plots through the plot card in the input file. The most basic form creates a two-dimensional cross-section of the model at a specified position, rendered as a raster image where each pixel is colored according to the material occupying that point in space. The plot card takes several parameters that control the viewing plane, resolution, position, and extent of the image.

% Basic geometry plot (type 3 = XY plane, material colors)
plot 3 800 800 0 -2.0 2.0 -2.0 2.0

% Close-up view of a single pin (XY plane)
plot 3 800 800 0 -0.7 0.7 -0.7 0.7

% Wider view showing surrounding area (XY plane)
plot 3 800 800 0 -2.0 2.0 -2.0 2.0

% Check at a different axial position (XY plane, z=10 cm)
plot 3 800 800 10 -0.7 0.7 -0.7 0.7

Plot Types and Their Applications

Serpent supports several plot types that reveal different aspects of the geometry model. The default material plot colors each region according to its material assignment and is the most commonly used type for verifying that materials are placed in the correct locations. Cell plots display cell boundaries and identifiers, which is particularly useful for debugging overlapping or undefined regions. Density plots show material densities using a color gradient, helpful for verifying coolant density variations in thermal-hydraulic coupling studies. Temperature plots display material temperatures when thermal feedback models are active.

% Material-colored XY plot (type 3)
plot 3 800 800 0 -2.0 2.0 -2.0 2.0

% Cell-colored XY plot (type 3 + 10 = 13)
plot 13 800 800 0 -2.0 2.0 -2.0 2.0

% Material-colored XZ plot (side view, type 2)
plot 2 800 800 0 -2.0 2.0 -2.0 2.0

% Cell-colored XZ plot (side view, type 12)
plot 12 800 800 0 -2.0 2.0 -2.0 2.0

Customizing Plot Appearance

The default color assignments in Serpent plots are often difficult to interpret, particularly for models with many materials. Custom color definitions using the rgb card make plots substantially more readable by assigning intuitive colors to each material. A consistent color scheme applied across all models in a project allows rapid interpretation without consulting a legend. Red tones are conventionally used for fuel materials, gray tones for structural materials like cladding and pressure vessel steel, and blue tones for coolant.

% Colors are set with the rgb keyword on the mat card
% Syntax: mat NAME DENSITY rgb R G B
mat fuel  -10.4  tmp 900 rgb 255 150 150  % Light red for fuel
mat clad  -6.56  tmp 600 rgb 180 180 180  % Gray for cladding
mat water -0.714 tmp 574 rgb 150 150 255  % Light blue for water

% Material plots will now use these colors
plot 3 800 800 0 -2.0 2.0 -2.0 2.0

% High-resolution XY plot for detailed inspection
plot 3 1500 1500 0 -1.5 1.5 -1.5 1.5

Advanced Visualization Techniques

The XY plane view is the default perspective, but XZ and YZ views are essential for verifying axial features such as fuel rod plenums, grid spacers, and reflector regions. Use multiple zoom levels: macro-scale to confirm overall structure, standard scale for assembly or lattice detail, and micro-scale for individual pins and sub-pin features.

% XY view - type 3 (looking down from above)
plot 3 800 800 0 -10 10 -10 10

% XZ view - type 2 (looking from the side)
plot 2 800 800 0 -10 10 -150 150

% YZ view - type 1 (looking from the front)
plot 1 800 800 0 -10 10 -150 150

% Macro view - see the big picture (XY plane)
plot 3 1200 1200 0 -50 50 -50 50

% Standard view - normal working scale (XY plane)
plot 3 1000 1000 0 -12 12 -12 12

% Micro view - check individual pins (XY plane)
plot 3 800 800 0 -1.5 1.5 -1.5 1.5

% Ultra close-up - verify small features (XY plane)
plot 3 600 600 0 -0.6 0.6 -0.6 0.6

% Zoom in on a single pin within the lattice
plot 3 800 800 0 -0.7 0.7 -0.7 0.7

% Full assembly view showing all pins
plot 3 1200 1200 0 -15 15 -15 15

Debugging with Visualization

When a model exhibits unexpected behavior, visualization provides the most direct diagnostic pathway. Certain visual patterns are characteristic of specific geometry errors. Black regions in a plot indicate undefined space where no cell covers the location, requiring additional cell definitions or corrections to surface equations. Unexpected colors indicate material misassignment, typically caused by spelling errors in material names or incorrect cell-material associations. Features that appear truncated or clipped often point to lattice or universe boundary problems where the periodic structure does not properly fill its containing region. Misaligned components suggest errors in transformation parameters or coordinate system definitions.

% Step 1: Cell plot zoomed in on individual pin positions
plot 13 800 800 0 -0.7 0.7 -0.7 0.7

% Step 2: Cell plot of interface regions between pins
plot 13 1000 1000 0 -5 5 -5 5

% Step 3: Material plot to check assignments
plot 3 1000 1000 0 -5 5 -5 5

% Step 4: Full overview with material colors
plot 3 1200 1200 0 -20 20 -20 20

Workflow Integration and Best Practices

Generate plots after each major model-building milestone: after defining materials, after creating each universe, after assembling lattices, and before launching production calculations. Incremental verification catches errors when they are easiest to diagnose and correct.

% Standard verification plots for any reactor model
% Colors are defined on the mat card, e.g.:
% mat fuel -10.4 rgb 255 150 150
% mat clad -6.56 rgb 180 180 180
% mat water -0.714 rgb 150 150 255

% Overview material plot (XY plane)
plot 3 1200 1200 0 -20 20 -20 20

% Overview cell plot (XY plane, cell colors)
plot 13 1200 1200 0 -20 20 -20 20

% Detail material plot (XY plane)
plot 3 1000 1000 0 -5 5 -5 5

% Axial view (XZ plane)
plot 2 1200 800 0 -20 20 -150 150

% Pin-level cross-section (XY plane)
plot 3 800 800 0 -2 2 -2 2

External Visualization Tools

Serpent can export mesh data in formats compatible with ParaView, MATLAB, and Python visualization libraries. These tools support overlaying physics results (flux distributions, power maps, temperature fields) onto the geometry, creating animated burnup sequences, and producing publication-quality figures.

% Create mesh plot for external visualization
mesh 3 100 100 0 -20 20 -20 20

% This creates a dataset that can be imported into:
% - ParaView for scientific visualization
% - MATLAB for custom analysis
% - Python with VTK or matplotlib

% Define detectors for flux visualization
det flux_map dm fuel de energy_grid

% Energy grid for thermal/fast split (type 1 = arbitrary boundaries)
ene energy_grid 1 1E-11 0.625E-6 20.0

% Create detector mesh
mesh 3 100 100

% Plot results overlaid on geometry
plot 3 1000 1000 0 -10 10 -10 10