SERPENT Guide

❮ Introduction to SerpentBasic Concepts & Workflow ❯

Installing Serpent

Before You Begin

Serpent installation requires attention to several details that can trip up new users. This guide walks you through each step, with special focus on common issues students encounter.

Student Tip: Before starting your own installation, check if your university already provides Serpent access. Many institutions have centralized installations that save you time and effort.

System Requirements

Minimum Requirements

  • 4GB RAM (8GB+ recommended)
  • 20GB free disk space
  • Linux/Unix environment
  • C/C++ compiler (GCC 4.6+)

Recommended Setup

  • 16GB+ RAM for large models
  • Multi-core processor
  • SSD storage
  • Modern Linux distribution

Obtaining Serpent

Serpent is proprietary software distributed through official channels. The process varies depending on your location and institutional affiliation.

For Academic Users

Most universities have institutional licenses. Contact your department's IT support or nuclear engineering faculty before requesting individual access.

Official Distribution Channels

OECD/NEA Data Bank

For users in NEA member countries (US, most of Europe, Japan, Australia, etc.)

  • Submit request through institutional contact
  • Typically 2-4 week processing time
  • Includes source code and documentation

RSICC (Oak Ridge)

Primary distribution center for US users

  • Requires US citizenship or permanent residence
  • University sponsor often required
  • Free for academic use

Important: Never download Serpent from unofficial sources. These may contain outdated versions, malware, or violate licensing terms.

Choosing Your Platform

Serpent runs best on Linux systems. Here are your options as a student:

Recommended: Native Linux

Best performance and compatibility. Popular distributions for scientific computing: Ubuntu 20.04+, CentOS 8+, or Fedora 33+.

Good Alternative: WSL2 (Windows)

Windows Subsystem for Linux provides near-native performance. Requires Windows 10/11 with WSL2 enabled.

Last Resort: Virtual Machine

Works but with performance penalty. Use VirtualBox or VMware with at least 8GB RAM allocated to the VM.

Installation Process

Step 1: Prepare Your Environment

First, install required development tools:

bash
# Ubuntu/Debian
sudo apt update
sudo apt install build-essential gfortran cmake git

# CentOS/RHEL/Fedora
sudo yum install gcc gcc-c++ gcc-gfortran make cmake git
# or for newer versions:
sudo dnf install gcc gcc-c++ gcc-gfortran make cmake git

Step 2: Extract and Compile Serpent

Once you have the Serpent distribution file:

bash
# Extract the distribution
tar -xzf serpent-2.1.32.tar.gz
cd serpent-2.1.32

# Create build directory (recommended)
mkdir build
cd build

# Configure the build
../configure --enable-openmp

# Compile (this may take 10-30 minutes)
make -j$(nproc)

# Optionally install system-wide
sudo make install

Compilation Notes:

  • The -j$(nproc) flag uses all CPU cores for faster compilation
  • OpenMP enables parallel processing within Serpent
  • System-wide installation is optional; you can run from the build directory

Step 3: Install Nuclear Data Libraries

Serpent requires nuclear cross-section data. The most commonly used libraries are ENDF/B-VII.1 or VIII.0:

bash
# Create data directory
sudo mkdir -p /opt/serpent/data
sudo chown $USER:$USER /opt/serpent/data

# Extract nuclear data (example for ENDF/B-VII.1)
cd /opt/serpent/data
tar -xzf endfb71_ace.tar.gz

# Set environment variable permanently
echo 'export SERPENT_DATA=/opt/serpent/data' >> ~/.bashrc
source ~/.bashrc

Alternative: Local Installation

If you can't install system-wide:

bash
# Create local data directory
mkdir -p $HOME/serpent/data
cd $HOME/serpent/data

# Extract data files here
# Add to your .bashrc:
echo 'export SERPENT_DATA=$HOME/serpent/data' >> ~/.bashrc

Verification and Testing

Always verify your installation before starting real work:

Basic Version Check

bash
# Check Serpent version and build info
sss2 -version

# Expected output should show:
# Serpent 2.1.32 -- (Month DD YYYY)
# Built with OpenMP support

Run Built-in Test

bash
# Create test directory
mkdir ~/serpent_test
cd ~/serpent_test

# Run simple test problem
sss2 -test pwr_pin

# This should create several output files
ls -la *_res.m *_det.m

Success Indicators:

  • No error messages during compilation
  • Version command shows correct build information
  • Test problem completes without errors
  • Output files contain reasonable results (k-eff around 1.2-1.3 for test pin)

Common Installation Issues

Compilation Fails

Symptoms: Errors during make command

Solutions:

  • Ensure all development tools are installed
  • Try make clean then make again
  • Check compiler version: GCC 4.6 or newer required
  • For older systems, try ./configure --disable-openmp

Cross Section Library Not Found

Symptoms: "XS data directory not found" errors

Solutions:

  • Verify SERPENT_DATA environment variable: echo $SERPENT_DATA
  • Check that data files exist in the specified directory
  • Ensure proper file permissions on data directory
  • Try specifying library path directly in input file

Permission Denied Errors

Symptoms: Cannot write output files or access directories

Solutions:

  • Run from your home directory or a directory you own
  • Check file permissions with ls -la
  • Avoid running as root unless absolutely necessary

Performance Issues

Symptoms: Very slow simulation speed

Solutions:

  • Verify OpenMP is enabled: check version output
  • Set appropriate number of threads: export OMP_NUM_THREADS=4
  • Ensure adequate RAM for your problem size
  • Consider SSD storage for large nuclear data libraries

WSL2 Installation (Windows Users)

For Windows users, WSL2 provides an excellent way to run Serpent with near-native performance:

Enable WSL2

powershell
# In PowerShell (as Administrator)
wsl --install

# Reboot when prompted
# Install Ubuntu from Microsoft Store

Configure WSL2 for Serpent

bash
# In Ubuntu WSL terminal
# Update package manager
sudo apt update && sudo apt upgrade -y

# Install required tools
sudo apt install build-essential gfortran cmake git

# Follow standard Linux installation steps above

WSL2 Tips:

  • Access Windows files via /mnt/c/
  • Install Windows Terminal for better experience
  • Use VSCode with WSL extension for editing
  • Allocate sufficient memory in .wslconfig

Getting Help

If you encounter issues not covered here:

  • Serpent Forum: ttuki.vtt.fi/serpent - Active community support
  • Documentation: serpent.vtt.fi/mediawiki - Official documentation
  • Your Instructor: Academic installations often have local expertise
  • IT Support: For university system-related issues

Forum Etiquette: When posting questions, include your Serpent version, operating system, error messages, and what you've already tried. This helps others provide better assistance.

Related Topics

❮ Introduction to SerpentBasic Concepts & Workflow ❯