OpenMC Guide
Materials in OpenMC
Understanding Materials
Materials in OpenMC represent the physical substances in your reactor model. Each material needs a composition (what nuclides it contains), a density, and sometimes additional properties like temperature. OpenMC uses this information to calculate how neutrons interact with the material.
The basic workflow is simple: create a material object, set its density, add nuclides or elements, and optionally specify properties like temperature or thermal scattering data.
python
import openmc
# Basic UO2 fuel - the essential components
fuel = openmc.Material(name='UO2 Fuel')
fuel.set_density('g/cm3', 10.4) # Always set density first
fuel.add_nuclide('U235', 0.045) # 4.5% enriched uranium
fuel.add_nuclide('U238', 0.955) # Depleted uranium
fuel.add_element('O', 2.0) # Stoichiometric oxygen
# Light water with thermal scattering
water = openmc.Material(name='Light Water')
water.set_density('g/cm3', 1.0)
water.add_nuclide('H1', 2.0)
water.add_element('O', 1.0)
water.add_s_alpha_beta('c_H_in_H2O') # Critical for neutron thermalization
# Structural material
zirc = openmc.Material(name='Zircaloy-4')
zirc.set_density('g/cm3', 6.55)
zirc.add_element('Zr', 0.982)
zirc.add_element('Sn', 0.015)
zirc.add_element('Fe', 0.002)
zirc.add_element('Cr', 0.001)
print(f"Fuel density: {fuel.get_mass_density():.1f} g/cm³")
print(f"Water contains {len(water.nuclides)} nuclides")Practical Material Examples
Here are realistic material definitions you'll commonly encounter in reactor physics. These examples show proper composition and density values based on real reactor materials.
PWR Materials
python
# Standard PWR UO2 fuel pellet
fuel = openmc.Material(name='PWR UO2 Fuel')
fuel.set_density('g/cm3', 10.4)
fuel.add_nuclide('U235', 0.04) # 4% enrichment
fuel.add_nuclide('U238', 0.96)
fuel.add_element('O', 2.0)
fuel.temperature = 900 # Operating temperature (K)
# Zircaloy-4 cladding with realistic composition
clad = openmc.Material(name='Zircaloy-4 Cladding')
clad.set_density('g/cm3', 6.55)
clad.add_element('Zr', 0.982)
clad.add_element('Sn', 0.015)
clad.add_element('Fe', 0.002)
clad.add_element('Cr', 0.001)
# Borated water moderator (typical PWR conditions)
moderator = openmc.Material(name='Borated Water')
moderator.set_density('g/cm3', 0.7) # Hot, pressurized water
moderator.add_nuclide('H1', 2.0)
moderator.add_element('O', 1.0)
moderator.add_nuclide('B10', 0.00002) # 1000 ppm boron
moderator.add_nuclide('B11', 0.00008)
moderator.add_s_alpha_beta('c_H_in_H2O')
moderator.temperature = 580 # Typical PWR temperature
# Structural steel (for reactor internals)
steel = openmc.Material(name='Stainless Steel 316')
steel.set_density('g/cm3', 8.0)
steel.add_element('Fe', 0.68, 'wo') # Weight fractions
steel.add_element('Ni', 0.12, 'wo')
steel.add_element('Cr', 0.17, 'wo')
steel.add_element('Mo', 0.025, 'wo')
steel.add_element('Mn', 0.02, 'wo')Advanced Fuel Types
python
# MOX fuel (mixed oxide with plutonium)
mox_fuel = openmc.Material(name='MOX Fuel')
mox_fuel.set_density('g/cm3', 10.8)
mox_fuel.add_nuclide('U235', 0.002) # Depleted uranium
mox_fuel.add_nuclide('U238', 0.948)
mox_fuel.add_nuclide('Pu239', 0.04) # 4% fissile Pu-239
mox_fuel.add_nuclide('Pu240', 0.01)
mox_fuel.add_element('O', 2.0)
# TRISO fuel particles (for advanced reactors)
triso_fuel = openmc.Material(name='TRISO Fuel Kernel')
triso_fuel.set_density('g/cm3', 10.5)
triso_fuel.add_nuclide('U235', 0.15) # Highly enriched
triso_fuel.add_nuclide('U238', 0.85)
triso_fuel.add_element('C', 1.0) # UC kernel
triso_fuel.temperature = 1200 # High temperature operation
# Graphite moderator (for HTGR)
graphite = openmc.Material(name='Nuclear Graphite')
graphite.set_density('g/cm3', 1.7)
graphite.add_element('C', 1.0)
graphite.add_s_alpha_beta('c_Graphite')
graphite.temperature = 1000Working with Material Collections
OpenMC requires all materials to be collected into a Materials object before running a simulation. This collection also provides useful methods for validation and manipulation.
python
# Create a complete materials collection
materials = openmc.Materials([fuel, clad, moderator, steel])
# Useful material collection methods
print(f"Total materials: {len(materials)}")
print(f"Material names: {[mat.name for mat in materials]}")
# Find materials by name
fuel_mat = materials.get_by_name('PWR UO2 Fuel')
print(f"Found material: {fuel_mat.name}")
# Export for use in OpenMC (performs validation)
materials.export_to_xml()
# You can also modify materials after creation
fuel.add_nuclide('Gd155', 0.001) # Add burnable absorber
print("Added gadolinium to fuel")Advanced Material Features
OpenMC supports sophisticated material modeling including mixtures, multiple temperatures, and depletion tracking. These features are essential for advanced reactor analysis.
Material Mixtures
python
# Create a homogeneous fuel-moderator mixture
# Useful for modeling very small geometries
fuel_water_mix = openmc.Material.mix_materials(
materials=[fuel, moderator],
fracs=[0.3, 0.7], # Volume fractions
percent_type='vo' # 'vo' = volume, 'wo' = weight
)
fuel_water_mix.name = 'Fuel-Water Mixture'
# Control rod material (B4C with steel cladding)
b4c = openmc.Material(name='Boron Carbide')
b4c.set_density('g/cm3', 2.5)
b4c.add_nuclide('B10', 0.8)
b4c.add_nuclide('B11', 0.2)
b4c.add_element('C', 1.0)
# Create control rod mixture
control_rod = openmc.Material.mix_materials(
materials=[b4c, steel],
fracs=[0.8, 0.2],
percent_type='vo'
)
control_rod.name = 'Control Rod'Temperature and Depletion
python
# Material with multiple temperature points
# OpenMC will interpolate between temperatures during simulation
hot_fuel = openmc.Material(name='Temperature-Dependent Fuel')
hot_fuel.set_density('g/cm3', 10.4)
hot_fuel.add_nuclide('U235', 0.045)
hot_fuel.add_nuclide('U238', 0.955)
hot_fuel.add_element('O', 2.0)
hot_fuel.temperatures = [600, 900, 1200] # Kelvin
# Material set up for depletion calculations
depleting_fuel = openmc.Material(name='Depleting Fuel')
depleting_fuel.set_density('g/cm3', 10.4)
depleting_fuel.add_nuclide('U235', 0.045)
depleting_fuel.add_nuclide('U238', 0.955)
depleting_fuel.add_element('O', 2.0)
depleting_fuel.depletable = True # Enable depletion tracking
depleting_fuel.volume = 100.0 # cm³ (required for depletion)
print(f"Material can be depleted: {depleting_fuel.depletable}")
print(f"Material volume: {depleting_fuel.volume} cm³")Common Mistakes and Tips
Here are the most common material definition errors and how to avoid them:
Always Set Density First
python
# Wrong - will cause an error
material = openmc.Material()
material.add_nuclide('U235', 0.05) # No density set!
# material.set_density('g/cm3', 10.4) # Too late
# Correct - density must be set before adding nuclides
material = openmc.Material()
material.set_density('g/cm3', 10.4) # Always do this first
material.add_nuclide('U235', 0.05) # Now this worksUse Realistic Values
python
# Check your material densities against references
# UO2 fuel: 10.4 g/cm³ (theoretical density)
# Zircaloy: 6.55 g/cm³
# Water (20°C): 1.0 g/cm³, (300°C): ~0.7 g/cm³
# Steel: 7.8-8.0 g/cm³
# Always add thermal scattering for light materials
water.add_s_alpha_beta('c_H_in_H2O') # Essential for water
# Available S(α,β) tables: c_H_in_H2O, c_Graphite, c_Be, etc.
# Use appropriate temperatures (in Kelvin)
material.temperature = 600 # 327°C
# Room temperature = 293 K, PWR operating = 580 KRemember that material definitions directly impact your simulation accuracy. Use well-established reference values and always validate your materials collection before running calculations.