SERPENT Guide
Visualization Tools in Serpent
Why Visualization Matters
Visualization is your first line of defense against geometry errors in Monte Carlo modeling. A single mistake in cell definitions, surface equations, or universe placement can invalidate an entire calculation, often without obvious warning signs.
Reality Check: Most geometry errors are caught by visualization, not by staring at input files. Even experienced users rely heavily on plots to verify their models. Make visualization a standard part of your modeling workflow, not an afterthought.
What Visualization Catches
Geometry Errors
- Undefined regions (gaps in geometry)
- Overlapping cells
- Wrong surface orientations
- Incorrect lattice placements
Physics Errors
- Wrong material assignments
- Missing materials in regions
- Incorrect universe definitions
- Boundary condition problems
Student Success Tip: Generate plots after every major step in model building. Don't wait until the end to check your work. Catching errors early saves hours of debugging later.
Your First Plot
Let's start with the most basic visualization - a simple 2D plot of your geometry:
% Basic geometry plot
plot 1 800 800 0 -2.0 2.0 -2.0 2.0Understanding Plot Parameters
plot ID WIDTH HEIGHT Z_POSITION X_MIN X_MAX Y_MIN Y_MAX
- ID: Unique number for this plot (1, 2, 3, etc.)
- WIDTH/HEIGHT: Image resolution in pixels (800×800 is good for start)
- Z_POSITION: Where to "slice" through your 3D model (0 = XY plane)
- X_MIN, X_MAX, Y_MIN, Y_MAX: What region to show (in cm)
Your First Real Example
For a fuel pin model, start with these plots:
% Close-up view of a single pin
plot 1 800 800 0 -0.7 0.7 -0.7 0.7
% Wider view showing surrounding area
plot 2 800 800 0 -2.0 2.0 -2.0 2.0
% Check if there are any axial features
plot 3 800 800 10 -0.7 0.7 -0.7 0.7 % 10 cm above midplaneQuick Start: Add these three plots to any new model you create. They provide a good baseline for catching common errors before you spend time on detailed analysis.
Plot Types and What They Show
Serpent offers different plot types for different purposes. Each type reveals different aspects of your model:
Material Plots (Default)
% Material plot - shows which material is in each region
plot 1 800 800 0 -2.0 2.0 -2.0 2.0Best for: Verifying material assignments, checking fuel/clad/coolant regions
Cell Plots
% Cell plot - shows cell boundaries and IDs
plot 2 800 800 0 -2.0 2.0 -2.0 2.0 3Best for: Debugging cell definitions, finding overlaps or gaps
Density Plots
% Density plot - shows material densities
plot 3 800 800 0 -2.0 2.0 -2.0 2.0 9Best for: Checking density variations, verifying coolant density changes
Temperature Plots
% Temperature plot - shows material temperatures
plot 4 800 800 0 -2.0 2.0 -2.0 2.0 12Best for: Verifying temperature distributions, checking thermal feedback models
Debugging Strategy: When troubleshooting, always check both material plots (type 0) and cell plots (type 3). Material plots show what you intended, cell plots show what Serpent actually sees.
Making Plots Readable
Default colors are often confusing. Custom colors make your plots much more interpretable:
Setting Material Colors
% Define intuitive colors for common materials
rgb fuel 255 150 150 % Light red for fuel
rgb clad 180 180 180 % Gray for cladding
rgb water 150 150 255 % Light blue for water
rgb steel 120 120 120 % Dark gray for steel
rgb air 255 255 255 % White for air/void
% Now your material plots will use these colors
plot 1 800 800 0 -2.0 2.0 -2.0 2.0Adding Labels and Titles
% Plot with descriptive title and axis labels
plot 1 1000 1000 0 -1.5 1.5 -1.5 1.5
"PWR Fuel Pin Cross-Section"
"X (cm)" "Y (cm)"Color Strategy for Common Reactor Components
Fuel Components
rgb fuel 255 100 100- Red for UO₂rgb mox 255 150 100- Orange for MOXrgb poison 100 255 100- Green for burnable poison
Structural Materials
rgb clad 150 150 150- Gray for zircaloyrgb steel 100 100 100- Dark gray for steelrgb water 100 100 255- Blue for water
Pro Tip: Create a standard color scheme and reuse it across all your models. This makes it easier to quickly interpret plots and spot anomalies.
Advanced Visualization Techniques
Multiple Views of the Same Model
Complex 3D geometries require multiple viewing angles:
% XY view (looking down from above)
plot 1 800 800 0 -10 10 -10 10
"XY View - Looking Down" "X (cm)" "Y (cm)"
% XZ view (looking from the side)
plot 2 800 800 0 -10 10 -150 150 0 0 1 0
"XZ View - Side View" "X (cm)" "Z (cm)"
% YZ view (looking from the front)
plot 3 800 800 0 -10 10 -150 150 0 0 0 1
"YZ View - Front View" "Y (cm)" "Z (cm)"Zooming In and Out
Use multiple zoom levels to verify both details and overall structure:
% Macro view - see the big picture
plot 1 1200 1200 0 -50 50 -50 50 "Full Assembly"
% Standard view - normal working scale
plot 2 1000 1000 0 -12 12 -12 12 "Assembly Detail"
% Micro view - check individual pins
plot 3 800 800 0 -1.5 1.5 -1.5 1.5 "Single Pin Detail"
% Ultra close-up - verify small features
plot 4 600 600 0 -0.6 0.6 -0.6 0.6 "Pin Internal Structure"Universe-Level Visualization
For complex hierarchical models, focus on specific universes:
% Plot a specific universe in isolation
set gcu 1 % Switch to universe 1
plot 1 800 800 0 -1 1 -1 1 % Plot just this universe
"Universe 1 - Fuel Pin" "X (cm)" "Y (cm)"
% Switch back to global view
set gcu -1 % Back to global coordinates
plot 2 1200 1200 0 -15 15 -15 15 % Plot everything
"Global View" "X (cm)" "Y (cm)"Systematic Approach: For complex models, use this progression:
- Start with individual universes (
set gcu) - Move to assembly-level views
- Finish with full system views
- Use multiple viewing planes for each level
Debugging with Visualization
Common Visual Clues to Problems
⚠️ Black Regions
What it means: Undefined space - no cell covers this region
Fix: Add cells to cover all space, check for gaps between surfaces
⚠️ Wrong Colors
What it means: Material assigned to wrong cell
Fix: Check material names in cell definitions, verify spelling
⚠️ Cut-off Features
What it means: Lattice or universe boundary problems
Fix: Check lattice size vs. containing cell, verify universe boundaries
⚠️ Misaligned Components
What it means: Transformation or positioning errors
Fix: Check transformation parameters, verify coordinate systems
Systematic Debugging Process
When your model has problems, follow this debugging sequence:
% Step 1: Check individual universes
set gcu 1
plot 1 800 800 0 -1 1 -1 1 3 % Cell plot of universe 1
set gcu 2
plot 2 800 800 0 -1 1 -1 1 3 % Cell plot of universe 2
% Step 2: Check interface regions
set gcu -1
plot 3 1000 1000 0 -5 5 -5 5 3 % Cell plot of interfaces
% Step 3: Check material assignments
plot 4 1000 1000 0 -5 5 -5 5 0 % Material plot
% Step 4: Verify overall structure
plot 5 1200 1200 0 -20 20 -20 20 % Full overviewDebugging Mindset: Assume your geometry has errors until proven otherwise. Even small models benefit from systematic visual checking. The time spent on visualization always pays off in reduced debugging time later.
Practical Workflow Integration
Development Workflow
Build visualization into your modeling process from the start:
Recommended Workflow:
- After defining materials: Create material test plots
- After each universe: Plot universe in isolation
- After lattice creation: Plot lattice structure
- After full assembly: Generate comprehensive plot set
- Before production runs: Final verification plots
Standard Plot Set for Any Model
% Standard verification plots for any reactor model
% Define colors first
rgb fuel 255 150 150
rgb clad 180 180 180
rgb water 150 150 255
rgb steel 120 120 120
% Plot 1: Overview material plot
plot 1 1200 1200 0 -20 20 -20 20 0
"Material Overview" "X (cm)" "Y (cm)"
% Plot 2: Overview cell plot
plot 2 1200 1200 0 -20 20 -20 20 3
"Cell Overview" "X (cm)" "Y (cm)"
% Plot 3: Detail material plot
plot 3 1000 1000 0 -5 5 -5 5 0
"Material Detail" "X (cm)" "Y (cm)"
% Plot 4: Axial view
plot 4 1200 800 0 -20 20 -150 150 0 0 1 0
"Axial View" "X (cm)" "Z (cm)"
% Plot 5: Cross-section verification
plot 5 800 800 0 -2 2 -2 2 0
"Pin Detail" "X (cm)" "Y (cm)"File Organization
Keep your plots organized and documented:
Best Practices:
- Save plots with descriptive filenames (e.g., "pwr_assembly_overview.png")
- Create a plots/ subdirectory in your project folder
- Document what each plot shows and why it's important
- Include key plots in your final reports and presentations
- Archive plots with your input files for future reference
Beyond Basic Visualization
Mesh Plots for External Visualization
For advanced visualization in external tools:
% Create 3D mesh for external visualization
mesh 1 geom 100 100 100 -20 20 -20 20 -150 150
% This creates a 3D dataset that can be imported into:
% - ParaView for scientific visualization
% - MATLAB for custom analysis
% - Python with VTK or matplotlibResult Visualization
Combine geometry plots with physics results:
% Define detectors for flux visualization
det flux_map dm fuel de energy_grid
% Energy grid for thermal/fast split
ene energy_grid 2 0.625e-6 20.0
% Create detector mesh
mesh 1 100 100
% Plot detector results overlaid on geometry
plot 10 1000 1000 0 -10 10 -10 10 8 1Advanced Tip: Learn to use external visualization tools like ParaView or Python matplotlib for publication-quality figures. Serpent's built-in plots are excellent for verification, but external tools offer more control for presentations.
Key Takeaways
Effective visualization is essential for successful Serpent modeling:
- Start early: Generate plots throughout model development, not just at the end
- Use multiple views: Different plot types and viewing angles reveal different problems
- Customize colors: Make plots readable with intuitive color schemes
- Be systematic: Follow a consistent debugging approach when issues arise
- Document everything: Save and organize plots for future reference
With solid visualization skills, you can catch geometry errors early, communicate your models effectively, and build confidence in your simulation results. The time invested in learning these tools pays dividends throughout your modeling career.