OpenMC 0.13.1

OpenMC Documentation
Release 0.13.1
OpenMC contributors
Aug 19, 2022

CONTENTS
1 Quick Install Guide 3

1.1 Installing on Linux/Mac with Mamba and conda-forge . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Installing on Linux/Mac/Windows with Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Installing from Source using Spack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Installing from Source on Ubuntu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.5 Installing from Source on Linux or Mac OS X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Release Notes 7
2.1 What’s New in 0.13.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.2 Compatibility Notes and Deprecations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.3 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.4 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1.5 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 What’s New in 0.13.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 What’s New in 0.12.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4 What’s New in 0.12.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.4.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5 What’s New in 0.12.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.5.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6 What’s New in 0.11.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.6.3 Python API Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.6.4 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.6.5 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
i
2.7 What’s New in 0.10.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.7.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.8 What’s New in 0.9.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.8.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.8.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.8.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.9 What’s New in 0.8.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.9.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.9.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.9.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.10 What’s New in 0.7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.10.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.10.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.10.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.11 What’s New in 0.7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.11.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.11.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.11.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.12 What’s New in 0.6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.12.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.12.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.12.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.13 What’s New in 0.6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.13.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.13.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.13.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.14 What’s New in 0.6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.14.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.14.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.14.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.15 What’s New in 0.5.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.15.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.15.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.15.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.16 What’s New in 0.5.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.16.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.16.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.17 What’s New in 0.5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.17.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.17.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.18 What’s New in 0.5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
ii
2.18.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.18.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.19 What’s New in 0.5.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.19.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.19.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.20 What’s New in 0.4.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.20.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.20.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.21 What’s New in 0.4.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.21.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.21.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.22 What’s New in 0.4.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.22.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.22.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.23 What’s New in 0.4.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.23.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.23.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.24 What’s New in 0.4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.24.2 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.24.3 Bug Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3 Theory and Methodology 43

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.1.1 Overview of Program Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2 Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2.1 Constructive Solid Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2.2 Computing the Distance to Nearest Boundary . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.2.3 Finding a Cell Given a Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.2.4 Finding a Lattice Tile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.2.5 Determining if a Coordinate is in a Cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.2.6 Handling Surface Crossings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.2.7 Building Neighbor Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.2.8 Reflective Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.2.9 White Boundary Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.3 Cross Section Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.3.1 Continuous-Energy Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.3.2 Multi-Group Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
3.4 Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.4.1 Linear Congruential Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.5 Neutron Physics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.5.1 Sampling Distance to Next Collision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5.2 (𝑛, 𝛾) and Other Disappearance Reactions . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5.3 Elastic Scattering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5.4 Inelastic Scattering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.5.5 (𝑛, 𝑥𝑛) Reactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.5.6 Multi-Group Scattering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.5.7 Fission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
iii
3.5.8 Secondary Angle-Energy Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.5.9 Transforming a Particle’s Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.5.10 Effect of Thermal Motion on Cross Sections . . . . . . . . . . . . . . . . . . . . . . . . . . 75
3.5.11 S(𝛼, 𝛽, 𝑇 ) Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.5.12 Unresolved Resonance Region Probability Tables . . . . . . . . . . . . . . . . . . . . . . . 81
3.5.13 Variance Reduction Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.6 Photon Physics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.6.1 Photon Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.6.2 Secondary Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
3.6.3 Photon Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.7 Tallies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.7.1 Filters and Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.7.2 Using Maps for Filter-Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.7.3 Volume-Integrated Flux and Reaction Rates . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.7.4 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.8 Eigenvalue Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
3.8.1 Method of Successive Generations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.8.2 Source Convergence Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.8.3 Uniform Fission Site Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.9 Depletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.9.1 Numerical Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3.9.2 Matrix Exponential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.9.3 Data Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.10 Heating and Energy Deposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
3.10.1 Fission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
3.10.2 OpenMC Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3.10.3 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3.11 Parallelization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3.11.1 Fission Bank Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
3.12 Nonlinear Diffusion Acceleration - Coarse Mesh Finite Difference . . . . . . . . . . . . . . . . . . . 115
3.12.1 Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
3.12.2 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
3.12.3 Implementation in OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4 User’s Guide 125

4.1 A Beginner’s Guide to OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4.1.1 What does OpenMC do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4.1.2 How does it work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.1.3 What do I need to know? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.2 Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.2.1 Installing on Linux/Mac with Mamba and conda-forge . . . . . . . . . . . . . . . . . . . . 127
4.2.2 Installing on Linux/Mac/Windows with Docker . . . . . . . . . . . . . . . . . . . . . . . . 127
4.2.3 Installing from Source using Spack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.2.4 Installing from Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.2.5 Installing Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
4.2.6 Configuring Input Validation with GNU Emacs nXML mode . . . . . . . . . . . . . . . . . 135
4.3 Cross Section Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.3.1 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.3.2 Continuous-Energy Cross Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
4.3.3 Windowed Multipole Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.3.4 Multi-Group Cross Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.4 Basics of Using OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4.4.1 Running a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4.4.2 Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
iv
4.4.3 Viewing and Analyzing Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4.4.4 Physical Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4.4.5 ERSN-OpenMC Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4.5 Material Compositions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
4.5.1 Natural Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
4.5.2 Thermal Scattering Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
4.5.3 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.5.4 Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.5.5 Material Mixtures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
4.5.6 Material Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.6 Defining Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.6.1 Surfaces and Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.6.2 Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
4.6.3 Universes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
4.6.4 Lattices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
4.6.5 Exporting a Geometry Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
4.6.6 Using CAD-based Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
4.6.7 Calculating Atoms Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
4.7 Execution Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
4.7.1 Run Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
4.7.2 Run Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
4.7.3 External Source Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
4.7.4 Shannon Entropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
4.7.5 Photon Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
4.7.6 Generation of Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
4.8 Specifying Tallies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.8.1 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
4.8.2 Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
4.8.3 Normalization of Tally Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
4.9 Geometry Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
4.9.1 Slice Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
4.9.2 Voxel Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
4.10 Depletion and Transmutation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
4.10.1 Transport-coupled depletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
4.10.2 Transport-independent depletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
4.11 Executables and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
4.11.1 openmc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
4.11.2 openmc-ace-to-hdf5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
4.11.3 openmc-plot-mesh-tally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
4.11.4 openmc-track-combine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
4.11.5 openmc-track-to-vtk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.11.6 openmc-update-inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.11.7 openmc-update-mgxs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.11.8 openmc-validate-xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.11.9 openmc-voxel-to-vtk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
4.12 Data Processing and Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
4.12.1 Working with State Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
4.12.2 Particle Track Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
4.12.3 Source Site Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
4.13 Running in Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
4.13.1 Shared-Memory Parallelism (OpenMP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
4.13.2 Distributed-Memory Parallelism (MPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
4.13.3 Maximizing Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
4.14 Stochastic Volume Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
v
4.15 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
4.15.1 Problems with Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
4.15.2 Problems with Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
5 Developer’s Guide 185

5.1 Contributing to OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.1.3 Contribution Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
5.1.4 Becoming a Committer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
5.1.5 TC Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
5.1.6 Leadership Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.1.7 Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.2 Development Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.2.2 Code Review Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
5.2.3 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.2.4 Private Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
5.2.5 Working in “Development” Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.3 Style Guide for OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.3.1 C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.3.2 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.4 Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.4.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
5.4.2 Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.4.3 Generating XML Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.4.4 Adding Tests to the Regression Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.5 Making User Input Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.6 Building Sphinx Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
5.6.1 Building Documentation as a Webpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.6.2 Building Documentation as a PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
5.7 Deployment with Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
6 Python API 195

6.1 openmc – Basic Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.1.1 Handling nuclear data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
6.1.2 Simulation Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
6.1.3 Material Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
6.1.4 Building geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
6.1.5 Constructing Tallies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
6.1.6 Geometry Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
6.1.7 Running OpenMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
6.1.8 Post-processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
6.1.9 Coarse Mesh Finite Difference Acceleration . . . . . . . . . . . . . . . . . . . . . . . . . . 340
6.2 openmc.model – Model Building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
6.2.1 Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
6.2.2 Composite Surfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
6.2.3 TRISO Fuel Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
6.2.4 Model Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
6.3 openmc.examples – Example Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.3.1 Simple Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.3.2 Reactor Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.4 openmc.deplete – Depletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
6.4.1 Primary API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
vi
6.4.2 Minimal Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
6.4.3 Internal Classes and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
6.4.4 Intermediate Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
6.4.5 Abstract Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
6.5 openmc.mgxs – Multi-Group Cross Section Generation . . . . . . . . . . . . . . . . . . . . . . . . 425
6.5.1 Energy Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
6.5.2 Multi-group Cross Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
6.5.3 Multi-delayed-group Cross Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
6.5.4 Multi-group Cross Section Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
6.6 openmc.stats – Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
6.6.1 Univariate Probability Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
6.6.2 Angular Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
6.6.3 Spatial Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
6.7 openmc.data – Nuclear Data Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
6.7.1 Core Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
6.7.2 Core Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
6.7.3 One-dimensional Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
6.7.4 Angle-Energy Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
6.7.5 Resonance Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
6.7.6 ACE Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
6.7.7 ENDF Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
6.7.8 NJOY Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
6.8 openmc.lib – Python bindings to the C/C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . 769
6.8.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
6.8.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
6.9 openmc.openmoc_compatible – OpenMOC Compatibility . . . . . . . . . . . . . . . . . . . . . . 780
6.9.1 Core Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
7 C/C++ API 785

7.1 Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
7.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
8 File Format Specifications 801

8.1 Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
8.1.1 Geometry Specification – geometry.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
8.1.2 Materials Specification – materials.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
8.1.3 Settings Specification – settings.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
8.1.4 Tallies Specification – tallies.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
8.1.5 Geometry Plotting Specification – plots.xml . . . . . . . . . . . . . . . . . . . . . . . . . . 830
8.2 Data Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
8.2.1 Cross Sections Listing – cross_sections.xml . . . . . . . . . . . . . . . . . . . . . . . . . . 833
8.2.2 Depletion Chain – chain.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
8.2.3 Nuclear Data File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
8.2.4 Multi-Group Cross Section Library Format . . . . . . . . . . . . . . . . . . . . . . . . . . 848
8.2.5 Windowed Multipole Library Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
8.3 Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
8.3.1 State Point File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
8.3.2 Source File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
8.3.3 Summary File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
8.3.4 Properties File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
8.3.5 Depletion Results File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
8.3.6 Particle Restart File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
8.3.7 Track File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860
8.3.8 Voxel Plot File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
vii
8.3.9 Volume File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
9 Publications 863
9.1 Overviews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
9.2 Benchmarking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
9.3 Coupling and Multi-physics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
9.4 Geometry and Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
9.5 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
9.6 Multigroup Cross Section Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
9.7 Doppler Broadening . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
9.8 Nuclear Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
9.9 Parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
9.10 Depletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
9.11 Sensitivity Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
10 License Agreement 871
Bibliography 873
Python Module Index 875
viii
OpenMC Documentation, Release 0.13.1
OpenMC is a community-developed Monte Carlo neutron and photon transport simulation code. It is capable of per-
forming fixed source, k-eigenvalue, and subcritical multiplication calculations on models built using either a construc-
tive solid geometry or CAD representation. OpenMC supports both continuous-energy and multigroup transport. The
continuous-energy particle interaction data is based on a native HDF5 format that can be generated from ACE files
produced by NJOY. Parallelism is enabled via a hybrid MPI and OpenMP programming model.
OpenMC was originally developed by members of the Computational Reactor Physics Group at the Massachusetts
Institute of Technology starting in 2011. Various universities, laboratories, and other organizations now contribute to
the development of OpenMC. For more information on OpenMC, feel free to post a message on the OpenMC Discourse
Forum.
Recommended publication for citing

Paul K. Romano, Nicholas E. Horelik, Bryan R. Herman, Adam G. Nelson, Benoit Forget, and Kord Smith, “OpenMC:
A State-of-the-Art Monte Carlo Code for Research and Development,” Ann. Nucl. Energy, 82, 90–97 (2015).
CONTENTS 1
2 CONTENTS
CHAPTER
ONE
QUICK INSTALL GUIDE
This quick install guide outlines the basic steps needed to install OpenMC on your computer. For more detailed in-
structions on configuring and installing OpenMC, see Installation and Configuration in the User’s Manual.
1.1 Installing on Linux/Mac with Mamba and conda-forge
Conda is an open source package management system and environments management system for installing multiple
versions of software packages and their dependencies and switching easily between them. Mamba is a cross-platform
package manager and is compatible with conda packages. OpenMC can be installed in a conda environment with
mamba. First, conda should be installed with one of the following installers: Miniconda, Anaconda, or Miniforge.
Once you have conda installed on your system, OpenMC can be installed via the conda-forge channel with mamba.
First, add the conda-forge channel with:
conda config --add channels conda-forge
Then create and activate a new conda enviroment called openmc-env in which to install OpenMC.
conda create -n openmc-env

conda activate openmc-env
Then install mamba, which will be used to install OpenMC.
conda install mamba
To list the versions of OpenMC that are available on the conda-forge channel, in your terminal window or an Anaconda
Prompt run:
mamba search openmc
OpenMC can then be installed with:
mamba install openmc
You are now in a conda environment called openmc-env that has OpenMC installed.
3
1.2 Installing on Linux/Mac/Windows with Docker
OpenMC can be easily deployed using Docker on any Windows, Mac, or Linux system. With Docker running, execute
the following command in the shell to download and run a Docker image with the most recent release of OpenMC from
DockerHub:
docker run openmc/openmc:latest
This will take several minutes to run depending on your internet download speed. The command will place you in an
interactive shell running in a Docker container with OpenMC installed.
Note: The docker run command supports many options for spawning containers including mounting volumes from
the host filesystem, which many users will find useful.
1.3 Installing from Source using Spack
Spack is a package management tool designed to support multiple versions and configurations of software on a wide
variety of platforms and environments. Please follow Spack’s setup guide to configure the Spack system.
To install the latest OpenMC with the Python API, use the following command:
spack install py-openmc
For more information about customizations including MPI, see the detailed installation instructions using Spack. Once
installed, environment/lmod modules can be generated or Spack’s load feature can be used to access the installed
packages.
1.4 Installing from Source on Ubuntu
To build OpenMC from source, several prerequisites are needed. If you are using Ubuntu or higher, all prerequisites
can be installed directly from the package manager:
sudo apt install g++ cmake libhdf5-dev libpng-dev
After the packages have been installed, follow the instructions below for building and installing OpenMC from source.
1.5 Installing from Source on Linux or Mac OS X
All OpenMC source code is hosted on GitHub. If you have git, the gcc compiler suite, CMake, and HDF5 installed,
you can download and install OpenMC be entering the following commands in a terminal:
git clone --recurse-submodules https://github.com/openmc-dev/openmc.git

cd openmc
mkdir build && cd build
cmake ..
make
sudo make install
4 Chapter 1. Quick Install Guide

This will build an executable named openmc and install it (by default in /usr/local/bin). If you do not have administrator
privileges, the cmake command should specify an installation directory where you have write access, e.g.
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
The openmc Python package must be installed separately. The easiest way to install it is using pip, which is included
by default in Python 3.4+. From the root directory of the OpenMC distribution/repository, run:
pip install .
If you want to build a parallel version of OpenMC (using OpenMP or MPI), directions can be found in the detailed
installation instructions.
1.5. Installing from Source on Linux or Mac OS X 5

6 Chapter 1. Quick Install Guide

CHAPTER
TWO
RELEASE NOTES
2.1 What’s New in 0.13.1
2.1.1 Summary
This release of OpenMC includes many bug fixes as well as improvements in geometry modeling, mesh functional-
ity, source specification, depletion capabilities, and other general enhancements. The depletion module features a new
transport operator, openmc.deplete.IndependentOperator, that allows a depletion calculation to be performed us-
ing arbitrary one-group cross sections (e.g., generated by an external solver) along with a openmc.deplete.MicroXS
class for managing one-group cross sections. The track file generation capability has been significantly overhauled and
a new openmc.Tracks class was introduced to allow access to information in track files from the Python API. Support
has been added for new ENDF thermal scattering evaluations that use mixed coherent/incoherent elastic scattering.
2.1.2 Compatibility Notes and Deprecations
• The openmc.deplete.Operator class has been renamed openmc.deplete.CoupledOperator.

• The openmc.deplete.ResultsList class has been renamed to openmc.deplete.Results and no longer
requires you to call the from_hdf5() method in order to create it; instead, you can directly instantiate it.
• A few methods that represent k-effective have been renamed for the sake of consistency:
– openmc.StatePoint.k_combined is now openmc.StatePoint.keff
– openmc.deplete.ResultsList.get_eigenvalue is now openmc.deplete.Results.get_keff()
• The openmc.stats.SphericalIndependent class, which used to accept a distribution for theta now accepts
a distribution for cos_theta instead in order to more easily handle the common case of specifying a uniform
spatial distribution over a sphere (also see the new openmc.stats.spherical_uniform() function).
• If you are building OpenMC from source, note that several of our CMake options have been changed:
Old option New option

debug —
optimize —
profile OPENMC_ENABLE_PROFILE
coverage OPENMC_ENABLE_COVERAGE
openmp OPENMC_USE_OPENMP
— OPENMC_USE_MPI
dagmc OPENMC_USE_DAGMC
libmesh OPENMC_USE_LIBMESH
7
The debug and optimize options have been removed; instead, use the standard CMAKE_BUILD_TYPE vari-
able.
2.1.3 New Features
• Two new composite surfaces: openmc.model.IsogonalOctagon and openmc.model.CylinderSector.

• The DAGMCUniverse class now has a bounding_box attribute and a bounding_region() method.
• When translating a Region using the translate() method, there is now an inplace argument.
• The Material class has several new methods and attributes:
– The add_components() methods allows you to add multiple nuclides/elements to a material with a single
call by passing a dictionary.
– The get_activity() method returns the activity of a material in Bq, Bq/g, or Bq/cm3 .
– The remove_element() method removes an element from a material
– The get_nuclide_atoms() method gives the number of atoms of each nuclide in a material
• All mesh classes now have a volumes property that provides the volume of each mesh element as well as
write_data_to_vtk methods.
• Support for externally managed MOAB meshes or libMesh meshes.
• Multiple discrete distributions can be merged with the new merge() method.
• The openmc.stats.spherical_uniform() function creates a uniform distribution over a sphere using the
SphericalIndependent class.
• Univariate distributions in the openmc.stats module now have sample() methods.
• An openmc_sample_external_source function has been added to the C API with a corresponding Python
binding openmc.lib.sample_external_source().
• The track file generation capability has been completely overhauled. Track files now include much more in-
formation, and a new Tracks class allows access to track file information from the Python API and has a
write_to_vtk() method for writing a VTK file. Multiple tracks are now written to a single file (one per
MPI rank).
• A new openmc.wwinp_to_wws() function that converts weight windows from a wwinp file to a list of
WeightWindows objects.
• The new openmc.EnergyFilter.from_group_structure() method provides a way of creating an energy
filter with a group structure identified by name.
• The openmc.data.Decay class now has a sources property that provides radioactive decay source distribu-
tions.
• A openmc.mgxs.ReducedAbsorptionXS class produces a multigroup cross section representing “reduced”
absorption (absorption less neutron production from (n,xn) reactions).
• Added support in the Python API and HDF5 nuclear data format for new ENDF thermal neutron scattering
evaluations with mixed coherent elastic and incoherent elastic.
• CMake now relies on find_package(MPI) for a more standard means of identifying an MPI compiler config-
uration.
8 Chapter 2. Release Notes

2.1.4 Bug Fixes
• Fix bug when a rotation matrix is passed to Halfspace.rotate

• Fix bug for spherical mesh string repr
• Fix package_data specification to include pyx files
• Allow meshes with same ID to appear in multiple files
• Fix overwritten variable in get_libraries_from_xsdata
• Write output files to correct directory
• Allow CMake to properly find third-party packages
• Fix Region.from_expression when “)(” appears in specification
• Move lost particle reset from finalize() to reset()
• Minor typo fixes in test_lattice.py
• Fix color assignment in Universe.plot
• Several depletion-related fixes
• Allow control of C++ standard used by compiler
• Fix IO format documentation for surface source read/write
• Make sure basis gets set in Plot.from_geometry
• Improve robustness of torus distance calculation
• Allow use of redundant fission when adjusting KERMA in from_njoy
• Disable GNU extensions for CMake target
• Two from_xml fixes
• Fix for rare infinite loop when finding cell
• Allow photon heating to be tallied by nuclide
• Use UTF-8 encoding when reading dose coefficients
• Fix a corner case in Region.from_expression
• Fix bug in spherical and cylindrical meshes
• Ensure weight window bounds are flattened when writing to XML
• Fix for std::cout sync bug in output.cpp
• Allow compiling against fmt v9
• Fix TimeFilter for small time intervals
2.1. What’s New in 0.13.1 9

2.1.5 Contributors
• David Andrs
• Hunter Belanger
• Helen Brooks
• Rémi Delaporte-Mathurin
• Joffrey Dorville
• Christopher Fichtlscherer
• Lewis Gross
• Andrew Johnson
• Kalin Kiesling
• Amanda Lund
• Richard Morrison
• Patrick Myers
• Adam Nelson
• April Novak
• Ethan Peterson
• Gavin Ridley
• Paul Romano
• Jonathan Shimwell
• Patrick Shriwise
• Amelia Trainer
• John Tramm
• Bob Urberger
• Olek Yardas
2.2.1 Summary
This release of OpenMC includes several noteworthy and unique features. Most importantly, mesh-based weight win-
dows have been added and work with all supported mesh types (regular, rectilinear, cylindrical, spherical, and unstruc-
tured). Other additions include torus surfaces, an ability to place CAD-based geometries in universes, a feature to
export/import physical properties, and a filter for particle time.
There is one breaking changing in the Python API. The openmc.deplete.Operator class used to accept Geometry
and Settings objects as its first two arguments; users now need to pass a Model class instead.
The minimum supported Python version is now 3.6.

2.2.2 New Features
• Variance reduction using mesh-based weight windows is now possible with the WeightWindows class.
• Users can now model axis-aligned tori using the XTorus, YTorus, and ZTorus classes.
• DAGMC CAD-based geometries can now be placed in a universe using DAGMCUniverse, allowing users to
combine CSG and CAD-based geometry in a single model.
• The C/C++ API has two new functions openmc_properties_export and openmc_properties_import with
corresponding Python API bindings, export_properties() and import_properties(). These functions
allow physical properties (temperatures, densities, material compositions) to be written to an HDF5 file and
re-used for subsequent simulations.
• A new PowerLaw univariate distribution
• The capabilities of the Model class have been substantially expanded (e.g., the deplete(), plot_geometry(),
and rotate_cells() methods).
• A new TimeFilter class that allows tallies to be filtered by the particle’s time, which is now tracked.
• The Source class now allows you to specify a time distribution.
• The new CylindricalMesh and SphericalMesh can be used for mesh tallies over cylidrical and spherical
meshes, respectively.
• Geometry plotting, which used to produce the files in the unusual .ppm format, now produces .png files by default.
2.2.3 Bug Fixes
• Fix for shared fission bank memory errors

• Make sure properties export only happens from root process
• Fix pathlib use error in openmc-ace-to-hdf5
• Fix DAGMC and libMesh variable in CMake config
• Fix bug associated with volume calc in MG mode
• Add missing Settings.write_initial_source property
• Bug fixes for specifying Materials.cross_sections
• Removing Legendre filter in diffusion coefficient results
• Ensure particles lost during event_calculate_xs are terminated
• Fixed parsing of xsdir entries with a continuation line
• openmc.RegularMesh attribute consistency
• Ensure secondary particles below energy cutoff are not created
• Allow compilation with g++ 11
• Depletion-related bug fixes
• Miscellaneous bug fixes
• Fixes for various bugs
• Reset triggers in openmc_reset
2.2. What’s New in 0.13.0 11

2.2.4 Contributors
• Hunter Belanger
• Helen Brooks
• Andrew Davis
• Valerio Giusti
• Jeff Hammond
• Yuan Hu
• Andrew Johnson
• Miriam Kreher
• Amanda Lund
• Adam Nelson
• April Novak
• Ariful Islam Pranto
• Gavin Ridley
• Paul Romano
• Olaf Schumann
• John Tramm
2.3.1 Summary
This release of OpenMC is primarily a hotfix release with numerous important bug fixes. Several tally-related enhance-
ments have also been added.
2.3.2 New Features
Three tally-related enhancements were added to the code in this release:

• A new CollisionFilter class that allows tallies to be filtered by the number of collisions a particle has un-
dergone.
• A translation attribute has been added to MeshFilter that allows a mesh to be translated from its original
position before location checks are performed.
• The UnstructuredMesh class now supports libMesh unstructured meshes to enable better ingration with
MOOSE-based applications.

2.3.3 Bug Fixes
• Reset particle coordinates during find cell operation

• Cover quadric edge case
• Prevent divide-by-zero in bins_crossed methods for meshes
• Fix for translational periodic boundary conditions
• Fix angle sampling in CorrelatedAngleEnergy
• Fix typo in fmt string for a lattice error
• Nu-fission tally and stochastic volume bug fixes
• Make sure failed neighbor list triggers exhaustic search
• Change element to element.title to catch lowercase entries
• Disallow non-current scores with a surface filter
• Depletion operator obeys Materials.cross_sections
• Fix for surface_bins_crossed override
2.3.4 Contributors
This release contains new contributions from the following people:

• Hunter Belanger
• Isaac Griswold-Steiner
• Andrew Johnson
• Gavin Ridley
• Paul Romano
2.4.1 Summary
This release of OpenMC includes an assortment of new features and many bug fixes. The openmc.deplete module
incorporates a number of improvements in usability, accuracy, and performance. Other enhancements include gen-
eralized rotational periodic boundary conditions, expanded source modeling capabilities, and a capability to generate
windowed multipole library files from ENDF files.
2.4. What’s New in 0.12.1 13

2.4.2 New Features
• Boundary conditions have been refactored and generalized. Rotational periodic boundary conditions can now be
applied to any N-fold symmetric geometry.
• External source distributions have been refactored and extended. Users writing their own C++ custom sources
need to write a class that derives from openmc::Source. These changes have enabled new functionality, such
as:
– Mixing more than one custom source library together
– Mixing a normal source with a custom source
– Using a file-based source for fixed source simulations
– Using a file-based source for eigenvalue simulations even when the number of particles doesn’t match
• New capability to read and write a source file based on particles that cross a surface (known as a “surface source”).
• Various improvements related to depletion:
– Reactions used in a depletion chain can now be configured through the reactions argument to openmc.
deplete.Chain.from_endf().
– Specifying a power of zero during a depletion simulation no longer results in an unnecessary transport
solve.
– Reaction rates can be computed either directly or using multigroup flux tallies that are used to collapse
reaction rates afterward. This is enabled through the reaction_rate_mode and reaction_rate_opts
to openmc.deplete.Operator.
– Depletion results can be used to create a new openmc.Materials object using the openmc.deplete.
ResultsList.export_to_materials() method.
• Multigroup current and diffusion cross sections can be generated through the openmc.mgxs.Current and
openmc.mgxs.DiffusionCoefficient classes.
• Added openmc.data.isotopes() function that returns a list of naturally occurring isotopes for a given ele-
ment.
• Windowed multipole libraries can now be generated directly from the Python API using openmc.data.
WindowedMultipole.from_endf().
• The new openmc.write_source_file() function allows source files to be generated programmatically.
2.4.3 Bug Fixes
• Proper detection of MPI wrappers

• Fix related to declaration order of maps/vectors
• Check for existence of decay rate attribute
• Small updates to deal with JEFF 3.3 data
• Fix for depletion chain generation
• Fix call to superclass constructor in MeshPlotter
• Fix for data crossover in VTK files
• Make sure reaction names are recognized as valid tally scores
• Fix bug related to logging of particle restarts

• Examine if region exists before removing redundant surfaces

• Fix plotting of individual universe levels
• Mixed materials should inherit depletable attribute
• Fix typo in energy units in dose coefficients
• Fixes for large tally cases
• Fix verification of volume calculation results
• Fix calculation of decay energy for depletion chains
• Fix pointers in CartesianIndependent
• Ensure correct initialization of members for RegularMesh
• Add missing import in depletion module
• Fixed several bugs related to decay-rate
• Fix how depletion operator distributes burnable materials
• Fix assignment of elemental carbon in JEFF 3.3
• Fix typo in RectangularParallelepiped.__pos__
• Fix temperature tolerance with S(a,b) data
• Fix sampling or normal distribution
• Fix for SharedArray relaxed memory ordering
• Check for proper format of source files
• Ensure (n,gamma) reaction rate tally uses sampled cross section
• Fix for temperature range behavior
2.4.4 Contributors

• Andrew Davis
• Guillaume Giudicelli
• Sterling Harper
• Bryan Herman
• Yue Jin
• Andrew Johnson
• Miriam Kreher
• Shikhar Kumar
• Jingang Liang
• Amanda Lund
• Adam Nelson
• April Novak
• YoungHui Park
2.4. What’s New in 0.12.1 15


• Ron Rahaman
• Gavin Ridley
• Paul Romano
• Dan Short
• Roy Stogner
• John Tramm
• Cyrus Wyett
• Jiankai Yu
2.5.1 Summary
This release of OpenMC includes an assortment of new features and many bug fixes. In particular, the openmc.
deplete module has been heavily tested which has resulted in a number of usability improvements, bug fixes, and
other enhancements. Energy deposition calculations, particularly for coupled neutron-photon simulations, have been
improved as well.
Improvements in modeling capabilities continue to be added to the code, including the ability to rotate surfaces in the
Python API, several new “composite” surfaces, a variety of new methods on openmc.Material, unstructured mesh
tallies that leverage the existing DAGMC infrastructure, effective dose coefficients from ICRP-116, and a new cell
instance tally filter.
2.5.2 New Features
• All surfaces now have a rotate method that allows them to be rotated.
• Several “composite” surfaces, which are actually composed of multiple surfaces but can be treated as a normal
surface through the -/+ unary operators, have been added. These include:
– openmc.model.RightCircularCylinder
– openmc.model.RectangularParallelepiped
– openmc.model.XConeOneSided (and equivalent versions for y- and z-axes)
• Various improvements related to depletion:
– The matrix exponential solver can now be configured through the solver argument on depletion integrator
classes.
– The openmc.deplete.Chain.reduce() method can automatically reduce the number of nuclides in a
depletion chain.
– Depletion integrator classes now allow a user to specify timesteps in several units (s, min, h, d, MWd/kg).
– openmc.deplete.ResultsList.get_atoms() now allows a user to obtain depleted material composi-
tions in atom/b-cm.

• Several new methods on openmc.Material:

– The openmc.Material.add_elements_from_formula() method allows a user to create a material
based on a chemical formula.
– openmc.Material.add_element() now supports the enrichment argument for non-uranium elements
when only two isotopes are naturally occurring.
– openmc.Material.add_element() now supports adding elements by name rather than by symbol.
– The openmc.Material.get_elements() method returns a list of elements within a material.
– The openmc.Material.mix_materials() method allows multiple materials to be mixed together based
on atom, weight, or volume fractions.
• The acceptable number of lost particles can now be configured through openmc.Settings.
max_lost_particles and openmc.Settings.rel_max_lost_particles.
• Delayed photons produced from fission are now accounted for by default by scaling the yield of prompt fission
photons. This behavior can be modified through the openmc.Settings.delayed_photon_scaling attribute.
• A trigger can now be specified for a volume calculation via the openmc.VolumeCalculation.set_trigger()
method.
• The openmc.stats.SphericalIndependent and openmc.stats.CylindricalIndependent classes al-
low a user to specify source distributions based on spherical or cylindrical coordinates.
• Custom external source distributions can be used via the openmc.Source.library attribute.
• Unstructured mesh class, openmc.UnstructuredMesh , that can be used in tallies.
• The openmc.CellInstanceFilter class allows one or more instances of a repeated cell to be tallied. This is
effectively a more flexible version of the existing openmc.DistribcellFilter class.
• The openmc.data.dose_coefficients() function provides effective dose coefficients from ICRP-116 and
can be used in conjunction with openmc.EnergyFunctionFilter in a tally.
2.5.3 Bug Fixes
• Keep user-supplied prev_results on operator

• Fix bug when S(a,b) tables appear in depletable material
• DAGMC fix for implicit complement material assignment
• Bug fix for tallying reaction rates in coupled n-p runs
• Corrected issue with multiplicity matrix
• Fix depletion with photon transport
• Fix secondary photon creation
• Bug fix for total xs plotting
• Account for light nuclide production in depletion
• Reset timer in depletion calculations
• Fix for Model.run
• Ensure NJOY output goes to specified directory
• Fix bug preventing creating photon data
• Fix bug when surface ID > 999999
2.5. What’s New in 0.12.0 17

• Fix bug for reading output settings in Settings.from_xml

• Fix improve energy deposition for coupled neutron-photon
• Use number of particles for tally normalization
• Fix a number of problems related to photoatomic data
• Fix cosine smearing for S(a,b)
• Use relative distances for coincidence test in hex lattice
• Fix RPATH for non-Debian linux systems
• Fix mesh plotter energy filter bins
• Fix memory leak
• Fix volume allocation related to burnable materials
• Fix tally mesh bug for short tracks
• DAGMC void material assignment fix
• Fix for Mesh __repr__ methods
2.5.4 Contributors

• Paul Cosgrove
• Steven Dargaville
• Andrew Davis
• Iurii Drobyshev
• Alec Golas
• Avery Grieve
• Sterling Harper
• Yuan Hu
• Yue Jin
• Andrew Johnson
• Mikolaj Kowalski
• Shikhar Kumar
• Jingang Liang
• David Long
• Amanda Lund
• Alex Lyons
• Adam Nelson
• Ethan Peterson
• Sam Powell-Gill


• Simon Richards
• Gavin Ridley
• Paul Romano
• John Tramm
• Paul P.H. Wilson
• Jiankai Yu
2.6.1 Summary
This release of OpenMC adds several major new features: depletion, photon transport, and support for CAD geometries
through DAGMC. In addition, the core codebase has been rewritten in C++14 (it was previously written in Fortran
2008). This makes compiling the code considerably simpler as no Fortran compiler is needed.
Functional expansion tallies are now supported through several new tally filters that can be arbitrarily combined:
• openmc.LegendreFilter
• openmc.SpatialLegendreFilter
• openmc.SphericalHarmonicsFilter
• openmc.ZernikeFilter
• openmc.ZernikeRadialFilter
Note that these filters replace the use expansion scores like scatter-P1. Instead, a normal scatter score should be
used along with a openmc.LegendreFilter.
The interface for random sphere packing has been significantly improved. A new openmc.model.pack_spheres()
function takes a region and generates a random, non-overlapping configuration of spheres within the region.
2.6.2 New Features
• White boundary conditions can be applied to surfaces

• Support for rectilinear meshes through openmc.RectilinearMesh .
• The Geometry, Materials, and Settings classes now have a from_xml method that will build an instance
from an existing XML file.
• Predefined energy group structures can be found in openmc.mgxs.GROUP_STRUCTURES.
• New tally scores: H1-production, H2-production, H3-production, He3-production, He4-production,
heating, heating-local, and damage-energy.
• Switched to cell-based neighor lists (PR 1140)
• Two new probability distributions that can be used for source distributions: openmc.stats.Normal and
openmc.stats.Muir
2.6. What’s New in 0.11.0 19

• The openmc.data module now supports reading and sampling from ENDF File 32 resonance covariance data
(PR 1024).
• Several new convenience functions/methods have been added:
– The openmc.model.cylinder_from_points() function creates a cylinder given two points passing
through its center and a radius.
– The openmc.Plane.from_points() function creates a plane given three points that pass through it.
– The openmc.model.pin() function creates a pin cell universe given a sequence of concentric cylinders
and materials.
2.6.3 Python API Changes
• All surface classes now have coefficient arguments given as lowercase names.
• The order of arguments in surface classes has been changed so that coefficients are the first arguments (rather
than the optional surface ID). This means you can now write:
x = openmc.XPlane(5.0, 'reflective')
zc = openmc.ZCylinder(0., 0., 10.)
• The Mesh class has been renamed openmc.RegularMesh .

• The get_rectangular_prism function has been renamed openmc.model.rectangular_prism().
• The get_hexagonal_prism function has been renamed openmc.model.hexagonal_prism().
• Python bindings to the C/C++ API have been move from openmc.capi to openmc.lib.
2.6.4 Bug Fixes
• Rotate azimuthal distributions correctly for source sampling

• Fix reading ASCII ACE tables in Python 3
• Fix bug for distributed temperatures
• Fix bug for distance to boundary in complex cells
• Bug fixes for precursor decay rate tallies
• Check for invalid surface IDs in region expression
• Support for 32-bit operating systems
• Avoid segfault from unused nuclides
• Avoid overflow when broadcasting tally results

2.6.5 Contributors

• Brody Bassett
• Will Boyd
• Andrew Davis
• Iurii Drobyshev
• Brittany Grayson
• Zhuoran Han
• Sterling Harper
• Andrew Johnson
• Colin Josey
• Shikhar Kumar
• Travis Labossiere-Hickman
• Matias Lavista
• Jingang Liang
• Alex Lindsay
• Johnny Liu
• Amanda Lund
• Jan Malec
• Isaac Meyer
• April Novak
• Adam Nelson
• Gavin Ridley
• Jose Salcedo Perez
• Paul Romano
• Sam Shaner
• John Tramm
• Jiankai Yu
• Xiaokang Zhang
2.6. What’s New in 0.11.0 21

This release of OpenMC includes several new features, performance improvements, and bug fixes compared to version
0.9.0. Notably, a C API has been added that enables in-memory coupling of neutronics to other physics fields, e.g.,
burnup calculations and thermal-hydraulics. The C API is also backed by Python bindings in a new openmc.capi
package. Users should be forewarned that the C API is still in an experimental state and the interface is likely to
undergo changes in future versions.
The Python API continues to improve over time; several backwards incompatible changes were made in the API which
users of previous versions should take note of:
• To indicate that nuclides in a material should be treated such that elastic scattering is isotropic in the laboratory
system, there is a new Material.isotropic property:
mat = openmc.Material()
mat.add_nuclide('H1', 1.0)
mat.isotropic = ['H1']
To treat all nuclides in a material this way, the Material.make_isotropic_in_lab() method can still be
used.
• The initializers for openmc.Intersection and openmc.Union now expect an iterable.
• Auto-generated unique IDs for classes now start from 1 rather than 10000.
Attention: This is the last release of OpenMC that will support Python 2.7. Future releases of OpenMC will
require Python 3.4 or later.
2.7.1 System Requirements
There are no special requirements for running the OpenMC code. As of this release, OpenMC has been tested on a
variety of Linux distributions and Mac OS X. Numerous users have reported working builds on Microsoft Windows,
but your mileage may vary. Memory requirements will vary depending on the size of the problem at hand (mostly on
the number of nuclides and tallies in the problem).
2.7.2 New Features
• Rotationally-periodic boundary conditions

• C API (with Python bindings) for in-memory coupling
• Improved correlation for Uranium enrichment
• Support for partial S(a,b) tables
• Improved handling of autogenerated IDs
• Many performance/memory improvements

2.7.3 Bug Fixes
• 937469: Fix energy group sampling for multi-group simulations

• a149ef: Ensure mutable objects are not hashable
• 2c9b21: Preserve backwards compatibility for generated HDF5 libraries
• 8047f6: Handle units of division for tally arithmetic correctly
• 0beb4c: Compatibility with newer versions of Pandas
• f124be: Fix generating 0K data with openmc.data.njoy module
• 0c6915: Bugfix for generating thermal scattering data
• 61ecb4: Fix bugs in Python multipole objects
2.7.4 Contributors

• Brody Bassett
• Will Boyd
• Brittany Grayson
• Sterling Harper
• Colin Josey
• Jingang Liang
• Alex Lindsay
• Johnny Liu
• Amanda Lund
• April Novak
• Adam Nelson
• Jose Salcedo Perez
• Paul Romano
• Sam Shaner
This release of OpenMC is the first release to use a new native HDF5 cross section format rather than ACE format cross
sections. Other significant new features include a nuclear data interface in the Python API (openmc.data) a stochastic
volume calculation capability, a random sphere packing algorithm that can handle packing fractions up to 60%, and a
new XML parser with significantly better performance than the parser used previously.
2.8. What’s New in 0.9.0 23

Caution: With the new cross section format, the default energy units are now electronvolts (eV) rather than
megaelectronvolts (MeV)! If you are specifying an energy filter for a tally, make sure you use units of eV now.
The Python API continues to improve over time; several backwards incompatible changes were made in the API which
users of previous versions should take note of:
• Each type of tally filter is now specified with a separate class. For example:
energy_filter = openmc.EnergyFilter([0.0, 0.625, 4.0, 1.0e6, 20.0e6])
• Several attributes of the Plot class have changed (color -> color_by and col_spec > colors). Plot.colors
now accepts a dictionary mapping Cell or Material instances to RGB 3-tuples or string colors names, e.g.:
plot.colors = {
fuel: 'yellow',
water: 'blue'
}
• make_hexagon_region is now get_hexagonal_prism()

• Several changes in Settings attributes:
– weight is now set as Settings.cutoff['weight']
– Shannon entropy is now specified by passing a openmc.Mesh to Settings.entropy_mesh
– Uniform fission site method is now specified by passing a openmc.Mesh to Settings.ufs_mesh
– All sourcepoint_* options are now specified in a Settings.sourcepoint dictionary
– Resonance scattering method is now specified as a dictionary in Settings.resonance_scattering
– Multipole is now turned on by setting Settings.temperature['multipole'] = True
– The output_path attribute is now Settings.output['path']
• All the openmc.mgxs.Nu* classes are gone. Instead, a nu argument was added to the constructor of the corre-
sponding classes.
2.8.2 New Features
• Stochastic volume calculations

• Multi-delayed group cross section generation
• Ability to calculate multi-group cross sections over meshes
• Temperature interpolation on cross section data
• Nuclear data interface in Python API, openmc.data
• Allow cutoff energy via Settings.cutoff

• Ability to define fuel by enrichment (see Material.add_element())

• Random sphere packing for TRISO particle generation, openmc.model.pack_trisos()
• Critical eigenvalue search, openmc.search_for_keff()
• Model container, openmc.model.Model
• In-line plotting in Jupyter, openmc.plot_inline()
• Energy function tally filters, openmc.EnergyFunctionFilter
• Replaced FoX XML parser with pugixml
• Cell/material instance counting, Geometry.determine_paths()
• Differential tallies (see openmc.TallyDerivative)
• Consistent multi-group scattering matrices
• Improved documentation and new Jupyter notebooks
• OpenMOC compatibility module, openmc.openmoc_compatible
2.8.3 Bug Fixes
• c5df6c: Fix mesh filter max iterator check

• 1cfa39: Reject external source only if 95% of sites are rejected
• 335359: Fix bug in plotting meshlines
• 17c678: Make sure system_clock uses high-resolution timer
• 23ec0b: Fix use of S(a,b) with multipole data
• 7eefb7: Fix several bugs in tally module
• 7880d4: Allow plotting calculation with no boundary conditions
• ad2d9f: Fix filter weight missing when scoring all nuclides
• 59fdca: Fix use of source files for fixed source calculations
• 9eff5b: Fix thermal scattering bugs
• 7848a9: Fix combined k-eff estimator producing NaN
• f139ce: Fix printing bug for tallies with AggregateNuclide
• b8ddfa: Bugfix for short tracks near tally mesh edges
• ec3cfb: Fix inconsistency in filter weights
• 5e9b06: Fix XML representation for verbosity
• c39990: Fix bug tallying reaction rates with multipole on
• c6b67e: Fix fissionable source sampling bug
• 489540: Check for void materials in tracklength tallies
• f0214f: Fixes/improvements to the ARES algorithm
2.8. What’s New in 0.9.0 25

2.8.4 Contributors

• Will Boyd
• Sterling Harper
• Qingming He
• Colin Josey
• Jingang Liang
• Amanda Lund
• Adam Nelson
• Paul Romano
• Sam Shaner
• Jon Walsh
This release of OpenMC includes a few new major features including the capability to perform neutron transport with
multi-group cross section data as well as experimental support for the windowed multipole method being developed at
MIT. Source sampling options have also been expanded significantly, with the option to supply arbitrary tabular and
discrete distributions for energy, angle, and spatial coordinates.
The Python API has been significantly restructured in this release compared to version 0.7.1. Any scripts written based
on the version 0.7.1 API will likely need to be rewritten. Some of the most visible changes include the following:
• SettingsFile is now Settings, MaterialsFile is now Materials, and TalliesFile is now Tallies.
• The GeometryFile class no longer exists and is replaced by the Geometry class which now has an
export_to_xml() method.
• Source distributions are defined using the Source class and assigned to the Settings.source property.
• The Executor class no longer exists and is replaced by openmc.run() and openmc.plot_geometry() func-
tions.
The Python API documentation has also been significantly expanded.

2.9.2 New Features
• Multi-group mode
• Vast improvements to the Python API
• Experimental windowed multipole capability
• Periodic boundary conditions
• Expanded source sampling options
• Distributed materials
• Subcritical multiplication support
• Improved method for reproducible URR table sampling
• Refactor of continuous-energy reaction data
• Improved documentation and new Jupyter notebooks
2.9.3 Bug Fixes
• 70daa7: Make sure MT=3 cross section is not used

• 40b05f: Ensure source bank is resampled for fixed source runs
• 9586ed: Fix two hexagonal lattice bugs
• a855e8: Make sure graphite models don’t error out on max events
• 7294a1: Fix incorrect check on cmfd.xml
• 12f246: Ensure number of realizations is written to statepoint
• 0227f4: Fix bug when sampling multiple energy distributions
• 51deaa: Prevent segfault when user specifies ‘18’ on tally scores
• fed74b: Prevent duplicate tally scores
• 8467ae: Better threshold for allowable lost particles
• 493c6f: Fix type of return argument for h5pget_driver_f
2.9.4 Contributors

• Will Boyd
• Derek Gaston
• Sterling Harper
• Colin Josey
• Jingang Liang
• Adam Nelson
• Paul Romano
• Kelly Rowland
2.9. What’s New in 0.8.0 27

• Sam Shaner
This release of OpenMC provides some substantial improvements over version 0.7.0. Non-simple cell regions can now
be defined through the | (union) and ~ (complement) operators. Similar changes in the Python API also allow complex
cell regions to be defined. A true secondary particle bank now exists; this is crucial for photon transport (to be added
in the next minor release). A rich API for multi-group cross section generation has been added via the openmc.mgxs
Python module.
Various improvements to tallies have also been made. It is now possible to explicitly specify that a collision estimator
be used in a tally. A new delayedgroup filter and delayed-nu-fission score allow a user to obtain delayed fission
neutron production rates filtered by delayed group. Finally, the new inverse-velocity score may be useful for
calculating kinetics parameters.
Caution: In previous versions, depending on how OpenMC was compiled binary output was either given in HDF5
or a flat binary format. With this version, all binary output is now HDF5 which means you must have HDF5 in
order to install OpenMC. Please consult the user’s guide for instructions on how to compile with HDF5.
variety of Linux distributions, Mac OS X, and Microsoft Windows 7. Memory requirements will vary depending on
the size of the problem at hand (mostly on the number of nuclides in the problem).
2.10.2 New Features
• Support for complex cell regions (union and complement operators)

• Generic quadric surface type
• Improved handling of secondary particles
• Binary output is now solely HDF5
• openmc.mgxs Python module enabling multi-group cross section generation
• Collision estimator for tallies
• Delayed fission neutron production tallies with ability to filter by delayed group
• Inverse velocity tally score
• Performance improvements for binary search
• Performance improvements for reaction rate tallies

2.10.3 Bug Fixes
• 299322: Bug with material filter when void material present

• d74840: Fix triggers on tallies with multiple filters
• c29a81: Correctly handle maximum transport energy
• 3edc23: Fixes in the nu-scatter score
• 629e3b: Assume unspecified surface coefficients are zero in Python API
• 5dbe8b: Fix energy filters for openmc-plot-mesh-tally
• ff66f4: Fixes in the openmc-plot-mesh-tally script
• 441fd4: Fix bug in kappa-fission score
• 7e5974: Allow fixed source simulations from Python API
2.10.4 Contributors

• Will Boyd
• Sterling Harper
• Bryan Herman
• Colin Josey
• Adam Nelson
• Paul Romano
• Kelly Rowland
• Sam Shaner
• Jon Walsh
2.11. What’s New in 0.7.0 29

2.11.2 New Features
• Complete Python API

• Python 3 compatability for all scripts
• All scripts consistently named openmc-* and installed together
• New ‘distribcell’ tally filter for repeated cells
• Ability to specify outer lattice universe
• XML input validation utility (openmc-validate-xml)
• Support for hexagonal lattices
• Material union energy grid method
• Tally triggers
• Remove dependence on PETSc
• Significant OpenMP performance improvements
• Support for Fortran 2008 MPI interface
• Use of Travis CI for continuous integration
• Simplifications and improvements to test suite
2.11.3 Bug Fixes
• b5f712: Fix bug in spherical harmonics tallies

• e6675b: Ensure all constants are double precision
• 04e2c1: Fix potential bug in sample_nuclide routine
• 6121d9: Fix bugs related to particle track files
• 2f0e89: Fixes for nuclide specification in tallies
2.11.4 Contributors

• Will Boyd
• Matt Ellis
• Sterling Harper
• Bryan Herman
• Nicholas Horelik
• Colin Josey
• William Lyu
• Adam Nelson
• Paul Romano
• Anthony Scopatz

• Jon Walsh
2.12.2 New Features
• Meshline plotting capability

• Support for plotting cells/materials on middle universe levels
• Ability to model cells with no surfaces
• Compatibility with PETSc 3.5
• Compatability with OpenMPI 1.7/1.8
• Improved overall performance via logarithmic-mapped energy grid search
• Improved multi-threaded performance with atomic operations
• Support for fixed source problems with fissionable materials
2.12.3 Bug Fixes
• 26fb93: Fix problem with -t, –track command-line flag

• 2f07c0: Improved evaporation spectrum algorithm
• e6abb9: Fix segfault when tallying in a void material
• 291b45: Handle metastable nuclides in NNDC data and multiplicities in MT=5 data
2.12.4 Contributors

• Will Boyd
• Matt Ellis
• Sterling Harper
• Bryan Herman
• Nicholas Horelik
• Anton Leontiev
• Adam Nelson
• Paul Romano
• Jon Walsh
2.12. What’s New in 0.6.2 31

• John Xia
2.13.2 New Features
• Coarse mesh finite difference (CMFD) acceleration no longer requires PETSc

• Statepoint file numbering is now zero-padded
• Python scripts now compatible with Python 2 or 3
• Ability to run particle restarts in fixed source calculations
• Capability to filter box source by fissionable materials
• Nuclide/element names are now case insensitive in input files
• Improved treatment of resonance scattering for heavy nuclides
2.13.3 Bug Fixes
• 03e890: Check for energy-dependent multiplicities in ACE files

• 4439de: Fix distance-to-surface calculation for general plane surface
• 5808ed: Account for differences in URR band probabilities at different energies
• 2e60c0: Allow zero atom/weight percents in materials
• 3e0870: Don’t use PWD environment variable when setting path to input files
• dc4776: Handle probability table resampling correctly
• 01178b: Fix metastables nuclides in NNDC cross_sections.xml file
• 62ec43: Don’t read tallies.xml when OpenMC is run in plotting mode
• 2a95ef: Prevent segmentation fault on “current” score without mesh filter
• 93e482: Check for negative values in probability tables

2.13.4 Contributors

• Sterling Harper
• Bryan Herman
• Adam Nelson
• Paul Romano
• Jon Walsh
• Will Boyd
2.14.2 New Features
• Legendre and spherical harmonic expansion tally scores

• CMake is now default build system
• Regression test suite based on CTests and NNDC cross sections
• FoX is now a git submodule
• Support for older cross sections (e.g. MCNP 66c)
• Progress bar for plots
• Expanded support for natural elements via <natural_elements> in settings.xml
2.14.3 Bug Fixes
• 41f7ca: Fixed erroneous results from survival biasing

• 038736: Fix tallies over void materials
• 46f9e8: Check for negative values in probability tables
• d1ca35: Fixed sampling of angular distribution
• 0291c0: Fixed indexing error in plotting
• d7a7d0: Fix bug with <element> specifying xs attribute
• 85b3cb: Fix out-of-bounds error with OpenMP threading
2.14. What’s New in 0.6.0 33

2.14.4 Contributors

• Sterling Harper
• Bryan Herman
• Nick Horelik
• Adam Nelson
• Paul Romano
• Jon Walsh
2.15.2 New Features
• Source sites outside geometry are resampled

• XML-Fortran backend replaced by FoX XML
• Ability to write particle track files
• Handle lost particles more gracefully (via particle track files)
• Multiple random number generator streams
• Mesh tally plotting utility converted to use Tkinter rather than PyQt
• Script added to download ACE data from NNDC
• Mixed ASCII/binary cross_sections.xml now allowed
• Expanded options for writing source bank
• Re-enabled ability to use source file as starting source
• S(a,b) recalculation avoided when same nuclide and S(a,b) table are accessed
2.15.3 Bug Fixes
• 32c03c: Check for valid data in cross_sections.xml

• c71ef5: Fix bug in statepoint.py
• 8884fb: Check for all ZAIDs for S(a,b) tables
• b38af0: Fix XML reading on multiple levels of input
• d28750: Fix bug in convert_xsdir.py
• cf567c: ENDF/B-VI data checked for compatibility

• 6b9461: Fix p_valid sampling inside of sample_energy
2.15.4 Contributors

• Sterling Harper
• Bryan Herman
• Nick Horelik
• Adam Nelson
• Paul Romano
• Tuomas Viitanen
• Jon Walsh
2.16.2 New Features
• Output interface enhanced to allow multiple files handles to be opened

• Particle restart file linked to output interface
• Particle restarts and state point restarts are both identified with the -r command line flag.
• Particle instance no longer global, passed to all physics routines
• Physics routines refactored to rely less on global memory, more arguments passed in
• CMFD routines refactored and now can compute dominance ratio on the fly
• PETSc 3.4.2 or higher must be used and compiled with fortran datatype support
• Memory leaks fixed except for ones from xml-fortran package
• Test suite enhanced to test output with different compiler options
• Description of OpenMC development workflow added
• OpenMP shared-memory parallelism added
• Special run mode –tallies removed.
2.16. What’s New in 0.5.3 35

2.16.3 Bug Fixes
• 2b1e8a: Normalize direction vector after reflecting particle.

• 5853d2: Set blank default for cross section listing alias.
• e178c7: Fix infinite loop with words greater than 80 characters in write_message.
• c18a6e: Check for valid secondary mode on S(a,b) tables.
• 82c456: Fix bug where last process could have zero particles.
2.17.2 New Features
• Python script for mesh tally plotting

• Isotopic abundances based on IUPAC 2009 when using <element>
• Particle restart files for debugging
• Code will abort after certain number of lost particles (defaults to 10)
• Region outside lattice can be filled with material (void by default)
• 3D voxel plots
• Full HDF5/PHDF5 support (including support in statepoint.py)
• Cell overlap checking with -g command line flag (or when plotting)
2.17.3 Bug Fixes
• 7632f3: Fixed bug in statepoint.py for multiple generations per batch.

• f85ac4: Fix infinite loop bug in error module.
• 49c36b: Don’t convert surface ids if surface filter is for current tallies.
• 5ccc78: Fix bug in reassignment of bins for mesh filter.
• b1f52f: Fixed bug in plot color specification.
• eae7e5: Fixed many memory leaks.
• 10c1cc: Minor CMFD fixes.
• afdb50: Add compatibility for XML comments without whitespace.
• a3c593: Fixed bug in use of free gas scattering for H-1.
• 3a66e3: Fixed bug in 2D mesh tally implementation.
• ab0793: Corrected PETSC_NULL references to their correct types.

• 182ebd: Use analog estimator with energyout filter.
2.18.2 New Features
• Absorption and combined estimators for k-effective.

• Natural elements can now be specified in materials using <element> rather than <nuclide>.
• Support for multiple S(a,b) tables in a single material (e.g. BeO).
• Test suite using Python nosetests.
• Proper install capability with ‘make install’.
• Lattices can now be 2 or 3 dimensions.
• New scatter-PN score type.
• New kappa-fission score type.
• Ability to tally any reaction by specifying MT.
2.18.3 Bug Fixes
• 94103e: Two checks for outgoing energy filters.

• e77059: Fix reaction name for MT=849.
• b0fe88: Fix distance to surface for cones.
• 63bfd2: Fix tracklength tallies with cell filter and universes.
• 88daf7: Fix analog tallies with survival biasing.
2.18. What’s New in 0.5.1 37

2.19.2 New Features
• All user input options that formerly accepted “off” or “on” should now be “false” or “true” (the proper XML
schema datatype).
• The <criticality> element is deprecated and was replaced with <eigenvalue>.
• Added ‘events’ score that returns number of events that scored to a tally.
• Restructured tally filter implementation and user input.
• Source convergence acceleration via CMFD (implemented with PETSc).
• Ability to read source files in parallel when number of particles is greater than that number of source sites.
• Cone surface types.
2.19.3 Bug Fixes
• 737b90: Coincident surfaces from separate universes / particle traveling tangent to a surface.
• a819b4: Output of surface neighbors in summary.out file.
• b11696: Reading long attribute lists in XML input.
• 2bd46a: Search for tallying nuclides when no default_xs specified.
• 7a1f08: Fix word wrapping when writing messages.
• c0e3ec: Prevent underflow when compiling with MPI=yes and DEBUG=yes.
• 6f8d9d: Set default tally labels.
• 6a3a5e: Fix problem with corner-crossing in lattices.
2.20.2 New Features
• Ability to write state points when using <no_reduce>.

• Real-time XML validation in GNU Emacs with RELAX NG schemata.
• Writing state points every n batches with <state_point interval=”. . . ” />
• Suppress creation of summary.out and cross_sections.out by default with option to turn them on with <output>
tag in settings.xml file.
• Ability to create HDF5 state points.
• Binary source file is now part of state point file by default.
• Enhanced state point usage and added state point Python scripts.

• Turning confidence intervals on affects k-effective.

• Option to specify <upper_right> for tally meshes.
2.20.3 Bug Fixes
• 4654ee: Fixed plotting with void cells.

• 7ee461: Fixed bug with multi-line input using type=’word’.
• 792eb3: Fixed degrees of freedom for confidence intervals.
• 7fd617: Fixed bug with restart runs in parallel.
• dc4a8f: Fixed bug with fixed source restart runs.
2.21.2 New Features
• Option to report confidence intervals for tally results.

• Rotation and translation for filled cells.
• Ability to explicitly specify <estimator> for tallies.
• Ability to store state points and use them to restart runs.
• Fixed source calculations (no subcritical multiplication however).
• Expanded options for external source distribution.
• Ability to tally reaction rates for individual nuclides within a material.
• Reduced memory usage by removing redundant storage or some cross-sections.
• 3bd35b: Log-log interpolation for URR probability tables.
• Support to specify labels on tallies (nelsonag).
2.21.3 Bug Fixes
• 33f29a: Handle negative values in probability table.

• 1c472d: Fixed survival biasing with probability tables.
• 3c6e80: Fixed writing tallies with no filters.
• 460ef1: Invalid results for duplicate tallies.
• 0069d5: Fixed bug with 0 inactive batches.
• 7af2cf: Fixed bug in score_analog_tallies.
2.21. What’s New in 0.4.3 39

• 85a60e: Pick closest angular distribution for law 61.

• 3212f5: Fixed issue with blank line at beginning of XML files.
2.22.2 New Features
• Ability to specify void materials.

• Option to not reduce tallies across processors at end of each batch.
• Uniform fission site method for reducing variance on local tallies.
• Reading/writing binary source files.
• Added more messages for <trace> or high verbosity.
• Estimator for diffusion coefficient.
• Ability to specify ‘point’ source type.
• Ability to change random number seed.
• Users can now specify units=’sum’ on a <density> tag. This tells the code that the total material density is the
sum of the atom fractions listed for each nuclide on the material.
2.22.3 Bug Fixes
• a27f8f: Fixed runtime error bug when using Intel compiler with DEBUG on.
• afe121: Fixed minor bug in fission bank algorithms.
• e0968e: Force re-evaluation of cross-sections when each particle is born.
• 298db8: Fixed bug in surface currents when using energy-in filter.
• 2f3bbe: Fixed subtle bug in S(a,b) cross section calculation.
• 671f30: Fixed surface currents on mesh not encompassing geometry.
• b2c40e: Fixed bug in incoming energy filter for track-length tallies.
• 5524fd: Mesh filter now works with track-length tallies.
• d050c7: Added Bessel’s correction to make estimate of variance unbiased.
• 2a5b9c: Fixed regression in plotting.

variety of Linux distributions as well as Mac OS X. However, it has not been tested yet on any releases of Microsoft
Windows. Memory requirements will vary depending on the size of the problem at hand (mostly on the number of
nuclides in the problem).
2.23.2 New Features
• A batching method has been implemented so that statistics can be calculated based on multiple generations
instead of a single generation. This can help to overcome problems with underpredicted variance in problems
where there is correlation between successive fission source iterations.
• Users now have the option to select a non-unionized energy grid for problems with many nuclides where the use
of a unionized grid is not feasible.
• Improved plotting capability (Nick Horelik). The plotting input is now in plots.xml instead of plot.xml.
• Added multiple estimators for k-effective and added a global tally for leakage.
• Moved cross section-related output into cross_sections.out.
• Improved timing capabilities.
• Can now use more than 2**31 - 1 particles per generation.
• Improved fission bank synchronization method. This also necessitated changing the source bank to be of type
Bank rather than of type Particle.
• Added HDF5 output (not complete yet).
• Major changes to tally implementation.
2.23.3 Bug Fixes
• b206a8: Fixed subtle error in the sampling of energy distributions.

• 800742: Fixed error in sampling of angle and rotating angles.
• a07c08: Fixed bug in linear-linear interpolation during sampling energy.
• a75283: Fixed energy and energyout tally filters to support many bins.
• 95cfac: Fixed error in cell neighbor searches.
• 83a803: Fixed bug related to probability tables.
2.23. What’s New in 0.4.1 41

variety of Linux distributions as well as Mac OS X. However, it has not been tested yet on any releases of Microsoft
Windows. Memory requirements will vary depending on the size of the problem at hand (mostly on the number of
nuclides in the problem).
2.24.2 New Features
• The probability table method for treatment of energy self-shielding in the unresolved resonance range has been
implemented and is now turned on by default.
• Calculation of Shannon entropy for assessing convergence of the fission source distribution.
• Ability to compile with the PGI Fortran compiler.
• Ability to run on IBM BlueGene/P machines.
• Completely rewrote how nested universes are handled. Geometry is now much more robust.
2.24.3 Bug Fixes
• Many geometry errors have been fixed. The Monte Carlo performance benchmark can now be successfully run
in OpenMC.

CHAPTER
THREE
THEORY AND METHODOLOGY
3.1 Introduction
The physical process by which a population of particles evolves over time is governed by a number of probability
distributions. For instance, given a particle traveling through some material, there is a probability distribution for the
distance it will travel until its next collision (an exponential distribution). Then, when it collides with a nucleus, there
is an associated probability of undergoing each possible reaction with that nucleus. While the behavior of any single
particle is unpredictable, the average behavior of a large population of particles originating from the same source is
well defined.
If the probability distributions that govern the transport of a particle are known, the process of single particles randomly
streaming and colliding with nuclei can be simulated directly with computers using a technique known as Monte Carlo
simulation. If enough particles are simulated this way, the average behavior can be determined to within arbitrarily
small statistical error, a fact guaranteed by the central limit theorem. To be more precise, the central limit theorem tells
us that the variance of the sample mean of some physical parameter being estimated with Monte Carlo will be inversely
proportional to the number of realizations, i.e. the number of particles we simulate:
1
𝜎2 ∝ .
𝑁
where 𝜎 2 is the variance of the sample mean and 𝑁 is the number of realizations.
3.1.1 Overview of Program Flow
OpenMC performs a Monte Carlo simulation one particle at a time – at no point is more than one particle being tracked
on a single program instance. Before any particles are tracked, the problem must be initialized. This involves the
following steps:
• Read input files and building data structures for the geometry, materials, tallies, and other associated variables.
• Initialize the pseudorandom number generator.
• Read the continuous-energy or multi-group cross section data specified in the problem.
• If using a special energy grid treatment such as a union energy grid or lethargy bins, that must be initialized as
well in a continuous-energy problem.
• In a multi-group problem, individual nuclide cross section information is combined to produce material-specific
cross section data.
• In a fixed source problem, source sites are sampled from the specified source. In an eigenvalue problem, source
sites are sampled from some initial source distribution or from a source file. The source sites consist of coordi-
nates, a direction, and an energy.
43
Once initialization is complete, the actual transport simulation can proceed. The life of a single particle will proceed
as follows:
1. The particle’s properties are initialized from a source site previously sampled.
2. Based on the particle’s coordinates, the current cell in which the particle resides is determined.
3. The energy-dependent cross sections for the material that the particle is currently in are determined. Note that
this includes the total cross section, which is not pre-calculated.
4. The distance to the nearest boundary of the particle’s cell is determined based on the bounding surfaces to the
cell.
5. The distance to the next collision is sampled. If the total material cross section is Σ𝑡 , this can be shown to be
ln 𝜉
𝑑=−
Σ𝑡
where 𝜉 is a pseudorandom number sampled from a uniform distribution on [0, 1).
6. If the distance to the nearest boundary is less than the distance to the next collision, the particle is moved forward
to this boundary. Then, the process is repeated from step 2. If the distance to collision is closer than the distance
to the nearest boundary, then the particle will undergo a collision.
7. The material at the collision site may consist of multiple nuclides. First, the nuclide with which the collision
will happen is sampled based on the total cross sections. If the total cross section of material 𝑖 is Σ𝑡,𝑖 , then the
probability that any nuclide is sampled is
Σ𝑡,𝑖
𝑃 (𝑖) = .
Σ𝑡
Note that the above selection of collided nuclide only applies to continuous-energy simulations as multi-group
simulations use nuclide data which has already been combined in to material-specific data.
8. Once the specific nuclide is sampled, a reaction for that nuclide is randomly sampled based on the microscopic
cross sections. If the microscopic cross section for some reaction 𝑥 is 𝜎𝑥 and the total microscopic cross section
for the nuclide is 𝜎𝑡 , then the probability that reaction 𝑥 will occur is
𝜎𝑥
𝑃 (𝑥) = .
𝜎𝑡
Since multi-group simulations use material-specific data, the above is performed with those material multi-group
cross sections (i.e., macroscopic cross sections for the material) instead of microscopic cross sections for the
nuclide).
9. If the sampled reaction is elastic or inelastic scattering, the outgoing energy and angle is sampled from the
appropriate distribution. In continuous-energy simulation, reactions of type (𝑛, 𝑥𝑛) are treated as scattering
and any additional particles which may be created are added to a secondary particle bank to be tracked later.
In a multi-group simulation, this secondary bank is not used but the particle weight is increased accordingly.
The original particle then continues from step 3. If the reaction is absorption or fission, the particle dies and if
necessary, fission sites are created and stored in the fission bank.
After all particles have been simulated, there are a few final tasks that must be performed before the run is finished.
This include the following:
• With the accumulated sum and sum of squares for each tally, the sample mean and its variance is calculated.
• All tallies and other results are written to disk.
• If requested, a source file is written to disk.
• Dynamically-allocated memory should be freed.
44 Chapter 3. Theory and Methodology

3.2 Geometry
3.2.1 Constructive Solid Geometry
OpenMC uses a technique known as constructive solid geometry (CSG) to build arbitrarily complex three-dimensional
models in Euclidean space. In a CSG model, every unique object is described as the union and/or intersection of
half-spaces created by bounding surfaces. Every surface divides all of space into exactly two half-spaces. We can
mathematically define a surface as a collection of points that satisfy an equation of the form 𝑓 (𝑥, 𝑦, 𝑧) = 0 where
𝑓 (𝑥, 𝑦, 𝑧) is a given function. All coordinates for which 𝑓 (𝑥, 𝑦, 𝑧) < 0 are referred to as the negative half-space (or
simply the negative side) and coordinates for which 𝑓 (𝑥, 𝑦, 𝑧) > 0 are referred to as the positive half-space.
Let us take the example of a sphere centered at the point (𝑥0 , 𝑦0 , 𝑧0 ) with radius 𝑅. One would normally write the
equation of the sphere as
(𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (3.2.1)
By subtracting the right-hand term from both sides of equation (3.2.1), we can then write the surface equation for the
sphere:
𝑓 (𝑥, 𝑦, 𝑧) = (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0 (3.2.2)
One can confirm that any point inside this sphere will correspond to 𝑓 (𝑥, 𝑦, 𝑧) < 0 and any point outside the sphere
will correspond to 𝑓 (𝑥, 𝑦, 𝑧) > 0.
In OpenMC, every surface defined by the user is assigned an integer to uniquely identify it. We can then refer to either
of the two half-spaces created by a surface by a combination of the unique ID of the surface and a positive/negative
sign. Figure 1 shows an example of an ellipse with unique ID 1 dividing space into two half-spaces.
+1 -1
Fig. 1: Example of an ellipse and its associated half-spaces.
References to half-spaces created by surfaces are used to define regions of space of uniform composition, which are
then assigned to cells. OpenMC allows regions to be defined using union, intersection, and complement operators. As
in MCNP, the intersection operator is implicit as doesn’t need to be written in a region specification. A defined region
is then associated with a material composition in a cell. Figure 2 shows an example of a cell region defined as the
intersection of an ellipse and two planes.
The ability to form regions based on bounding quadratic surfaces enables OpenMC to model arbitrarily complex three-
dimensional objects. In practice, one is limited only by the different surface types available in OpenMC. The following
table lists the available surface types, the identifier used to specify them in input files, the corresponding surface equa-
tion, and the input parameters needed to fully define the surface.
3.2. Geometry 45
+1
-1
-2 +2
+3
-3
Fig. 2: The shaded region represents a cell bounded by three surfaces.
Table 1: Surface types available in OpenMC.

Surface Identi- Equation Parameters
fier
Plane perpendicular to 𝑥- x-plane 𝑥 − 𝑥0 = 0 𝑥0
axis
Plane perpendicular to 𝑦- y-plane 𝑦 − 𝑦0 = 0 𝑦0
axis
Plane perpendicular to 𝑧- z-plane 𝑧 − 𝑧0 = 0 𝑧0
axis
Arbitrary plane plane 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷 𝐴𝐵𝐶𝐷
Infinite cylinder parallel x- (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 𝑦0 𝑧0 𝑅
to 𝑥-axis cylinder
Infinite cylinder parallel y- (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 𝑥0 𝑧0 𝑅
to 𝑦-axis cylinder
Infinite cylinder parallel z- (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑅2 𝑥0 𝑦0 𝑅
to 𝑧-axis cylinder
Sphere sphere (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 𝑥0 𝑦0 𝑧0 𝑅
Cone parallel to the 𝑥- x-cone (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (𝑥 − 𝑥0 )2 𝑥0 𝑦0 𝑧0 𝑅2
axis
Cone parallel to the 𝑦- y-cone (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (𝑦 − 𝑦0 )2 𝑥0 𝑦0 𝑧0 𝑅2
axis
Cone parallel to the 𝑧- z-cone (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑅2 (𝑧 − 𝑧0 )2 𝑥0 𝑦0 𝑧0 𝑅2
axis
General quadric surface quadric 𝐴𝑥2 + 𝐵𝑦 2 + 𝐶𝑧 2 + 𝐷𝑥𝑦 + 𝐸𝑦𝑧 + 𝐹 𝑥𝑧 + 𝐺𝑥 + 𝐴𝐵𝐶𝐷𝐸𝐹 𝐺𝐻𝐽 𝐾
𝐻𝑦 + 𝐽𝑧 + 𝐾 = 0√
( (𝑦−𝑦0 )2 +(𝑧−𝑧0 )2 −𝐴)2
Torus parallel to the 𝑥- x-torus (𝑥 − 𝑥0 )2 /𝐵 2 + 𝐶2 −1=0 𝑥0 𝑦0 𝑧0 𝐴 𝐵 𝐶
axis √
( (𝑥−𝑥0 )2 +(𝑧−𝑧0 )2 −𝐴)2
Torus parallel to the 𝑦- y-torus (𝑦 − 𝑦0 )2 /𝐵 2 + 𝐶2 −1=0 𝑥0 𝑦0 𝑧0 𝐴 𝐵 𝐶
axis √
( (𝑥−𝑥0 )2 +(𝑦−𝑦0 )2 −𝐴)2
Torus parallel to the 𝑧- z-torus (𝑧 − 𝑧0 )2 /𝐵 2 + 𝐶2 −1=0 𝑥0 𝑦0 𝑧0 𝐴 𝐵 𝐶
axis

Universes
OpenMC supports universe-based geometry similar to the likes of MCNP and Serpent. This capability enables user
to model any identical repeated structures once and then fill them in various spots in the geometry. A prototypical
example of a repeated structure would be a fuel pin within a fuel assembly or a fuel assembly within a core.
Each cell in OpenMC can either be filled with a normal material or with a universe. If the cell is filled with a universe,
only the region of the universe that is within the defined boundaries of the parent cell will be present in the geometry.
That is to say, even though a collection of cells in a universe may extend to infinity, not all of the universe will be
“visible” in the geometry since it will be truncated by the boundaries of the cell that contains it.
When a cell is filled with a universe, it is possible to specify that the universe filling the cell should be rotated and
translated. This is done through the rotation and translation attributes on a cell (note though that these can only
be specified on a cell that is filled with another universe, not a material).
It is not necessary to use or assign universes in a geometry if there are no repeated structures. Any cell in the geometry
that is not assigned to a specified universe is automatically part of the base universe whose coordinates are just the
normal coordinates in Euclidean space.
Lattices
Often times, repeated structures in a geometry occur in a regular pattern such as a rectangular or hexagonal lattice. In
such a case, it would be cumbersome for a user to have to define the boundaries of each of the cells to be filled with a
universe. Thus, OpenMC provides a lattice capability similar to that used in MCNP and Serpent.
The implementation of lattices is similar in principle to universes — instead of a cell being filled with a universe, the
user can specify that it is filled with a finite lattice. The lattice is then defined by a two-dimensional array of universes
that are to fill each position in the lattice. A good example of the use of lattices and universes can be seen in the
OpenMC model for the Monte Carlo Performance benchmark.
3.2.2 Computing the Distance to Nearest Boundary
One of the most basic algorithms in any Monte Carlo code is determining the distance to the nearest surface within a
cell. Since each cell is defined by the surfaces that bound it, if we compute the distance to all surfaces bounding a cell,
we can determine the nearest one.
With the possibility of a particle having coordinates on multiple levels (universes) in a geometry, we must exercise care
when calculating the distance to the nearest surface. Each different level of geometry has a set of boundaries with which
the particle’s direction of travel may intersect. Thus, it is necessary to check the distance to the surfaces bounding the
cell in each level. This should be done starting the highest (most global) level going down to the lowest (most local)
level. That ensures that if two surfaces on different levels are coincident, by default the one on the higher level will be
selected as the nearest surface. Although they are not explicitly defined, it is also necessary to check the distance to
surfaces representing lattice boundaries if a lattice exists on a given level.
The following procedure is used to calculate the distance to each bounding surface. Suppose we have a particle at
(𝑥0 , 𝑦0 , 𝑧0 ) traveling in the direction 𝑢0 , 𝑣0 , 𝑤0 . To find the distance 𝑑 to a surface 𝑓 (𝑥, 𝑦, 𝑧) = 0, we need to solve the
equation:
𝑓 (𝑥0 + 𝑑𝑢0 , 𝑦0 + 𝑑𝑣0 , 𝑧0 + 𝑑𝑤0 ) = 0 (3.2.3)
If no solutions to equation (3.2.3) exist or the only solutions are complex, then the particle’s direction of travel will not
intersect the surface. If the solution to equation (3.2.3) is negative, this means that the surface is “behind” the particle,
i.e. if the particle continues traveling in its current direction, it will not hit the surface. The complete derivation for
different types of surfaces used in OpenMC will be presented in the following sections.
3.2. Geometry 47
Since 𝑓 (𝑥, 𝑦, 𝑧) in general is quadratic in 𝑥, 𝑦, and 𝑧, this implies that 𝑓 (𝑥0 + 𝑑𝑢0 , 𝑦 + 𝑑𝑣0 , 𝑧 + 𝑑𝑤0 ) is quadratic in 𝑑.
Thus we expect at most two real solutions to (3.2.3). If no solutions to (3.2.3) exist or the only solutions are complex,
then the particle’s direction of travel will not intersect the surface. If the solution to (3.2.3) is negative, this means that
the surface is “behind” the particle, i.e. if the particle continues traveling in its current direction, it will not hit the
surface.
Once a distance has been computed to a surface, we need to check if it is closer than previously-computed distances
to surfaces. Unfortunately, we cannot just use the minimum function because some of the calculated distances, which
should be the same in theory (e.g. coincident surfaces), may be slightly different due to the use of floating-point
arithmetic. Consequently, we should first check for floating-point equality of the current distance calculated and the
minimum found thus far. This is done by checking if
|𝑑 − 𝑑𝑚𝑖𝑛 |
<𝜖 (3.2.4)
𝑑𝑚𝑖𝑛
where 𝑑 is the distance to a surface just calculated, 𝑑𝑚𝑖𝑛 is the minimum distance found thus far, and 𝜖 is a small
number. In OpenMC, this parameter is set to 𝜖 = 10−14 since all floating calculations are done on 8-byte floating point
numbers.
Plane Perpendicular to an Axis
The equation for a plane perpendicular to, for example, the x-axis is simply 𝑥 − 𝑥0 = 0. As such, we need to solve
𝑥 + 𝑑𝑢 − 𝑥0 = 0. The solution for the distance is
𝑥0 − 𝑥
𝑑= (3.2.5)
𝑢
Note that if the particle’s direction of flight is parallel to the x-axis, i.e. 𝑢 = 0, the distance to the surface will be
infinity. While the example here was for a plane perpendicular to the x-axis, the same formula can be applied for the
surfaces 𝑦 = 𝑦0 and 𝑧 = 𝑧0 .
Generic Plane
The equation for a generic plane is 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷. Thus, we need to solve the equation 𝐴(𝑥 + 𝑑𝑢) + 𝐵(𝑦 +
𝑑𝑣) + 𝐶(𝑧 + 𝑑𝑤) = 𝐷. The solution to this equation for the distance is
𝐷 − 𝐴𝑥 − 𝐵𝑦 − 𝐶𝑧
𝑑= (3.2.6)
𝐴𝑢 + 𝐵𝑣 + 𝐶𝑤
Again, we need to check whether the denominator is zero. If so, this means that the particle’s direction of flight is
parallel to the plane and it will therefore never hit the plane.
Cylinder Parallel to an Axis
The equation for a cylinder parallel to, for example, the x-axis is (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 . Thus, we need to solve
(𝑦 + 𝑑𝑣 − 𝑦0 )2 + (𝑧 + 𝑑𝑤 − 𝑧0 )2 = 𝑅2 . Let us define 𝑦¯ = 𝑦 − 𝑦0 and 𝑧¯ = 𝑧 − 𝑧0 . We then have
𝑦 + 𝑑𝑣)2 + (¯
(¯ 𝑧 + 𝑑𝑤)2 = 𝑅2 (3.2.7)
Expanding equation (3.2.7) and rearranging terms, we obtain
(𝑣 2 + 𝑤2 )𝑑2 + 2(¯ 𝑦 2 + 𝑧¯2 − 𝑅2 ) = 0

𝑦 𝑣 + 𝑧¯𝑤)𝑑 + (¯ (3.2.8)
This is a quadratic equation for 𝑑. To simplify notation, let us define 𝑎 = 𝑣 2 + 𝑤2 , 𝑘 = 𝑦¯𝑣 + 𝑧¯𝑤, and 𝑐 = 𝑦¯2 + 𝑧¯2 − 𝑅2 .
Thus, the distance is just the solution to 𝑎𝑑2 + 2𝑘𝑑 + 𝑐 = 0:
√
−𝑘 ± 𝑘 2 − 𝑎𝑐 (3.2.9)
𝑑=
𝑎

A few conditions must be checked for. If 𝑎 = 0, this means the particle is parallel to the cylinder and will thus never
intersect it. Also, if 𝑘 2 − 𝑎𝑐 < 0, this means that both solutions to the quadratic are complex. In physical terms, this
means that the ray along which the particle is traveling does not make any intersections with the cylinder.
If we do have intersections and 𝑐 < 0, this means that the particle is inside the cylinder. Thus, one solution should be
positive and one should be negative. Clearly, the positive distance will occur when the sign on the square root of the
discriminant is positive since 𝑎 > 0.
If we have intersections and 𝑐 > 0 this means that the particle is outside the cylinder. Thus, the solutions to the quadratic
are either both positive or both negative. If they are both positive, the smaller (closer) one will be the solution with a
negative sign on the square root of the discriminant.
The same equations and logic here can be used for cylinders that are parallel to the y- or z-axis with appropriate
substitution of constants.
Sphere
The equation for a sphere is (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 . Thus, we need to solve the equation
(𝑥 + 𝑑𝑢 − 𝑥0 )2 + (𝑦 + 𝑑𝑣 − 𝑦0 )2 + (𝑧 + 𝑑𝑤 − 𝑧0 )2 = 𝑅2 (3.2.10)
Let us define 𝑥
¯ = 𝑥 − 𝑥0 , 𝑦¯ = 𝑦 − 𝑦0 , and 𝑧¯ = 𝑧 − 𝑧0 . We then have
𝑥 + 𝑑𝑢)2 + (¯
(¯ 𝑦 + 𝑑𝑣)2 + (¯
𝑧 − 𝑑𝑤)2 = 𝑅2 (3.2.11)
𝑑2 + 2(¯ 𝑥2 + 𝑦¯2 + 𝑧¯2 − 𝑅2 ) = 0

𝑥𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤)𝑑 + (¯ (3.2.12)
This is a quadratic equation for 𝑑. To simplify notation, let us define 𝑘 = 𝑥

¯𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤 and 𝑐 = 𝑥
¯2 + 𝑦¯2 + 𝑧¯2 − 𝑅2 .
Thus, the distance is just the solution to 𝑑 + 2𝑘𝑑 + 𝑐 = 0:
2
(3.2.13)
√︀
𝑑 = −𝑘 ± 𝑘 2 − 𝑐
If the discriminant 𝑘 2 − 𝑐 < 0, this means that both solutions to the quadratic are complex. In physical terms, this
means that the ray along which the particle is traveling does not make any intersections with the sphere.
If we do have intersections and 𝑐 < 0, this means that the particle is inside the sphere. Thus, one solution should
be positive and one should be negative. The positive distance will occur when the sign on the square root of the
discriminant is positive. If we have intersections but 𝑐 > 0 this means that the particle is outside the sphere. The
solutions to the quadratic will then be either both positive or both negative. If they are both positive, the smaller
(closer) one will be the solution with a negative sign on the square root of the discriminant.
Cone Parallel to an Axis
The equation for a cone parallel to, for example, the x-axis is (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (𝑥 − 𝑥0 )2 . Thus, we need to
solve (𝑦 + 𝑑𝑣 − 𝑦0 )2 + (𝑧 + 𝑑𝑤 − 𝑧0 )2 = 𝑅2 (𝑥 + 𝑑𝑢 − 𝑥0 )2 . Let us define 𝑥 ¯ = 𝑥 − 𝑥0 , 𝑦¯ = 𝑦 − 𝑦0 , and 𝑧¯ = 𝑧 − 𝑧0 .
We then have
𝑦 + 𝑑𝑣)2 + (¯
(¯ 𝑧 + 𝑑𝑤)2 = 𝑅2 (¯
𝑥 + 𝑑𝑢)2 (3.2.14)
(𝑣 2 + 𝑤2 − 𝑅2 𝑢2 )𝑑2 + 2(¯
𝑦 𝑣 + 𝑧¯𝑤 − 𝑅2 𝑥 𝑦 2 + 𝑧¯2 − 𝑅2 𝑥
¯𝑢)𝑑 + (¯ ¯2 ) = 0 (3.2.15)
3.2. Geometry 49
Defining the terms
𝑎 = 𝑣 2 + 𝑤2 − 𝑅2 𝑢2
𝑘 = 𝑦¯𝑣 + 𝑧¯𝑤 − 𝑅2 𝑥
¯𝑢 (3.2.16)
2 2 2 2
𝑐 = 𝑦¯ + 𝑧¯ − 𝑅 𝑥
¯
we then have the simple quadratic equation 𝑎𝑑2 + 2𝑘𝑑 + 𝑐 = 0 which can be solved as described in Cylinder Parallel
to an Axis.
General Quadric
The equation for a general quadric surface is 𝐴𝑥2 + 𝐵𝑦 2 + 𝐶𝑧 2 + 𝐷𝑥𝑦 + 𝐸𝑦𝑧 + 𝐹 𝑥𝑧 + 𝐺𝑥 + 𝐻𝑦 + 𝐽𝑧 + 𝐾 = 0.

Thus, we need to solve the equation
𝐴(𝑥 + 𝑑𝑢)2 + 𝐵(𝑦 + 𝑑𝑣)2 + 𝐶(𝑧 + 𝑑𝑤)2 + 𝐷(𝑥 + 𝑑𝑢)(𝑦 + 𝑑𝑣) + 𝐸(𝑦 + 𝑑𝑣)(𝑧 + 𝑑𝑤)+
(3.2.17)
𝐹 (𝑥 + 𝑑𝑢)(𝑧 + 𝑑𝑤) + 𝐺(𝑥 + 𝑑𝑢) + 𝐻(𝑦 + 𝑑𝑣) + 𝐽(𝑧 + 𝑑𝑤) + 𝐾 = 0
𝑑2 (𝑢𝑣 + 𝑣𝑤 + 𝑢𝑤) + 2𝑑(𝐴𝑢𝑥 + 𝐵𝑣𝑦 + 𝐶𝑤𝑥 + (𝐷(𝑢𝑣 + 𝑣𝑥) + 𝐸(𝑣𝑧 + 𝑤𝑦)+

(3.2.18)
𝐹 (𝑤𝑥 + 𝑢𝑧))/2) + (𝑥(𝐴𝑥 + 𝐷𝑦) + 𝑦(𝐵𝑦 + 𝐸𝑧) + 𝑧(𝐶𝑧 + 𝐹 𝑥)) = 0
Defining the terms
𝑎 = 𝑢𝑣 + 𝑣𝑤 + 𝑢𝑤
𝑘 = 𝐴𝑢𝑥 + 𝐵𝑣𝑦 + 𝐶𝑤𝑥 + (𝐷(𝑢𝑣 + 𝑣𝑥) + 𝐸(𝑣𝑧 + 𝑤𝑦) + 𝐹 (𝑤𝑥 + 𝑢𝑧))/2 (3.2.19)
𝑐 = 𝑥(𝐴𝑥 + 𝐷𝑦) + 𝑦(𝐵𝑦 + 𝐸𝑧) + 𝑧(𝐶𝑧 + 𝐹 𝑥)
we then have the simple quadratic equation 𝑎𝑑2 + 2𝑘𝑑 + 𝑐 = 0 which can be solved as described in Cylinder Parallel
to an Axis.
Torus Parallel to an Axis
The equation for a torus parallel to, for example, the x-axis is
√︀
(𝑥 − 𝑥0 )2 ( (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 (3.2.20)
+ − 1 = 0.
𝐵2 𝐶2
First, it needs to be cast into a polynomial form. Rearranging terms,
𝑥2 + 𝑦¯2 + 𝑧¯2 + 𝐴2 − 𝐶 2 )2 = 4𝐴2 (¯

(𝐷¯ 𝑦 2 + 𝑧¯2 ) (3.2.21)
where 𝐷 = (𝐶/𝐵)2 , 𝑥
¯ = 𝑥 − 𝑥0 , 𝑦¯ = 𝑦 − 𝑦0 , and 𝑧¯ = 𝑧 − 𝑧0 . To find the distance to the surface, we thus need to
solve
𝑥 + 𝑑𝑢)2 + (¯
(𝐷(¯ 𝑦 + 𝑑𝑣)2 + (¯
𝑧 + 𝑑𝑤)2 + 𝐴2 − 𝐶 2 )2 = 4𝐴2 ((¯
𝑦 + 𝑑𝑣)2 + (¯
𝑧 + 𝑑𝑤)2 ). (3.2.22)
Expanding and collecting like powers of 𝑑 yields
(𝑐2 𝑑2 + 𝑐1 𝑑 + 𝑐0 )2 = 𝑐′2 𝑑2 + 𝑐′1 𝑑 + 𝑐′0 (3.2.23)

where
𝑐2 = 𝐷𝑢2 + 𝑣 2 + 𝑤2
𝑐1 = 2(𝐷𝑢¯
𝑥 + 𝑣 𝑦¯ + 𝑤¯
𝑧)
𝑥2 + 𝑦¯2 + 𝑧¯2 + 𝐴2 − 𝐶 2
𝑐0 = 𝐷¯
(3.2.24)
𝑐′2 = 4𝐴2 (𝑣 2 + 𝑤2 )
𝑐′1 = 8𝐴2 (𝑣 𝑦¯ + 𝑤¯
𝑧)
𝑐′0 = 4𝐴2 (¯
𝑦 2 + 𝑧¯2 ).
Expanding the left-hand side and collecting like powers of 𝑑 on one side, we obtain
(𝑐22 )𝑑4 + (2𝑐1 𝑐2 )𝑑3 + (𝑐21 + 2𝑐0 𝑐2 − 𝑐′2 )𝑑2 + (2𝑐0 𝑐1 − 𝑐′1 )𝑑 + (𝑐20 − 𝑐′0 ) = 0. (3.2.25)
The above equation is a fourth-order (quartic) polynomial equation. Although there is an analytical solution to the gen-
eral quartic equation, it can be subject to roundoff errors when evaluated numerically. OpenMC uses an external quartic
equation solver developed by Orellana and De Michele that is based on the decomposition of the quartic polynomial
into two quadratics.
3.2.3 Finding a Cell Given a Point
Another basic algorithm is to determine which cell contains a given point in the global coordinate system, i.e. if the
particle’s position is (𝑥, 𝑦, 𝑧), what cell is it currently in. This is done in the following manner in OpenMC. With the
possibility of multiple levels of coordinates, we must perform a recursive search for the cell. First, we start in the highest
(most global) universe, which we call the base universe, and loop over each cell within that universe. For each cell, we
check whether the specified point is inside the cell using the algorithm described in Finding a Lattice Tile. If the cell is
filled with a normal material, the search is done and we have identified the cell containing the point. If the cell is filled
with another universe, we then search all cells within that universe to see if any of them contain the specified point. If
the cell is filled with a lattice, the position within the lattice is determined, and then whatever universe fills that lattice
position is recursively searched. The search ends once a cell containing a normal material is found that contains the
specified point.
3.2.4 Finding a Lattice Tile
If a particle is inside a lattice, its position inside the lattice must be determined before assigning it to a cell. Throughout
this section, the volumetric units of the lattice will be referred to as “tiles”. Tiles are identified by thier indices, and the
process of discovering which tile contains the particle is referred to as “indexing”.
Rectilinear Lattice Indexing
Indices are assigned to tiles in a rectilinear lattice based on the tile’s position along the 𝑥, 𝑦, and 𝑧 axes. Figure 3 maps
the indices for a 2D lattice. The indices, (1, 1), map to the lower-left tile. (5, 1) and (5, 5) map to the lower-right and
upper-right tiles, respectively.
In general, a lattice tile is specified by the three indices, (𝑖𝑥 , 𝑖𝑦 , 𝑖𝑧 ). If a particle’s current coordinates are (𝑥, 𝑦, 𝑧) then
the indices can be determined from these formulas:
⌈︂ ⌉︂
𝑥 − 𝑥0
𝑖𝑥 =
𝑝0
⌈︂ ⌉︂
𝑦 − 𝑦0
𝑖𝑦 = (3.2.26)
𝑝1
⌈︂ ⌉︂
𝑧 − 𝑧0
𝑖𝑧 =
𝑝2
3.2. Geometry 51
Fig. 3: Rectilinear lattice tile indices.

where (𝑥0 , 𝑦0 , 𝑧0 ) are the coordinates to the lower-left-bottom corner of the lattice, and 𝑝0 , 𝑝1 , 𝑝2 are the pitches along
the 𝑥, 𝑦, and 𝑧 axes, respectively.
Hexagonal Lattice Indexing
A skewed coordinate system is used for indexing hexagonal lattice tiles. Rather than a 𝑦-axis, another axis is used that
is rotated 30 degrees counter-clockwise from the 𝑦-axis. This axis is referred to as the 𝛼-axis. Figure 4 shows how 2D
hexagonal tiles are mapped with the (𝑥, 𝛼) basis. In this system, (0, 0) maps to the center tile, (0, 2) to the top tile, and
(2, -1) to the middle tile on the right side.
Fig. 4: Hexagonal lattice tile indices.
Unfortunately, the indices cannot be determined with one simple formula as before. Indexing requires a two-step
process, a coarse step which determines a set of four tiles that contains the particle and a fine step that determines
which of those four tiles actually contains the particle.
In the first step, indices are found using these formulas:
𝑥
𝛼 = −√ + 𝑦
3
⌊︂ ⌋︂
𝑥
𝑖*𝑥 = √ (3.2.27)
𝑝0 3/2
⌊︂ ⌋︂
* 𝛼
𝑖𝛼 =
𝑝0
where 𝑝0 is the lattice pitch (in the 𝑥-𝑦 plane). The true index of the particle could be (𝑖*𝑥 , 𝑖*𝛼 ), (𝑖*𝑥 + 1, 𝑖*𝛼 ), (𝑖*𝑥 , 𝑖*𝛼 + 1),
or (𝑖*𝑥 + 1, 𝑖*𝛼 + 1).
3.2. Geometry 53
The second step selects the correct tile from that neighborhood of 4. OpenMC does this by calculating the distance
between the particle and the centers of each of the 4 tiles, and then picking the closest tile. This works because regular
hexagonal tiles form a Voronoi tessellation which means that all of the points within a tile are closest to the center of
that same tile.
Indexing along the 𝑧-axis uses the same method from rectilinear lattices, i.e.
⌈︂ ⌉︂
𝑧 − 𝑧0
𝑖𝑧 = (3.2.28)
𝑝2
3.2.5 Determining if a Coordinate is in a Cell
To determine which cell a particle is in given its coordinates, we need to be able to check whether a given cell contains
a point. The algorithm for determining if a cell contains a point is as follows. For each surface that bounds a cell, we
determine the particle’s sense with respect to the surface. As explained earlier, if we have a point (𝑥0 , 𝑦0 , 𝑧0 ) and a
surface 𝑓 (𝑥, 𝑦, 𝑧) = 0, the point is said to have negative sense if 𝑓 (𝑥0 , 𝑦0 , 𝑧0 ) < 0 and positive sense if 𝑓 (𝑥0 , 𝑦0 , 𝑧0 ) >
0. If for all surfaces, the sense of the particle with respect to the surface matches the specified sense that defines the
half-space within the cell, then the point is inside the cell. Note that this algorithm works only for simple cells defined
as intersections of half-spaces.
It may help to illustrate this algorithm using a simple example. Let’s say we have a cell defined as
<surface id="1" type="sphere" coeffs="0 0 0 10" />

<surface id="2" type="x-plane" coeffs="-3" />
<surface id="3" type="y-plane" coeffs="2" />
<cell id="1" surfaces="-1 2 -3" />
This means that the cell is defined as the intersection of the negative half space of a sphere, the positive half-space of an
x-plane, and the negative half-space of a y-plane. Said another way, any point inside this cell must satisfy the following
equations
𝑥2 + 𝑦 2 + 𝑧 2 − 102 < 0
𝑥 − (−3) > 0 (3.2.29)
𝑦−2<0
In order to determine if a point is inside the cell, we would substitute its coordinates into equation (3.2.29). If the
inequalities are satisfied, than the point is indeed inside the cell.
3.2.6 Handling Surface Crossings
A particle will cross a surface if the distance to the nearest surface is closer than the distance sampled to the next
collision. A number of things happen when a particle hits a surface. First, we need to check if a non-transmissive
boundary condition has been applied to the surface. If a vacuum boundary condition has been applied, the particle is
killed and any surface current tallies are scored to as needed. If a reflective boundary condition has been applied to
the surface, surface current tallies are scored to and then the particle’s direction is changed according to the procedure
in Reflective Boundary Conditions. Note that the white boundary condition can be considered as the special case
of reflective boundary condition, where the same processing method will be applied to deal with the surface current
tallies scoring, except for determining the changes of particle’s direction according to the procedures in White Boundary
Conditions.
Next, we need to determine what cell is beyond the surface in the direction of travel of the particle so that we can
evaluate cross sections based on its material properties. At initialization, a list of neighboring cells is created for each
surface in the problem as described in Building Neighbor Lists. The algorithm outlined in Finding a Cell Given a Point
is used to find a cell containing the particle with one minor modification; rather than searching all cells in the base

universe, only the list of neighboring cells is searched. If this search is unsuccessful, then a search is done over every
cell in the base universe.
3.2.7 Building Neighbor Lists
Neighbor lists are data structures that are used to accelerate geometry searches when a particle crosses a boundary.
Namely, they are used to constrain the number of cells that must be searched in order to determine which cell a particle
is crossing into. Earlier versions of OpenMC relied on “surface-based” neighbor lists, where the cells that are adjacent
to each surface are stored in lists, one for each side of a surface. As of version 0.11, OpenMC switched to using “cell-
based” neighbor lists. For each cell, a list of the adjacent cells is stored and then used to limit future searches. Unlike
surface-based neighbor lists, cell-based neighbor lists cannot be computed prior to transport. Thus, cell-based neighbor
lists in OpenMC grow dynamically as particles are transported through the geometry and cross surfaces. Special care
must be taken to ensure that these dynamic neighbor lists are populated in a threadsafe manner. Full details of the
implementation in OpenMC can be found in a paper by Harper et al.
3.2.8 Reflective Boundary Conditions
If the velocity of a particle is v and it crosses a surface of the form 𝑓 (𝑥, 𝑦, 𝑧) = 0 with a reflective boundary condition,
it can be shown based on geometric arguments that the velocity vector will then become
v′ = v − 2(v · n̂)n̂ (3.2.30)
where n̂ is a unit vector normal to the surface at the point of the surface crossing. The rationale for this can be understood
by noting that (v · n̂)n̂ is the projection of the velocity vector onto the normal vector. By subtracting two times this
projection, the velocity is reflected with respect to the surface normal. Since the magnitude of the velocity of the
particle will not change as it undergoes reflection, we can work with the direction of the particle instead, simplifying
equation (3.2.30) to
Ω′ = Ω − 2(Ω · n̂)n̂ (3.2.31)
where v = ||v||Ω. The direction of the surface normal will be the gradient of the surface at the point of crossing, i.e.
n = ∇𝑓 (𝑥, 𝑦, 𝑧). Substituting this into equation (3.2.31), we get
2(Ω · ∇𝑓 )
Ω′ = Ω − ∇𝑓 (3.2.32)
||∇𝑓 ||2
If we write the initial and final directions in terms of their vector components, Ω = (𝑢, 𝑣, 𝑤) and Ω′ = (𝑢′ , 𝑣 ′ , 𝑤′ ),
this allows us to represent equation (3.2.31) as a series of equations:
2(Ω · ∇𝑓 ) 𝜕𝑓
𝑢′ = 𝑢 −
||∇𝑓 ||2 𝜕𝑥
2(Ω · ∇𝑓 ) 𝜕𝑓
𝑣′ = 𝑣 − (3.2.33)
||∇𝑓 ||2 𝜕𝑦
2(Ω · ∇𝑓 ) 𝜕𝑓
𝑤′ = 𝑤 −
||∇𝑓 ||2 𝜕𝑧
One can then use equation (3.2.33) to develop equations for transforming a particle’s direction given the equation of
the surface.
3.2. Geometry 55
Plane Perpendicular to an Axis
For a plane that is perpendicular to an axis, the rule for reflection is almost so simple that no derivation is needed at all.
Nevertheless, we will proceed with the derivation to confirm that the rules of geometry agree with our intuition. The
gradient of the surface 𝑓 (𝑥, 𝑦, 𝑧) = 𝑥 − 𝑥0 = 0 is simply ∇𝑓 = (1, 0, 0). Note that this vector is already normalized,
i.e. ||∇𝑓 || = 1. The second two equations in (3.2.33) tell us that 𝑣 and 𝑤 do not change and the first tell us that
𝑢′ = 𝑢 − 2𝑢 = −𝑢 (3.2.34)
We see that reflection for a plane perpendicular to an axis only entails negating the directional cosine for that axis.
Generic Plane
A generic plane has the form 𝑓 (𝑥, 𝑦, 𝑧) = 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 − 𝐷 = 0. Thus, the gradient to the surface is simply
∇𝑓 = (𝐴, 𝐵, 𝐶) whose norm squared is 𝐴2 + 𝐵 2 + 𝐶 2 . This implies that
2(Ω · ∇𝑓 ) 2(𝐴𝑢 + 𝐵𝑣 + 𝐶𝑤)

= (3.2.35)
||∇𝑓 ||2 𝐴2 + 𝐵 2 + 𝐶 2
Substituting equation (3.2.35) into equation (3.2.33) gives us the form of the solution. For example, the x-component
of the reflected direction will be
2𝐴(𝐴𝑢 + 𝐵𝑣 + 𝐶𝑤)
𝑢′ = 𝑢 − (3.2.36)
𝐴2 + 𝐵 2 + 𝐶 2
Cylinder Parallel to an Axis
A cylinder parallel to, for example, the x-axis has the form 𝑓 (𝑥, 𝑦, 𝑧) = (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0. Thus, the
gradient to the surface is
⎛ ⎞ ⎛ ⎞
0 0
∇𝑓 = 2 ⎝ 𝑦 − 𝑦0 ⎠ = 2 ⎝ 𝑦¯ ⎠ (3.2.37)
𝑧 − 𝑧0 𝑧¯
where we have introduced the constants 𝑦¯ and 𝑧¯. Taking the square of the norm of the gradient, we find that
||∇𝑓 ||2 = 4¯
𝑦 2 + 4¯
𝑧 2 = 4𝑅2 (3.2.38)
This implies that
2(Ω · ∇𝑓 ) 𝑦¯𝑣 + 𝑧¯𝑤

2
= (3.2.39)
||∇𝑓 || 𝑅2
Substituting equations (3.2.39) and (3.2.37) into equation (3.2.33) gives us the form of the solution. In this case, the
x-component will not change. The y- and z-components of the reflected direction will be
2(¯
𝑦 𝑣 + 𝑧¯𝑤)¯
𝑦
𝑣′ = 𝑣 −
𝑅2
(3.2.40)
2(¯
𝑦 𝑣 + 𝑧¯𝑤)¯
𝑧
𝑤′ = 𝑤 − 2
𝑅

Sphere
The surface equation for a sphere has the form 𝑓 (𝑥, 𝑦, 𝑧) = (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0. Thus, the
gradient to the surface is
⎛ ⎞ ⎛ ⎞
𝑥 − 𝑥0 𝑥 ¯
∇𝑓 = 2 ⎝ 𝑦 − 𝑦0 ⎠ = 2 ⎝ 𝑦¯ ⎠ (3.2.41)
𝑧 − 𝑧0 𝑧¯
where we have introduced the constants 𝑥
¯, 𝑦¯, 𝑧¯. Taking the square of the norm of the gradient, we find that
||∇𝑓 ||2 = 4¯
𝑥2 + 4¯
𝑦 2 + 4¯
𝑧 2 = 4𝑅2 (3.2.42)
This implies that

2(Ω · ∇𝑓 ) 𝑥
¯𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤
= (3.2.43)
||∇𝑓 ||2 𝑅2
Substituting equations (3.2.43) and (3.2.41) into equation (3.2.33) gives us the form of the solution:
2(¯
𝑥𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤)¯
𝑥
𝑢′ = 𝑢 −
𝑅2
2(¯
𝑥𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤)¯
𝑦
𝑣′ = 𝑣 − (3.2.44)
𝑅 2
2(¯
𝑥𝑢 + 𝑦¯𝑣 + 𝑧¯𝑤)¯
𝑧
𝑤′ = 𝑤 −
𝑅2
Cone Parallel to an Axis
A cone parallel to, for example, the z-axis has the form 𝑓 (𝑥, 𝑦, 𝑧) = (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝑅2 (𝑧 − 𝑧0 )2 = 0. Thus,
the gradient to the surface is
⎛ ⎞ ⎛ ⎞
𝑥 − 𝑥0 𝑥
¯
∇𝑓 = 2 ⎝ 𝑦 − 𝑦0 ⎠ = 2 ⎝ 𝑦¯ ⎠ (3.2.45)
2
−𝑅 (𝑧 − 𝑧0 ) −𝑅2 𝑧¯
where we have introduced the constants 𝑥
¯, 𝑦¯, and 𝑧¯. Taking the square of the norm of the gradient, we find that
||∇𝑓 ||2 = 4¯
𝑥2 + 𝑦¯2 + 4𝑅4 𝑧¯2
= 4𝑅2 𝑧¯2 + 4𝑅4 𝑧¯2 (3.2.46)
2 2 2
= 4𝑅 (1 + 𝑅 )¯
𝑧
This implies that
2(Ω · ∇𝑓 ) ¯𝑢 + 𝑦¯𝑣 − 𝑅2 𝑧¯𝑤
𝑥
= (3.2.47)
||∇𝑓 ||2 𝑅2 (1 + 𝑅2 )¯
𝑧2
Substituting equations (3.2.47) and (3.2.45) into equation (3.2.33) gives us the form of the solution:
𝑥𝑢 + 𝑦¯𝑣 − 𝑅2 𝑧¯𝑤)¯
2(¯ 𝑥
𝑢′ = 𝑢 −
𝑅2 (1 + 𝑅2 )¯
𝑧2
𝑥𝑢 + 𝑦¯𝑣 − 𝑅2 𝑧¯𝑤)¯
2(¯ 𝑦
𝑣′ = 𝑣 − (3.2.48)
𝑅2 (1 + 𝑅2 )¯
𝑧2
2(¯𝑥𝑢 + 𝑦¯𝑣 − 𝑅2 𝑧¯𝑤)
𝑤′ = 𝑤 +
𝑅2 (1 + 𝑅2 )¯
𝑧
3.2. Geometry 57
General Quadric
A general quadric surface has the form 𝑓 (𝑥, 𝑦, 𝑧) = 𝐴𝑥2 +𝐵𝑦 2 +𝐶𝑧 2 +𝐷𝑥𝑦 +𝐸𝑦𝑧 +𝐹 𝑥𝑧 +𝐺𝑥+𝐻𝑦 +𝐽𝑧 +𝐾 = 0.
Thus, the gradient to the surface is
⎛ ⎞
2𝐴𝑥 + 𝐷𝑦 + 𝐹 𝑧 + 𝐺
∇𝑓 = ⎝ 2𝐵𝑦 + 𝐷𝑥 + 𝐸𝑧 + 𝐻 ⎠ . (3.2.49)
2𝐶𝑧 + 𝐸𝑦 + 𝐹 𝑥 + 𝐽
Torus Parallel to an Axis
A torus parallel to, for example, the x-axis has the form
√︀
(𝑥 − 𝑥0 )2 ( (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 (3.2.50)
𝑓 (𝑥, 𝑦, 𝑧) = + − 1.
𝐵2 𝐶2
The gradient to the surface is therefore
𝑥/𝐵 2
⎛ ⎞
2¯
𝑦 (𝑔 − 𝐴)/(𝐶 2 𝑔) ⎠
∇𝑓 = ⎝ 2¯ (3.2.51)
𝑧 (𝑔 − 𝐴)/(𝐶 2 𝑔)
2¯
where 𝑔 = 𝑦¯2 + 𝑧¯2 and, as always, 𝑥

¯ = 𝑥 − 𝑥0 , 𝑦¯ = 𝑦 − 𝑦0 , and 𝑧¯ = 𝑧 − 𝑧0 .
√︀
3.2.9 White Boundary Conditions
The white boundary condition is usually applied in deterministic codes, where the particle will hit the surface and
travel back with isotropic angular distribution. The change in particle’s direction is sampled from a cosine distribution
instead of uniform. Figure 5 shows an example of cosine-distribution reflection on the arbitrary surface relative to the
surface normal.
The probability density function (pdf) for the reflected direction can be expressed as follows,
𝜇 𝑑𝜑
𝑓 (𝜇, 𝜑)𝑑𝜇𝑑𝜑 = 𝑑𝜇𝑑𝜑 = 2𝜇𝑑𝜇 (3.2.52)
𝜋 2𝜋
where 𝜇 = cos 𝜃 is the cosine of the polar angle between reflected direction and the normal to the surface; and 𝜃 is the
azimuthal angle in [0, 2𝜋]. We can separate the multivariate probability density into two separate univariate density
functions, one for the cosine of the polar angle,
𝑓 (𝜇) = 2𝜇 (3.2.53)
and one for the azimuthal angle,

1
𝑓 (𝜑) = . (3.2.54)
2𝜋
Each of these density functions can be sampled by analytical inversion of the cumulative distribution distribution,
resulting in the following sampling scheme:
√︀
𝜇 = 𝜉1
(3.2.55)
𝜑 = 2𝜋𝜉2
where 𝜉1 and 𝜉2 are uniform random numbers on [0, 1). With the sampled values of 𝜇 and 𝜑, the final reflected
direction vector can be computed via rotation of the surface normal using the equations from Transforming a Particle’s
Coordinates. The white boundary condition can be applied to any kind of surface, as long as the normal to the surface
is known as in Reflective Boundary Conditions.

Fig. 5: Cosine-distribution reflection on an arbitrary surface.
3.3 Cross Section Representations
3.3.1 Continuous-Energy Data
In OpenMC, the data governing the interaction of neutrons with various nuclei for continuous-energy problems are
represented using an HDF5 format that can be produced by converting files in the ACE format, which is used by MCNP
and Serpent. ACE-format data can be generated with the NJOY nuclear data processing system, which converts raw
ENDF/B data into linearly-interpolable data as required by most Monte Carlo codes. Since ACE-format data can be
converted into OpenMC’s HDF5 format, it is possible to perform direct comparison of OpenMC with other codes using
the same underlying nuclear data library.
The ACE format contains continuous-energy cross sections for the following types of reactions: elastic scattering,
fission (or first-chance fission, second-chance fission, etc.), inelastic scattering, (𝑛, 𝑥𝑛), (𝑛, 𝛾), and various other ab-
sorption reactions. For those reactions with one or more neutrons in the exit channel, secondary angle and energy
distributions may be provided. In addition, fissionable nuclides have total, prompt, and/or delayed 𝜈 as a function of
energy and neutron precursor distributions. Many nuclides also have probability tables to be used for accurate treatment
of self-shielding in the unresolved resonance range. For bound scatterers, separate tables with 𝑆(𝛼, 𝛽, 𝑇 ) scattering
law data can be used.
3.3. Cross Section Representations 59

Energy Grid Methods
The method by which continuous-energy cross sections for each nuclide in a problem are stored as a function of energy
can have a substantial effect on the performance of a Monte Carlo simulation. Since the ACE format is based on
linearly-interpolable cross sections, each nuclide has cross sections tabulated over a wide range of energies. Some
nuclides may only have a few points tabulated (e.g. H-1) whereas other nuclides may have hundreds or thousands of
points tabulated (e.g. U-238).
At each collision, it is necessary to sample the probability of having a particular type of interaction whether it be elastic
scattering, (𝑛, 2𝑛), level inelastic scattering, etc. This requires looking up the microscopic cross sections for these
reactions for each nuclide within the target material. Since each nuclide has a unique energy grid, it would be necessary
to search for the appropriate index for each nuclide at every collision. This can become a very time-consuming process,
especially if there are many nuclides in a problem as there would be for burnup calculations. Thus, there is a strong
motive to implement a method of reducing the number of energy grid searches in order to speed up the calculation.
Logarithmic Mapping
To speed up energy grid searches, OpenMC uses a logarithmic mapping technique to limit the range of energies that
must be searched for each nuclide. The entire energy range is divided up into equal-lethargy segments, and the bounding
energies of each segment are mapped to bounding indices on each of the nuclide energy grids. By default, OpenMC
uses 8000 equal-lethargy segments as recommended by Brown.
Other Methods
A good survey of other energy grid techniques, including unionized energy grids, can be found in a paper by Leppanen.
Windowed Multipole Representation
In addition to the usual pointwise representation of cross sections, OpenMC offers support for a data format called
windowed multipole (WMP). This data format requires less memory than pointwise cross sections, and it allows on-
the-fly Doppler broadening to arbitrary temperature.
The multipole method was introduced by Hwang and the faster windowed multipole method by Josey. In the multipole
format, cross section resonances are represented by poles, 𝑝𝑗 , and residues, 𝑟𝑗 , in the complex plane. The 0K cross
sections in the resolved resonance region can be computed by summing up a contribution from each pole:
[︃ ]︃
1 ∑︁ 𝑖𝑟𝑗
𝜎(𝐸, 𝑇 = 0K) = Re √
𝐸 𝑗 𝐸 − 𝑝𝑗
Assuming free-gas thermal motion, cross sections in the multipole form can be analytically Doppler broadened to give
the form:
√
[︂ (︂ )︂]︂
1 ∑︁ 𝑟𝑗 𝑝𝑗 𝑢
𝜎(𝐸, 𝑇 ) = √ Re 𝑟𝑗 𝜋𝑊𝑖 (𝑧) − √ 𝐶 √ , √
2𝐸 𝜉 𝑗 𝜋 𝜉 2 𝜉
2
𝑖 ∞ 𝑒−𝑡
∫︁
𝑊𝑖 (𝑧) = 𝑑𝑡
𝜋 −∞ 𝑧 − 𝑡
∫︁ ∞ ′ 2
𝑒−(𝑢+𝑢 ) /4𝜉
(︂ )︂
𝑝𝑗 𝑢
𝐶 √ , √ = 2𝑝𝑗 𝑑𝑢′
𝜉 2 𝜉 0 𝑝2𝑗 − 𝑢′2
√
𝐸 − 𝑝𝑗
𝑧= √
2 𝜉

𝑘𝐵 𝑇
𝜉=
4𝐴
√
𝑢= 𝐸
where 𝑇 is the temperature of the resonant scatterer, 𝑘𝐵 is the Boltzmann constant, 𝐴 is the mass of the target nucleus.
For 𝐸 ≫ 𝑘𝑏 𝑇 /𝐴, the 𝐶 integral is approximately zero, simplifying the cross section to:
1 ∑︁ [︀ √
Re 𝑖𝑟𝑗 𝜋𝑊𝑖 (𝑧)
]︀
𝜎(𝐸, 𝑇 ) = √
2𝐸 𝜉 𝑗
The 𝑊𝑖 integral simplifies down to an analytic form. We define the Faddeeva function, 𝑊 as:
2
𝑊 (𝑧) = 𝑒−𝑧 Erfc(−𝑖𝑧)
Through this, the integral transforms as follows:
Im(𝑧) > 0 : 𝑊𝑖 (𝑧) = 𝑊 (𝑧)
Im(𝑧) < 0 : 𝑊𝑖 (𝑧) = −𝑊 (𝑧 * )*

There are freely available algorithms to evaluate the Faddeeva function. For many nuclides, the Faddeeva function
needs to be evaluated thousands of times to calculate a cross section. To mitigate that computational cost, the WMP
method only evaluates poles within a certain energy “window” around the incident neutron energy and accounts for
the effect of resonances outside that window with a polynomial fit. This polynomial fit is then broadened exactly. This
exact broadening can make up for the removal of the 𝐶 integral, as typically at low energies, only curve fits are used.
Note that the implementation of WMP in OpenMC currently assumes that inelastic scattering does not occur in the
resolved resonance region. This is usually, but not always the case. Future library versions may eliminate this issue.
The data format used by OpenMC to represent windowed multipole data is specified in Windowed Multipole Library
Format with a publicly available WMP library.
Temperature Treatment
At the beginning of a simulation, OpenMC collects a list of all temperatures that are present in a model. It then uses
this list to determine what cross sections to load. The data that is loaded depends on what temperature method has been
selected. There are three methods available:
Nearest
Cross sections are loaded only if they are within a specified tolerance of the actual temperatures in
the model.
Interpolation
Cross sections are loaded at temperatures that bound the actual temperatures in the model. During
transport, cross sections for each material are calculated using statistical linear-linear interpolation
between bounding temperature. Suppose cross sections are available at temperatures 𝑇1 , 𝑇2 , ..., 𝑇𝑛
and a material is assigned a temperature 𝑇 where 𝑇𝑖 < 𝑇 < 𝑇𝑖+1 . Statistical interpolation is
applied as follows: a uniformly-distributed random number of the unit interval, 𝜉, is sampled. If
𝜉 < (𝑇 −𝑇𝑖 )/(𝑇𝑖+1 −𝑇𝑖 ), then cross sections at temperature 𝑇𝑖+1 are used. Otherwise, cross sections
at 𝑇𝑖 are used. This procedure is applied for pointwise cross sections in the resolved resonance range,
unresolved resonance probability tables, and 𝑆(𝛼, 𝛽) thermal scattering tables.
Multipole
Resolved resonance cross sections are calculated on-the-fly using techniques/data described in Win-
dowed Multipole Representation. Cross section data is loaded for a single temperature and is used in
the unresolved resonance and fast energy ranges.
3.3. Cross Section Representations 61

3.3.2 Multi-Group Data
The data governing the interaction of particles with various nuclei or materials are represented using a multi-group
library format specific to the OpenMC code. The format is described in the MGXS Library Specification. The data
itself can be prepared via traditional paths or directly from a continuous-energy OpenMC calculation by use of the
Python API as is shown in an example notebook. This multi-group library consists of meta-data (such as the energy
group structure) and multiple xsdata objects which contains the required microscopic or macroscopic multi-group data.
At a minimum, the library must contain the absorption cross section (𝜎𝑎,𝑔 ) and a scattering matrix. If the problem is
an eigenvalue problem then all fissionable materials must also contain either a fission production matrix cross section
(𝜈𝜎𝑓,𝑔→𝑔′ ), or both the fission spectrum data (𝜒𝑔′ ) and a fission production cross section (𝜈𝜎𝑓,𝑔 ), or, . The library must
also contain the fission cross section (𝜎𝑓,𝑔 ) or the fission energy release cross section (𝜅𝜎𝑓,𝑔 ) if the associated tallies
are required by the model using the library.
After a scattering collision, the outgoing particle experiences a change in both energy and angle. The probability of
a particle resulting in a given outgoing energy group (g’) given a certain incoming energy group (g) is provided by
the scattering matrix data. The angular information can be expressed either via Legendre expansion of the particle’s
change-in-angle (𝜇), a tabular representation of the probability distribution function of 𝜇, or a histogram representation
of the same PDF. The formats used to represent these are described in the MGXS Library Specification.
Unlike the continuous-energy mode, the multi-group mode does not explicitly track particles produced from scattering
multiplication (i.e., (𝑛, 𝑥𝑛)) reactions. These are instead accounted for by adjusting the weight of the particle after
the collision such that the correct total weight is maintained. The weight adjustment factor is optionally provided by
the multiplicity data which is required to be provided in the form of a group-wise matrix. This data is provided as a
group-wise matrix since the probability of producing multiple particles in a scattering reaction depends on both the
incoming energy, g, and the sampled outgoing energy, g’. This data represents the average number of particles emitted
from a scattering reaction, given a scattering reaction has occurred:
𝜈𝑠𝑐𝑎𝑡𝑡𝑒𝑟 𝜎𝑠,𝑔→𝑔′
𝑚𝑢𝑙𝑡𝑖𝑝𝑙𝑖𝑐𝑖𝑡𝑦𝑔→𝑔′ =
𝜎𝑠,𝑔→𝑔′
If this scattering multiplication information is not provided in the library then no weight adjustment will be performed.
This is equivalent to neglecting any additional particles produced in scattering multiplication reactions. However, this
assumption will result in a loss of accuracy since the total particle population would not be conserved. This reduction
in accuracy due to the loss in particle conservation can be mitigated by reducing the absorption cross section as needed
to maintain particle conservation. This adjustment can be done when generating the library, or by OpenMC. To have
OpenMC perform the adjustment, the total cross section (𝜎𝑡,𝑔 ) must be provided. With this information, OpenMC will
then adjust the absorption cross section as follows:
∑︁
𝜎𝑎,𝑔 = 𝜎𝑡,𝑔 − 𝜈𝑠𝑐𝑎𝑡𝑡𝑒𝑟 𝜎𝑠,𝑔→𝑔′
𝑔′
The above method is the same as is usually done with most deterministic solvers. Note that this method is less accurate
than using the scattering multiplication weight adjustment since simply reducing the absorption cross section does not
include any information about the outgoing energy of the particles produced in these reactions.
All of the data discussed in this section can be provided to the code independent of the particle’s direction of motion (i.e.,
isotropic), or the data can be provided as a tabular distribution of the polar and azimuthal particle direction angles. The
isotropic representation is the most commonly used, however inaccuracies are to be expected especially near material
interfaces where a material has a very large cross sections relative to the other material (as can be expected in the
resonance range). The angular representation can be used to minimize this error.
Finally, the above options for representing the physics do not have to be consistent across the problem. The number of
groups and the structure, however, does have to be consistent across the data sets. That is to say that each microscopic
or macroscopic data set does not have to apply the same scattering expansion, treatment of multiplicity or angular
representation of the cross sections. This allows flexibility for the model to use highly anisotropic scattering information
in the water while the fuel can be simulated with linear or even isotropic scattering.

3.4 Random Number Generation
In order to sample probability distributions, one must be able to produce random numbers. The standard technique to do
this is to generate numbers on the interval [0, 1) from a deterministic sequence that has properties that make it appear to
be random, e.g. being uniformly distributed and not exhibiting correlation between successive terms. Since the numbers
produced this way are not truly “random” in a strict sense, they are typically referred to as pseudorandom numbers, and
the techniques used to generate them are pseudorandom number generators (PRNGs). Numbers sampled on the unit
interval can then be transformed for the purpose of sampling other continuous or discrete probability distributions.
3.4.1 Linear Congruential Generators
There are a great number of algorithms for generating random numbers. One of the simplest and commonly used
algorithms is called a linear congruential generator. We start with a random number seed 𝜉0 and a sequence of random
numbers can then be generated using the following recurrence relation:
𝜉𝑖+1 = 𝑔𝜉𝑖 + 𝑐 mod 𝑀 (3.4.1)
where 𝑔, 𝑐, and 𝑀 are constants. The choice of these constants will have a profound effect on the quality and perfor-
mance of the generator, so they should not be chosen arbitrarily. As Donald Knuth stated in his seminal work The Art
of Computer Programming, “random numbers should not be generated with a method chosen at random. Some theory
should be used.” Typically, 𝑀 is chosen to be a power of two as this enables 𝑥 mod 𝑀 to be performed using the
bitwise AND operator with a bit mask. The constants for the linear congruential generator used by default in OpenMC
are 𝑔 = 2806196910506780709, 𝑐 = 1, and 𝑀 = 263 (see L’Ecuyer).
Skip-ahead Capability
One of the important capabilities for a random number generator is to be able to skip ahead in the sequence of random
numbers. Without this capability, it would be very difficult to maintain reproducibility in a parallel calculation. If we
want to skip ahead 𝑁 random numbers and 𝑁 is large, the cost of sampling 𝑁 random numbers to get to that position
may be prohibitively expensive. Fortunately, algorithms have been developed that allow us to skip ahead in 𝑂(log2 𝑁 )
operations instead of 𝑂(𝑁 ). One algorithm to do so is described in a paper by Brown. This algorithm relies on the
following relationship:
𝑔𝑘 − 1
𝜉𝑖+𝑘 = 𝑔 𝑘 𝜉𝑖 + 𝑐 mod 𝑀 (3.4.2)
𝑔−1
Note that equation (3.4.2) has the same general form as equation (3.4.1), so the idea is to determine the new multiplica-
tive and additive constants in 𝑂(log2 𝑁 ) operations.
3.5 Neutron Physics
There are limited differences between physics treatments used in the continuous-energy and multi-group modes. If
distinctions are necessary, each of the following sections will provide an explanation of the differences. Otherwise,
replacing any references of the particle’s energy (E) with references to the particle’s energy group (g) will suffice.
3.4. Random Number Generation 63

3.5.1 Sampling Distance to Next Collision
As a particle travels through a homogeneous material, the probability distribution function for the distance to its next
collision ℓ is
𝑝(ℓ)𝑑ℓ = Σ𝑡 𝑒−Σ𝑡 ℓ 𝑑ℓ (3.5.1)
where Σ𝑡 is the total macroscopic cross section of the material. Equation (3.5.1) tells us that the further the distance is
to the next collision, the less likely the particle will travel that distance. In order to sample the probability distribution
function, we first need to convert it to a cumulative distribution function
∫︁ ℓ ∫︁ ℓ
′
′ ′
𝑑ℓ 𝑝(ℓ ) = 𝑑ℓ′ Σ𝑡 𝑒−Σ𝑡 ℓ = 1 − 𝑒−Σ𝑡 ℓ . (3.5.2)
0 0
By setting the cumulative distribution function equal to 𝜉, a random number on the unit interval, and solving for the
distance ℓ, we obtain a formula for sampling the distance to next collision:
ln(1 − 𝜉)
ℓ=− . (3.5.3)
Σ𝑡
Since 𝜉 is uniformly distributed on [0, 1), this implies that 1 − 𝜉 is also uniformly distributed on [0, 1) as well. Thus,
the formula usually used to calculate the distance to next collision is
ln 𝜉
ℓ=− (3.5.4)
Σ𝑡
3.5.2 (𝑛, 𝛾) and Other Disappearance Reactions
All absorption reactions other than fission do not produce any secondary neutrons. As a result, these are the easiest
type of reactions to handle. When a collision occurs, the first step is to sample a nuclide within a material. Once
the nuclide has been sampled, then a specific reaction for that nuclide is sampled. Since the total absorption cross
section is pre-calculated at the beginning of a simulation, the first step in sampling a reaction is to determine whether
a “disappearance” reaction occurs where no secondary neutrons are produced. This is done by sampling a random
number 𝜉 on the interval [0, 1) and checking whether
𝜉𝜎𝑡 (𝐸) < 𝜎𝑎 (𝐸) − 𝜎𝑓 (𝐸) (3.5.5)
where 𝜎𝑡 is the total cross section, 𝜎𝑎 is the absorption cross section (this includes fission), and 𝜎𝑓 is the total fission
cross section. If this condition is met, then the neutron is killed and we proceed to simulate the next neutron from the
source bank.
Note that photons arising from (𝑛, 𝛾) and other neutron reactions are not produced in a microscopically correct manner.
Instead, photons are sampled probabilistically at each neutron collision, regardless of what reaction actually takes place.
This is described in more detail in Photon Production.
3.5.3 Elastic Scattering
Note that the multi-group mode makes no distinction between elastic or inelastic scattering reactions. The specific
multi-group scattering implementation is discussed in the Multi-Group Scattering section.
Elastic scattering refers to the process by which a neutron scatters off a nucleus and does not leave it in an excited. It
is referred to as “elastic” because in the center-of-mass system, the neutron does not actually lose energy. However, in
lab coordinates, the neutron does indeed lose energy. Elastic scattering can be treated exactly in a Monte Carlo code
thanks to its simplicity.

Let us discuss how OpenMC handles two-body elastic scattering kinematics. The first step is to determine whether
the target nucleus has any associated motion. Above a certain energy threshold (400 kT by default), all scattering is
assumed to take place with the target at rest. Below this threshold though, we must account for the thermal motion of
the target nucleus. Methods to sample the velocity of the target nucleus are described later in section Effect of Thermal
Motion on Cross Sections. For the time being, let us assume that we have sampled the target velocity v𝑡 . The velocity
of the center-of-mass system is calculated as
v𝑛 + 𝐴v𝑡
v𝑐𝑚 = (3.5.6)
𝐴+1
where v𝑛 is the velocity of the neutron and 𝐴 is the atomic mass of the target nucleus measured in neutron masses
(commonly referred to as the atomic weight ratio). With the velocity of the center-of-mass calculated, we can then
determine the neutron’s velocity in the center-of-mass system:
V𝑛 = v𝑛 − v𝑐𝑚 (3.5.7)
where we have used uppercase V to denote the center-of-mass system. The direction of the neutron in the center-of-
mass system is
V𝑛
Ω𝑛 = . (3.5.8)
||V𝑛 ||
At low energies, elastic scattering will be isotropic in the center-of-mass system, but for higher energies, there may be
p-wave and higher order scattering that leads to anisotropic scattering. Thus, in general, we need to sample a cosine of
the scattering angle which we will refer to as 𝜇. For elastic scattering, the secondary angle distribution is always given
in the center-of-mass system and is sampled according to the procedure outlined in Sampling Angular Distributions.
After the cosine of the angle of scattering has been sampled, we need to determine the neutron’s new direction Ω′𝑛
in the center-of-mass system. This is done with the procedure in Transforming a Particle’s Coordinates. The new
direction is multiplied by the speed of the neutron in the center-of-mass system to obtain the new velocity vector in the
center-of-mass:
V𝑛′ = ||V𝑛 ||Ω′𝑛 . (3.5.9)
Finally, we transform the velocity in the center-of-mass system back to lab coordinates:
v𝑛′ = V𝑛′ + v𝑐𝑚 (3.5.10)
In OpenMC, the angle and energy of the neutron are stored rather than the velocity vector itself, so the post-collision
angle and energy can be inferred from the post-collision velocity of the neutron in the lab system.
For tallies that require the scattering cosine, it is important to store the scattering cosine in the lab system. If we know
the scattering cosine in the center-of-mass, the scattering cosine in the lab system can be calculated as
1 + 𝐴𝜇
𝜇𝑙𝑎𝑏 = √︀
2
. (3.5.11)
𝐴 + 2𝐴𝜇 + 1
However, equation (3.5.11) is only valid if the target was at rest. When the target nucleus does have thermal motion,
the cosine of the scattering angle can be determined by simply taking the dot product of the neutron’s initial and final
direction in the lab system.
3.5.4 Inelastic Scattering
The major algorithms for inelastic scattering were described in previous sections. First, a scattering cosine is sampled
using the algorithms in Sampling Angular Distributions. Then an outgoing energy is sampled using the algorithms in
3.5. Neutron Physics 65

Sampling Energy Distributions. If the outgoing energy and scattering cosine were given in the center-of-mass system,
they are transformed to laboratory coordinates using the algorithm described in Transforming a Particle’s Coordinates.
Finally, the direction of the particle is changed also using the procedure in Transforming a Particle’s Coordinates.
Although inelastic scattering leaves the target nucleus in an excited state, no secondary photons from nuclear de-
excitation are tracked in OpenMC.
3.5.5 (𝑛, 𝑥𝑛) Reactions
These types of reactions are just treated as inelastic scattering and as such are subject to the same procedure as described
in Inelastic Scattering. For reactions with integral multiplicity, e.g., (𝑛, 2𝑛), an appropriate number of secondary
neutrons are created. For reactions that have a multiplicity given as a function of the incoming neutron energy (which
occasionally occurs for MT=5), the weight of the outgoing neutron is multiplied by the multiplicity.
3.5.6 Multi-Group Scattering
In multi-group mode, a scattering collision requires that the outgoing energy group of the simulated particle be selected
from a probability distribution, the change-in-angle selected from a probability distribution according to the outgoing
energy group, and finally the particle’s weight adjusted again according to the outgoing energy group.
The first step in selecting an outgoing energy group for a particle in a given incoming energy group is to select a random
number (𝜉) between 0 and 1. This number is then compared to the cumulative distribution function produced from the
outgoing group (g’) data for the given incoming group (g):
ℎ
∑︁
𝐶𝐷𝐹 = Σ𝑠,𝑔→𝑔′
𝑔 ′ =1
If the scattering data is represented as a Legendre expansion, then the value of Σ𝑠,𝑔→𝑔′ above is the 0th order for the
given group transfer. If the data is provided as tabular or histogram data, then Σ𝑠,𝑔→𝑔′ is the sum of all bins of data for
a given g and g’ pair.
Now that the outgoing energy is known the change-in-angle, 𝜇 can be determined. If the data is provided as a Legendre
expansion, this is done by rejection sampling of the probability distribution represented by the Legendre series. For
efficiency, the selected values of the PDF (𝑓 (𝜇)) are chosen to be between 0 and the maximum value of 𝑓 (𝜇) in
the domain of -1 to 1. Note that this sampling scheme automatically forces negative values of the 𝑓 (𝜇) probability
distribution function to be treated as zero probabilities.
If the angular data is instead provided as a tabular representation, then the value of 𝜇 is selected as described in the
Tabular Angular Distribution section with a linear-linear interpolation scheme.
If the angular data is provided as a histogram representation, then the value of 𝜇 is selected in a similar fashion to
that described for the selection of the outgoing energy (since the energy group representation is simply a histogram
representation) except the CDF is composed of the angular bins and not the energy groups. However, since we are
interested in a specific value of 𝜇 instead of a group, then an angle is selected from a uniform distribution within from
the chosen angular bin.
The final step in the scattering treatment is to adjust the weight of the neutron to account for any production of neutrons
due to (𝑛, 𝑥𝑛) reactions. This data is obtained from the multiplicity data provided in the multi-group cross section
library for the material of interest. The scaled value will default to 1.0 if no value is provided in the library.

3.5.7 Fission
While fission is normally considered an absorption reaction, as far as it concerns a Monte Carlo simulation it actually
bears more similarities to inelastic scattering since fission results in secondary neutrons in the exit channel. Other
absorption reactions like (𝑛, 𝛾) or (𝑛, 𝛼), on the contrary, produce no neutrons. There are a few other idiosyncrasies
in treating fission. In an eigenvalue calculation, secondary neutrons from fission are only “banked” for use in the next
generation rather than being tracked as secondary neutrons from elastic and inelastic scattering would be. On top of
this, fission is sometimes broken into first-chance fission, second-chance fission, etc. The nuclear data file either lists
the partial fission reactions with secondary energy distributions for each one, or a total fission reaction with a single
secondary energy distribution.
When a fission reaction is sampled in OpenMC (either total fission or, if data exists, first- or second-chance fission), the
following algorithm is used to create and store fission sites for the following generation. First, the average number of
prompt and delayed neutrons must be determined to decide whether the secondary neutrons will be prompt or delayed.
This is important because delayed neutrons have a markedly different spectrum from prompt neutrons, one that has a
lower average energy of emission. The total number of neutrons emitted 𝜈𝑡 is given as a function of incident energy in
the ENDF format. Two representations exist for 𝜈𝑡 . The first is a polynomial of order 𝑁 with coefficients 𝑐0 , 𝑐1 , . . . , 𝑐𝑁 .
If 𝜈𝑡 has this format, we can evaluate it at incoming energy 𝐸 by using the equation
𝑁
∑︁
𝜈𝑡 (𝐸) = 𝑐𝑖 𝐸 𝑖 . (3.5.12)
𝑖=0
The other representation is just a tabulated function with a specified interpolation law. The number of prompt neutrons
released per fission event 𝜈𝑝 is also given as a function of incident energy and can be specified in a polynomial or
tabular format. The number of delayed neutrons released per fission event 𝜈𝑑 can only be specified in a tabular format.
In practice, we only need to determine 𝑛𝑢𝑡 and 𝑛𝑢𝑑 . Once these have been determined, we can calculated the delayed
neutron fraction
𝜈𝑑
𝛽= . (3.5.13)
𝜈𝑡
We then need to determine how many total neutrons should be emitted from fission. If no survival biasing is being
used, then the number of neutrons emitted is
𝑤𝜈𝑡
𝜈= (3.5.14)
𝑘𝑒𝑓 𝑓
where 𝑤 is the statistical weight and 𝑘𝑒𝑓 𝑓 is the effective multiplication factor from the previous generation. The number
of neutrons produced is biased in this manner so that the expected number of fission neutrons produced is the number
of source particles that we started with in the generation. Since 𝜈 is not an integer, we use the following procedure to
obtain an integral number of fission neutrons to produce. If 𝜉 > 𝜈 − ⌊𝜈⌋, then we produce ⌊𝜈⌋ neutrons. Otherwise, we
produce ⌊𝜈⌋ + 1 neutrons. Then, for each fission site produced, we sample the outgoing angle and energy according to
the algorithms given in Sampling Angular Distributions and Sampling Energy Distributions respectively. If the neutron
is to be born delayed, then there is an extra step of sampling a delayed neutron precursor group since they each have an
associated secondary energy distribution.
The sampled outgoing angle and energy of fission neutrons along with the position of the collision site are stored in an
array called the fission bank. In a subsequent generation, these fission bank sites are used as starting source sites.
The above description is similar for the multi-group mode except the data are provided as group-wise data instead of
in a continuous-energy format. In this case, the outgoing energy of the fission neutrons are represented as histograms
by way of either the nu-fission matrix or chi vector.

3.5.8 Secondary Angle-Energy Distributions
Note that this section is specific to continuous-energy mode since the multi-group scattering process has already been
described including the secondary energy and angle sampling.
For a reaction with secondary products, it is necessary to determine the outgoing angle and energy of the products. For
any reaction other than elastic and level inelastic scattering, the outgoing energy must be determined based on tabulated
or parameterized data. The ENDF-6 Format specifies a variety of ways that the secondary energy distribution can be
represented. ENDF File 5 contains uncorrelated energy distribution whereas ENDF File 6 contains correlated energy-
angle distributions. The ACE format specifies its own representations based loosely on the formats given in ENDF-6.
OpenMC’s HDF5 nuclear data files use a combination of ENDF and ACE distributions; in this section, we will describe
how the outgoing angle and energy of secondary particles are sampled.
One of the subtleties in the nuclear data format is the fact that a single reaction product can have multiple angle-energy
distributions. This is mainly useful for reactions with multiple products of the same type in the exit channel such as
(𝑛, 2𝑛) or (𝑛, 3𝑛). In these types of reactions, each neutron is emitted corresponding to a different excitation level of
the compound nucleus, and thus in general the neutrons will originate from different energy distributions. If multiple
angle-energy distributions are present, they are assigned incoming-energy-dependent probabilities that can then be used
to randomly select one.
Once a distribution has been selected, the procedure for determining the outgoing angle and energy will depend on the
type of the distribution.
Uncorrelated Angle-Energy Distributions
The first set of distributions we will look at are uncorrelated angle-energy distributions, where angle and energy are
specified separately. For these distributions, OpenMC first samples the angular distribution as described Sampling
Angular Distributions and then samples an energy as described in Sampling Energy Distributions.
Sampling Angular Distributions
For elastic scattering, it is only necessary to specific a secondary angle distribution since the outgoing energy can be
determined analytically. Other reactions may also have separate secondary angle and secondary energy distributions
that are uncorrelated. In these cases, the secondary angle distribution is represented as either
• An isotropic angular distribution,
• A tabular distribution.
Isotropic Angular Distribution
In the first case, no data is stored in the nuclear data file, and the cosine of the scattering angle is simply calculated as
𝜇 = 2𝜉 − 1 (3.5.15)
where 𝜇 is the cosine of the scattering angle and 𝜉 is a random number sampled uniformly on [0, 1).

Tabular Angular Distribution
In this case, we have a table of cosines and their corresponding values for a probability distribution function and
cumulative distribution function. For each incoming neutron energy 𝐸𝑖 , let us call 𝑝𝑖,𝑗 the j-th value in the probability
distribution function and 𝑐𝑖,𝑗 the j-th value in the cumulative distribution function. We first find the interpolation factor
on the incoming energy grid:
𝐸 − 𝐸𝑖
𝑓= (3.5.16)
𝐸𝑖+1 − 𝐸𝑖
where 𝐸 is the incoming energy of the particle. Then, statistical interpolation is performed to choose between using
the cosines and distribution functions corresponding to energy 𝐸𝑖 and 𝐸𝑖+1 . Let ℓ be the chosen table where ℓ = 𝑖
if 𝜉1 > 𝑓 and ℓ = 𝑖 + 1 otherwise, where 𝜉1 is a random number. Another random number 𝜉2 is used to sample a
scattering cosine bin 𝑗 using the cumulative distribution function:
𝑐ℓ,𝑗 < 𝜉2 < 𝑐ℓ,𝑗+1 (3.5.17)
The final scattering cosine will depend on whether histogram or linear-linear interpolation is used. In general, we can
write the cumulative distribution function as
∫︁ 𝜇
𝑐(𝜇) = 𝑝(𝜇′ )𝑑𝜇′ (3.5.18)
−1
where 𝑐(𝜇) is the cumulative distribution function and 𝑝(𝜇) is the probability distribution function. Since we know
that 𝑐(𝜇ℓ,𝑗 ) = 𝑐ℓ,𝑗 , this implies that for 𝜇 > 𝜇ℓ,𝑗 ,
∫︁ 𝜇
𝑐(𝜇) = 𝑐ℓ,𝑗 + 𝑝(𝜇′ )𝑑𝜇′ (3.5.19)
𝜇ℓ,𝑗
For histogram interpolation, we have that 𝑝(𝜇′ ) = 𝑝ℓ,𝑗 for 𝜇ℓ,𝑗 ≤ 𝜇′ < 𝜇ℓ,𝑗+1 . Thus, after integrating (3.5.19) we
have that
𝑐(𝜇) = 𝑐ℓ,𝑗 + (𝜇 − 𝜇ℓ,𝑗 )𝑝ℓ,𝑗 = 𝜉2 (3.5.20)
Solving for the scattering cosine, we obtain the final form for histogram interpolation:
𝜉2 − 𝑐ℓ,𝑗
𝜇 = 𝜇ℓ,𝑗 + . (3.5.21)
𝑝ℓ,𝑗
For linear-linear interpolation, we represent the function 𝑝(𝜇′ ) as a first-order polynomial in 𝜇′ . If we interpolate
between successive values on the probability distribution function, we know that
𝑝ℓ,𝑗+1 − 𝑝ℓ,𝑗 ′
𝑝(𝜇′ ) − 𝑝ℓ,𝑗 = (𝜇 − 𝜇ℓ,𝑗 ) (3.5.22)
𝜇ℓ,𝑗+1 − 𝜇ℓ,𝑗
Solving for 𝑝(𝜇′ ) in equation (3.5.22) and inserting it into equation (3.5.19), we obtain
∫︁ 𝜇 [︂ ]︂
𝑐(𝜇) = 𝑐ℓ,𝑗 + (𝜇 − 𝜇ℓ,𝑗 ) + 𝑝ℓ,𝑗 𝑑𝜇′ . (3.5.23)
𝜇ℓ,𝑗 𝜇ℓ,𝑗+1 − 𝜇ℓ,𝑗
Let us now make a change of variables using

𝜂= (𝜇 − 𝜇ℓ,𝑗 ) + 𝑝ℓ,𝑗 . (3.5.24)
Equation (3.5.23) then becomes
∫︁ 𝑚(𝜇−𝜇ℓ,𝑗 )+𝑝ℓ,𝑗
1
𝑐(𝜇) = 𝑐ℓ,𝑗 + 𝜂 𝑑𝜂 (3.5.25)
𝑚 𝑝ℓ,𝑗

where we have used

𝑝ℓ,𝑗+1 − 𝑝ℓ,𝑗
𝑚= . (3.5.26)
Integrating equation (3.5.25), we have

1 (︁ )︁
𝑐(𝜇) = 𝑐ℓ,𝑗 +
2
[𝑚(𝜇 − 𝜇ℓ,𝑗 ) + 𝑝ℓ,𝑗 ] − 𝑝2ℓ,𝑗 = 𝜉2 (3.5.27)
2𝑚
Solving for 𝜇, we have the final form for the scattering cosine using linear-linear interpolation:
1 (︁√︁ 2 )︁
𝜇 = 𝜇ℓ,𝑗 + 𝑝ℓ,𝑗 + 2𝑚(𝜉2 − 𝑐ℓ,𝑗 ) − 𝑝ℓ,𝑗 (3.5.28)
𝑚
Sampling Energy Distributions
Inelastic Level Scattering
It can be shown (see Foderaro) that in inelastic level scattering, the outgoing energy of the neutron 𝐸 ′ can be related
to the Q-value of the reaction and the incoming energy:
(︂ )︂2 (︂ )︂
𝐴 𝐴+1
𝐸′ = 𝐸− 𝑄 (3.5.29)
𝐴+1 𝐴
where 𝐴 is the mass of the target nucleus measured in neutron masses.
Continuous Tabular Distribution
In a continuous tabular distribution, a tabulated energy distribution is provided for each of a set of incoming energies.
While the representation itself is simple, the complexity lies in how one interpolates between incident as well as out-
going energies on such a table. If one performs simple interpolation between tables for neighboring incident energies,
it is possible that the resulting energies would violate laws governing the kinematics, i.e., the outgoing energy may be
outside the range of available energy in the reaction.
To avoid this situation, the accepted practice is to use a process known as scaled interpolation. First, we find the tabulated
incident energies which bound the actual incoming energy of the particle, i.e., find 𝑖 such that 𝐸𝑖 < 𝐸 < 𝐸𝑖+1 and
calculate the interpolation factor 𝑓 via (3.5.16). Then, we interpolate between the minimum and maximum energies of
the outgoing energy distributions corresponding to 𝐸𝑖 and 𝐸𝑖+1 :
𝐸𝑚𝑖𝑛 = 𝐸𝑖,1 + 𝑓 (𝐸𝑖+1,1 − 𝐸𝑖,1 )

(3.5.30)
𝐸𝑚𝑎𝑥 = 𝐸𝑖,𝑀 + 𝑓 (𝐸𝑖+1,𝑀 − 𝐸𝑖,𝑀 )
where 𝐸𝑚𝑖𝑛 and 𝐸𝑚𝑎𝑥 are the minimum and maximum outgoing energies of a scaled distribution, 𝐸𝑖,𝑗 is the j-th
outgoing energy corresponding to the incoming energy 𝐸𝑖 , and 𝑀 is the number of outgoing energy bins.
Next, statistical interpolation is performed to choose between using the outgoing energy distributions corresponding
to energy 𝐸𝑖 and 𝐸𝑖+1 . Let ℓ be the chosen table where ℓ = 𝑖 if 𝜉1 > 𝑓 and ℓ = 𝑖 + 1 otherwise, and 𝜉1 is a random
number. For each incoming neutron energy 𝐸𝑖 , let us call 𝑝𝑖,𝑗 the j-th value in the probability distribution function, 𝑐𝑖,𝑗
the j-th value in the cumulative distribution function, and 𝐸𝑖,𝑗 the j-th outgoing energy. We then sample an outgoing
energy bin 𝑗 using the cumulative distribution function:
𝑐ℓ,𝑗 < 𝜉2 < 𝑐ℓ,𝑗+1 (3.5.31)
where 𝜉2 is a random number sampled uniformly on [0, 1). At this point, we need to interpolate between the successive
values on the outgoing energy distribution using either histogram or linear-linear interpolation. The formulas for these

can be derived along the same lines as those found in Tabular Angular Distribution. For histogram interpolation, the
interpolated outgoing energy on the ℓ-th distribution is
ˆ = 𝐸ℓ,𝑗 + 𝜉2 − 𝑐ℓ,𝑗 .
𝐸 (3.5.32)
𝑝ℓ,𝑗
If linear-linear interpolation is to be used, the outgoing energy on the ℓ-th distribution is

(︃√︃ )︃
𝐸 ℓ,𝑗+1 − 𝐸ℓ,𝑗 𝑝ℓ,𝑗+1 − 𝑝ℓ,𝑗
ˆ = 𝐸ℓ,𝑗 +
𝐸 2
𝑝ℓ,𝑗 + 2 (𝜉2 − 𝑐ℓ,𝑗 ) − 𝑝ℓ,𝑗 . (3.5.33)
𝑝ℓ,𝑗+1 − 𝑝ℓ,𝑗 𝐸ℓ,𝑗+1 − 𝐸ℓ,𝑗
Since this outgoing energy may violate reaction kinematics, we then scale it to minimum and maximum energies
calculated in equation (3.5.30) to get the final outgoing energy:
𝐸ˆ − 𝐸ℓ,1
𝐸 ′ = 𝐸𝑚𝑖𝑛 + (𝐸𝑚𝑎𝑥 − 𝐸𝑚𝑖𝑛 ) (3.5.34)
𝐸ℓ,𝑀 − 𝐸ℓ,1
where 𝐸𝑚𝑖𝑛 and 𝐸𝑚𝑎𝑥 are defined the same as in equation (3.5.30).
Maxwell Fission Spectrum
One representation of the secondary energies for neutrons from fission is the so-called Maxwell spectrum. A probability
distribution for the Maxwell spectrum can be written in the form
′
𝑝(𝐸 ′ )𝑑𝐸 ′ = 𝑐𝐸 ′1/2 𝑒−𝐸 /𝑇 (𝐸)
𝑑𝐸 ′ (3.5.35)
where 𝐸 is the incoming energy of the neutron and 𝑇 is the so-called nuclear temperature, which is a function of the
incoming energy of the neutron. The ENDF format contains a list of nuclear temperatures versus incoming energies.
The nuclear temperature is interpolated between neighboring incoming energies using a specified interpolation law.
Once the temperature 𝑇 is determined, we then calculate a candidate outgoing energy based on rule C64 in the Monte
Carlo Sampler:
[︂ (︂ )︂]︂
𝜋𝜉3
′
𝐸 = −𝑇 log(𝜉1 ) + log(𝜉2 ) cos 2
(3.5.36)
2
where 𝜉1 , 𝜉2 , 𝜉3 are random numbers sampled on the unit interval. The outgoing energy is only accepted if
0 ≤ 𝐸′ ≤ 𝐸 − 𝑈 (3.5.37)
where 𝑈 is called the restriction energy and is specified in the ENDF data. If the outgoing energy is rejected, it is
resampled using equation (3.5.36).
Evaporation Spectrum
Evaporation spectra are primarily used in compound nucleus processes where a secondary particle can “evaporate”
from the compound nucleus if it has sufficient energy. The probability distribution for an evaporation spectrum can be
written in the form
′
𝑝(𝐸 ′ )𝑑𝐸 ′ = 𝑐𝐸 ′ 𝑒−𝐸 /𝑇 (𝐸)
𝑑𝐸 ′ (3.5.38)
where 𝐸 is the incoming energy of the neutron and 𝑇 is the nuclear temperature, which is a function of the incoming
energy of the neutron. The ENDF format contains a list of nuclear temperatures versus incoming energies. The nu-
clear temperature is interpolated between neighboring incoming energies using a specified interpolation law. Once the

temperature 𝑇 is determined, we then calculate a candidate outgoing energy based on the algorithm given in LA-UR-
14-27694:
𝐸 ′ = −𝑇 log((1 − 𝑔𝜉1 )(1 − 𝑔𝜉2 )) (3.5.39)
where 𝑔 = 1 − 𝑒−𝑤 , 𝑤 = (𝐸 − 𝑈 )/𝑇 , 𝑈 is the restriction energy, and 𝜉1 , 𝜉2 are random numbers sampled on the
unit interval. The outgoing energy is only accepted according to the restriction energy as in equation (3.5.37). This
algorithm has a much higher rejection efficiency than the standard technique, i.e. rule C45 in the Monte Carlo Sampler.
Energy-Dependent Watt Spectrum
The probability distribution for a Watt fission spectrum can be written in the form
′
(3.5.40)
√︀
𝑝(𝐸 ′ )𝑑𝐸 ′ = 𝑐𝑒−𝐸 /𝑎(𝐸)
sinh 𝑏(𝐸) 𝐸 ′ 𝑑𝐸 ′
where 𝑎 and 𝑏 are parameters for the distribution and are given as tabulated functions of the incoming energy of the
neutron. These two parameters are interpolated on the incoming energy grid using a specified interpolation law. Once
the parameters have been determined, we sample a Maxwellian spectrum with nuclear temperature 𝑎 using the algorithm
described in Maxwell Fission Spectrum to get an energy 𝑊 . Then, the outgoing energy is calculated as
𝑎2 𝑏 √
𝐸′ = 𝑊 + + (2𝜉 − 1) 𝑎2 𝑏𝑊 (3.5.41)
4
where 𝜉 is a random number sampled on the interval [0, 1). The outgoing energy is only accepted according to a
specified restriction energy 𝑈 as defined in equation (3.5.37).
A derivation of the algorithm described here can be found in a paper by Romano.
Product Angle-Energy Distributions
If the secondary distribution for a product was given in file 6 in ENDF, the angle and energy are correlated with one
another and cannot be sampled separately. Several representations exist in ENDF/ACE for correlated angle-energy
distributions.
Kalbach-Mann Correlated Scattering
This law is very similar to the uncorrelated continuous tabular energy distribution except now the outgoing angle of the
neutron is correlated to the outgoing energy and is not sampled from a separate distribution. For each incident neutron
energy 𝐸𝑖 tabulated, there is an array of precompound factors 𝑅𝑖,𝑗 and angular distribution slopes 𝐴𝑖,𝑗 corresponding
to each outgoing energy bin 𝑗 in addition to the outgoing energies and distribution functions as in Continuous Tabular
Distribution.
The calculation of the outgoing energy of the neutron proceeds exactly the same as in the algorithm described in Con-
tinuous Tabular Distribution. In that algorithm, we found an interpolation factor 𝑓 , statistically sampled an incoming
energy bin ℓ, and sampled an outgoing energy bin 𝑗 based on the tabulated cumulative distribution function. Once the
outgoing energy has been determined with equation (3.5.34), we then need to calculate the outgoing angle based on
the tabulated Kalbach-Mann parameters. These parameters themselves are subject to either histogram or linear-linear
interpolation on the outgoing energy grid. For histogram interpolation, the parameters are
𝑅 = 𝑅ℓ,𝑗
(3.5.42)
𝐴 = 𝐴ℓ,𝑗 .

If linear-linear interpolation is specified, the parameters are
𝐸ˆ − 𝐸ℓ,𝑗
𝑅 = 𝑅ℓ,𝑗 + (𝑅ℓ,𝑗+1 − 𝑅ℓ,𝑗 )
𝐸ℓ,𝑗+1 − 𝐸ℓ,𝑗
(3.5.43)
𝐸ˆ − 𝐸ℓ,𝑗
𝐴 = 𝐴ℓ,𝑗 + (𝐴ℓ,𝑗+1 − 𝐴ℓ,𝑗 )
𝐸ℓ,𝑗+1 − 𝐸ℓ,𝑗
where 𝐸ˆ is defined in equation (3.5.33). With the parameters determined, the probability distribution function for the
cosine of the scattering angle is
𝐴
𝑝(𝜇)𝑑𝜇 = [cosh(𝐴𝜇) + 𝑅 sinh(𝐴𝜇)] 𝑑𝜇. (3.5.44)
2 sinh(𝐴)
The rules for sampling this probability distribution function can be derived based on rules C39 and C40 in the Monte
Carlo Sampler. First, we sample two random numbers 𝜉3 , 𝜉4 on the unit interval. If 𝜉3 > 𝑅 then the outgoing angle is
1 (︁ √︀ )︁
𝜇 = ln 𝑇 + 𝑇 2 + 1 (3.5.45)
𝐴
where 𝑇 = (2𝜉4 − 1) sinh(𝐴). If 𝜉3 ≤ 𝑅, then the outgoing angle is
1 (︀ 𝐴
ln 𝜉4 𝑒 + (1 − 𝜉4 )𝑒−𝐴 . (3.5.46)
)︀
𝜇=
𝐴
Correlated Energy and Angle Distribution
This distribution is very similar to a Kalbach-Mann distribution in the sense that the outgoing angle of the neutron is
correlated to the outgoing energy and is not sampled from a separate distribution. In this case though, rather than being
determined from an analytical distribution function, the cosine of the scattering angle is determined from a tabulated
distribution. For each incident energy 𝑖 and outgoing energy 𝑗, there is a tabulated angular distribution.
The calculation of the outgoing energy of the neutron proceeds exactly the same as in the algorithm described in Con-
tinuous Tabular Distribution. In that algorithm, we found an interpolation factor 𝑓 , statistically sampled an incoming
energy bin ℓ, and sampled an outgoing energy bin 𝑗 based on the tabulated cumulative distribution function. Once the
outgoing energy has been determined with equation (3.5.34), we then need to decide which angular distribution to use.
If histogram interpolation was used on the outgoing energy bins, then we use the angular distribution corresponding
to incoming energy bin ℓ and outgoing energy bin 𝑗. If linear-linear interpolation was used on the outgoing energy
bins, then we use the whichever angular distribution was closer to the sampled value of the cumulative distribution
function for the outgoing energy. The actual algorithm used to sample the chosen tabular angular distribution has been
previously described in Tabular Angular Distribution.
N-Body Phase Space Distribution
Reactions in which there are more than two products of similar masses are sometimes best treated by using what’s
known as an N-body phase distribution. This distribution has the following probability density function for outgoing
energy and angle of the 𝑖-th particle in the center-of-mass system:
√
𝑝𝑖 (𝜇, 𝐸 ′ )𝑑𝐸 ′ 𝑑𝜇 = 𝐶𝑛 𝐸 ′ (𝐸𝑖𝑚𝑎𝑥 − 𝐸 ′ )(3𝑛/2)−4 𝑑𝐸 ′ 𝑑𝜇 (3.5.47)
where 𝑛 is the number of outgoing particles, 𝐶𝑛 is a normalization constant, 𝐸𝑖𝑚𝑎𝑥 is the maximum center-of-mass
energy for particle 𝑖, and 𝐸 ′ is the outgoing energy. We see in equation (3.5.47) that the angle is simply isotropic in the
center-of-mass system. The algorithm for sampling the outgoing energy is based on algorithms R28, C45, and C64 in
the Monte Carlo Sampler. First we calculate the maximum energy in the center-of-mass using the following equation:
(︂ )︂
𝐴𝑝 − 1 𝐴
𝐸𝑖𝑚𝑎𝑥 = 𝐸+𝑄 (3.5.48)
𝐴𝑝 𝐴+1

where 𝐴𝑝 is the total mass of the outgoing particles in neutron masses, 𝐴 is the mass of the original target nucleus in
neutron masses, and 𝑄 is the Q-value of the reaction. Next we sample a value 𝑥 from a Maxwell distribution with a
nuclear temperature of one using the algorithm outlined in Maxwell Fission Spectrum. We then need to determine a
value 𝑦 that will depend on how many outgoing particles there are. For 𝑛 = 3, we simply sample another Maxwell
distribution with unity nuclear temperature. For 𝑛 = 4, we use the equation
𝑦 = − ln(𝜉1 𝜉2 𝜉3 ) (3.5.49)
where 𝜉𝑖 are random numbers sampled on the interval [0, 1). For 𝑛 = 5, we use the equation
(︁ 𝜋 )︁
𝑦 = − ln(𝜉1 𝜉2 𝜉3 𝜉4 ) − ln(𝜉5 ) cos2 𝜉6 (3.5.50)
2
After 𝑥 and 𝑦 have been determined, the outgoing energy is then calculated as
𝑥
𝐸′ = 𝐸 𝑚𝑎𝑥 (3.5.51)
𝑥+𝑦 𝑖
There are two important notes to make regarding the N-body phase space distribution. First, the documentation (and
code) for MCNP5-1.60 has a mistake in the algorithm for 𝑛 = 4. That being said, there are no existing nuclear data
evaluations which use an N-body phase space distribution with 𝑛 = 4, so the error would not affect any calculations.
In the ENDF/B-VII.1 nuclear data evaluation, only one reaction uses an N-body phase space distribution at all, the
(𝑛, 2𝑛) reaction with H-2.
3.5.9 Transforming a Particle’s Coordinates
Since all the multi-group data exists in the laboratory frame of reference, this section does not apply to the multi-group
mode.
Once the cosine of the scattering angle 𝜇 has been sampled either from a angle distribution or a correlated angle-
energy distribution, we are still left with the task of transforming the particle’s coordinates. If the outgoing energy
and scattering cosine were given in the center-of-mass system, then we first need to transform these into the laboratory
system. The relationship between the outgoing energy in center-of-mass and laboratory is
√︀
𝐸 + 2𝜇𝑐𝑚 (𝐴 + 1) 𝐸𝐸𝑐𝑚 ′
′ ′
𝐸 = 𝐸𝑐𝑚 + . (3.5.52)
(𝐴 + 1)2
where 𝐸𝑐𝑚
′
is the outgoing energy in the center-of-mass system, 𝜇𝑐𝑚 is the scattering cosine in the center-of-mass
system, 𝐸 ′ is the outgoing energy in the laboratory system, and 𝐸 is the incident neutron energy. The relationship
between the scattering cosine in center-of-mass and laboratory is
√︂ √︂
′
𝐸𝑐𝑚 1 𝐸
𝜇 = 𝜇𝑐𝑚 + (3.5.53)
𝐸 ′ 𝐴 + 1 𝐸′
where 𝜇 is the scattering cosine in the laboratory system. The scattering cosine still only tells us the cosine of the
angle between the original direction of the particle and the new direction of the particle. If we express the pre-collision
direction of the particle as Ω = (𝑢, 𝑣, 𝑤) and the post-collision direction of the particle as Ω′ = (𝑢′ , 𝑣 ′ , 𝑤′ ), it is
possible to relate the pre- and post-collision components. We first need to uniformly sample an azimuthal angle 𝜑 in
[0, 2𝜋). After the azimuthal angle has been sampled, the post-collision direction is calculated as
√︀
′ 1 − 𝜇2 (𝑢𝑤 cos 𝜑 − 𝑣 sin 𝜑)
𝑢 = 𝜇𝑢 + √
1 − 𝑤2
(3.5.54)
√︀
′ 1 − 𝜇2 (𝑣𝑤 cos 𝜑 + 𝑢 sin 𝜑)
𝑣 = 𝜇𝑣 + √
1 − 𝑤2
√︀ √︀
𝑤′ = 𝜇𝑤 − 1 − 𝜇2 1 − 𝑤2 cos 𝜑.

3.5.10 Effect of Thermal Motion on Cross Sections
Since all the multi-group data should be generated with thermal scattering treatments already, this section does not
apply to the multi-group mode.
When a neutron scatters off of a nucleus, it may often be assumed that the target nucleus is at rest. However, the
target nucleus will have motion associated with its thermal vibration, even at absolute zero (This is due to the zero-
point energy arising from quantum mechanical considerations). Thus, the velocity of the neutron relative to the target
nucleus is in general not the same as the velocity of the neutron entering the collision.
The effect of the thermal motion on the interaction probability can be written as
∫︁
𝑣𝑛 𝜎
¯ (𝑣𝑛 , 𝑇 ) = 𝑑v𝑇 𝑣𝑟 𝜎(𝑣𝑟 )𝑀 (v𝑇 ) (3.5.55)
where 𝑣𝑛 is the magnitude of the velocity of the neutron, 𝜎 ¯ is an effective cross section, 𝑇 is the temperature of the target
material, v𝑇 is the velocity of the target nucleus, 𝑣𝑟 = ||v𝑛 −v𝑇 || is the magnitude of the relative velocity, 𝜎 is the cross
section at 0 K, and 𝑀 (v𝑇 ) is the probability distribution for the target nucleus velocity at temperature 𝑇 (a Maxwellian).
In a Monte Carlo code, one must account for the effect of the thermal motion on both the integrated cross section as well
as secondary angle and energy distributions. For integrated cross sections, it is possible to calculate thermally-averaged
cross sections by applying a kernel Doppler broadening algorithm to data at 0 K (or some temperature lower than the
desired temperature). The most ubiquitous algorithm for this purpose is the SIGMA1 method developed by Red Cullen
and subsequently refined by others. This method is used in the NJOY and PREPRO data processing codes.
The effect of thermal motion on secondary angle and energy distributions can be accounted for on-the-fly in a Monte
Carlo simulation. We must first qualify where it is actually used however. All threshold reactions are treated as being
independent of temperature, and therefore they are not Doppler broadened in NJOY and no special procedure is used
to adjust the secondary angle and energy distributions. The only non-threshold reactions with secondary neutrons are
elastic scattering and fission. For fission, it is assumed that the neutrons are emitted isotropically (this is not strictly true,
but is nevertheless a good approximation). This leaves only elastic scattering that needs a special thermal treatment for
secondary distributions.
Fortunately, it is possible to directly sample the velocity of the target nuclide and then use it directly in the kinematic
calculations. However, this calculation is a bit more nuanced than it might seem at first glance. One might be tempted to
simply sample a Maxwellian distribution for the velocity of the target nuclide. Careful inspection of equation (3.5.55)
however tells us that target velocities that produce relative velocities which correspond to high cross sections will have
a greater contribution to the effective reaction rate. This is most important when the velocity of the incoming neutron
is close to a resonance. For example, if the neutron’s velocity corresponds to a trough in a resonance elastic scattering
cross section, a very small target velocity can cause the relative velocity to correspond to the peak of the resonance,
thus making a disproportionate contribution to the reaction rate. The conclusion is that if we are to sample a target
velocity in the Monte Carlo code, it must be done in such a way that preserves the thermally-averaged reaction rate as
per equation (3.5.55).
The method by which most Monte Carlo codes sample the target velocity for use in elastic scattering kinematics is
outlined in detail by [Gelbard]. The derivation here largely follows that of Gelbard. Let us first write the reaction rate
as a function of the velocity of the target nucleus:
𝑅(v𝑇 ) = ||v𝑛 − v𝑇 ||𝜎(||v𝑛 − v𝑇 ||)𝑀 (v𝑇 ) (3.5.56)
where 𝑅 is the reaction rate. Note that this is just the right-hand side of equation (3.5.55). Based on the discussion
above, we want to construct a probability distribution function for sampling the target velocity to preserve the reaction
rate – this is different from the overall probability distribution function for the target velocity, 𝑀 (v𝑇 ). This probability
distribution function can be found by integrating equation (3.5.56) to obtain a normalization factor:
𝑅(v𝑇 )𝑑v𝑇
𝑝(v𝑇 )𝑑v𝑇 = ∫︀ (3.5.57)
𝑑v𝑇 𝑅(v𝑇 )
Let us call the normalization factor in the denominator of equation (3.5.57) 𝐶.

Constant Cross Section Model
It is often assumed that 𝜎(𝑣𝑟 ) is constant over the range of relative velocities of interest. This is a good assumption
for almost all cases since the elastic scattering cross section varies slowly with velocity for light nuclei, and for heavy
nuclei where large variations can occur due to resonance scattering, the moderating effect is rather small. Nonetheless,
this assumption may cause incorrect answers in systems with low-lying resonances that can cause a significant amount
of up-scatter that would be ignored by this assumption (e.g. U-238 in commercial light-water reactors). We will revisit
this assumption later in Energy-Dependent Cross Section Model. For now, continuing with the assumption, we write
𝜎(𝑣𝑟 ) = 𝜎𝑠 which simplifies (3.5.57) to
𝜎𝑠
𝑝(v𝑇 )𝑑v𝑇 = ||v𝑛 − v𝑇 ||𝑀 (v𝑇 )𝑑v𝑇 (3.5.58)
𝐶
The Maxwellian distribution in velocity is
−𝑚||v𝑇2 ||
(︁ 𝑚 )︁3/2 (︂ )︂
𝑀 (v𝑇 ) = exp (3.5.59)
2𝜋𝑘𝑇 2𝑘𝑇
where 𝑚 is the mass of the target nucleus and 𝑘 is Boltzmann’s constant. Notice here that the term in the exponential
is dependent only on the speed of the target, not on the actual direction. Thus, we can change the Maxwellian into a
distribution for speed rather than velocity. The differential element of velocity is
𝑑v𝑇 = 𝑣𝑇2 𝑑𝑣𝑇 𝑑𝜇𝑑𝜑 (3.5.60)
Let us define the Maxwellian distribution in speed as

1 2𝜋
√︂ (︂ )︂
−𝑚𝑣𝑇
∫︁ ∫︁
2 (︁ 𝑚 )︁3 2
𝑀 (𝑣𝑇 )𝑑𝑣𝑇 = 𝑑𝜇 𝑑𝜑 𝑑𝑣𝑇 𝑣𝑇2 𝑀 (v𝑇 ) = 𝑣𝑇 exp 𝑑𝑣𝑇 . (3.5.61)
−1 0 𝜋 𝑘𝑇 2𝑘𝑇
To simplify things a bit, we’ll define a parameter
√︂
𝑚
𝛽= . (3.5.62)
2𝑘𝑇
Substituting equation (3.5.62) into equation (3.5.61), we obtain
4
𝑀 (𝑣𝑇 )𝑑𝑣𝑇 = √ 𝛽 3 𝑣𝑇2 exp −𝛽 2 𝑣𝑇2 𝑑𝑣𝑇 . (3.5.63)
(︀ )︀
𝜋
Now, changing variables in equation (3.5.58) by using the result from equation (3.5.61), our new probability distribution
function is
4𝜎𝑠
𝑝(𝑣𝑇 , 𝜇)𝑑𝑣𝑇 𝑑𝜇 = √ ′ ||v𝑛 − v𝑇 ||𝛽 3 𝑣𝑇2 exp −𝛽 2 𝑣𝑇2 𝑑𝑣𝑇 𝑑𝜇 (3.5.64)
(︀ )︀
𝜋𝐶
Again, the Maxwellian distribution for the speed of the target nucleus has no dependence on the angle between the
neutron and target velocity vectors. Thus, only the term ||v𝑛 − v𝑇 || imposes any constraint on the allowed angle. Our
last task is to take that term and write it in terms of magnitudes of the velocity vectors and the angle rather than the
vectors themselves. We can establish this relation based on the law of cosines which tells us that
2𝑣𝑛 𝑣𝑇 𝜇 = 𝑣𝑛2 + 𝑣𝑇2 − 𝑣𝑟2 . (3.5.65)
Thus, we can infer that

√︁
||v𝑛 − v𝑇 || = ||v𝑟 || = 𝑣𝑟 = 𝑣𝑛2 + 𝑣𝑇2 − 2𝑣𝑛 𝑣𝑇 𝜇. (3.5.66)
Inserting equation (3.5.66) into (3.5.64), we obtain

4𝜎𝑠
√︁
𝑝(𝑣𝑇 , 𝜇)𝑑𝑣𝑇 𝑑𝜇 = √ ′ 𝑣𝑛2 + 𝑣𝑇2 − 2𝑣𝑛 𝑣𝑇 𝜇𝛽 3 𝑣𝑇2 exp −𝛽 2 𝑣𝑇2 𝑑𝑣𝑇 𝑑𝜇 (3.5.67)
(︀ )︀
𝜋𝐶

This expression is still quite formidable and does not lend itself to any natural sampling scheme. We can divide this
probability distribution into two parts as such:
𝑝(𝑣𝑇 , 𝜇) = 𝑓1 (𝑣𝑇 , 𝜇)𝑓2 (𝑣𝑇 )

√︀
4𝜎𝑠 𝑣𝑛2 + 𝑣𝑇2 − 2𝑣𝑛 𝑣𝑇 𝜇
𝑓1 (𝑣𝑇 , 𝜇) = √ ′ (3.5.68)
𝜋𝐶 𝑣𝑛 + 𝑣𝑇
𝑓2 (𝑣𝑇 ) = (𝑣𝑛 + 𝑣𝑇 )𝛽 𝑣𝑇 exp −𝛽 2 𝑣𝑇2 .
3 2
(︀ )︀
In general, any probability distribution function of the form 𝑝(𝑥) = 𝑓1 (𝑥)𝑓2 (𝑥) with 𝑓1 (𝑥) bounded can be sampled
by sampling 𝑥′ from the distribution
𝑓2 (𝑥)𝑑𝑥
𝑞(𝑥)𝑑𝑥 = ∫︀ (3.5.69)
𝑓2 (𝑥)𝑑𝑥
and accepting it with probability
𝑓1 (𝑥′ )
𝑝𝑎𝑐𝑐𝑒𝑝𝑡 = (3.5.70)
max 𝑓1 (𝑥)
The reason for dividing and multiplying the terms by 𝑣𝑛 + 𝑣𝑇 is to ensure that the first term is bounded. In general,
||v𝑛 − v𝑇 || can take on arbitrarily large values, but if we divide it by its maximum value 𝑣𝑛 + 𝑣𝑇 , then it ensures that
the function will be bounded. We now must come up with a sampling scheme for equation (3.5.69). To determine
𝑞(𝑣𝑇 ), we need to integrate 𝑓2 in equation (3.5.68). Doing so we find that
∫︁ ∞
1 (︀√
𝑑𝑣𝑇 (𝑣𝑛 + 𝑣𝑇 )𝛽 3 𝑣𝑇2 exp −𝛽 2 𝑣𝑇2 = (3.5.71)
(︀ )︀ )︀
𝜋𝛽𝑣𝑛 + 2 .
0 4𝛽
Thus, we need to sample the probability distribution function
4𝛽 2 𝑣𝑛 𝑣𝑇2 4𝛽 4 𝑣𝑇3
(︂ )︂
𝑒𝑥𝑝 −𝛽 2 𝑣𝑇2 . (3.5.72)
(︀ )︀
𝑞(𝑣𝑇 )𝑑𝑣𝑇 = √ +√
𝜋𝛽𝑣𝑛 + 2 𝜋𝛽𝑣𝑛 + 2
Now, let us do a change of variables with the following definitions
𝑥 = 𝛽𝑣𝑇
(3.5.73)
𝑦 = 𝛽𝑣𝑛 .
Substituting equation (3.5.73) into equation (3.5.72) along with 𝑑𝑥 = 𝛽𝑑𝑣𝑇 and doing some crafty rearranging of
terms yields
[︂(︂ √ )︂ (︂ )︂ ]︂
𝜋𝑦 4 2 2 2
𝑞(𝑥)𝑑𝑥 = √ √ 𝑥2 𝑒−𝑥 + √ 2𝑥3 𝑒−𝑥 𝑑𝑥. (3.5.74)
𝜋𝑦 + 2 𝜋 𝜋𝑦 + 2
It’s important to make note of the following two facts. First, the terms outside the parentheses are properly normalized
probability distribution functions that can be sampled directly. Secondly, the terms inside the parentheses are always
less than unity. Thus, the sampling scheme for 𝑞(𝑥) is as follows. We sample a random number 𝜉1 on the interval [0, 1)
and if
2
𝜉1 < √ (3.5.75)
𝜋𝑦 + 2
2
then we sample the probability distribution 2𝑥3 𝑒−𝑥 for 𝑥 using rule C49 in the Monte Carlo Sampler which we can
then use to determine the speed of the target nucleus 𝑣𝑇 from equation (3.5.73). Otherwise, we sample the probability
2
distribution √4𝜋 𝑥2 𝑒−𝑥 for 𝑥 using rule C61 in the Monte Carlo Sampler.
With a target speed sampled, we must then decide whether to accept it based on the probability in equation (3.5.70).
The cosine can be sampled isotropically as 𝜇 = 2𝜉2 − 1 where 𝜉2 is a random number on the unit interval. Since the

√
maximum value of 𝑓1 (𝑣𝑇 , 𝜇) is 4𝜎𝑠 / 𝜋𝐶 ′ , we then sample another random number 𝜉3 and accept the sampled target
speed and cosine if
√︀
𝑣𝑛2 + 𝑣𝑇2 − 2𝑣𝑛 𝑣𝑇 𝜇
𝜉3 < . (3.5.76)
𝑣𝑛 + 𝑣𝑇
If is not accepted, then we repeat the process and resample a target speed and cosine until a combination is found that
satisfies equation (3.5.76).
Energy-Dependent Cross Section Model
As was noted earlier, assuming that the elastic scattering cross section is constant in (3.5.56) is not strictly correct,
especially when low-lying resonances are present in the cross sections for heavy nuclides. To correctly account for
energy dependence of the scattering cross section entails performing another rejection step. The most common method
is to sample 𝜇 and 𝑣𝑇 as in the constant cross section approximation and then perform a rejection on the ratio of the 0
K elastic scattering cross section at the relative velocity to the maximum 0 K elastic scattering cross section over the
range of velocities considered:
𝜎𝑠 (𝑣𝑟 )
𝑝𝑑𝑏𝑟𝑐 = (3.5.77)
𝜎𝑠,𝑚𝑎𝑥
where it should be noted that the maximum is taken over the range [𝑣𝑛 −4/𝛽, 4𝑛 +4𝛽]. This method is known as Doppler
broadening rejection correction (DBRC) and was first introduced by Becker et al.. OpenMC has an implementation of
DBRC as well as an accelerated sampling method that samples the relative velocity directly.
3.5.11 S(𝛼, 𝛽, 𝑇 ) Tables
Note that S(𝛼, 𝛽, 𝑇 ) tables are only applicable to continuous-energy transport.

For neutrons with thermal energies, generally less than 4 eV, the kinematics of scattering can be affected by chemical
binding and crystalline effects of the target molecule. If these effects are not accounted for in a simulation, the reported
results may be highly inaccurate. There is no general analytic treatment for the scattering kinematics at low energies,
and thus when nuclear data is processed for use in a Monte Carlo code, special tables are created that give cross sections
and secondary angle/energy distributions for thermal scattering that account for thermal binding effects. These tables
are mainly used for moderating materials such as light or heavy water, graphite, hydrogen in ZrH, beryllium, etc.
The theory behind S(𝛼, 𝛽, 𝑇 ) is rooted in quantum mechanics and is quite complex. Those interested in first princi-
ples derivations for formulae relating to S(𝛼, 𝛽, 𝑇 ) tables should be referred to the excellent books by [Williams] and
[Squires]. For our purposes here, we will focus only on the use of already processed data as it appears in the ACE
format.
Each S(𝛼, 𝛽, 𝑇 ) table can contain the following:
• Thermal inelastic scattering cross section;
• Thermal elastic scattering cross section;
• Correlated energy-angle distributions for thermal inelastic and elastic scattering.
Note that when we refer to “inelastic” and “elastic” scattering now, we are actually using these terms with respect
to the scattering system. Thermal inelastic scattering means that the scattering system is left in an excited state; no
particular nucleus is left in an excited state as would be the case for inelastic level scattering. In a crystalline material,
the excitation of the scattering could correspond to the production of phonons. In a molecule, it could correspond to
the excitation of rotational or vibrational modes.
Both thermal elastic and thermal inelastic scattering are generally divided into incoherent and coherent parts. Coherent
elastic scattering refers to scattering in crystalline solids like graphite or beryllium. These cross sections are charac-
terized by the presence of Bragg edges that relate to the crystal structure of the scattering material. Incoherent elastic

scattering refers to scattering in hydrogenous solids such as polyethylene. As it occurs in ACE data, thermal inelastic
scattering includes both coherent and incoherent effects and is dominant for most other materials including hydrogen
in water.
Calculating Integrated Cross Sections
The first aspect of using S(𝛼, 𝛽, 𝑇 ) tables is calculating cross sections to replace the data that would normally appear
on the incident neutron data, which do not account for thermal binding effects. For incoherent inelastic scattering, the
cross section is stored as a linearly interpolable function on a specified energy grid. For coherent elastic data, the cross
section can be expressed as
1 ∑︁
𝜎(𝐸) = 𝑠𝑖 (3.5.78)
𝐸
𝐸𝑖 <𝐸
where 𝐸𝑖 are the energies of the Bragg edges and 𝑠𝑖 are related to crystallographic structure factors. Since the functional
form of the cross section is just 1/E and the proportionality constant changes only at Bragg edges, the proportionality
constants are stored and then the cross section can be calculated analytically based on equation (3.5.78). For incoherent
elastic data, the cross section can be expressed as
(︃ ′
)︃
𝜎𝑏 1 − 𝑒−4𝐸𝑊
𝜎(𝐸) = (3.5.79)
2 2𝐸𝑊 ′
where 𝜎𝑏 is the characteristic bound cross section and 𝑊 ′ is the Debye-Waller integral divided by the atomic mass.
Outgoing Angle for Coherent Elastic Scattering
Another aspect of using S(𝛼, 𝛽, 𝑇 ) tables is determining the outgoing energy and angle of the neutron after scatter-
ing. For incoherent and coherent elastic scattering, the energy of the neutron does not actually change, but the angle
does change. For coherent elastic scattering, the angle will depend on which Bragg edge scattered the neutron. The
probability that edge 𝑖 will scatter then neutron is given by
𝑠
∑︀ 𝑖 . (3.5.80)
𝑗 𝑠𝑗
After a Bragg edge has been sampled, the cosine of the angle of scattering is given analytically by
2𝐸𝑖
𝜇=1− (3.5.81)
𝐸
where 𝐸𝑖 is the energy of the Bragg edge that scattered the neutron.
Outgoing Angle for Incoherent Elastic Scattering
For incoherent elastic scattering, OpenMC has two methods for calculating the cosine of the angle of scattering. The
first method uses the Debye-Waller integral, 𝑊 ′ , and the characteristic bound cross section as given directly in an
ENDF-6 formatted file. In this case, the cosine of the angle of scattering can be sampled by inverting equation 7.4 from
the ENDF-6 Format:
1
log 1 + 𝜉 𝑒2𝑐 − 1 − 1 (3.5.82)
(︀ (︀ )︀)︀
𝜇=
𝑐
where 𝜉 is a random number sampled on unit interval and 𝑐 = 2𝐸𝑊 ′ . In the second method, the probability distribution
for the cosine of the angle of scattering is represented as a series of equally-likely discrete cosines 𝜇𝑖,𝑗 for each incoming

energy 𝐸𝑖 on the thermal elastic energy grid. First the outgoing angle bin 𝑗 is sampled. Then, if the incoming energy
of the neutron satisfies 𝐸𝑖 < 𝐸 < 𝐸𝑖+1 the cosine of the angle of scattering is
𝜇′ = 𝜇𝑖,𝑗 + 𝑓 (𝜇𝑖+1,𝑗 − 𝜇𝑖,𝑗 ) (3.5.83)
where the interpolation factor is defined as
𝐸 − 𝐸𝑖
𝑓= . (3.5.84)
𝐸𝑖+1 − 𝐸𝑖
To better represent the true, continuous nature of the cosine distribution, the sampled value of 𝑚𝑢′ is then “smeared”
based on the neighboring values. First, values of 𝜇 are calculated for outgoing angle bins 𝑗 − 1 and 𝑗 + 1:
𝜇left = 𝜇𝑖,𝑗−1 + 𝑓 (𝜇𝑖+1,𝑗−1 − 𝜇𝑖,𝑗−1 )

(3.5.85)
𝜇right = 𝜇𝑖,𝑗+1 + 𝑓 (𝜇𝑖+1,𝑗+1 − 𝜇𝑖,𝑗+1 ).
Then, a final cosine is calculated as:

(︂ )︂
1
𝜇 = 𝜇′ + min(𝜇 − 𝜇left , 𝜇 + 𝜇right ) · 𝜉 − (3.5.86)
2
where 𝜉 is again a random number sampled on the unit interval. Care must be taken to ensure that 𝜇 does not fall
outside the interval [−1, 1].
Outgoing Energy and Angle for Inelastic Scattering
Each S(𝛼, 𝛽, 𝑇 ) table provides a correlated angle-energy secondary distribution for neutron thermal inelastic scattering.
There are three representations used in the ACE thermal scattering data: equiprobable discrete outgoing energies, non-
uniform yet still discrete outgoing energies, and continuous outgoing energies with corresponding probability and
cumulative distribution functions provided in tabular format. These three representations all represent the angular
distribution in a common format, using a series of discrete equiprobable outgoing cosines.
Equi-Probable Outgoing Energies
If the thermal data was processed with 𝑖𝑤𝑡 = 1 in NJOY, then the outgoing energy spectra is represented in the ACE
data as a set of discrete and equiprobable outgoing energies. The procedure to determine the outgoing energy and angle
is as such. First, the interpolation factor is determined from equation (3.5.84). Then, an outgoing energy bin is sampled
from a uniform distribution and then interpolated between values corresponding to neighboring incoming energies:
𝐸 = 𝐸𝑖,𝑗 + 𝑓 (𝐸𝑖+1,𝑗 − 𝐸𝑖,𝑗 ) (3.5.87)
where 𝐸𝑖,𝑗 is the j-th outgoing energy corresponding to the i-th incoming energy. For each combination of incoming
and outgoing energies, there is a series equiprobable outgoing cosines. An outgoing cosine bin is sampled uniformly
and then the final cosine is interpolated on the incoming energy grid:
𝜇 = 𝜇𝑖,𝑗,𝑘 + 𝑓 (𝜇𝑖+1,𝑗,𝑘 − 𝜇𝑖,𝑗,𝑘 ) (3.5.88)
where 𝜇𝑖,𝑗,𝑘 is the k-th outgoing cosine corresponding to the j-th outgoing energy and the i-th incoming energy.

Skewed Equi-Probable Outgoing Energies
If the thermal data was processed with 𝑖𝑤𝑡 = 0 in NJOY, then the outgoing energy spectra is represented in the ACE
data according to the following: the first and last outgoing energies have a relative probability of 1, the second and
second-to-last energies have a relative probability of 4, and all other energies have a relative probability of 10. The
procedure to determine the outgoing energy and angle is similar to the method discussed above, except that the sampled
probability distribution is now skewed accordingly.
Continuous Outgoing Energies
If the thermal data was processed with 𝑖𝑤𝑡 = 2 in NJOY, then the outgoing energy spectra is represented by a continuous
outgoing energy spectra in tabular form with linear-linear interpolation. The sampling of the outgoing energy portion
of this format is very similar to Correlated Energy and Angle Distribution, but the sampling of the correlated angle
is performed as it was in the other two representations discussed in this sub-section. In the Law 61 algorithm, we
found an interpolation factor 𝑓 , statistically sampled an incoming energy bin ℓ, and sampled an outgoing energy bin 𝑗
based on the tabulated cumulative distribution function. Once the outgoing energy has been determined with equation
(3.5.34), we then need to decide which angular distribution data to use. Like the linear-linear interpolation case in Law
61, the angular distribution closest to the sampled value of the cumulative distribution function for the outgoing energy
is utilized. The actual algorithm utilized to sample the outgoing angle is shown in equation (3.5.88). As in the case of
incoherent elastic scattering with discrete cosine bins, the sampled cosine is smeared over neighboring angle bins to
better approximate a continuous distribution.
3.5.12 Unresolved Resonance Region Probability Tables
Note that unresolved resonance treatments are only applicable to continuous-energy transport.
In the unresolved resonance energy range, resonances may be so closely spaced that it is not possible for experimental
measurements to resolve all resonances. To properly account for self-shielding in this energy range, OpenMC uses
the probability table method. For most thermal reactors, the use of probability tables will not significantly affect
problem results. However, for some fast reactors and other problems with an appreciable flux spectrum in the unresolved
resonance range, not using probability tables may lead to incorrect results.
Probability tables in the ACE format are generated from the UNRESR module in NJOY following the method of Levitt.
A similar method employed for the RACER and MC21 Monte Carlo codes is described in a paper by Sutton and Brown.
For the discussion here, we will focus only on use of the probability table table as it appears in the ACE format.
Each probability table for a nuclide contains the following information at a number of incoming energies within the
unresolved resonance range:
• Cumulative probabilities for cross section bands;
• Total cross section (or factor) in each band;
• Elastic scattering cross section (or factor) in each band;
• Fission cross section (or factor) in each band;
• (𝑛, 𝛾) cross section (or factor) in each band; and
• Neutron heating number (or factor) in each band.
It should be noted that unresolved resonance probability tables affect only integrated cross sections and no extra data
need be given for secondary angle/energy distributions. Secondary distributions for elastic and inelastic scattering
would be specified whether or not probability tables were present.
The procedure for determining cross sections in the unresolved range using probability tables is as follows. First, the
bounding incoming energies are determined, i.e. find 𝑖 such that 𝐸𝑖 < 𝐸 < 𝐸𝑖+1 . We then sample a cross section band

𝑗 using the cumulative probabilities for table 𝑖. This allows us to then calculate the elastic, fission, and capture cross
sections from the probability tables interpolating between neighboring incoming energies. If interpolation is specified,
then the cross sections are calculated as
𝜎 = 𝜎𝑖,𝑗 + 𝑓 (𝜎𝑖+1,𝑗 − 𝜎𝑖, 𝑗) (3.5.89)
where 𝜎𝑖,𝑗 is the j-th band cross section corresponding to the i-th incoming neutron energy and 𝑓 is the interpolation
factor defined in the same manner as (3.5.84). If logarithmic interpolation is specified, the cross sections are calculated
as
(︂ )︂
𝜎𝑖+1,𝑗
𝜎 = exp log 𝜎𝑖,𝑗 + 𝑓 log (3.5.90)
𝜎𝑖,𝑗
where the interpolation factor is now defined as
𝐸
log 𝐸𝑖
𝑓= 𝐸𝑖+1
. (3.5.91)
log 𝐸𝑖
A flag is also present in the probability table that specifies whether an inelastic cross section should be calculated. If so,
this is done from a normal reaction cross section (either MT=51 or a special MT). Finally, if the cross sections defined
are above are specified to be factors and not true cross sections, they are multiplied by the underlying smooth cross
section in the unresolved range to get the actual cross sections. Lastly, the total cross section is calculated as the sum
of the elastic, fission, capture, and inelastic cross sections.
3.5.13 Variance Reduction Techniques
Survival Biasing
In problems with highly absorbing materials, a large fraction of neutrons may be killed through absorption reactions,
thus leading to tallies with very few scoring events. To remedy this situation, an algorithm known as survival biasing
or implicit absorption (or sometimes implicit capture, even though this is a misnomer) is commonly used.
In survival biasing, absorption reactions are prohibited from occurring and instead, at every collision, the weight of
neutron is reduced by probability of absorption occurring, i.e.
(︂ )︂
𝜎𝑎 (𝐸)
′
𝑤 =𝑤 1− (3.5.92)
𝜎𝑡 (𝐸)
where 𝑤′ is the weight of the neutron after adjustment and 𝑤 is the weight of the neutron before adjustment. A few
other things need to be handled differently if survival biasing is turned on. Although fission reactions never actually
occur with survival biasing, we still need to create fission sites to serve as source sites for the next generation in the
method of successive generations. The algorithm for sampling fission sites is the same as that described in Fission.
The only difference is in equation (3.5.14). We now need to produce
𝑤 𝜈𝑡 𝜎𝑓 (𝐸)
𝜈= (3.5.93)
𝑘 𝜎𝑡 (𝐸)
fission sites, where 𝑤 is the weight of the neutron before being adjusted. One should note this is just the expected
number of neutrons produced per collision rather than the expected number of neutrons produced given that fission has
already occurred.
Additionally, since survival biasing can reduce the weight of the neutron to very low values, it is always used in con-
junction with a weight cutoff and Russian rouletting. Two user adjustable parameters 𝑤𝑐 and 𝑤𝑠 are given which are the
weight below which neutrons should undergo Russian roulette and the weight should they survive Russian roulette. The
algorithm for Russian rouletting is as follows. After a collision if 𝑤 < 𝑤𝑐 , then the neutron is killed with probability
1 − 𝑤/𝑤𝑠 . If it survives, the weight is set equal to 𝑤𝑠 . One can confirm that the average weight following Russian
roulette is simply 𝑤, so the game can be considered “fair”. By default, the cutoff weight in OpenMC is 𝑤𝑐 = 0.25 and
the survival weight is 𝑤𝑠 = 1.0. These parameters vary from one Monte Carlo code to another.

Weight Windows
In fixed source problems, it can often be difficult to obtain sufficiently low variance on tallies in regions that are far
from the source. The weight window method was developed to increase the population of particles in important spatial
regions and energy ranges by controlling particle weights. Each spatial region and particle energy range is assigned
upper and lower weight bounds, 𝑤𝑢 and 𝑤ℓ , respectively. When a particle is in a given spatial region / energy range, its
weight, 𝑤, is compared to the lower and upper bounds. If the weight of the particle is above the upper weight bound,
the particle is split into 𝑁 particles, where
𝑁 = min(𝑁𝑚𝑎𝑥 , ⌈𝑤/𝑤𝑢 ⌉) (3.5.94)
and 𝑁𝑚𝑎𝑥 is a user-defined maximum number of splits. To ensure a fair game, each of the 𝑁 particles is assigned a
weight 𝑤/𝑁 . If the weight is below 𝑤ℓ , it is Russian rouletted as described in Survival Biasing with a survival weight
𝑤𝑠 that is set equal to
𝑤𝑠 = min(𝑁𝑚𝑎𝑥 𝑤, 𝑓𝑠 𝑤𝑙 ) (3.5.95)
where 𝑓𝑠 is a user-defined survival weight ratio greater than one.

On top of the standard weight window method described above, OpenMC implements two additional checks intended
to mitigate problems with long histories. First, particles with a weight that falls below some very small cutoff (defaults
to 10−38 ) are killed with no Russian rouletting. Additionally, the total number of splits experienced by a particle is
tracked and if it reaches some maximum value, it is prohibited from splitting further.
At present, OpenMC allows weight windows to be defined on all supported mesh types.
3.6 Photon Physics
Photons, being neutral particles, behave much in the same manner as neutrons, traveling in straight lines and experienc-
ing occasional collisions that change their energy and direction. Photons undergo four basic interactions as they pass
through matter: coherent (Rayleigh) scattering, incoherent (Compton) scattering, photoelectric effect, and pair/triplet
production. Photons with energy in the MeV range may also undergo photonuclear reactions with an atomic nucleus.
In addition to these primary interaction mechanisms, all processes other than coherent scattering can result in the ex-
citation/ionization of atoms. The de-excitation of these atoms can result in the emission of electrons and photons.
Electrons themselves also can produce photons by means of bremsstrahlung radiation.
3.6.1 Photon Interactions
Coherent (Rayleigh) Scattering
The elastic scattering of a photon off a free charged particle is known as Thomson scattering. The differential cross
section is independent of the energy of the incident photon. For scattering off a free electron, the differential cross
section is
𝑑𝜎
= 𝜋𝑟𝑒2 (1 + 𝜇2 ) (3.6.1)
𝑑𝜇
where 𝜇 is the cosine of the scattering angle and 𝑟𝑒 is the classical electron radius. Thomson scattering can generally
occur when the photon energy is much less than the rest mass energy of the particle.
In practice, most elastic scattering of photons off electrons happens not with free electrons but those bound in atoms.
This process is known as Rayleigh scattering. The radiation scattered off of individual bound electrons combines
coherently, and thus Rayleigh scattering is also known as coherent scattering. Even though conceptually we think of
3.6. Photon Physics 83

the photon interacting with a single electron, because the wave functions combine constructively it is really as though
the photon is interacting with the entire atom.
The differential cross section for Rayleigh scattering is given by
𝑑𝜎(𝐸, 𝐸 ′ , 𝜇) 2
= 𝜋𝑟𝑒2 (1 + 𝜇2 ) |𝐹 (𝑥, 𝑍) + 𝐹 ′ + 𝑖𝐹 ′′ |
𝑑𝜇 (3.6.2)
= 𝜋𝑟𝑒2 (1 + 𝜇2 ) (𝐹 (𝑥, 𝑍) + 𝐹 ′ (𝐸))2 + 𝐹 ′′ (𝐸)2
[︀ ]︀
where 𝐹 (𝑥, 𝑍) is a form factor as a function of the momentum transfer 𝑥 and the atomic number 𝑍 and the term
𝐹 ′ + 𝑖𝐹 ′′ accounts for anomalous scattering which can occur near absorption edges. In a Monte Carlo simulation,
when coherent scattering occurs, we only need to sample the scattering angle using the differential cross section in
(3.6.2) since the energy of the photon does not change. In OpenMC, anomalous scattering is ignored such that the
differential cross section becomes
𝑑𝜎(𝐸, 𝐸 ′ , 𝜇)
= 𝜋𝑟𝑒2 (1 + 𝜇2 )𝐹 (𝑥, 𝑍)2 (3.6.3)
𝑑𝜇
To construct a proper probability density, we need to normalize the differential cross section in (3.6.3) by the integrated
coherent scattering cross section:
𝜋𝑟𝑒2
𝑝(𝜇)𝑑𝜇 = (1 + 𝜇2 )𝐹 (𝑥, 𝑍)2 𝑑𝜇. (3.6.4)
𝜎(𝐸)
Since the form factor is given in terms of the momentum transfer, it is more convenient to change variables of the
probability density to 𝑥2 . The momentum transfer is traditionally expressed as
(3.6.5)
√︀
𝑥 = 𝑎𝑘 1 − 𝜇
where 𝑘 is the ratio of the photon energy to the electron rest mass, and the coefficient 𝑎 can be shown to be
𝑚𝑒 𝑐2
𝑎= √ ≈ 2.914329 × 10−9 m (3.6.6)
2ℎ𝑐
where 𝑚𝑒 is the mass of the electron, 𝑐 is the speed of light in a vacuum, and ℎ is Planck’s constant. Using (3.6.5), we
have 𝜇 = 1 − [𝑥/(𝑎𝑘)]2 and 𝑑𝜇/𝑑𝑥2 = −1/(𝑎𝑘)2 . The probability density in 𝑥2 is
2𝜋𝑟𝑒2 𝐴(¯𝑥2 , 𝑍) 1 + 𝜇2 𝐹 (𝑥, 𝑍)2

⃒ ⃒ (︂ )︂ (︂ )︂
⃒ 𝑑𝜇 ⃒ 2
2 2
𝑝(𝑥 )𝑑𝑥 = 𝑝(𝜇) ⃒ 2 ⃒ 𝑑𝑥 =
⃒ ⃒ 𝑑𝑥2 (3.6.7)
𝑑𝑥 (𝑎𝑘)2 𝜎(𝐸) 2 𝐴(¯𝑥2 , 𝑍)
where 𝑥
¯ is the maximum value of 𝑥 that occurs for 𝜇 = −1,
√ 𝑚𝑒 𝑐2
𝑥
¯ = 𝑎𝑘 2 = 𝑘, (3.6.8)
ℎ𝑐
and 𝐴(𝑥2 , 𝑍) is the integral of the square of the form factor:
∫︁ 𝑥2
2
𝐴(𝑥 , 𝑍) = 𝐹 (𝑥, 𝑍)2 𝑑𝑥2 . (3.6.9)
0
As you see, we have multiplied and divided the probability density by the integral of the squared form factor so that the
density in (3.6.7) is expressed as the product of two separate densities in parentheses. In OpenMC, a table of 𝐴(𝑥2 , 𝑍)
versus 𝑥2 is pre-generated and used at run-time to do a table search on the cumulative distribution function:
∫︀ 𝑥2
𝐹 (𝑥, 𝑍)2 𝑑𝑥2
0
∫︀ 𝑥¯2 (3.6.10)
0
𝐹 (𝑥, 𝑍)2 𝑑𝑥2
Once a trial 𝑥2 value has been selected, we can calculate 𝜇 and perform rejection sampling using the Thomson scattering
differential cross section. The complete algorithm is as follows:

1. Determine 𝑥
¯2 using (3.6.8).
2. Determine 𝐴𝑚𝑎𝑥 = 𝐴(¯
𝑥2 , 𝑍) using the pre-generated tabulated data.
3. Sample the cumulative density by calculating 𝐴′ = 𝜉1 𝐴𝑚𝑎𝑥 where 𝜉1 is a uniformly distributed random number.
4. Perform a binary search to determine the value of 𝑥2 which satisfies 𝐴(𝑥2 , 𝑍) = 𝐴′ .
5. By combining (3.6.5) and (3.6.8), calculate 𝜇 = 1 − 2𝑥2 /¯
𝑥2 .
6. If 𝜉2 < (1 + 𝜇2 )/2, accept 𝜇. Otherwise, repeat the sampling at step 3.
Incoherent (Compton) Scattering
Before we noted that the Thomson cross section gives the behavior for photons scattering off of free electrons valid at
low energies. The formula for photon scattering off of free electrons that is valid for all energies can be found using
quantum electrodynamics and is known as the Klein-Nishina formula after the two authors who discovered it:
(︂ ′ )︂2 [︂ ′ ]︂
𝑑𝜎𝐾𝑁 𝑘 𝑘 𝑘
= 𝜋𝑟𝑒 2
+ ′ +𝜇 −12 (3.6.11)
𝑑𝜇 𝑘 𝑘 𝑘
where 𝑘 and 𝑘 ′ are the ratios of the incoming and exiting photon energies to the electron rest mass energy equivalent
(0.511 MeV), respectively. Although it appears that the outgoing energy and angle are separate, there is actually a
one-to-one relationship between them such that only one needs to be sampled:
𝑘
𝑘′ = . (3.6.12)
1 + 𝑘(1 − 𝜇)
Note that when 𝑘 ′ /𝑘 goes to one, i.e., scattering is elastic, the Klein-Nishina cross section becomes identical to the
Thomson cross section. In general though, the scattering is inelastic and is known as Compton scattering. When a
photon interacts with a bound electron in an atom, the Klein-Nishina formula must be modified to account for the
binding effects. As in the case of coherent scattering, this is done by means of a form factor. The differential cross
section for incoherent scattering is given by
(︂ ′ )︂2 [︂ ′ ]︂
𝑑𝜎 𝑑𝜎𝐾𝑁 𝑘 𝑘 𝑘
= 𝑆(𝑥, 𝑍) = 𝜋𝑟𝑒 2 2
+ ′ + 𝜇 − 1 𝑆(𝑥, 𝑍) (3.6.13)
𝑑𝜇 𝑑𝜇 𝑘 𝑘 𝑘
where 𝑆(𝑥, 𝑍) is the form factor. The approach in OpenMC is to first sample the Klein-Nishina cross section and then
perform rejection sampling on the form factor. As in other codes, Kahn’s rejection method is used for 𝑘 < 3 and a
direct method by Koblinger is used for 𝑘 ≥ 3. The complete algorithm is as follows:
1. If 𝑘 < 3, sample 𝜇 from the Klein-Nishina cross section using Kahn’s rejection method. Otherwise, use
Koblinger’s direct method.
2. Calculate 𝑥 and 𝑥
¯ using (3.6.5) and (3.6.8), respectively.
3. If 𝜉 < 𝑆(𝑥, 𝑍)/𝑆(¯
𝑥, 𝑍), accept 𝜇. Otherwise repeat from step 1.
Doppler Energy Broadening
Bound electrons are not at rest but have a momentum distribution that will cause the energy of the scattered photon to
be Doppler broadened. More tightly bound electrons have a wider momentum distribution, so the energy spectrum of
photons scattering off inner shell electrons will be broadened the most. In addition, scattering from bound electrons
places a limit on the maximum scattered photon energy:
′
𝐸max = 𝐸 − 𝐸𝑏,𝑖 , (3.6.14)
where 𝐸𝑏,𝑖 is the binding energy of the 𝑖-th subshell.

Compton profiles 𝐽𝑖 (𝑝𝑧 ) are used to account for the binding effects. The quantity 𝑝𝑧 = p · q/𝑞 is the projection of the
initial electron momentum on q, where the scattering vector q = p − p′ is the momentum gained by the photon, p is
the initial momentum of the electron, and p′ is the momentum of the scattered electron. Applying the conservation of
energy and momentum, 𝑝𝑧 can be written in terms of the photon energy and scattering angle:
𝐸 − 𝐸 ′ − 𝐸𝐸 ′ (1 − 𝜇)/(𝑚𝑒 𝑐2 )
𝑝𝑧 = √︀ , (3.6.15)
−𝛼 𝐸 2 + 𝐸 ′2 − 2𝐸𝐸 ′ 𝜇
where 𝛼 is the fine structure constant. The maximum momentum transferred, 𝑝𝑧,max , can be calculated from (3.6.15)
using 𝐸 ′ = 𝐸max
′
. The Compton profile of the 𝑖-th electron subshell is defined as
∫︁ ∫︁
𝐽𝑖 (𝑝𝑧 ) = 𝜌𝑖 (p)𝑑𝑝𝑥 𝑑𝑝𝑦 , (3.6.16)
where 𝜌𝑖 (p) is the initial electron momentum distribution. 𝐽𝑖 (𝑝𝑧 ) can be interpreted as the probability density function
of 𝑝𝑧 .
The Doppler broadened energy of the Compton-scattered photon can be sampled by selecting an electron shell, sam-
pling a value of 𝑝𝑧 using the Compton profile, and calculating the scattered photon energy. The theory and methods
used to do this are described in detail in LA-UR-04-0487 and LA-UR-04-0488. The sampling algorithm is summarized
below:
1. Sample 𝜇 from (3.6.13) using the algorithm described in Incoherent (Compton) Scattering.
2. Sample the electron subshell 𝑖 using the number of electrons per shell as the probability mass function.
3. Sample 𝑝𝑧 using 𝐽𝑖 (𝑝𝑧 ) as the PDF.
4. Calculate 𝐸 ′ by solving (3.6.15) for 𝐸 ′ using the sampled value of 𝑝𝑧 .
5. If 𝑝𝑧 < 𝑝𝑧,max for shell 𝑖, accept 𝐸 ′ . Otherwise repeat from step 2.
Compton Electrons
Because the Compton-scattered photons can transfer a large fraction of their energy to the kinetic energy of the recoil
electron, which may in turn go on to lose its energy as bremsstrahlung radiation, it is necessary to accurately model the
angular and energy distributions of Compton electrons. The energy of the recoil electron ejected from the 𝑖-th subshell
is given by
𝐸− = 𝐸 − 𝐸 ′ − 𝐸𝑏,𝑖 . (3.6.17)
The direction of the electron is assumed to be in the direction of the momentum transfer, with the cosine of the polar
angle given by
𝐸 − 𝐸′𝜇
𝜇− = √︀ (3.6.18)
𝐸 2 + 𝐸 ′2 − 2𝐸𝐸 ′ 𝜇
and the azimuthal angle 𝜑− = 𝜑 + 𝜋, where 𝜑 is the azimuthal angle of the photon. The vacancy left by the ejected
electron is filled through atomic relaxation.

Photoelectric Effect
In the photoelectric effect, the incident photon is absorbed by an atomic electron, which is then emitted from the 𝑖-th
shell with kinetic energy
𝐸− = 𝐸 − 𝐸𝑏,𝑖 . (3.6.19)
Photoelectric emission is only possible when the photon energy exceeds the binding energy of the shell. These binding
energies are often referred to as edge energies because the otherwise continuously decreasing cross section has discon-
tinuities at these points, creating the characteristic sawtooth shape. The photoelectric effect dominates at low energies
and is more important for heavier elements.
When simulating the photoelectric effect, the first step is to sample the electron shell. The shell 𝑖 where the ionization
occurs can be considered a discrete random variable with probability mass function
𝜎pe,𝑖
𝑝𝑖 = , (3.6.20)
𝜎pe
where 𝜎pe,𝑖 is the cross section of the 𝑖-th shell, and the total photoelectric cross section of the atom, 𝜎pe , is the sum over
the shell cross sections. Once the shell has been sampled, the energy of the photoelectron is calculated using (3.6.19).
To determine the direction of the photoelectron, we implement the method described in Kaltiaisenaho, which models
the angular distribution of the photoelectrons using the K-shell cross section derived by Sauter (K-shell electrons are
the most tightly bound, and they contribute the most to 𝜎pe ). The non-relativistic Sauter distribution for unpolarized
photons can be approximated as
𝑑𝜎pe 1 − 𝜇2−
∝ , (3.6.21)
𝑑𝜇− (1 − 𝛽− 𝜇− )4
where 𝛽− is the ratio of the velocity of the electron to the speed of light,
√︀
(𝐸− (𝐸− + 2𝑚𝑒 𝑐2 )
𝛽− = . (3.6.22)
𝐸− + 𝑚𝑒 𝑐2
To sample 𝜇− from the Sauter distribution, we first express (3.6.21) in the form:
3
𝑓 (𝜇− ) = 𝜓(𝜇− )𝑔(𝜇− ), (3.6.23)
2
where
2
(1 − 𝛽− )(1 − 𝜇2− )
𝜓(𝜇− ) = ,
(1 − 𝛽− 𝜇− )2
2
(3.6.24)
1 − 𝛽−
𝑔(𝜇− ) = .
2(1 − 𝛽− 𝜇− )2
In the interval [−1, 1], 𝑔(𝜇− ) is a normalized PDF and 𝜓(𝜇− ) satisfies the condition 0 < 𝜓(𝜇− ) < 1. The following
algorithm can now be used to sample 𝜇− :
1. Using the inverse transform method, sample 𝜇− from 𝑔(𝜇− ) using the sampling formula
2𝜉1 + 𝛽− − 1
𝜇− = .
2𝛽− 𝜉1 − 𝛽− + 1
2. If 𝜉2 ≤ 𝜓(𝜇− ), accept 𝜇− . Otherwise, repeat the sampling from step 1.

The azimuthal angle is sampled uniformly on [0, 2𝜋).
The atom is left in an excited state with a vacancy in the 𝑖-th shell and decays to its ground state through a cascade of
transitions that produce fluorescent photons and Auger electrons.

Pair Production
In electron-positron pair production, a photon is absorbed in the vicinity of an atomic nucleus or an electron and an
electron and positron are created. Pair production is the dominant interaction with matter at high photon energies and
is more important for high-Z elements. When it takes place in the field of a nucleus, energy is essentially conserved
among the incident photon and the resulting charged particles. Therefore, in order for pair production to occur, the
photon energy must be greater than the sum of the rest mass energies of the electron and positron, i.e., 𝐸threshold,pp =
2𝑚𝑒 𝑐2 = 1.022 MeV.
The photon can also interact in the field of an atomic electron. This process is referred to as “triplet production”
because the target electron is ejected from the atom and three charged particles emerge from the interaction. In this
case, the recoiling electron also absorbs some energy, so the energy threshold for triplet production is greater than that
of pair production from atomic nuclei, with 𝐸threshold,tp = 4𝑚𝑒 𝑐2 = 2.044 MeV. The ratio of the triplet production
cross section to the pair production cross section is approximately 1/Z, so triplet production becomes increasingly
unimportant for high-Z elements. Though it can be significant in lighter elements, the momentum of the recoil electron
becomes negligible in the energy regime where pair production dominates. For our purposes, it is a good approximation
to treat triplet production as pair production and only simulate the electron-positron pair.
Accurately modeling the creation of electron-positron pair is important because the charged particles can go on to lose
much of their energy as bremsstrahlung radiation, and the subsequent annihilation of the positron with an electron
produces two additional photons. We sample the energy and direction of the charged particles using a semiempirical
model described in Salvat. The Bethe-Heitler differential cross section, given by
[︂ ]︂
𝑑𝜎pp 2
2 2 2 2
= 𝛼𝑟𝑒 𝑍 (𝜖 + (1 − 𝜖) )(Φ1 − 4𝑓𝐶 ) + 𝜖(1 − 𝜖)(Φ2 − 4𝑓𝐶 ) , (3.6.25)
𝑑𝜖 3
is used as a starting point, where 𝛼 is the fine structure constant, 𝑓𝐶 is the Coulomb correction function, Φ1 and Φ2 are
screening functions, and 𝜖 = (𝐸− + 𝑚𝑒 𝑐2 )/𝐸 is the electron reduced energy (i.e., the fraction of the photon energy
given to the electron). 𝜖 can take values between 𝜖min = 𝑘 −1 (when the kinetic energy of the electron is zero) and
𝜖max = 1 − 𝑘 −1 (when the kinetic energy of the positron is zero).
The Coulomb correction, given by
𝑓𝐶 = 𝛼2 𝑍 2 (1 + 𝛼2 𝑍 2 )−1 + 0.202059 − 0.03693𝛼2 𝑍 2 + 0.00835𝛼4 𝑍 4

[︀
(3.6.26)
− 0.00201𝛼6 𝑍 6 + 0.00049𝛼8 𝑍 8 − 0.00012𝛼10 𝑍 10 + 0.00003𝛼12 𝑍 12
]︀
is introduced to correct for the fact that the Bethe-Heitler differential cross section was derived using the Born approx-
imation, which treats the Coulomb interaction as a small perturbation.
The screening functions Φ1 and Φ2 account for the screening of the Coulomb field of the atomic nucleus by outer
electrons. Since they are given by integrals which include the atomic form factor, they must be computed numerically
for a realistic form factor. However, by assuming exponential screening and using a simplified form factor, analytical
approximations of the screening functions can be derived:
Φ1 = 2 − 2 ln(1 + 𝑏2 ) − 4𝑏 arctan(𝑏−1 ) + 4 ln(𝑅𝑚𝑒 𝑐/ℏ)

4 (3.6.27)
Φ2 = − 2 ln(1 + 𝑏2 ) + 2𝑏2 4 − 4𝑏 arctan(𝑏−1 ) − 3 ln(1 + 𝑏−2 ) + 4 ln(𝑅𝑚𝑒 𝑐/ℏ)
[︀ ]︀
3
where
𝑅𝑚𝑒 𝑐
𝑏= . (3.6.28)
2𝑘𝜖(1 − 𝜖)ℏ
and 𝑅 is the screening radius.

The differential cross section in (3.6.25) with the approximations described above will not be accurate at low energies:
the lower boundary of 𝜖 will be shifted above 𝜖min and the upper boundary of 𝜖 will be shifted below 𝜖max . To offset this

behavior, a correcting factor 𝐹0 (𝑘, 𝑍) is used:

𝐹0 (𝑘, 𝑍) = (0.1774 + 12.10𝛼𝑍 − 11.18𝛼2 𝑍 2 )(2/𝑘)1/2
+ (8.523 + 73.26𝛼𝑍 − 44.41𝛼2 𝑍 2 )(2/𝑘)
(3.6.29)
− (13.52 + 121.1𝛼𝑍 − 96.41𝛼2 𝑍 2 )(2/𝑘)3/2
+ (8.946 + 62.05𝛼𝑍 − 63.41𝛼2 𝑍 2 )(2/𝑘)2 .
To aid sampling, the differential cross section used to sample 𝜖 (minus the normalization constant) can now be expressed
in the form
𝑑𝜎pp 𝜑1 (𝜖) 𝜑2 (𝜖)
= 𝑢1 𝜋1 (𝜖) + 𝑢2 𝜋2 (𝜖) (3.6.30)
𝑑𝜖 𝜑1 (1/2) 𝜑2 (1/2)
where
(︂ )︂2
2 1 1
𝑢1 = − 𝜑1 (1/2),
3 2 𝑘 (3.6.31)
𝑢2 = 𝜑2 (1/2),
1
𝜑1 (𝜖) = (3Φ1 − Φ2 ) − 4𝑓𝐶 (𝑍) + 𝐹0 (𝑘, 𝑍),
2 (3.6.32)
1
𝜑2 (𝜖) = (3Φ1 + Φ2 ) − 4𝑓𝐶 (𝑍) + 𝐹0 (𝑘, 𝑍),
4
and
(︂ )︂−3 (︂ )︂2
3 1 1 1
𝜋1 (𝜖) = − −𝜖 ,
2 2 𝑘 2
(︂ )︂−1 (3.6.33)
1 1 1
𝜋2 (𝜖) = − .
2 2 𝑘
The functions in (3.6.32) are non-negative and maximum at 𝜖 = 1/2. In the interval (𝜖min , 𝜖max ), the functions in
(3.6.33) are normalized PDFs and 𝜑𝑖 (𝜖)/𝜑𝑖 (1/2) satisfies the condition 0 < 𝜑𝑖 (𝜖)/𝜑𝑖 (1/2) < 1. The following
algorithm can now be used to sample the reduced electron energy 𝜖:
1. Sample 𝑖 according to the point probabilities 𝑝(𝑖 = 1) = 𝑢1 /(𝑢1 + 𝑢2 ) and 𝑝(𝑖 = 2) = 𝑢2 /(𝑢1 + 𝑢2 ).
2. Using the inverse transform method, sample 𝜖 from 𝜋𝑖 (𝜖) using the sampling formula
(︂ )︂
1 1 1
𝜖= + − (2𝜉1 − 1)1/3 if 𝑖 = 1
2 2 𝑘
(︂ )︂
1 1 1
𝜖= + − 2𝜉1 if 𝑖 = 2.
𝑘 2 𝑘
3. If 𝜉2 ≤ 𝜑𝑖 (𝜖)/𝜑𝑖 (1/2), accept 𝜖. Otherwise, repeat the sampling from step 1.

Because charged particles have a much smaller range than the mean free path of photons and because they immediately
undergo multiple scattering events which randomize their direction, it is sufficient to use a simplified model to sample
the direction of the electron and positron. The cosines of the polar angles are sampled using the leading order term of
the Sauter–Gluckstern–Hull distribution,
𝑝(𝜇± ) = 𝐶(1 − 𝛽± 𝜇± )−2 , (3.6.34)
where 𝐶 is a normalization constant and 𝛽± is the ratio of the velocity of the charged particle to the speed of light given
in (3.6.22).
The inverse transform method is used to sample 𝜇− and 𝜇+ from (3.6.34), using the sampling formula
2𝜉 − 1 + 𝛽±
𝜇± = . (3.6.35)
(2𝜉 − 1)𝛽± + 1
The azimuthal angles for the electron and positron are sampled independently and uniformly on [0, 2𝜋).

3.6.2 Secondary Processes
New photons may be produced in secondary processes related to the main photon interactions discussed above. A
Compton-scattered photon transfers a portion of its energy to the kinetic energy of the recoil electron, which in turn
may lose the energy as bremsstrahlung radiation. The vacancy left in the shell by the ejected electron is filled through
atomic relaxation, creating a shower of electrons and fluorescence photons. Similarly, the vacancy left by the electron
emitted in the photoelectric effect is filled through atomic relaxation. Pair production generates an electron and a
positron, both of which can emit bremsstrahlung radiation before the positron eventually collides with an electron,
resulting in annihilation of the pair and the creation of two additional photons.
Atomic Relaxation
When an electron is ejected from an atom and a vacancy is left in an inner shell, an electron from a higher energy
level will fill the vacancy. This results in either a radiative transition, in which a photon with a characteristic energy
(fluorescence photon) is emitted, or non-radiative transition, in which an electron from a shell that is farther out (Auger
electron) is emitted. If a non-radiative transition occurs, the new vacancy is filled in the same manner, and as the
process repeats a shower of photons and electrons can be produced.
The energy of a fluorescence photon is the equal to the energy difference between the transition states, i.e.,
𝐸 = 𝐸𝑏,𝑣 − 𝐸𝑏,𝑖 , (3.6.36)
where 𝐸𝑏,𝑣 is the binding energy of the vacancy shell and 𝐸𝑏,𝑖 is the binding energy of the shell from which the electron
transitioned. The energy of an Auger electron is given by
𝐸− = 𝐸𝑏,𝑣 − 𝐸𝑏,𝑖 − 𝐸𝑏,𝑎 , (3.6.37)
where 𝐸𝑏,𝑎 is the binding energy of the shell from which the Auger electron is emitted. While Auger electrons are
low-energy so their range and bremsstrahlung yield is small, fluorescence photons can travel far before depositing their
energy, so the relaxation process should be modeled in detail.
Transition energies and probabilities are needed for each subshell to simulate atomic relaxation. Starting with the initial
shell vacancy, the following recursive algorithm is used to fill vacancies and create fluorescence photons and Auger
electrons:
1. If there are no transitions for the vacancy shell, create a fluorescence photon assuming it is from a captured free
electron and terminate.
2. Sample a transition using the transition probabilities for the vacancy shell as the probability mass function.
3. Create either a fluorescence photon or Auger electron, sampling the direction of the particle isotropically.
4. If a non-radiative transition occurred, repeat from step 1 for the vacancy left by the emitted Auger electron.
5. Repeat from step 1 for vacancy left by the transition electron.
Electron-Positron Annihilation
When a positron collides with an electron, both particles are annihilated and generally two photons with equal energy
are created. If the kinetic energy of the positron is high enough, the two photons can have different energies, and the
higher-energy photon is emitted preferentially in the direction of flight of the positron. It is also possible to produce a
single photon if the interaction occurs with a bound electron, and in some cases three (or, rarely, even more) photons
can be emitted. However, the annihilation cross section is largest for low-energy positrons, and as the positron energy
decreases, the angular distribution of the emitted photons becomes isotropic.
In OpenMC, we assume the most likely case in which a low-energy positron (which has already lost most of its energy
to bremsstrahlung radiation) interacts with an electron which is free and at rest. Two photons with energy equal to the
electron rest mass energy 𝑚𝑒 𝑐2 = 0.511 MeV are emitted isotropically in opposite directions.

Bremsstrahlung
When a charged particle is decelerated in the field of an atom, some of its kinetic energy is converted into electro-
magnetic radiation known as bremsstrahlung, or ‘braking radiation’. In each event, an electron or positron with kinetic
energy 𝑇 generates a photon with an energy 𝐸 between 0 and 𝑇 . Bremsstrahlung is described by a cross section that
is differential in photon energy, in the direction of the emitted photon, and in the final direction of the charged particle.
However, in Monte Carlo simulations it is typical to integrate over the angular variables to obtain a single differential
cross section with respect to photon energy, which is often expressed in the form
𝑑𝜎br 𝑍2 1
= 2 𝜒(𝑍, 𝑇, 𝜅), (3.6.38)
𝑑𝐸 𝛽 𝐸
where 𝜅 = 𝐸/𝑇 is the reduced photon energy and 𝜒(𝑍, 𝑇, 𝜅) is the scaled bremsstrahlung cross section, which is
experimentally measured.
Because electrons are attracted to atomic nuclei whereas positrons are repulsed, the cross section for positrons is smaller,
though it approaches that of electrons in the high energy limit. To obtain the positron cross section, we multiply (3.6.38)
by the 𝜅-independent factor used in Salvat,
𝐹p (𝑍, 𝑇 ) =1 − exp(−1.2359 × 10−1 𝑡 + 6.1274 × 10−2 𝑡2 − 3.1516 × 10−2 𝑡3

+ 7.7446 × 10−3 𝑡4 − 1.0595 × 10−3 𝑡5 + 7.0568 × 10−5 𝑡6 (3.6.39)
−6 7
− 1.8080 × 10 𝑡 ),
where
106 𝑇
(︂ )︂
𝑡 = ln 1 + 2 . (3.6.40)
𝑍 me 𝑐2
𝐹p (𝑍, 𝑇 ) is the ratio of the radiative stopping powers for positrons and electrons. Stopping power describes the average
energy loss per unit path length of a charged particle as it passes through matter:
∫︁
𝑑𝑇 𝑑𝜎
− =𝑛 𝐸 𝑑𝐸 ≡ 𝑆(𝑇 ), (3.6.41)
𝑑𝑠 𝑑𝐸
where 𝑛 is the number density of the material and 𝑑𝜎/𝑑𝐸 is the cross section differential in energy loss. The total
stopping power 𝑆(𝑇 ) can be separated into two components: the radiative stopping power 𝑆rad (𝑇 ), which refers to
energy loss due to bremsstrahlung, and the collision stopping power 𝑆col (𝑇 ), which refers to the energy loss due to
inelastic collisions with bound electrons in the material that result in ionization and excitation. The radiative stopping
power for electrons is given by
∫︁ 1
𝑍2
𝑆rad (𝑇 ) = 𝑛 2 𝑇 𝜒(𝑍, 𝑇, 𝜅)𝑑𝜅. (3.6.42)
𝛽 0
To obtain the radiative stopping power for positrons, (3.6.42) is multiplied by (3.6.39).
While the models for photon interactions with matter described above can safely assume interactions occur with free
atoms, sampling the target atom based on the macroscopic cross sections, molecular effects cannot necessarily be
disregarded for charged particle treatment. For compounds and mixtures, the bremsstrahlung cross section is calculated
using Bragg’s additivity rule as
𝑑𝜎br 1 ∑︁
= 2 𝛾𝑖 𝑍𝑖2 𝜒(𝑍𝑖 , 𝑇, 𝜅), (3.6.43)
𝑑𝐸 𝛽 𝐸 𝑖
where the sum is over the constituent elements and 𝛾𝑖 is the atomic fraction of the 𝑖-th element. Similarly, the radiative
stopping power is calculated using Bragg’s additivity rule as
∑︁
𝑆rad (𝑇 ) = 𝑤𝑖 𝑆rad,𝑖 (𝑇 ), (3.6.44)
𝑖

where 𝑤𝑖 is the mass fraction of the 𝑖-th element and 𝑆rad,𝑖 (𝑇 ) is found for element 𝑖 using (3.6.42). The collision
stopping power, however, is a function of certain quantities such as the mean excitation energy 𝐼 and the density
effect correction 𝛿𝐹 that depend on molecular properties. These quantities cannot simply be summed over constituent
elements in a compound, but should instead be calculated for the material. The Bethe formula can be used to find the
collision stopping power of the material:
2𝜋𝑟𝑒2 𝑚𝑒 𝑐2 𝑍
𝑆col (𝑇 ) = 2
𝑁𝐴 [ln(𝑇 2 /𝐼 2 ) + ln(1 + 𝜏 /2) + 𝐹 (𝜏 ) − 𝛿𝐹 (𝑇 )], (3.6.45)
𝛽 𝐴𝑀
where 𝑁𝐴 is Avogadro’s number, 𝐴𝑀 is the molar mass, 𝜏 = 𝑇 /𝑚𝑒 , and 𝐹 (𝜏 ) depends on the particle type. For
electrons,
𝐹− (𝜏 ) = (1 − 𝛽 2 )[1 + 𝜏 2 /8 − (2𝜏 + 1) ln 2], (3.6.46)
while for positrons
𝐹+ (𝜏 ) = 2 ln 2 − (𝛽 2 /12)[23 + 14/(𝜏 + 2) + 10/(𝜏 + 2)2 + 4/(𝜏 + 2)3 ]. (3.6.47)
The density effect correction 𝛿𝐹 takes into account the reduction of the collision stopping power due to the polarization
of the material the charged particle is passing through by the electric field of the particle. It can be evaluated using the
method described by Sternheimer, where the equation for 𝛿𝐹 is
𝑛
∑︁
𝛿𝐹 (𝛽) = 𝑓𝑖 ln[(𝑙𝑖2 + 𝑙2 )/𝑙𝑖2 ] − 𝑙2 (1 − 𝛽 2 ). (3.6.48)
𝑖=1
Here, 𝑓𝑖 is the oscillator strength of the 𝑖-th transition, given by 𝑓𝑖 = 𝑛𝑖 /𝑍, where 𝑛𝑖 is the number of electrons in the
𝑖-th subshell. The frequency 𝑙 is the solution of the equation
𝑛
1 ∑︁ 𝑓𝑖
− 1 = , (3.6.49)
𝛽2 𝜈¯2 + 𝑙2
𝑖=1 𝑖
where 𝑣¯𝑖 is defined as
𝜈¯𝑖 = ℎ𝜈𝑖 𝜌/ℎ𝜈𝑝 . (3.6.50)
The plasma energy ℎ𝜈𝑝 of the medium is given by

√︂
(ℎ𝑐)2 𝑟𝑒 𝜌𝑚 𝑁𝐴 𝑍 (3.6.51)
ℎ𝜈𝑝 = ,
𝜋𝐴
where 𝐴 is the atomic weight and 𝜌𝑚 is the density of the material. In (3.6.50), ℎ𝜈𝑖 is the oscillator energy, and 𝜌 is
an adjustment factor introduced to give agreement between the experimental values of the oscillator energies and the
mean excitation energy. The 𝑙𝑖 in (3.6.48) are defined as
𝜈𝑖2 + 2/3𝑓𝑖 )1/2

𝑙𝑖 = (¯ for 𝜈¯𝑖 > 0
(3.6.52)
𝑙𝑛 = 𝑓𝑛1/2 for 𝜈¯𝑛 = 0,
where the second case applies to conduction electrons. For a conductor, 𝑓𝑛 is given by 𝑛𝑐 /𝑍, where 𝑛𝑐 is the effective
number of conduction electrons, and 𝑣𝑛 = 0. The adjustment factor 𝜌 is determined using the equation for the mean
excitation energy:
𝑛−1
∑︁
ln 𝐼 = 𝑓𝑖 ln[(ℎ𝜈𝑖 𝜌)2 + 2/3𝑓𝑖 (ℎ𝜈𝑝 )2 ]1/2 + 𝑓𝑛 ln(ℎ𝜈𝑝 𝑓𝑛1/2 ). (3.6.53)
𝑖=1

Thick-Target Bremsstrahlung Approximation
Since charged particles lose their energy on a much shorter distance scale than neutral particles, not much error should
be introduced by neglecting to transport electrons. However, the bremsstrahlung emitted from high energy electrons
and positrons can travel far from the interaction site. Thus, even without a full electron transport mode it is necessary
to model bremsstrahlung. We use a thick-target bremsstrahlung (TTB) approximation based on the models in Salvat
and Kaltiaisenaho for generating bremsstrahlung photons, which assumes the charged particle loses all its energy in a
single homogeneous material region.
To model bremsstrahlung using the TTB approximation, we need to know the number of photons emitted by the charged
particle and the energy distribution of the photons. These quantities can be calculated using the continuous slowing
down approximation (CSDA). The CSDA assumes charged particles lose energy continuously along their trajectory
with a rate of energy loss equal to the total stopping power, ignoring fluctuations in the energy loss. The approximation
is useful for expressing average quantities that describe how charged particles slow down in matter. For example, the
CSDA range approximates the average path length a charged particle travels as it slows to rest:
∫︁ 𝑇
𝑑𝑇 ′
𝑅(𝑇 ) = ′
. (3.6.54)
0 𝑆(𝑇 )
Actual path lengths will fluctuate around 𝑅(𝑇 ). The average number of photons emitted per unit path length is given
by the inverse bremsstrahlung mean free path:
∫︁ 𝑇
𝑍2 1 1
∫︁
𝑑𝜎br
𝜆−1
br (𝑇, 𝐸 cut ) = 𝑛 𝑑𝐸 = 𝑛 𝜒(𝑍, 𝑇, 𝜅)𝑑𝜅. (3.6.55)
𝐸cut 𝑑𝐸 𝛽 2 𝜅cut 𝜅
The lower limit of the integral in (3.6.55) is non-zero because the bremsstrahlung differential cross section diverges for
small photon energies but is finite for photon energies above some cutoff energy 𝐸cut . The mean free path 𝜆−1br (𝑇, 𝐸cut )
is used to calculate the photon number yield, defined as the average number of photons emitted with energy greater
than 𝐸cut as the charged particle slows down from energy 𝑇 to 𝐸cut . The photon number yield is given by
∫︁ 𝑅(𝑇 ) ∫︁ 𝑇 −1 ′
𝜆br (𝑇 , 𝐸cut ) ′
𝑌 (𝑇, 𝐸cut ) = 𝜆−1
br (𝑇 ′
, 𝐸cut )𝑑𝑠 = 𝑑𝑇 . (3.6.56)
𝑅(𝐸cut ) 𝐸cut 𝑆(𝑇 ′ )
𝑌 (𝑇, 𝐸cut ) can be used to construct the energy spectrum of bremsstrahlung photons: the number of photons created
with energy between 𝐸1 and 𝐸2 by a charged particle with initial kinetic energy 𝑇 as it comes to rest is given by
𝑌 (𝑇, 𝐸1 ) − 𝑌 (𝑇, 𝐸2 ).
To simulate the emission of bremsstrahlung photons, the total stopping power and bremsstrahlung differential cross
section for positrons and electrons must be calculated for a given material using (3.6.43) and (3.6.44). These quantities
are used to build the tabulated bremsstrahlung energy PDF and CDF for that material for each incident energy 𝑇𝑘 on
the energy grid. The following algorithm is then applied to sample the photon energies:
1. For an incident charged particle with energy 𝑇 , sample the number of emitted photons as
𝑁 = ⌊𝑌 (𝑇, 𝐸cut ) + 𝜉1 ⌋.
2. Rather than interpolate the PDF between indices 𝑘 and 𝑘+1 for which 𝑇𝑘 < 𝑇 < 𝑇𝑘+1 , which is computationally
expensive, use the composition method and sample from the PDF at either 𝑘 or 𝑘 + 1. Using linear interpolation
on a logarithmic scale, the PDF can be expressed as
𝑝br (𝑇, 𝐸) = 𝜋𝑘 𝑝br (𝑇𝑘 , 𝐸) + 𝜋𝑘+1 𝑝br (𝑇𝑘+1 , 𝐸),
where the interpolation weights are

ln 𝑇𝑘+1 − ln 𝑇 ln 𝑇 − ln 𝑇𝑘
𝜋𝑘 = , 𝜋𝑘+1 = .
ln 𝑇𝑘+1 − ln 𝑇𝑘 ln 𝑇𝑘+1 − ln 𝑇𝑘
Sample either the index 𝑖 = 𝑘 or 𝑖 = 𝑘 + 1 according to the point probabilities 𝜋𝑘 and 𝜋𝑘+1 .

3. Determine the maximum value of the CDF 𝑃br,max .

3. Sample the photon energies using the inverse transform method with the tabulated CDF 𝑃br (𝑇𝑖 , 𝐸) i.e.,
[︂ 1
]︂ 1+𝑎
𝜉2 𝑃br,max − 𝑃br (𝑇𝑖 , 𝐸𝑗 ) 𝑗
𝐸 = 𝐸𝑗 (1 + 𝑎𝑗 ) +1
𝐸𝑗 𝑝br (𝑇𝑖 , 𝐸𝑗 )
where the interpolation factor 𝑎𝑗 is given by
ln 𝑝br (𝑇𝑖 , 𝐸𝑗+1 ) − ln 𝑝br (𝑇𝑖 , 𝐸𝑗 )

𝑎𝑗 =
ln 𝐸𝑗+1 − ln 𝐸𝑗
and 𝑃br (𝑇𝑖 , 𝐸𝑗 ) ≤ 𝜉2 𝑃br,max ≤ 𝑃br (𝑇𝑖 , 𝐸𝑗+1 ).

We ignore the range of the electron or positron, i.e., the bremsstrahlung photons are produced in the same location that
the charged particle was created. The direction of the photons is assumed to be the same as the direction of the incident
charged particle, which is a reasonable approximation at higher energies when the bremsstrahlung radiation is emitted
at small angles.
3.6.3 Photon Production
In coupled neutron-photon transport, a source neutron is tracked, and photons produced from neutron reactions are
transported after the neutron’s history has terminated. Since these secondary photons form the photon source for the
problem, it is important to correctly describe their energy and angular distributions as the accuracy of the calculation
relies on the accuracy of this source. The photon production cross section for a particular reaction 𝑖 and incident neutron
energy 𝐸 is defined as
𝜎𝛾,𝑖 (𝐸) = 𝑦𝑖 (𝐸)𝜎𝑖 (𝐸), (3.6.57)
where 𝑦𝑖 (𝐸) is the photon yield corresponding to an incident neutron reaction having cross section 𝜎𝑖 (𝐸).
The yield of photons during neutron transport is determined as the sum of the photon yields from each individual
reaction. In OpenMC, production of photons is treated in an average sense. That is, the total photon production cross
section is used at a collision site to determine how many photons to produce rather than the photon production from
the reaction that actually took place. This is partly done for convenience but also because the use of variance reduction
techniques such as implicit capture make it difficult in practice to directly sample photon production from individual
reactions.
In OpenMC, secondary photons are created after a nuclide has been sampled in a neutron collision. The expected
number of photons produced is
𝜎𝛾 (𝐸)
𝑛=𝑤 , (3.6.58)
𝜎𝑇 (𝐸)
where 𝑤 is the weight of the neutron, 𝜎𝛾 is the photon production cross section for the sampled nuclide, and 𝜎𝑇 is
the total cross section for the nuclide. ⌊𝑛⌋ photons are created with an additional photon produced with probability
𝑛 − ⌊𝑛⌋. Next,
∑︀ a reaction is sampled
∑︀ for each secondary photon. The probability of sampling the 𝑖-th reaction is given
by 𝜎𝛾,𝑖 (𝐸)/ 𝑗 𝜎𝛾,𝑗 (𝐸), where 𝑗 𝜎𝛾,𝑗 = 𝜎𝛾 is the total photon production cross section. The secondary angle and
energy distributions associated with the reaction are used to sample the angle and energy of the emitted photon.

3.7 Tallies
Note that the methods discussed in this section are written specifically for continuous-energy mode but equivalent apply
to the multi-group mode if the particle’s energy is replaced with the particle’s group
3.7.1 Filters and Scores
The tally capability in OpenMC takes a similar philosophy as that employed in the MC21 Monte Carlo code to give
maximum flexibility in specifying tallies while still maintaining scalability. Any tally in a Monte Carlo simulation can
be written in the following form:
∫︁ ∫︁ ∫︁
𝑋 = 𝑑r 𝑑Ω 𝑑𝐸 𝑓 (r, Ω, 𝐸) 𝜓(r, Ω, 𝐸)
⏟ ⏞ (3.7.1)
⏟ ⏞ scores
filters
A user can specify one or more filters which identify which regions of phase space should score to a given tally (the
limits of integration as shown in equation (3.7.1)) as well as the scoring function (𝑓 in equation (3.7.1)). For example,
if the desired tally was the (𝑛, 𝛾) reaction rate in a fuel pin, the filter would specify the cell which contains the fuel
pin and the scoring function would be the radiative capture macroscopic cross section. The following quantities can
be scored in OpenMC: flux, total reaction rate, scattering reaction rate, neutron production from scattering, higher
scattering moments, (𝑛, 𝑥𝑛) reaction rates, absorption reaction rate, fission reaction rate, neutron production rate from
fission, and surface currents. The following variables can be used as filters: universe, material, cell, birth cell, surface,
mesh, pre-collision energy, post-collision energy, polar angle, azimuthal angle, and the cosine of the change-in-angle
due to a scattering event.
With filters for pre- and post-collision energy and scoring functions for scattering and fission production, it is possible
to use OpenMC to generate cross sections with user-defined group structures. These multigroup cross sections can
subsequently be used in deterministic solvers such as coarse mesh finite difference (CMFD) diffusion.
3.7.2 Using Maps for Filter-Matching
Some Monte Carlo codes suffer severe performance penalties when tallying a large number of quantities. Care must
be taken to ensure that a tally system scales well with the total number of tally bins. In OpenMC, a mapping technique
is used that allows for a fast determination of what tally/bin combinations need to be scored to a given particle’s phase
space coordinates. For each discrete filter variable, a list is stored that contains the tally/bin combinations that could
be scored to for each value of the filter variable. If a particle is in cell 𝑛, the mapping would identify what tally/bin
combinations specify cell 𝑛 for the cell filter variable. In this manner, it is not necessary to check the phase space
variables against each tally. Note that this technique only applies to discrete filter variables and cannot be applied to
energy, angle, or change-in-angle bins. For these filters, it is necessary to perform a binary search on the specified
energy grid.
3.7.3 Volume-Integrated Flux and Reaction Rates
One quantity we may wish to compute during the course of a Monte Carlo simulation is the flux or a reaction rate
integrated over a finite volume. The volume may be a particular cell, a collection of cells, or the entire geometry. There
are various methods by which we can estimate reaction rates
3.7. Tallies 95
Analog Estimator
The analog estimator is the simplest type of estimator for reaction rates. The basic idea is that we simply count the
number of actual reactions that take place and use that as our estimate for the reaction rate. This can be written
mathematically as
1 ∑︁
𝑅𝑥 = 𝑤𝑖 (3.7.2)
𝑊
𝑖∈𝐴
where 𝑅𝑥 is the reaction rate for reaction 𝑥, 𝑖 denotes an index for each event, 𝐴 is the set of all events resulting in
reaction 𝑥, and 𝑊 is the total starting weight of the particles, and 𝑤𝑖 is the pre-collision weight of the particle as it
enters event 𝑖. One should note that equation (3.7.2) is volume-integrated so if we want a volume-averaged quantity,
we need to divided by the volume of the region of integration. If survival biasing is employed, the analog estimator
cannot be used for any reactions with zero neutrons in the exit channel.
Collision Estimator
While the analog estimator is conceptually very simple and easy to implement, it can suffer higher variance due to
the fact low probability events will not occur often enough to get good statistics if they are being tallied. Thus, it is
desirable to use a different estimator that allows us to score to the tally more often. One such estimator is the collision
estimator. Instead of tallying a reaction only when it happens, the idea is to make a contribution to the tally at every
collision.
We can start by writing a formula for the collision estimate of the flux. Since 𝑅 = Σ𝑡 𝜑 where 𝑅 is the total reaction
rate, Σ𝑡 is the total macroscopic cross section, and 𝜑 is the scalar flux, it stands to reason that we can estimate the flux
by taking an estimate of the total reaction rate and dividing it by the total macroscopic cross section. This gives us the
following formula:
1 ∑︁ 𝑤𝑖
𝜑= (3.7.3)
𝑊 Σ𝑡 (𝐸𝑖 )
𝑖∈𝐶
where 𝑊 is again the total starting weight of the particles, 𝐶 is the set of all events resulting in a collision with a
nucleus, and Σ𝑡 (𝐸) is the total macroscopic cross section of the target material at the incoming energy of the particle
𝐸𝑖 .
If we multiply both sides of equation (3.7.3) by the macroscopic cross section for some reaction 𝑥, then we get the
collision estimate for the reaction rate for that reaction:
1 ∑︁ 𝑤𝑖 Σ𝑥 (𝐸𝑖 )
𝑅𝑥 =
𝑊 Σ𝑡 (𝐸𝑖 ) (3.7.4)
𝑖∈𝐶
where Σ𝑥 (𝐸𝑖 ) is the macroscopic cross section for reaction 𝑥 at the incoming energy of the particle 𝐸𝑖 . In comparison
to equation (3.7.2), we see that the collision estimate will result in a tally with a larger number of events that score to
it with smaller contributions (since we have multiplied it by Σ𝑥 /Σ𝑡 ).
Track-length Estimator
One other method we can use to increase the number of events that scores to tallies is to use an estimator the scores
contributions to a tally at every track for the particle rather than every collision. This is known as a track-length
estimator, sometimes also called a path-length estimator. We first start with an expression for the volume integrated
flux, which can be written as
∫︁ ∫︁ ∫︁ ∫︁
𝑉 𝜑 = 𝑑r 𝑑𝐸 𝑑Ω 𝑑𝑡 𝜓(r, Ω, ^ 𝐸, 𝑡) (3.7.5)

where 𝑉 is the volume, 𝜓 is the angular flux, r is the position of the particle, Ω
^ is the direction of the particle, 𝐸 is the
energy of the particle, and 𝑡 is the time. By noting that 𝜓(r, Ω, 𝐸, 𝑡) = 𝑣𝑛(r, Ω,
^ ^ 𝐸, 𝑡) where 𝑛 is the angular neutron
density, we can rewrite equation (3.7.5) as
∫︁ ∫︁ ∫︁ ∫︁
𝑉 𝜑 = 𝑑r 𝑑𝐸 𝑑𝑡𝑣 𝑑Ω 𝑛(r, Ω, ^ 𝐸, 𝑡)). (3.7.6)
Using the relations 𝑁 (r, 𝐸, 𝑡) = ^ 𝐸, 𝑡) and 𝑑ℓ = 𝑣 𝑑𝑡 where 𝑑ℓ is the differential unit of track length, we
∫︀
𝑑Ω𝑛(r, Ω,
then obtain
∫︁ ∫︁ ∫︁
𝑉𝜑= 𝑑r 𝑑𝐸 𝑑ℓ𝑁 (r, 𝐸, 𝑡). (3.7.7)
Equation (3.7.7) indicates that we can use the length of a particle’s trajectory as an estimate for the flux, i.e. the
track-length estimator of the flux would be
1 ∑︁
𝜑= 𝑤𝑖 ℓ𝑖 (3.7.8)
𝑊
𝑖∈𝑇
where 𝑇 is the set of all the particle’s trajectories within the desired volume and ℓ𝑖 is the length of the 𝑖-th trajectory. In
the same vein as equation (3.7.4), the track-length estimate of a reaction rate is found by multiplying equation (3.7.8)
by a macroscopic reaction cross section:
1 ∑︁
𝑅𝑥 = 𝑤𝑖 ℓ𝑖 Σ𝑥 (𝐸𝑖 ). (3.7.9)
𝑊
𝑖∈𝑇
One important fact to take into consideration is that the use of a track-length estimator precludes us from using any filter
that requires knowledge of the particle’s state following a collision because by definition, it will not have had a collision
at every event. Thus, for tallies with outgoing-energy filters (which require the post-collision energy), scattering change-
in-angle filters, or for tallies of scattering moments (which require the scattering cosine of the change-in-angle), we
must use an analog estimator.
3.7.4 Statistics
As was discussed briefly in Introduction, any given result from a Monte Carlo calculation, colloquially known as
a “tally”, represents an estimate of the mean of some random variable of interest. This random variable typically
corresponds to some physical quantity like a reaction rate, a net current across some surface, or the neutron flux in a
region. Given that all tallies are produced by a stochastic process, there is an associated uncertainty with each value
reported. It is important to understand how the uncertainty is calculated and what it tells us about our results. To that
end, we will introduce a number of theorems and results from statistics that should shed some light on the interpretation
of uncertainties.
Law of Large Numbers
The law of large numbers is an important statistical result that tells us that the average value of the result a large
number of repeated experiments should be close to the expected value. Let 𝑋1 , 𝑋2 , . . . , 𝑋𝑛 be an infinite sequence of
independent, identically-distributed random variables with expected values 𝐸(𝑋1 ) = 𝐸(𝑋2 ) = 𝜇. One form of the
law of large numbers states that the sample mean 𝑋¯𝑛 = 𝑋1 +···+𝑋
𝑛
𝑛
converges in probability to the true mean, i.e. for
all 𝜖 > 0
¯ 𝑛 − 𝜇⃒ ≥ 𝜖 = 0.
(︀⃒ ⃒ )︀
lim 𝑃 ⃒𝑋
𝑛→∞
3.7. Tallies 97
Central Limit Theorem
The central limit theorem (CLT) is perhaps the most well-known and ubiquitous statistical theorem that has far-reaching
implications across many disciplines. The CLT is similar to the law of large numbers in that it tells us the limiting
behavior of the sample mean. Whereas the law of large numbers tells us only that the value of the sample mean will
converge to the expected value of the distribution, the CLT says that the distribution of the sample mean will converge
to a normal distribution. As we defined before, let 𝑋1 , 𝑋2 , . . . , 𝑋𝑛 be an infinite sequence of independent, identically-
distributed random variables with expected values 𝐸(𝑋𝑖 ) = 𝜇 and variances Var(𝑋𝑖 ) = 𝜎 2 < ∞. Note that we don’t
require that these random variables take on any particular distribution –√ they can be normal, log-normal, Weibull, etc.
The central limit theorem states that as 𝑛 → ∞, the random variable 𝑛(𝑋 ¯ 𝑛 − 𝜇) converges in distribution to the
standard normal distribution:
(︃ 𝑛 )︃
√ 1 ∑︁ 𝑑
𝑛 𝑋𝑖 − 𝜇 − → 𝒩 (0, 𝜎 2 ) (3.7.10)
𝑛 𝑖=1
Estimating Statistics of a Random Variable
Mean
Given independent samples drawn from a random variable, the sample mean is simply an estimate of the average value
of the random variable. In a Monte Carlo simulation, the random variable represents physical quantities that we want
tallied. If 𝑋 is the random variable with 𝑁 observations 𝑥1 , 𝑥2 , . . . , 𝑥𝑁 , then an unbiased estimator for the population
mean is the sample mean, defined as
𝑁
1 ∑︁
𝑥
¯= 𝑥𝑖 . (3.7.11)
𝑁 𝑖=1
Variance
The variance of a population indicates how spread out different members of the population are. For a Monte Carlo
simulation, the variance of a tally is a measure of how precisely we know the tally value, with a lower variance indicating
a higher precision. There are a few different estimators for the population variance. One of these is the second central
moment of the distribution also known as the biased sample variance:
𝑁
(︃ 𝑁
)︃
1 ∑︁ 2 1 ∑︁
𝑠2𝑁 = (𝑥𝑖 − 𝑥
¯) = 𝑥2 − 𝑥 ¯2 . (3.7.12)
𝑁 𝑖=1 𝑁 𝑖=1 𝑖
This estimator is biased because its expected value is actually not equal to the population variance:
𝑁 −1 2
𝐸[𝑠2𝑁 ] = 𝜎 (3.7.13)
𝑁
where 𝜎 2 is the actual population variance. As a result, this estimator should not be used in practice. Instead, one can
use Bessel’s correction to come up with an unbiased sample variance estimator:
𝑁
(︃ 𝑁 )︃
1 ∑︁ 2 1 ∑︁
2
𝑠 = (𝑥𝑖 − 𝑥¯) = 2
𝑥 − 𝑁𝑥 2
¯ . (3.7.14)
𝑁 − 1 𝑖=1 𝑁 − 1 𝑖=1 𝑖
This is the estimator normally used to calculate sample variance. The final form in equation (3.7.14) is especially
suitable for computation since we do not need to store the values at every realization of the random variable as the
simulation proceeds. Instead, we can simply keep a running sum and sum of squares of the values at each realization
of the random variable and use that to calculate the variance.

Variance of the Mean
The previous sections discussed how to estimate the mean and variance of a random variable using statistics on a finite
sample. However, we are generally not interested in the variance of the random variable itself; we are more interested
in the variance of the estimated mean. The sample mean is the result of our simulation, and the variance of the sample
mean will tell us how confident we should be in our answers.
Fortunately, it is quite easy to estimate the variance of the mean if we are able to estimate the variance of the random
variable. We start with the observation that if we have a series of uncorrelated random variables, we can write the
variance of their sum as the sum of their variances:
(︃ 𝑁 )︃ 𝑁
∑︁ ∑︁
Var 𝑋𝑖 = Var (𝑋𝑖 ) (3.7.15)
𝑖=1 𝑖=1
This result is known as the Bienaymé formula. We can use this result to determine a formula for the variance of the
sample mean. Assuming that the realizations of our random variable are again identical, independently-distributed
samples, then we have that
(︃ 𝑁
)︃ 𝑁
1 ∑︁ 1 ∑︁ 1 (︀ )︀ 𝜎 2
Var 𝑋 = Var
¯ Var (𝑋𝑖 ) = 2 𝑁 𝜎 2 = (3.7.16)
(︀ )︀
𝑋𝑖 = 2 .
𝑁 𝑖=1 𝑁 𝑖=1 𝑁 𝑁
We can combine this result with equation (3.7.14) to come up with an unbiased estimator for the variance of the sample
mean:
(︃ 𝑁
)︃
1 1 ∑︁ 2
2
𝑠𝑋¯ = 𝑥 −𝑥 2
¯ . (3.7.17)
𝑁 − 1 𝑁 𝑖=1 𝑖
At this point, an important distinction should be made between the estimator for the variance of the population and the
estimator for the variance of the mean. As the number of realizations increases, the estimated variance of the population
based on equation (3.7.14) will tend to the true population variance. On the other hand, the estimated variance of the
mean will tend to zero as the number of realizations increases. A practical interpretation of this is that the longer you
run a simulation, the better you know your results. Therefore, by running a simulation long enough, it is possible to
reduce the stochastic uncertainty to arbitrarily low levels.
Confidence Intervals
While the sample variance and standard deviation gives us some idea about the variability of the estimate of the mean of
whatever quantities we’ve tallied, it does not help us interpret how confidence we should be in the results. To quantify
the reliability of our estimates, we can use confidence intervals based on the calculated sample variance.
A 1 − 𝛼 confidence interval for a population parameter is defined as such: if we repeat the same experiment many times
and calculate the confidence interval for each experiment, then 1−𝛼 percent of the calculated intervals would encompass
the true population parameter. Let 𝑥1 , 𝑥2 , . . . , 𝑥𝑁 be samples from a set of independent, identically-distributed random
variables each with population mean 𝜇 and variance 𝜎 2 . The t-statistic is defined as
¯−𝜇
𝑥
𝑡= √ (3.7.18)
𝑠/ 𝑁
where 𝑥
¯ is the sample mean from equation (3.7.11) and 𝑠 is the standard deviation based on equation (3.7.14). If the
random variables 𝑋𝑖 are normally-distributed, then the t-statistic has a Student’s t-distribution with 𝑁 − 1 degrees of
freedom. This implies that
(︂ )︂
¯−𝜇
𝑥
𝑃 𝑟 −𝑡1−𝛼/2,𝑁 −1 ≤ √ ≤ 𝑡1−𝛼/2,𝑁 −1 = 1 − 𝛼 (3.7.19)
𝑠/ 𝑁
3.7. Tallies 99
where 𝑡1−𝛼/2,𝑁 −1 is the 1 − 𝛼/2 percentile of a t-distribution with 𝑁 − 1 degrees of freedom. Thus, the 1 − 𝛼 two
sided confidence interval for the sample mean is
𝑠
¯ ± 𝑡1−𝛼/2,𝑁 −1 √ .
𝑥 (3.7.20)
𝑁
One should be cautioned that equation (3.7.20) only applies if the underlying random variables are normally-distributed.
In general, this may not be true for a tally random variable — the central limit theorem guarantees only that the sample
mean is normally distributed, not the underlying random variable. If batching is used, then the underlying random
variable, which would then be the averages from each batch, will be normally distributed as long as the conditions of
the central limit theorem are met.
Let us now outline the method used to calculate the percentile of the Student’s t-distribution. For one or two degrees of
freedom, the percentile can be written analytically. For one degree of freedom, the t-distribution becomes a standard
Cauchy distribution whose cumulative distribution function is
1 1
𝑐(𝑥) = arctan 𝑥 + . (3.7.21)
𝜋 2
Thus, inverting the cumulative distribution function, we find the 𝑥 percentile of the standard Cauchy distribution to be
(︂ (︂ )︂)︂
1
𝑡𝑥,1 = tan 𝜋 𝑥 − . (3.7.22)
2
For two degrees of freedom, the cumulative distribution function is the second-degree polynomial
1 𝑥
𝑐(𝑥) = + √ (3.7.23)
2 2 𝑥2 + 2
Solving for 𝑥, we find the 𝑥 percentile to be

√
2 2(𝑥 − 1/2)
𝑡𝑥,2 = √︀ (3.7.24)
1 − 4(𝑥 − 1/2)2
For degrees of freedom greater than two, it is not possible to obtain an analytical formula for the inverse of the cu-
mulative distribution function. We must resort to either numerically solving for the inverse or to an approximation.
Approximations for percentiles of the t-distribution have been found with high levels of accuracy. OpenMC uses the
following approximation:
1 𝑧𝑥3 − 3𝑧𝑥 1 5𝑧𝑥5 − 56𝑧𝑥3 + 75𝑧𝑥 1 3𝑧𝑥7 − 81𝑧𝑥5 + 417𝑧𝑥3 − 315𝑧𝑥

√︂ (︂ )︂
𝑛
𝑡𝑥,𝑛 = 𝑧𝑥 + + + (3.7.25)
𝑛−2 4 𝑛−2 96 (𝑛 − 2)2 384 (𝑛 − 2)3
where 𝑧𝑥 is the 𝑥 percentile of the standard normal distribution. In order to determine an arbitrary percentile of the
standard normal distribution, we use an unpublished rational approximation. After using the rational approximation,
one iteration of Newton’s method is applied to improve the estimate of the percentile.
3.8 Eigenvalue Calculations
An eigenvalue calculation, also referred to as a criticality calculation, is a transport simulation wherein the source
of neutrons includes a fissionable material. Some common eigenvalue calculations include the simulation of nuclear
reactors, spent fuel pools, nuclear weapons, and other fissile systems. The reason they are called eigenvalue calculations
is that the transport equation becomes an eigenvalue equation if a fissionable source is present since then the source of
neutrons will depend on the flux of neutrons itself. Eigenvalue simulations using Monte Carlo methods are becoming
increasingly common with the advent of high-performance computing.
This section will explore the theory behind and implementation of eigenvalue calculations in a Monte Carlo code.

3.8.1 Method of Successive Generations
The method used to converge on the fission source distribution in an eigenvalue calculation, known as the method of
successive generations, was first introduced by [Lieberoth]. In this method, a finite number of neutron histories, 𝑁 ,
are tracked through their lifetime iteratively. If fission occurs, rather than tracking the resulting fission neutrons, the
spatial coordinates of the fission site, the sampled outgoing energy and direction of the fission neutron, and the weight
of the neutron are stored for use in the subsequent generation. In OpenMC, the array used for storing the fission site
information is called the fission bank. At the end of each fission generation, 𝑁 source sites for the next generation must
be randomly sampled from the 𝑀 fission sites that were stored to ensure that the neutron population does not grow
exponentially. The sampled source sites are stored in an array called the source bank and can be retrieved during the
subsequent generation.
It’s important to recognize that in the method of successive generations, we must start with some assumption on how
the fission source sites are distributed since the distribution is not known a priori. Typically, a user will make a guess
as to what the distribution is – this guess could be a uniform distribution over some region of the geometry or simply a
point source. Fortunately, regardless of the choice of initial source distribution, the method is guaranteed to converge
to the true source distribution. Until the source distribution converges, tallies should not be scored to since they will
otherwise include contributions from an unconverged source distribution.
The method by which the fission source iterations are parallelized can have a large impact on the achievable parallel
scaling. This topic is discussed at length in Fission Bank Algorithms.
3.8.2 Source Convergence Issues
Diagnosing Convergence with Shannon Entropy
As discussed earlier, it is necessary to converge both 𝑘𝑒𝑓 𝑓 and the source distribution before any tallies can begin.
Moreover, the convergence rate of the source distribution is in general slower than that of 𝑘𝑒𝑓 𝑓 . One should thus
examine not only the convergence of 𝑘𝑒𝑓 𝑓 but also the convergence of the source distribution in order to make decisions
on when to start active batches.
However, the representation of the source distribution makes it a bit more difficult to analyze its convergence. Since
𝑘𝑒𝑓 𝑓 is a scalar quantity, it is easy to simply look at a line plot of 𝑘𝑒𝑓 𝑓 versus the number of batches and this should give
the user some idea about whether it has converged. On the other hand, the source distribution at any given batch is a
finite set of coordinates in Euclidean space. In order to analyze the convergence, we would either need to use a method
for assessing convergence of an N-dimensional quantity or transform our set of coordinates into a scalar metric. The
latter approach has been developed considerably over the last decade and a method now commonly used in Monte Carlo
eigenvalue calculations is to use a metric called the Shannon entropy, a concept borrowed from information theory.
To compute the Shannon entropy of the source distribution, we first need to discretize the source distribution rather
than having a set of coordinates in Euclidean space. This can be done by superimposing a structured mesh over the
geometry (containing at least all fissionable materials). Then, the fraction of source sites that are present in each mesh
element is counted:
Source sites in 𝑖-th mesh element
𝑆𝑖 = (3.8.1)
Total number of source sites
The Shannon entropy is then computed as
𝑁
∑︁
𝐻=− 𝑆𝑖 log2 𝑆𝑖 (3.8.2)
𝑖=1
where 𝑁 is the number of mesh elements. With equation (3.8.2), we now have a scalar metric that we can use to assess
the convergence of the source distribution by observing line plots of the Shannon entropy versus the number of batches.
In recent years, researchers have started looking at ways of automatically assessing source convergence to relieve the
burden on the user of having to look at plots of 𝑘𝑒𝑓 𝑓 and the Shannon entropy. A number of methods have been proposed
(see e.g. [Romano], [Ueki]), but each of these is not without problems.
3.8. Eigenvalue Calculations 101

3.8.3 Uniform Fission Site Method
Generally speaking, the variance of a Monte Carlo tally will be inversely proportional to the number of events that score
to the tally. In a reactor problem, this implies that regions with low relative power density will have higher variance
that regions with high relative power density. One method to circumvent the uneven distribution of relative errors is
the uniform fission site (UFS) method introduced by [Sutton]. In this method, the portion of the problem containing
fissionable material is subdivided into a number of cells (typically using a structured mesh). Rather than producing
𝑤 𝜈Σ𝑓
𝑚=
𝑘 Σ𝑡
fission sites at each collision where 𝑤 is the weight of the neutron, 𝑘 is the previous-generation estimate of the neutron
multiplication factor, 𝜈Σ𝑓 is the neutron production cross section, and Σ𝑡 is the total cross section, in the UFS method
we produce
𝑤 𝜈Σ𝑓 𝑣𝑖
𝑚𝑈 𝐹 𝑆 =
𝑘 Σ𝑡 𝑠𝑖
fission sites at each collision where 𝑣𝑖 is the fraction of the total volume occupied by cell 𝑖 and 𝑠𝑖 is the fraction of the
fission source contained in cell 𝑖. To ensure that no bias is introduced, the weight of each fission site stored in the fission
bank is 𝑠𝑖 /𝑣𝑖 rather than unity. By ensuring that the expected number of fission sites in each mesh cell is constant, the
collision density across all cells, and hence the variance of tallies, is more uniform than it would be otherwise.
3.9 Depletion
When materials in a system are subject to irradiation over a long period of time, nuclides within the material will
transmute due to nuclear reactions as well as spontaneous radioactive decay. The time-dependent process by which
nuclides transmute under irradiation is known as depletion or burnup. To accurately analyze nuclear systems, it is often
necessary to predict how the composition of materials will change since this change results in a corresponding change
in the solution of the transport equation. The equation that governs the transmutation and decay of nuclides inside of
an irradiated environment can be written as
⎡ ⎤
∫︁ ∞
𝑑𝑁𝑖 (𝑡) ∑︁ ⎢ ⎥
= ⎢𝑓𝑗→𝑖 𝑑𝐸 𝜎𝑗 (𝐸, 𝑡)𝜑(𝐸, 𝑡) + 𝜆𝑗→𝑖 ⎥ 𝑁𝑗 (𝑡)
𝑑𝑡 𝑗
⎣
0 ⏟ ⏞ ⎦
⏟ ⏞ decay
transmutation
⏟ ⏞
Production of nuclide 𝑖 from nuclide 𝑗
⎡ ⎤
⎢∫︁ ⎥
⎢ ∞ ∑︁ ⎥
−⎢ 𝑑𝐸 𝜎𝑖 (𝐸, 𝑡)𝜑(𝐸, 𝑡) + 𝜆𝑖→𝑗 ⎥ 𝑁𝑖 (𝑡)
⎢ ⎥
⎢ 0 ⎥
⎣⏟ ⏞ 𝑗 ⎦
transmutation
⏟ ⏞
decay
⏟ ⏞
Loss of nuclide 𝑖
where 𝑁𝑖 is the density of nuclide 𝑖 at time 𝑡, 𝜎𝑖 is the transmutation cross section for nuclide 𝑖 at energy 𝐸, 𝑓𝑗→𝑖 is the
fraction of transmutation reactions in nuclide 𝑗 that produce nuclide 𝑖, and 𝜆𝑗→𝑖 is the decay constant for decay modes
in nuclide 𝑗 that produce nuclide 𝑖. Note that we have not included the spatial dependence of the flux or cross sections.
As one can see, the equation simply states that the rate of change of 𝑁𝑖 is equal to the production rate minus the loss
rate. Because the equation for nuclide 𝑖 depends on the nuclide density for possibly many other nuclides, we have a
system of first-order differential equations. To form a proper initial value problem, we also need the nuclide densities
at time 0:
𝑁𝑖 (0) = 𝑁𝑖,0 .

These equations can be written more compactly in matrix notation as
𝑑n
= A(n, 𝑡)n, n(0) = n0 (3.9.1)
𝑑𝑡
where n ∈ R𝑛 is the nuclide density vector, A(n, 𝑡) ∈ R𝑛×𝑛 is the burnup matrix containing the decay and transmu-
tation coefficients, and n0 is the initial density vector. Note that the burnup matrix depends on n because the solution
to the transport equation depends on the nuclide densities.
3.9.1 Numerical Integration
A variety of numerical methods exist for solving Eq. (3.9.1). The simplest such method, known as the “predictor”
method, is to divide the overall time interval of interest [0, 𝑡] into smaller timesteps over which it is assumed that the
burnup matrix is constant. Let 𝑡 ∈ [𝑡𝑖 , 𝑡𝑖 + ℎ] be one such timestep. Over the timestep, the solution to Eq. (3.9.1) can
be written analytically using the matrix exponential
A𝑖 = A(n𝑖 , 𝑡𝑖 )
n𝑖+1 = 𝑒A𝑖 ℎ n𝑖
where n𝑖 ≡ n(𝑡𝑖 ). The exponential of a matrix X is defined by the power series expansion
∞
∑︁ 1 𝑘
𝑒X = (X)
𝑘!
𝑘=0
where X0 = I. A series of so-called predictor-corrector methods that use multiple stages offer improved accuracy over
the predictor method. The simplest of these methods, the CE/CM algorithm, is defined as
ℎ
n𝑖+1/2 = 𝑒 2 A(n𝑖 ,𝑡𝑖 ) n𝑖
n𝑖+1 = 𝑒ℎA(n𝑖+1/2 ,𝑡𝑖+1/2 ) n𝑖
Here, the value of n at the midpoint is estimated using A evaluated at the beginning of the timestep. Then, A is
evaluated using the densities at the midpoint and used to integrate over the entire timestep.
Our aim here is not to exhaustively describe all integration methods but rather to give a few examples that elucidate
the main considerations one must take into account when choosing a method. Generally, there is a tradeoff between
the accuracy of the method and its computational expense. In the case of transport-coupled depletion, the expense is
driven almost entirely by the time to compute a transport solution, i.e., to evaluate A for a given n. Thus, the cost of
a method scales with the number of A evaluations that are performed per timestep. On the other hand, methods that
require more evaluations generally achieve higher accuracy. The predictor method only requires one evaluation and its
error converges as 𝒪(ℎ). The CE/CM method requires two evaluations and is thus twice as expensive as the predictor
method, but achieves an error of 𝒪(ℎ2 ). An exhaustive description of time integration methods and their merits can
be found in the thesis of Colin Josey.
OpenMC does not rely on a single time integration method but rather has several classes that implement different
algorithms. For example, the openmc.deplete.PredictorIntegrator class implements the predictor method, and
the openmc.deplete.CECMIntegrator class implements the CE/CM method. A full list of the integrator classes
available can be found in the documentation for the openmc.deplete module.
3.9. Depletion 103

3.9.2 Matrix Exponential
As we saw in the previous section, numerically integrating Eq. (3.9.1) requires evaluating one or more matrix expo-
nentials. OpenMC uses the Chebyshev rational approximation method (CRAM), which was introduced in a series of
papers by Pusa (1, 2), to evaluate matrix exponentials. In particular, OpenMC utilizes an incomplete partial fraction
(IPF) form of CRAM that provides a good balance of numerical stability and efficiency. In this representation the
matrix exponential is approximated as
𝑘/2 (︁ (︁ )︁)︁
−1
∏︁
𝑒A𝑡 ≈ 𝛼0 I + 2Re 𝛼 ̃︀ℓ (A𝑡 − 𝜃ℓ I)
ℓ=1
where 𝑘 is the order of the approximation and 𝛼0 , 𝛼

̃︀ℓ , and 𝜃ℓ are coefficients that have been tabulated for orders up to
𝑘 = 48. Rather than computing the full approximation and then multiplying it by a vector, the following algorithm is
used to incrementally apply the terms within the product (note that the original description of the algorithm presented
by Pusa contains a typo):
1. n ← n0
2. For ℓ = 1, 2, . . . , 𝑘/2
• n ← n + 2Re(̃︀
𝛼ℓ (A𝑡 − 𝜃ℓ )−1 )n
3. n ← 𝛼0 n
The 𝑘th order approximation for CRAM requires solving 𝑘/2 sparse linear systems. OpenMC relies on functionality
from scipy.sparse.linalg for solving the linear systems.
3.9.3 Data Considerations
In principle, solving Eq. (3.9.1) using CRAM is fairly simple: just construct the burnup matrix at various times and
solve a set of sparse linear systems. However, constructing the burnup matrix itself involves not only solving the
transport equation to estimate transmutation reaction rates (in the case of transport-coupled depletion) or to obtain
microscopic cross sections (in the case of transport-independent depletion), but also a series of choices about what
data to include. In OpenMC, the burnup matrix is constructed based on data inside of a depletion chain file, which
includes fundamental data gathered from ENDF incident neutron, decay, and fission product yield sublibraries. For
each nuclide, this file includes:
• What transmutation reactions are possible, their Q values, and their products;
• If a nuclide is not stable, what decay modes are possible, their branching ratios, and their products; and
• If a nuclide is fissionable, the fission products yields at any number of incident neutron energies.
Transmutation Reactions
In transport-coupled depletion, OpenMC will setup tallies in a problem based on what transmutation reactions are
available in a depletion chain file, so any arbitrary number of transmutation reactions can be tracked. In transport-
independent depletion, OpenMC will calculate reaction rates for every reaction that is present in both the available
cross sections and the depletion chain file. The pregenerated chain files that are available on https://openmc.org include
the following transmutation reactions: fission, (n,𝛾), (n,2n), (n,3n), (n,4n), (n,p), and (n,𝛼).

Capture Branching Ratios
Some (n,𝛾) reactions may result in a product being in either the ground or a metastable state. The most well-known
example is capture in Am241, which can produce either Am242 or Am242m. Because the metastable state of Am242m
has a significantly longer half-life than the ground state, it is important to accurately model the branching of the capture
reaction in Am241. This is complicated by the fact that the branching ratio may depend on the incident neutron energy
causing capture.
OpenMC’s transport solver does not currently allow energy-dependent capture branching ratios. However, the depletion
chain file does allow a transmutation reaction to be listed multiple times with different branching ratios resulting in
different products. Spectrum-averaged capture branching ratios have been computed in LWR and SFR spectra and are
available at https://openmc.org/depletion-chains.
Fission Product Yields
Fission product yields (FPY) are also energy-dependent in general. ENDF fission product yield sublibraries typically
include yields tabulated at 2 or 3 energies. It is an open question as to what the best way to handle this energy dependence
is. OpenMC includes three methods for treating the energy dependence of FPY:
1. Use FPY data corresponding to a specified energy. This is used by default in both transport-coupled and transport-
independent depletion.
2. Tally fission rates above and below a specified cutoff energy. Assume that all fissions below the cutoff energy
correspond to thermal FPY data and all fission above the cutoff energy correspond to fast FPY data. Only
applicable to transport-coupled depletion.
3. Compute the average energy at which fission events occur and use an effective FPY by linearly interpolating
between FPY provided at neighboring energies. Only applicable to transport-coupled depletion.
The method for transport-coupled depletion can be selected through the fission_yield_mode argument to the
openmc.deplete.CoupledOperator constructor.
Power Normalization
In transport-coupled depletion, the reaction rates provided OpenMC are given in units of reactions per source particle.
For depletion, it is necessary to compute an absolute reaction rate in reactions per second. To do so, the reaction rates
are normalized based on a specified power. A complete description of how this normalization can be performed is
described in Normalization of Tally Results. Here, we simply note that the main depletion class, openmc.deplete.
CoupledOperator, allows the user to choose one of two methods for estimating the heating rate, including:
1. Using fixed Q values from a depletion chain file (useful for comparisons to other codes that use fixed Q values),
or
2. Using the heating or heating-local scores to obtain an nuclide- and energy-dependent estimate of the true
heating rate.
The method for normalization can be chosen through the normalization_mode argument to the openmc.deplete.
CoupledOperator class.
3.9. Depletion 105

3.10 Heating and Energy Deposition
As particles traverse a problem, some portion of their energy is deposited at collision sites. This energy is deposited
when charged particles, including electrons and recoil nuclei, undergo electromagnetic interactions with surrounding
electrons and ions. The information describing how much energy is deposited for a specific reaction is referred to as
“heating numbers” and can be computed using a program like NJOY with the heatr module.
The heating rate is the product of reaction-specific coefficients and a reaction cross section
∑︁ ∑︁
𝐻(𝐸) = 𝜑(𝐸) 𝜌𝑖 𝑘𝑖,𝑟 (𝐸),
𝑖 𝑟
and has units energy per time, typically eV/s. Here, 𝑘𝑖,𝑟 are the KERMA (Kinetic Energy Release in Materials)
[Mack97] coefficients for reaction 𝑟 of isotope 𝑖. The KERMA coefficients have units of energy × cross-section (e.g.,
eV-barn) and can be used much like a reaction cross section for the purpose of tallying energy deposition.
KERMA coefficients can be computed using the energy-balance method with a nuclear data processing code like NJOY,
which performs the following iteration over all reactions 𝑟 for all isotopes 𝑖 requested
¯𝑖,𝑟,𝑛 − 𝐸¯𝑖,𝑟,𝛾 𝜎𝑖,𝑟 (𝐸),

(︀ )︀
𝑘𝑖,𝑟 (𝐸) = 𝐸 + 𝑄𝑖,𝑟 − 𝐸
removing the energy of neutral particles (neutrons and photons) that are transported away from the reaction site 𝐸,
¯ and
the reaction 𝑄 value.
3.10.1 Fission
During a fission event, there are potentially many secondary particles, and all must be considered. The total energy
released in a fission event is typically broken up into the following categories:
• 𝐸𝑓 𝑟 - kinetic energy of fission fragments
• 𝐸𝑛,𝑝 - energy of prompt fission neutrons
• 𝐸𝑛,𝑑 - energy of delayed fission neutrons
• 𝐸𝛾,𝑝 - energy of prompt fission photons
• 𝐸𝛾,𝑑 - energy of delayed fission photons
• 𝐸𝛽 - energy of released 𝛽 particles
• 𝐸𝜈 - energy of neutrinos
These components are defined in MF=1, MT=458 data in a standard ENDF-6 formatted file. All these quantities may
depend upon incident neutron energy, but this dependence is not shown to make the following demonstrations cleaner.
As neutrinos scarcely interact with matter, the recoverable energy from fission is defined as
𝐸𝑟 ≡ 𝐸𝑓 𝑟 + 𝐸𝑛,𝑝 + 𝐸𝑛,𝑑 + 𝐸𝛾,𝑝 + 𝐸𝛾,𝑑 + 𝐸𝛽
Furthermore, the energy of the secondary neutrons and photons is given as 𝐸𝑛,𝑝 and 𝐸𝛾,𝑝 , respectively.
NJOY computes the fission KERMA coefficient using this energy-balance method to be
¯
[︀ ]︀
𝑘𝑖,𝑓 (𝐸) = 𝐸 + 𝑄(𝐸) − 𝐸(𝐸) 𝜎𝑖,𝑓 (𝐸) = [𝐸𝑓 𝑟 + 𝐸𝛾,𝑝 ] 𝜎𝑖,𝑗 (𝐸)
Note: The energy from delayed neutrons and photons and beta particles is intentionally left out from the NJOY
calculations.

3.10.2 OpenMC Implementation
For fissile isotopes, OpenMC makes modifications to the heating reaction to include all relevant components of fis-
sion energy release. These modifications are made to the total heating reaction, MT=301. Breaking the total heating
KERMA into a fission and non-fission section, one can write
𝑘𝑖 (𝐸) = 𝑘𝑖,𝑛𝑓 (𝐸) + [𝐸𝑓 𝑟 (𝐸) + 𝐸𝛾,𝑝 ] 𝜎𝑖,𝑓 (𝐸)
OpenMC seeks to modify the total heating data to include energy from 𝛽 particles and, conditionally, delayed photons.
This conditional inclusion depends on the simulation mode: neutron transport, or coupled neutron-photon transport.
The heating due to fission is removed using MT=318 data, and then re-built using the desired components of fission
energy release from MF=1,MT=458 data.
Neutron Transport
For this case, OpenMC instructs heatr to produce heating coefficients assuming that energy from photons, 𝐸𝛾,𝑝 and
𝐸𝛾,𝑑 , is deposited at the fission site. Let 𝑁 901 represent the total heating number returned from this heatr run with
𝑁 918 reflecting fission heating computed from NJOY. 𝑀 901 represent the following modification
𝑀 901𝑖 (𝐸) ≡ 𝑁 901𝑖 (𝐸) − 𝑁 918𝑖 (𝐸) + [𝐸𝑖,𝑓 𝑟 + 𝐸𝑖,𝛽 + 𝐸𝑖,𝛾,𝑝 + 𝐸𝑖,𝛾,𝑑 ] 𝜎𝑖,𝑓 (𝐸).
This modified heating data is stored as the MT=901 reaction and will be scored if heating-local is included in
openmc.Tally.scores.
Coupled neutron-photon transport
Here, OpenMC instructs heatr to assume that energy from photons is not deposited locally. However, the definitions
provided in the NJOY manual indicate that, regardless of this mode, the prompt photon energy is still included in 𝑘𝑖,𝑓 ,
and therefore must be manually removed. Let 𝑁 301 represent the total heating number returned from this heatr run
and 𝑀 301 be
𝑀 301𝑖 (𝐸) ≡ 𝑁 301𝑖 (𝐸) − 𝑁 318𝑖 (𝐸) + [𝐸𝑖,𝑓 𝑟 (𝐸) + 𝐸𝑖,𝛽 (𝐸)] 𝜎𝑖,𝑓 (𝐸).
This modified heating data is stored as the MT=301 reaction and will be scored if heating is included in openmc.
Tally.scores.
3.10.3 References
3.11 Parallelization
Due to the computationally-intensive nature of Monte Carlo methods, there has been an ever-present interest in par-
allelizing such simulations. Even in the first paper on the Monte Carlo method, John Metropolis and Stanislaw Ulam
recognized that solving the Boltzmann equation with the Monte Carlo method could be done in parallel very easily
whereas the deterministic counterparts for solving the Boltzmann equation did not offer such a natural means of par-
allelism. With the introduction of vector computers in the early 1970s, general-purpose parallel computing became a
reality. In 1972, Troubetzkoy et al. designed a Monte Carlo code to be run on the first vector computer, the ILLIAC-IV
[Troubetzkoy]. The general principles from that work were later refined and extended greatly through the work of
Forrest Brown in the 1980s. However, as Brown’s work shows, the single-instruction multiple-data (SIMD) parallel
model inherent to vector processing does not lend itself to the parallelism on particles in Monte Carlo simulations.
Troubetzkoy et al. recognized this, remarking that “the order and the nature of these physical events have little, if any,
correlation from history to history,” and thus following independent particle histories simultaneously using a SIMD
model is difficult.
3.11. Parallelization 107

The difficulties with vector processing of Monte Carlo codes led to the adoption of the single program multiple data
(SPMD) technique for parallelization. In this model, each different process tracks a particle independently of other
processes, and between fission source generations the processes communicate data through a message-passing interface.
This means of parallelism was enabled by the introduction of message-passing standards in the late 1980s and early
1990s such as PVM and MPI. The SPMD model proved much easier to use in practice and took advantage of the
inherent parallelism on particles rather than instruction-level parallelism. As a result, it has since become ubiquitous
for Monte Carlo simulations of transport phenomena.
Thanks to the particle-level parallelism using SPMD techniques, extremely high parallel efficiencies could be achieved
in Monte Carlo codes. Until the last decade, even the most demanding problems did not require transmitting large
amounts of data between processors, and thus the total amount of time spent on communication was not significant
compared to the amount of time spent on computation. However, today’s computing power has created a demand
for increasingly large and complex problems, requiring a greater number of particles to obtain decent statistics (and
convergence in the case of criticality calculations). This results in a correspondingly higher amount of communication,
potentially degrading the parallel efficiency. Thus, while Monte Carlo simulations may seem embarrassingly parallel,
obtaining good parallel scaling with large numbers of processors can be quite difficult to achieve in practice.
3.11.1 Fission Bank Algorithms
Master-Slave Algorithm
Monte Carlo particle transport codes commonly implement a SPMD model by having one master process that controls
the scheduling of work and the remaining processes wait to receive work from the master, process the work, and then
send their results to the master at the end of the simulation (or a source iteration in the case of an eigenvalue calculation).
This idea is illustrated in Communication pattern in master-slave algorithm..
Fig. 6: Communication pattern in master-slave algorithm.
Eigenvalue calculations are slightly more difficult to parallelize than fixed source calculations since it is necessary to
converge on the fission source distribution and eigenvalue before tallying. In the Method of Successive Generations,
to ensure that the results are reproducible, one must guarantee that the process by which fission sites are randomly
sampled does not depend on the number of processors. What is typically done is the following:
1. Each compute node sends its fission bank sites to a master process;
2. The master process sorts or orders the fission sites based on a unique identifier;
3. The master process samples 𝑁 fission sites from the ordered array of 𝑀 sites; and
4. The master process broadcasts all the fission sites to the compute nodes.
The first and last steps of this process are the major sources of communication overhead between cycles. Since the
master process must receive 𝑀 fission sites from the compute nodes, the first step is necessarily serial. This step

can be completed in 𝑂(𝑀 ) time. The broadcast step can benefit from parallelization through a tree-based algorithm.
Despite this, the communication overhead is still considerable.
To see why this is the case, it is instructive to look at a hypothetical example. Suppose that a calculation is run with
𝑁 = 10, 000, 000 neutrons across 64 compute nodes. On average, 𝑀 = 10, 000, 000 fission sites will be produced. If
the data for each fission site consists of a spatial location (three 8 byte real numbers) and a unique identifier (one 4 byte
integer), the memory required per site is 28 bytes. To broadcast 10,000,000 source sites to 64 nodes will thus require
transferring 17.92 GB of data. Since each compute node does not need to keep every source site in memory, one could
modify the algorithm from a broadcast to a scatter. However, for practical reasons (e.g. work self-scheduling), this is
normally not done in production Monte Carlo codes.
Nearest Neighbors Algorithm
To reduce the amount of communication required in a fission bank synchronization algorithm, it is desirable to move
away from the typical master-slave algorithm to an algorithm whereby the compute nodes communicate with one
another only as needed. This concept is illustrated in Communication pattern in nearest neighbor algorithm..
Fig. 7: Communication pattern in nearest neighbor algorithm.
Since the source sites for each cycle are sampled from the fission sites banked from the previous cycle, it is a common
occurrence for a fission site to be banked on one compute node and sent back to the master only to get sent back to
the same compute node as a source site. As a result, much of the communication inherent in the algorithm described
previously is entirely unnecessary. By keeping the fission sites local, having each compute node sample fission sites,
and sending sites between nodes only as needed, one can cut down on most of the communication. One algorithm to
achieve this is as follows:
1. An exclusive scan is performed on the number of sites banked, and the total number of fission bank sites
is broadcasted to all compute nodes. By picturing the fission bank as one large array distributed across
multiple nodes, one can see that this step enables each compute node to determine the starting index of
fission bank sites in this array. Let us call the starting and ending indices on the 𝑖-th node 𝑎𝑖 and 𝑏𝑖 ,
respectively;
2. Each compute node samples sites at random from the fission bank using the same starting seed. A
separate array on each compute node is created that consists of sites that were sampled local to that node,
i.e. if the index of the sampled site is between 𝑎𝑖 and 𝑏𝑖 , it is set aside;
3. If any node sampled more than 𝑁/𝑝 fission sites where 𝑝 is the number of compute nodes, the extra
sites are put in a separate array and sent to all other compute nodes. This can be done efficiently using the
allgather collective operation;
4. The extra sites are divided among those compute nodes that sampled fewer than 𝑁/𝑝 fission sites.
However, even this algorithm exhibits more communication than necessary since the allgather will send fission bank
sites to nodes that don’t necessarily need any extra sites.
One alternative is to replace the allgather with a series of sends. If 𝑎𝑖 is less than 𝑖𝑁/𝑝, then send 𝑖𝑁/𝑝 − 𝑎𝑖 sites to
the left adjacent node. Similarly, if 𝑎𝑖 is greater than 𝑖𝑁/𝑝, then receive 𝑎𝑖 − 𝑖𝑁/𝑝 from the left adjacent node. This
idea is applied to the fission bank sites at the end of each node’s array as well. If 𝑏𝑖 is less than (𝑖 + 1)𝑁/𝑝, then receive
(𝑖 + 1)𝑁/𝑝 − 𝑏𝑖 sites from the right adjacent node. If 𝑏𝑖 is greater than (𝑖 + 1)𝑁/𝑝, then send 𝑏𝑖 − (𝑖 + 1)𝑁/𝑝 sites
to the right adjacent node. Thus, each compute node sends/receives only two messages under normal circumstances.
The following example illustrates how this algorithm works. Let us suppose we are simulating 𝑁 = 1000 neutrons
across four compute nodes. For this example, it is instructive to look at the state of the fission bank and source bank at

several points in the algorithm:

1. The beginning of a cycle where each node has 𝑁/𝑝 source sites;
2. The end of a cycle where each node has accumulated fission sites;
3. After sampling, where each node has some amount of source sites usually not equal to 𝑁/𝑝;
4. After redistribution, each node again has 𝑁/𝑝 source sites for the next cycle;
At the end of each cycle, each compute node needs 250 fission bank sites to continue on the next cycle. Let us suppose
that 𝑝0 produces 270 fission banks sites, 𝑝1 produces 230, 𝑝2 produces 290, and 𝑝3 produces 250. After each node
samples from its fission bank sites, let’s assume that 𝑝0 has 260 source sites, 𝑝1 has 215, 𝑝2 has 280, and 𝑝3 has 245.
Note that the total number of sampled sites is 1000 as needed. For each node to have the same number of source sites,
𝑝0 needs to send its right-most 10 sites to 𝑝1 , and 𝑝2 needs to send its left-most 25 sites to 𝑝1 and its right-most 5
sites to 𝑝3 . A schematic of this example is shown in Example of nearest neighbor algorithm.. The data local to each
node is given a different hatching, and the cross-hatched regions represent source sites that are communicated between
adjacent nodes.
Cost of Master-Slave Algorithm
While the prior considerations may make it readily apparent that the novel algorithm should outperform the traditional
algorithm, it is instructive to look at the total communication cost of the novel algorithm relative to the traditional
algorithm. This is especially so because the novel algorithm does not have a constant communication cost due to
stochastic fluctuations. Let us begin by looking at the cost of communication in the traditional algorithm
As discussed earlier, the traditional algorithm is composed of a series of sends and typically a broadcast. To estimate
the communication cost of the algorithm, we can apply a simple model that captures the essential features. In this
model, we assume that the time that it takes to send a message between two nodes is given by 𝛼 + (𝑠𝑁 )𝛽, where 𝛼
is the time it takes to initiate the communication (commonly called the latency), 𝛽 is the transfer time per unit of data
(commonly called the bandwidth), 𝑁 is the number of fission sites, and 𝑠 is the size in bytes of each fission site.
The first step of the traditional algorithm is to send 𝑝 messages to the master node, each of size 𝑠𝑁/𝑝. Thus, the total
time to send these messages is
𝑡send = 𝑝𝛼 + 𝑠𝑁 𝛽. (3.11.1)
Generally, the best parallel performance is achieved in a weak scaling scheme where the total number of histories is
proportional to the number of processors. However, we see that when 𝑁 is proportional to 𝑝, the time to send these
messages increases proportionally with 𝑝.
Estimating the time of the broadcast is complicated by the fact that different MPI implementations may use different
algorithms to perform collective communications. Worse yet, a single implementation may use a different algorithm
depending on how many nodes are communicating and the size of the message. Using multiple algorithms allows one
to minimize latency for small messages and minimize bandwidth for long messages.
We will focus here on the implementation of broadcast in the MPICH implementation. For short messages, MPICH
uses a binomial tree algorithm. In this algorithm, the root process sends the data to one node in the first step, and then
in the subsequent, both the root and the other node can send the data to other nodes. Thus, it takes a total of ⌈log2 𝑝⌉
steps to complete the communication. The time to complete the communication is
𝑡short = ⌈log2 𝑝⌉ (𝛼 + 𝑠𝑁 𝛽) . (3.11.2)
This algorithm works well for short messages since the latency term scales logarithmically with the number of nodes.
However, for long messages, an algorithm that has lower bandwidth has been proposed by Barnett and implemented in
MPICH. Rather than using a binomial tree, the broadcast is divided into a scatter and an allgather. The time to complete

Fig. 8: Example of nearest neighbor algorithm.

the scatter is :math:` log_2 p : alpha + frac{p-1}{p} Nbeta` using a binomial tree algorithm. The allgather is performed
using a ring algorithm that completes in 𝑝 − 1)𝛼 + 𝑝−1 𝑝 𝑁 𝛽. Thus, together the time to complete the broadcast is
𝑝−1
𝑡long = (log2 𝑝 + 𝑝 − 1) 𝛼 + 2 𝑠𝑁 𝛽. (3.11.3)
𝑝
The fission bank data will generally exceed the threshold for switching from short to long messages (typically 8 kilo-
bytes), and thus we will use the equation for long messages. Adding equations (3.11.1) and (3.11.3), the total cost of
the series of sends and the broadcast is
3𝑝 − 2
𝑡old = (log2 𝑝 + 2𝑝 − 1) 𝛼 + 𝑠𝑁 𝛽. (3.11.4)
𝑝
Cost of Nearest Neighbor Algorithm
With the communication cost of the traditional fission bank algorithm quantified, we now proceed to discuss the com-
munication cost of the proposed algorithm. Comparing the cost of communication of this algorithm with the traditional
algorithm is not trivial due to fact that the cost will be a function of how many fission sites are sampled on each node. If
each node samples exactly 𝑁/𝑝 sites, there will not be communication between nodes at all. However, if any one node
samples more or less than 𝑁/𝑝 sites, the deviation will result in communication between logically adjacent nodes. To
determine the expected deviation, one can analyze the process based on the fundamentals of the Monte Carlo process.
The steady-state neutron transport equation for a multiplying medium can be written in the form of an eigenvalue
problem,
∫︁
1
𝑆(r) = 𝐹 (r′ → r)𝑆(r′ ) 𝑑r, (3.11.5)
𝑘
where r is the spatial coordinates of the neutron, 𝑆(r) is the source distribution defined as the expected number of
neutrons born from fission per unit phase-space volume at r, 𝐹 (r′ → r) is the expected number of neutrons born from
fission per unit phase space volume at r caused by a neutron at r, and 𝑘 is the eigenvalue. The fundamental eigenvalue
of equation (3.11.5) is known as 𝑘𝑒𝑓 𝑓 , but for simplicity we will simply refer to it as 𝑘.
In a Monte Carlo criticality simulation, the power iteration method is applied iteratively to obtain stochastic realizations
of the source distribution and estimates of the 𝑘-eigenvalue. Let us define 𝑆ˆ(𝑚) to be the realization of the source
distribution at cycle 𝑚 and 𝜖ˆ(𝑚) be the noise arising from the stochastic nature of the tracking process. We can write
the stochastic realization in terms of the fundamental source distribution and the noise component as (see Brissenden
and Garlick):
√
𝑆ˆ(𝑚) (r) = 𝑁 𝑆(r) + 𝑁 𝜖ˆ(𝑚) (r), (3.11.6)
where 𝑁 is the number of particle histories per cycle. Without loss of generality, we shall drop the superscript notation
indicating the cycle as it is understood that the stochastic realization is at a particular cycle. The expected value of the
stochastic source distribution is simply
[︁ ]︁
ˆ
𝐸 𝑆(r) = 𝑁 𝑆(r) (3.11.7)
since 𝐸 [ˆ𝜖(r)] = 0. The noise in the source distribution is due only to 𝜖ˆ(r) and thus the variance of the source distribu-
tion will be
[︁ ]︁
Var 𝑆(r)
ˆ = 𝑁 Var [ˆ
𝜖(r)] . (3.11.8)
Lastly, the stochastic and true eigenvalues can be written as integrals over all phase space of the stochastic and true
source distributions, respectively, as
∫︁ ∫︁
ˆ 1
𝑘= 𝑆(r) 𝑑r and 𝑘 = 𝑆(r) 𝑑r,
ˆ (3.11.9)
𝑁

noting that 𝑆(r) is 𝑂(1). One should note that the expected value 𝑘 calculated by Monte Carlo power iteration (i.e.
the method of successive generations) will be biased from the true fundamental eigenvalue of equation (3.11.5) by
𝑂(1/𝑁 ) (see Brissenden and Garlick), but we will assume henceforth that the number of particle histories per cycle is
sufficiently large to neglect this bias.
With this formalism, we now have a framework within which we can determine the properties of the distribution of
expected number of fission sites. The explicit form of the source distribution can be written as
𝑀
∑︁
ˆ
𝑆(r) = 𝑤𝑖 𝛿(r − r𝑖 ) (3.11.10)
𝑖=1
where r𝑖 is the spatial location of the 𝑖-th fission site, 𝑤𝑖 is the statistical weight of the fission site at r𝑖 , and 𝑀 is
the total number of fission sites. It is clear that the total weight of the fission sites is simply the integral of the source
distribution. Integrating equation (3.11.6) over all space, we obtain
∫︁ ∫︁ √ ∫︁
ˆ
𝑆(r) 𝑑r = 𝑁 𝑆(r) 𝑑r + 𝑁 𝜖ˆ(r) 𝑑r. (3.11.11)
Substituting the expressions for the stochastic and true eigenvalues from equation (3.11.9), we can relate the stochastic
eigenvalue to the integral of the noise component of the source distribution as
√ ∫︁
ˆ
𝑁 𝑘 = 𝑁 𝑘 + 𝑁 𝜖ˆ(r) 𝑑r. (3.11.12)
Since the expected value of 𝜖ˆ is zero, the expected value of its integral will also be zero. We thus see that the variance
of the integral of the source distribution, i.e. the variance of the total weight of fission sites produced, is directly
proportional to the variance of the integral of the noise component. Let us call this term 𝜎 2 for simplicity:
[︂∫︁ ]︂
Var ˆ
𝑆(r) = 𝑁 𝜎2 . (3.11.13)
The actual value of 𝜎 2 will depend on the physical nature of the problem, whether variance reduction techniques are
employed, etc. For instance, one could surmise that for a highly scattering problem, 𝜎 2 would be smaller than for a
highly absorbing problem since more collisions will lead to a more precise estimate of the source distribution. Similarly,
using implicit capture should in theory reduce the value of 𝜎 2 .
Let us now consider the case where the 𝑁 total histories are divided up evenly across 𝑝 compute nodes. Since each
node simulates 𝑁/𝑝 histories, we can write the source distribution as
√︃
𝑁 𝑁
𝑆ˆ𝑖 (r) = 𝑆(r) + 𝜖ˆ𝑖 (r) for 𝑖 = 1, . . . , 𝑝 (3.11.14)
𝑝 𝑝
Integrating over all space and simplifying, we can obtain an expression for the eigenvalue on the 𝑖-th node:
√︂ ∫︁
𝑝
ˆ
𝑘𝑖 = 𝑘 + 𝜖ˆ𝑖 (r) 𝑑r. (3.11.15)
𝑁
It is easy to show from this expression that the stochastic realization of the global eigenvalue is merely the average of
these local eigenvalues:
𝑝
1 ∑︁ ˆ
𝑘ˆ = 𝑘𝑖 . (3.11.16)
𝑝 𝑖=1
As was mentioned earlier, at the end of each cycle one must sample 𝑁 sites from the 𝑀 sites that were created. Thus,
the source for the next cycle can be seen as the fission source from the current cycle divided by the stochastic realization
of the eigenvalue since it is clear from equation (3.11.9) that 𝑘ˆ = 𝑀/𝑁 . Similarly, the number of sites sampled on
each compute node that will be used for the next cycle is
𝑁 𝑘ˆ𝑖
∫︁
1
𝑀𝑖 = 𝑆ˆ𝑖 (r) 𝑑r = . (3.11.17)
𝑘ˆ 𝑝 𝑘ˆ

While we know conceptually that each compute node will under normal circumstances send two messages, many of
these messages will overlap. Rather than trying to determine the actual communication cost, we will instead attempt
to determine the maximum amount of data being communicated from one node to another. At any given cycle, the
number of fission sites that the 𝑗-th compute node will send or receive (Λ𝑗 ) is
⃒ 𝑗 ⃒
⃒∑︁ 𝑗𝑁 ⃒⃒
Λ𝑗 = ⃒ 𝑀𝑖 − ⃒. (3.11.18)
⃒
⃒
𝑖=1
𝑝 ⃒
Noting that 𝑗𝑁/𝑝 is the expected value of the summation, we can write the expected value of Λ𝑗 as the mean absolute
deviation of the summation:
[︃⃒ 𝑗 ⃒]︃ [︃ 𝑗 ]︃
⃒∑︁ 𝑗𝑁 ⃒⃒ ∑︁
𝐸 [Λ𝑗 ] = 𝐸 ⃒ 𝑀𝑖 − ⃒ = MD 𝑀𝑖 (3.11.19)
⃒
⃒
𝑖=1
𝑝 ⃒ 𝑖=1
where MD indicates the mean absolute deviation of a random variable. The mean absolute deviation is an alternative
measure of variability.
In order to ascertain any information about the mean deviation of 𝑀𝑖 , we need to know the nature of its distribution.
Thus far, we have said nothing of the distributions of the random variables in question. The total number of fission
sites resulting from the tracking of 𝑁 neutrons can be shown to be normally distributed via the Central Limit Theorem
(provided that 𝑁 is sufficiently large) since the fission sites∫︀resulting from each neutron are “sampled” from indepen-
dent, identically-distributed random variables. Thus, 𝑘ˆ and 𝑆(r)𝑑r
ˆ will be normally distributed as will the individual
estimates of these on each compute node.
Next, we need to know what the distribution of 𝑀𝑖 in equation (3.11.17) is or, equivalently, how 𝑘ˆ𝑖 /𝑘ˆ is distributed.
The distribution of a ratio of random variables is not easy to calculate analytically, and it is not guaranteed that the
ratio distribution is normal if the numerator and denominator are normally distributed. For example, if 𝑋 is a standard
normal distribution and 𝑌 is also standard normal distribution, then the ratio 𝑋/𝑌 has the standard Cauchy distribution.
The reader should be reminded that the Cauchy distribution has no defined mean or variance. That being said, Geary
has shown that, for the case of two normal distributions, if the denominator is unlikely to assume values less than zero,
then the ratio distribution is indeed approximately normal. In our case, 𝑘ˆ absolutely cannot assume a value less than
zero, so we can be reasonably assured that the distribution of 𝑀𝑖 will be normal.
For a normal distribution with mean 𝜇 and distribution function 𝑓 (𝑥), it can be shown that
∫︁ ∞ √︃ ∫︁
2 ∞
𝑓 (𝑥) |𝑥 − 𝜇| 𝑑𝑥 =
2
𝑓 (𝑥) (𝑥 − 𝜇) 𝑑𝑥 (3.11.20)
−∞ 𝜋 −∞
and thus the mean absolute deviation is 2/𝜋 times the standard deviation. Therefore, to evaluate the mean absolute
√︀
deviation of 𝑀𝑖 , we need to first determine its variance. Substituting equation (3.11.16) into equation (3.11.17), we
can rewrite 𝑀𝑖 solely in terms of 𝑘ˆ1 , . . . , 𝑘ˆ𝑝 :
𝑁 𝑘ˆ𝑖
𝑀𝑖 = .
𝑝 (3.11.21)
𝑘ˆ𝑗
∑︀
𝑗=1
Since we know the variance of 𝑘ˆ𝑖 , we can use the error propagation law to determine the variance of 𝑀𝑖 :
𝑝
(︃ )︃2 𝑝
(︃ )︃ (︂ )︂
∑︁ 𝜕𝑀𝑖 [︁ ]︁ ∑︁ ∑︁
ˆ 𝜕𝑀𝑖 𝜕𝑀𝑖 [︁ ]︁
Var [𝑀𝑖 ] = Var 𝑘𝑗 + Cov 𝑘ˆ𝑗 , 𝑘ˆ𝑚 (3.11.22)
𝑗=1 𝜕 𝑘ˆ𝑗 𝑗̸=𝑚 𝑚=1
𝜕 𝑘ˆ𝑗 𝜕 𝑘ˆ𝑚
where the partial derivatives are evaluated at 𝑘ˆ𝑗 = 𝑘. Since 𝑘ˆ𝑗 and 𝑘ˆ𝑚 are independent if 𝑗 ̸= 𝑚, their covariance is
zero and thus the second term cancels out. Evaluating the partial derivatives, we obtain
(︂ )︂2 2 ∑︁ (︂ )︂2 2
𝑁 (𝑝 − 1) 𝑝𝜎 −𝑁 𝑝𝜎 𝑁 (𝑝 − 1) 2
Var [𝑀𝑖 ] = 2
+ 2
= 𝜎 . (3.11.23)
𝑘𝑝 𝑁 𝑘𝑝 𝑁 𝑘 2 𝑝2
𝑗̸=𝑖

∑︀𝑗
Through a similar analysis, one can show that the variance of 𝑖=1 𝑀𝑖 is
[︃ 𝑗 ]︃
∑︁ 𝑁 𝑗(𝑝 − 𝑗) 2
Var 𝑀𝑖 = 𝜎 (3.11.24)
𝑖=1
𝑘 2 𝑝2
∑︀𝑗
Thus, the expected amount of communication on node 𝑗, i.e. the mean absolute deviation of 𝑖=1 𝑀𝑖 is proportional
to
√︃
2𝑁 𝑗(𝑝 − 𝑗)𝜎 2
𝐸 [Λ𝑗 ] = . (3.11.25)
𝜋𝑘 2 𝑝2
This formula has all the properties that one would expect based on intuition:
1. As the number of histories increases, the communication cost on each node increases as well;
2. If 𝑝 = 1, i.e. if the problem is run on only one compute node, the variance will be zero. This reflects
the fact that exactly 𝑁 sites will be sampled if there is only one node.
3. For 𝑗 = 𝑝, the variance will be zero. Again, this says that when you sum the number of sites from each
node, you will get exactly 𝑁 sites.
We can determine the node that has the highest communication cost by differentiating equation (3.11.25) with respect
to 𝑗, setting it equal to zero, and solving for 𝑗. Doing so yields 𝑗max = 𝑝/2. Interestingly, substituting 𝑗 = 𝑝/2 in
equation (3.11.25) shows us that the maximum communication cost is actually independent of the number of nodes:
√︂
𝑁 𝜎2 (3.11.26)
𝐸 [Λ𝑗max ] = .
2𝜋𝑘 2
3.12 Nonlinear Diffusion Acceleration - Coarse Mesh Finite Difference
This page section discusses how nonlinear diffusion acceleration (NDA) using coarse mesh finite difference (CMFD)
is implemented into OpenMC. Before we get into the theory, general notation for this section is discussed.
Note that the methods discussed in this section are written specifically for continuous-energy mode but equivalent apply
to the multi-group mode if the particle’s energy is replaced with the particle’s group
3.12.1 Notation
Before deriving NDA relationships, notation is explained. If a parameter has a ·, it is surface area-averaged and if it has
a ·, it is volume-averaged. When describing a specific cell in the geometry, indices (𝑖, 𝑗, 𝑘) are used which correspond
to directions (𝑥, 𝑦, 𝑧). In most cases, the same operation is performed in all three directions. To compactly write this,
an arbitrary direction set (𝑢, 𝑣, 𝑤) that corresponds to cell indices (𝑙, 𝑚, 𝑛) is used. Note that 𝑢 and 𝑙 do not have to
correspond to 𝑥 and 𝑖. However, if 𝑢 and 𝑙 correspond to 𝑦 and 𝑗, 𝑣 and 𝑤 correspond to 𝑥 and 𝑧 directions. An example
of this is shown in the following expression:
∑︁ ⟨ 𝑢,𝑔 ⟩
𝐽 𝑙+1/2,𝑚,𝑛 ∆𝑣𝑚 ∆𝑤𝑛 (3.12.1)
𝑢∈(𝑥,𝑦,𝑧)
Here, 𝑢 takes on each direction one at a time. The parameter 𝐽 is surface area-averaged over the transverse indices 𝑚
and 𝑛 located at 𝑙 + 1/2. Usually, spatial indices are listed as subscripts and the direction as a superscript. Energy
group indices represented by 𝑔 and ℎ are also listed as superscripts here. The group 𝑔 is the group of interest and, if
present, ℎ is all groups. Finally, any parameter surrounded by ⟨·⟩ represents a tally quantity that can be edited from a
Monte Carlo (MC) solution.
3.12. Nonlinear Diffusion Acceleration - Coarse Mesh Finite Difference 115

3.12.2 Theory
NDA is a diffusion model that has equivalent physics to a transport model. There are many different methods that can
be classified as NDA. The CMFD method is a type of NDA that represents second order multigroup diffusion equations
on a coarse spatial mesh. Whether a transport model or diffusion model is used to represent the distribution of neutrons,
these models must satisfy the neutron balance equation. This balance is represented by the following formula for a
specific energy group 𝑔 in cell (𝑙, 𝑚, 𝑛):
∑︁ (︁⟨ 𝑢,𝑔 ⟩ ⟨ 𝑢,𝑔 ⟩)︁ ⟨ 𝑔 𝑔 ⟩
𝐽 𝑙+1/2,𝑚,𝑛 ∆𝑣𝑚 ∆𝑤 𝑛 − 𝐽 ∆ 𝑣
𝑙−1/2,𝑚,𝑛 𝑚 𝑛 ∆ 𝑤
+ Σ 𝜑 ∆
𝑡𝑙,𝑚,𝑛 𝑙,𝑚,𝑛 𝑙
𝑢 𝑣
∆ 𝑤
𝑚 𝑛 =
∆
𝑢∈(𝑥,𝑦,𝑧)
𝐺 ⟨ ⟩ 𝐺 ⟨ ⟩ (3.12.2)
∑︁ ℎ→𝑔 ℎ 1 ∑︁ ℎ→𝑔 ℎ
𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛 + 𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛 .
𝑘𝑒𝑓 𝑓
ℎ=1 ℎ=1
In eq. (3.12.2) the parameters are defined as:

⟨ 𝑢,𝑔 ⟩
• 𝐽 𝑙±1/2,𝑚,𝑛 ∆𝑣𝑚 ∆𝑤 𝑛 — surface area-integrated net current over surface (𝑙 ± 1/2, 𝑚, 𝑛) with surface normal in
direction 𝑢 in energy group 𝑔. By dividing this quantity by the transverse area, ∆𝑣𝑚 ∆𝑤
𝑛 , the surface area-averaged
net current can be computed.
⟨ 𝑔 𝑔 ⟩
• Σ𝑡𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤 𝑛 — volume-integrated total reaction rate over energy group 𝑔.
⟨ ⟩
ℎ→𝑔 ℎ
• 𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑙 ∆𝑚 ∆𝑛 — volume-integrated scattering production rate of neutrons that begin with en-
𝑢 𝑣 𝑤
ergy in group ℎ and exit reaction in group 𝑔. This reaction rate also includes the energy transfer of reactions
(except fission) that produce multiple neutrons such as (n, 2n); hence, the need for 𝜈𝑠 to represent neutron mul-
tiplicity.
• 𝑘𝑒𝑓 𝑓 — core multiplication factor.
⟨ ⟩
ℎ→𝑔 ℎ
• 𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑙 ∆𝑚 ∆𝑛 — volume-integrated fission production rate of neutrons from fissions in group
𝑢 𝑣 𝑤
ℎ that exit in group 𝑔.

Each quantity in ⟨·⟩ represents a scalar value that is obtained from an MC tally. A good verification step when using
an MC code is to make sure that tallies satisfy this balance equation within statistics. No NDA acceleration can be
performed if the balance equation is not satisfied.
There are three major steps to consider when performing NDA: (1) calculation of macroscopic cross sections and
nonlinear parameters, (2) solving an eigenvalue problem with a system of linear equations, and (3) modifying MC
source distribution to align with the NDA solution on a chosen mesh. This process is illustrated as a flow chart below.
After a batch of neutrons is simulated, NDA can take place. Each of the steps described above is described in detail in
the following sections.
Calculation of Macroscopic Cross Sections
A diffusion model needs macroscopic cross sections and diffusion coefficients to solve for multigroup fluxes. Cross sec-
tions are derived by conserving reaction rates predicted by MC tallies. From Eq. (3.12.2), total, scattering production
and fission production macroscopic cross sections are needed. They are defined from MC tallies as follows:
⟨ 𝑔 𝑔 ⟩
𝑔 Σ𝑡𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛
Σ𝑡𝑙,𝑚,𝑛 ≡ ⟨ 𝑔 ⟩ , (3.12.3)
𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛
⟨ ⟩
ℎ→𝑔 ℎ
𝑢 𝑣 𝑤
𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑙 ∆𝑚 ∆𝑛
ℎ→𝑔
𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 ≡ ⟨
ℎ
⟩ (3.12.4)
𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛

Fig. 9: Flow chart of NDA process. Note “XS” is used for cross section and “DC” is used for diffusion coefficient.
and
⟨ ⟩
ℎ→𝑔 ℎ
𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛
ℎ→𝑔
𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 ≡ ⟨
ℎ
⟩ . (3.12.5)
𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛
In order to fully conserve neutron balance, leakage rates also need to be preserved. In standard diffusion theory,
leakage rates are represented by diffusion coefficients. Unfortunately, it is not easy in MC to calculate a single diffusion
coefficient for a cell that describes leakage out of each surface. Luckily, it does not matter what definition of diffusion
coefficient is used because nonlinear equivalence parameters will correct for this inconsistency. However, depending on
the diffusion coefficient definition chosen, different convergence properties of NDA equations are observed. Here, we
introduce a diffusion coefficient that is derived for a coarse energy transport reaction rate. This definition can easily be
constructed from MC tallies provided that angular moments of scattering reaction rates can be obtained. The diffusion
coefficient is defined as follows:
⟨ 𝑔 ⟩
𝑢 𝑣 𝑤
𝑔 𝜑 ∆
𝑙,𝑚,𝑛 𝑙 ∆ ∆
𝑚 𝑛
𝐷𝑙,𝑚,𝑛 = ⟨ 𝑔 𝑔 ⟩, (3.12.6)
3 Σ𝑡𝑟𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛
where
⟨ 𝑔 𝑔 ⟩ ⟨ 𝑔 𝑔 ⟩
Σ𝑡𝑟𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤 𝑢 𝑣
𝑛 = Σ𝑡𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑙 ∆𝑚 ∆𝑛
𝑤
⟨ 𝑔 𝑔 ⟩ (3.12.7)
− 𝜈𝑠 Σ𝑠1𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛 .
Note that the transport reaction rate is calculated from the total reaction rate reduced by the 𝑃1 scattering production
reaction rate. Equation (3.12.6) does not represent the best definition of diffusion coefficients from MC; however, it is
very simple and usually fits into MC tally frameworks easily. Different methods to calculate more accurate diffusion
coefficients can found in [Herman].

CMFD Equations
The first part of this section is devoted to discussing second-order finite volume discretization of multigroup diffusion
equations. This will be followed up by the formulation of CMFD equations that are used in this NDA scheme. When
performing second-order finite volume discretization of the diffusion equation, we need information that relates current
to flux. In this numerical scheme, each cell is coupled only to its direct neighbors. Therefore, only two types of coupling
exist: (1) cell-to-cell coupling and (2) cell-to-boundary coupling. The derivation of this procedure is referred to as finite
difference diffusion equations and can be found in literature such as [Hebert]. These current/flux relationships are as
follows:
• cell-to-cell coupling
𝑔 𝑔
𝑢,𝑔 2𝐷𝑙±1,𝑚,𝑛 𝐷𝑙,𝑚,𝑛 (︁ 𝑔 𝑔 )︁
𝐽 𝑙±1/2,𝑚,𝑛 =− 𝑔 𝑔 ±𝜑𝑙±1,𝑚,𝑛 ∓ 𝜑𝑙,𝑚,𝑛 , (3.12.8)
𝐷𝑙±1,𝑚,𝑛 ∆𝑢𝑙 + 𝐷𝑙,𝑚,𝑛 ∆𝑢𝑙±1
• cell-to-boundary coupling
𝑔 (︁ )︁
𝑢,𝑔
𝑢,𝑔
2𝐷𝑙,𝑚,𝑛 1 − 𝛽𝑙±1/2,𝑚,𝑛 𝑔
𝐽 𝑙±1/2,𝑚,𝑛 =± 𝑔 (︁ )︁ (︁ )︁ 𝜑𝑙,𝑚,𝑛 . (3.12.9)
𝑢,𝑔 𝑢,𝑔
4𝐷𝑙,𝑚,𝑛 1 + 𝛽𝑙±1/2,𝑚,𝑛 + 1 − 𝛽𝑙±1/2,𝑚,𝑛 ∆𝑢𝑙
In Eqs. (3.12.8) and (3.12.9), the ± refers to left (−𝑥) or right (+𝑥) surface in the 𝑥 direction, back (−𝑦) or front
(+𝑦) surface in the 𝑦 direction and bottom (−𝑧) or top (+𝑧) surface in the 𝑧 direction. For cell-to-boundary coupling,
𝑢,𝑔
a general albedo, 𝛽𝑙±1/2,𝑚,𝑛 , is used. The albedo is defined as the ratio of incoming (− superscript) to outgoing (+
superscript) partial current on any surface represented as
𝑢,𝑔−
𝑢,𝑔 𝐽 𝑙±1/2,𝑚,𝑛
𝛽𝑙±1/2,𝑚,𝑛 = 𝑢,𝑔+ . (3.12.10)
𝐽 𝑙±1/2,𝑚,𝑛
Common boundary conditions are: vacuum (𝛽 = 0), reflective (𝛽 = 1) and zero flux (𝛽 = −1). Both eq. (3.12.8) and
eq. (3.12.9) can be written in this generic form,
𝑢,𝑔
̃︀ 𝑢,𝑔 (. . . ) .
𝐽 𝑙±1/2,𝑚,𝑛 = 𝐷 𝑙,𝑚,𝑛 (3.12.11)
The parameter 𝐷 ̃︀ 𝑢,𝑔 represents the linear coupling term between current and flux. These current relationships can
𝑙,𝑚,𝑛
be substituted into eq. (3.12.2) to produce a linear system of multigroup diffusion equations for each spatial cell and
energy group. However, a solution to these equations is not consistent with a higher order transport solution unless
equivalence factors are present. This is because both the diffusion approximation, governed by Fick’s Law, and spatial
truncation error will produce differences. Therefore, a nonlinear parameter, 𝐷 ̂︀ 𝑢,𝑔 , is added to eqs. (3.12.8) and
𝑙,𝑚,𝑛
(3.12.9). These equations are, respectively,
𝑢,𝑔
(︁ 𝑔 𝑔 )︁ (︁ 𝑔 𝑔 )︁
𝐽 𝑙±1/2,𝑚,𝑛 = −𝐷̃︀ 𝑢,𝑔 ±𝜑 𝑙±1,𝑚,𝑛 ∓ 𝜑 𝑙,𝑚,𝑛 + 𝐷
̂︀ 𝑢,𝑔
𝜑 𝑙±1,𝑚,𝑛 + 𝜑 𝑙,𝑚,𝑛 (3.12.12)
𝑙,𝑚,𝑛 𝑙,𝑚,𝑛
and
𝑢,𝑔 𝑔 𝑔
̃︀ 𝑢,𝑔 𝜑
𝐽 𝑙±1/2,𝑚,𝑛 = ±𝐷 ̂︀ 𝑢,𝑔
𝑙,𝑚,𝑛 𝑙,𝑚,𝑛 + 𝐷𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 .
(3.12.13)
The only unknown in each of these equations is the equivalence parameter. The current, linear coupling term and flux
can either be obtained or derived from MC tallies. Thus, it is called nonlinear because it is dependent on the flux which
is updated on the next iteration.
Equations (3.12.12) and (3.12.13) can be substituted into eq. (3.12.2) to create a linear system of equations that is

consistent with transport physics. One example of this equation is written for an interior cell,
∑︁ 1 [︁(︁ ˜ 𝑢,𝑔 ˆ 𝑢,𝑔
)︁ 𝑔
𝑢 −𝐷𝑙−1/2,𝑚,𝑛 − 𝐷 𝑙−1/2,𝑚,𝑛 𝜑𝑙−1,𝑚,𝑛
𝑢∈𝑥,𝑦,𝑥
∆𝑙
(︁ )︁ 𝑔
+ 𝐷 ˜ 𝑢,𝑔 + ˜ 𝑢,𝑔
𝐷 − ˆ 𝑢,𝑔
𝐷 + ˆ 𝑢,𝑔
𝐷
𝑙−1/2,𝑚,𝑛 𝑙+1/2,𝑚,𝑛 𝑙−1/2,𝑚,𝑛 𝑙+1/2,𝑚,𝑛 𝜑𝑙,𝑚,𝑛
(︁ )︁ 𝑔 ]︁ (3.12.14)
+ −𝐷 ˜ 𝑢,𝑔 ˆ 𝑢,𝑔
𝑙+1/2,𝑚,𝑛 + 𝐷𝑙+1/2,𝑚,𝑛 𝜑𝑙+1,𝑚,𝑛
𝐺 𝐺
𝑔 𝑔 ∑︁ ℎ→𝑔 ℎ 1 ∑︁ ℎ→𝑔 ℎ
+Σ𝑡𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 − 𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 = 𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 .
𝑘
ℎ=1 ℎ=1
It should be noted that before substitution, eq. (3.12.2) was divided by the volume of the cell, ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤
𝑛 . Equation
(3.12.14) can be represented in operator form as
1
MΦ = FΦ, (3.12.15)
𝑘
where M is the neutron loss matrix operator, F is the neutron production matrix operator, Φ is the multigroup flux
vector and 𝑘 is the eigenvalue. This generalized eigenvalue problem is solved to obtain fundamental mode multigroup
fluxes and eigenvalue. In order to produce consistent results with transport theory from these equations, the neutron
balance equation must have been satisfied by MC tallies. The desire is that CMFD equations will produce a more
accurate source than MC after each fission source generation.
CMFD Feedback
Now that a more accurate representation of the expected source distribution is estimated from CMFD, it needs to
be communicated back to MC. The first step in this process is to generate a probability mass function that provides
information about how probable it is for a neutron to be born in a given cell and energy group. This is represented as
∑︀𝐺 ℎ→𝑔 ℎ
𝜈 𝑓 Σ𝑓
ℎ=1 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛
𝑝𝑔𝑙,𝑚,𝑛 = ∑︀ ∑︀ ∑︀ ∑︀ 𝑙,𝑚,𝑛 ℎ→𝑔 ℎ . (3.12.16)
𝐺 𝑢 ∆𝑣 ∆𝑤
𝑛 𝑚 𝑙 ℎ=1 𝜈 𝑓 Σ 𝜑 ∆
𝑓𝑙,𝑚,𝑛 𝑙,𝑚,𝑛 𝑙 𝑚 𝑛
This equation can be multiplied by the number of source neutrons to obtain an estimate of the expected number of
neutrons to be born in a given cell and energy group. This distribution can be compared to the MC source distribution
to generate weight adjusted factors defined as
𝑔 𝑁 𝑝𝑔𝑙,𝑚,𝑛
𝑓𝑙,𝑚,𝑛 = ∑︀ ; 𝑠 ∈ (𝑔, 𝑙, 𝑚, 𝑛) . (3.12.17)
𝑤𝑠
𝑠
The MC source distribution is represented on the same coarse mesh as CMFD by summing all neutrons’ weights, 𝑤𝑠 ,
in a given cell and energy group. MC source weights can then be modified by this weight adjustment factor so that it
matches the CMFD solution on the coarse mesh,
𝑔
𝑤𝑠′ = 𝑤𝑠 × 𝑓𝑙,𝑚,𝑛 ; 𝑠 ∈ (𝑔, 𝑙, 𝑚, 𝑛) . (3.12.18)
It should be noted that heterogeneous information about local coordinates and energy remain constant throughout this
modification process.

3.12.3 Implementation in OpenMC
The section describes how CMFD was implemented in OpenMC. Before the simulation begins, a user sets up a CMFD
input file that contains the following basic information:
• CMFD mesh (space and energy),
• boundary conditions at edge of mesh (albedos),
• acceleration region (subset of mesh, optional),
• fission source generation (FSG)/batch that CMFD should begin, and
• whether CMFD feedback should be applied.
It should be noted that for more difficult simulations (e.g., light water reactors), there are other options available to
users such as tally resetting parameters, effective down-scatter usage, tally estimator, etc. For more information please
see the openmc.cmfd.CMFDRun class.
Of the options described above, the optional acceleration subset region is an uncommon feature. Because OpenMC
only has a structured Cartesian mesh, mesh cells may overlay regions that don’t contain fissionable material and may
be so far from the core that the neutron flux is very low. If these regions were included in the CMFD solution, bad
estimates of diffusion parameters may result and affect CMFD feedback. To deal with this, a user can carve out an
active acceleration region from their structured Cartesian mesh. This is illustrated in diagram below. When placing a
CMFD mesh over a geometry, the boundary conditions must be known at the global edges of the mesh. If the geometry
is complex like the one below, one may have to cover the whole geometry including the reactor pressure vessel because
we know that there is a zero incoming current boundary condition at the outer edge of the pressure vessel. This is
not viable in practice because neutrons in simulations may not reach mesh cells that are near the pressure vessel. To
circumvent this, one can shrink the mesh to cover just the core region as shown in the diagram. However, one must
still estimate the boundary conditions at the global boundaries, but at these locations, they are not readily known.
In OpenMC, one can carve out the active core region from the entire structured Cartesian mesh. This is shown in
the diagram below by the darkened region over the core. The albedo boundary conditions at the active core/reflector
boundary can be tallied indirectly during the MC simulation with incoming and outgoing partial currents. This allows
the user to not have to worry about neutrons producing adequate tallies in mesh cells far away from the core.
During an MC simulation, CMFD tallies are accumulated. The basic tallies needed are listed in Table OpenMC CMFD
tally list. Each tally is performed on a spatial and energy mesh basis. The surface area-integrated net current is tallied
on every surface of the mesh. OpenMC tally objects are created by the CMFD code internally, and cross sections
are calculated at each CMFD feedback iteration. The first CMFD iteration, controlled by the user, occurs just after
tallies are communicated to the master processor. Once tallies are collapsed, cross sections, diffusion coefficients
and equivalence parameters are calculated. This is performed only on the acceleration region if that option has been
activated by the user. Once all diffusion parameters are calculated, CMFD matrices are formed where energy groups
are the inner most iteration index. In OpenMC, compressed row storage sparse matrices are used due to the sparsity of
CMFD operators. An example of this sparsity is shown for the 3-D BEAVRS model in figures 11 and 12 [BEAVRS].
These matrices represent an assembly radial mesh, 24 cell mesh in the axial direction and two energy groups. The
loss matrix is 99.92% sparse and the production matrix is 99.99% sparse. Although the loss matrix looks like it is
tridiagonal, it is really a seven banded matrix with a block diagonal matrix for scattering. The production matrix is a
2 × 2 block diagonal; however, zeros are present because no fission neutrons appear with energies in the thermal group.

Fig. 10: Diagram of CMFD acceleration mesh

Table 2: OpenMC CMFD tally list
tally
⟨ 𝑔 ⟩ score filter
𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛 flux mesh, energy
⟨ 𝑔 𝑔 ⟩
Σ𝑡𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛 total mesh, energy
⟨ 𝑔 𝑔 ⟩
𝜈𝑠 Σ𝑠1𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑙 ∆𝑚 ∆𝑤
𝑢 𝑣
𝑛 nu-scatter-1 mesh, energy
⟨ ⟩
ℎ→𝑔 ℎ
𝜈𝑠 Σ𝑠𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛 nu-scatter mesh, energy, energyout
⟨ ⟩
ℎ→𝑔 ℎ
𝜈𝑓 Σ𝑓𝑙,𝑚,𝑛 𝜑𝑙,𝑚,𝑛 ∆𝑢𝑙 ∆𝑣𝑚 ∆𝑤𝑛 nu-fission mesh, energy, energyout
⟨ 𝑢,𝑔 ⟩
𝐽 𝑙±1/2,𝑚,𝑛 ∆𝑣𝑚 ∆𝑤 𝑛 current mesh, energy
Fig. 11: Sparsity of Neutron Loss Operator
To solve the eigenvalue problem with these matrices, different source iteration and linear solvers can be used. The
most common source iteration solver used is standard power iteration as described in [Gill]. To accelerate these source
iterations, a Wielandt shift scheme can be used as discussed in [Park]. PETSc solvers were first implemented to perform
the linear solution in parallel that occurs once per source iteration. When using PETSc, different types of parallel linear

Fig. 12: Sparsity of Neutron Production Operator

solvers and preconditioners can be used. By default, OpenMC uses an incomplete LU preconditioner and a GMRES
Krylov solver. After some initial studies of parallelization with PETSc, it was observed that because CMFD matrices
are very sparse, solution times do not scale well. An additional Gauss-Seidel linear solver with Chebyshev acceleration
was added that is similar to the one used for CMFD in CASMO [Rhodes] and [Smith]. This solver was implemented
with a custom section for two energy groups. Because energy group is the inner most index, a block diagonal is formed
when using more than one group. For two groups, it is easy to invert this diagonal analytically inside the Gauss-Seidel
iterative solver. For more than two groups, this analytic inversion can still be performed, but with more computational
effort. A standard Gauss-Seidel solver is used for more than two groups.
Besides a power iteration, a Jacobian-free Newton-Krylov method was also implemented to obtain eigenvalue and
multigroup fluxes as described in [Gill] and [Knoll]. This method is not the primary one used, but has gotten recent at-
tention due to its coupling advantages to other physics such as thermal hydraulics. Once multigroup fluxes are obtained,
a normalized fission source is calculated in the code using eq. (3.12.16) directly.
The next step in the process is to compute weight adjustment factors. These are calculated by taking the ratio of the
expected number of neutrons from the CMFD source distribution to the current number of neutrons in each mesh. It
is straightforward to compute the CMFD number of neutrons because it is the product between the total starting initial
weight of neutrons and the CMFD normalized fission source distribution. To compute the number of neutrons from
the current MC source, OpenMC sums the statistical weights of neutrons from the source bank on a given spatial and
energy mesh. Once weight adjustment factors were calculated, each neutron’s statistical weight in the source bank
was modified according to its location and energy. Examples of CMFD simulations using OpenMC can be found in
[HermanThesis].

CHAPTER
FOUR
USER’S GUIDE
Welcome to the OpenMC User’s Guide! This tutorial will guide you through the essential aspects of using OpenMC
to perform simulations.
4.1 A Beginner’s Guide to OpenMC
4.1.1 What does OpenMC do?
In a nutshell, OpenMC simulates neutral particles (presently neutrons and photons) moving stochastically through an
arbitrarily defined model that represents an real-world experimental setup. The experiment could be as simple as a
sphere of metal or as complicated as a full-scale nuclear reactor. This is what’s known as Monte Carlo simulation. In
the case of a nuclear reactor model, neutrons are especially important because they are the particles that induce fission
in isotopes of uranium and other elements. Knowing the behavior of neutrons allows one to determine how often and
where fission occurs. The amount of energy released is then directly proportional to the fission reaction rate since most
heat is produced by fission. By simulating many neutrons (millions or billions), it is possible to determine the average
behavior of these neutrons (or the behavior of the energy produced, or any other quantity one is interested in) very
accurately.
Using Monte Carlo methods to determine the average behavior of various physical quantities in a system is quite
different from other means of solving the same problem. The other class of methods for determining the behavior of
neutrons and reactions rates is so-called deterministic methods. In these methods, the starting point is not randomly
simulating particles but rather writing an equation that describes the average behavior of the particles. The equation
that describes the average behavior of neutrons is called the neutron transport equation. This equation is a seven-
dimensional equation (three for space, three for velocity, and one for time) and is very difficult to solve directly. For
all but the simplest problems, it is necessary to make some sort of discretization. As an example, we can divide up
all space into small sections which are homogeneous and then solve the equation on those small sections. After these
discretizations and various approximations, one can arrive at forms that are suitable for solution on a computer. Among
these are discrete ordinates, method of characteristics, finite-difference diffusion, and nodal methods.
So why choose Monte Carlo over deterministic methods? Each method has its pros and cons. Let us first take a look at
few of the salient pros and cons of deterministic methods:
• Pro: Depending on what method is used, solution can be determined very quickly.
• Pro: The solution is a global solution, i.e. we know the average behavior everywhere.
• Pro: Once the problem is converged, the solution is known.
• Con: If the model is complex, it is necessary to do sophisticated mesh generation.
• Con: It is necessary to generate multi-group cross sections which requires knowing the solution a priori.
Now let’s look at the pros and cons of Monte Carlo methods:
125
• Pro: No mesh generation is required to build geometry. By using constructive solid geometry, it’s possible to
build complex models with curved surfaces.
• Pro: Monte Carlo methods can be used with either continuous-energy or multi-group cross sections.
• Pro: Running simulations in parallel is conceptually very simple.
• Con: Because they rely on repeated random sampling, they are computationally very expensive.
• Con: A simulation doesn’t automatically give you the global solution everywhere – you have to specifically ask
for those quantities you want.
• Con: Even after the problem is converged, it is necessary to simulate many particles to reduce stochastic uncer-
tainty.
Because fewer approximations are made in solving a problem by the Monte Carlo method, it is often seen as a “gold
standard” which can be used as a benchmark for a solution of the same problem by deterministic means. However, it
comes at the expense of a potentially longer simulation.
4.1.2 How does it work?
In order to do anything, the code first needs to have a model of some problem of interest. This could be a nuclear
reactor or any other physical system with fissioning material. You, as the code user, will need to describe the model so
that the code can do something with it. A basic model consists of a few things:
• A description of the geometry – the problem must be split up into regions of homogeneous material composition.
• For each different material in the problem, a description of what nuclides are in the material and at what density.
• Various parameters telling the code how many particles to simulate and what options to use.
• A list of different physical quantities that the code should return at the end of the simulation. In a Monte Carlo
simulation, if you don’t ask for anything, it will not give you any answers (other than a few default quantities).
4.1.3 What do I need to know?
If you are starting to work with OpenMC, there are a few things you should be familiar with. Whether you plan on
working in Linux, macOS, or Windows, you should be comfortable working in a command line environment. There
are many resources online for learning command line environments. If you are using Linux or Mac OS X (also Unix-
derived), this tutorial will help you get acquainted with commonly-used commands.
To reap the full benefits of OpenMC, you should also have basic proficiency in the use of Python, as OpenMC includes
a rich Python API that offers many usability improvements over dealing with raw XML input files.
OpenMC uses a version control software called git to keep track of changes to the code, document bugs and issues,
and other development tasks. While you don’t necessarily have to have git installed in order to download and run
OpenMC, it makes it much easier to receive updates if you do have it installed and have a basic understanding of
how it works. There are a list of good git tutorials at the git documentation website. The OpenMC source code and
documentation are hosted at GitHub. In order to receive updates to the code directly, submit bug reports, and perform
other development tasks, you may want to sign up for a free account on GitHub. Once you have an account, you can
follow these instructions on how to set up your computer for using GitHub.
If you are new to nuclear engineering, you may want to review the NRC’s Reactor Concepts Manual. This manual
describes the basics of nuclear power for electricity generation, the fission process, and the overall systems in a pres-
surized or boiling water reactor. Another resource that is a bit more technical than the Reactor Concepts Manual but
still at an elementary level is the DOE Fundamentals Handbook on Nuclear Physics and Reactor Theory Volume I and
Volume II. You may also find it helpful to review the following terms:
• Neutron cross section
126 Chapter 4. User’s Guide

• Effective multiplication factor

• Flux
4.2 Installation and Configuration
4.2.1 Installing on Linux/Mac with Mamba and conda-forge
Conda is an open source package management systems and environments management system for installing multiple
versions of software packages and their dependencies and switching easily between them. Mamba is a cross-platform
package manager and is compatible with conda packages. OpenMC can be installed in a conda environment with
mamba. First, conda should be installed with one of the following installers: Miniconda, Anaconda, or Miniforge.
Once you have conda installed on your system, OpenMC can be installed via the conda-forge channel with mamba.
First, add the conda-forge channel with:
conda config --add channels conda-forge
Then create and activate a new conda enviroment called openmc-env in which to install OpenMC.
conda create -n openmc-env

conda activate openmc-env
Then install mamba, which will be used to install OpenMC.
conda install mamba
To list the versions of OpenMC that are available on the conda-forge channel, in your terminal window or an Anaconda
Prompt run:
mamba search openmc
OpenMC can then be installed with:
mamba install openmc
You are now in a conda environment called openmc-env that has OpenMC installed.
4.2.2 Installing on Linux/Mac/Windows with Docker
OpenMC can be easily deployed using Docker on any Windows, Mac, or Linux system. With Docker running, execute
the following command in the shell to download and run a Docker image with the most recent release of OpenMC from
DockerHub:
docker run openmc/openmc:latest
This will take several minutes to run depending on your internet download speed. The command will place you in an
interactive shell running in a Docker container with OpenMC installed.
Note: The docker run command supports many options for spawning containers including mounting volumes from
the host filesystem, which many users will find useful.
4.2. Installation and Configuration 127

4.2.3 Installing from Source using Spack
Spack is a package management tool designed to support multiple versions and configurations of software on a wide
variety of platforms and environments. Please follow Spack’s setup guide to configure the Spack system.
The OpenMC Spack recipe has been configured with variants that match most options provided in the CMakeLists.txt
file. To see a list of these variants and other information use:
spack info openmc
Note: It should be noted that by default OpenMC builds with -O2 -g flags which are equivalent to a CMake build
type of RelwithDebInfo. In addition, MPI is OFF while OpenMP is ON.
It is recommended to install OpenMC with the Python API. Information about this Spack recipe can be found with the
following command:
spack info py-openmc
Note: The only variant for the Python API is mpi.
The most basic installation of OpenMC can be accomplished by entering the following command:
spack install py-openmc
Caution: When installing any Spack package, dependencies are assumed to be at configured defaults unless
otherwise specfied in the specification on the command line. In the above example, assuming the default options
weren’t changed in Spack’s package configuration, py-openmc will link against a non-optimized non-MPI openmc.
Even if an optimized openmc was built separately, it will rebuild openmc with optimization OFF. Thus, if you are
trying to link against dependencies that were configured different than defaults, ôpenmc[variants] will have to
be present in the command.
For a more performant build of OpenMC with optimization turned ON and MPI provided by OpenMPI, the following
command can be used:
spack install py-openmc+mpi ôpenmc+optimize ôpenmpi
Note: +mpi is automatically forwarded to OpenMC.
Tip: When installing py-openmc, it will use Spack’s preferred Python. For example, assuming Spack’s preferred
Python is 3.8.7, to build py-openmc against the latest Python 3.7 instead, ^python@3.7.0:3.7.99 should be added
to the specification on the command line. Additionally, a compiler type and version can be specified at the end of the
command using %gcc@<version>, %intel@<version>, etc.
A useful tool in Spack is to look at the dependency tree before installation. This can be observed using Spack’s spec
tool:

spack spec py-openmc+mpi ôpenmc+optimize
Once installed, environment/lmod modules can be generated or Spack’s load feature can be used to access the installed
packages.
4.2.4 Installing from Source
Prerequisites
Required
• A C/C++ compiler such as gcc
OpenMC’s core codebase is written in C++. The source files have been tested to work with a wide variety of
compilers. If you are using a Debian-based distribution, you can install the g++ compiler using the following
command:
sudo apt install g++
• CMake cross-platform build system

The compiling and linking of source files is handled by CMake in a platform-independent manner. If you are
using Debian or a Debian derivative such as Ubuntu, you can install CMake using the following command:
sudo apt install cmake
• HDF5 Library for portable binary output format

OpenMC uses HDF5 for many input/output files. As such, you will need to have HDF5 installed on your com-
puter. The installed version will need to have been compiled with the same compiler you intend to compile
OpenMC with. If compiling with gcc from the APT repositories, users of Debian derivatives can install HDF5
and/or parallel HDF5 through the package manager:
sudo apt install libhdf5-dev
Parallel versions of the HDF5 library called libhdf5-mpich-dev and libhdf5-openmpi-dev exist which are built
against MPICH and OpenMPI, respectively. To link against a parallel HDF5 library, make sure to set the
HDF5_PREFER_PARALLEL CMake option, e.g.:
cmake -DHDF5_PREFER_PARALLEL=on -DOPENMC_USE_MPI=on ..
Note that the exact package names may vary depending on your particular distribution and version.
If you are using building HDF5 from source in conjunction with MPI, we recommend that your HDF5 installation
be built with parallel I/O features. An example of configuring HDF5 is listed below:
CC=mpicc ./configure --enable-parallel
You may omit --enable-parallel if you want to compile HDF5 in serial.
Optional

• libpng official reference PNG library

OpenMC’s built-in plotting capabilities use the libpng library to produce compressed PNG files. In the absence
of this library, OpenMC will fallback to writing PPM files, which are uncompressed and only supported by select
image viewers. libpng can be installed on Ddebian derivates with:
sudo apt install libpng-dev
• An MPI implementation for distributed-memory parallel runs

To compile with support for parallel runs on a distributed-memory architecture, you will need to have a valid
implementation of MPI installed on your machine. The code has been tested and is known to work with the latest
versions of both OpenMPI and MPICH. OpenMPI and/or MPICH can be installed on Debian derivatives with:
sudo apt install mpich libmpich-dev

sudo apt install openmpi-bin libopenmpi-dev
• git version control software for obtaining source code

• DAGMC toolkit for simulation using CAD-based geometries
OpenMC supports particle tracking in CAD-based geometries via the Direct Accelerated Geometry Monte Carlo
(DAGMC) toolkit (installation instructions). For use in OpenMC, only the MOAB_DIR and BUILD_TALLY vari-
ables need to be specified in the CMake configuration step when building DAGMC. This option also allows
unstructured mesh tallies on tetrahedral MOAB meshes. In addition to turning this option on, the path to the
DAGMC installation should be specified as part of the CMAKE_PREFIX_PATH variable:
cmake -DOPENMC_USE_DAGMC=on -DCMAKE_PREFIX_PATH=/path/to/dagmc/installation ..
• libMesh mesh library framework for numerical simulations of partial differential equations
This optional dependency enables support for unstructured mesh tally filters using libMesh meshes. Any 3D
element type supported by libMesh can be used, but the implementation is currently restricted to collision esti-
mators. In addition to turning this option on, the path to the libMesh installation should be specified as part of
the CMAKE_PREFIX_PATH variable.:
cmake -DOPENMC_USE_LIBMESH=on -DOPENMC_USE_MPI=on -DCMAKE_PREFIX_PATH=/path/to/

˓→libmesh/installation ..
Note that libMesh is most commonly compiled with MPI support. If that is the case, then OpenMC should be
compiled with MPI support as well.
Obtaining the Source
All OpenMC source code is hosted on GitHub. You can download the source code directly from GitHub or, if you
have the git version control software installed on your computer, you can use git to obtain the source code. The latter
method has the benefit that it is easy to receive updates directly from the GitHub repository. GitHub has a good set of
instructions for how to set up git to work with GitHub since this involves setting up ssh keys. With git installed and
setup, the following command will download the full source code from the GitHub repository:
git clone --recurse-submodules https://github.com/openmc-dev/openmc.git
By default, the cloned repository will be set to the development branch. To switch to the source of the latest stable
release, run the following commands:

cd openmc
git checkout master
Build Configuration
Compiling OpenMC with CMake is carried out in two steps. First, cmake is run to determine the compiler, whether
optional packages (MPI, HDF5) are available, to generate a list of dependencies between source files so that they may
be compiled in the correct order, and to generate a normal Makefile. The Makefile is then used by make to actually carry
out the compile and linking commands. A typical out-of-source build would thus look something like the following

cmake ..
make
Note that first a build directory is created as a subdirectory of the source directory. The Makefile in the top-level
directory will automatically perform an out-of-source build with default options.
CMakeLists.txt Options
The following options are available in the CMakeLists.txt file:

OPENMC_ENABLE_PROFILE
Enables profiling using the GNU profiler, gprof. (Default: off)
OPENMC_USE_OPENMP
Enables shared-memory parallelism using the OpenMP API. The C++ compiler being used must support
OpenMP. (Default: on)
OPENMC_USE_DAGMC
Enables use of CAD-based DAGMC geometries and MOAB unstructured mesh tallies. Please see the note about
DAGMC in the optional dependencies list for more information on this feature. The installation directory for
DAGMC should also be defined as DAGMC_ROOT in the CMake configuration command. (Default: off)
OPENMC_USE_LIBMESH
Enables the use of unstructured mesh tallies with libMesh. (Default: off)
OPENMC_ENABLE_COVERAGE
Compile and link code instrumented for coverage analysis. This is typically used in conjunction with gcov.
(Default: off)
OPENMC_USE_MPI
Turns on compiling with MPI (default: off). For further information on MPI options, please see the Find-
MPI.cmake documentation.
To set any of these options (e.g., turning on profiling), the following form should be used:
cmake -DOPENMC_ENABLE_PROFILE=on /path/to/openmc

Specifying the Build Type
OpenMC can be configured for debug, release, or release with debug info by setting the CMAKE_BUILD_TYPE option.
Debug
Enable debug compiler flags with no optimization -O0 -g.
Release
Disable debug and enable optimization -O3 -DNDEBUG.
RelWithDebInfo
(Default if no type is specified.) Enable optimization and debug -O2 -g.
Example of configuring for Debug mode:
cmake -DCMAKE_BUILD_TYPE=Debug /path/to/openmc
Selecting HDF5 Installation
CMakeLists.txt searches for the h5cc or h5pcc HDF5 C wrapper on your PATH environment variable and subsequently
uses it to determine library locations and compile flags. If you have multiple installations of HDF5 or one that does not
appear on your PATH, you can set the HDF5_ROOT environment variable to the root directory of the HDF5 installation,
e.g.
export HDF5_ROOT=/opt/hdf5/1.8.15
cmake /path/to/openmc
This will cause CMake to search first in /opt/hdf5/1.8.15/bin for h5cc / h5pcc before it searches elsewhere. As noted
above, an environment variable can typically be set for a single command, i.e.
HDF5_ROOT=/opt/hdf5/1.8.15 cmake /path/to/openmc
Compiling on Linux and Mac OS X
To compile OpenMC on Linux or Max OS X, run the following commands from within the root directory of the source
code:

cmake ..
make
make install
This will build an executable named openmc and install it (by default in /usr/local/bin). If you do not have administrative
privileges, you can install OpenMC locally by specifying an install prefix when running cmake:
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
The CMAKE_INSTALL_PREFIX variable can be changed to any path for which you have write-access.

Compiling on Windows 10
Recent versions of Windows 10 include a subsystem for Linux that allows one to run Bash within Ubuntu running in
Windows. First, follow the installation guide here to get Bash on Ubuntu on Windows setup. Once you are within bash,
obtain the necessary prerequisites via apt. Finally, follow the instructions for compiling on linux.
Testing Build
To run the test suite, you will first need to download a pre-generated cross section library along with windowed multipole
data. Please refer to our Test Suite documentation for further details.
4.2.5 Installing Python API
If you installed OpenMC using Conda, no further steps are necessary in order to use OpenMC’s Python API. However,
if you are installing from source, the Python API is not installed by default when make install is run because in many
situations it doesn’t make sense to install a Python package in the same location as the openmc executable (for example,
if you are installing the package into a virtual environment). The easiest way to install the openmc Python package is to
use pip, which is included by default in Python 3.4+. From the root directory of the OpenMC distribution/repository,
run:
pip install .
pip will first check that all required third-party packages have been installed, and if they are not present, they will be
installed by downloading the appropriate packages from the Python Package Index (PyPI). However, do note that since
pip runs the setup.py script which requires NumPy, you will have to first install NumPy:
pip install numpy
Installing in “Development” Mode
If you are primarily doing development with OpenMC, it is strongly recommended to install the Python package in
“editable” mode.
Prerequisites
The Python API works with Python 3.6+. In addition to Python itself, the API relies on a number of third-party
packages. All prerequisites can be installed using Conda (recommended), pip, or through the package manager in most
Linux distributions.
Required
NumPy
NumPy is used extensively within the Python API for its powerful N-dimensional array.
SciPy
SciPy’s special functions, sparse matrices, and spatial data structures are used for several optional features in the
API.
pandas
Pandas is used to generate tally DataFrames as demonstrated in an example notebook.

h5py
h5py provides Python bindings to the HDF5 library. Since OpenMC outputs various HDF5 files, h5py is needed
to provide access to data within these files from Python.
Matplotlib
Matplotlib is used to providing plotting functionality in the API like the Universe.plot() method and the
openmc.plot_xs() function.
uncertainties
Uncertainties are used for decay data in the openmc.data module.
lxml
lxml is used for the openmc-validate-xml script and various other parts of the Python API.
Optional
mpi4py
mpi4py provides Python bindings to MPI for running distributed-memory parallel runs. This package is needed
if you plan on running depletion simulations in parallel using MPI.
Cython
Cython is used for resonance reconstruction for ENDF data converted to openmc.data.IncidentNeutron.
vtk
The Python VTK bindings are needed to convert voxel and track files to VTK format.
pytest
The pytest framework is used for unit testing the Python API.
If you are running simulations that require OpenMC’s Python bindings to the C API (including depletion and CMFD),
it is recommended to build h5py (and mpi4py, if you are using MPI) using the same compilers and HDF5 version as
for OpenMC. Thus, the install process would proceed as follows:

HDF5_ROOT=<path to HDF5> CXX=<path to mpicxx> cmake ..
make
make install
cd ..
MPICC=<path to mpicc> pip install mpi4py
HDF5_DIR=<path to HDF5> pip install --no-binary=h5py h5py
If you are using parallel HDF5, you’ll also need to make sure the right MPI wrapper is used when installing h5py:
CC=<path to mpicc> HDF5_MPI=ON HDF5_DIR=<path to HDF5> pip install --no-binary=h5py h5py

4.2.6 Configuring Input Validation with GNU Emacs nXML mode
The GNU Emacs text editor has a built-in mode that extends functionality for editing XML files. One of the features in
nXML mode is the ability to perform real-time validation of XML files against a RELAX NG schema. The OpenMC
source contains RELAX NG schemas for each type of user input file. In order for nXML mode to know about these
schemas, you need to tell emacs where to find a “locating files” description. Adding the following lines to your ~/.
emacs file will enable real-time validation of XML input files:
(require 'rng-loc)
(add-to-list 'rng-schema-locating-files "~/openmc/schemas.xml")
Make sure to replace the last string on the second line with the path to the schemas.xml file in your own OpenMC
source directory.
4.3 Cross Section Configuration
In order to run a simulation with OpenMC, you will need cross section data for each nuclide or material in your problem.
OpenMC can be run in continuous-energy or multi-group mode.
In continuous-energy mode, OpenMC uses a native HDF5 format (see Nuclear Data File Formats) to store all nuclear
data. Pregenerated HDF5 libraries can be found at https://openmc.org; unless you have specific data needs, it is highly
recommended to use one of the pregenerated libraries. Alternatively, if you have ACE format data that was produced
with NJOY, such as that distributed with MCNP or Serpent, it can be converted to the HDF5 format using the using the
Python API. Several sources provide openly available ACE data including the ENDF/B, JEFF, and TENDL libraries
as well as the LANL Nuclear Data Team. In addition to tabulated cross sections in the HDF5 files, OpenMC relies on
windowed multipole data to perform on-the-fly Doppler broadening.
In multi-group mode, OpenMC utilizes an HDF5-based library format which can be used to describe nuclide- or
material-specific quantities.
4.3.1 Environment Variables
When openmc is run, it will look for several environment variables that indicate where cross sections can be found.
While the location of cross sections can also be indicated through the openmc.Materials.cross_sections attribute
(or in the materials.xml file), if you always use the same set of cross section data, it is often easier to just set an
environment variable that will be picked up by default every time OpenMC is run. The following environment variables
are used:
OPENMC_CROSS_SECTIONS
Indicates the path to the cross_sections.xml summary file that is used to locate HDF5 format cross section li-
braries if the user has not specified openmc.Materials.cross_sections (equivalently, the <cross_sections>
Element in materials.xml).
OPENMC_MG_CROSS_SECTIONS
Indicates the path to an HDF5 file that contains multi-group cross sections if the user has not specified openmc.
Materials.cross_sections (equivalently, the <cross_sections> Element in materials.xml).
To set these environment variables persistently, export them from your shell profile (.profile or .bashrc in bash).
4.3. Cross Section Configuration 135

4.3.2 Continuous-Energy Cross Sections
Using Pregenerated Libraries
Various evaluated nuclear data libraries have been processed into the HDF5 format required by OpenMC and can
be found at https://openmc.org. You can find both libraries generated by the OpenMC development team as well as
libraries based on ACE files distributed elsewhere. To use these libraries, download the archive file, unpack it, and
then set your OPENMC_CROSS_SECTIONS environment variable to the absolute path of the cross_sections.xml file
contained in the unpacked directory.
Manually Creating a Library from ACE files
The openmc.data module in the Python API enables users to directly convert ACE data to OpenMC’s HDF5 format
and create a corresponding cross_sections.xml file. For those who prefer to use the API directly, the openmc.data.
IncidentNeutron and openmc.data.ThermalScattering classes can be used to read ACE data and convert it to
HDF5. For continuous-energy incident neutron data, use the IncidentNeutron.from_ace() class method to read
in an existing ACE file and the IncidentNeutron.export_to_hdf5() method to write the data to an HDF5 file.
u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
u235.export_to_hdf5('U235.h5')
If you have multiple ACE files for the same nuclide at different temperatures, you can use the IncidentNeutron.
add_temperature_from_ace() method to append cross sections to an existing IncidentNeutron instance:
u235 = openmc.data.IncidentNeutron.from_ace('92235.710nc')
for suffix in [711, 712, 713, 714, 715, 716]:
u235.add_temperature_from_ace('92235.{}nc'.format(suffix))
u235.export_to_hdf5('U235.h5')
Similar methods exist for thermal scattering data:
light_water = openmc.data.ThermalScattering.from_ace('lwtr.20t')
for suffix in range(21, 28):
light_water.add_temperature_from_ace('lwtr.{}t'.format(suffix))
light_water.export_to_hdf5('lwtr.h5')
Once you have created corresponding HDF5 files for each of your ACE files, you can create a library and export it to
XML using the openmc.data.DataLibrary class:
library = openmc.data.DataLibrary()
library.register_file('U235.h5')
library.register_file('lwtr.h5')
...
library.export_to_xml()
At this point, you will have a cross_sections.xml file that you can use in OpenMC.
Hint: The IncidentNeutron class allows you to view/modify cross sections, secondary angle/energy distributions,
probability tables, etc. For a more thorough overview of the capabilities of this class, see the example notebook.

Manually Creating a Library from ENDF files
If you need to create a nuclear data library and you do not already have suitable ACE files or you need to
further customize the data (for example, adding more temperatures), the IncidentNeutron.from_njoy() and
ThermalScattering.from_njoy() methods can be used to create data instances by directly running NJOY. Both
methods require that you pass the name of ENDF file(s) that are passed on to NJOY. For example, to generate data for
Zr-92:
zr92 = openmc.data.IncidentNeutron.from_njoy('n-040_Zr_092.endf')
By default, data is produced at room temperature, 293.6 K. You can also specify a list of temperatures that you want
data at:
zr92 = openmc.data.IncidentNeutron.from_njoy(
'n-040_Zr_092.endf', temperatures=[300., 600., 1000.])
The IncidentNeutron.from_njoy() method assumes you have an executable named njoy available on your path.
If you want to explicitly name the executable, the njoy_exec optional argument can be used. Additionally, the stdout
argument can be used to show the progress of the NJOY run.
To generate a thermal scattering file, you need to specify both an ENDF incident neutron sub-library file as well as a
thermal neutron scattering sub-library file; for example:
light_water = openmc.data.ThermalScattering.from_njoy(
'neutrons/n-001_H_001.endf', 'thermal_scatt/tsl-HinH2O.endf')
Once you have instances of IncidentNeutron and ThermalScattering, a library can be created by using the
export_to_hdf5() methods and the DataLibrary class as described in Manually Creating a Library from ACE
files.
Enabling Resonance Scattering Treatments
In order for OpenMC to correctly treat elastic scattering in heavy nuclides where low-lying resonances might be present
(see Energy-Dependent Cross Section Model), the elastic scattering cross section at 0 K must be present. If the data
you are using was generated via IncidentNeutron.from_njoy(), you will already have 0 K elastic scattering cross
sections available. Otherwise, to add 0 K elastic scattering cross sections to an existing IncidentNeutron instance,
you can use the IncidentNeutron.add_elastic_0K_from_endf() method which requires an ENDF file for the
nuclide you are modifying:
u238 = openmc.data.IncidentNeutron.from_hdf5('U238.h5')
u238.add_elastic_0K_from_endf('n-092_U_238.endf')
u238.export_to_hdf5('U238_with_0K.h5')
With 0 K elastic scattering data present, you can turn on a resonance scattering method using Settings.
resonance_scattering.
Note: The process of reconstructing resonances and generating tabulated 0 K cross sections can be computation-
ally expensive, especially for nuclides like U-238 where thousands of resonances are present. Thus, running the
IncidentNeutron.add_elastic_0K_from_endf() method may take several minutes to complete.
4.3. Cross Section Configuration 137

Photon Cross Sections
Photon interaction data is needed to run OpenMC with photon transport enabled. Some of this data, namely
bremsstrahlung cross sections from Seltzer and Berger, mean excitation energy from the NIST ESTAR database, and
Compton profiles calculated by Biggs et al. and available in the Geant4 G4EMLOW data file, is distributed with
OpenMC. The rest is available from the NNDC, which provides ENDF data from the photo-atomic and atomic relax-
ation sublibraries of the ENDF/B-VII.1 library.
Most of the pregenerated HDF5 libraries available at https://openmc.org already have photon interaction data in-
cluded. If you are building a data library yourself, it is possible to use the Python API directly to convert photon
interaction data from an ENDF or ACE file to an HDF5 file. The openmc.data.IncidentPhoton class contains an
IncidentPhoton.from_ace() method that will generate photon data from an ACE table and an IncidentPhoton.
export_to_hdf5() method that writes the data to an HDF5 file:
u = openmc.data.IncidentPhoton.from_ace('92000.12p')
u.export_to_hdf5('U.h5')
Similarly, the IncidentPhoton.from_endf() method can be used to read photon data from an ENDF file. In this
case, both the photo-atomic and atomic relaxation sublibrary files are required:
u = openmc.data.IncidentPhoton.from_endf('photoat-092_U_000.endf',
'atom-092_U_000.endf')
Once the HDF5 files have been generated, a library can be created using the DataLibrary class as described in
Manually Creating a Library from ACE files.
4.3.3 Windowed Multipole Data
OpenMC is capable of using windowed multipole data for on-the-fly Doppler broadening. A comprehensive multipole
data library containing all nuclides in ENDF/B-VII.1 is available on GitHub. To obtain this library, download and
unpack an archive (.zip or .tag.gz) from GitHub. Once unpacked, you can use the openmc.data.DataLibrary class
to register the .h5 files as described in Manually Creating a Library from ACE files.
The official ENDF/B-VII.1 HDF5 library includes the windowed multipole library, so if you are using this library, the
windowed multipole data will already be available to you.
4.3.4 Multi-Group Cross Sections
Multi-group cross section libraries are generally tailored to the specific calculation to be performed. Therefore, at
this point in time, OpenMC is not distributed with any pre-existing multi-group cross section libraries. However, if
obtained or generated their own library, the user should set the OPENMC_MG_CROSS_SECTIONS environment variable
to the absolute path of the file library expected to used most frequently.
For an example of how to create a multi-group library, see the example notebook.

4.4 Basics of Using OpenMC
4.4.1 Running a Model
When you build and install OpenMC, you will have an openmc executable on your system. When you run openmc, the
first thing it will do is look for a set of XML files that describe the model you want to simulate. Three of these files are
required and another three are optional, as described below.
Required
Materials Specification – materials.xml
This file describes what materials are present in the problem and what they are composed of. Additionally, it
indicates where OpenMC should look for a cross section library.
Geometry Specification – geometry.xml
This file describes how the materials defined in materials.xml occupy regions of space. Physical volumes are
defined using constructive solid geometry, described in detail in Defining Geometry.
Settings Specification – settings.xml
This file indicates what mode OpenMC should be run in, how many particles to simulate, the source definition,
and a whole host of miscellaneous options.
Optional
Tallies Specification – tallies.xml
This file describes what physical quantities should be tallied during the simulation (fluxes, reaction rates, currents,
etc.).
Geometry Plotting Specification – plots.xml
This file gives specifications for producing slice or voxel plots of the geometry.
Warning: OpenMC models should be treated as code, and it is important to be careful with code from untrusted
sources.
eXtensible Markup Language (XML)
Unlike many other Monte Carlo codes which use an arbitrary-format ASCII file with “cards” to specify a particular
geometry, materials, and associated run settings, the input files for OpenMC are structured in a set of XML files. XML,
which stands for eXtensible Markup Language, is a simple format that allows data to be exchanged efficiently between
different programs and interfaces.
Anyone who has ever seen webpages written in HTML will be familiar with the structure of XML whereby “tags”
enclosed in angle brackets denote that a particular piece of data will follow. Let us examine the follow example:
<person>
<firstname>John</firstname>
<lastname>Smith</lastname>
<age>27</age>
<occupation>Health Physicist</occupation>
</person>
4.4. Basics of Using OpenMC 139

Here we see that the first tag indicates that the following data will describe a person. The nested tags firstname, lastname,
age, and occupation indicate characteristics about the person being described.
In much the same way, OpenMC input uses XML tags to describe the geometry, the materials, and settings for a
Monte Carlo simulation. Note that because the XML files have a well-defined structure, they can be validated using
the openmc-validate-xml script or using Emacs nXML mode.
Creating Input Files
The most rudimentary option for creating input files is to simply write them from scratch using the XML format spec-
ifications. This approach will feel familiar to users of other Monte Carlo codes such as MCNP and Serpent, with
the added bonus that the XML formats feel much more “readable”. Alternatively, input files can be generated using
OpenMC’s Python API, which is introduced in the following section.
4.4.2 Python API
OpenMC’s Python API defines a set of functions and classes that roughly correspond to elements in the XML files. For
example, the openmc.Cell Python class directly corresponds to the <cell> Element in XML. Each XML file itself
also has a corresponding class: openmc.Geometry for geometry.xml, openmc.Materials for materials.xml,
openmc.Settings for settings.xml, and so on. To create a model then, one creates instances of these classes and
then uses the export_to_xml() method, e.g., Geometry.export_to_xml(). Most scripts that generate a full model
will look something like the following:
# Create materials
materials = openmc.Materials()
...
materials.export_to_xml()
# Create geometry
geometry = openmc.Geometry()
...
geometry.export_to_xml()
# Assign simulation settings

settings = openmc.Settings()
...
settings.export_to_xml()
Once a model has been created and exported to XML, a simulation can be run either by calling openmc directly from
a shell or by using the openmc.run() function from Python.
Identifying Objects
In the XML user input files, each object (cell, surface, tally, etc.) has to be uniquely identified by a positive integer
(ID) in the same manner as MCNP and Serpent. In the Python API, integer IDs can be assigned but it is not strictly
required. When IDs are not explicitly assigned to instances of the OpenMC Python classes, they will be automatically
assigned.

4.4.3 Viewing and Analyzing Results
After a simulation has been completed by running openmc, you will have several output files that were created:
tallies.out
An ASCII file showing the mean and standard deviation of the mean for any user-defined tallies.
summary.h5
An HDF5 file with a complete description of the geometry and materials used in the simulation.
statepoint.#.h5
An HDF5 file with the complete results of the simulation, including tallies as well as the final source distribution.
This file can be used both to view/analyze results as well as restart a simulation if desired.
For a simple simulation with few tallies, looking at the tallies.out file might be sufficient. For anything more
complicated (plotting results, finding a subset of results, etc.), you will likely find it easier to work with the statepoint
file directly using the openmc.StatePoint class. For more details on working with statepoints, see Working with
State Points.
4.4.4 Physical Units
Unless specified otherwise, all length quantities are assumed to be in units of centimeters, all energy quantities are
assumed to be in electronvolts, and all time quantities are assumed to be in seconds.
Measure Default unit Symbol

length centimeter cm
energy electronvolt eV
time second s
4.4.5 ERSN-OpenMC Graphical User Interface
A third-party Java-based user-friendly graphical user interface for creating XML input files called ERSN-OpenMC is
developed and maintained by members of the Radiation and Nuclear Systems Group at the Faculty of Sciences Tetouan,
Morocco. The GUI also allows one to automatically download prerequisites for installing and running OpenMC.
4.5 Material Compositions
Materials in OpenMC are defined as a set of nuclides/elements at specified densities and are created using the openmc.
Material class. Once a material has been instantiated, nuclides can be added with Material.add_nuclide() and
elements can be added with Material.add_element(). Densities can be specified using atom fractions or weight
fractions. For example, to create a material and add Gd152 at 0.5 atom percent, you’d run:
mat.add_nuclide('Gd152', 0.5, 'ao')
The third argument to Material.add_nuclide() can also be ‘wo’ for weight percent. The densities specified for each
nuclide/element are relative and are renormalized based on the total density of the material. The total density is set
using the Material.set_density() method. The density can be specified in gram per cubic centimeter (‘g/cm3’),
atom per barn-cm (‘atom/b-cm’), or kilogram per cubic meter (‘kg/m3’), e.g.,
mat.set_density('g/cm3', 4.5)
4.5. Material Compositions 141

4.5.1 Natural Elements
The Material.add_element() method works exactly the same as Material.add_nuclide(), except that instead
of specifying a single isotope of an element, you specify the element itself. For example,
mat.add_element('C', 1.0)
This method can also accept case-insensitive element names such as
mat.add_element('aluminium', 1.0)
Internally, OpenMC stores data on the atomic masses and natural abundances of all known isotopes and then uses this
data to determine what isotopes should be added to the material. When the material is later exported to XML for use
by the openmc executable, you’ll see that any natural elements were expanded to the naturally-occurring isotopes.
The Material.add_element() method can also be used to add uranium at a specified enrichment through the en-
richment argument. For example, the following would add 3.2% enriched uranium to a material:
mat.add_element('U', 1.0, enrichment=3.2)
In addition to U235 and U238, concentrations of U234 and U236 will be present and are determined through a corre-
lation based on measured data.
It is also possible to perform enrichment of any element that is composed of two naturally-occurring isotopes (e.g., Li
or B) in terms of atomic percent. To invoke this, provide the additional argument enrichment_target to Material.
add_element(). For example the following would enrich B10 to 30ao%:
mat.add_element('B', 1.0, enrichment=30.0, enrichment_target='B10')
In order to enrich an isotope in terms of mass percent (wo%), provide the extra argument enrichment_type. For example
the following would enrich Li6 to 15wo%:
mat.add_element('Li', 1.0, enrichment=15.0, enrichment_target='Li6',

enrichment_type='wo')
Often, cross section libraries don’t actually have all naturally-occurring isotopes for a given element. For example, in
ENDF/B-VII.1, cross section evaluations are given for O16 and O17 but not for O18. If OpenMC is aware of what cross
sections you will be using (through the OPENMC_CROSS_SECTIONS environment variable), it will attempt to only put
isotopes in your model for which you have cross section data. In the case of oxygen in ENDF/B-VII.1, the abundance
of O18 would end up being lumped with O16.
4.5.2 Thermal Scattering Data
If you have a moderating material in your model like water or graphite, you should assign thermal scattering data (so-
called 𝑆(𝛼, 𝛽)) using the Material.add_s_alpha_beta() method. For example, to model light water, you would
need to add hydrogen and oxygen to a material and then assign the c_H_in_H2O thermal scattering data:
water = openmc.Material()
water.add_nuclide('H1', 2.0)
water.add_nuclide('O16', 1.0)
water.add_s_alpha_beta('c_H_in_H2O')
water.set_density('g/cm3', 1.0)

4.5.3 Naming Conventions
OpenMC uses the GNDS naming convention for nuclides, metastable states, and compounds:
Nuclides
SymA where “A” is the mass number (e.g., Fe56)
Elements
Sym0 (e.g., Fe0 or C0)
Excited states
SymA_eN (e.g., V51_e1 for the first excited state of Vanadium-51.) This is only used in decay data.
Metastable states
SymA_mN (e.g., Am242_m1 for the first excited state of Americium-242).
Compounds
c_String_Describing_Material (e.g., c_H_in_H2O). Used for thermal scattering data.
Important: The element syntax, e.g., C0, is only used when the cross section evaluation is an elemental evaluation,
like carbon in ENDF/B-VII.1! If you are adding an element via Material.add_element(), just use Sym.
4.5.4 Temperature
Some Monte Carlo codes define temperature implicitly through the cross section data, which is itself given only at a
particular temperature. In OpenMC, the material definition is decoupled from the specification of temperature. Instead,
temperatures are assigned to cells directly. Alternatively, a default temperature can be assigned to a material that is
to be applied to any cell where the material is used. In the absence of any cell or material temperature specification,
a global default temperature can be set that is applied to all cells and materials. Anytime a material temperature is
specified, it will override the global default temperature. Similarly, anytime a cell temperatures is specified, it will
override the material or global default temperature. All temperatures should be given in units of Kelvin.
To assign a default material temperature, one should use the temperature attribute, e.g.,
hot_fuel = openmc.Material()
hot_fuel.temperature = 1200.0 # temperature in Kelvin
Warning: MCNP users should be aware that OpenMC does not use the concept of cross section suffixes like
“71c” or “80c”. Temperatures in Kelvin should be assigned directly per material or per cell using the Material.
temperature or Cell.temperature attributes, respectively.
4.5.5 Material Mixtures
In OpenMC it is possible to mix any number of materials to create a new material with the correct nuclide composition
and density. The Material.mix_materials() method takes a list of materials and a list of their mixing fractions.
Mixing fractions can be provided as atomic fractions, weight fractions, or volume fractions. The fraction type can be
specified by passing ‘ao’, ‘wo’, or ‘vo’ as the third argument, respectively. For example, assuming the required materials
have already been defined, a MOX material with 3% plutonium oxide by weight could be created using the following:
mox = openmc.Material.mix_materials([uo2, puo2], [0.97, 0.03], 'wo')
4.5. Material Compositions 143

It should be noted that, if mixing fractions are specifed as atomic or weight fractions, the supplied fractions should
sum to one. If the fractions are specified as volume fractions, and the sum of the fractions is less than one, then the
remaining fraction is set as void material.
Warning: Materials with 𝑆(𝛼, 𝛽) thermal scattering data cannot be used in Material.mix_materials(). How-
ever, thermal scattering data can be added to a material created by Material.mix_materials().
4.5.6 Material Collections
The openmc executable expects to find a materials.xml file when it is run. To create this file, one needs to instantiate
the openmc.Materials class and add materials to it. The Materials class acts like a list (in fact, it is a subclass
of Python’s built-in list class), so materials can be added by passing a list to the constructor, using methods like
append(), or through the operator +=. Once materials have been added to the collection, it can be exported using the
Materials.export_to_xml() method.
materials.append(water)
materials += [uo2, zircaloy]
# This is equivalent
materials = openmc.Materials([water, uo2, zircaloy])
Cross Sections
OpenMC uses a file called cross_sections.xml to indicate where cross section data can be found on the filesystem. This
file serves the same role that xsdir does for MCNP or xsdata does for Serpent. Information on how to generate a
cross section listing file can be found in Manually Creating a Library from ACE files. Once you have a cross sections
file that has been generated, you can tell OpenMC to use this file either by setting Materials.cross_sections or by
setting the OPENMC_CROSS_SECTIONS environment variable to the path of the cross_sections.xml file. The former
approach would look like:
materials.cross_sections = '/path/to/cross_sections.xml'
4.6 Defining Geometry
4.6.1 Surfaces and Regions
The geometry of a model in OpenMC is defined using constructive solid geometry (CSG), also sometimes referred to
as combinatorial geometry. CSG allows a user to create complex regions using Boolean operators (intersection, union,
and complement) on simpler regions. In order to define a region that we can assign to a cell, we must first define
surfaces which bound the region. A surface is a locus of zeros of a function of Cartesian coordinates 𝑥, 𝑦, 𝑧, e.g.
• A plane perpendicular to the 𝑥 axis: 𝑥 − 𝑥0 = 0
• A cylinder parallel to the 𝑧 axis: (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝑅2 = 0
• A sphere: (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0

Defining a surface alone is not sufficient to specify a volume – in order to define an actual volume, one must reference
the half-space of a surface. A surface half-space is the region whose points satisfy a positive or negative inequality of
the surface equation. For example, for a sphere of radius one centered at the origin, the surface equation is 𝑓 (𝑥, 𝑦, 𝑧) =
𝑥2 + 𝑦 2 + 𝑧 2 − 1 = 0. Thus, we say that the negative half-space of the sphere, is defined as the collection of points
satisfying 𝑓 (𝑥, 𝑦, 𝑧) < 0, which one can reason is the inside of the sphere. Conversely, the positive half-space of the
sphere would correspond to all points outside of the sphere, satisfying 𝑓 (𝑥, 𝑦, 𝑧) > 0.
In the Python API, surfaces are created via subclasses of openmc.Surface. The available surface types and their
corresponding classes are listed in the following table.
Table 1: Surface types available in OpenMC.

Surface Equation Class
Plane perpendicular to 𝑥- 𝑥 − 𝑥0 = 0 openmc.XPlane
axis
Plane perpendicular to 𝑦-axis 𝑦 − 𝑦0 = 0 openmc.YPlane
Plane perpendicular to 𝑧-axis 𝑧 − 𝑧0 = 0 openmc.ZPlane
Arbitrary plane 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷 openmc.Plane
Infinite cylinder parallel to 𝑥- (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0 openmc.
axis XCylinder
Infinite cylinder parallel to 𝑦- (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0 openmc.
axis YCylinder
Infinite cylinder parallel to 𝑧- (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝑅2 = 0 openmc.
axis ZCylinder
Sphere (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 = 0 openmc.Sphere
Cone parallel to the 𝑥-axis (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 (𝑥 − 𝑥0 )2 = 0 openmc.XCone
Cone parallel to the 𝑦-axis (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 − 𝑅2 (𝑦 − 𝑦0 )2 = 0 openmc.YCone
Cone parallel to the 𝑧-axis (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝑅2 (𝑧 − 𝑧0 )2 = 0 openmc.ZCone
General quadric surface 𝐴𝑥2 +𝐵𝑦 2 +𝐶𝑧 2 +𝐷𝑥𝑦+𝐸𝑦𝑧+𝐹 𝑥𝑧+𝐺𝑥+𝐻𝑦+𝐽𝑧+𝐾 = openmc.
0 √ Quadric
( (𝑦−𝑦 )2 +(𝑧−𝑧 )2 −𝐴)2
Torus parallel to the 𝑥-axis (𝑥 − 𝑥0 )2 /𝐵 2 + √ 0
𝐶2
0
−1=0 openmc.XTorus
( (𝑥−𝑥0 ) +(𝑧−𝑧0 )2 −𝐴)2
2
Torus parallel to the 𝑦-axis 2 2
(𝑦 − 𝑦0 ) /𝐵 + √ 𝐶2 −1=0 openmc.YTorus
( (𝑥−𝑥0 )2 +(𝑦−𝑦0 )2 −𝐴)2
Torus parallel to the 𝑧-axis (𝑧 − 𝑧0 )2 /𝐵 2 + 𝐶2 −1=0 openmc.ZTorus
Each surface is characterized by several parameters. As one example, the parameters for a sphere are the 𝑥, 𝑦, 𝑧 coor-
dinates of the center of the sphere and the radius of the sphere. All of these parameters can be set either as optional
keyword arguments to the class constructor or via attributes:
sphere = openmc.Sphere(r=10.0)
sphere = openmc.Sphere()
sphere.r = 10.0
Once a surface has been created, half-spaces can be obtained by applying the unary - or + operators, corresponding to
the negative and positive half-spaces, respectively. For example:
>>> sphere = openmc.Sphere(r=10.0)

>>> inside_sphere = -sphere
>>> outside_sphere = +sphere
>>> type(inside_sphere)
<class 'openmc.surface.Halfspace'>
4.6. Defining Geometry 145

Instances of openmc.Halfspace can be combined together using the Boolean operators & (intersection), | (union),
and ~ (complement):
>>> inside_sphere = -openmc.Sphere()

>>> above_plane = +openmc.ZPlane()
>>> northern_hemisphere = inside_sphere & above_plane
>>> type(northern_hemisphere)
<class 'openmc.region.Intersection'>
The & operator can be thought of as a logical AND, the | operator as a logical OR, and the ~ operator as a logical NOT.
Thus, if you wanted to create a region that consists of the space for which −4 < 𝑧 < −3 or 3 < 𝑧 < 4, a union could
be used:
>>> region_bottom = +openmc.ZPlane(-4) & -openmc.ZPlane(-3)

>>> region_top = +openmc.ZPlane(3) & -openmc.ZPlane(4)
>>> combined_region = region_bottom | region_top
Half-spaces and the objects resulting from taking the intersection, union, and/or complement or half-spaces are all
considered regions that can be assigned to cells.
For many regions, a bounding-box can be determined automatically:
>>> northern_hemisphere.bounding_box
(array([-1., -1., 0.]), array([1., 1., 1.]))
While a bounding box can be determined for regions involving half-spaces of spheres, cylinders, and axis-aligned
planes, it generally cannot be determined if the region involves cones, non-axis-aligned planes, or other exotic second-
order surfaces. For example, the openmc.model.hexagonal_prism() function returns the interior region of a hexag-
onal prism; because it is bounded by a openmc.Plane, trying to get its bounding box won’t work:
>>> hex = openmc.model.hexagonal_prism()

>>> hex.bounding_box
(array([-0.8660254, -inf, -inf]),
array([ 0.8660254, inf, inf]))
Boundary Conditions
When a surface is created, by default particles that pass through the surface will consider it to be transmissive, i.e.,
they pass through the surface freely. If your model does not extend to infinity in all spatial dimensions, you may want
to specify different behavior for particles passing through a surface. To specify a vacuum boundary condition, simply
change the Surface.boundary_type attribute to ‘vacuum’:
outer_surface = openmc.Sphere(r=100.0, boundary_type='vacuum')
outer_surface = openmc.Sphere(r=100.0)
outer_surface.boundary_type = 'vacuum'
Reflective and periodic boundary conditions can be set with the strings ‘reflective’ and ‘periodic’. Vacuum and reflective
boundary conditions can be applied to any type of surface. Periodic boundary conditions can be applied to pairs of
planar surfaces. If there are only two periodic surfaces they will be matched automatically. Otherwise it is necessary
to specify pairs explicitly using the Surface.periodic_surface attribute as in the following example:

p1 = openmc.Plane(a=0.3, b=5.0, d=1.0, boundary_type='periodic')

p2 = openmc.Plane(a=0.3, b=5.0, d=-1.0, boundary_type='periodic')
p1.periodic_surface = p2
Both rotational and translational periodic boundary conditions are specified in the same fashion. If both planes have
the same normal vector, a translational periodicity is assumed; rotational periodicity is assumed otherwise. Currently,
only rotations about the 𝑧-axis are supported.
For a rotational periodic BC, the normal vectors of each surface must point inwards—towards the valid geometry. For
example, a XPlane and YPlane would be valid for a 90-degree periodic rotation if the geometry lies in the first quadrant
of the Cartesian grid. If the geometry instead lies in the fourth quadrant, the YPlane must be replaced by a Plane with
the normal vector pointing in the −𝑦 direction.
4.6.2 Cells
Once you have a material created and a region of space defined, you need to define a cell that assigns the material to
the region. Cells are created using the openmc.Cell class:
fuel = openmc.Cell(fill=uo2, region=pellet)
fuel = openmc.Cell()
fuel.fill = uo2
fuel.region = pellet
In this example, an instance of openmc.Material is assigned to the Cell.fill attribute. One can also fill a cell with
a universe or lattice. If you provide no fill to a cell or assign a value of None, it will be treated as a “void” cell with no
material within. Particles are allowed to stream through the cell but will undergo no collisions:
# This cell will be filled with void on export to XML

gap = openmc.Cell(region=pellet_gap)
The classes Halfspace, Intersection, Union, and Complement and all instances of openmc.Region and can be
assigned to the Cell.region attribute.
4.6.3 Universes
Similar to MCNP and Serpent, OpenMC is capable of using universes, collections of cells that can be used as re-
peatable units of geometry. At a minimum, there must be one “root” universe present in the model. To define a
universe, an instance of openmc.Universe is created and then cells can be added using the Universe.add_cells()
or Universe.add_cell() methods. Alternatively, a list of cells can be specified in the constructor:
universe = openmc.Universe(cells=[cell1, cell2, cell3])
universe = openmc.Universe()
universe.add_cells([cell1, cell2])
universe.add_cell(cell3)
Universes are generally used in three ways:

1. To be assigned to a Geometry object (see Exporting a Geometry Model),
2. To be assigned as the fill for a cell via the Cell.fill attribute, and

3. To be used in a regular arrangement of universes in a lattice.

Once a universe is constructed, it can actually be used to determine what cell or material is found at a given location by
using the Universe.find() method, which returns a list of universes, cells, and lattices which are traversed to find a
given point. The last element of that list would contain the lowest-level cell at that location:
>>> universe.find((0., 0., 0.))[-1]

Cell
ID = 10000
Name = cell 1
Fill = Material 10000
Region = -10000
Rotation = None
Temperature = None
Translation = None
As you are building a geometry, it is also possible to display a plot of single universe using the Universe.plot()
method. This method requires that you have matplotlib installed.
4.6.4 Lattices
Many particle transport models involve repeated structures that occur in a regular pattern such as a rectangular or
hexagonal lattice. In such a case, it would be cumbersome to have to define the boundaries of each of the cells to be
filled with a universe. OpenMC provides a means to define lattice structures through the openmc.RectLattice and
openmc.HexLattice classes.
Rectangular Lattices
A rectangular lattice defines a two-dimensional or three-dimensional array of universes that are filled into rectangular
prisms (lattice elements) each of which has the same width, length, and height. To completely define a rectangular
lattice, one needs to specify
• The coordinates of the lower-left corner of the lattice (RectLattice.lower_left),
• The pitch of the lattice, i.e., the distance between the center of adjacent lattice elements (RectLattice.pitch),
• What universes should fill each lattice element (RectLattice.universes), and
• A universe that is used to fill any lattice position outside the well-defined portion of the lattice (RectLattice.
outer).
For example, to create a 3x3 lattice centered at the origin in which each lattice element is 5cm by 5cm and is filled by
a universe u, one could run:
lattice = openmc.RectLattice()
lattice.lower_left = (-7.5, -7.5)
lattice.pitch = (5.0, 5.0)
lattice.universes = [[u, u, u],
[u, u, u],
[u, u, u]]
Note that because this is a two-dimensional lattice, the lower-left coordinates and pitch only need to specify the 𝑥, 𝑦
values. The order that the universes appear is such that the first row corresponds to lattice elements with the highest 𝑦
-value. Note that the RectLattice.universes attribute expects a doubly-nested iterable of type openmc.Universe
— this can be normal Python lists, as shown above, or a NumPy array can be used as well:

lattice.universes = np.tile(u, (3, 3))
For a three-dimensional lattice, the 𝑥, 𝑦, 𝑧 coordinates of the lower-left coordinate need to be given and the pitch should
also give dimensions for all three axes. For example, to make a 3x3x3 lattice where the bottom layer is universe u, the
middle layer is universe q and the top layer is universe z would look like:
lat3d = openmc.RectLattice()
lat3d.lower_left = (-7.5, -7.5, -7.5)
lat3d.pitch = (5.0, 5.0, 5.0)
lat3d.universes = [
[[u, u, u],
[u, u, u],
[u, u, u]],
[[q, q, q],
[q, q, q],
[q, q, q]],
[[z, z, z],
[z, z, z]
[z, z, z]]]
Again, using NumPy can make things easier:
lat3d.universes = np.empty((3, 3, 3), dtype=openmc.Universe)

lat3d.universes[0, ...] = u
lat3d.universes[1, ...] = q
lat3d.universes[2, ...] = z
Finally, it’s possible to specify that lattice positions that aren’t normally without the bounds of the lattice be filled
with an “outer” universe. This allows one to create a truly infinite lattice if desired. An outer universe is set with the
RectLattice.outer attribute.
Hexagonal Lattices
OpenMC also allows creation of 2D and 3D hexagonal lattices. Creating a hexagonal lattice is similar to creating a
rectangular lattice with a few differences:
• The center of the lattice must be specified (HexLattice.center).
• For a 2D hexagonal lattice, a single value for the pitch should be specified, although it still needs to appear in a
list. For a 3D hexagonal lattice, the pitch in the radial and axial directions should be given.
• For a hexagonal lattice, the HexLattice.universes attribute cannot be given as a NumPy array for reasons
explained below.
• As with rectangular lattices, the HexLattice.outer attribute will specify an outer universe.
For a 2D hexagonal lattice, the HexLattice.universes attribute should be set to a two-dimensional list of universes
filling each lattice element. Each sub-list corresponds to one ring of universes and is ordered from the outermost ring
to the innermost ring. The universes within each sub-list are ordered from the “top” (position with greatest y value)
and proceed in a clockwise fashion around the ring. The HexLattice.show_indices() static method can be used
to help figure out how to place universes:
>>> print(openmc.HexLattice.show_indices(3))
(0, 0)
(0,11) (0, 1)
(continues on next page)

(continued from previous page)

(0,10) (1, 0) (0, 2)
(1, 5) (1, 1)
(0, 9) (2, 0) (0, 3)
(1, 4) (1, 2)
(0, 8) (1, 3) (0, 4)
(0, 7) (0, 5)
(0, 6)
Note that by default, hexagonal lattices are positioned such that each lattice element has two faces that are parallel to
the 𝑦 axis. As one example, to create a three-ring lattice centered at the origin with a pitch of 10 cm where all the lattice
elements centered along the 𝑦 axis are filled with universe u and the remainder are filled with universe q, the following
code would work:
hexlat = openmc.HexLattice()
hexlat.center = (0, 0)
hexlat.pitch = [10]
outer_ring = [u, q, q, q, q, q, u, q, q, q, q, q]
middle_ring = [u, q, q, u, q, q]
inner_ring = [u]
hexlat.universes = [outer_ring, middle_ring, inner_ring]
If you need to create a hexagonal boundary (composed of six planar surfaces) for a hexagonal lattice, openmc.model.
hexagonal_prism() can be used.
4.6.5 Exporting a Geometry Model
Once you have finished building your geometry by creating surfaces, cell, and, if needed, lattices, the last step is to
create an instance of openmc.Geometry and export it to an XML file that the openmc executable can read using the
Geometry.export_to_xml() method. This can be done as follows:
geom = openmc.Geometry(root_univ)
geom.export_to_xml()
geom = openmc.Geometry()
geom.root_universe = root_univ
Note that it’s not strictly required to manually create a root universe. You can also pass a list of cells to the openmc.
Geometry constructor and it will handle creating the unverse:
geom = openmc.Geometry([cell1, cell2, cell3])


4.6.6 Using CAD-based Geometry
Defining Geometry
OpenMC relies on the Direct Accelerated Geometry Monte Carlo (DAGMC) to represent CAD-based geometry in
a surface mesh format. DAGMC geometries are applied as universes in the OpenMC geometry file. A geometry
represented entirely by a DAGMC geometry will contain only the DAGMC universe. Using a openmc.DAGMCUniverse
looks like the following:
dag_univ = openmc.DAGMCUniverse(filename='dagmc.h5m')
geometry = openmc.Geometry(dag_univ)
geometry.export_to_xml()
The resulting geometry.xml file will be:
<?xml version='1.0' encoding='utf-8'?>

<geometry>
<dagmc auto_ids="false" filename="dagmc.h5m" id="1" name="" />
</geometry>
DAGMC universes can also be used to fill CSG cells or lattice cells in a geometry:
cell.fill = dagmc_univ
It is important in these cases to understand the DAGMC model’s position with respect to the CSG geometry. DAGMC
geometries can be plotted with OpenMC to verify that the model matches one’s expectations.
Note: DAGMC geometries used in OpenMC are currently required to be clean, meaning that all surfaces have been
imprinted and merged successfully and that the model is watertight. Future implementations of DAGMC geometry
will support small volume overlaps and un-merged surfaces.
Cell, Surface, and Material IDs
By default, DAGMC applies cell and surface IDs defined by the CAD engine that the model originated in. If these
IDs overlap with IDs in the CSG ID space, this will result in an error. However, the auto_ids property of a DAGMC
universe can be set to set DAGMC cell and surface IDs by appending to the existing CSG cell ID space in the OpenMC
model.
Similar options exist for the material IDs of DAGMC models. If DAGMC material assignments are based on natively
defined OpenMC materials, no further work is required. If DAGMC materials are assigned using the University of
Wisconsin Unified Workflow (UWUW), however, material IDs in the UWUW material library may overlap with those
used in the CSG geometry. In this case, overlaps in the UWUW and OpenMC material ID space will cause an error.
To automatically resolve these ID overlaps, auto_ids can be set to True to append the UWUW material IDs to the
OpenMC material ID space.

4.6.7 Calculating Atoms Content
If the total volume occupied by all instances of a cell in the geometry is known by the user, it is possible to assign this
volume to a cell without performing a stochastic volume calculation:
from uncertainties import ufloat
# Set known total volume in [cc]

cell = openmc.Cell()
cell.volume = 17.0
# Set volume if it is known with some uncertainty

cell.volume = ufloat(17.0, 0.1)
Once a volume is set, and a cell is filled with a material or distributed materials, it is possible to use the atoms() method
to obtain a dictionary of nuclides and their total number of atoms in all instances of a cell (e.g. {'H1': 1.0e22,
'O16': 0.5e22, ...}):
cell = openmc.Cell(fill = u02)

cell.volume = 17.0
O16_atoms = cell.atoms['O16']
4.7 Execution Settings
Once you have created the materials and geometry for your simulation, the last step to have a complete model is
to specify execution settings through the openmc.Settings class. At a minimum, you need to specify a source
distribution and how many particles to run. Many other execution settings can be set using the openmc.Settings
object, but they are generally optional.
4.7.1 Run Modes
The Settings.run_mode attribute controls what run mode is used when openmc is executed. There are five different
run modes that can be specified:
‘eigenvalue’
Runs a 𝑘 eigenvalue simulation. See Eigenvalue Calculations for a full description of eigenvalue calculations.
In this mode, the Settings.source specifies a starting source that is only used for the first fission generation.
‘fixed source’
Runs a fixed-source calculation with a specified external source, specified in the Settings.source attribute.
‘volume’
Runs a stochastic volume calculation.
‘plot’
Generates slice or voxel plots (see Geometry Visualization).
‘particle restart’
Simulate a single source particle using a particle restart file.
So, for example, to specify that OpenMC should be run in fixed source mode, you would need to instantiate a openmc.
Settings object and assign the Settings.run_mode attribute:

settings.run_mode = 'fixed source'
If you don’t specify a run mode, the default run mode is ‘eigenvalue’.
4.7.2 Run Strategy
For a fixed source simulation, the total number of source particle histories simulated is broken up into a number of
batches, each corresponding to a realization of the tally random variables. Thus, you need to specify both the number
of batches (Settings.batches) as well as the number of particles per batch (Settings.particles).
For a 𝑘 eigenvalue simulation, particles are grouped into fission generations, as described in Eigenvalue Calculations.
Successive fission generations can be combined into a batch for statistical purposes. By default, a batch will consist
of only a single fission generation, but this can be changed with the Settings.generations_per_batch attribute.
For problems with a high dominance ratio, using multiple generations per batch can help reduce underprediction of
variance, thereby leading to more accurate confidence intervals. Tallies should not be scored to until the source distri-
bution converges, as described in Method of Successive Generations, which may take many generations. To specify the
number of batches that should be discarded before tallies begin to accumulate, use the Settings.inactive attribute.
The following example shows how one would simulate 10000 particles per generation, using 10 generations per batch,
150 total batches, and discarding 5 batches. Thus, a total of 145 active batches (or 1450 generations) will be used for
accumulating tallies.
settings.particles = 10000
settings.generations_per_batch = 10
settings.batches = 150
settings.inactive = 5
Number of Batches
In general, the stochastic uncertainty in your simulation results is directly related to how many total active particles are
simulated (the product of the number of active batches, number of generations per batch, and number of particles). At
a minimum, you should use enough active batches so that the central limit theorem is satisfied (about 30). Otherwise,
reducing the overall uncertainty in your√ simulation by a factor of 2 will require using 4 times as many batches (since
the standard deviation decreases as 1/ 𝑁 ).
Number of Inactive Batches
For 𝑘 eigenvalue simulations, the source distribution is not known a priori. Thus, a “guess” of the source distribution
is made and then iterated on, with the source evolving closer to the true distribution at each iteration. Once the source
distribution has converged, it is then safe to start accumulating tallies. Consequently, a preset number of inactive batches
are run before the active batches (where tallies are turned on) begin. The number of inactive batches necessary to reach
a converged source depends on the spatial extent of the problem, its dominance ratio, what boundary conditions are
used, and many other factors. For small problems, using 50–100 inactive batches is likely sufficient. For larger models,
many hundreds of inactive batches may be necessary. Users are recommended to use the Shannon entropy diagnostic
as a way of determining how many inactive batches are necessary.
Specifying the initial source used for the very first batch is described in below. Although the initial source is arbitrary
in the sense that any source will eventually converge to the correct distribution, using a source guess that is closer to
the actual converged source distribution will translate into needing fewer inactive batches (and hence less simulation
time).
4.7. Execution Settings 153

For fixed source simulations, the source distribution is known exactly, so no inactive batches are needed. In this case
the Settings.inactive attribute can be omitted since it defaults to zero.
Number of Generations per Batch
The standard deviation of tally results is calculated assuming that all realizations (batches) are independent. However, in
a 𝑘 eigenvalue calculation, the source sites for each batch are produced from fissions in the preceding batch, resulting in
a correlation between successive batches. This correlation can result in an underprediction of the variance. That is, the
variance reported is actually less than the true variance. To mitigate this effect, OpenMC allows you to group together
multiple fission generations into a single batch for statistical purposes, rather than having each fission generation be a
separate batch, which is the default behavior.
Number of Particles per Generation
There are several considerations for choosing the number of particles per generation. As discussed in Number of
Batches, the total number of active particles will determine the level of stochastic uncertainty in simulation results,
so using a higher number of particles will result in less uncertainty. For parallel simulations that use OpenMP and/or
MPI, the number of particles per generation should be large enough to ensure good load balancing between threads.
For example, if you are running on a single processor with 32 cores, each core should have at least 100 particles or so
(i.e., at least 3,200 particles per generation should be used). Using a larger number of particles per generation can also
help reduce the cost of synchronization and communication between batches. For 𝑘 eigenvalue calculations, experts
recommend at least 10,000 particles per generation to avoid any bias in the estimate of 𝑘 eigenvalue or tallies.
4.7.3 External Source Distributions
External source distributions can be specified through the Settings.source attribute. If you have a single external
source, you can create an instance of openmc.Source and use it to set the Settings.source attribute. If you have
multiple external sources with varying source strengths, Settings.source should be set to a list of openmc.Source
objects.
The openmc.Source class has four main attributes that one can set: Source.space, which defines the spatial distribu-
tion, Source.angle, which defines the angular distribution, Source.energy, which defines the energy distribution,
and Source.time, which defines the time distribution.
The spatial distribution can be set equal to a sub-class of openmc.stats.Spatial; common choices are openmc.
stats.Point or openmc.stats.Box. To independently specify distributions in the 𝑥, 𝑦, and 𝑧 coordinates, you can
use openmc.stats.CartesianIndependent. To independently specify distributions using spherical or cylindrical
coordinates, you can use openmc.stats.SphericalIndependent or openmc.stats.CylindricalIndependent,
respectively.
The angular distribution can be set equal to a sub-class of openmc.stats.UnitSphere such as openmc.stats.
Isotropic, openmc.stats.Monodirectional, or openmc.stats.PolarAzimuthal. By default, if no angular
distribution is specified, an isotropic angular distribution is used. As an example of a non-trivial angular distribution,
the following code would create a conical distribution with an aperture of 30 degrees pointed in the positive x direction:
from math import pi, cos

aperture = 30.0
mu = openmc.stats.Uniform(cos(aperture/2), 1.0)
phi = openmc.stats.Uniform(0.0, 2*pi)
angle = openmc.stats.PolarAzimuthal(mu, phi, reference_uvw=(1., 0., 0.))

The energy distribution can be set equal to any univariate probability distribution. This could be a probability mass func-
tion (openmc.stats.Discrete), a Watt fission spectrum (openmc.stats.Watt), or a tabular distribution (openmc.
stats.Tabular). By default, if no energy distribution is specified, a Watt fission spectrum with 𝑎 = 0.988 MeV and
𝑏 = 2.249 MeV -1 is used.
The time distribution can be set equal to any univariate probability distribution. This could be a probability mass
function (openmc.stats.Discrete), a uniform distribution (openmc.stats.Uniform), or a tabular distribution
(openmc.stats.Tabular). By default, if no time distribution is specified, particles are started at 𝑡 = 0.
As an example, to create an isotropic, 10 MeV monoenergetic source uniformly distributed over a cube centered at the
origin with an edge length of 10 cm, and emitting a pulse of particles from 0 to 10 µs, one would run:
source = openmc.Source()
source.space = openmc.stats.Box((-5, -5, -5), (5, 5, 5))
source.angle = openmc.stats.Isotropic()
source.energy = openmc.stats.Discrete([10.0e6], [1.0])
source.time = openmc.stats.Uniform(0, 1e-6)
settings.source = source
The openmc.Source class also has a Source.strength attribute that indicates the relative strength of a source dis-
tribution if multiple are used. For example, to create two sources, one that should be sampled 70% of the time and
another that should be sampled 30% of the time:
src1 = openmc.Source()
src1.strength = 0.7
...
src2 = openmc.Source()
src2.strength = 0.3
...
settings.source = [src1, src2]
Finally, the Source.particle attribute can be used to indicate the source should be composed of particles other than
neutrons. For example, the following would generate a photon source:
source = openmc.Source()
source.particle = 'photon'
...
settings.source = source
For a full list of all classes related to statistical distributions, see openmc.stats – Statistics.
File-based Sources
OpenMC can use a pregenerated HDF5 source file by specifying the filename argument to openmc.Source:
settings.source = openmc.Source(filename='source.h5')
Statepoint and source files are generated automatically when a simulation is run and can be used as the starting source
in a new simulation. Alternatively, a source file can be manually generated with the openmc.write_source_file()
function. This is particularly useful for coupling OpenMC with another program that generates a source to be used in
OpenMC.

A source file based on particles that cross one or more surfaces can be generated during a simulation using the
Settings.surf_source_write attribute:
settings.surf_source_write = {
'surfaces_ids': [1, 2, 3],
'max_particles': 10000
}
In this example, at most 10,000 source particles are stored when particles cross surfaces with IDs of 1, 2, or 3.
Custom Sources
It is often the case that one may wish to simulate a complex source distribution that is not possible to represent with the
classes described above. For these situations, it is possible to define a complex source class containing an externally
defined source function that is loaded at runtime. A simple example source is shown below.
#include <memory> // for unique_ptr
#include "openmc/random_lcg.h"
#include "openmc/source.h"
#include "openmc/particle.h"
class CustomSource : public openmc::Source

{
openmc::SourceSite sample(uint64_t* seed) const
{
openmc::SourceSite particle;
// weight
particle.particle = openmc::ParticleType::neutron;
particle.wgt = 1.0;
// position
double angle = 2.0 * M_PI * openmc::prn(seed);
double radius = 3.0;
particle.r.x = radius * std::cos(angle);
particle.r.y = radius * std::sin(angle);
particle.r.z = 0.0;
// angle
particle.u = {1.0, 0.0, 0.0};
particle.E = 14.08e6;
particle.delayed_group = 0;
return particle;
}
};
extern "C" std::unique_ptr<CustomSource> openmc_create_source(std::string parameters)

{
return std::make_unique<CustomSource>();
}
The above source creates monodirectional 14.08 MeV neutrons that are distributed in a ring with a 3 cm radius. This
routine is not particularly complex, but should serve as an example upon which to build more complicated sources.

Note: The source class must inherit from openmc::Source and implement a sample() function.
Note: The openmc_create_source() function signature must be declared extern "C".
Note: You should only use the openmc::prn() random number generator.
In order to build your external source, you will need to link it against the OpenMC shared library. This can be done by
writing a CMakeLists.txt file:
cmake_minimum_required(VERSION 3.3 FATAL_ERROR)

project(openmc_sources CXX)
add_library(source SHARED source_ring.cpp)
find_package(OpenMC REQUIRED HINTS <path to openmc>)
target_link_libraries(source OpenMC::libopenmc)
After running cmake and make, you will have a libsource.so (or .dylib) file in your build directory. Setting the openmc.
Source.library attribute to the path of this shared library will indicate that it should be used for sampling source
particles at runtime.
Custom Parameterized Sources
Some custom sources may have values (parameters) that can be changed between runs. This is supported by using the
openmc_create_source() function to pass parameters defined in the openmc.Source.parameters attribute to the
source class when it is created:
#include <memory> // for unique_ptr
#include "openmc/source.h"
#include "openmc/particle.h"
class CustomSource : public openmc::Source {

public:
CustomSource(double energy) : energy_{energy} { }
// Samples from an instance of this class.

openmc::SourceSite sample(uint64_t* seed) const
{
openmc::SourceSite particle;
// weight
particle.particle = openmc::ParticleType::neutron;
particle.wgt = 1.0;
// position
particle.r.x = 0.0;
particle.r.y = 0.0;
particle.r.z = 0.0;
// angle
particle.u = {1.0, 0.0, 0.0};
particle.E = this->energy_;


particle.delayed_group = 0;
return particle;
}
private:
double energy_;
};
extern "C" std::unique_ptr<CustomSource> openmc_create_source(std::string parameter) {

double energy = std::stod(parameter);
return std::make_unique<CustomSource>(energy);
}
As with the basic custom source functionality, the custom source library location must be provided in the openmc.
Source.library attribute.
4.7.4 Shannon Entropy
To assess convergence of the source distribution, the scalar Shannon entropy metric is often used in Monte Carlo
codes. OpenMC also allows you to calculate Shannon entropy at each generation over a specified mesh, created using
the openmc.RegularMesh class. After instantiating a RegularMesh , you need to specify the lower-left coordinates
of the mesh (RegularMesh.lower_left), the number of mesh cells in each direction (RegularMesh.dimension)
and either the upper-right coordinates of the mesh (RegularMesh.upper_right) or the width of each mesh cell
(RegularMesh.width). Once you have a mesh, simply assign it to the Settings.entropy_mesh attribute.
entropy_mesh = openmc.RegularMesh()
entropy_mesh.lower_left = (-50, -50, -25)
entropy_mesh.upper_right = (50, 50, 25)
entropy_mesh.dimension = (8, 8, 8)
settings.entropy_mesh = entropy_mesh
If you’re unsure of what bounds to use for the entropy mesh, you can try getting a bounding box for the entire geometry
using the Geometry.bounding_box property:
geom = openmc.Geometry()
...
m = openmc.RegularMesh()
m.lower_left, m.upper_right = geom.bounding_box
m.dimension = (8, 8, 8)
settings.entropy_mesh = m

4.7.5 Photon Transport
In addition to neutrons, OpenMC is also capable of simulating the passage of photons through matter. This al-
lows the modeling of photon production from neutrons as well as pure photon calculations. The Settings.
photon_transport attribute can be used to enable photon transport:
settings.photon_transport = True
The way in which OpenMC handles secondary charged particles can be specified with the Settings.
electron_treatment attribute. By default, the thick-target bremsstrahlung (TTB) approximation is used to gen-
erate bremsstrahlung radiation emitted by electrons and positrons created in photon interactions. To neglect secondary
bremsstrahlung photons and instead deposit all energy from electrons locally, the local energy deposition option can
be selected:
settings.electron_treatment = 'led'
Note: Some features related to photon transport are not currently implemented, including:
• Tallying photon energy deposition.
• Generating a photon source from a neutron calculation that can be used for a later fixed source photon calculation.
• Photoneutron reactions.
4.7.6 Generation of Output Files
A number of attributes of the openmc.Settings class can be used to control what files are output and how often.
First, there is the Settings.output attribute which takes a dictionary having keys ‘summary’, ‘tallies’, and ‘path’.
The first two keys controls whether a summary.h5 and tallies.out file are written, respectively (see Viewing and
Analyzing Results for a description of those files). By default, output files are written to the current working directory;
this can be changed by setting the ‘path’ key. For example, if you want to disable the tallies.out file and write the
summary.h5 to a directory called ‘results’, you’d specify the Settings.output dictionary as:
settings.output = {
'tallies': False,
'path': 'results'
}
Generation of statepoint and source files is handled separately through the Settings.statepoint and Settings.
sourcepoint attributes. Both of those attributes expect dictionaries and have a ‘batches’ key which indicates at which
batches statepoints and source files should be written. Note that by default, the source is written as part of the statepoint
file; this behavior can be changed by the ‘separate’ and ‘write’ keys of the Settings.sourcepoint dictionary, the
first of which indicates whether the source should be written to a separate file and the second of which indicates whether
the source should be written at all.
As an example, to write a statepoint file every five batches:
settings.batches = n
settings.statepoint = {'batches': range(5, n + 5, 5)}

Particle Track Files
OpenMC can generate a particle track file that contains track information (position, direction, energy, time, weight,
cell ID, and material ID) for each state along a particle’s history. There are two ways to indicate which particles and/or
how many particles should have their tracks written. First, you can identify specific source particles by their batch,
generation, and particle ID numbers:
settings.tracks = [
(1, 1, 50),
(2, 1, 30),
(5, 1, 75)
]
In this example, track information would be written for the 50th particle in the 1st generation of batch 1, the 30th
particle in the first generation of batch 2, and the 75th particle in the 1st generation of batch 5. Unless you are using
more than one generation per batch (see Run Strategy), the generation number should be 1. Alternatively, you can run
OpenMC in a mode where track information is written for all particles, up to a user-specified limit:
openmc.run(tracks=True)
In this case, you can control the maximum number of source particles for which tracks will be written as follows:
settings.max_tracks = 1000
Particle track information is written to the tracks.h5 file, which can be analyzed using the Tracks class:
>>> tracks = openmc.Tracks('tracks.h5')

>>> tracks
[<Track (1, 1, 50): 151 particles>,
<Track (2, 1, 30): 191 particles>,
<Track (5, 1, 75): 81 particles>]
Each Track object stores a list of track information for every primary/secondary particle. In the above example, the first
source particle produced 150 secondary particles for a total of 151 particles. Information for each primary/secondary
particle can be accessed using the particle_tracks attribute:
>>> first_track = tracks[0]

>>> first_track.particle_tracks
[<ParticleTrack: neutron, 120 states>,
<ParticleTrack: photon, 6 states>,
<ParticleTrack: electron, 2 states>,
...
<ParticleTrack: electron, 2 states>]
>>> photon = first_track.particle_tracks[1]
The ParticleTrack class is a named tuple indicating the particle type and then a NumPy array of the “states”. The
states array is a compound type with a field for each physical quantity (position, direction, energy, time, weight, cell
ID, and material ID). For example, to get the position for the above particle track:
>>> photon.states['r']
array([(-11.92987939, -12.28467295, 0.67837495),


(-11.95213726, -12.2682 , 0.68783964),
(-12.2682 , -12.03428339, 0.82223855),
(-12.5913778 , -11.79510096, 0.95966298),
(-12.6622572 , -11.74264344, 0.98980293),
(-12.6907775 , -11.7215357 , 1.00193058)],
dtype=[('x', '<f8'), ('y', '<f8'), ('z', '<f8')])
The full list of fields is as follows:

r
Position (each direction in [cm])
u
Direction
E
Energy in [eV]
time
Time in [s]
wgt
Weight
cell_id
Cell ID
cell_instance
Cell instance
material_id
Material ID
Both the Tracks and Track classes have a filter method that allows you to get a subset of tracks that meet a given
criteria. For example, to get all tracks that involved a photon:
>>> tracks.filter(particle='photon')
[<Track (1, 1, 50): 151 particles>,
<Track (2, 1, 30): 191 particles>,
<Track (5, 1, 75): 81 particles>]
The openmc.Tracks.filter() method returns a new Tracks instance, whereas the openmc.Track.filter()
method returns a new Track instance.
Note: If you are using an MPI-enabled install of OpenMC and run a simulation with more than one process, a separate
track file will be written for each MPI process with the filename tracks_p#.h5 where # is the rank of the corresponding
process. Multiple track files can be combined with the openmc-track-combine script:
openmc-track-combine tracks_p*.h5 --out tracks.h5

4.8 Specifying Tallies
In order to obtain estimates of physical quantities in your simulation, you need to create one or more tallies using the
openmc.Tally class. As explained in detail in the theory manual, tallies provide estimates of a scoring function times
the flux integrated over some region of phase space, as in:
∫︁ ∫︁ ∫︁
𝑋 = 𝑑r 𝑑Ω 𝑑𝐸 𝑓 (r, Ω, 𝐸) 𝜓(r, Ω, 𝐸)
⏟ ⏞
⏟ ⏞ scores
filters
Thus, to specify a tally, we need to specify what regions of phase space should be included when deciding whether to
score an event as well as what the scoring function (𝑓 in the above equation) should be used. The regions of phase
space are generally called filters and the scoring functions are simply called scores.
The only cases when filters do not correspond directly with the regions of phase space are when expansion functions
are applied in the integrand, such as for Legendre expansions of the scattering kernel.
4.8.1 Filters
To specify the regions of phase space, one must create a openmc.Filter. Since openmc.Filter is an abstract class,
you actually need to instantiate one of its sub-classes (for a full listing, see Constructing Tallies). For example, to
indicate that events that occur in a given cell should score to the tally, we would create a openmc.CellFilter:
cell_filter = openmc.CellFilter([fuel.id, moderator.id, reflector.id])
Another commonly used filter is openmc.EnergyFilter, which specifies multiple energy bins over which events
should be scored. Thus, if we wanted to tally events where the incident particle has an energy in the ranges [0 eV, 4
eV] and [4 eV, 1 MeV], we would do the following:
energy_filter = openmc.EnergyFilter([0.0, 4.0, 1.0e6])
Energies are specified in eV and need to be monotonically increasing.
Caution: An energy bin between zero and the lowest energy specified is not included by default as it is in MCNP.
Once you have created a filter, it should be assigned to a openmc.Tally instance through the Tally.filters attribute:
tally.filters.append(cell_filter)
tally.filters.append(energy_filter)
tally.filters = [cell_filter, energy_filter]
Note: You are actually not required to assign any filters to a tally. If you create a tally with no filters, all events will
score to the tally. This can be useful if you want to know, for example, a reaction rate over your entire model.

4.8.2 Scores
To specify the scoring functions, a list of strings needs to be given to the Tally.scores attribute. You can score the
flux (‘flux’), or a reaction rate (‘total’, ‘fission’, etc.). For example, to tally the elastic scattering rate and the fission
neutron production, you’d assign:
tally.scores = ['elastic', 'nu-fission']
With no further specification, you will get the total elastic scattering rate and the total fission neutron production. If
you want reaction rates for a particular nuclide or set of nuclides, you can set the Tally.nuclides attribute to a list
of strings indicating which nuclides. The nuclide names should follow the same naming convention as that used for
material specification. If we wanted the reaction rates only for U235 and U238 (separately), we’d set:
tally.nuclides = ['U235', 'U238']
You can also list ‘all’ as a nuclide which will give you a separate reaction rate for every nuclide in the model.
The following tables show all valid scores:
Table 2: Flux scores: units are particle-cm per source particle.

Score Description
flux Total flux.
Table 3: Reaction scores: units are reactions per sourc

Score Description
absorption Total absorption rate. For incident neutrons, this accounts for all reactions that do not produce secondary neutron
elastic Elastic scattering reaction rate.
fission Total fission reaction rate.
scatter Total scattering rate.
total Total reaction rate.
(n,2nd) (n,2nd) reaction rate.
(n,2n) (n,2n) reaction rate.
(n,na) (n,n𝛼) reaction rate.
(n,n3a) (n,n3𝛼) reaction rate.
(n,2na) (n,2n𝛼) reaction rate.
(n,3na) (n,3n𝛼) reaction rate.
(n,np) (n,np) reaction rate.
(n,n2a) (n,n2𝛼) reaction rate.
(n,2n2a) (n,2n2𝛼) reaction rate.
(n,nd) (n,nd) reaction rate.
(n,nt) (n,nt) reaction rate.
(n,n3He) (n,n3 He) reaction rate.
(n,nd2a) (n,nd2𝛼) reaction rate.
(n,nt2a) (n,nt2𝛼) reaction rate.
(n,2np) (n,2np) reaction rate.
(n,3np) (n,3np) reaction rate.
(n,n2p) (n,n2p) reaction rate.
(n,n*X*) Level inelastic scattering reaction rate. The X indicates what which inelastic level, e.g., (n,n3) is third-level inelas
(n,nc) Continuum level inelastic scattering reaction rate.
4.8. Specifying Tallies 163

Table 3 – continued from previous page

Score Description
(n,gamma) Radiative capture reaction rate.
(n,p) (n,p) reaction rate.
(n,d) (n,d) reaction rate.
(n,t) (n,t) reaction rate.
(n,3He) (n,3 He) reaction rate.
(n,a) (n,𝛼) reaction rate.
(n,2a) (n,2𝛼) reaction rate.
(n,3a) (n,3𝛼) reaction rate.
(n,2p) (n,2p) reaction rate.
(n,pa) (n,p𝛼) reaction rate.
(n,t2a) (n,t2𝛼) reaction rate.
(n,d2a) (n,d2𝛼) reaction rate.
(n,pd) (n,pd) reaction rate.
(n,pt) (n,pt) reaction rate.
(n,da) (n,d𝛼) reaction rate.
coherent-scatter Coherent (Rayleigh) scattering reaction rate.
incoherent-scatter Incoherent (Compton) scattering reaction rate.
photoelectric Photoelectric absorption reaction rate.
pair-production Pair production reaction rate.
Arbitrary integer An arbitrary integer is interpreted to mean the reaction rate for a reaction with a given ENDF MT number.
Table 4: Particle production scores: units are particles produced per

source particles.
Score Description
delayed- Total production of delayed neutrons due to fission.
nu-
fission
prompt- Total production of prompt neutrons due to fission.
nu-
fission
nu- Total production of neutrons due to fission.
fission
nu- This score is similar in functionality to the scatter score except the total production of neutrons due
scatter to scattering is scored vice simply the scattering rate. This accounts for multiplicity from (n,2n), (n,3n),
and (n,4n) reactions.
H1- Total production of H1.
production
H2- Total production of H2 (deuterium).
production
H3- Total production of H3 (tritium).
production
He3- Total production of He3.
production
He4- Total production of He4 (alpha particles).
production

Table 5: Miscellaneous scores: units are indicated for each.

Score Description
cur- Used in combination with a meshsurface filter: Partial currents on the boundaries of each cell in a mesh. It
rent may not be used in conjunction with any other score. Only energy and mesh filters may be used. Used in
combination with a surface filter: Net currents on any surface previously defined in the geometry. It may be
used along with any other filter, except meshsurface filters. Surfaces can alternatively be defined with cell
from and cell filters thereby resulting in tallying partial currents. Units are particles per source particle.
events Number of scoring events. Units are events per source particle.
inverse-The flux-weighted inverse velocity where the velocity is in units of centimeters per second.
velocity
heat- Total nuclear heating in units of eV per source particle. For neutrons, this corresponds to MT=301 produced
ing by NJOY’s HEATR module while for photons, this is tallied from either direct photon energy deposition
(analog estimator) or pre-generated photon heating number. See Heating and Energy Deposition
heating-Total nuclear heating in units of eV per source particle assuming energy from secondary photons is deposited
local locally. Note that this score should only be used for incident neutrons. See Heating and Energy Deposition.
kappa- The recoverable energy production rate due to fission. The recoverable energy is defined as the fission
fission product kinetic energy, prompt and delayed neutron kinetic energies, prompt and delayed 𝛾-ray total energies,
and the total energy released by the delayed 𝛽 particles. The neutrino energy does not contribute to this
response. The prompt and delayed 𝛾-rays are assumed to deposit their energy locally. Units are eV per
source particle.
fission-The prompt fission energy production rate. This energy comes in the form of fission fragment nuclei, prompt
q- neutrons, and prompt 𝛾-rays. This value depends on the incident energy and it requires that the nuclear data
prompt library contains the optional fission energy release data. Energy is assumed to be deposited locally. Units
are eV per source particle.
fission-The recoverable fission energy production rate. This energy comes in the form of fission fragment nuclei,
q- prompt and delayed neutrons, prompt and delayed 𝛾-rays, and delayed 𝛽-rays. This tally differs from the
recoverable
kappa-fission tally in that it is dependent on incident neutron energy and it requires that the nuclear data
library contains the optional fission energy release data. Energy is assumed to be deposited locally. Units
are eV per source paticle.
decay- The delayed-nu-fission-weighted decay rate where the decay rate is in units of inverse seconds.
rate
damage-Damage energy production in units of eV per source particle. This corresponds to MT=444 produced by
energy NJOY’s HEATR module.
4.8.3 Normalization of Tally Results
As described in Scores, all tally scores are normalized per source particle simulated. However, for analysis of a given
system, we usually want tally scores in a more natural unit. For example, neutron flux is often reported in units of
particles/cm2 -s. For a fixed source simulation, it is usually straightforward to convert units if the source rate is known.
For example, if the system being modeled includes a source that is emitting 104 neutrons per second, the tally results
just need to be multipled by 104 . This can either be done manually or using the openmc.Source.strength attribute.
For a 𝑘-eigenvalue calculation, normalizing tally results is not as simple because the source rate is not actually known.
Instead, we typically know the system power, 𝑃 , which represents how much energy is deposited per unit time. Most of
this energy originates from fission, but a small percentage also results from other reactions (e.g., photons emitted from
(𝑛, 𝛾) reactions). The most rigorous method to normalize tally results is to run a coupled neutron-photon calculation
and tally the heating score over the entire system. This score provides the heating rate in units of [eV/source], which
we’ll denote 𝐻. Then, calculate the heating rate in J/source as
J eV
[︂ ]︂ [︂ ]︂
𝐻 ′ = 1.602 × 10−19 ·𝐻 .
eV source
4.8. Specifying Tallies 165

Dividing the power by the observed heating rate then gives us a normalization factor that can be applied to other tallies:
𝑃 [J/s] [︁ source ]︁
𝑓= = = .
𝐻′ [J/source] s
Multiplying by the normalization factor and dividing by volume, we can then get the flux in typical units:
particle
[︂ ]︂
𝑓𝜑 [source/s][particle-cm/source]
𝜑′ = = =
𝑉 [cm3 ] cm2 · s
There are several slight variations on this procedure:

• Run a neutron-only calculation and estimate the total heating using the heating-local score (this requires that
your nuclear data has local heating data available, such as in the official data library at https://openmc.org. See
Heating and Energy Deposition for more information.)
• Run a neutron-only calculation and use the kappa-fission or fission-q-recoverable scores along with
an estimate of the extra heating due to neutron capture reactions.
• Calculate the overall fission rate and then used a fixed Q value to estimate the heating rate.
Note that the only difference between these and the above procedures is in how 𝐻 ′ is estimated.
4.9 Geometry Visualization
OpenMC is capable of producing two-dimensional slice plots of a geometry as well as three-dimensional voxel plots
using the geometry plotting run mode. The geometry plotting mode relies on the presence of a plots.xml file that
indicates what plots should be created. To create this file, one needs to create one or more openmc.Plot instances,
add them to a openmc.Plots collection, and then use the Plots.export_to_xml method to write the plots.xml
file.
4.9.1 Slice Plots
By default, when an instance of openmc.Plot is created, it indicates that a 2D slice plot should be made. You can
specify the origin of the plot (Plot.origin), the width of the plot in each direction (Plot.width), the number of

pixels to use in each direction (Plot.pixels), and the basis directions for the plot. For example, to create a 𝑥 - 𝑧 plot
centered at (5.0, 2.0, 3.0) with a width of (50., 50.) and 400x400 pixels:
plot = openmc.Plot()
plot.basis = 'xz'
plot.origin = (5.0, 2.0, 3.0)
plot.width = (50., 50.)
plot.pixels = (400, 400)
The color of each pixel is determined by placing a particle at the center of that pixel and using OpenMC’s internal
find_cell routine (the same one used for particle tracking during simulation) to determine the cell and material at
that location.
Note: In this example, pixels are 50/400=0.125 cm wide. Thus, this plot may miss any features smaller than 0.125
cm, since they could exist between pixel centers. More pixels can be used to resolve finer features but will result in
larger files.
By default, a unique color will be assigned to each cell in the geometry. If you want your plot to be colored by material
instead, change the Plot.color_by attribute:
plot.color_by = 'material'
If you don’t like the random colors assigned, you can also indicate that particular cells/materials should be given colors
of your choosing:
plot.colors = {
water: 'blue',
clad: 'black'
}
plot.colors = {
water: (0, 0, 255),
clad: (0, 0, 0)
}
Note that colors can be given as RGB tuples or by a string indicating a valid SVG color.
When you’re done creating your openmc.Plot instances, you need to then assign them to a openmc.Plots collection
and export it to XML:
plots = openmc.Plots([plot1, plot2, plot3])

plots.export_to_xml()
plots = openmc.Plots()
plots.append(plot1)
plots += [plot2, plot3]
plots.export_to_xml()
To actually generate the plots, run the openmc.plot_geometry() function. Alternatively, run the openmc executable
with the --plot command-line flag. When that has finished, you will have one or more .png files. Alternatively, if
you’re working within a Jupyter Notebook or QtConsole, you can use the openmc.plot_inline() to run OpenMC
in plotting mode and display the resulting plot within the notebook.
4.9. Geometry Visualization 167

4.9.2 Voxel Plots
The openmc.Plot class can also be told to generate a 3D voxel plot instead of a 2D slice plot. Simply change the
Plot.type attribute to ‘voxel’. In this case, the Plot.width and Plot.pixels attributes should be three items long,
e.g.:
vox_plot = openmc.Plot()
vox_plot.type = 'voxel'
vox_plot.width = (100., 100., 50.)
vox_plot.pixels = (400, 400, 200)
The voxel plot data is written to an HDF5 file. The voxel file can subsequently be converted into a standard mesh format
that can be viewed in ParaView, VisIt, etc. This typically will compress the size of the file significantly. The provided
openmc-voxel-to-vtk script can convert the HDF5 voxel file to VTK formats. Once processed into a standard 3D file
format, colors and masks can be defined using the stored ID numbers to better explore the geometry. The process for
doing this will depend on the 3D viewer, but should be straightforward.
Note: 3D voxel plotting can be very computer intensive for the viewing program (Visit, ParaView, etc.) if the number
of voxels is large (>10 million or so). Thus if you want an accurate picture that renders smoothly, consider using only
one voxel in a certain direction.
4.10 Depletion and Transmutation
OpenMC supports transport-coupled and transport-independent depletion, or burnup, calculations through the
openmc.deplete Python module. OpenMC uses transmutation reaction rates to solve a set of transmutation equations
that determine the evolution of nuclide densities within a material. The nuclide densities predicted at some future time
are then used to determine updated reaction rates, and the process is repeated for as many timesteps as are requested.
The depletion module is designed such that the reaction rate solution (the transport “operator”) is completely isolated
from the solution of the transmutation equations and the method used for advancing time.
openmc.deplete supports multiple time-integration methods for determining material compositions over time. Each
method appears as a different class. For example, openmc.deplete.CECMIntegrator runs a depletion calcula-
tion using the CE/CM algorithm (deplete over a timestep using the middle-of-step reaction rates). An instance of

TransportOperator is passed to one of these Integrator classes along with the timesteps and power level:
power = 1200.0e6 # watts

timesteps = [10.0, 10.0, 10.0] # days
openmc.deplete.CECMIntegrator(op, timesteps, power, timestep_units='d').integrate()
The depletion problem is executed, and once it is done a depletion_results.h5 file is written. The results can be
analyzed using the openmc.deplete.Results class. This class has methods that allow for easy retrieval of k-effective,
nuclide concentrations, and reaction rates over time:
results = openmc.deplete.Results("depletion_results.h5")
time, keff = results.get_keff()
Note that the coupling between the reaction rate solver and the transmutation solver happens in-memory rather than by
reading/writing files on disk. OpenMC has two categories of transport operators for obtaining transmutation reaction
rates.
4.10.1 Transport-coupled depletion
This category of operator solves the transport equation to obtain transmutation reaction rates. At present, the openmc.
deplete module offers a single transport-coupled operator, openmc.deplete.CoupledOperator (which uses the
OpenMC transport solver), but in principle additional transport-coupled operator classes based on other transport
codes could be implemented and no changes to the depletion solver itself would be needed. The openmc.deplete.
CoupledOperator class requires a Model instance containing material, geometry, and settings information:
model = openmc.Model()
...
op = openmc.deplete.CoupledOperator(model)
Any material that contains a fissionable nuclide is depleted by default, but this can behavior can be changed with the
Material.depletable attribute.
Important: The volume must be specified for each material that is depleted by setting the Material.volume attribute.
This is necessary in order to calculate the proper normalization of tally results based on the source rate.
Fixed-Source Transmutation
When the power or power_density argument is used for one of the Integrator classes, it is assumed that OpenMC
is running in k-eigenvalue mode, and normalization of tally results is performed based on energy deposition. It is also
possible to run a fixed-source simulation and perform normalization based on a known source rate. First, as with all
fixed-source calculations, we need to set the run mode:
settings.run_mode = 'fixed source'
Additionally, all materials that you wish to deplete need to be marked as such using the Material.depletable
attribute:
mat.depletable = True
4.10. Depletion and Transmutation 169

When constructing the CoupledOperator, you should indicate that normalization of tally results will be done based
on the source rate rather than a power or power density:
op = openmc.deplete.CoupledOperator(model, normalization_mode='source-rate')
Finally, when creating a depletion integrator, use the source_rates argument:
integrator = openmc.deplete.PredictorIntegrator(op, timesteps, sources_rates=...)
As with the power argument, you can provide a different source rate for each timestep in the calculation. A zero source
rate for a given timestep will result in a decay-only step, where all reaction rates are zero.
Caveats
Energy Deposition
The default energy deposition mode, "fission-q", instructs the CoupledOperator to normalize reaction rates using
the product of fission reaction rates and fission Q values taken from the depletion chain. This approach does not consider
indirect contributions to energy deposition, such as neutron heating and energy from secondary photons. In doing this,
the energy deposited during a transport calculation will be lower than expected. This causes the reaction rates to be
over-adjusted to hit the user-specific power, or power density, leading to an over-depletion of burnable materials.
There are some remedies. First, the fission Q values can be directly set in a variety of ways. This requires knowing
what the total fission energy release should be, including indirect components. Some examples are provided below:
# use a dictionary of fission_q values

fission_q = {"U235": 202e+6} # energy in eV
# create a Model object

model = openmc.Model(geometry, settings)
# create a modified chain and write it to a new file

chain = openmc.deplete.Chain.from_xml("chain.xml", fission_q)
chain.export_to_xml("chain_mod_q.xml")
op = openmc.deplete.CoupledOperator(model, "chain_mod_q.xml")
# alternatively, pass the modified fission Q directly to the operator

op = openmc.deplete.CoupledOperator(model, "chain.xml",
fission_q=fission_q)
A more complete way to model the energy deposition is to use the modified heating reactions described in Heating
and Energy Deposition. These values can be used to normalize reaction rates instead of using the fission reaction rates
with:
op = openmc.deplete.CoupledOperator(model, "chain.xml",
normalization_mode="energy-deposition")
These modified heating libraries can be generated by running the latest version of openmc.data.IncidentNeutron.
from_njoy(), and will eventually be bundled into the distributed libraries.

Local Spectra and Repeated Materials
It is not uncommon to explicitly create a single burnable material across many locations. From a pure transport per-
spective, there is nothing wrong with creating a single 3.5 wt.% enriched fuel fuel_3, and placing that fuel in every
fuel pin in an assembly or even full core problem. This certainly expedites the model making process, but can pose
issues with depletion. Under this setup, openmc.deplete will deplete a single fuel_3 material using a single set
of reaction rates, and produce a single new composition for the next time step. This can be problematic if the same
fuel_3 is used in very different regions of the problem.
As an example, consider a full-scale power reactor core with vacuum boundary conditions, and with fuel pins solely
composed of the same fuel_3 material. The fuel pins towards the center of the problem will surely experience a more
intense neutron flux and greater reaction rates than those towards the edge of the domain. This indicates that the fuel in
the center should be at a more depleted state than periphery pins, at least for the fist depletion step. However, without
any other instructions, OpenMC will deplete fuel_3 as a single material, and all of the fuel pins will have an identical
composition at the next transport step.
This can be countered by instructing the operator to treat repeated instances of the same material as a unique material
definition with:
op = openmc.deplete.CoupledOperator(model, chain_file,
diff_burnable_mats=True)
For our example problem, this would deplete fuel on the outer region of the problem with different reaction rates
than those in the center. Materials will be depleted corresponding to their local neutron spectra, and have unique
compositions at each transport step. The volume of the original fuel_3 material must represent the volume of all the
fuel_3 in the problem. When creating the unique materials, this volume will be equally distributed across all material
instances.
Note: This will increase the total memory usage and run time due to an increased number of tallies and material
definitions.
4.10.2 Transport-independent depletion
Warning: This feature is still under heavy development and has yet to be rigorously verified. API changes and
feature additions are possible and likely in the near future.
This category of operator uses pre-calculated one-group microscopic cross sections to obtain transmutation reaction
rates. OpenMC provides the IndependentOperator for this method of calculation. While the one-group microscopic
cross sections can be calculated using a transport solver, IndependentOperator is not directly coupled to any trans-
port solver. The IndependentOperator class requires a openmc.Materials object, a MicroXS object, and a path
to a depletion chain file:
# load in the microscopic cross sections

...
micro_xs = openmc.deplete.MicroXS.from_csv(micro_xs_path)
op = openmc.deplete.IndependentOperator(materials, micro_xs, chain_file)

Note: The same statements from Transport-coupled depletion about which materials are depleted and the requirement
for depletable materials to have a specified volume also apply here.
An alternate constructor, from_nuclides(), accepts a volume and dictionary of nuclide concentrations in place of
the openmc.Materials object:
nuclides = {'U234': 8.92e18,

'U235': 9.98e20,
'U238': 2.22e22,
'U236': 4.57e18,
'O16': 4.64e22,
'O17': 1.76e19}
volume = 0.5
op = openmc.deplete.IndependentOperator.from_nuclides(volume,
nuclides,
micro_xs,
chain_file,
nuc_units='atom/cm3')
A user can then define an integrator class as they would for a coupled transport-depletion calculation and follow the
same steps from there.
Note: Ideally, one-group cross section data should be available for every reaction in the depletion chain. If a nuclide
that has a reaction associated with it in the depletion chain is present in the nuclides parameter but not the cross section
data, that reaction will not be simulated.
Generating Microscopic Cross Sections
Users can generate the one-group microscopic cross sections needed by IndependentOperator using the MicroXS
class:
import openmc
model = openmc.Model.from_xml()
micro_xs = openmc.deplete.MicroXS.from_model(model,
model.materials[0],
chain_file)
The from_model() method will produce a MicroXS object with microscopic cross section data in units of barns,
which is what IndependentOperator expects the units to be. The MicroXS class also includes functions to read in
cross section data directly from a .csv file or from data arrays:
micro_xs = MicroXS.from_csv(micro_xs_path)
nuclides = ['U234', 'U235', 'U238']

reactions = ['fission', '(n,gamma)']
data = np.array([[0.1, 0.2],
[0.3, 0.4],


[0.01, 0.5]])
micro_xs = MicroXS.from_array(nuclides, reactions, data)
Important: Both from_csv() and from_array() assume the cross section values provided are in barns by de-
fualt, but have no way of verifying this. Make sure your cross sections are in the correct units before passing to a
IndependentOperator object.
Caveats
Reaction Rate Normalization
The IndependentOperator class supports two methods for normalizing reaction rates:
Important: Make sure you set the correct parameter in the openmc.abc.Integrator class. Use the
source_rates parameter when normalization_mode == source-rate, and use power or power_density when
normalization_mode == fission-q.
1. source-rate normalization, which assumes the source_rate provided by the time integrator is a flux, and
obtains the reaction rates by multiplying the cross-sections by the source-rate.
2. fission-q normalization, which uses the power or power_density provided by the time integrator to obtain
reaction rates by computing a value for the flux based on this power. The general equation for the flux is
𝑃
𝜑 = ∑︀
(𝑄𝑖 𝜎𝑖𝑓 𝑁𝑖 )
𝑖
where 𝑃 is the power, 𝑄𝑖 is the fission Q value for nuclide 𝑖, 𝜎𝑖𝑓 is the microscopic fission cross section for
nuclide 𝑖, and 𝑁𝑖 is the number of atoms of nuclide 𝑖. This equation makes the same assumptions and issues as
discussed in Energy Deposition. Unfortunately, the proposed solution in that section does not apply here since
we are decoupled from transport code. However, there is a method to converge to a more accurate value for flux
by using substeps during time integration. This paper provides a good discussion of this method.
Warning: The accuracy of results when using fission-q is entirely dependent on your depletion chain. Make
sure it has sufficient data to resolve the dynamics of your particular scenario.
Multiple Materials
Running a depletion simulation with multiple materials using the source-rate normalization method treats each ma-
terial as completely separate with respect to reaction rates. This can be useful for running many different cases of a
particular scenario. However, running a depletion simulation with multiple materials using the fission-q normal-
ization method treats each material as part of the same “reactor” due to how fission-q normalization accumulates
energy values from each material to a single value. This behavior may change in the future.

Time integration
The one-group microscopic cross sections passed to openmc.deplete.IndependentOperator are fixed values for
the entire depletion simulation. This implicit assumption may produce inaccurate results for certain scenarios.
4.11 Executables and Scripts
4.11.1 openmc
Once you have a model built (see Basics of Using OpenMC), you can either run the openmc executable directly from
the directory containing your XML input files, or you can specify as a command-line argument the directory containing
the XML input files.
Warning: OpenMC models should be treated as code, and it is important to be careful with code from untrusted
sources.
For example, if your XML input files are in the directory /home/username/somemodel/, one way to run the simula-
tion would be:
cd /home/username/somemodel
openmc
Alternatively, you could run from any directory:
openmc /home/username/somemodel
Note that in the latter case, any output files will be placed in the present working directory which may be different from
/home/username/somemodel. openmc accepts the following command line flags:
-c, --volume Run in stochastic volume calculation mode
-e, --event Run using event-based parallelism
-g, --geometry-debug Run in geometry debugging mode, where cell overlaps are checked for after each
move of a particle
-n, --particles N Use N particles per generation or batch
-p, --plot Run in plotting mode
-r, --restart file Restart a previous run from a state point or a particle restart file
-s, --threads N Run with N OpenMP threads
-t, --track Write tracks for all particles (up to max_tracks)
-v, --version Show version information
-h, --help Show help message
Note: If you’re using the Python API, openmc.run() is equivalent to running openmc from the command line.

4.11.2 openmc-ace-to-hdf5
This script can be used to create HDF5 nuclear data libraries used by OpenMC if you have existing ACE files. There
are four different ways you can specify ACE libraries that are to be converted:
1. List each ACE library as a positional argument. This is very useful in conjunction with the usual shell utilities
(ls, find, etc.).
2. Use the --xml option to specify a pre-v0.9 cross_sections.xml file.
3. Use the --xsdir option to specify a MCNP xsdir file.
4. Use the --xsdata option to specify a Serpent xsdata file.
The script does not use any extra information from cross_sections.xml/ xsdir/ xsdata files to determine whether the nu-
clide is metastable. Instead, the --metastable argument can be used to specify whether the ZAID naming convention
follows the NNDC data convention (1000*Z + A + 300 + 100*m), or the MCNP data convention (essentially the same
as NNDC, except that the first metastable state of Am242 is 95242 and the ground state is 95642).
The optional --fission_energy_release argument will accept an HDF5 file containing a library of fission en-
ergy release (ENDF MF=1 MT=458) data. A library built from ENDF/B-VII.1 data is released with OpenMC and
can be found at openmc/data/fission_Q_data_endb71.h5. This data is necessary for ‘fission-q-prompt’ and ‘fission-q-
recoverable’ tallies, but is not needed otherwise.
-h, --help show help message and exit
-d DESTINATION, --destination DESTINATION Directory to create new library in
-m META, --metastable META How to interpret ZAIDs for metastable nuclides. META can be either
‘nndc’ or ‘mcnp’. (default: nndc)
--xml XML Old-style cross_sections.xml that lists ACE libraries
--xsdir XSDIR MCNP xsdir file that lists ACE libraries
--xsdata XSDATA Serpent xsdata file that lists ACE libraries
--fission_energy_release FISSION_ENERGY_RELEASE HDF5 file containing fission energy re-
lease data
4.11.3 openmc-plot-mesh-tally
openmc-plot-mesh-tally provides a graphical user interface for plotting mesh tallies. The path to the statepoint file
can be provided as an optional arugment (if omitted, a file dialog will be presented).
4.11.4 openmc-track-combine
This script combines multiple HDF5 particle track files into a single HDF5 particle track file. The filenames of the
particle track files should be given as posititional arguments. The output filename can also be changed with the -o
flag:
-o OUT, --out OUT Output HDF5 particle track file
4.11. Executables and Scripts 175

4.11.5 openmc-track-to-vtk
This script converts HDF5 particle track files to VTK poly data that can be viewed with ParaView or VisIt. The
filenames of the particle track files should be given as posititional arguments. The output filename can also be changed
with the -o flag:
-o OUT, --out OUT Output VTK poly filename
4.11.6 openmc-update-inputs
If you have existing XML files that worked in a previous version of OpenMC that no longer work with the current
version, you can try to update these files using openmc-update-inputs. If any of the given files do not match the
most up-to-date formatting, then they will be automatically rewritten. The old out-of-date files will not be deleted; they
will be moved to a new file with ‘.original’ appended to their name.
Formatting changes that will be made:
geometry.xml
Lattices containing ‘outside’ attributes/tags will be replaced with lattices containing ‘outer’ attributes, and the
appropriate cells/universes will be added. Any ‘surfaces’ attributes/elements on a cell will be renamed ‘region’.
materials.xml
Nuclide names will be changed from ACE aliases (e.g., Am-242m) to HDF5/GND names (e.g., Am242_m1).
Thermal scattering table names will be changed from ACE aliases (e.g., HH2O) to HDF5/GND names (e.g.,
c_H_in_H2O).
4.11.7 openmc-update-mgxs
This script updates OpenMC’s deprecated multi-group cross section XML files to the latest HDF5-based format.
-i IN, --input IN Input XML file
-o OUT, --output OUT Output file in HDF5 format
4.11.8 openmc-validate-xml
Input files can be checked before executing OpenMC using the openmc-validate-xml script which is installed along-
side the Python API. Two command line arguments can be set when running openmc-validate-xml:
-i, --input-path Location of OpenMC input files.
-r, --relaxng-path Location of OpenMC RelaxNG files
If the RelaxNG path is not set, the script will search for these files because it expects that the user is either running the
script located in the install directory bin folder or in src/utils. Once executed, it will match OpenMC XML files
with their RelaxNG schema and check if they are valid. Below is a table of the messages that will be printed after each
file is checked.
Message Description
[XML ERROR] Cannot parse XML file.
[NO RELAXNG FOUND] No RelaxNG file found for XML file.
[NOT VALID] XML file does not match RelaxNG.
[VALID] XML file matches RelaxNG.

4.11.9 openmc-voxel-to-vtk
When OpenMC generates voxel plots, they are in an HDF5 format that is not terribly useful by itself. The
openmc-voxel-to-vtk script converts a voxel HDF5 file to a VTK file. To run this script, you will need to have
the VTK Python bindings installed. To convert a voxel file, simply provide the path to the file:
openmc-voxel-to-vtk voxel_1.h5
The openmc-voxel-to-vtk script also takes the following optional command-line arguments:
-o, --output Path to output VTK file
4.12 Data Processing and Visualization
This section is intended to explain procedures for carrying out common post-processing tasks with OpenMC. While
several utilities of varying complexity are provided to help automate the process, the most powerful capabilities for
post-processing derive from use of the Python API.
4.12.1 Working with State Points
Tally results are saved in both a text file (tallies.out) as well as an HDF5 statepoint file. While the tallies.out file may
be fine for simple tallies, in many cases the user requires more information about the tally or the run, or has to deal
with a large number of result values (e.g. for mesh tallies). In these cases, extracting data from the statepoint file via
the Python API is the preferred method of data analysis and visualization.
Data Extraction
A great deal of information is available in statepoint files (See State Point File Format), all of which is accessible
through the Python API. The openmc.StatePoint class can load statepoints and access data as requested; it is used
in many of the provided plotting utilities, OpenMC’s regression test suite, and can be used in user-created scripts to
carry out manipulations of the data.
An example notebook demonstrates how to extract data from a statepoint using the Python API.
Plotting in 2D
The example notebook also demonstrates how to plot a structured mesh tally in two dimensions using the Python API.
One can also use the openmc-plot-mesh-tally script which provides an interactive GUI to explore and plot structured
mesh tallies for any scores and filter bins.
4.12. Data Processing and Visualization 177

4.12.2 Particle Track Visualization
OpenMC can dump particle tracks—the position of particles as they are transported through the geometry. There are
two ways to make OpenMC output tracks: all particle tracks through a command line argument or specific particle
tracks through settings.xml.
Running openmc with the argument -t or --track will cause a track file to be created for every particle transported
in the code. Be careful as this will produce as many files as there are source particles in your simulation. To identify a
specific particle for which a track should be created, set the Settings.track attribute to a tuple containing the batch,
generation, and particle number of the desired particle. For example, to create a track file for particle 4 of batch 1 and
generation 2:

settings.track = (1, 2, 4)
To specify multiple particles, the length of the iterable should be a multiple of three, e.g., if we wanted particles 3 and
4 from batch 1 and generation 2:
settings.track = (1, 2, 3, 1, 2, 4)
After running OpenMC, the working directory will contain a file of the form “track_(batch #)_(generation #)_(particle
#).h5” for each particle tracked. These track files can be converted into VTK poly data files with the openmc-track-to-vtk
script.
4.12.3 Source Site Processing
For eigenvalue problems, OpenMC will store information on the fission source sites in the statepoint file by default.
For each source site, the weight, position, sampled direction, and sampled energy are stored. To extract this data from a
statepoint file, the openmc.statepoint module can be used. An example notebook demontrates how to analyze and
plot source information.
4.13 Running in Parallel
If you are running a simulation on a computer with multiple cores, multiple sockets, or multiple nodes (i.e., a cluster),
you can benefit from the fact that OpenMC is able to use all available hardware resources if configured correctly.
OpenMC is capable of using both distributed-memory (MPI) and shared-memory (OpenMP) parallelism. If you are on
a single-socket workstation or a laptop, using shared-memory parallelism is likely sufficient. On a multi-socket node,
cluster, or supercomputer, chances are you will need to use both distributed-memory (across nodes) and shared-memory
(within a single node) parallelism.
4.13.1 Shared-Memory Parallelism (OpenMP)
When using OpenMP, multiple threads will be launched and each is capable of simulating a particle independently of
all other threads. The primary benefit of using OpenMP within a node is that it requires very little extra memory per
thread. OpenMP can be turned on or off at configure-time; by default it is turned on. The only requirement is that the
C++ compiler you use must support the OpenMP 3.1 or higher standard. Most recent compilers do support the use of
OpenMP.
To specify the number of threads at run-time, you can use the threads argument to openmc.run():
openmc.run(threads=8)
If you’re running openmc directly from the command line, you can use the -s or --threads command-line argument.
Alternatively, you can use the OMP_NUM_THREADS environment variable. If you do not specify the number of threads,
the OpenMP library will try to determine how many hardware threads are available on your system and use that many
threads.
In general, it is recommended to use as many OpenMP threads as you have hardware threads on your system. Notably,
on a system with Intel hyperthreading, the hyperthreads should be used and can be expected to provide a 10–30%
performance improvement over not using hyperthreads.
4.13. Running in Parallel 179

4.13.2 Distributed-Memory Parallelism (MPI)
MPI defines a library specification for message-passing between processes. There are two major implementations of
MPI, OpenMPI and MPICH. Both implementations are known to work with OpenMC; there is no obvious reason to
prefer one over the other. Building OpenMC with support for MPI requires that you have one of these implementations
installed on your system. For instructions on obtaining MPI, see Prerequisites. Once you have an MPI implementation
installed, compile OpenMC following Specifying the Build Type.
To run a simulation using MPI, openmc needs to be called using the mpiexec wrapper. For example, to run OpenMC
using 32 processes:
mpiexec -n 32 openmc
The same thing can be achieved from the Python API by supplying the mpi_args argument to openmc.run():
openmc.run(mpi_args=['mpiexec', '-n', '32'])
4.13.3 Maximizing Performance
There are a number of things you can do to ensure that you obtain optimal performance on a machine when running in
parallel:
• Use OpenMP within each NUMA node. Some large server processors have so many cores that the last level
cache is split to reduce memory latency. For example, the Intel Xeon Haswell-EP architecture uses a snoop mode
called cluster on die where the L3 cache is split in half. Thus, in general, you should use one MPI process per
socket (and OpenMP within each socket), but for these large processors, you will want to go one step further and
use one process per NUMA node. The Xeon Phi Knights Landing architecture uses a similar concept called sub
NUMA clustering.
• Use a sufficiently large number of particles per generation. Between fission generations, a number of syn-
chronization tasks take place. If the number of particles per generation is too low and you are using many
processes/threads, the synchronization time may become non-negligible.
• Use hardware threading if available.
• Use process binding. When running with MPI, you should ensure that processes are bound to a specific hardware
region. This can be set using the -bind-to (MPICH) or --bind-to (OpenMPI) option to mpiexec.
• Turn off generation of tallies.out. For large simulations with millions of tally bins or more, generating this
ASCII file might consume considerable time. You can turn off generation of tallies.out via the Settings.
output attribute:
settings.output = {'tallies': False}
4.14 Stochastic Volume Calculations
OpenMC has a capability to stochastically determine volumes of cells, materials, and universes. The method works by
overlaying a bounding box, sampling points from within the box, and seeing what fraction of points were found in a
desired domain. The benefit of doing this stochastically (as opposed to equally-spaced points), is that it is possible to
give reliable error estimates on each stochastic quantity.
To specify that a volume calculation be run, you first need to create an instance of openmc.VolumeCalculation.
The constructor takes a list of cells, materials, or universes; the number of samples to be used; and the lower-left and
upper-right Cartesian coordinates of a bounding box that encloses the specified domains:

lower_left = (-0.62, -0.62, -50.)

upper_right = (0.62, 0.62, 50.)
vol_calc = openmc.VolumeCalculation([fuel, clad, moderator], 1000000,
lower_left, upper_right)
For domains contained within regions that have simple definitions, OpenMC can sometimes automatically determine
a bounding box. In this case, the last two arguments are not necessary. For example,
sphere = openmc.Sphere(r=10.0)
cell = openm.Cell(region=-sphere)
vol_calc = openmc.VolumeCalculation([cell], 1000000)
Of course, the volumes that you need this capability for are often the ones with complex definitions.
A threshold can be applied for the calculation’s variance, standard deviation, or relative error of volume estimates using
openmc.VolumeCalculation.set_trigger():
vol_calc.set_trigger(1e-05, 'std_dev')
If a threshold is provided, calculations will be performed iteratively using the number of samples specified on the
calculation until all volume uncertainties are below the threshold value. If no threshold is provided, the calculation will
run the number of samples specified once and return the result.
Once you have one or more openmc.VolumeCalculation objects created, you can then assign then to Settings.
volume_calculations:
settings.volume_calculations = [cell_vol_calc, mat_vol_calc]
To execute the volume calculations, one can either set Settings.run_mode to ‘volume’ and run openmc.run(), or
alternatively run openmc.calculate_volumes() which doesn’t require that Settings.run_mode be set.
When your volume calculations have finished, you can load the results using the VolumeCalculation.
load_results() method on an existing object. If you don’t have an existing VolumeCalculation object, you can
create one and load results simultaneously using the VolumeCalculation.from_hdf5() class method:
vol_calc = openmc.VolumeCalculation(...)
...
openmc.calculate_volumes()
vol_calc.load_results('volume_1.h5')
# ..or we can create a new object

vol_calc = openmc.VolumeCalculation.from_hdf5('volume_1.h5')
After the results are loaded, volume estimates will be stored in VolumeCalculation.volumes. There is also a
VolumeCalculation.atoms_dataframe attribute that shows stochastic estimates of the number of atoms of each
type of nuclide within the specified domains along with their uncertainties.
4.14. Stochastic Volume Calculations 181

4.15 Troubleshooting
4.15.1 Problems with Compilation
If you are experiencing problems trying to compile OpenMC, first check if the error you are receiving is among the
following options.
4.15.2 Problems with Simulations
RuntimeError: OpenMC aborted unexpectedly.
This error usually indicates that OpenMC experienced a segmentation fault. A segmentation fault occurs when the
program tries to access a variable in memory that was outside the memory allocated for the program. The best way
to debug a segmentation fault is to compile OpenMC from source with debug options turned on. Create a new build
directory and type the following commands:
mkdir build-debug && cd build-debug

cmake -Ddebug=on /path/to/openmc
make
Now when you re-run your problem, it should report exactly where the program failed. If after reading the debug
output, you are still unsure why the program failed, post a message on the OpenMC Discourse Forum.
WARNING: After particle __ crossed surface __ it could not be located in any cell and it did not leak.
During a simulation, particles can become “lost” if they reach a surface and there is no cell defined on the other side
of the surface. It is important to ensure that 1) proper boundary conditions have been applied to the outer surfaces of
your model and 2) all space in your model is filled with a cell, even regions that are void and have no material assigned
to them.
Please see the instructions in Geometry Debugging on how to resolve issues with lost particles.
ERROR: Maximum number of lost particles has been reached.
See the above description regarding lost particles. When too many particles are lost, the simulation will abort altogether.
Again, please see the instructions in Geometry Debugging on how to resolve issues with lost particles.
ERROR: No cross_sections.xml file was specified in settings.xml or in the

OPENMC_CROSS_SECTIONS environment variable.
OpenMC needs to know where to find cross section data for each nuclide. Information on what data is available and in
what files is summarized in a cross_sections.xml file. You need to tell OpenMC where to find the cross_sections.xml
file either with the <cross_sections> Element in settings.xml or with the OPENMC_CROSS_SECTIONS environment
variable. It is recommended to add a line in your .profile or .bash_profile setting the OPENMC_CROSS_SECTIONS
environment variable.

RuntimeError: Failed to open HDF5 file with mode ‘w’: summary.h5
This often occurs when working with the Python API and executing multiple OpenMC runs in a script. If an openmc.
StatePoint is open in the Python interpreter, the file handle of the statepoint file as well as the linked summary.h5
file will be unavailable for writing, causing this error to appear. To avoid this situation, it is recommended that data be
extracted from statepoint files in a context manager:
with openmc.StatePoint('statepoint.10.h5') as sp:

k_eff = sp.keff
or that the StatePoint.close() method is called before executing a subsequent OpenMC run.
Geometry Debugging
To identify issues in your geometry, it is highly recommended to use the OpenMC Plot Explorer GUI application. This
application enables you to interactively explore a model, identify regions that may be missing a cell definition, and
identify overlapping cells.
If you are having issues with lost particles, the following procedure may be helpful. If OpenMC reports, for example,
that a particle reaching surface 50 could not be located, look at your geometry.xml to see which cells have a region
definition that includes surface 50, e.g.:
<cell id="10" material="5" region="-49 50 -51 52" />
This may indicate that you need to define a cell on the other side of cell 10. At this point, using the OpenMC Plot
Explorer to locate cell 10 may provide a visual clue as to whether there is a missing or overlapping cell near cell 10.
Working with the unique integer IDs of cells may be cumbersome; if you provide names to your cells, these names will
show up in the Plot Explorer, which will aid geometry debugging.
Another method to check for overlapping cells in a geometry is to run the problem in geometry debugging mode with
the -g, -geometry-debug, or --geometry-debug command-line options. This will enable checks for overlapping
cells at every move of each simulated particle. Depending on the complexity of the geometry input file, this could add
considerable overhead to the run (these runs can still be done in parallel). As a result, for this run mode the user will
probably want to run fewer particles than a normal simulation run. In this case it is important to be aware of how much
coverage each area of the geometry is getting. For instance, if certain regions do not have many particles travelling
through them there will not be many locations where overlaps are checked for in that region. The user should refer to
the output after a geometry debug run to see how many checks were performed in each cell, and then adjust the number
of starting particles or starting source distributions accordingly to achieve good coverage.
Depletion
If you are running a depletion simulation and are experiencing random hangs or crashes, you may need to set:
openmc.deplete.pool.USE_MULTIPROCESSING = False
in your Python file before making any calls to the integrator. This can be caused by an MPI implementation that is not
compatible with forking (e.g., see the OpenMPI FAQ entry about forking).
4.15. Troubleshooting 183


CHAPTER
FIVE
DEVELOPER’S GUIDE
Welcome to the OpenMC Developer’s Guide! This guide documents how contributions are made to OpenMC, what
style rules exist for the code, how to run tests, and other related topics.
5.1 Contributing to OpenMC
Thank you for considering contributing to OpenMC! We look forward to welcoming new members to the community
and will do our best to help you get up to speed. The purpose of this section is to document how the project is managed:
how contributions (bug fixes, enhancements, new features) are made, how they are evaluated, who is permitted to
merge pull requests, and what happens in the event of disagreements. Once you have read through this section, the
Development Workflow section outlines the actual mechanics of making a contribution (forking, submitting a pull
request, etc.).
The goal of our governance model is to:
• Encourage new contributions.
• Encourage contributors to remain involved.
• Avoid unnecessary processes and bureaucracy whenever possible.
• Create a transparent decision making process which makes it clear how contributors can be involved in decision
making.
5.1.1 Overview
OpenMC uses a liberal contribution model for project governance. Anyone involved in development in a non-trivial ca-
pacity is given an opportunity to influence the direction of the project. Project decisions are made through a consensus-
seeking process rather than by voting.
5.1.2 Terminology
• A Contributor is any individual creating or commenting on an issue or pull request.

• A Committer is a subset of contributors who are authorized to review and merge pull requests.
• The TC (Technical Committee) is a group of committers who have the authority to make decisions on behalf of
the project team in order to resolve disputes.
• The Project Lead is a single individual who has the authority to make a final decision when the TC is unable to
reach consensus.
185
5.1.3 Contribution Process
Any change to the OpenMC repository must be made through a pull request (PR). This applies to all changes to docu-
mentation, code, binary files, etc. Even long term committers and TC members must use pull requests.
No pull request may be merged without being independently reviewed.
For non-trivial contributions, pull requests should not be merged for at least 36 hours to ensure that contributors in
other timezones have time to review. Consideration should be given to weekends and other holiday periods to ensure
active committers have reasonable time to become involved in the discussion and review process if they wish. Any
committer may request that the review period be extended if they are unable to review the change within 36 hours.
During review, a committer may request that a specific contributor who is most versed in a particular area review the
PR before it can be merged.
A pull request can be merged by any committer, but only if no objections are raised by any other committer. In the case
of an objection being raised, all involved committers should seek consensus through discussion and compromise.
In the case of an objection being raised in a pull request by another committer, all involved committers should seek to
arrive at a consensus by way of addressing concerns being expressed through discussion, compromise on the proposed
change, or withdrawal of the proposed change.
If objections to a PR are made and committers cannot reach a consensus on how to proceed, the decision is escalated
to the TC. TC members should regularly discuss pending contributions in order to find a resolution. It is expected
that only a small minority of issues be brought to the TC for resolution and that discussion and compromise among
committers be the default resolution mechanism.
5.1.4 Becoming a Committer
All contributors who make a non-trivial contribution will be added as a committer in a timely manner. Committers are
expected to follow this policy.
5.1.5 TC Process
Any issues brought to the TC will be addressed among the committee with a consensus-seeking process. The group
tries to find a resolution that has no objections among TC members. If a consensus cannot be reached, the Project Lead
has the ultimate authority to make a final decision. It is expected that the majority of decisions made by the TC are via
a consensus seeking process and that the Project Lead intercedes only as a last resort.
Resolution may involve returning the issue to committers with suggestions on how to move forward towards a consensus.
Members can be added to the TC at any time. Any committer can nominate another committer to the TC and the TC
uses its standard consensus seeking process to evaluate whether or not to add this new member. Members who do not
participate consistently at the level of a majority of the other members are expected to resign.
In the event that the Project Lead resigns or otherwise steps down, the TC uses a consensus seeking process to choose
a new Project Lead.
186 Chapter 5. Developer’s Guide

5.1.6 Leadership Team
The TC consists of the following individuals:

• Paul Romano
• Sterling Harper
• Adam Nelson
• Benoit Forget
The Project Lead is Paul Romano.
5.1.7 Next Steps
If you are interested in working on a specific feature or helping to address outstanding issues, consider joining the
developer’s mailing list and/or Slack community. Note that some issues have specifically been labeled as good for first-
time contributors. Once you’re at the point of writing code, make sure your read through the Development Workflow
section to understand the mechanics of making pull requests and what is expected during code reviews.
5.2 Development Workflow
Anyone wishing to make contributions to OpenMC should be fully acquainted and comfortable working with git and
GitHub. We assume here that you have git installed on your system, have a GitHub account, and have setup SSH keys
to be able to create/push to repositories on GitHub.
5.2.1 Overview
Development of OpenMC relies heavily on branching; specifically, we use a branching model sometimes referred to
as git flow. If you plan to contribute to OpenMC development, we highly recommend that you read the linked blog
post to get a sense of how the branching model works. There are two main branches that always exist: master and
develop. The master branch is a stable branch that contains the latest release of the code. The develop branch is where
any ongoing development takes place prior to a release and is not guaranteed to be stable. When the development team
decides that a release should occur, the develop branch is merged into master.
All new features, enhancements, and bug fixes should be developed on a branch that branches off of develop. When
the feature is completed, a pull request is initiated on GitHub that is then reviewed by a committer. If the pull request
is satisfactory, it is then merged into develop. Note that a committer may not review their own pull request (i.e., an
independent code review is required).
5.2.2 Code Review Criteria
In order to be considered suitable for inclusion in the develop branch, the following criteria must be satisfied for all
proposed changes:
• Changes have a clear purpose and are useful.
• Compiles and passes all tests under multiple build configurations (This is checked by Travis CI).
• If appropriate, test cases are added to regression or unit test suites.
• No memory leaks (checked with valgrind).
• Conforms to the OpenMC style guide.
5.2. Development Workflow 187

• No degradation of performance or greatly increased memory usage. This is not a hard rule – in certain circum-
stances, a performance loss might be acceptable if there are compelling reasons.
• New features/input are documented.
• No unnecessary external software dependencies are introduced.
5.2.3 Contributing
Now that you understand the basic development workflow, let’s discuss how an individual can contribute to develop-
ment. Note that this would apply to both new features and bug fixes. The general steps for contributing are as follows:
1. Fork the main openmc repository from openmc-dev/openmc. This will create a repository with the same name
under your personal account. As such, you can commit to it as you please without disrupting other developers.
2. Clone your fork of OpenMC and create a branch that branches off of develop:
git clone --recurse-submodules git@github.com:yourusername/openmc.git

cd openmc
git checkout -b newbranch develop
3. Run tools/dev/install-commit-hooks.sh to install a post-commit hook that runs clang-format on C++

files to apply automatic code formatting (requires that clang-format already be installed). In addition, you may
want to configure your text editor to automatically run clang-format when saving C++ files.
3. Make your changes on the new branch that you intend to have included in develop. If you have made other
changes that should not be merged back, ensure that those changes are made on a different branch.
4. Issue a pull request from GitHub and select the develop branch of openmc-dev/openmc as the target.
At a minimum, you should describe what the changes you’ve made are and why you are making them. If the
changes are related to an outstanding issue, make sure it is cross-referenced.
5. A committer will review your pull request based on the criteria above. Any issues with the pull request can be
discussed directly on the pull request page itself.
6. After the pull request has been thoroughly vetted, it is merged back into the develop branch of openmc-
dev/openmc.
5.2.4 Private Development
While the process above depends on the fork of the OpenMC repository being publicly available on GitHub, you may
also wish to do development on a private repository for research or commercial purposes. The proper way to do this is
to create a complete copy of the OpenMC repository (not a fork from GitHub). The private repository can then either
be stored just locally or in conjunction with a private repository on Github (this requires a paid plan). Alternatively,
Bitbucket offers private repositories for free. If you want to merge some changes you’ve made in your private repository
back to openmc-dev/openmc repository, simply follow the steps above with an extra step of pulling a branch from your
private repository into a public fork.

5.2.5 Working in “Development” Mode
If you are making changes to the Python API during development, it is highly suggested to install the Python API in
development/editable mode using pip. From the root directory of the OpenMC repository, run:
pip install -e .[test]
This installs the OpenMC Python package in “editable” mode so that 1) it can be imported from a Python interpreter
and 2) any changes made are immediately reflected in the installed version (that is, you don’t need to keep reinstalling
it). While the same effect can be achieved using the PYTHONPATH environment variable, this is generally discouraged
as it can interfere with virtual environments.
5.3 Style Guide for OpenMC
In order to keep the OpenMC code base consistent in style, this guide specifies a number of rules which should be
adhered to when modified existing code or adding new code in OpenMC.
5.3.1 C++
Automatic Formatting
To ensure consistent styling with little effort, this project uses clang-format. The repository contains a .clang-format
file that can be used to automatically apply a consistent format. The easiest way to use clang-format is to run tools/
dev/install-commit-hooks.sh to install a post-commit hook that gets executed each time a commit is made. Note
that this script requires that you already have clang-format installed. In addition, you may want to configure your
editor/IDE to automatically runs clang-format using the .clang-format file whenever a file is saved. For example,
Visual Studio Code includes support for running clang-format.
Miscellaneous
Follow the C++ Core Guidelines except when they conflict with another guideline listed here. For convenience, many
important guidelines from that list are repeated here.
Conform to the C++14 standard.
Always use C++-style comments (//) as opposed to C-style (/**/). (It is more difficult to comment out a large section
of code that uses C-style comments.)
Do not use C-style casting. Always use the C++-style casts static_cast, const_cast, or reinterpret_cast. (See
ES.49)
Source Files
Use a .cpp suffix for code files and .h for header files.
Header files should always use include guards with the following style (See SF.8):
#ifndef OPENMC_MODULE_NAME_H
#define OPENMC_MODULE_NAME_H
namespace openmc {
5.3. Style Guide for OpenMC 189


...
content
...
}
#endif // OPENMC_MODULE_NAME_H
Avoid hidden dependencies by always including a related header file first, followed by C/C++ library includes, other
library includes, and then local includes. For example:
// foo.cpp
#include "foo.h"
#include <cstddef>
#include <iostream>
#include <vector>
#include "hdf5.h"
#include "pugixml.hpp"
#include "error.h"
#include "random_lcg.h"
Naming
Struct and class names should be CamelCase, e.g. HexLattice.

Functions (including member functions) should be lower-case with underscores, e.g. get_indices.
Local variables, global variables, and struct/class member variables should be lower-case with underscores (e.g.,
n_cells) except for physics symbols that are written differently by convention (e.g., E for energy). Data members
of classes (but not structs) additionally have trailing underscores (e.g., a_class_member_).
The following conventions are used for variables with short names:
• d stands for “distance”
• E stands for “energy”
• p stands for “particle”
• r stands for “position”
• rx stands for “reaction”
• u stands for “direction”
• xs stands for “cross section”
All classes and non-member functions should be declared within the openmc namespace. Global variables must be
declared in a namespace nested within the openmc namespace. The following sub-namespaces are in use:
• openmc::data: Fundamental nuclear data (cross sections, multigroup data, decay constants, etc.)
• openmc::model: Variables related to geometry, materials, and tallies
• openmc::settings: Global settings / options
• openmc::simulation: Variables used only during a simulation

Accessors and mutators (get and set functions) may be named like variables. These often correspond to actual member
variables, but this is not required. For example, int count() and void set_count(int count).
Variables declared constexpr or const that have static storage duration (exist for the duration of the program) should be
upper-case with underscores, e.g., SQRT_PI.
Documentation
Classes, structs, and functions are to be annotated for the Doxygen documentation generation tool. Use the \ form of
Doxygen commands, e.g., \brief instead of @brief.
5.3.2 Python
Style for Python code should follow PEP8.

Docstrings for functions and methods should follow numpydoc style.
Python code should work with Python 3.6+.
Use of third-party Python packages should be limited to numpy, scipy, matplotlib, pandas, and h5py. Use of other
third-party packages must be implemented as optional dependencies rather than required dependencies.
Prefer pathlib when working with filesystem paths over functions in the os module or other standard-library modules.
Functions that accept arguments that represent a filesystem path should work with both strings and Path objects.
5.4 Test Suite
The OpenMC test suite consists of two parts, a regression test suite and a unit test suite. The regression test suite is
based on regression or integrated testing where different types of input files are configured and the full OpenMC code
is executed. Results from simulations are compared with expected results. The unit tests are primarily intended to test
individual functions/classes in the OpenMC Python API.
5.4.1 Prerequisites
• The test suite relies on the third-party pytest package. To run either or both the regression and unit test suites, it
is assumed that you have OpenMC fully installed, i.e., the openmc executable is available on your PATH and the
openmc Python module is importable. In development where it would be onerous to continually install OpenMC
every time a small change is made, it is recommended to install OpenMC in development/editable mode. With
setuptools, this is accomplished by running:
python setup.py develop
or using pip (recommended):
pip install -e .[test]
• The test suite requires a specific set of cross section data in order for tests to pass. A download URL for the data
that OpenMC expects can be found within tools/ci/download-xs.sh.
• In addition to the HDF5 data, some tests rely on ENDF files. A download URL for those can also be found in
tools/ci/download-xs.sh.
• Some tests require NJOY to preprocess cross section data. The test suite assumes that you have an njoy exe-
cutable available on your PATH.
5.4. Test Suite 191

5.4.2 Running Tests
To execute the test suite, go to the tests/ directory and run:
pytest
If you want to collect information about source line coverage in the Python API, you must have the pytest-cov plugin
installed and run:
pytest --cov=../openmc --cov-report=html
5.4.3 Generating XML Inputs
Many of the regression tests rely on the Python API to build an appropriate model. However, it can sometimes be
desirable to work directly with the XML input files rather than having to run a script in order to run the problem/test.
To build the input files for a test without actually running the test, you can run:
pytest --build-inputs <name-of-test>
5.4.4 Adding Tests to the Regression Suite
To add a new test to the regression test suite, create a sub-directory in the tests/regression_tests/ directory. To
configure a test you need to add the following files to your new test directory:
• OpenMC input XML files, if they are not generated through the Python API
• test.py - Python test driver script; please refer to other tests to see how to construct. Any output files that are
generated during testing must be removed at the end of this script.
• inputs_true.dat - ASCII file that contains Python API-generated XML files concatenated together. When the
test is run, inputs that are generated are compared to this file.
• results_true.dat - ASCII file that contains the expected results from the test. The file results_test.dat is compared
to this file during the execution of the python test driver script. When the above files have been created, generate
a results_test.dat file and copy it to this name and commit. It should be noted that this file should be generated
with basic compiler options during openmc configuration and build (e.g., no MPI, no debug/optimization).
In addition to this description, please see the various types of tests that are already included in the test suite to see how
to create them. If all is implemented correctly, the new test will automatically be discovered by pytest.
5.5 Making User Input Changes
Users are encouraged to use OpenMC’s Python API to build XML files that the OpenMC solver then reads during the
initialization phase. Thus, to modify, add, or remove user input options, changes must be made both within the Python
API and the C++ source that reads XML files produced by the Python API. The following steps should be followed to
make changes to user input:
1. Determine the Python class you need to change. For example, if you are adding a new setting, you probably
want to change the openmc.Settings class. If you are adding a new surface type, you would need to create a
subclass of openmc.Surface.
2. To add a new option, the class will need a property attribute. For example, if you wanted to add a “fast_mode”
setting, you would need two methods that look like:

@property
def fast_mode(self):
...
@fast_mode.setter
def fast_mode(self, fast_mode):
...
3. Make sure that when an instance of the class is exported to XML (usually through a export_to_xml() or
to_xml_element() method), a new element is written to the appropriate file. OpenMC uses the xml.etree.
ElementTree API, so refer to the documentation of that module for guidance on creating elements/attributes.
4. Make sure that your input can be categorized as one of the datatypes from XML Schema Part 2 and that parsing
of the data appropriately reflects this. For example, for a boolean value, true can be represented either by “true”
or by “1”.
5. Now that you’re done with the Python side, you need to make modifications to the C++ codebase. Make
appropriate changes in source files (e.g., settings.cpp). You should use convenience functions defined by
xml_interface.cpp.
6. If you’ve made changes in the geometry or materials, make sure they are written out to the statepoint or summary
files and that the openmc.StatePoint and openmc.Summary classes read them in.
7. Finally, a set of RELAX NG schemas exists that enables validation of input files. You should modify the RELAX
NG schema for the file you changed. The easiest way to do this is to change the compact syntax file (e.g. src/
relaxng/geometry.rnc) and then convert it to regular XML syntax using trang:
trang geometry.rnc geometry.rng
For most user input additions and changes, it is simple enough to follow a “monkey see, monkey do” approach. When
in doubt, contact your nearest OpenMC developer or send a message to the developers mailing list.
5.6 Building Sphinx Documentation
In order to build the documentation in the docs directory, you will need to have the Sphinx third-party Python package.
The easiest way to install Sphinx is via pip:
pip install sphinx
Additionally, you will need several Sphinx extensions that can be installed directly with pip:
pip install sphinx-numfig

pip install sphinxcontrib-katex
pip install sphinxcontrib-svg2pdfconverter
5.6. Building Sphinx Documentation 193

5.6.1 Building Documentation as a Webpage
To build the documentation as a webpage (what appears at https://docs.openmc.org), simply go to the docs directory
and run:
make html
5.6.2 Building Documentation as a PDF
To build PDF documentation, you will need to have a LaTeX distribution installed on your computer. Once you have a
LaTeX distribution installed, simply go to the docs directory and run:
make latexpdf
5.7 Deployment with Docker
OpenMC can be easily deployed using Docker on any Windows, Mac or Linux system. With Docker running, execute
the following command in the shell to build a Docker image called debian/openmc:latest:
docker build -t debian/openmc:latest https://github.com/openmc-dev/openmc.git#develop
Note: This may take 5 – 10 minutes to run to completion.
This command will execute the instructions in OpenMC’s Dockerfile to build a Docker image with OpenMC in-
stalled. The image includes OpenMC with MPICH and parallel HDF5 in the /opt/openmc directory, and Mini-
conda3 with all of the Python pre-requisites (NumPy, SciPy, Pandas, etc.) installed. The NJOY2016 codebase is
installed in /opt/NJOY2016 to support full functionality and testing of the openmc.data Python module. The pub-
licly available nuclear data libraries necessary to run OpenMC’s test suite – including NNDC and WMP cross sections
and ENDF data – are in the /opt/openmc/data directory, and the corresponding OPENMC_CROSS_SECTIONS,
OPENMC_MULTIPOLE_LIBRARY, and OPENMC_ENDF_DATA environment variables are initialized.
After building the Docker image, you can run the following to see the names of all images on your machine, including
debian/openmc:latest:
docker image ls
Now you can run the following to create a Docker container called my_openmc based on the debian/openmc:latest
image:
docker run -it --name=my_openmc debian/openmc:latest
This command will open an interactive shell running from within the Docker container where you have access to use
OpenMC.
Note: The docker run command supports many options for spawning containers – including mounting volumes
from the host filesystem – which many users will find useful.

CHAPTER
SIX
PYTHON API
OpenMC includes a rich Python API that enables programmatic pre- and post-processing. The easiest way to begin
using the API is to take a look at the examples. This assumes that you are already familiar with Python and common
third-party packages such as NumPy. If you have never used Python before, the prospect of learning a new code and
a programming language might sound daunting. However, you should keep in mind that there are many substantial
benefits to using the Python API, including:
• The ability to define dimensions using variables.
• Availability of standard-library modules for working with files.
• An entire ecosystem of third-party packages for scientific computing.
• Automated multi-group cross section generation (openmc.mgxs)
• A fully-featured nuclear data interface (openmc.data)
• Depletion capability (openmc.deplete)
• Convenience functions (e.g., a function returning a hexagonal region)
• Ability to plot individual universes as geometry is being created
• A 𝑘eff search function (openmc.search_for_keff())
• Random sphere packing for generating TRISO particle locations (openmc.model.pack_spheres())
• Ability to create materials based on natural elements or uranium enrichment
For those new to Python, there are many good tutorials available online. We recommend going through the modules
from Codecademy and/or the Scipy lectures.
The full API documentation serves to provide more information on a given module or class.
Tip: Users are strongly encouraged to use the Python API to generate input files and analyze results.
195
Modules
6.1 openmc – Basic Functionality
6.1.1 Handling nuclear data
openmc.XSdata A multi-group cross section data set providing all the

multi-group data necessary for a multi-group OpenMC
calculation.
openmc.MGXSLibrary Multi-Group Cross Sections file used for an OpenMC
simulation.
openmc.XSdata
class openmc.XSdata(name, energy_groups, temperatures=[294.0], representation='isotropic',

num_delayed_groups=0)
A multi-group cross section data set providing all the multi-group data necessary for a multi-group OpenMC
calculation.
Parameters
• name (str) – Name of the mgxs data set.
• energy_groups (openmc.mgxs.EnergyGroups) – Energy group structure
• representation ({'isotropic', 'angle'}, optional) – Method used in generating the
MGXS (isotropic or angle-dependent flux weighting). Defaults to ‘isotropic’
• temperatures (Iterable of float) – Temperatures (in units of Kelvin) of the provided
datasets. Defaults to a single temperature at 294K.
• num_delayed_groups (int) – Number of delayed groups
Variables
• name (str) – Unique identifier for the xsdata object
• atomic_weight_ratio (float) – Atomic weight ratio of an isotope. That is, the ratio of
the mass of the isotope to the mass of a single neutron.
• temperatures (numpy.ndarray) – Temperatures (in units of Kelvin) of the provided
datasets. Defaults to a single temperature at 294K.
• num_delayed_groups (int) – Num delayed groups
• fissionable (bool) – Whether or not this is a fissionable data set.
• scatter_format ({'legendre', 'histogram', or 'tabular'}) – Angular distribution
representation (legendre, histogram, or tabular)
• order (int) – Either the Legendre order, number of bins, or number of points used to de-
scribe the angular distribution associated with each group-to-group transfer probability.
• representation ({'isotropic', 'angle'}) – Method used in generating the MGXS
(isotropic or angle-dependent flux weighting).
196 Chapter 6. Python API

• num_azimuthal (int) – Number of equal width angular bins that the azimuthal angular
domain is subdivided into. This only applies when XSdata.representation is “angle”.
• num_polar (int) – Number of equal width angular bins that the polar angular domain is
subdivided into. This only applies when XSdata.representation is “angle”.
• total (list of numpy.ndarray) – Group-wise total cross section.
• absorption (list of numpy.ndarray) – Group-wise absorption cross section.
• scatter_matrix (list of numpy.ndarray) – Scattering moment matrices presented
with the columns representing incoming group and rows representing the outgoing group.
That is, down-scatter will be above the diagonal of the resultant matrix.
• multiplicity_matrix (list of numpy.ndarray) – Ratio of neutrons produced in scat-
tering collisions to the neutrons which undergo scattering collisions; that is, the multiplicity
provides the code with a scaling factor to account for neutrons produced in (n,xn) reactions.
• fission (list of numpy.ndarray) – Group-wise fission cross section.
• kappa_fission (list of numpy.ndarray) – Group-wise kappa_fission cross section.
• chi (list of numpy.ndarray) – Group-wise fission spectra ordered by increasing group
index (i.e., fast to thermal). This attribute should be used if making the common approxima-
tion that the fission spectra does not depend on incoming energy. If the user does not wish
to make this approximation, then this should not be provided and this information included
in the XSdata.nu_fission attribute instead.
• chi_prompt (list of numpy.ndarray) – Group-wise prompt fission spectra ordered by
increasing group index (i.e., fast to thermal). This attribute should be used if chi from prompt
and delayed neutrons is being set separately.
• chi_delayed (list of numpy.ndarray) – Group-wise delayed fission spectra ordered
by increasing group index (i.e., fast to thermal). This attribute should be used if chi from
prompt and delayed neutrons is being set separately.
• nu_fission (list of numpy.ndarray) – Group-wise fission production cross section
vector (i.e., if chi is provided), or is the group-wise fission production matrix.
• prompt_nu_fission (list of numpy.ndarray) – Group-wise prompt fission produc-
tion cross section vector.
• delayed_nu_fission (list of numpy.ndarray) – Group-wise delayed fission produc-
tion cross section vector.
• beta (list of numpy.ndarray) – Delayed-group-wise delayed neutron fraction cross
section vector.
• decay_rate (list of numpy.ndarray) – Delayed-group-wise decay rate vector.
• inverse_velocity (list of numpy.ndarray) – Inverse of velocity, in units of sec/cm.
• xs_shapes (dict of iterable of int) – Dictionary with keys of _XS_SHAPES and
iterable of int values with the corresponding shapes where “Order” corresponds to the pn
scattering order, “G” corresponds to incoming energy group, “G’” corresponds to outgoing
energy group, and “DG” corresponds to delayed group.
6.1. openmc – Basic Functionality 197

Notes
The parameters containing cross section data have dimensionalities which depend upon the value of XSdata.
representation as well as the number of Legendre or other angular dimensions as described by XSdata.
order. The XSdata.xs_shapes are provided to obtain the dimensionality of the data for each temperature.
The following are cross sections which should use each of the properties. Note that some cross sections can be
input in more than one shape so they are listed multiple times:
[G][G’][Order]: scatter_matrix
[G]: total, absorption, fission, kappa_fission, nu_fission,
prompt_nu_fission, delayed_nu_fission, inverse_velocity
[G’]: chi, chi_prompt, chi_delayed
[G][G’]: multiplicity_matrix, nu_fission, prompt_nu_fission
[DG]: beta, decay_rate
[DG][G]: delayed_nu_fission, beta, decay_rate
[DG][G’]: chi_delayed
[DG][G][G’]: delayed_nu_fission
add_temperature(temperature)
This method re-sizes the attributes of this XSdata object so that it can accommodate an additional temper-
ature. Note that the set_* methods will still need to be executed.
Parameters
temperature (float) – Temperature (in units of Kelvin) of the provided dataset.
convert_representation(target_representation, num_polar=None, num_azimuthal=None)
Produce a new XSdata object with the same data, but converted to the new representation (isotropic or
angle-dependent).
This method cannot be used to change the number of polar or azimuthal bins of an XSdata object that
already uses an angular representation. Finally, this method simply uses an arithmetic mean to convert
from an angular to isotropic representation; no flux-weighting is applied and therefore reaction rates will
not be preserved.
Parameters
• target_representation ({'isotropic', 'angle'}) – Representation of the MGXS
• num_polar (int, optional) – Number of equal width angular bins that the polar angular
domain is subdivided into. This is required when target_representation is “angle”.
• num_azimuthal (int, optional) – Number of equal width angular bins that the az-
imuthal angular domain is subdivided into. This is required when target_representation is
“angle”.
Returns
Multi-group cross section data with the same data as self, but represented as specified in
target_representation.
Return type
openmc.XSdata

convert_scatter_format(target_format, target_order=None)
Produce a new MGXSLibrary object with the same data, but converted to the new scatter format and order
Parameters
• target_format ({'tabular', 'legendre', 'histogram'}) – Representation of the
scattering angle distribution
• target_order (int) – Either the Legendre target_order, number of bins, or number of
points used to describe the angular distribution associated with each group-to-group trans-
fer probability
Returns
Multi-group cross section data with the same data as in self, but represented as specified in
target_format.
Return type
openmc.XSdata
classmethod from_hdf5(group, name, energy_groups, num_delayed_groups)
Generate XSdata object from an HDF5 group
Parameters
• group (h5py.Group) – HDF5 group to read from
• name (str) – Name of the mgxs data set.
Returns
Multi-group cross section data
Return type
openmc.XSdata
set_absorption(absorption, temperature=294.0)
This method sets the cross section for this XSdata object at the provided temperature.
Parameters
• absorption (np.ndarray) – Absorption Cross Section
• temperature (float) – Temperature (in Kelvin) of the data. Defaults to room tempera-
ture (294K).
See also:
openmc.mgxs_library.set_absorption_mgxs
set_absorption_mgxs(absorption, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.AbsorptionXS to be used to set the absorption cross section for
this XSdata object.
Parameters
• absorption (openmc.mgxs.AbsorptionXS) – MGXS Object containing the absorption
cross section for the domain of interest.
ture (294K).

• nuclide (str) – Individual nuclide (or ‘total’ if obtaining material-wise data) to gather
data for. Defaults to ‘total’.
• xs_type ({'macro', 'micro'}) – Provide the macro or micro cross section in units of
cm^-1 or barns. Defaults to ‘macro’.
• subdomain (iterable of int) – If the MGXS contains a mesh domain type, the sub-
domain parameter specifies which mesh cell (i.e., [i, j, k] index) to use.
See also:
openmc.mgxs.Library.create_mg_library, openmc.mgxs.Library.get_xsdata
set_beta(beta, temperature=294.0)
Parameters
• beta (np.ndarray) – Delayed fission spectrum
• temperature (float) – Temperature (in units of Kelvin) of the provided dataset. Defaults
to 294K
See also:
openmc.mgxs_library.set_beta_mgxs
set_beta_mgxs(beta, temperature=294.0, nuclide='total', xs_type='macro', subdomain=None)
This method allows for an openmc.mgxs.Beta to be used to set beta for this XSdata object.
Parameters
• beta (openmc.mgxs.Beta) – MGXS Object containing beta for the domain of interest.
to 294K
See also:
set_chi(chi, temperature=294.0)
Parameters
• chi (np.ndarray) – Fission Spectrum
ture (294K).
See also:
openmc.mgxs_library.set_chi_mgxs

set_chi_delayed(chi_delayed, temperature=294.0)
Parameters
• chi_delayed (np.ndarray) – Delayed fission Spectrum
to 294K
See also:
openmc.mgxs_library.set_chi_delayed_mgxs
set_chi_delayed_mgxs(chi_delayed, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.ChiDelayed to be used to set chi-delayed for this XSdata object.
Parameters
• chi_delayed (openmc.mgxs.ChiDelayed) – MGXS Object containing chi-delayed for
the domain of interest.
to 294K
See also:
set_chi_mgxs(chi, temperature=294.0, nuclide='total', xs_type='macro', subdomain=None)
This method allows for an openmc.mgxs.Chi to be used to set chi for this XSdata object.
Parameters
• chi (openmc.mgxs.Chi) – MGXS Object containing chi for the domain of interest.
ture (294K).
See also:

set_chi_prompt(chi_prompt, temperature=294.0)
Parameters
• chi_prompt (np.ndarray) – Prompt fission Spectrum
to 294K
See also:
openmc.mgxs_library.set_chi_prompt_mgxs
set_chi_prompt_mgxs(chi_prompt, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.Chi to be used to set chi-prompt for this XSdata object.
Parameters
• chi_prompt (openmc.mgxs.Chi) – MGXS Object containing chi-prompt for the domain
of interest.
to 294K
See also:
set_decay_rate(decay_rate, temperature=294.0)
Parameters
• decay_rate (np.ndarray) – Delayed neutron precursor decay rate
to 294K
See also:
openmc.mgxs_library.set_decay_rate_mgxs
set_decay_rate_mgxs(decay_rate, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.DecayRate to be used to set decay rate for this XSdata object.
Parameters
• decay_rate (openmc.mgxs.DecayRate) – MGXS Object containing decay rate for the
domain of interest.
to 294K

See also:
set_delayed_nu_fission(delayed_nu_fission, temperature=294.0)
Parameters
• delayed_nu_fission (np.ndarray) – Delayed-nu-fission Cross Section
to 294K
See also:
openmc.mgxs_library.set_delayed_nu_fission_mgxs
set_delayed_nu_fission_mgxs(delayed_nu_fission, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.DelayedNuFissionXS or
openmc.mgxs.DelayedNuFissionMatrixXS to be used to set the delayed-nu-fission cross section for
this XSdata object.
Parameters
• delayed_nu_fission (openmc.mgxs.DelayedNuFissionXS or openmc.mgxs.
DelayedNuFissionMatrixXS) – MGXS Object containing the delayed-nu-fission cross
section for the domain of interest.
to 294K
See also:
set_fission(fission, temperature=294.0)
Parameters
• fission (np.ndarray) – Fission Cross Section
ture (294K).

See also:
openmc.mgxs_library.set_fission_mgxs
set_fission_mgxs(fission, temperature=294.0, nuclide='total', xs_type='macro', subdomain=None)
This method allows for an openmc.mgxs.FissionXS to be used to set the fission cross section for this XSdata
object.
Parameters
• fission (openmc.mgxs.FissionXS) – MGXS Object containing the fission cross sec-
tion for the domain of interest.
ture (294K).
See also:
set_inverse_velocity(inv_vel, temperature=294.0)
This method sets the inverse velocity for this XSdata object at the provided temperature.
Parameters
• inv_vel (np.ndarray) – Inverse velocity in units of sec/cm.
ture (294K).
set_inverse_velocity_mgxs(inverse_velocity, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.InverseVelocity to be used to set the inverse velocity for this XSdata
object.
Parameters
• inverse_velocity (openmc.mgxs.InverseVelocity) – MGXS object containing the
inverse velocity for the domain of interest.
ture (294K).
See also:

set_kappa_fission(kappa_fission, temperature=294.0)
Parameters
• kappa_fission (np.ndarray) – Kappa-Fission Cross Section
ture (294K).
See also:
openmc.mgxs_library.set_kappa_fission_mgxs
set_kappa_fission_mgxs(k_fission, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.KappaFissionXS to be used to set the kappa-fission cross section
for this XSdata object.
Parameters
• kappa_fission (openmc.mgxs.KappaFissionXS) – MGXS Object containing the
kappa-fission cross section for the domain of interest.
ture (294K).
See also:
set_multiplicity_matrix(multiplicity, temperature=294.0)
Parameters
• multiplicity (np.ndarray) – Multiplicity Matrix Cross Section
ture (294K).
See also:
openmc.mgxs_library.set_multiplicity_matrix_mgxs
set_multiplicity_matrix_mgxs(nuscatter, scatter=None, temperature=294.0, nuclide='total',
xs_type='macro', subdomain=None)
This method allows for either the direct use of only an openmc.mgxs.MultiplicityMatrixXS or an
openmc.mgxs.ScatterMatrixXS and openmc.mgxs.ScatterMatrixXS to be used to set the scattering mul-
tiplicity for this XSdata object. Multiplicity, in OpenMC parlance, is a factor used to account for the
production of neutrons introduced by scattering multiplication reactions, i.e., (n,xn) events. In this sense,
the multiplication matrix is simply defined as the ratio of the nu-scatter and scatter matrices.
Parameters

• nuscatter (openmc.mgxs.ScatterMatrixXS or openmc.mgxs.

MultiplicityMatrixXS) – MGXS Object containing the matrix cross section for
the domain of interest.
• scatter (openmc.mgxs.ScatterMatrixXS) – MGXS Object containing the scattering
matrix cross section for the domain of interest.
ture (294K).
See also:
set_nu_fission(nu_fission, temperature=294.0)
Parameters
• nu_fission (np.ndarray) – Nu-fission Cross Section
ture (294K).
See also:
openmc.mgxs_library.set_nu_fission_mgxs
set_nu_fission_mgxs(nu_fission, temperature=294.0, nuclide='total', xs_type='macro', subdomain=None)
This method allows for an openmc.mgxs.FissionXS to be used to set the nu-fission cross section for this
XSdata object.
Parameters
• nu_fission (openmc.mgxs.FissionXS) – MGXS Object containing the nu-fission cross
section for the domain of interest.
ture (294K).
See also:
set_prompt_nu_fission(prompt_nu_fission, temperature=294.0)

Parameters
• prompt_nu_fission (np.ndarray) – Prompt-nu-fission Cross Section
to 294K
See also:
openmc.mgxs_library.set_prompt_nu_fission_mgxs
set_prompt_nu_fission_mgxs(prompt_nu_fission, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
Sets the prompt-nu-fission cross section.
This method allows for an openmc.mgxs.FissionXS or openmc.mgxs.NuFissionMatrixXS to be used to set
the prompt-nu-fission cross section for this XSdata object.
Parameters
• prompt_nu_fission (openmc.mgxs.FissionXS or openmc.mgxs.
NuFissionMatrixXS) – MGXS Object containing the prompt-nu-fission cross section
for the domain of interest.
to 294K
See also:
set_scatter_matrix(scatter, temperature=294.0)
Parameters
• scatter (np.ndarray) – Scattering Matrix Cross Section
ture (294K).
See also:
openmc.mgxs_library.set_scatter_matrix_mgxs
set_scatter_matrix_mgxs(scatter, temperature=294.0, nuclide='total', xs_type='macro',
subdomain=None)
This method allows for an openmc.mgxs.ScatterMatrixXS to be used to set the scatter matrix cross section
for this XSdata object. If the XSdata.order attribute has not yet been set, then it will be set based on the
properties of scatter.
Parameters
• scatter (openmc.mgxs.ScatterMatrixXS) – MGXS Object containing the scatter ma-
trix cross section for the domain of interest.

ture (294K).
See also:
set_total(total, temperature=294.0)
Parameters
• total (np.ndarray) – Total Cross Section
ture (294K).
See also:
openmc.mgxs_library.set_total_mgxs
set_total_mgxs(total, temperature=294.0, nuclide='total', xs_type='macro', subdomain=None)
This method allows for an openmc.mgxs.TotalXS or openmc.mgxs.TransportXS to be used to set the total
cross section for this XSdata object.
Parameters
• total (openmc.mgxs.TotalXS or openmc.mgxs.TransportXS) – MGXS Object
containing the total, transport or nu-transport cross section for the domain of interest.
ture (294K).
See also:
to_hdf5(file)
Write XSdata to an HDF5 file
Parameters
file (h5py.File) – HDF5 File (a root Group) to write to

openmc.MGXSLibrary
class openmc.MGXSLibrary(energy_groups, num_delayed_groups=0)

Multi-Group Cross Sections file used for an OpenMC simulation. Corresponds directly to the MG version of the
cross_sections.xml input file.
Parameters
Variables
• energy_groups (openmc.mgxs.EnergyGroups) – Energy group structure.
• xsdatas (Iterable of openmc.XSdata) – Iterable of multi-Group cross section data ob-
jects
add_xsdata(xsdata)
Add an XSdata entry to the file.
Parameters
xsdata (openmc.XSdata) – MGXS information to add
add_xsdatas(xsdatas)
Add multiple XSdatas to the file.
Parameters
xsdatas (tuple or list of openmc.XSdata) – XSdatas to add
convert_representation(target_representation, num_polar=None, num_azimuthal=None)
Produce a new XSdata object with the same data, but converted to the new representation (isotropic or
angle-dependent).
This method cannot be used to change the number of polar or azimuthal bins of an XSdata object that
already uses an angular representation. Finally, this method simply uses an arithmetic mean to convert
from an angular to isotropic representation; no flux-weighting is applied and therefore the reaction rates
will not be preserved.
Parameters
• target_representation ({'isotropic', 'angle'}) – Representation of the MGXS
• num_polar (int, optional) – Number of equal width angular bins that the polar angular
domain is subdivided into. This is required when target_representation is “angle”.
• num_azimuthal (int, optional) – Number of equal width angular bins that the az-
imuthal angular domain is subdivided into. This is required when target_representation is
“angle”.
Returns
Multi-group Library with the same data as self, but represented as specified in tar-
get_representation.
Return type
openmc.MGXSLibrary

convert_scatter_format(target_format, target_order)
Produce a new MGXSLibrary object with the same data, but converted to the new scatter format and order
Parameters
• target_format ({'tabular', 'legendre', 'histogram'}) – Representation of the
scattering angle distribution
• target_order (int) – Either the Legendre target_order, number of bins, or number of
points used to describe the angular distribution associated with each group-to-group trans-
fer probability
Returns
Multi-group Library with the same data as self, but with the scatter format represented as
specified in target_format and target_order.
Return type
openmc.MGXSLibrary
export_to_hdf5(filename='mgxs.h5', libver='earliest')
Create an hdf5 file that can be used for a simulation.
Parameters
• filename (str) – Filename of file, default is mgxs.h5.
• libver ({'earliest', 'latest'}) – Compatibility mode for the HDF5 file. ‘latest’ will
produce files that are less backwards compatible but have performance benefits.
classmethod from_hdf5(filename=None)
Generate an MGXS Library from an HDF5 group or file
Parameters
filename (str, optional) – Name of HDF5 file containing MGXS data. Default is None.
If not provided, the value of the OPENMC_MG_CROSS_SECTIONS environmental variable
will be used
Returns
Multi-group cross section data object.
Return type
openmc.MGXSLibrary
get_by_name(name)
Access the XSdata objects by name
Parameters
name (str) – Name of openmc.XSdata object to obtain
Returns
result – Provides the matching XSdata object or None, if not found
Return type
openmc.XSdata or None
remove_xsdata(xsdata)
Remove a xsdata from the file
Parameters
xsdata (openmc.XSdata) – XSdata to remove

6.1.2 Simulation Settings
openmc.Source Distribution of phase space coordinates for source sites.

openmc.SourceParticle Source particle
openmc.VolumeCalculation Stochastic volume calculation specifications and results.
openmc.WeightWindows Mesh-based weight windows
openmc.Settings Settings used for an OpenMC simulation.
openmc.Source
class openmc.Source(space=None, angle=None, energy=None, time=None, filename=None, library=None,

parameters=None, strength=1.0, particle='neutron')
Distribution of phase space coordinates for source sites.
Parameters
• space (openmc.stats.Spatial) – Spatial distribution of source sites
• angle (openmc.stats.UnitSphere) – Angular distribution of source sites
• energy (openmc.stats.Univariate) – Energy distribution of source sites
• time (openmc.stats.Univariate) – time distribution of source sites
• filename (str) – Source file from which sites should be sampled
• library (str) – Path to a custom source library
• parameters (str) – Parameters to be provided to the custom source library
New in version 0.12.
• strength (float) – Strength of the source
• particle ({'neutron', 'photon'}) – Source particle type
Variables
• space (openmc.stats.Spatial or None) – Spatial distribution of source sites
• angle (openmc.stats.UnitSphere or None) – Angular distribution of source sites
• energy (openmc.stats.Univariate or None) – Energy distribution of source sites
• time (openmc.stats.Univariate or None) – time distribution of source sites
• file (str or None) – Source file from which sites should be sampled
• library (str or None) – Path to a custom source library
• parameters (str) – Parameters to be provided to the custom source library
• strength (float) – Strength of the source
• particle ({'neutron', 'photon'}) – Source particle type
classmethod from_xml_element(elem)
Generate source from an XML element
Parameters
elem (xml.etree.ElementTree.Element) – XML element

Returns
Source generated from XML element
Return type
openmc.Source
to_xml_element()
Return XML representation of the source
Returns
element – XML element containing source data
Return type
xml.etree.ElementTree.Element
openmc.SourceParticle
class openmc.SourceParticle(r=(0.0, 0.0, 0.0), u=(0.0, 0.0, 1.0), E=1000000.0, time=0.0, wgt=1.0,
delayed_group=0, surf_id=0, particle=ParticleType.NEUTRON)
Source particle
This class can be used to create source particles that can be written to a file and used by OpenMC
Parameters
• r (iterable of float) – Position of particle in Cartesian coordinates
• u (iterable of float) – Directional cosines
• E (float) – Energy of particle in [eV]
• time (float) – Time of particle in [s]
• wgt (float) – Weight of the particle
• delayed_group (int) – Delayed group particle was created in (neutrons only)
• surf_id (int) – Surface ID where particle is at, if any.
• particle (ParticleType) – Type of the particle
to_tuple()
Return source particle attributes as a tuple
Returns
Source particle attributes
Return type
tuple
openmc.VolumeCalculation
class openmc.VolumeCalculation(domains, samples, lower_left=None, upper_right=None)

Stochastic volume calculation specifications and results.
Parameters
• domains (Iterable of openmc.Cell, openmc.Material, or openmc.Universe)
– Domains to find volumes of
• samples (int) – Number of samples used to generate volume estimates

• lower_left (Iterable of float) – Lower-left coordinates of bounding box used to sam-

ple points. If this argument is not supplied, an attempt is made to automatically determine a
bounding box.
• upper_right (Iterable of float) – Upper-right coordinates of bounding box used to
sample points. If this argument is not supplied, an attempt is made to automatically determine
a bounding box.
Variables
• ids (Iterable of int) – IDs of domains to find volumes of
• domain_type ({'cell', 'material', 'universe'}) – Type of each domain
• samples (int) – Number of samples used to generate volume estimates
• lower_left (Iterable of float) – Lower-left coordinates of bounding box used to sam-
ple points
• upper_right (Iterable of float) – Upper-right coordinates of bounding box used to
sample points
• atoms (dict) – Dictionary mapping unique IDs of domains to a mapping of nuclides to
total number of atoms for each nuclide present in the domain. For example, {10: {‘U235’:
1.0e22, ‘U238’: 5.0e22, . . . }}.
• atoms_dataframe (pandas.DataFrame) – DataFrame showing the estimated number of
atoms for each nuclide present in each domain specified.
• volumes (dict) – Dictionary mapping unique IDs of domains to estimated volumes in cm^3.
• threshold (float) – Threshold for the maximum standard deviation of volumes.
• trigger_type ({'variance', 'std_dev', 'rel_err'}) – Value type used to halt volume
calculation
• iterations (int) – Number of iterations over samples (for calculations with a trigger).
classmethod from_hdf5(filename)
Load stochastic volume calculation results from HDF5 file.
Parameters
filename (str) – Path to volume.h5 file
Returns
Results of the stochastic volume calculation
Return type
Generate volume calculation object from an XML element
New in version 0.13.0.
Parameters

Returns
Volume calculation object
Return type
load_results(filename)
Load stochastic volume calculation results from an HDF5 file.
Parameters
filename (str) – Path to volume.h5 file
set_trigger(threshold, trigger_type)
Set a trigger on the volume calculation
Parameters
• threshold (float) – Threshold for the maximum standard deviation of volumes
• trigger_type ({'variance', 'std_dev', 'rel_err'}) – Value type used to halt volume
calculation
to_xml_element()
Return XML representation of the volume calculation
Returns
element – XML element containing volume calculation data
Return type
openmc.WeightWindows
class openmc.WeightWindows(mesh, lower_ww_bounds, upper_ww_bounds=None, upper_bound_ratio=None,

energy_bounds=None, particle_type='neutron', survival_ratio=3,
max_lower_bound_ratio=None, max_split=10, weight_cutoff=1e-38, id=None)
Mesh-based weight windows
This class enables you to specify weight window parameters that are used in a simulation. Multiple sets of weight
windows can be defined for different meshes and different particles. An iterable of WeightWindows instances
can be assigned to the openmc.Settings.weight_windows attribute, which is then exported to XML.
Weight window lower/upper bounds are to be specified for each combination of a mesh element and an energy
bin. Thus the total number of bounds should be equal to the product of the number of mesh bins and the number
of energy bins.
Parameters
• mesh (openmc.MeshBase) – Mesh for the weight windows
• lower_ww_bounds (Iterable of Real) – A list of values for which each value is the
lower bound of a weight window
• upper_ww_bounds (Iterable of Real) – A list of values for which each value is the
upper bound of a weight window
• upper_bound_ratio (float) – Ratio of the lower to upper weight window bounds

• energy_bounds (Iterable of Real) – A list of values for which each successive pair
constitutes a range of energies in [eV] for a single bin
• particle_type ({'neutron', 'photon'}) – Particle type the weight windows apply to
• survival_ratio (float) – Ratio of the survival weight to the lower weight window bound
for rouletting
• max_lower_bound_ratio (float) – Maximum allowed ratio of a particle’s weight to the
weight window’s lower bound. A factor will be applied to raise the weight window to be
lower than the particle’s weight by a factor of max_lower_bound_ratio during transport if
exceeded.
• max_split (int) – Maximum allowable number of particles when splitting
• weight_cutoff (float) – Threshold below which particles will be terminated
• id (int) – Unique identifier for the weight window settings. If not specified, an identifier
will automatically be assigned.
Variables
• id (int) – Unique identifier for the weight window settings.
• mesh (openmc.MeshBase) – Mesh for the weight windows with dimension (ni, nj, nk)
• particle_type (str) – Particle type the weight windows apply to
• energy_bounds (Iterable of Real) – A list of values for which each successive pair
constitutes a range of energies in [eV] for a single bin
• num_energy_bins (int) – Number of energy bins
• lower_ww_bounds (numpy.ndarray of float) – An array of values for which each value
is the lower bound of a weight window. Shape: (ni, nj, nk, num_energy_bins) for Struc-
turedMesh; (num_elements, num_energy_bins) for UnstructuredMesh
• upper_ww_bounds (numpy.ndarray of float) – An array of values for which each value
is the upper bound of a weight window. Shape: (ni, nj, nk, num_energy_bins) for Struc-
turedMesh; (num_elements, num_energy_bins) for UnstructuredMesh
• survival_ratio (float) – Ratio of the survival weight to the lower weight window bound
for rouletting
• max_lower_bound_ratio (float) – Maximum allowed ratio of a particle’s weight to the
weight window’s lower bound. (Default: 1.0)
• max_split (int) – Maximum allowable number of particles when splitting
• weight_cutoff (float) – Threshold below which particles will be terminated
See also:
openmc.Settings
classmethod from_hdf5(group, meshes)
Create weight windows from HDF5 group
Parameters
• group (h5py.Group) – Group in HDF5 file
• meshes (dict) – Dictionary mapping IDs to mesh objects
Returns
A weight window object

Return type
classmethod from_xml_element(elem, root)
Generate weight window settings from an XML element
Parameters
• elem (xml.etree.ElementTree.Element) – XML element
• root (xml.etree.ElementTree.Element) – Root element for the file where meshes can
be found
Returns
Weight windows object
Return type
to_xml_element()
Return an XML representation of the weight window settings
Returns
element – XML element containing the weight window information
Return type
openmc.Settings
class openmc.Settings(**kwargs)
Settings used for an OpenMC simulation.
Parameters
**kwargs (dict, optional) – Any keyword arguments are used to set attributes on the in-
stance.
Variables
• batches (int) – Number of batches to simulate
• confidence_intervals (bool) – If True, uncertainties on tally results will be reported
as the half-width of the 95% two-sided confidence interval. If False, uncertainties on tally
results will be reported as the sample standard deviation.
• create_fission_neutrons (bool) – Indicate whether fission neutrons should be created
or not.
• cutoff (dict) – Dictionary defining weight cutoff and energy cutoff. The dictionary may
have six keys, ‘weight’, ‘weight_avg’, ‘energy_neutron’, ‘energy_photon’, ‘energy_electron’,
and ‘energy_positron’. Value for ‘weight’ should be a float indicating weight cutoff below
which particle undergo Russian roulette. Value for ‘weight_avg’ should be a float indicating
weight assigned to particles that are not killed after Russian roulette. Value of energy should
be a float indicating energy in eV below which particle type will be killed.
• delayed_photon_scaling (bool) – Indicate whether to scale the fission photon yield by
(EGP + EGD)/EGP where EGP is the energy release of prompt photons and EGD is the
energy release of delayed photons.

• electron_treatment ({'led', 'ttb'}) – Whether to deposit all energy from electrons lo-
cally (‘led’) or create secondary bremsstrahlung photons (‘ttb’).
• energy_mode ({'continuous-energy', 'multi-group'}) – Set whether the calculation
should be continuous-energy or multi-group.
• entropy_mesh (openmc.RegularMesh) – Mesh to be used to calculate Shannon entropy.
If the mesh dimensions are not specified, OpenMC assigns a mesh such that 20 source sites
per mesh cell are to be expected on average.
• event_based (bool) – Indicate whether to use event-based parallelism instead of the default
history-based parallelism.
• generations_per_batch (int) – Number of generations per batch
• max_lost_particles (int) – Maximum number of lost particles
• rel_max_lost_particles (float) – Maximum number of lost particles, relative to the
total number of particles
• inactive (int) – Number of inactive batches
• keff_trigger (dict) – Dictionary defining a trigger on eigenvalue. The dictionary must
have two keys, ‘type’ and ‘threshold’. Acceptable values corresponding to type are ‘vari-
ance’, ‘std_dev’, and ‘rel_err’. The threshold value should be a float indicating the variance,
standard deviation, or relative error used.
• log_grid_bins (int) – Number of bins for logarithmic energy grid search
• material_cell_offsets (bool) – Generate an “offset table” for material cells by default.
These tables are necessary when a particular instance of a cell needs to be tallied.
• max_particles_in_flight (int) – Number of neutrons to run concurrently when using
event-based parallelism.
• max_order (None or int) – Maximum scattering order to apply globally when in multi-
group mode.
• max_splits (int) – Maximum number of times a particle can split during a history
• max_tracks (int) – Maximum number of tracks written to a track file (per MPI process).
• no_reduce (bool) – Indicate that all user-defined and global tallies should not be reduced
across processes in a parallel calculation.
• output (dict) – Dictionary indicating what files to output. Acceptable keys are:
path
String indicating a directory where output files should be written
summary
Whether the ‘summary.h5’ file should be written (bool)

tallies
Whether the ‘tallies.out’ file should be written (bool)
• particles (int) – Number of particles per generation
• photon_transport (bool) – Whether to use photon transport.
• ptables (bool) – Determine whether probability tables are used.
• resonance_scattering (dict) – Settings for resonance elastic scattering. Accepted keys
are ‘enable’ (bool), ‘method’ (str), ‘energy_min’ (float), ‘energy_max’ (float), and ‘nuclides’
(list). The ‘method’ can be set to ‘dbrc’ (Doppler broadening rejection correction) or ‘rvs’
(relative velocity sampling). If not specified, ‘rvs’ is the default method. The ‘energy_min’
and ‘energy_max’ values indicate the minimum and maximum energies above and below
which the resonance elastic scattering method is to be applied. The ‘nuclides’ list indicates
what nuclides the method should be applied to. In its absence, the method will be applied to
all nuclides with 0 K elastic scattering data present.
• run_mode ({'eigenvalue', 'fixed source', 'plot', 'volume', 'particle
restart'}) – The type of calculation to perform (default is ‘eigenvalue’)
• seed (int) – Seed for the linear congruential pseudorandom number generator
• source (Iterable of openmc.Source) – Distribution of source sites in space, angle, and
energy
• sourcepoint (dict) – Options for writing source points. Acceptable keys are:
batches
list of batches at which to write source
overwrite
bool indicating whether to overwrite
separate
bool indicating whether the source should be written as a separate file
write
bool indicating whether or not to write the source
• statepoint (dict) – Options for writing state points. Acceptable keys are:
batches
list of batches at which to write source
• surf_source_read (dict) – Options for reading surface source points. Acceptable keys
are:
path
Path to surface source file (str).
• surf_source_write (dict) – Options for writing surface source points. Acceptable keys
are:
surface_ids
List of surface ids at which crossing particles are to be banked (int)
max_particles
Maximum number of particles to be banked on surfaces per process (int)
• survival_biasing (bool) – Indicate whether survival biasing is to be used

• tabular_legendre (dict) – Determines if a multi-group scattering moment kernel ex-

panded via Legendre polynomials is to be converted to a tabular distribution or not. Ac-
cepted keys are ‘enable’ and ‘num_points’. The value for ‘enable’ is a bool stating whether
the conversion to tabular is performed; the value for ‘num_points’ sets the number of points
to use in the tabular distribution, should ‘enable’ be True.
• temperature (dict) – Defines a default temperature and method for treating intermediate
temperatures at which nuclear data doesn’t exist. Accepted keys are ‘default’, ‘method’,
‘range’, ‘tolerance’, and ‘multipole’. The value for ‘default’ should be a float representing the
default temperature in Kelvin. The value for ‘method’ should be ‘nearest’ or ‘interpolation’.
If the method is ‘nearest’, ‘tolerance’ indicates a range of temperature within which cross
sections may be used. The value for ‘range’ should be a pair a minimum and maximum
temperatures which are used to indicate that cross sections be loaded at all temperatures
within the range. ‘multipole’ is a boolean indicating whether or not the windowed multipole
method should be used to evaluate resolved resonance cross sections.
• trace (tuple or list) – Show detailed information about a single particle, indicated by
three integers: the batch number, generation number, and particle number
• track (tuple or list) – Specify particles for which track files should be written. Each
particle is identified by a tuple with the batch number, generation number, and particle num-
ber.
• trigger_active (bool) – Indicate whether tally triggers are used
• trigger_batch_interval (int) – Number of batches in between convergence checks
• trigger_max_batches (int) – Maximum number of batches simulated. If this is set, the
number of batches specified via batches is interpreted as the minimum number of batches
• ufs_mesh (openmc.RegularMesh) – Mesh to be used for redistributing source sites via the
uniform fission site (UFS) method.
• verbosity (int) – Verbosity during simulation between 1 and 10. Verbosity levels are
described in <verbosity> Element.
• volume_calculations (VolumeCalculation or iterable of
VolumeCalculation) – Stochastic volume calculation specifications
• weight_windows (WeightWindows iterable of WeightWindows) – Weight windows
to use for variance reduction
• weight_windows_on (bool) – Whether weight windows are enabled
• write_initial_source (bool) – Indicate whether to write the initial source distribution
to file
export_to_xml(path: Union[str, PathLike] = 'settings.xml')
Export simulation settings to an XML file.
Parameters
path (str) – Path to file to write. Defaults to ‘settings.xml’.
classmethod from_xml(path: Union[str, PathLike] = 'settings.xml')
Generate settings from XML file

Parameters
path (str, optional) – Path to settings XML file
Returns
Settings object
Return type
openmc.Settings
openmc.write_source_file Write a source file using a collection of source particles

openmc.wwinp_to_wws Create WeightWindows instances from a wwinp file
openmc.write_source_file
openmc.write_source_file(source_particles, filename, **kwargs)

Write a source file using a collection of source particles
Parameters
• source_particles (iterable of SourceParticle) – Source particles to write to file
• filename (str or path-like) – Path to source file to write
• **kwargs – Keyword arguments to pass to h5py.File
See also:
openmc.SourceParticle
openmc.wwinp_to_wws
openmc.wwinp_to_wws(path)
Create WeightWindows instances from a wwinp file
Parameters
path (str or pathlib.Path ) – Path to the wwinp file
Return type
list of openmc.WeightWindows
6.1.3 Material Specification
openmc.Nuclide A nuclide that can be used in a material.

openmc.Element A natural element that auto-expands to add the isotopes
of an element to a material in their natural abundance.
openmc.Macroscopic A Macroscopic object that can be used in a material.
openmc.Material A material composed of a collection of nu-
clides/elements.
openmc.Materials Collection of Materials used for an OpenMC simulation.

openmc.Nuclide
class openmc.Nuclide(name)
A nuclide that can be used in a material.
Parameters
name (str) – Name of the nuclide, e.g. ‘U235’
Variables
openmc.Element
class openmc.Element(name)
A natural element that auto-expands to add the isotopes of an element to a material in their natural abundance.
Internally, the OpenMC Python API expands the natural element into isotopes only when the materials.xml file
is created.
Parameters
name (str) – Chemical symbol of the element, e.g. Pu
Variables
name (str) – Chemical symbol of the element, e.g. Pu
expand(percent, percent_type, enrichment=None, enrichment_target=None, enrichment_type=None,
cross_sections=None)
Expand natural element into its naturally-occurring isotopes.
An optional cross_sections argument or the OPENMC_CROSS_SECTIONS environment variable is used to
specify a cross_sections.xml file. If the cross_sections.xml file is found, the element is expanded only into
the isotopes/nuclides present in cross_sections.xml. If no cross_sections.xml file is found, the element is
expanded based on its naturally occurring isotopes.
Parameters
• percent (float) – Atom or weight percent
• percent_type ({'ao', 'wo'}) – ‘ao’ for atom percent and ‘wo’ for weight percent
• enrichment (float, optional) – Enrichment of an enrichment_target nuclide in per-
cent (ao or wo). If enrichment_target is not supplied then it is enrichment for U235 in
weight percent. For example, input 4.95 for 4.95 weight percent enriched U. Default is
None (natural composition).
• enrichment_target (str, optional) – Single nuclide name to enrich from a natural
composition (e.g., ‘O16’)
• enrichment_type ({'ao', 'wo'}, optional) – ‘ao’ for enrichment as atom percent and
‘wo’ for weight percent. Default is: ‘ao’ for two-isotope enrichment; ‘wo’ for U enrichment
• cross_sections (str, optional) – Location of cross_sections.xml file. Default is
None.
Returns
isotopes – Naturally-occurring isotopes of the element. Each item of the list is a tuple con-
sisting of a nuclide string, the atom/weight percent, and the string ‘ao’ or ‘wo’.

Return type
list
Raises
• ValueError – No data is available for any of natural isotopes of the element
• ValueError – If only some natural isotopes are available in the cross-section data library
and the element is not O, W, or Ta
• ValueError – If a non-naturally-occurring isotope is requested
• ValueError – If enrichment is requested of an element with more than two naturally-
occurring isotopes.
• ValueError – If enrichment procedure for Uranium is used when element is not Uranium.
• ValueError – Uranium enrichment is requested with enrichment_type==’ao’
Notes
When the enrichment argument is specified, a correlation from ORNL/CSD/TM-244 is used to calculate
the weight fractions of U234, U235, U236, and U238. Namely, the weight fraction of U234 and U236 are
taken to be 0.89% and 0.46%, respectively, of the U235 weight fraction. The remainder of the isotopic
weight is assigned to U238.
When the enrichment argument is specified with enrichment_target, a general enrichment procedure is
used for elements composed of exactly two naturally-occurring isotopes. enrichment is interpreted as atom
percent by default but can be controlled by the enrichment_type argument.
openmc.Macroscopic
class openmc.Macroscopic(name)
A Macroscopic object that can be used in a material.
Parameters
name (str) – Name of the macroscopic data, e.g. UO2
Variables
name (str) – Name of the nuclide, e.g. UO2
openmc.Material
class openmc.Material(material_id=None, name='', temperature=None)

A material composed of a collection of nuclides/elements.
To create a material, one should create an instance of this class, add nuclides or elements with Material.
add_nuclide() or Material.add_element(), respectively, and set the total material density with
Material.set_density(). Alternatively, you can use Material.add_components() to pass a dictionary
containing all the component information. The material can then be assigned to a cell using the Cell.fill
attribute.
Parameters
• material_id (int, optional) – Unique identifier for the material. If not specified, an
identifier will automatically be assigned.

• name (str, optional) – Name of the material. If not specified, the name will be the empty
string.
• temperature (float, optional) – Temperature of the material in Kelvin. If not speci-
fied, the material inherits the default temperature applied to the model.
Variables
• id (int) – Unique identifier for the material
• temperature (float) – Temperature of the material in Kelvin.
• density (float) – Density of the material (units defined separately)
• density_units (str) – Units used for density. Can be one of ‘g/cm3’, ‘g/cc’, ‘kg/m3’,
‘atom/b-cm’, ‘atom/cm3’, ‘sum’, or ‘macro’. The ‘macro’ unit only applies in the case of a
multi-group calculation.
• depletable (bool) – Indicate whether the material is depletable.
• nuclides (list of namedtuple) – List in which each item is a namedtuple consisting of
a nuclide string, the percent density, and the percent type (‘ao’ or ‘wo’). The namedtuple has
field names name, percent, and percent_type.
• isotropic (list of str) – Nuclides for which elastic scattering should be treated as
though it were isotropic in the laboratory system.
• average_molar_mass (float) – The average molar mass of nuclides in the material in
units of grams per mol. For example, UO2 with 3 nuclides will have an average molar mass
of 270 / 3 = 90 g / mol.
• volume (float) – Volume of the material in cm^3. This can either be set man-
ually or calculated in a stochastic volume calculation and added via the Material.
add_volume_information() method.
• paths (list of str) – The paths traversed through the CSG tree to reach each material in-
stance. This property is initialized by calling the Geometry.determine_paths() method.
• num_instances (int) – The number of instances of this material throughout the geometry.
This property is initialized by calling the Geometry.determine_paths() method.
• fissionable_mass (float) – Mass of fissionable nuclides in the material in [g]. Requires
that the volume attribute is set.
add_components(components: dict, percent_type: str = 'ao')
Add multiple elements or nuclides to a material
Parameters
• components (dict of str to float or dict) – Dictionary mapping element or nu-
clide names to their atom or weight percent. To specify enrichment of an element, the
entry of components for that element must instead be a dictionary containing the keyword
arguments as well as a value for 'percent'

Examples
>>> mat = openmc.Material()

>>> components = {'Li': {'percent': 1.0,
>>> 'enrichment': 60.0,
>>> 'enrichment_target': 'Li7'},
>>> 'Fl': 1.0,
>>> 'Be6': 0.5}
>>> mat.add_components(components)
add_element(element: str, percent: float, percent_type: str = 'ao', enrichment: Optional[float] = None,
enrichment_target: Optional[str] = None, enrichment_type: Optional[str] = None)
Add a natural element to the material
Parameters
• element (str) – Element to add, e.g., ‘Zr’ or ‘Zirconium’
• percent_type ({'ao', 'wo'}, optional) – ‘ao’ for atom percent and ‘wo’ for weight
percent. Defaults to atom percent.
Notes
General enrichment procedure is allowed only for elements composed of two isotopes. If enrichment_target
is given without enrichment natural composition is added to the material.
add_elements_from_formula(formula: str, percent_type: str = 'ao', enrichment: Optional[float] = None,
enrichment_target: Optional[str] = None, enrichment_type: Optional[str] =
None)
Add a elements from a chemical formula to the material.
Parameters
• formula (str) – Formula to add, e.g., ‘C2O’, ‘C6H12O6’, or (NH4)2SO4. Note this is
case sensitive, elements must start with an uppercase character. Multiplier numbers must
be integers.
• percent_type ({'ao', 'wo'}, optional) – ‘ao’ for atom percent and ‘wo’ for weight
percent. Defaults to atom percent.


Notes
General enrichment procedure is allowed only for elements composed of two isotopes. If enrichment_target
is given without enrichment natural composition is added to the material.
add_macroscopic(macroscopic: str)
Add a macroscopic to the material. This will also set the density of the material to 1.0, unless it has been
otherwise set, as a default for Macroscopic cross sections.
Parameters
macroscopic (str) – Macroscopic to add
add_nuclide(nuclide: str, percent: float, percent_type: str = 'ao')
Add a nuclide to the material
Parameters
• nuclide (str) – Nuclide to add, e.g., ‘Mo95’
add_s_alpha_beta(name: str, fraction: float = 1.0)
Add an 𝑆(𝛼, 𝛽) table to the material
Parameters
• name (str) – Name of the 𝑆(𝛼, 𝛽) table
• fraction (float) – The fraction of relevant nuclei that are affected by the 𝑆(𝛼, 𝛽) table.
For example, if the material is a block of carbon that is 60% graphite and 40% amorphous
then add a graphite 𝑆(𝛼, 𝛽) table with fraction=0.6.
add_volume_information(volume_calc)
Add volume information to a material.
Parameters
volume_calc (openmc.VolumeCalculation) – Results from a stochastic volume calcula-
tion
clone(memo: Optional[dict] = None)
Create a copy of this material with a new unique ID.
Parameters
memo (dict or None) – A nested dictionary of previously cloned objects. This parameter
is used internally and should not be specified by the user.
Returns
clone – The clone of this material

Return type
openmc.Material
classmethod from_hdf5(group: Group)
Create material from HDF5 group
Parameters
group (h5py.Group) – Group in HDF5 file
Returns
Material instance
Return type
openmc.Material
classmethod from_xml_element(elem: Element)
Generate material from an XML element
Parameters
Returns
Material generated from XML element
Return type
openmc.Material
get_activity(units: str = 'Bq/cm3', by_nuclide: bool = False)
Returns the activity of the material or for each nuclide in the material in units of [Bq], [Bq/g] or [Bq/cm3].
Parameters
• units ({'Bq', 'Bq/g', 'Bq/cm3'}) – Specifies the type of activity to return, options in-
clude total activity [Bq], specific [Bq/g] or volumetric activity [Bq/cm3]. Default is volu-
metric activity [Bq/cm3].
• by_nuclide (bool) – Specifies if the activity should be returned for the material as a
whole or per nuclide. Default is False.
Returns
If by_nuclide is True then a dictionary whose keys are nuclide names and values are activity
is returned. Otherwise the activity of the material is returned as a float.
Return type
Union[dict, float]
get_elements()
Returns all elements in the material
Returns
elements – List of element names
Return type
list of str
get_mass(nuclide: Optional[str] = None)
Return mass of one or all nuclides.
Note that this method requires that the Material.volume has already been set.

Parameters
nuclides (str, optional) – Nuclide for which mass is desired. If not specified, the den-
sity for the entire material is given.
Returns
Mass of the nuclide/material in [g]
Return type
float
get_mass_density(nuclide: Optional[str] = None)
Return mass density of one or all nuclides
Parameters
nuclides (str, optional) – Nuclide for which density is desired. If not specified, the
density for the entire material is given.
Returns
Density of the nuclide/material in [g/cm^3]
Return type
float
get_nuclide_atom_densities()
Returns all nuclides in the material and their atomic densities in units of atom/b-cm
Changed in version 0.13.1: The values in the dictionary were changed from a tuple containing the nuclide
name and the density to just the density.
Returns
nuclides – Dictionary whose keys are nuclide names and values are densities in [atom/b-cm]
Return type
dict
get_nuclide_atoms()
Return number of atoms of each nuclide in the material
Returns
Dictionary whose keys are nuclide names and values are number of atoms present in the
material.
Return type
dict
get_nuclide_densities()
Returns all nuclides in the material and their densities
Returns
nuclides – Dictionary whose keys are nuclide names and values are 3-tuples of (nuclide,
density percent, density percent type)
Return type
dict
get_nuclides()
Returns all nuclides in the material
Returns
nuclides – List of nuclide names

Return type
list of str
classmethod mix_materials(materials, fracs: Iterable[float], percent_type: str = 'ao', name:
Optional[str] = None)
Mix materials together based on atom, weight, or volume fractions
Parameters
• materials (Iterable of openmc.Material) – Materials to combine
• fracs (Iterable of float) – Fractions of each material to be combined
• percent_type ({'ao', 'wo', 'vo'}) – Type of percentage, must be one of ‘ao’, ‘wo’, or
‘vo’, to signify atom percent (molar percent), weight percent, or volume percent, optional.
Defaults to ‘ao’
• name (str) – The name for the new material, optional. Defaults to concatenated names of
input materials with percentages indicated inside parentheses.
Returns
Mixture of the materials
Return type
openmc.Material
remove_element(element)
Remove an element from the material
Parameters
element (str) – Element to remove
remove_macroscopic(macroscopic: str)
Remove a macroscopic from the material
Parameters
macroscopic (str) – Macroscopic to remove
remove_nuclide(nuclide: str)
Remove a nuclide from the material
Parameters
nuclide (str) – Nuclide to remove
set_density(units: str, density: Optional[float] = None)
Set the density of the material
Parameters
• units ({'g/cm3', 'g/cc', 'kg/m3', 'atom/b-cm', 'atom/cm3', 'sum', 'macro'}) –
Physical units of density.
• density (float, optional) – Value of the density. Must be specified unless units is
given as ‘sum’.
to_xml_element()
Return XML representation of the material
Returns
element – XML element containing material data

Return type
openmc.Materials
class openmc.Materials(materials=None)
Collection of Materials used for an OpenMC simulation.
This class corresponds directly to the materials.xml input file. It can be thought of as a normal Python list where
each member is a Material. It behaves like a list as the following example demonstrates:
>>> fuel = openmc.Material()

>>> clad = openmc.Material()
>>> water = openmc.Material()
>>> m = openmc.Materials([fuel])
>>> m.append(water)
>>> m += [clad]
Parameters
materials (Iterable of openmc.Material) – Materials to add to the collection
Variables
cross_sections (str or path-like) – Indicates the path to an XML cross section listing file
(usually named cross_sections.xml). If it is not set, the OPENMC_CROSS_SECTIONS environment
variable will be used for continuous-energy calculations and OPENMC_MG_CROSS_SECTIONS will
be used for multi-group calculations to find the path to the HDF5 cross section file.
append(material)
Append material to collection
Parameters
material (openmc.Material) – Material to append
export_to_xml(path: Union[str, PathLike] = 'materials.xml')
Export material collection to an XML file.
Parameters
path (str) – Path to file to write. Defaults to ‘materials.xml’.
classmethod from_xml(path: Union[str, PathLike] = 'materials.xml')
Generate materials collection from XML file
Parameters
path (str) – Path to materials XML file
Returns
Materials collection
Return type
openmc.Materials
insert(index: int, material)
Insert material before index
Parameters
• index (int) – Index in list

• material (openmc.Material) – Material to insert

Cross sections for nuclides, elements, and materials can be plotted using the following function:
openmc.plot_xs Creates a figure of continuous-energy cross sections for

this item.
openmc.plot_xs
openmc.plot_xs(this, types, divisor_types=None, temperature=294.0, data_type=None, axis=None,

sab_name=None, ce_cross_sections=None, mg_cross_sections=None, enrichment=None,
plot_CE=True, orders=None, divisor_orders=None, **kwargs)
Creates a figure of continuous-energy cross sections for this item.
Parameters
• this (str or openmc.Material) – Object to source data from
• types (Iterable of values of PLOT_TYPES) – The type of cross sections to include
in the plot.
• divisor_types (Iterable of values of PLOT_TYPES, optional) – Cross section
types which will divide those produced by types before plotting. A type of ‘unity’ can be
used to effectively not divide some types.
• temperature (float, optional) – Temperature in Kelvin to plot. If not specified, a
default temperature of 294K will be plotted. Note that the nearest temperature in the library
for each nuclide will be used as opposed to using any interpolation.
• data_type ({'nuclide', 'element', 'material', 'macroscopic'}, optional) –
Type of object to plot. If not specified, a guess is made based on the this argument.
• axis (matplotlib.axes, optional) – A previously generated axis to use for plotting.
If not specified, a new axis and figure will be generated.
• sab_name (str, optional) – Name of S(a,b) library to apply to MT=2 data when appli-
cable; only used for items which are instances of openmc.Element or openmc.Nuclide
• ce_cross_sections (str, optional) – Location of cross_sections.xml file. Default is
None.
• mg_cross_sections (str, optional) – Location of MGXS HDF5 Library file. Default
is None.
• enrichment (float, optional) – Enrichment for U235 in weight percent. For example,
input 4.95 for 4.95 weight percent enriched U. Default is None. This is only used for items
which are instances of openmc.Element
• plot_CE (bool, optional) – Denotes whether or not continuous-energy will be plotted.
Defaults to plotting the continuous-energy data.
• orders (Iterable of Integral, optional) – The scattering order or delayed group
index to use for the corresponding entry in types. Defaults to the 0th order for scattering and
the total delayed neutron data. This only applies to plots of multi-group data.
• divisor_orders (Iterable of Integral, optional) – Same as orders, but for divi-
sor_types
• **kwargs – All keyword arguments are passed to matplotlib.pyplot.figure().

Returns
fig – If axis is None, then a Matplotlib Figure of the generated cross section will be returned.
Otherwise, a value of None will be returned as the figure and axes have already been generated.
Return type
matplotlib.figure.Figure
6.1.4 Building geometry
openmc.Plane An arbitrary plane of the form 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷.

openmc.XPlane A plane perpendicular to the x axis of the form 𝑥 − 𝑥0 =
0
openmc.YPlane A plane perpendicular to the y axis of the form 𝑦 − 𝑦0 =
0
openmc.ZPlane A plane perpendicular to the z axis of the form 𝑧−𝑧0 = 0
openmc.XCylinder An infinite cylinder whose length is parallel to the x-axis
of the form (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 .
openmc.YCylinder An infinite cylinder whose length is parallel to the y-axis
of the form (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 .
openmc.ZCylinder An infinite cylinder whose length is parallel to the z-axis
of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑟2 .
openmc.Sphere A sphere of the form (𝑥−𝑥0 )2 +(𝑦 −𝑦0 )2 +(𝑧 −𝑧0 )2 =
𝑟2 .
openmc.Cone A conical surface parallel to the x-, y-, or z-axis.
openmc.XCone A cone parallel to the x-axis of the form (𝑦 −𝑦0 )2 +(𝑧 −
𝑧0 )2 = 𝑟2 (𝑥 − 𝑥0 )2 .
openmc.YCone A cone parallel to the y-axis of the form (𝑥−𝑥0 )2 +(𝑧 −
𝑧0 )2 = 𝑟2 (𝑦 − 𝑦0 )2 .
openmc.ZCone A cone parallel to the z-axis of the form (𝑥−𝑥0 )2 +(𝑦 −
𝑦0 )2 = 𝑟2 (𝑧 − 𝑧0 )2 .
openmc.Quadric A surface of the form 𝐴𝑥2 +𝐵𝑦 2 +𝐶𝑧 2 +𝐷𝑥𝑦 +𝐸𝑦𝑧 +
𝐹 𝑥𝑧 + 𝐺𝑥 + 𝐻𝑦 + 𝐽𝑧 + 𝐾 = 0.
openmc.XTorus A√︀ torus of the form (𝑥 − 𝑥0 )2 /𝐵 2 +
( (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
openmc.YTorus A√︀ torus of the form (𝑦 − 𝑦0 )2 /𝐵 2 +
( (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
openmc.ZTorus A√︀ torus of the form (𝑧 − 𝑧0 )2 /𝐵 2 +
( (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
openmc.Halfspace A positive or negative half-space region.
openmc.Intersection Intersection of two or more regions.
openmc.Union Union of two or more regions.
openmc.Complement Complement of a region.
openmc.Cell A region of space defined as the intersection of half-
space created by quadric surfaces.
openmc.Universe A collection of cells that can be repeated.
openmc.DAGMCUniverse A reference to a DAGMC file to be used in the model.
openmc.RectLattice A lattice consisting of rectangular prisms.
openmc.HexLattice A lattice consisting of hexagonal prisms.
openmc.Geometry Geometry representing a collection of surfaces, cells,
and universes.

openmc.Plane
class openmc.Plane(a=1.0, b=0.0, c=0.0, d=0.0, *args, **kwargs)

An arbitrary plane of the form 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷.
Parameters
• a (float, optional) – The ‘A’ parameter for the plane. Defaults to 1.
• b (float, optional) – The ‘B’ parameter for the plane. Defaults to 0.
• c (float, optional) – The ‘C’ parameter for the plane. Defaults to 0.
• d (float, optional) – The ‘D’ parameter for the plane. Defaults to 0.
• boundary_type ({'transmission, 'vacuum', 'reflective', 'periodic',
'white'}, optional) – Boundary condition that defines the behavior for particles
hitting the surface. Defaults to transmissive boundary condition where particles freely pass
through the surface.
• name (str, optional) – Name of the plane. If not specified, the name will be the empty
string.
• surface_id (int, optional) – Unique identifier for the surface. If not specified, an iden-
tifier will automatically be assigned.
Variables
• a (float) – The ‘A’ parameter for the plane
• b (float) – The ‘B’ parameter for the plane
• c (float) – The ‘C’ parameter for the plane
• d (float) – The ‘D’ parameter for the plane
• boundary_type ({'transmission, 'vacuum', 'reflective', 'periodic', 'white'})
– Boundary condition that defines the behavior for particles hitting the surface.
• periodic_surface (openmc.Surface) – If a periodic boundary condition is used, the
surface with which this one is periodic with
• coefficients (dict) – Dictionary of surface coefficients
• id (int) – Unique identifier for the surface
• name (str) – Name of the surface
• type (str) – Type of the surface
classmethod from_points(p1, p2, p3, **kwargs)
Return a plane given three points that pass through it.
Parameters
• p1 (3-tuples) – Points that pass through the plane
• kwargs (dict) – Keyword arguments passed to the Plane constructor
Returns
Plane that passes through the three points

Return type
Plane
openmc.XPlane
class openmc.XPlane(x0=0.0, *args, **kwargs)

A plane perpendicular to the x axis of the form 𝑥 − 𝑥0 = 0
Parameters
• x0 (float, optional) – Location of the plane in [cm]. Defaults to 0.
through the surface. Only axis-aligned periodicity is supported, i.e., x-planes can only be
paired with x-planes.
string.
Variables
• x0 (float) – Location of the plane in [cm]
evaluate(point)
Evaluate the surface equation at a given point.
Parameters
point (3-tuple of float) – The Cartesian coordinates, (𝑥′ , 𝑦 ′ , 𝑧 ′ ), at which the surface
equation should be evaluated.
Returns
𝐴𝑥′ + 𝐵𝑦 ′ + 𝐶𝑧 ′ − 𝐷
Return type
float

openmc.YPlane
class openmc.YPlane(y0=0.0, *args, **kwargs)

A plane perpendicular to the y axis of the form 𝑦 − 𝑦0 = 0
Parameters
• y0 (float, optional) – Location of the plane in [cm]
string.
Variables
• y0 (float) – Location of the plane in [cm]
evaluate(point)
Parameters
Returns
𝐴𝑥′ + 𝐵𝑦 ′ + 𝐶𝑧 ′ − 𝐷
Return type
float

openmc.ZPlane
class openmc.ZPlane(z0=0.0, *args, **kwargs)

A plane perpendicular to the z axis of the form 𝑧 − 𝑧0 = 0
Parameters
• z0 (float, optional) – Location of the plane in [cm]. Defaults to 0.
string.
Variables
• z0 (float) – Location of the plane in [cm]
evaluate(point)
Parameters
Returns
𝐴𝑥′ + 𝐵𝑦 ′ + 𝐶𝑧 ′ − 𝐷
Return type
float

openmc.XCylinder
class openmc.XCylinder(y0=0.0, z0=0.0, r=1.0, *args, **kwargs)

An infinite cylinder whose length is parallel to the x-axis of the form (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 .
Parameters
• y0 (float, optional) – y-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
• z0 (float, optional) – z-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
• r (float, optional) – Radius of the cylinder in [cm]. Defaults to 1.
• boundary_type ({'transmission, 'vacuum', 'reflective', 'white'}, optional)
– Boundary condition that defines the behavior for particles hitting the surface. Defaults
to transmissive boundary condition where particles freely pass through the surface.
• name (str, optional) – Name of the cylinder. If not specified, the name will be the empty
string.
Variables
• y0 (float) – y-coordinate for the origin of the Cylinder in [cm]
• z0 (float) – z-coordinate for the origin of the Cylinder in [cm]
• r (float) – Radius of the cylinder in [cm]
• boundary_type ({'transmission, 'vacuum', 'reflective', 'white'}) – Boundary
condition that defines the behavior for particles hitting the surface.
bounding_box(side)
Determine an axis-aligned bounding box.
An axis-aligned bounding box for surface half-spaces is represented by its lower-left and upper-right coor-
dinates. If the half-space is unbounded in a particular direction, numpy.inf is used to represent infinity.
Parameters
side ({'+', '-'}) – Indicates the negative or positive half-space
Returns
• numpy.ndarray – Lower-left coordinates of the axis-aligned bounding box for the desired
half-space
• numpy.ndarray – Upper-right coordinates of the axis-aligned bounding box for the desired
half-space
evaluate(point)
Parameters
point (3-tuple of float) – The Cartesian coordinates, (𝑥′ , 𝑦 ′ , 𝑧 ′ ), in [cm] at which the
surface equation should be evaluated.

Returns
𝐴𝑥′2 + 𝐵𝑦 ′2 + 𝐶𝑧 ′2 + 𝐷𝑥′ 𝑦 ′ + 𝐸𝑦 ′ 𝑧 ′ + 𝐹 𝑥′ 𝑧 ′ + 𝐺𝑥′ + 𝐻𝑦 ′ + 𝐽𝑧 ′ + 𝐾 = 0
Return type
float
openmc.YCylinder
class openmc.YCylinder(x0=0.0, z0=0.0, r=1.0, *args, **kwargs)

An infinite cylinder whose length is parallel to the y-axis of the form (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 .
Parameters
• x0 (float, optional) – x-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
• z0 (float, optional) – z-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
string.
Variables
• x0 (float) – x-coordinate for the origin of the Cylinder in [cm]
• z0 (float) – z-coordinate for the origin of the Cylinder in [cm]
bounding_box(side)
Parameters
Returns
half-space
half-space

evaluate(point)
Parameters
Returns
Return type
float
openmc.ZCylinder
class openmc.ZCylinder(x0=0.0, y0=0.0, r=1.0, *args, **kwargs)

An infinite cylinder whose length is parallel to the z-axis of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑟2 .
Parameters
• x0 (float, optional) – x-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
• y0 (float, optional) – y-coordinate for the origin of the Cylinder in [cm]. Defaults to 0
string.
Variables
• x0 (float) – x-coordinate for the origin of the Cylinder in [cm]
• y0 (float) – y-coordinate for the origin of the Cylinder in [cm]
bounding_box(side)
Parameters

Returns
half-space
half-space
evaluate(point)
Parameters
Returns
Return type
float
openmc.Sphere
class openmc.Sphere(x0=0.0, y0=0.0, z0=0.0, r=1.0, *args, **kwargs)

A sphere of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 .
Parameters
• x0 (float, optional) – x-coordinate of the center of the sphere in [cm]. Defaults to 0.
• y0 (float, optional) – y-coordinate of the center of the sphere in [cm]. Defaults to 0.
• z0 (float, optional) – z-coordinate of the center of the sphere in [cm]. Defaults to 0.
• r (float, optional) – Radius of the sphere in [cm]. Defaults to 1.
• name (str, optional) – Name of the sphere. If not specified, the name will be the empty
string.
Variables
• x0 (float) – x-coordinate of the center of the sphere in [cm]
• y0 (float) – y-coordinate of the center of the sphere in [cm]
• z0 (float) – z-coordinate of the center of the sphere in [cm]
• r (float) – Radius of the sphere in [cm]


bounding_box(side)
Parameters
Returns
half-space
half-space
evaluate(point)
Parameters
Returns
Return type
float
openmc.Cone
class openmc.Cone(x0=0.0, y0=0.0, z0=0.0, r2=1.0, dx=0.0, dy=0.0, dz=1.0, *args, **kwargs)
A conical surface parallel to the x-, y-, or z-axis.
Parameters
• x0 (float, optional) – x-coordinate of the apex in [cm]. Defaults to 0.
• y0 (float, optional) – y-coordinate of the apex in [cm]. Defaults to 0.
• z0 (float, optional) – z-coordinate of the apex in [cm]. Defaults to 0.
• r2 (float, optional) – Parameter related to the aperature. Defaults to 1.
• dx (float, optional) – x-component of the vector representing the axis of the cone. De-
faults to 0.
• dy (float, optional) – y-component of the vector representing the axis of the cone. De-
faults to 0.
• dz (float, optional) – z-component of the vector representing the axis of the cone. De-
faults to 1.

• name (str) – Name of the cone. If not specified, the name will be the empty string.
Variables
• x0 (float) – x-coordinate of the apex in [cm]
• y0 (float) – y-coordinate of the apex in [cm]
• z0 (float) – z-coordinate of the apex in [cm]
• r2 (float) – Parameter related to the aperature
• dx (float) – x-component of the vector representing the axis of the cone.
• dy (float) – y-component of the vector representing the axis of the cone.
• dz (float) – z-component of the vector representing the axis of the cone.
to_xml_element()
Return XML representation of the surface
Returns
Return type
openmc.XCone
class openmc.XCone(x0=0.0, y0=0.0, z0=0.0, r2=1.0, *args, **kwargs)

A cone parallel to the x-axis of the form (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 (𝑥 − 𝑥0 )2 .
Parameters
• name (str, optional) – Name of the cone. If not specified, the name will be the empty
string.
Variables


evaluate(point)
Parameters
Returns
Return type
float
openmc.YCone
class openmc.YCone(x0=0.0, y0=0.0, z0=0.0, r2=1.0, *args, **kwargs)

A cone parallel to the y-axis of the form (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑟2 (𝑦 − 𝑦0 )2 .
Parameters
string.
Variables


evaluate(point)
Parameters
Returns
Return type
float
openmc.ZCone
class openmc.ZCone(x0=0.0, y0=0.0, z0=0.0, r2=1.0, *args, **kwargs)

A cone parallel to the z-axis of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑟2 (𝑧 − 𝑧0 )2 .
Parameters
string.
Variables


evaluate(point)
Parameters
Returns
Return type
float
openmc.Quadric
class openmc.Quadric(a=0.0, b=0.0, c=0.0, d=0.0, e=0.0, f=0.0, g=0.0, h=0.0, j=0.0, k=0.0, *args, **kwargs)
A surface of the form 𝐴𝑥2 + 𝐵𝑦 2 + 𝐶𝑧 2 + 𝐷𝑥𝑦 + 𝐸𝑦𝑧 + 𝐹 𝑥𝑧 + 𝐺𝑥 + 𝐻𝑦 + 𝐽𝑧 + 𝐾 = 0.
Parameters
• a (float, optional) – coefficients for the surface. All default to 0.
• b (float, optional) – coefficients for the surface. All default to 0.
• c (float, optional) – coefficients for the surface. All default to 0.
• d (float, optional) – coefficients for the surface. All default to 0.
• e (float, optional) – coefficients for the surface. All default to 0.
• f (float, optional) – coefficients for the surface. All default to 0.
• g (float, optional) – coefficients for the surface. All default to 0.
• h (float, optional) – coefficients for the surface. All default to 0.
• j (float, optional) – coefficients for the surface. All default to 0.
• k (float, optional) – coefficients for the surface. All default to 0.
• name (str, optional) – Name of the surface. If not specified, the name will be the empty
string.
Variables
• k (a, b, c, d, e, f , g, h , j,) – coefficients for the surface


openmc.XTorus
class openmc.XTorus(x0=0.0, y0=0.0, z0=0.0, a=0.0, b=0.0, c=0.0, **kwargs)

A torus of the form (𝑥 − 𝑥0 )2 /𝐵 2 + ( (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
√︀

Parameters
• x0 (float) – x-coordinate of the center of the axis of revolution in [cm]
• y0 (float) – y-coordinate of the center of the axis of revolution in [cm]
• z0 (float) – z-coordinate of the center of the axis of revolution in [cm]
• a (float) – Major radius of the torus in [cm]
• b (float) – Minor radius of the torus in [cm] (parallel to axis of revolution)
• c (float) – Minor radius of the torus in [cm] (perpendicular to axis of revolution)
• kwargs (dict) – Keyword arguments passed to the Surface constructor
Variables
bounding_box(side)
Parameters
Returns
half-space

half-space
evaluate(point)
Parameters
Returns
Evaluation of the surface polynomial at point (𝑥′ , 𝑦 ′ , 𝑧 ′ )
Return type
float
openmc.YTorus
class openmc.YTorus(x0=0.0, y0=0.0, z0=0.0, a=0.0, b=0.0, c=0.0, **kwargs)

A torus of the form (𝑦 − 𝑦0 )2 /𝐵 2 + ( (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
√︀

Parameters
Variables
• c (float) – Minor radius of the torus (perpendicular to axis of revolution)

bounding_box(side)
Parameters
Returns
half-space
half-space
evaluate(point)
Parameters
Returns
Return type
float
openmc.ZTorus
class openmc.ZTorus(x0=0.0, y0=0.0, z0=0.0, a=0.0, b=0.0, c=0.0, **kwargs)

A torus of the form (𝑧 − 𝑧0 )2 /𝐵 2 + ( (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 − 𝐴)2 /𝐶 2 − 1 = 0.
√︀

Parameters
Variables


bounding_box(side)
Parameters
Returns
half-space
half-space
evaluate(point)
Parameters
Returns
Return type
float
openmc.Halfspace
class openmc.Halfspace(surface, side)

A positive or negative half-space region.
A half-space is either of the two parts into which a two-dimension surface divides the three-dimensional Eu-
clidean space. If the equation of the surface is 𝑓 (𝑥, 𝑦, 𝑧) = 0, the region for which 𝑓 (𝑥, 𝑦, 𝑧) < 0 is referred to
as the negative half-space and the region for which 𝑓 (𝑥, 𝑦, 𝑧) > 0 is referred to as the positive half-space.
Instances of Halfspace are generally not instantiated directly. Rather, they can be created from an existing Surface
through the __neg__ and __pos__ operators, as the following example demonstrates:
>>> sphere = openmc.Sphere(surface_id=1, r=10.0)

>>> inside_sphere = -sphere
>>> outside_sphere = +sphere
>>> type(inside_sphere)
<class 'openmc.surface.Halfspace'>

Parameters
• surface (openmc.Surface) – Surface which divides Euclidean space.
• side ({'+', '-'}) – Indicates whether the positive or negative half-space is used.
Variables
• surface (openmc.Surface) – Surface which divides Euclidean space.
• side ({'+', '-'}) – Indicates whether the positive or negative half-space is used.
• bounding_box (tuple of numpy.ndarray) – Lower-left and upper-right coordinates of
an axis-aligned bounding box
clone(memo=None)
Create a copy of this halfspace, with a cloned surface with a unique ID.
Parameters
Returns
clone – The clone of this halfspace
Return type
openmc.Halfspace
get_surfaces(surfaces=None)
Returns the surface that this is a halfspace of.
Parameters
surfaces (collections.OrderedDict, optional) – Dictionary mapping surface IDs
to openmc.Surface instances
Returns
surfaces – Dictionary mapping surface IDs to openmc.Surface instances
Return type
collections.OrderedDict
remove_redundant_surfaces(redundant_surfaces)
Recursively remove all redundant surfaces referenced by this region
Parameters
redundant_surfaces (dict) – Dictionary mapping redundant surface IDs to surface IDs
for the openmc.Surface instances that should replace them.
rotate(rotation, pivot=(0.0, 0.0, 0.0), order='xyz', inplace=False, memo=None)
Rotate surface by angles provided or by applying matrix directly.
Parameters
• rotation (3-tuple of float, or 3x3 iterable) – A 3-tuple of angles (𝜑, 𝜃, 𝜓) in
degrees where the first element is the rotation about the x-axis in the fixed laboratory frame,
the second element is the rotation about the y-axis in the fixed laboratory frame, and the
third element is the rotation about the z-axis in the fixed laboratory frame. The rotations
are active rotations. Additionally a 3x3 rotation matrix can be specified directly either as a
nested iterable or array.

• pivot (iterable of float, optional) – (x, y, z) coordinates for the point to rotate
about. Defaults to (0., 0., 0.)
• order (str, optional) – A string of ‘x’, ‘y’, and ‘z’ in some order specifying which
rotation to perform first, second, and third. Defaults to ‘xyz’ which means, the rotation
by angle 𝜑 about x will be applied first, followed by 𝜃 about y and then 𝜓 about z. This
corresponds to an x-y-z extrinsic rotation as well as a z-y’-x” intrinsic rotation using Tait-
Bryan angles (𝜑, 𝜃, 𝜓).
• inplace (bool) – Whether or not to return a new instance of Surface or to modify the
coefficients of this Surface in place. Defaults to False.
• memo (dict or None) – Dictionary used for memoization
Returns
Translated half-space
Return type
openmc.Halfspace
translate(vector, inplace=False, memo=None)
Translate half-space in given direction
Parameters
• vector (iterable of float) – Direction in which region should be translated
Returns
Translated half-space
Return type
openmc.Halfspace
openmc.Intersection
class openmc.Intersection(nodes)
Intersection of two or more regions.
Instances of Intersection are generally created via the & operator applied to two instances of openmc.Region.
This is illustrated in the following example:
>>> equator = openmc.ZPlane(z0=0.0)

>>> earth = openmc.Sphere(r=637.1e6)
>>> northern_hemisphere = -earth & +equator
>>> southern_hemisphere = -earth & -equator
>>> type(northern_hemisphere)
<class 'openmc.region.Intersection'>
Instances of this class behave like a mutable sequence, e.g., they can be indexed and have an append() method.
Parameters
nodes (iterable of openmc.Region) – Regions to take the intersection of
Variables
bounding_box (tuple of numpy.array) – Lower-left and upper-right coordinates of an axis-
aligned bounding box

insert(index, value)
S.insert(index, value) – insert value before index
openmc.Union
class openmc.Union(nodes)
Union of two or more regions.
Instances of Union are generally created via the | operator applied to two instances of openmc.Region. This is
illustrated in the following example:
>>> s1 = openmc.ZPlane(z0=0.0)
>>> s2 = openmc.Sphere(r=637.1e6)
>>> type(-s2 | +s1)
<class 'openmc.region.Union'>
Instances of this class behave like a mutable sequence, e.g., they can be indexed and have an append() method.
Parameters
nodes (iterable of openmc.Region) – Regions to take the union of
Variables
bounding_box (2-tuple of numpy.array) – Lower-left and upper-right coordinates of an
axis-aligned bounding box
insert(index, value)
S.insert(index, value) – insert value before index
openmc.Complement
class openmc.Complement(node)
Complement of a region.
The Complement of an existing openmc.Region can be created by using the ~ operator as the following example
demonstrates:
>>> xl = openmc.XPlane(-10.0)
>>> xr = openmc.XPlane(10.0)
>>> yl = openmc.YPlane(-10.0)
>>> yr = openmc.YPlane(10.0)
>>> inside_box = +xl & -xr & +yl & -yr
>>> outside_box = ~inside_box
>>> type(outside_box)
<class 'openmc.region.Complement'>
Parameters
node (openmc.Region) – Region to take the complement of
Variables
• node (openmc.Region) – Regions to take the complement of
• bounding_box (tuple of numpy.array) – Lower-left and upper-right coordinates of an
axis-aligned bounding box

clone(memo=None)
Create a copy of this region - each of the surfaces in the region’s nodes will be cloned and will have new
unique IDs.
Parameters
Returns
clone – The clone of this region
Return type
openmc.Region
Recursively find and return all the surfaces referenced by the node
Parameters
Returns
Return type
Parameters
redundant_surfaces (dict) – Dictionary mapping redundant surface IDs to
class:openmc.Surface instances that should replace them.
Parameters


Returns
Translated region
Return type
openmc.Region
Translate region in given direction
Parameters
• inplace (bool) – Whether or not to return a region based on new surfaces or one based
on the original surfaces that have been modified.
• memo (dict or None) – Dictionary used for memoization. This parameter is used inter-
nally and should not be specified by the user.
Returns
Translated region
Return type
openmc.Region
openmc.Cell
class openmc.Cell(cell_id=None, name='', fill=None, region=None)

A region of space defined as the intersection of half-space created by quadric surfaces.
Parameters
• cell_id (int, optional) – Unique identifier for the cell. If not specified, an identifier
will automatically be assigned.
• name (str, optional) – Name of the cell. If not specified, the name is the empty string.
• fill (openmc.Material or openmc.UniverseBase or openmc.Lattice or None
or iterable of openmc.Material, optional) – Indicates what the region of space
is filled with
• region (openmc.Region, optional) – Region of space that is assigned to the cell.
Variables
• id (int) – Unique identifier for the cell
• name (str) – Name of the cell
• fill (openmc.Material or openmc.UniverseBase or openmc.Lattice or None
or iterable of openmc.Material) – Indicates what the region of space is filled with.
If None, the cell is treated as a void. An iterable of materials is used to fill repeated instances
of a cell with different materials.
• fill_type ({'material', 'universe', 'lattice', 'distribmat', 'void'}) – Indi-
cates what the cell is filled with.
• region (openmc.Region or None) – Region of space that is assigned to the cell.

• rotation (Iterable of float) – If the cell is filled with a universe, this array specifies
the angles in degrees about the x, y, and z axes that the filled universe should be rotated. The
rotation applied is an intrinsic rotation with specified Tait-Bryan angles. That is to say, if the
angles are (𝜑, 𝜃, 𝜓), then the rotation matrix applied is 𝑅𝑧 (𝜓)𝑅𝑦 (𝜃)𝑅𝑥 (𝜑) or
⎡ ⎤
cos 𝜃 cos 𝜓 − cos 𝜑 sin 𝜓 + sin 𝜑 sin 𝜃 cos 𝜓 sin 𝜑 sin 𝜓 + cos 𝜑 sin 𝜃 cos 𝜓
⎣ cos 𝜃 sin 𝜓 cos 𝜑 cos 𝜓 + sin 𝜑 sin 𝜃 sin 𝜓 − sin 𝜑 cos 𝜓 + cos 𝜑 sin 𝜃 sin 𝜓 ⎦
− sin 𝜃 sin 𝜑 cos 𝜃 cos 𝜑 cos 𝜃
A rotation matrix can also be specified directly by setting this attribute to a nested list (or 2D
numpy array) that specifies each element of the matrix.
• rotation_matrix (numpy.ndarray) – The rotation matrix defined by the angles specified
in the Cell.rotation property.
• temperature (float or iterable of float) – Temperature of the cell in Kelvin.
Multiple temperatures can be given to give each distributed cell instance a unique tempera-
ture.
• translation (Iterable of float) – If the cell is filled with a universe, this array spec-
ifies a vector that is used to translate (shift) the universe.
• paths (list of str) – The paths traversed through the CSG tree to reach each cell in-
stance. This property is initialized by calling the Geometry.determine_paths() method.
• num_instances (int) – The number of instances of this cell throughout the geometry.
• volume (float) – Volume of the cell in cm^3. This can either be set manually or calculated
in a stochastic volume calculation and added via the Cell.add_volume_information()
method. For ‘distribmat’ cells it is the total volume of all instances.
• atoms (collections.OrderedDict) – Mapping of nuclides to the total number of atoms
for each nuclide present in the cell, or in all of its instances for a ‘distribmat’ fill. For example,
{‘U235’: 1.0e22, ‘U238’: 5.0e22, . . . }.
Add volume information to a cell.
Parameters
tion
clone(clone_materials=True, clone_regions=True, memo=None)
Create a copy of this cell with a new unique ID, and clones the cell’s region and fill.
Parameters
• clone_materials (bool) – Whether to create separate copies of the materials filling cells
contained in this cell, or the material filling this cell.
• clone_regions (bool) – Whether to create separate copies of the regions bounding cells
contained in this cell, and the region bounding this cell.
• memo (dict or None) – A nested dictionary of previously cloned objects. This parameter
Returns
clone – The clone of this cell
Return type
openmc.Cell

create_xml_subelement(xml_element, memo=None)
Add the cell’s xml representation to an incoming xml element
Parameters
• xml_element (xml.etree.ElementTree.Element) – XML element to be added to
• memo (set or None) – A set of object IDs representing geometry entities already written
to xml_element. This parameter is used internally and should not be specified by users.
Return type
None
classmethod from_xml_element(elem, surfaces, materials, get_universe)
Generate cell from XML element
Parameters
• elem (xml.etree.ElementTree.Element) – <cell> element
• surfaces (dict) – Dictionary mapping surface IDs to openmc.Surface instances
• materials (dict) – Dictionary mapping material IDs to openmc.Material instances
(defined in 𝑜𝑝𝑒𝑛𝑚𝑐.𝐺𝑒𝑜𝑚𝑒𝑡𝑟𝑦.𝑓 𝑟𝑜𝑚𝑥 𝑚𝑙)
• get_universe (function) – Function returning universe (defined in openmc.
Geometry.from_xml())
Returns
Cell instance
Return type
openmc.Cell
get_all_cells(memo=None)
Return all cells that are contained within this one if it is filled with a universe or lattice
Returns
cells – Dictionary whose keys are cell IDs and values are Cell instances
Return type
collections.orderedDict
get_all_materials(memo=None)
Return all materials that are contained within the cell
Returns
materials – Dictionary whose keys are material IDs and values are Material instances
Return type
get_all_universes()
Return all universes that are contained within this one if any of its cells are filled with a universe or lattice.
Returns
universes – Dictionary whose keys are universe IDs and values are Universe instances
Return type

Return all nuclides contained in the cell and their densities
Returns
density)
Return type
get_nuclides()
Returns all nuclides in the cell
Returns
Return type
list of str
openmc.Universe
class openmc.Universe(universe_id=None, name='', cells=None)

A collection of cells that can be repeated.
Parameters
• universe_id (int, optional) – Unique identifier of the universe. If not specified, an
identifier will automatically be assigned
• name (str, optional) – Name of the universe. If not specified, the name is the empty
string.
• cells (Iterable of openmc.Cell, optional) – Cells to add to the universe. By de-
fault no cells are added.
Variables
• id (int) – Unique identifier of the universe
• name (str) – Name of the universe
• cells (collections.OrderedDict) – Dictionary whose keys are cell IDs and values are
Cell instances
• volume (float) – Volume of the universe in cm^3. This can either be set man-
ually or calculated in a stochastic volume calculation and added via the Universe.
add_volume_information() method.
• bounding_box (2-tuple of numpy.array) – Lower-left and upper-right coordinates of
an axis-aligned bounding box of the universe.
add_cell(cell)
Add a cell to the universe.
Parameters
cell (openmc.Cell) – Cell to add
add_cells(cells)
Add multiple cells to the universe.
Parameters
cells (Iterable of openmc.Cell) – Cells to add

clear_cells()
Remove all cells from the universe.
Add the universe xml representation to an incoming xml element
Parameters
• memo (set or None) – A set of object id’s representing geometry entities already written
to the xml_element. This parameter is used internally and should not be specified by users.
Return type
None
find(point)
Find cells/universes/lattices which contain a given point
Parameters
point (3-tuple of float) – Cartesian coordinates of the point
Returns
Sequence of universes, cells, and lattices which are traversed to find the given point
Return type
list
classmethod from_hdf5(group, cells)
Create universe from HDF5 group
Parameters
• cells (dict) – Dictionary mapping cell IDs to instances of openmc.Cell.
Returns
Universe instance
Return type
openmc.Universe
Return all cells that are contained within the universe
Returns
Return type
Return all materials that are contained within the universe
Returns
Return type

get_all_universes()
Return all universes that are contained within this one.
Returns
Return type
Return all nuclides contained in the universe
Returns
density)
Return type
get_nuclides()
Returns all nuclides in the universe
Returns
Return type
list of str
plot(origin=(0.0, 0.0, 0.0), width=(1.0, 1.0), pixels=(200, 200), basis='xy', color_by='cell', colors=None,
seed=None, openmc_exec='openmc', **kwargs)
Display a slice plot of the universe.
Parameters
• origin (Iterable of float) – Coordinates at the origin of the plot
• width (Iterable of float) – Width of the plot in each basis direction
• pixels (Iterable of int) – Number of pixels to use in each basis direction
• basis ({'xy', 'xz', 'yz'}) – The basis directions for the plot
• color_by ({'cell', 'material'}) – Indicate whether the plot should be colored by cell
or by material
• colors (dict) – Assigns colors to specific materials or cells. Keys are instances of Cell
or Material and values are RGB 3-tuples, RGBA 4-tuples, or strings indicating SVG color
names. Red, green, blue, and alpha should all be floats in the range [0.0, 1.0], for example:
# Make water blue

water = openmc.Cell(fill=h2o)
universe.plot(..., colors={water: (0., 0., 1.))
• seed (int) – Seed for the random number generator

• openmc_exec (str) – Path to OpenMC executable.
• **kwargs – Keyword arguments passed to matplotlib.pyplot.imshow()
Returns
Resulting image

Return type
matplotlib.image.AxesImage
remove_cell(cell)
Remove a cell from the universe.
Parameters
cell (openmc.Cell) – Cell to remove
openmc.DAGMCUniverse
class openmc.DAGMCUniverse(filename, universe_id=None, name='', auto_geom_ids=False,

auto_mat_ids=False)
A reference to a DAGMC file to be used in the model.
Parameters
• filename (str) – Path to the DAGMC file used to represent this universe.
• universe_id (int, optional) – Unique identifier of the universe. If not specified, an
identifier will automatically be assigned.
• name (str, optional) – Name of the universe. If not specified, the name is the empty
string.
• auto_geom_ids (bool) – Set IDs automatically on initialization (True) or report overlaps
in ID space between CSG and DAGMC (False)
• auto_mat_ids (bool) – Set IDs automatically on initialization (True) or report overlaps in
ID space between OpenMC and UWUW materials (False)
Variables
• id (int) – Unique identifier of the universe
• name (str) – Name of the universe
• filename (str) – Path to the DAGMC file used to represent this universe.
• auto_geom_ids (bool) – Set IDs automatically on initialization (True) or report overlaps
in ID space between CSG and DAGMC (False)
• auto_mat_ids (bool) – Set IDs automatically on initialization (True) or report overlaps in
ID space between OpenMC and UWUW materials (False)
bounded_universe(bounding_cell_id=10000, **kwargs)
Returns an openmc.Universe filled with this DAGMCUniverse and bounded with a cell. Defaults to a box
cell with a vacuum surface however this can be changed using the kwargs which are passed directly to
DAGMCUniverse.bounding_region().
Parameters
bounding_cell_id (int) – The cell ID number to use for the bounding cell, defaults to
10000 to reduce the chance of overlapping ID numbers with the DAGMC geometry.
Returns
Universe instance

Return type
openmc.Universe
bounding_region(bounded_type='box', boundary_type='vacuum', starting_id=10000)
Creates a either a spherical or box shaped bounding region around the DAGMC geometry.
Parameters
• bounded_type (str) – The type of bounding surface(s) to use when constructing the
region. Options include a single spherical surface (sphere) or a rectangle made from six
planes (box).
• boundary_type (str) – Boundary condition that defines the behavior for particles hitting
the surface. Defaults to vacuum boundary condition. Passed into the surface construction.
• starting_id (int) – Starting ID of the surface(s) used in the region. For bounded_type
‘box’, the next 5 IDs will also be used. Defaults to 10000 to reduce the chance of an overlap
of surface IDs with the DAGMC geometry.
Returns
Region instance
Return type
openmc.Region
Add the universe xml representation to an incoming xml element
Parameters
Return type
None
classmethod from_hdf5(group)
Create DAGMC universe from HDF5 group
Parameters
Returns
DAGMCUniverse instance
Return type
Generate DAGMC universe from XML element
Parameters
elem (xml.etree.ElementTree.Element) – <dagmc_universe> element
Returns
DAGMCUniverse instance
Return type

openmc.RectLattice
class openmc.RectLattice(lattice_id=None, name='')

A lattice consisting of rectangular prisms.
To completely define a rectangular lattice, the RectLattice.lower_left RectLattice.pitch,
RectLattice.outer, and RectLattice.universes properties need to be set.
Most methods for this class use a natural indexing scheme wherein elements are assigned an index corresponding
to their position relative to the (x,y,z) axes in a Cartesian coordinate system, i.e., an index of (0,0,0) in the lattice
gives the element whose x, y, and z coordinates are the smallest. However, note that when universes are assigned
to lattice elements using the RectLattice.universes property, the array indices do not correspond to natural
indices.
Parameters
• lattice_id (int, optional) – Unique identifier for the lattice. If not specified, an iden-
• name (str, optional) – Name of the lattice. If not specified, the name is the empty string.
Variables
• id (int) – Unique identifier for the lattice
• name (str) – Name of the lattice
• pitch (Iterable of float) – Pitch of the lattice in the x, y, and (if applicable) z directions
in cm.
• outer (openmc.Universe) – A universe to fill all space outside the lattice
• universes (Iterable of Iterable of openmc.Universe) – A two- or three-
dimensional list/array of universes filling each element of the lattice. The first dimension
corresponds to the z-direction (if applicable), the second dimension corresponds to the
y-direction, and the third dimension corresponds to the x-direction. Note that for the y-
direction, a higher index corresponds to a lower physical y-value. Each z-slice in the array
can be thought of as a top-down view of the lattice.
• lower_left (Iterable of float) – The Cartesian coordinates of the lower-left corner
of the lattice. If the lattice is two-dimensional, only the x- and y-coordinates are specified.
• indices (list of tuple) – A list of all possible (z,y,x) or (y,x) lattice element indices.
These indices correspond to indices in the RectLattice.universes property.
• ndim (int) – The number of dimensions of the lattice
• shape (Iterable of int) – An array of two or three integers representing the number of
lattice cells in the x- and y- (and z-) directions, respectively.
Add the lattice xml representation to an incoming xml element
Parameters
Return type
None

discretize(strategy='degenerate', universes_to_ignore=[], materials_to_clone=[], lattice_neighbors=[],

key=<function RectLattice.<lambda>>)
Discretize the lattice with either a degenerate or a local neighbor symmetry strategy
‘Degenerate’ clones every universe in the lattice, thus making them all uniquely defined. This is typically
required if depletion or thermal hydraulics will make every universe’s environment unique.
‘Local neighbor symmetry’ groups universes with similar neighborhoods. These clusters of cells and ma-
terials provide increased convergence speed to multi-group cross sections tallies. The user can specify the
lattice’s neighbors to discriminate between two sides of a lattice for example.
Parameters
• strategy ({'degenerate', 'lns'}) – Which strategy to adopt when discretizing the lat-
tice
• universes_to_ignore (Iterable of Universe) – Lattice universes that need not be
discretized
• materials_to_clone (Iterable of Material) – List of materials that should be
cloned when discretizing
• lattice_neighbors (Iterable of Universe) – List of the lattice’s neighbors. By
default, if present, the lattice outer universe will be used. The neighbors should be ordered
as follows [top left, top, top right, left, right, bottom left, bottom, bottom right]
• key (function) – Function of argument a universe that is used to extract a comparison key.
This function will be called on each universe’s neighbors in the lattice to form a neighbor
pattern. This pattern is then used to identify unique neighbor symmetries.
find_element(point)
Determine index of lattice element and local coordinates for a point
Parameters
point (Iterable of float) – Cartesian coordinates of point
Returns
• 2- or 3-tuple of int – A tuple of the corresponding (x,y,z) lattice element indices
• 3-tuple of float – Carestian coordinates of the point in the corresponding lattice element
coordinate system
classmethod from_hdf5(group, universes)
Create rectangular lattice from HDF5 group
Parameters
• universes (dict) – Dictionary mapping universe IDs to instances of openmc.Universe.
Returns
Rectangular lattice
Return type
openmc.RectLattice
classmethod from_xml_element(elem, get_universe)
Generate rectangular lattice from XML element
Parameters
• elem (xml.etree.ElementTree.Element) – <lattice> element


Returns
Rectangular lattice
Return type
RectLattice
get_local_coordinates(point, idx)
Determine local coordinates of a point within a lattice element
Parameters
• point (Iterable of float) – Cartesian coordinates of point
• idx (Iterable of int) – (x,y,z) indices of lattice element. If the lattice is 2D, the z
index can be omitted.
Returns
Cartesian coordinates of point in the lattice element coordinate system
Return type
3-tuple of float
get_universe_index(idx)
Return index in the universes array corresponding to a lattice element index
Parameters
idx (Iterable of int) – Lattice element indices in the (𝑥, 𝑦, 𝑧) coordinate system
Returns
Indices used when setting the RectLattice.universes property
Return type
2- or 3-tuple of int
is_valid_index(idx)
Determine whether lattice element index is within defined range
Parameters
idx (Iterable of int) – Lattice element indices in the (𝑥, 𝑦, 𝑧) coordinate system
Returns
Whether index is valid
Return type
bool
openmc.HexLattice
class openmc.HexLattice(lattice_id=None, name='')

A lattice consisting of hexagonal prisms.
To completely define a hexagonal lattice, the HexLattice.center, HexLattice.pitch, HexLattice.
universes, and HexLattice.outer properties need to be set.
Most methods for this class use a natural indexing scheme wherein elements are assigned an index corresponding
to their position relative to skewed (𝑥, 𝛼, 𝑧) or (𝛼, 𝑦, 𝑧) bases, depending on the lattice orientation, as described
fully in Hexagonal Lattice Indexing. However, note that when universes are assigned to lattice elements using
the HexLattice.universes property, the array indices do not correspond to natural indices.

Changed in version 0.11: The orientation of the lattice can now be changed with the orientation attribute.
Parameters
Variables
• pitch (Iterable of float) – Pitch of the lattice in cm. The first item in the iterable
specifies the pitch in the radial direction and, if the lattice is 3D, the second item in the
iterable specifies the pitch in the axial direction.
• universes (Nested Iterable of openmc.Universe) – A two- or three-dimensional
list/array of universes filling each element of the lattice. Each sub-list corresponds to one
ring of universes and should be ordered from outermost ring to innermost ring. The uni-
verses within each sub-list are ordered from the “top” and proceed in a clockwise fashion.
The HexLattice.show_indices() method can be used to help figure out indices for this
property.
• center (Iterable of float) – Coordinates of the center of the lattice. If the lattice does
not have axial sections then only the x- and y-coordinates are specified
• indices (list of tuple) – A list of all possible (z,r,i) or (r,i) lattice element indices that
are possible, where z is the axial index, r is in the ring index (starting from the outermost
ring), and i is the index with a ring starting from the top and proceeding clockwise.
• orientation ({'x', 'y'}) – str by default ‘y’ orientation of main lattice diagonal another
option - ‘x’
• num_rings (int) – Number of radial ring positions in the xy-plane
• num_axial (int) – Number of positions along the z-axis.
find_element(point)
Determine index of lattice element and local coordinates for a point
Parameters
point (Iterable of float) – Cartesian coordinates of point
Returns
• 3-tuple of int – Indices of corresponding lattice element in (𝑥, 𝛼, 𝑧) or (𝛼, 𝑦, 𝑧) bases
• numpy.ndarray – Carestian coordinates of the point in the corresponding lattice element
coordinate system
classmethod from_hdf5(group, universes)
Create rectangular lattice from HDF5 group
Parameters

Returns
Hexagonal lattice
Return type
openmc.HexLattice
classmethod from_xml_element(elem, get_universe)
Generate hexagonal lattice from XML element
Parameters
• elem (xml.etree.ElementTree.Element) – <hex_lattice> element
Returns
Hexagonal lattice
Return type
HexLattice
get_local_coordinates(point, idx)
Determine local coordinates of a point within a lattice element
Parameters
• point (Iterable of float) – Cartesian coordinates of point
• idx (Iterable of int) – Indices of lattice element in (𝑥, 𝛼, 𝑧) or (𝛼, 𝑦, 𝑧) bases
Returns
Cartesian coordinates of point in the lattice element coordinate system
Return type
3-tuple of float
get_universe_index(idx)
Return index in the universes array corresponding to a lattice element index
Parameters
idx (Iterable of int) – Lattice element indices in the (𝑥, 𝛼, 𝑧) coordinate system in ‘y’
orientation case, or indices in the (𝛼, 𝑦, 𝑧) coordinate system in ‘x’ one
Returns
• 2- or 3-tuple of int
• Indices used when setting the HexLattice.universes
• property
is_valid_index(idx)
Determine whether lattice element index is within defined range
Parameters
idx (Iterable of int) – Lattice element indices in the both (𝑥, 𝛼, 𝑧) and (𝛼, 𝑦, 𝑧) coor-
dinate system
Returns
Whether index is valid
Return type
bool

static show_indices(num_rings, orientation='y')

Return a diagram of the hexagonal lattice layout with indices.
Parameters
• num_rings (int) – Number of rings in the hexagonal lattice
• orientation ({"x", "y"}) – Orientation of the hexagonal lattice
Returns
Diagram of the hexagonal lattice showing indices
Return type
str
openmc.Geometry
class openmc.Geometry(root=None)
Geometry representing a collection of surfaces, cells, and universes.
Parameters
root (openmc.UniverseBase or Iterable of openmc.Cell, optional) – Root uni-
verse which contains all others, or an iterable of cells that should be used to create a root universe.
Variables
• root_universe (openmc.UniverseBase) – Root universe which contains all others
Add volume information from a stochastic volume calculation.
Parameters
tion
clone()
Create a copy of this geometry with new unique IDs for all of its enclosed materials, surfaces, cells, uni-
verses and lattices.
determine_paths(instances_only=False)
Determine paths through CSG tree for cells and materials.
This method recursively traverses the CSG tree to determine each unique path that reaches every cell and
material. The paths are stored in the Cell.paths and Material.paths attributes.
Parameters
instances_only (bool, optional) – If true, this method will only determine the number
of instances of each cell and material.
export_to_xml(path='geometry.xml', remove_surfs=False)
Export geometry to an XML file.
Parameters
• path (str) – Path to file to write. Defaults to ‘geometry.xml’.

• remove_surfs (bool) – Whether or not to remove redundant surfaces from the geometry
when exporting
find(point)
Parameters
Returns
Return type
list
classmethod from_xml(path='geometry.xml', materials=None)
Generate geometry from XML file
Parameters
• path (str, optional) – Path to geometry XML file
• materials (openmc.Materials or None) – Materials used to assign to cells. If None,
an attempt is made to generate it from the materials.xml file.
Returns
Geometry object
Return type
openmc.Geometry
get_all_cells()
Return all cells in the geometry.
Returns
Dictionary mapping cell IDs to openmc.Cell instances
Return type
get_all_lattices()
Return all lattices defined
Returns
Dictionary mapping lattice IDs to openmc.Lattice instances
Return type
get_all_material_cells()
Return all cells filled by a material
Returns
Dictionary mapping cell IDs to openmc.Cell instances that are filled with materials or dis-
tributed materials.
Return type

get_all_material_universes()
Return all universes having at least one material-filled cell.
This method can be used to find universes that have at least one cell that is filled with a material or is void.
Returns
Dictionary mapping universe IDs to openmc.Universe instances with at least one material-
filled cell
Return type
get_all_materials()
Return all materials within the geometry.
Returns
Dictionary mapping material IDs to openmc.Material instances
Return type
get_all_surfaces()
Return all surfaces used in the geometry
Returns
Dictionary mapping surface IDs to openmc.Surface instances
Return type
get_all_universes()
Return all universes in the geometry.
Returns
Dictionary mapping universe IDs to openmc.Universe instances
Return type
get_cells_by_fill_name(name, case_sensitive=False, matching=False)
Return a list of cells with fills with matching names.
Parameters
• name (str) – The name to match
• case_sensitive (bool) – Whether to distinguish upper and lower case letters in each
cell’s name (default is False)
• matching (bool) – Whether the names must match completely (default is False)
Returns
Cells with fills matching the queried name
Return type
list of openmc.Cell
get_cells_by_name(name, case_sensitive=False, matching=False)
Return a list of cells with matching names.
Parameters
• name (str) – The name to search match

cell’s name (default is False)
Returns
Cells matching the queried name
Return type
list of openmc.Cell
get_instances(paths)
Return the instance number(s) for a cell/material in a geometry path.
The instance numbers are used as indices into distributed material/temperature arrays and tally distribcell
filter arrays.
Parameters
paths (str or iterable of str) – The path traversed through the CSG tree to reach a
cell or material instance. For example, ‘u0->c10->l20(2,2,1)->u5->c5’ would indicate the
cell instance whose first level is universe 0 and cell 10, second level is lattice 20 position
(2,2,1), and third level is universe 5 and cell 5.
Returns
Instance number(s) for the given path(s)
Return type
int or list of int
get_lattices_by_name(name, case_sensitive=False, matching=False)
Return a list of lattices with matching names.
Parameters
lattice’s name (default is False)
Returns
Lattices matching the queried name
Return type
list of openmc.Lattice
get_materials_by_name(name, case_sensitive=False, matching=False)
Return a list of materials with matching names.
Parameters
material’s name (default is False)
Returns
Materials matching the queried name
Return type
list of openmc.Material

get_redundant_surfaces()
Return all of the topologically redundant surface IDs
Returns
Dictionary whose keys are the ID of a redundant surface and whose values are the topologi-
cally equivalent openmc.Surface that should replace it.
Return type
dict
get_universes_by_name(name, case_sensitive=False, matching=False)
Return a list of universes with matching names.
Parameters
universe’s name (default is False)
Returns
Universes matching the queried name
Return type
list of openmc.Universe
remove_redundant_surfaces()
Remove redundant surfaces from the geometry
Many of the above classes are derived from several abstract classes:
openmc.Surface An implicit surface with an associated boundary condi-

tion.
openmc.Region Region of space that can be assigned to a cell.
openmc.Lattice A repeating structure wherein each element is a universe.
openmc.Surface
class openmc.Surface(surface_id=None, boundary_type='transmission', name='')

An implicit surface with an associated boundary condition.
An implicit surface is defined as the set of zeros of a function of the three Cartesian coordinates. Surfaces in
OpenMC are limited to a set of algebraic surfaces, i.e., surfaces that are polynomial in x, y, and z.
Parameters
through the surface. Note that periodic boundary conditions can only be applied to x-, y-,
and z-planes, and only axis-aligned periodicity is supported.

• name (str, optional) – Name of the surface. If not specified, the name will be the empty
string.
Variables
bounding_box(side)
Parameters
Returns
half-space
half-space
clone(memo=None)
Create a copy of this surface with a new unique ID.
Parameters
Returns
clone – The clone of this surface
Return type
openmc.Surface
abstract evaluate(point)
Parameters
Returns
Return type
float
static from_hdf5(group)
Create surface from HDF5 group
Parameters

Returns
Instance of surface subclass
Return type
openmc.Surface
static from_xml_element(elem)
Generate surface from an XML element
Parameters
Returns
Instance of a surface subclass
Return type
openmc.Surface
is_equal(other)
Determine if this Surface is equivalent to another
Parameters
other (instance of openmc.Surface) – Instance of openmc.Surface that should be com-
pared to the current surface
normalize(coeffs=None)
Normalize coefficients by first nonzero value
Parameters
coeffs (tuple, optional) – Tuple of surface coefficients to normalize. Defaults to None.
If no coefficients are supplied then the coefficients will be taken from the current Surface.
Return type
tuple of normalized coefficients
abstract rotate(rotation, pivot=(0.0, 0.0, 0.0), order='xyz', inplace=False)
Parameters

Returns
Rotated surface
Return type
openmc.Surface
to_xml_element()
Return XML representation of the surface
Returns
Return type
abstract translate(vector, inplace=False)
Translate surface in given direction
Parameters
• vector (iterable of float) – Direction in which surface should be translated
• inplace (bool) – Whether or not to return a new instance of this Surface or to modify the
coefficients of this Surface.
Returns
Translated surface
Return type
instance of openmc.Surface
openmc.Region
class openmc.Region
Region of space that can be assigned to a cell.
Region is an abstract base class that is inherited by openmc.Halfspace, openmc.Intersection, openmc.
Union, and openmc.Complement. Each of those respective classes are typically not instantiated directly but
rather are created through operators of the Surface and Region classes.
clone(memo=None)
Create a copy of this region - each of the surfaces in the region’s nodes will be cloned and will have new
unique IDs.
Parameters
Returns
clone – The clone of this region
Return type
openmc.Region
static from_expression(expression, surfaces)
Generate a region given an infix expression.
Parameters

• expression (str) – Boolean expression relating surface half-spaces. The possible op-
erators are union ‘|’, intersection ‘ ‘, and complement ‘~’. For example, ‘(1 -2) | 3 ~(4
-5)’.
• surfaces (dict) – Dictionary whose keys are surface IDs that appear in the Boolean
expression and whose values are Surface objects.
Recursively find all surfaces referenced by a region and return them
Parameters
Returns
Return type
Parameters
redundant_surfaces (dict) – Dictionary mapping redundant surface IDs to
class:openmc.Surface instances that should replace them.
Parameters
Returns
Translated region
Return type
openmc.Region


Translate region in given direction
Parameters
• inplace (bool) – Whether or not to return a region based on new surfaces or one based
on the original surfaces that have been modified.
• memo (dict or None) – Dictionary used for memoization. This parameter is used inter-
nally and should not be specified by the user.
Returns
Translated region
Return type
openmc.Region
openmc.Lattice
class openmc.Lattice(lattice_id=None, name='')

A repeating structure wherein each element is a universe.
Parameters
Variables
• pitch (Iterable of float) – Pitch of the lattice in each direction in cm
• universes (Iterable of Iterable of openmc.Universe) – A two-or three-
dimensional list/array of universes filling each element of the lattice
clone(clone_materials=True, clone_regions=True, memo=None)
Create a copy of this lattice with a new unique ID, and clones all universes within this lattice.
Parameters
• clone_materials (bool) – Whether to create separate copies of the materials filling cells
contained in this lattice and its outer universe.
• clone_regions (bool) – Whether to create separate copies of the regions bounding cells
contained in this lattice and its outer universe.
• memo (dict or None) – A nested dictionary of previously cloned objects. This parameter
Returns
clone – The clone of this lattice

Return type
openmc.Lattice
find(point)
Parameters
Returns
Return type
list
static from_hdf5(group, universes)
Create lattice from HDF5 group
Parameters
Returns
Instance of lattice subclass
Return type
openmc.Lattice
Return all cells that are contained within the lattice
Returns
Return type
Return all materials that are contained within the lattice
Returns
Return type
get_all_universes()
Return all universes that are contained within the lattice
Returns
Return type
get_nuclides()
Returns all nuclides in the lattice
Returns

Return type
list of str
get_unique_universes()
Determine all unique universes in the lattice
Returns
universes – Dictionary whose keys are universe IDs and values are openmc.Universe in-
stances
Return type
get_universe(idx)
Return universe corresponding to a lattice element index
Parameters
idx (Iterable of int) – Lattice element indices. For a rectangular lattice, the indices are
given in the (𝑥, 𝑦) or (𝑥, 𝑦, 𝑧) coordinate system. For hexagonal lattices, they are given in the
𝑥, 𝛼 or 𝑥, 𝛼, 𝑧 coordinate systems for “y” orientations and 𝛼, 𝑦 or 𝛼, 𝑦, 𝑧 coordinate systems
for “x” orientations.
Returns
Universe with given indices
Return type
openmc.Universe
6.1.5 Constructing Tallies
openmc.Filter Tally modifier that describes phase-space and other char-

acteristics.
openmc.UniverseFilter Bins tally event locations based on the Universe they oc-
curred in.
openmc.MaterialFilter Bins tally event locations based on the Material they oc-
curred in.
openmc.CellFilter Bins tally event locations based on the Cell they occurred
in.
openmc.CellFromFilter Bins tally on which cell the particle came from.
openmc.CellbornFilter Bins tally events based on which cell the particle was
born in.
openmc.CellInstanceFilter Bins tally events based on which cell instance a particle
is in.
openmc.CollisionFilter Bins tally events based on the number of collisions.
openmc.SurfaceFilter Filters particles by surface crossing
openmc.MeshFilter Bins tally event locations onto a regular, rectangular
mesh.
openmc.MeshSurfaceFilter Filter events by surface crossings on a regular, rectangu-
lar mesh.
openmc.EnergyFilter Bins tally events based on incident particle energy.
openmc.EnergyoutFilter Bins tally events based on outgoing particle energy.
openmc.MuFilter Bins tally events based on particle scattering angle.
openmc.PolarFilter Bins tally events based on the incident particle's direc-
tion.
continues on next page

Table 1 – continued from previous page

openmc.AzimuthalFilter Bins tally events based on the incident particle's direc-
tion.
openmc.DistribcellFilter Bins tally event locations on instances of repeated cells.
openmc.DelayedGroupFilter Bins fission events based on the produced neutron pre-
cursor groups.
openmc.EnergyFunctionFilter Multiplies tally scores by an arbitrary function of inci-
dent energy.
openmc.LegendreFilter Score Legendre expansion moments up to specified or-
der.
openmc.SpatialLegendreFilter Score Legendre expansion moments in space up to spec-
ified order.
openmc.SphericalHarmonicsFilter Score spherical harmonic expansion moments up to
specified order.
openmc.TimeFilter Bins tally events based on the particle's time.
openmc.ZernikeFilter Score Zernike expansion moments in space up to speci-
fied order.
openmc.ZernikeRadialFilter Score the 𝑚 = 0 (radial variation only) Zernike mo-
ments up to specified order.
openmc.ParticleFilter Bins tally events based on the Particle type.
openmc.RegularMesh A regular Cartesian mesh in one, two, or three dimen-
sions
openmc.RectilinearMesh A 3D rectilinear Cartesian mesh
openmc.CylindricalMesh A 3D cylindrical mesh
openmc.SphericalMesh A 3D spherical mesh
openmc.UnstructuredMesh A 3D unstructured mesh
openmc.Trigger A criterion for when to finish a simulation based on tally
uncertainties.
openmc.TallyDerivative A material perturbation derivative to apply to a tally.
openmc.Tally A tally defined by a set of scores that are accumulated
for a list of nuclides given a set of filters.
openmc.Tallies Collection of Tallies used for an OpenMC simulation.
openmc.Filter
class openmc.Filter(bins, filter_id=None)

Tally modifier that describes phase-space and other characteristics.
Parameters
• bins (Integral or Iterable of Integral or Iterable of Real) – The bins for
the filter. This takes on different meaning for different filters. See the docstrings for sub-
classes of this filter or the online documentation for more details.
• filter_id (int) – Unique identifier for the filter
Variables
• bins (Integral or Iterable of Integral or Iterable of Real) – The bins for
the filter
• id (int) – Unique identifier for the filter
• num_bins (Integral) – The number of filter bins

can_merge(other)
Determine if filter can be merged with another.
Parameters
other (openmc.Filter) – Filter to compare with
Returns
Whether the filter can be merged
Return type
bool
check_bins(bins)
Make sure given bins are valid for this filter.
Raises
• TypeError –
• ValueError –
classmethod from_hdf5(group, **kwargs)
Construct a new Filter instance from HDF5 data.
Parameters
group (h5py.Group) – HDF5 group to read from
Keyword Arguments
meshes (dict) – Dictionary mapping integer IDs to openmc.MeshBase objects. Only used
for openmc.MeshFilter objects.
classmethod from_xml_element(elem, **kwargs)
Generate a filter from an XML element
Parameters
• **kwargs – Keyword arguments (e.g., mesh information)
Returns
Filter object
Return type
openmc.Filter
get_bin_index(filter_bin)
Returns the index in the Filter for some bin.
Parameters
filter_bin (int or tuple) – The bin is the integer ID for ‘material’, ‘surface’, ‘cell’,
‘cellborn’, and ‘universe’ Filters. The bin is an integer for the cell instance ID for ‘distribcell’
Filters. The bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to
the energy boundaries of the bin of interest. The bin is an (x,y,z) 3-tuple for ‘mesh’ filters
corresponding to the mesh cell of interest.
Returns
filter_index – The index in the Tally data array for this filter bin.
Return type
int

get_pandas_dataframe(data_size, stride, **kwargs)

Builds a Pandas DataFrame for the Filter’s bins.
This method constructs a Pandas DataFrame object for the filter with columns annotated by filter bin infor-
mation. This is a helper method for Tally.get_pandas_dataframe().
Parameters
• data_size (int) – The total number of bins in the tally corresponding to this filter
• stride (int) – Stride in memory for the filter
Keyword Arguments
paths (bool) – Only used for DistribcellFilter. If True (default), expand distribcell indices
into multi-index columns describing the path to that distribcell through the CSG tree. NOTE:
This option assumes that all distribcell paths are of the same length and do not have the same
universes and cells but different lattice cell indices.
Returns
A Pandas DataFrame with columns of strings that characterize the filter’s bins. The number
of rows in the DataFrame is the same as the total number of bins in the corresponding tally,
with the filter bin appropriately tiled to map to the corresponding tally bins.
Return type
pandas.DataFrame
See also:
Tally.get_pandas_dataframe, CrossFilter.get_pandas_dataframe
is_subset(other)
Determine if another filter is a subset of this filter.
If all of the bins in the other filter are included as bins in this filter, then it is a subset of this filter.
Parameters
other (openmc.Filter) – The filter to query as a subset of this filter
Returns
Whether or not the other filter is a subset of this filter
Return type
bool
merge(other)
Merge this filter with another.
Parameters
other (openmc.Filter) – Filter to merge with
Returns
merged_filter – Filter resulting from the merge
Return type
openmc.Filter
to_xml_element()
Return XML Element representing the Filter.
Returns
element – XML element containing filter data
Return type

openmc.UniverseFilter
class openmc.UniverseFilter(bins, filter_id=None)

Bins tally event locations based on the Universe they occurred in.
Parameters
• bins (openmc.UniverseBase, int, or iterable thereof ) – The Universes to tally.
Either openmc.UniverseBase objects or their Integral ID numbers can be used.
Variables
• bins (Iterable of Integral) – openmc.UniverseBase IDs.
expected_type
alias of UniverseBase
openmc.MaterialFilter
class openmc.MaterialFilter(bins, filter_id=None)

Bins tally event locations based on the Material they occurred in.
Parameters
• bins (openmc.Material, Integral, or iterable thereof ) – The Materials to
tally. Either openmc.Material objects or their Integral ID numbers can be used.
Variables
• bins (Iterable of Integral) – openmc.Material IDs.
expected_type
alias of Material
openmc.CellFilter
class openmc.CellFilter(bins, filter_id=None)

Bins tally event locations based on the Cell they occurred in.
Parameters
• bins (openmc.Cell, int, or iterable thereof ) – The cells to tally. Either
openmc.Cell objects or their ID numbers can be used.
Variables
• bins (Iterable of Integral) – openmc.Cell IDs.


expected_type
alias of Cell
openmc.CellFromFilter
class openmc.CellFromFilter(bins, filter_id=None)

Bins tally on which cell the particle came from.
Parameters
• bins (openmc.Cell, Integral, or iterable thereof ) – The cell(s) to tally. Either
openmc.Cell objects or their integral ID numbers can be used.
Variables
• bins (Integral or Iterable of Integral) – Cell IDs.
expected_type
alias of Cell
openmc.CellbornFilter
class openmc.CellbornFilter(bins, filter_id=None)

Bins tally events based on which cell the particle was born in.
Parameters
• bins (openmc.Cell, Integral, or iterable thereof ) – The birth cells to tally. Ei-
ther openmc.Cell objects or their integral ID numbers can be used.
Variables
• bins (Iterable of Integral) – Cell IDs.
expected_type
alias of Cell

openmc.CellInstanceFilter
class openmc.CellInstanceFilter(bins, filter_id=None)

Bins tally events based on which cell instance a particle is in.
This filter is similar to DistribcellFilter but allows one to select particular instances to be tallied (instead
of obtaining all instances by default) and allows instances from different cells to be specified in a single filter.
Parameters
• bins (iterable of 2-tuples or numpy.ndarray) – The cell instances to tally, given
as 2-tuples. For the first value in the tuple, either openmc.Cell objects or their integral ID
numbers can be used.
Variables
• bins (numpy.ndarray) – 2D numpy array of cell IDs and instances
See also:
DistribcellFilter
Parameters
Returns
Filter object
Return type
openmc.Filter
Parameters
Returns
A Pandas DataFrame with a multi-index column for the cell instance. The number of rows
in the DataFrame is the same as the total number of bins in the corresponding tally, with the
filter bin appropriately tiled to map to the corresponding tally bins.
Return type
pandas.DataFrame

See also:
to_xml_element()
Returns
Return type
openmc.CollisionFilter
class openmc.CollisionFilter(bins, filter_id=None)

Bins tally events based on the number of collisions.
Parameters
• bins (Iterable of int) – A list or iterable of the number of collisions, as integer values.
The events whose post-scattering collision number equals one of the provided values will be
counted.
Variables
• bins (numpy.ndarray) – An array of integer values representing the number of collisions
events by which to filter
• num_bins (int) – The number of filter bins
check_bins(bins)
Raises
• TypeError –
• ValueError –
openmc.SurfaceFilter
class openmc.SurfaceFilter(bins, filter_id=None)

Filters particles by surface crossing
Parameters
• bins (openmc.Surface, int, or iterable of Integral) – The surfaces to tally
over. Either openmc.Surface objects or their ID numbers can be used.
Variables
• bins (Iterable of Integral) – The surfaces to tally over. Either openmc.Surface ob-
jects or their ID numbers can be used.


expected_type
alias of Surface
openmc.MeshFilter
class openmc.MeshFilter(mesh, filter_id=None)

Bins tally event locations onto a regular, rectangular mesh.
Parameters
• mesh (openmc.MeshBase) – The mesh object that events will be tallied onto
Variables
• translation (Iterable of float) – This array specifies a vector that is used to translate
(shift) the mesh for this filter
• bins (list of tuple) – A list of mesh indices for each filter bin, e.g. [(1, 1, 1), (2, 1, 1),
...]
can_merge(other)
Parameters
Returns
Return type
bool
Parameters
Keyword Arguments
Parameters

Returns
Filter object
Return type
openmc.Filter
Parameters
Returns
A Pandas DataFrame with three columns describing the x,y,z mesh cell indices corresponding
to each filter bin. The number of rows in the DataFrame is the same as the total number of bins
in the corresponding tally, with the filter bin appropriately tiled to map to the corresponding
tally bins.
Return type
pandas.DataFrame
See also:
to_xml_element()
Returns
Return type
openmc.MeshSurfaceFilter
class openmc.MeshSurfaceFilter(mesh, filter_id=None)

Filter events by surface crossings on a regular, rectangular mesh.
Parameters
Variables
• bins (list of tuple) – The mesh ID
• translation (Iterable of float) – This array specifies a vector that is used to translate
(shift) the mesh for this filter
• bins – A list of mesh indices / surfaces for each filter bin, e.g. [(1, 1, ‘x-min out’), (1, 1,
‘x-min in’), . . . ]


Parameters
Returns
A Pandas DataFrame with three columns describing the x,y,z mesh cell indices corresponding
to each filter bin. The number of rows in the DataFrame is the same as the total number of bins
in the corresponding tally, with the filter bin appropriately tiled to map to the corresponding
tally bins.
Return type
pandas.DataFrame
See also:
openmc.EnergyFilter
class openmc.EnergyFilter(values, filter_id=None)

Bins tally events based on incident particle energy.
Parameters
• values (Iterable of Real) – A list of values for which each successive pair constitutes
a range of energies in [eV] for a single bin
Variables
• values (numpy.ndarray) – An array of values for which each successive pair constitutes
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of energies in
[eV] for a single filter bin
check_bins(bins)
Raises
• TypeError –
• ValueError –
classmethod from_group_structure(group_structure)
Construct an EnergyFilter instance from a standard group structure.

Parameters
group_structure (str) – Name of the group structure. Must be a valid key of
openmc.mgxs.GROUP_STRUCTURES dictionary.
Parameters
Returns
Return type
int
property lethargy_bin_width
Calculates the base 10 log width of energy bins which is useful when plotting the normalized flux.
Returns
Array of bin widths
Return type
numpy.array
openmc.EnergyoutFilter
class openmc.EnergyoutFilter(values, filter_id=None)

Bins tally events based on outgoing particle energy.
Parameters
• values (Iterable of Real) – A list of values for which each successive pair constitutes
Variables
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of energies in
[eV] for a single filter bin

openmc.MuFilter
class openmc.MuFilter(values, filter_id=None)

Bins tally events based on particle scattering angle.
Parameters
• values (int or Iterable of Real) – A grid of scattering angles which events will
binned into. Values represent the cosine of the scattering angle. If an iterable is given,
the values will be used explicitly as grid points. If a single int is given, the range [-1, 1] will
be divided up equally into that number of bins.
Variables
a range of scattering angle cosines for a single bin
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of scattering
angle cosines for a single filter bin
check_bins(bins)
Raises
• TypeError –
• ValueError –
openmc.PolarFilter
class openmc.PolarFilter(values, filter_id=None)

Bins tally events based on the incident particle’s direction.
Parameters
• values (int or Iterable of Real) – A grid of polar angles which events will binned
into. Values represent an angle in radians relative to the z-axis. If an iterable is given, the
values will be used explicitly as grid points. If a single int is given, the range [0, pi] will be
divided up equally into that number of bins.
Variables
a range of polar angles in [rad] for a single bin
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of polar angles
for a single filter bin
• id – Unique identifier for the filter

check_bins(bins)
Raises
• TypeError –
• ValueError –
openmc.AzimuthalFilter
class openmc.AzimuthalFilter(values, filter_id=None)

Bins tally events based on the incident particle’s direction.
Parameters
• values (int or Iterable of Real) – A grid of azimuthal angles which events will
binned into. Values represent an angle in radians relative to the x-axis and perpendicular
to the z-axis. If an iterable is given, the values will be used explicitly as grid points. If a
single int is given, the range [-pi, pi) will be divided up equally into that number of bins.
Variables
a range of azimuthal angles in [rad] for a single bin
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of azimuthal
angles for a single filter bin
check_bins(bins)
Raises
• TypeError –
• ValueError –
openmc.DistribcellFilter
class openmc.DistribcellFilter(cell, filter_id=None)

Bins tally event locations on instances of repeated cells.
This filter provides a separate score for each unique instance of a repeated cell in a geometry. Note that only one
cell can be specified in this filter. The related CellInstanceFilter allows one to obtain scores for particular
cell instances as well as instances from different cells.
Parameters
• cell (openmc.Cell or Integral) – The distributed cell to tally. Either an openmc.Cell
or an Integral cell ID number can be used.
Variables

• bins (Iterable of Integral) – An iterable with one element—the ID of the distributed

Cell.
• paths (list of str) – The paths traversed through the CSG tree to reach each distribcell
instance (for ‘distribcell’ filters only)
See also:
CellInstanceFilter
can_merge(other)
Parameters
Returns
Return type
bool
Parameters
Keyword Arguments
Parameters
Returns
Return type
int
Parameters

Keyword Arguments
paths (bool) – If True (default), expand distribcell indices into multi-index columns de-
scribing the path to that distribcell through the CSG tree. NOTE: This option assumes that
all distribcell paths are of the same length and do not have the same universes and cells but
different lattice cell indices.
Returns
A Pandas DataFrame with columns describing distributed cells. The dataframe will have
either:
1. a single column with the cell instance IDs (without summary info)
2. separate columns for the cell IDs, universe IDs, and lattice IDs and x,y,z cell indices cor-
responding to each (distribcell paths).
The number of rows in the DataFrame is the same as the total number of bins in the corre-
sponding tally, with the filter bin appropriately tiled to map to the corresponding tally bins.
Return type
pandas.DataFrame
See also:
openmc.DelayedGroupFilter
class openmc.DelayedGroupFilter(bins, filter_id=None)

Bins fission events based on the produced neutron precursor groups.
Parameters
• bins (iterable of int) – The delayed neutron precursor groups. For example, ENDF/B-
VII.1 uses 6 precursor groups so a tally with all groups will have bins = [1, 2, 3, 4, 5, 6].
Variables
• bins (iterable of int) – The delayed neutron precursor groups. For example, ENDF/B-
VII.1 uses 6 precursor groups so a tally with all groups will have bins = [1, 2, 3, 4, 5, 6].
check_bins(bins)
Raises
• TypeError –
• ValueError –

openmc.EnergyFunctionFilter
class openmc.EnergyFunctionFilter(energy, y, filter_id=None)

Multiplies tally scores by an arbitrary function of incident energy.
The arbitrary function is described by a piecewise linear-linear interpolation of energy and y values. Values
outside of the given energy range will be evaluated as zero.
Parameters
• energy (Iterable of Real) – A grid of energy values in [eV]
• y (iterable of Real) – A grid of interpolant values in [eV]
Variables
• energy (Iterable of Real) – A grid of energy values in [eV]
• y (iterable of Real) – A grid of interpolant values in [eV]
• num_bins (Integral) – The number of filter bins (always 1 for this filter)
can_merge(other)
Parameters
Returns
Return type
bool
Parameters
Keyword Arguments
classmethod from_tabulated1d(tab1d)
Construct a filter from a Tabulated1D object.
Parameters
tab1d (openmc.data.Tabulated1D) – A linear-linear Tabulated1D object with only a sin-
gle interpolation region.
Return type
EnergyFunctionFilter
Parameters


Returns
Filter object
Return type
openmc.Filter
Parameters
Returns
Return type
int
Parameters
Returns
A Pandas DataFrame with a column that is filled with a hash of this filter. EnergyFunction-
Filters have only 1 bin so the purpose of this DataFrame column is to differentiate the filter
from other EnergyFunctionFilters. The number of rows in the DataFrame is the same as the
total number of bins in the corresponding tally.
Return type
pandas.DataFrame
See also:
is_subset(other)
Determine if another filter is a subset of this filter.
If all of the bins in the other filter are included as bins in this filter, then it is a subset of this filter.
Parameters
other (openmc.Filter) – The filter to query as a subset of this filter
Returns
Whether or not the other filter is a subset of this filter
Return type
bool

to_xml_element()
Returns
Return type
openmc.LegendreFilter
class openmc.LegendreFilter(order, filter_id=None)

Score Legendre expansion moments up to specified order.
This filter allows scores to be multiplied by Legendre polynomials of the change in particle angle (𝜇) up to a
user-specified order.
Parameters
• order (int) – Maximum Legendre polynomial order
• filter_id (int or None) – Unique identifier for the filter
Variables
Parameters
Keyword Arguments
openmc.SpatialLegendreFilter
class openmc.SpatialLegendreFilter(order, axis, minimum, maximum, filter_id=None)

Score Legendre expansion moments in space up to specified order.
This filter allows scores to be multiplied by Legendre polynomials of the the particle’s position along a particular
axis, normalized to a given range, up to a user-specified order.
Parameters
• axis ({'x', 'y', 'z'}) – Axis along which to take the expansion
• minimum (float) – Minimum value along selected axis
• maximum (float) – Maximum value along selected axis
Variables


• axis ({'x', 'y', 'z'}) – Axis along which to take the expansion
• minimum (float) – Minimum value along selected axis
• maximum (float) – Maximum value along selected axis
Parameters
Keyword Arguments
Parameters
Returns
Filter object
Return type
openmc.Filter
to_xml_element()
Return XML Element representing the filter.
Returns
element – XML element containing Legendre filter data
Return type
openmc.SphericalHarmonicsFilter
class openmc.SphericalHarmonicsFilter(order, filter_id=None)

Score spherical harmonic expansion moments up to specified order.
This filter allows you to obtain real spherical harmonic moments of either the particle’s direction or the cosine
of the scattering angle. Specifying a filter with order ℓ tallies moments for all orders from 0 to ℓ.
Parameters
• order (int) – Maximum spherical harmonics order, ℓ
Variables
• order (int) – Maximum spherical harmonics order, ℓ


• cosine ({'scatter', 'particle'}) – How to handle the cosine term.
Parameters
Keyword Arguments
Parameters
Returns
Filter object
Return type
openmc.Filter
to_xml_element()
Returns
element – XML element containing spherical harmonics filter data
Return type
openmc.TimeFilter
class openmc.TimeFilter(values, filter_id=None)

Bins tally events based on the particle’s time.
Parameters
• values (iterable of float) – A list of values for which each successive pair constitutes
a range of time in [s] for a single bin
Variables
a range of time in [s] for a single bin
• bins (numpy.ndarray) – An array of shape (N, 2) where each row is a pair of time in [s]
for a single filter bin


check_bins(bins)
Raises
• TypeError –
• ValueError –
Parameters
Returns
Return type
int
openmc.ZernikeFilter
class openmc.ZernikeFilter(order, x=0.0, y=0.0, r=1.0, filter_id=None)

Score Zernike expansion moments in space up to specified order.
This filter allows scores to be multiplied by Zernike polynomials of the particle’s position normalized to a given
unit circle, up to a user-specified order. The standard Zernike polynomials follow the definition by Born and
Wolf, Principles of Optics and are defined as
𝑍𝑛𝑚 (𝜌, 𝜃) = 𝑅𝑛𝑚 (𝜌) cos(𝑚𝜃), 𝑚>0

𝑍𝑛𝑚 (𝜌, 𝜃)= 𝑅𝑛𝑚 (𝜌) sin(𝑚𝜃), 𝑚<0
𝑍𝑛𝑚 (𝜌, 𝜃) = 𝑅𝑛𝑚 (𝜌), 𝑚=0
where the radial polynomials are

(𝑛−𝑚)/2
∑︁ (−1)𝑘 (𝑛 − 𝑘)!
𝑅𝑛𝑚 (𝜌) = 𝜌𝑛−2𝑘 .
𝑘=0
𝑘!( 𝑛+𝑚
2 − 𝑘)!( 𝑛−𝑚
2 − 𝑘)!
With this definition, the integral of (𝑍𝑛𝑚 )2 over the unit disk is 𝜖𝑚 𝜋
2𝑛+2 for each polynomial where 𝜖𝑚 is 2 if 𝑚
equals 0 and 1 otherwise.
Specifying a filter with order N tallies moments for all 𝑛 from 0 to N and each value of 𝑚. The ordering of the
Zernike polynomial moments follows the ANSI Z80.28 standard, where the one-dimensional index 𝑗 corresponds
to the 𝑛 and 𝑚 by
𝑛(𝑛 + 2) + 𝑚
𝑗= .
2
Parameters
• order (int) – Maximum Zernike polynomial order

• x (float) – x-coordinate of center of circle for normalization

• y (float) – y-coordinate of center of circle for normalization
• r (float) – Radius of circle for normalization
Variables
• order (int) – Maximum Zernike polynomial order
Parameters
Keyword Arguments
Parameters
Returns
Filter object
Return type
openmc.Filter
to_xml_element()
Returns
element – XML element containing Zernike filter data
Return type

openmc.ZernikeRadialFilter
class openmc.ZernikeRadialFilter(order, x=0.0, y=0.0, r=1.0, filter_id=None)

Score the 𝑚 = 0 (radial variation only) Zernike moments up to specified order.
The Zernike polynomials are defined the same as in ZernikeFilter.
𝑍𝑛0 (𝜌, 𝜃) = 𝑅𝑛0 (𝜌)
where the radial polynomials are

𝑛/2
∑︁ (−1)𝑘 (𝑛 − 𝑘)!
𝑅𝑛0 (𝜌) = 𝜌𝑛−2𝑘 .
𝑘!(( 𝑛2 − 𝑘)!)2
𝑘=0
With this definition, the integral of (𝑍𝑛0 )2 over the unit disk is 𝑛+1 .
𝜋
If there is only radial dependency, the polynomials are integrated over the azimuthal angles. The only terms left
are 𝑍𝑛0 (𝜌, 𝜃) = 𝑅𝑛0 (𝜌). Note that 𝑛 could only be even orders. Therefore, for a radial Zernike polynomials up to
order of 𝑛, there are 𝑛2 + 1 terms in total. The indexing is from the lowest even order (0) to highest even order.
Parameters
• order (int) – Maximum radial Zernike polynomial order
Variables
• order (int) – Maximum radial Zernike polynomial order
openmc.ParticleFilter
class openmc.ParticleFilter(bins, filter_id=None)

Bins tally events based on the Particle type.
Parameters
• bins (str, or iterable of str) – The particles to tally represented as strings (‘neu-
tron’, ‘photon’, ‘electron’, ‘positron’).
Variables
• bins (iterable of str) – The particles to tally


Parameters
Keyword Arguments
Parameters
Returns
Filter object
Return type
openmc.Filter
openmc.RegularMesh
class openmc.RegularMesh(mesh_id=None, name='')

A regular Cartesian mesh in one, two, or three dimensions
Parameters
• mesh_id (int) – Unique identifier for the mesh
• name (str) – Name of the mesh
Variables
• id (int) – Unique identifier for the mesh
• dimension (Iterable of int) – The number of mesh cells in each direction.
• n_dimension (int) – Number of mesh dimensions.
• lower_left (Iterable of float) – The lower-left corner of the structured mesh. If only
two coordinate are given, it is assumed that the mesh is an x-y mesh.
• upper_right (Iterable of float) – The upper-right corner of the structured mesh. If
only two coordinate are given, it is assumed that the mesh is an x-y mesh.
• width (Iterable of float) – The width of mesh cells in each direction.
• indices (Iterable of tuple) – An iterable of mesh indices for each mesh element, e.g.
[(1, 1, 1), (2, 1, 1), . . . ]
build_cells(bc=None)
Generates a lattice of universes with the same dimensionality as the mesh object. The individual
cells/universes produced will not have material definitions applied and so downstream code will have to
apply that information.

Parameters
bc (iterable of {'reflective', 'periodic', 'transmission', 'vacuum', or
'white'}) – Boundary conditions for each of the four faces of a rectangle (if applying to a 2D
mesh) or six faces of a parallelepiped (if applying to a 3D mesh) provided in the following
order: [x min, x max, y min, y max, z min, z max]. 2-D cells do not contain the z min and z
max entries. Defaults to ‘reflective’ for all faces.
Returns
• root_cell (openmc.Cell) – The cell containing the lattice representing the mesh geometry;
this cell is a single parallelepiped with boundaries matching the outermost mesh boundary
with the boundary conditions from bc applied.
• cells (iterable of openmc.Cell) – The list of cells within each lattice position mimicking the
mesh geometry.
Create mesh from HDF5 group
Parameters
Returns
Instance of a MeshBase subclass
Return type
openmc.MeshBase
classmethod from_rect_lattice(lattice, division=1, mesh_id=None, name='')
Create mesh from an existing rectangular lattice
Parameters
• lattice (openmc.RectLattice) – Rectangular lattice used as a template for this mesh
• division (int) – Number of mesh cells per lattice cell. If not specified, there will be 1
mesh cell per lattice cell.
Returns
RegularMesh instance
Return type
openmc.RegularMesh
Generate mesh from an XML element
Parameters
Returns
Mesh generated from XML element
Return type
openmc.Mesh
to_xml_element()
Return XML representation of the mesh

Returns
element – XML element containing mesh data
Return type
property volumes
Return Volumes for every mesh cell
Returns
volumes – Volumes
Return type
numpy.ndarray
write_data_to_vtk(filename, datasets, volume_normalization=True)
Creates a VTK object of the mesh
Parameters
• filename (str or pathlib.Path ) – Name of the VTK file to write.
• datasets (dict) – Dictionary whose keys are the data labels and values are the data sets.
• volume_normalization (bool, optional) – Whether or not to normalize the data by
the volume of the mesh elements. Defaults to True.
Returns
the VTK object
Return type
vtk.vtkStructuredGrid
openmc.RectilinearMesh
class openmc.RectilinearMesh(mesh_id=None, name='')

A 3D rectilinear Cartesian mesh
Parameters
Variables
• n_dimension (int) – Number of mesh dimensions (always 3 for a RectilinearMesh).
• x_grid (numpy.ndarray) – 1-D array of mesh boundary points along the x-axis.
• y_grid (numpy.ndarray) – 1-D array of mesh boundary points along the y-axis.
• z_grid (numpy.ndarray) – 1-D array of mesh boundary points along the z-axis.
[(1, 1, 1), (2, 1, 1), . . . ]

Parameters
Returns
Return type
openmc.MeshBase
Generate a rectilinear mesh from an XML element
Parameters
Returns
Rectilinear mesh object
Return type
openmc.RectilinearMesh
to_xml_element()
Returns
Return type
property volumes
Returns
volumes – Volumes
Return type
numpy.ndarray
Parameters
Returns
the VTK object
Return type

openmc.CylindricalMesh
class openmc.CylindricalMesh(mesh_id=None, name='')

A 3D cylindrical mesh
Parameters
Variables
• n_dimension (int) – Number of mesh dimensions (always 3 for a CylindricalMesh).
• r_grid (numpy.ndarray) – 1-D array of mesh boundary points along the r-axis. Require-
ment is r >= 0.
• phi_grid (numpy.ndarray) – 1-D array of mesh boundary points along the phi-axis in
radians. The default value is [0, 2𝜋], i.e. the full phi range.
• z_grid (numpy.ndarray) – 1-D array of mesh boundary points along the z-axis.
[(1, 1, 1), (2, 1, 1), . . . ]
Parameters
Returns
Return type
openmc.MeshBase
Generate a cylindrical mesh from an XML element
Parameters
Returns
Cylindrical mesh object
Return type
openmc.CylindricalMesh
to_xml_element()
Returns
Return type

property volumes
Returns
volumes – Volumes
Return type
Iterable of float
Parameters
Returns
the VTK object
Return type
openmc.SphericalMesh
class openmc.SphericalMesh(mesh_id=None, name='')

A 3D spherical mesh
Parameters
Variables
• n_dimension (int) – Number of mesh dimensions (always 3 for a SphericalMesh).
• r_grid (numpy.ndarray) – 1-D array of mesh boundary points along the r-axis. Require-
ment is r >= 0.
• theta_grid (numpy.ndarray) – 1-D array of mesh boundary points along the theta-axis
in radians. The default value is [0, 𝜋], i.e. the full theta range.
• phi_grid (numpy.ndarray) – 1-D array of mesh boundary points along the phi-axis in
radians. The default value is [0, 2𝜋], i.e. the full phi range.
[(1, 1, 1), (2, 1, 1), . . . ]

Parameters
Returns
Return type
openmc.MeshBase
Generate a spherical mesh from an XML element
Parameters
Returns
Spherical mesh object
Return type
openmc.SphericalMesh
to_xml_element()
Returns
Return type
property volumes
Returns
volumes – Volumes
Return type
Iterable of float
Parameters
Returns
the VTK object
Return type

openmc.UnstructuredMesh
class openmc.UnstructuredMesh(filename, library, mesh_id=None, name='', length_multiplier=1.0)

A 3D unstructured mesh
Changed in version 0.12.2: Support for libMesh unstructured meshes was added.
Parameters
• filename (str or pathlib.Path ) – Location of the unstructured mesh file
• library ({'moab', 'libmesh'}) – Mesh library used for the unstructured mesh tally
• length_multiplier (float) – Constant multiplier to apply to mesh coordinates
Variables
• filename (str) – Name of the file containing the unstructured mesh
• length_multiplier (float) – Multiplicative factor to apply to mesh coordinates
• library ({'moab', 'libmesh'}) – Mesh library used for the unstructured mesh tally
• output (bool) – Indicates whether or not automatic tally output should be generated for this
mesh
• volumes (Iterable of float) – Volumes of the unstructured mesh elements
• centroids (numpy.ndarray) – Centroids of the mesh elements with array shape
(n_elements, 3)
• vertices (numpy.ndarray) – Coordinates of the mesh vertices with array shape
(n_elements, 3)
• connectivity (numpy.ndarray) – Connectivity of the elements with array shape
(n_elements, 8)
• element_types (Iterable of integers) – Mesh element types
• total_volume (float) – Volume of the unstructured mesh in total
centroid(bin)
Return the vertex averaged centroid of an element
Parameters
bin (int) – Bin ID for the returned centroid
Returns
x, y, z values of the element centroid

Return type
numpy.ndarray
Parameters
Returns
Return type
openmc.MeshBase
Generate unstructured mesh object from XML element
Parameters
Returns
UnstructuredMesh generated from an XML element
Return type
openmc.UnstructuredMesh
to_xml_element()
Returns
Return type
property volumes
Return Volumes for every mesh cell if populated by a StatePoint file
Returns
volumes – Volumes
Return type
numpy.ndarray
write_data_to_vtk(filename=None, datasets=None, volume_normalization=True)
Map data to unstructured VTK mesh elements.
Parameters
• filename (str or pathlib.Path ) – Name of the VTK file to write
• datasets (dict) – Dictionary whose keys are the data labels and values are numpy ap-
propriately sized arrays of the data
• volume_normalization (bool) – Whether or not to normalize the data by the volume of
the mesh elements
write_vtk_mesh(**kwargs)
Map data to unstructured VTK mesh elements.
Deprecated since version 0.13: Use UnstructuredMesh.write_data_to_vtk() instead.
Parameters


• volume_normalization (bool) – Whether or not to normalize the data by the volume of
the mesh elements
openmc.Trigger
class openmc.Trigger(trigger_type, threshold)

A criterion for when to finish a simulation based on tally uncertainties.
Parameters
• trigger_type ({'variance', 'std_dev', 'rel_err'}) – Determine whether to trigger on
the variance, standard deviation, or relative error of scores.
• threshold (float) – The threshold for the trigger type.
Variables
• trigger_type ({'variance', 'std_dev', 'rel_err'}) – Determine whether to trigger on
the variance, standard deviation, or relative error of scores.
• threshold (float) – The threshold for the trigger type.
• scores (list of str) – Scores which should be checked against the trigger
Generate trigger object from an XML element
Parameters
Returns
Trigger object
Return type
openmc.Trigger
to_xml_element()
Return XML representation of the trigger
Returns
element – XML element containing trigger data
Return type
openmc.TallyDerivative
class openmc.TallyDerivative(derivative_id=None, variable=None, material=None, nuclide=None)

A material perturbation derivative to apply to a tally.
Parameters
• derivative_id (int, optional) – Unique identifier for the tally derivative. If none is
specified, an identifier will automatically be assigned
• variable (str, optional) – Accepted values are ‘density’, ‘nuclide_density’, and ‘tem-
perature’

• material (int, optional) – The perturbed material ID

• nuclide (str, optional) – The perturbed nuclide. Only needed for ‘nuclide_density’
derivatives. Ex: ‘Xe135’
Variables
• id (int) – Unique identifier for the tally derivative
• variable (str) – Accepted values are ‘density’, ‘nuclide_density’, and ‘temperature’
• material (int) – The perturubed material ID
• nuclide (str) – The perturbed nuclide. Only needed for ‘nuclide_density’ derivatives. Ex:
‘Xe135’
Generate tally derivative from an XML element
Parameters
Returns
Tally derivative object
Return type
openmc.TallyDerivative
to_xml_element()
Return XML representation of the tally derivative
Returns
element – XML element containing derivative data
Return type
openmc.Tally
class openmc.Tally(tally_id=None, name='')

A tally defined by a set of scores that are accumulated for a list of nuclides given a set of filters.
Parameters
• tally_id (int, optional) – Unique identifier for the tally. If none is specified, an iden-
tifier will automatically be assigned
• name (str, optional) – Name of the tally. If not specified, the name is the empty string.
Variables
• id (int) – Unique identifier for the tally
• name (str) – Name of the tally
• filters (list of openmc.Filter) – List of specified filters for the tally
• nuclides (list of openmc.Nuclide) – List of nuclides to score results for
• scores (list of str) – List of defined scores, e.g. ‘flux’, ‘fission’, etc.
• estimator ({'analog', 'tracklength', 'collision'}) – Type of estimator for the tally
• triggers (list of openmc.Trigger) – List of tally triggers

• num_scores (int) – Total number of scores

• num_filter_bins (int) – Total number of filter bins accounting for all filters
• num_bins (int) – Total number of bins for the tally
• shape (3-tuple of int) – The shape of the tally data array ordered as the number of filter
bins, nuclide bins and score bins
• filter_strides (list of int) – Stride in memory for each filter
• num_realizations (int) – Total number of realizations
• with_summary (bool) – Whether or not a Summary has been linked
• sum (numpy.ndarray) – An array containing the sum of each independent realization for
each bin
• sum_sq (numpy.ndarray) – An array containing the sum of each independent realization
squared for each bin
• mean (numpy.ndarray) – An array containing the sample mean for each bin
• std_dev (numpy.ndarray) – An array containing the sample standard deviation for each
bin
• derived (bool) – Whether or not the tally is derived from one or more other tallies
• sparse (bool) – Whether or not the tally uses SciPy’s LIL sparse matrix format for com-
pressed data storage
• derivative (openmc.TallyDerivative) – A material perturbation derivative to apply to
all scores in the tally.
average(scores=[], filter_type=None, filter_bins=[], nuclides=[], remove_filter=False)
Vectorized average of tally data across scores, filter bins and/or nuclides using tally aggregation.
This method constructs a new tally to encapsulate the average of the data represented by the average of the
data in this tally. The tally data average is determined by the scores, filter bins and nuclides specified in the
input parameters.
Parameters
• scores (list of str) – A list of one or more score strings to average across (e.g., [‘ab-
sorption’, ‘nu-fission’]; default is [])
• filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
• filter_bins (Iterable of int or tuple) – A list of the filter bins corresponding
to the filter_type parameter Each bin in the list is the integer ID for ‘material’, ‘surface’,
‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID
for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters
corresponding to the energy boundaries of the bin of interest. Each bin is an (x,y,z) 3-tuple
for ‘mesh’ filters corresponding to the mesh cell of interest.
• nuclides (list of str) – A list of nuclide name strings to average across (e.g., [‘U235’,
‘U238’]; default is [])
• remove_filter (bool) – If a filter is being averaged over, this bool indicates whether to
remove that filter in the returned tally. Default is False.
Returns
A new tally which encapsulates the average of data requested.

Return type
openmc.Tally
can_merge(other)
Determine if another tally can be merged with this one
If results have been loaded from a statepoint, then tallies are only mergeable along one and only one of
filter bins, nuclides or scores.
Parameters
other (openmc.Tally) – Tally to check for merging
contains_filter(filter_type)
Looks for a filter in the tally that matches a specified type
Parameters
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
Returns
filter_found – True if the tally contains a filter of the requested type; otherwise false
Return type
bool
diagonalize_filter(new_filter, filter_position=-1)
Diagonalize the tally data array along a new axis of filter bins.
This is a helper method for the tally arithmetic methods. This method adds the new filter to a derived tally
constructed copied from this one. The data in the derived tally arrays is “diagonalized” along the bins in the
new filter. This functionality is used by the openmc.mgxs module; to transport-correct scattering matrices
by subtracting a ‘scatter-P1’ reaction rate tally with an energy filter from a ‘scatter’ reaction rate tally with
both energy and energyout filters.
Parameters
• new_filter (Filter) – The filter along which to diagonalize the data in the new
• filter_position (int) – Where to place the new filter in the Tally.filters list. Defaults
to last position.
Returns
A new derived Tally with data diagonalized along the new filter.
Return type
openmc.Tally
find_filter(filter_type)
Return a filter in the tally that matches a specified type
Parameters
filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
Returns
filter_found – Filter from this tally with matching type, or None if no matching Filter is found
Return type
openmc.Filter
Raises
ValueError – If no matching Filter is found


Generate tally object from an XML element
Parameters
Returns
Tally object
Return type
openmc.Tally
get_filter_indices(filters=[], filter_bins=[])
Get indices into the filter axis of this tally’s data arrays.
This is a helper method for the Tally.get_values(. . . ) method to extract tally data. This method returns the
indices into the filter axis of the tally’s data array (axis=0) for particular combinations of filters and their
corresponding bins.
Parameters
• filters (Iterable of openmc.FilterMeta) – An iterable of filter types (e.g., [Mesh-
Filter, EnergyFilter]; default is [])
• filter_bins (Iterable of tuple) – A list of tuples of filter bins corresponding to
the filter_types parameter (e.g., [(1,), ((0., 0.625e-6),)]; default is []). Each tuple contains
bins for the corresponding filter type in the filters parameter. Each bin is an integer ID
for Material-, Surface-, Cell-, Cellborn-, and Universe- Filters. Each bin is an integer for
the cell instance ID for DistribcellFilters. Each bin is a 2-tuple of floats for Energy- and
Energyout- Filters corresponding to the energy boundaries of the bin of interest. The bin
is an (x,y,z) 3-tuple for MeshFilters corresponding to the mesh cell of interest. The order
of the bins in the list must correspond to the filter_types parameter.
Returns
A NumPy array of the filter indices
Return type
numpy.ndarray
get_nuclide_index(nuclide)
Returns the index in the Tally’s results array for a Nuclide bin
Parameters
nuclide (str) – The name of the Nuclide (e.g., ‘H1’, ‘U238’)
Returns
nuclide_index – The index in the Tally data array for this nuclide.
Return type
int
Raises
KeyError – When the argument passed to the ‘nuclide’ parameter cannot be found in the
Tally.
get_nuclide_indices(nuclides)
Get indices into the nuclide axis of this tally’s data arrays.
indices into the nuclide axis of the tally’s data array (axis=1) for one or more nuclides.

Parameters
nuclides (list of str) – A list of nuclide name strings (e.g., [‘U235’, ‘U238’]; default
is [])
Returns
A NumPy array of the nuclide indices
Return type
numpy.ndarray
get_pandas_dataframe(filters=True, nuclides=True, scores=True, derivative=True, paths=True,
float_format='{:.2e}')
Build a Pandas DataFrame for the Tally data.
This method constructs a Pandas DataFrame object for the Tally data with columns annotated by filter,
nuclide and score bin information.
This capability has been tested for Pandas >=0.13.1. However, it is recommended to use v0.16 or newer
versions of Pandas since this method uses the Multi-index Pandas feature.
Parameters
• filters (bool) – Include columns with filter bin information (default is True).
• nuclides (bool) – Include columns with nuclide bin information (default is True).
• scores (bool) – Include columns with score bin information (default is True).
• derivative (bool) – Include columns with differential tally info (default is True).
• paths (bool, optional) – Construct columns for distribcell tally filters (default is True).
The geometric information in the Summary object is embedded into a Multi-index column
with a geometric “path” to each distribcell instance.
• float_format (str) – All floats in the DataFrame will be formatted using the given for-
mat string before printing.
Returns
A Pandas DataFrame with each column annotated by filter, nuclide and score bin information
(if these parameters are True), and the mean and standard deviation of the Tally’s data.
Return type
pandas.DataFrame
Raises
KeyError – When this method is called before the Tally is populated with data
get_reshaped_data(value='mean')
Returns an array of tally data with one dimension per filter.
The tally data in OpenMC is stored as a 3D array with the dimensions corresponding to filters, nuclides
and scores. As a result, tally data can be opaque for a user to directly index (i.e., without use of openmc.
Tally.get_values()) since one must know how to properly use the number of bins and strides for each
filter to index into the first (filter) dimension.
This builds and returns a reshaped version of the tally data array with unique dimensions corresponding to
each tally filter. For example, suppose this tally has arrays of data with shape (8,5,5) corresponding to two
filters (2 and 4 bins, respectively), five nuclides and five scores. This method will return a version of the
data array with the with a new shape of (2,4,5,5) such that the first two dimensions correspond directly to
the two filters with two and four bins.

Parameters
value (str) – A string for the type of value to return - ‘mean’ (default), ‘std_dev’, ‘rel_err’,
‘sum’, or ‘sum_sq’ are accepted
Returns
The tally data array indexed by filters, nuclides and scores.
Return type
numpy.ndarray
get_score_index(score)
Returns the index in the Tally’s results array for a score bin
Parameters
score (str) – The score string (e.g., ‘absorption’, ‘nu-fission’)
Returns
score_index – The index in the Tally data array for this score.
Return type
int
Raises
ValueError – When the argument passed to the ‘score’ parameter cannot be found in the
Tally.
get_score_indices(scores)
Get indices into the score axis of this tally’s data arrays.
indices into the score axis of the tally’s data array (axis=2) for one or more scores.
Parameters
scores (list of str or openmc.CrossScore) – A list of one or more score strings
(e.g., [‘absorption’, ‘nu-fission’]; default is [])
Returns
A NumPy array of the score indices
Return type
numpy.ndarray
get_slice(scores=[], filters=[], filter_bins=[], nuclides=[], squeeze=False)
Build a sliced tally for the specified filters, scores and nuclides.
This method constructs a new tally to encapsulate a subset of the data represented by this tally. The subset
of data to include in the tally slice is determined by the scores, filters and nuclides specified in the input
parameters.
Parameters
• scores (list of str) – A list of one or more score strings (e.g., [‘absorption’, ‘nu-
fission’]
Filter, EnergyFilter])
• filter_bins (list of Iterables) – A list of iterables of filter bins corresponding to
the specified filter types (e.g., [(1,), ((0., 0.625e-6),)]). Each iterable contains bins to slice
for the corresponding filter type in the filters parameter. Each bin is the integer ID for
‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the
cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and

‘energyout’ filters corresponding to the energy boundaries of the bin of interest. The bin is
an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest. The order of
the bins in the list must correspond to the filters argument.
• nuclides (list of str) – A list of nuclide name strings (e.g., [‘U235’, ‘U238’])
• squeeze (bool) – Whether to remove filters with only a single bin in the sliced tally
Returns
A new tally which encapsulates the subset of data requested in the order each filter, nuclide
and score is listed in the parameters.
Return type
openmc.Tally
Raises
ValueError – When this method is called before the Tally is populated with data.
get_values(scores=[], filters=[], filter_bins=[], nuclides=[], value='mean')
Returns one or more tallied values given a list of scores, filters, filter bins and nuclides.
This method constructs a 3D NumPy array for the requested Tally data indexed by filter bin, nuclide bin,
and score index. The method will order the data in the array as specified in the parameter lists.
Parameters
• scores (list of str) – A list of one or more score strings (e.g., [‘absorption’, ‘nu-
fission’]; default is [])
Filter, EnergyFilter]; default is [])
• filter_bins (list of Iterables) – A list of tuples of filter bins corresponding to the
filter_types parameter (e.g., [(1,), ((0., 0.625e-6),)]; default is []). Each tuple contains bins
for the corresponding filter type in the filters parameter. Each bins is the integer ID for
‘material’, ‘surface’, ‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the
cell instance ID for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and
‘energyout’ filters corresponding to the energy boundaries of the bin of interest. The bin is
an (x,y,z) 3-tuple for ‘mesh’ filters corresponding to the mesh cell of interest. The order of
the bins in the list must correspond to the filter_types parameter.
• nuclides (list of str) – A list of nuclide name strings (e.g., [‘U235’, ‘U238’]; default
is [])
• value (str) – A string for the type of value to return - ‘mean’ (default), ‘std_dev’, ‘rel_err’,
‘sum’, or ‘sum_sq’ are accepted
Returns
A scalar or NumPy array of the Tally data indexed in the order each filter, nuclide and score
is listed in the parameters.
Return type
float or numpy.ndarray
Raises
ValueError – When this method is called before the Tally is populated with data, or the
input parameters do not correspond to the Tally’s attributes, e.g., if the score(s) do not match
those in the Tally.
hybrid_product(other, binary_op, filter_product=None, nuclide_product=None, score_product=None)
Combines filters, scores and nuclides with another tally.

This is a helper method for the tally arithmetic operator overloaded methods. It is called a “hybrid product”
because it performs a combination of tensor (or Kronecker) and entrywise (or Hadamard) products. The
filters from both tallies are combined using an entrywise (or Hadamard) product on matching filters. By
default, if all nuclides are identical in the two tallies, the entrywise product is performed across nuclides;
else the tensor product is performed. By default, if all scores are identical in the two tallies, the entrywise
product is performed across scores; else the tensor product is performed. Users can also call the method
explicitly and specify the desired product.
Parameters
• other (openmc.Tally) – The tally on the right hand side of the hybrid product
• binary_op ({'+', '-', '*', '/', '^'}) – The binary operation in the hybrid product
• filter_product ({'tensor', 'entrywise' or None}) – The type of product (tensor
or entrywise) to be performed between filter data. The default is the entrywise product.
Currently only the entrywise product is supported since a tally cannot contain two of the
same filter.
• nuclide_product ({'tensor', 'entrywise' or None}) – The type of product (tensor
or entrywise) to be performed between nuclide data. The default is the entrywise product if
all nuclides between the two tallies are the same; otherwise the default is the tensor product.
• score_product ({'tensor', 'entrywise' or None}) – The type of product (tensor or
entrywise) to be performed between score data. The default is the entrywise product if all
scores between the two tallies are the same; otherwise the default is the tensor product.
Returns
A new Tally that is the hybrid product with this one.
Return type
openmc.Tally
Raises
ValueError – When this method is called before the other tally is populated with data.
merge(other)
Merge another tally with this one
If results have been loaded from a statepoint, then tallies are only mergeable along one and only one of
filter bins, nuclides or scores.
Parameters
other (openmc.Tally) – Tally to merge with this one
Returns
merged_tally – Merged tallies
Return type
openmc.Tally
remove_filter(old_filter)
Remove a filter from the tally
Parameters
old_filter (openmc.Filter) – Filter to remove
remove_nuclide(nuclide)
Remove a nuclide from the tally
Parameters
nuclide (openmc.Nuclide) – Nuclide to remove

remove_score(score)
Remove a score from the tally
Parameters
score (str) – Score to remove
summation(scores=[], filter_type=None, filter_bins=[], nuclides=[], remove_filter=False)
Vectorized sum of tally data across scores, filter bins and/or nuclides using tally aggregation.
This method constructs a new tally to encapsulate the sum of the data represented by the summation of the
data in this tally. The tally data sum is determined by the scores, filter bins and nuclides specified in the
input parameters.
Parameters
• scores (list of str) – A list of one or more score strings to sum across (e.g., [‘absorp-
tion’, ‘nu-fission’]; default is [])
• filter_type (openmc.FilterMeta) – Type of the filter, e.g. MeshFilter
• filter_bins (Iterable of int or tuple) – A list of the filter bins corresponding
to the filter_type parameter Each bin in the list is the integer ID for ‘material’, ‘surface’,
‘cell’, ‘cellborn’, and ‘universe’ Filters. Each bin is an integer for the cell instance ID
for ‘distribcell’ Filters. Each bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters
corresponding to the energy boundaries of the bin of interest. Each bin is an (x,y,z) 3-tuple
for ‘mesh’ filters corresponding to the mesh cell of interest.
• nuclides (list of str) – A list of nuclide name strings to sum across (e.g., [‘U235’,
‘U238’]; default is [])
• remove_filter (bool) – If a filter is being summed over, this bool indicates whether to
remove that filter in the returned tally. Default is False.
Returns
A new tally which encapsulates the sum of data requested.
Return type
openmc.Tally
to_xml_element()
Return XML representation of the tally
Returns
element – XML element containing tally data
Return type
openmc.Tallies
class openmc.Tallies(tallies=None)
Collection of Tallies used for an OpenMC simulation.
This class corresponds directly to the tallies.xml input file. It can be thought of as a normal Python list where
each member is a Tally. It behaves like a list as the following example demonstrates:
>>> t1 = openmc.Tally()


>>> tallies = openmc.Tallies([t1])
>>> tallies.append(t2)
>>> tallies += [t3]
Parameters
tallies (Iterable of openmc.Tally) – Tallies to add to the collection
append(tally, merge=False)
Append tally to collection
Parameters
• tally (openmc.Tally) – Tally to append
• merge (bool) – Indicate whether the tally should be merged with an existing tally, if pos-
sible. Defaults to False.
export_to_xml(path='tallies.xml')
Create a tallies.xml file that can be used for a simulation.
Parameters
path (str) – Path to file to write. Defaults to ‘tallies.xml’.
classmethod from_xml(path='tallies.xml')
Generate tallies from XML file
Parameters
path (str, optional) – Path to tallies XML file
Returns
Tallies object
Return type
openmc.Tallies
insert(index, item)
Insert tally before index
Parameters
• item (openmc.Tally) – Tally to insert
merge_tallies()
Merge any mergeable tallies together. Note that n-way merges are possible.
6.1.6 Geometry Plotting
openmc.Plot Definition of a finite region of space to be plotted.

openmc.Plots Collection of Plots used for an OpenMC simulation.

openmc.Plot
class openmc.Plot(plot_id=None, name='')

Definition of a finite region of space to be plotted.
OpenMC is capable of generating two-dimensional slice plots and three-dimensional voxel plots. Colors that are
used in plots can be given as RGB tuples, e.g. (255, 255, 255) would be white, or by a string indicating a valid
SVG color.
Parameters
• plot_id (int) – Unique identifier for the plot
• name (str) – Name of the plot
Variables
• id (int) – Unique identifier
• name (str) – Name of the plot
• width (Iterable of float) – Width of the plot in each basis direction
• pixels (Iterable of int) – Number of pixels to use in each basis direction
• origin (tuple or list of ndarray) – Origin (center) of the plot
• filename – Path to write the plot to
• color_by ({'cell', 'material'}) – Indicate whether the plot should be colored by cell or
by material
• type ({'slice', 'voxel'}) – The type of the plot
• background (Iterable of int or str) – Color of the background
• mask_components (Iterable of openmc.Cell or openmc.Material or int) –
The cells or materials (or corresponding IDs) to mask
• mask_background (Iterable of int or str) – Color to apply to all cells/materials not
listed in mask_components
• show_overlaps (bool) – Indicate whether or not overlapping regions are shown
• overlap_color (Iterable of int or str) – Color to apply to overlapping regions
• colors (dict) – Dictionary indicating that certain cells/materials should be displayed with
a particular color. The keys can be of type Cell, Material, or int (ID for a cell/material).
• level (int) – Universe depth to plot at
• meshlines (dict) – Dictionary defining type, id, linewidth and color of a mesh to be plotted
on top of a plot
colorize(geometry, seed=1)
Generate a color scheme for each domain in the plot.
This routine may be used to generate random, reproducible color schemes. The colors generated are based
upon cell/material IDs in the geometry.
Parameters
• geometry (openmc.Geometry) – The geometry for which the plot is defined
• seed (Integral) – The random number seed used to generate the color scheme

classmethod from_geometry(geometry, basis='xy', slice_coord=0.0)

Return plot that encompasses a geometry.
Parameters
• geometry (openmc.Geometry) – The geometry to base the plot off of
• slice_coord (float) – The level at which the slice plot should be plotted. For example,
if the basis is ‘xy’, this would indicate the z value used in the origin.
Generate plot object from an XML element
Parameters
Returns
Plot object
Return type
openmc.Plot
highlight_domains(geometry, domains, seed=1, alpha=0.5, background='gray')
Use alpha compositing to highlight one or more domains in the plot.
This routine generates a color scheme and applies alpha compositing to make all domains except the high-
lighted ones appear partially transparent.
Parameters
• domains (Iterable of openmc.Cell or openmc.Material) – A collection of the
domain IDs to highlight in the plot
• seed (int) – The random number seed used to generate the color scheme
• alpha (float) – The value between 0 and 1 to apply in alpha compositing
• background (3-tuple of int or str) – The background color to apply in alpha com-
positing
to_ipython_image(openmc_exec='openmc', cwd='.')
Render plot as an image
This method runs OpenMC in plotting mode to produce a .png file.
Changed in version 0.13.0: The convert_exec argument was removed since OpenMC now produces .png
images directly.
Parameters
• openmc_exec (str) – Path to OpenMC executable
• cwd (str, optional) – Path to working directory to run in
Returns
Image generated
Return type
IPython.display.Image

to_xml_element()
Return XML representation of the plot
Returns
element – XML element containing plot data
Return type
openmc.Plots
class openmc.Plots(plots=None)
Collection of Plots used for an OpenMC simulation.
This class corresponds directly to the plots.xml input file. It can be thought of as a normal Python list where
each member is a Plot. It behaves like a list as the following example demonstrates:
>>> xz_plot = openmc.Plot()

>>> big_plot = openmc.Plot()
>>> small_plot = openmc.Plot()
>>> p = openmc.Plots((xz_plot, big_plot))
>>> p.append(small_plot)
>>> small_plot = p.pop()
Parameters
plots (Iterable of openmc.Plot) – Plots to add to the collection
append(plot)
Append plot to collection
Parameters
plot (openmc.Plot) – Plot to append
colorize(geometry, seed=1)
Generate a consistent color scheme for each domain in each plot.
This routine may be used to generate random, reproducible color schemes. The colors generated are based
upon cell/material IDs in the geometry. The color schemes will be consistent for all plots in “plots.xml”.
Parameters
• geometry (openmc.Geometry) – The geometry for which the plots are defined
• seed (Integral) – The random number seed used to generate the color scheme
export_to_xml(path='plots.xml')
Export plot specifications to an XML file.
Parameters
path (str) – Path to file to write. Defaults to ‘plots.xml’.
classmethod from_xml(path='plots.xml')
Generate plots collection from XML file
Parameters
path (str, optional) – Path to plots XML file
Returns
Plots collection

Return type
openmc.Plots
highlight_domains(geometry, domains, seed=1, alpha=0.5, background='gray')
Use alpha compositing to highlight one or more domains in the plot.
This routine generates a color scheme and applies alpha compositing to make all domains except the high-
lighted ones appear partially transparent.
Parameters
• domains (Iterable of openmc.Cell or openmc.Material) – A collection of the
domain IDs to highlight in the plot
• seed (int) – The random number seed used to generate the color scheme
• alpha (float) – The value between 0 and 1 to apply in alpha compositing
• background (3-tuple of int or str) – The background color to apply in alpha com-
positing
insert(index, plot)
Insert plot before index
Parameters
• plot (openmc.Plot) – Plot to insert
6.1.7 Running OpenMC
openmc.run Run an OpenMC simulation.

openmc.calculate_volumes Run stochastic volume calculations in OpenMC.
openmc.plot_geometry Run OpenMC in plotting mode
openmc.plot_inline Display plots inline in a Jupyter notebook.
openmc.search_for_keff Function to perform a keff search by modifying a model
parametrized by a single independent variable.
openmc.run
openmc.run(particles=None, threads=None, geometry_debug=False, restart_file=None, tracks=False,

output=True, cwd='.', openmc_exec='openmc', mpi_args=None, event_based=False)
Run an OpenMC simulation.
Parameters
• particles (int, optional) – Number of particles to simulate per generation.
• threads (int, optional) – Number of OpenMP threads. If OpenMC is compiled with
OpenMP threading enabled, the default is implementation-dependent but is usually equal to
the number of hardware threads available (or a value set by the OMP_NUM_THREADS environ-
ment variable).
• geometry_debug (bool, optional) – Turn on geometry debugging during simulation.
Defaults to False.

• restart_file (str, optional) – Path to restart file to use

• tracks (bool, optional) – Write tracks for all particles. Defaults to False.
• output (bool) – Capture OpenMC output from standard out
• cwd (str, optional) – Path to working directory to run in. Defaults to the current working
directory.
• openmc_exec (str, optional) – Path to OpenMC executable. Defaults to ‘openmc’.
• mpi_args (list of str, optional) – MPI execute command and any additional MPI
arguments to pass, e.g. [‘mpiexec’, ‘-n’, ‘8’].
• event_based (bool, optional) – Turns on event-based parallelism, instead of default
history-based
Raises
RuntimeError – If the openmc executable returns a non-zero status
openmc.calculate_volumes
openmc.calculate_volumes(threads=None, output=True, cwd='.', openmc_exec='openmc', mpi_args=None)

Run stochastic volume calculations in OpenMC.
This function runs OpenMC in stochastic volume calculation mode. To specify the parameters of a volume
calculation, one must first create a openmc.VolumeCalculation instance and assign it to openmc.Settings.
volume_calculations. For example:
>>> vol = openmc.VolumeCalculation(domains=[cell1, cell2], samples=100000)

>>> settings = openmc.Settings()
>>> settings.volume_calculations = [vol]
>>> settings.export_to_xml()
>>> openmc.calculate_volumes()
Parameters
OpenMP threading enabled, the default is implementation-dependent but is usually equal to
the number of hardware threads available (or a value set by the OMP_NUM_THREADS environ-
ment variable).
• output (bool, optional) – Capture OpenMC output from standard out
• cwd (str, optional) – Path to working directory to run in. Defaults to the current working
directory.
Raises
See also:

openmc.plot_geometry
openmc.plot_geometry(output=True, openmc_exec='openmc', cwd='.')

Run OpenMC in plotting mode
Parameters
• openmc_exec (str, optional) – Path to OpenMC executable
Raises
openmc.plot_inline
openmc.plot_inline(plots, openmc_exec='openmc', cwd='.')

Display plots inline in a Jupyter notebook.
Changed in version 0.13.0: The convert_exec argument was removed since OpenMC now produces .png images
directly.
Parameters
• plots (Iterable of openmc.Plot) – Plots to display
• openmc_exec (str) – Path to OpenMC executable
Raises
openmc.search_for_keff
openmc.search_for_keff(model_builder, initial_guess=None, target=1.0, bracket=None, model_args=None,

tol=None, bracketed_method='bisect', print_iterations=False, run_args=None,
**kwargs)
Function to perform a keff search by modifying a model parametrized by a single independent variable.
Parameters
• model_builder (collections.Callable) – Callable function which builds a model ac-
cording to a passed parameter. This function must return an openmc.model.Model object.
• initial_guess (Real, optional) – Initial guess for the parameter to be searched in
model_builder. One of guess or bracket must be provided.
• target (Real, optional) – keff value to search for, defaults to 1.0.
• bracket (None or Iterable of Real, optional) – Bracketing interval to search for
the solution; if not provided, a generic non-bracketing method is used. If provided, the brack-
ets are used. Defaults to no brackets provided. One of guess or bracket must be provided. If
both are provided, the bracket will be preferentially used.
• model_args (dict, optional) – Keyword-based arguments to pass to the model_builder
method. Defaults to no arguments.
• tol (float) – Tolerance to pass to the search method

• bracketed_method ({'brentq', 'brenth', 'ridder', 'bisect'}, optional) – Solu-

tion method to use; only applies if bracket is set, otherwise the Secant method is used. De-
faults to ‘bisect’.
• print_iterations (bool) – Whether or not to print the guess and the result during the
iteration process. Defaults to False.
• run_args (dict, optional) – Keyword arguments to pass to openmc.Model.run().
Defaults to no arguments.
• **kwargs – All remaining keyword arguments are passed to the root-finding method.
Returns
• zero_value (float) – Estimated value of the variable parameter where keff is the targeted
value
• guesses (List of Real) – List of guesses attempted by the search
• results (List of 2-tuple of Real) – List of keffs and uncertainties corresponding to the guess
attempted by the search
6.1.8 Post-processing
openmc.Particle Information used to restart a specific particle that caused

a simulation to fail.
openmc.ParticleTrack Particle track information
openmc.StatePoint State information on a simulation at a certain point in
time (at the end of a given batch).
openmc.Summary Summary of model used in a simulation.
openmc.Track Tracks resulting from a single source particle
openmc.Tracks Collection of particle tracks
openmc.Particle
class openmc.Particle(filename)
Information used to restart a specific particle that caused a simulation to fail.
Parameters
filename (str) – Path to the particle restart file
Variables
• current_batch (int) – The batch containing the particle
• generations_per_batch (int) – Number of generations per batch
• current_generation (int) – The generation containing the particle
• n_particles (int) – Number of particles per generation
• run_mode (int) – Type of simulation (criticality or fixed source)
• id (long) – Identifier of the particle
• type (int) – Particle type (1 = neutron, 2 = photon, 3 = electron, 4 = positron)
• weight (float) – Weight of the particle

• energy (float) – Energy of the particle in eV

• xyz (list of float) – Position of the particle
• uvw (list of float) – Directional cosines of the particle
openmc.ParticleTrack
class openmc.ParticleTrack(particle, states)

Particle track information
Parameters
• particle (openmc.ParticleType) – Type of the particle
• states (numpy.ndarray) – Structured array containing each state of the particle. The
structured array contains the following fields: r (position; each direction in [cm]), u
(direction), E (energy in [eV]), time (time in [s]), wgt (weight), cell_id (cell ID) ,
cell_instance (cell instance), and material_id (material ID).
particle
Alias for field number 0
states
Alias for field number 1
openmc.StatePoint
class openmc.StatePoint(filepath, autolink=True)

State information on a simulation at a certain point in time (at the end of a given batch). Statepoints can be used
to analyze tally results as well as restart a simulation.
Parameters
• filepath (str or Path ) – Path to file to load
• autolink (bool, optional) – Whether to automatically link in metadata from a sum-
mary.h5 file and stochastic volume calculation results from volume_*.h5 files. Defaults to
True.
Variables
• cmfd_on (bool) – Indicate whether CMFD is active
• cmfd_balance (numpy.ndarray) – Residual neutron balance for each batch
• cmfd_dominance – Dominance ratio for each batch
• cmfd_entropy (numpy.ndarray) – Shannon entropy of CMFD fission source for each
batch
• cmfd_indices (numpy.ndarray) – Number of CMFD mesh cells and energy groups. The
first three indices correspond to the x-, y-, and z- spatial directions and the fourth index is
the number of energy groups.
• cmfd_srccmp (numpy.ndarray) – Root-mean-square difference between OpenMC and
CMFD fission source for each batch
• cmfd_src (numpy.ndarray) – CMFD fission source distribution over all mesh cells and
energy groups.

• current_batch (int) – Number of batches simulated

• date_and_time (datetime.datetime) – Date and time at which statepoint was written
• entropy (numpy.ndarray) – Shannon entropy of fission source at each batch
• filters (dict) – Dictionary whose keys are filter IDs and whose values are Filter objects
• generations_per_batch (int) – Number of fission generations per batch
• global_tallies (numpy.ndarray of compound datatype) – Global tallies for k-
effective estimates and leakage. The compound datatype has fields ‘name’, ‘sum’, ‘sum_sq’,
‘mean’, and ‘std_dev’.
• k_combined (uncertainties.UFloat) – Combined estimator for k-effective
Deprecated since version 0.13.1.
• k_col_abs (float) – Cross-product of collision and absorption estimates of k-effective
• k_col_tra (float) – Cross-product of collision and tracklength estimates of k-effective
• k_abs_tra (float) – Cross-product of absorption and tracklength estimates of k-effective
• k_generation (numpy.ndarray) – Estimate of k-effective for each batch/generation
• keff (uncertainties.UFloat) – Combined estimator for k-effective
• meshes (dict) – Dictionary whose keys are mesh IDs and whose values are MeshBase
objects
• n_batches (int) – Number of batches
• n_inactive (int) – Number of inactive batches
• n_particles (int) – Number of particles per generation
• n_realizations (int) – Number of tally realizations
• path (str) – Working directory for simulation
• photon_transport (bool) – Indicate whether photon transport is active
• run_mode (str) – Simulation run mode, e.g. ‘eigenvalue’
• runtime (dict) – Dictionary whose keys are strings describing various runtime metrics and
whose values are time values in seconds.
• seed (int) – Pseudorandom number generator seed
• source (numpy.ndarray of compound datatype) – Array of source sites. The com-
pound datatype has fields ‘r’, ‘u’, ‘E’, ‘wgt’, ‘delayed_group’, ‘surf_id’, and ‘particle’, cor-
responding to the position, direction, energy, weight, delayed group, surface ID and particle
type of the source site, respectively.
• source_present (bool) – Indicate whether source sites are present
• sparse (bool) – Whether or not the tallies uses SciPy’s LIL sparse matrix format for com-
pressed data storage
• tallies (dict) – Dictionary whose keys are tally IDs and whose values are Tally objects
• tallies_present (bool) – Indicate whether user-defined tallies are present
• tally_derivatives (dict) – Dictionary whose keys are tally derivative IDs and whose
values are TallyDerivative objects

• version (tuple of Integral) – Version of OpenMC

• summary (None or openmc.Summary) – A summary object if the statepoint has been
linked with a summary file
Add volume information to the geometry within the file
Parameters
tion
close()
Close the statepoint HDF5 file and the corresponding summary HDF5 file if present.
get_tally(scores=[], filters=[], nuclides=[], name=None, id=None, estimator=None, exact_filters=False,
exact_nuclides=False, exact_scores=False)
Finds and returns a Tally object with certain properties.
This routine searches the list of Tallies and returns the first Tally found which satisfies all of the input
parameters.
NOTE: If any of the “exact” parameters are False (default), the input parameters do not need to match
the complete Tally specification and may only represent a subset of the Tally’s properties. If an “exact”
parameter is True then number of scores, filters, or nuclides in the parameters must precisely match those
of any matching Tally.
Parameters
• scores (list, optional) – A list of one or more score strings (default is []).
• filters (list, optional) – A list of Filter objects (default is []).
• nuclides (list, optional) – A list of Nuclide objects (default is []).
• name (str, optional) – The name specified for the Tally (default is None).
• id (Integral, optional) – The id specified for the Tally (default is None).
• estimator (str, optional) – The type of estimator (‘tracklength’, ‘analog’; default is
None).
• exact_filters (bool) – If True, the number of filters in the parameters must be identical
to those in the matching Tally. If False (default), the filters in the parameters may be a subset
of those in the matching Tally.
• exact_nuclides (bool) – If True, the number of nuclides in the parameters must be
identical to those in the matching Tally. If False (default), the nuclides in the parameters
may be a subset of those in the matching Tally.
• exact_scores (bool) – If True, the number of scores in the parameters must be identical
to those in the matching Tally. If False (default), the scores in the parameters may be a
subset of those in the matching Tally.
Returns
tally – A tally matching the specified criteria
Return type
openmc.Tally
Raises
LookupError – If a Tally meeting all of the input parameters cannot be found in the statepoint.

link_with_summary(summary)
Links Tallies and Filters with Summary model information.
This routine retrieves model information (materials, geometry) from a Summary object populated with
an HDF5 ‘summary.h5’ file and inserts it into the Tally objects. This can be helpful when viewing and
manipulating large scale Tally data. Note that it is necessary to link against a summary to populate the
Tallies with any user-specified “name” XML tags.
Parameters
summary (openmc.Summary) – A Summary object.
Raises
ValueError – An error when the argument passed to the ‘summary’ parameter is not an
openmc.Summary object.
openmc.Summary
class openmc.Summary(filename)
Summary of model used in a simulation.
Parameters
filename (str or path-like) – Path to file to load
Variables
• date_and_time (str) – Date and time when simulation began
• geometry (openmc.Geometry) – The geometry reconstructed from the summary file
• materials (openmc.Materials) – The materials reconstructed from the summary file
• nuclides (dict) – Dictionary whose keys are nuclide names and values are atomic weight
ratios.
• macroscopics (list) – Names of macroscopic data sets
• version (tuple of int) – Version of OpenMC
Add volume information to the geometry within the summary file
Parameters
tion
openmc.Track
class openmc.Track(dset)
Tracks resulting from a single source particle
This class stores information for all tracks resulting from a primary source particle and any secondary particles
that it created. The track for each primary/secondary particle is stored in the particle_tracks attribute.
Parameters
dset (h5py.Dataset) – Dataset to read track data from
Variables
• identifier (tuple) – Tuple of (batch, generation, particle number)

• particle_tracks (list) – List of tuples containing (particle type, array of track states)
• sources (list) – List of SourceParticle representing each primary/secondary particle
filter(particle=None, state_filter=None)
Filter particle tracks by given criteria
Parameters
• particle ({'neutron', 'photon', 'electron', 'positron'}) – Matching particle
type
• state_filter (function) – Function that takes a state (structured datatype) and returns
a bool depending on some criteria.
Returns
New instance with only matching openmc.ParticleTrack objects
Return type
Track
Examples
Get all particle tracks for photons:
>>> track.filter(particle='photon')
Get all particle tracks that entered cell with ID=15:
>>> track.filter(state_filter=lambda s: s['cell_id'] == 15)
Get all particle tracks in entered material with ID=2:
>>> track.filter(state_filter=lambda s: s['material_id'] == 2)
See also:
openmc.ParticleTrack
plot(axes=None)
Produce a 3D plot of particle tracks
Parameters
axes (matplotlib.axes.Axes, optional) – Axes for plot
Returns
axes – Axes for plot
Return type
matplotlib.axes.Axes

openmc.Tracks
class openmc.Tracks(filepath='tracks.h5')
Collection of particle tracks
This class behaves like a list and can be indexed using the normal subscript notation. Each element in the list is
a openmc.Track object.
Parameters
filepath (str or pathlib.Path ) – Path of file to load
static combine(track_files, path='tracks.h5')
Combine multiple track files into a single track file
Parameters
• track_files (list of path-like) – Paths to track files to combine
• path (path-like) – Path of combined track file to create
filter(particle=None, state_filter=None)
Filter tracks by given criteria
Parameters
• particle ({'neutron', 'photon', 'electron', 'positron'}) – Matching particle
type
• state_filter (function) – Function that takes a state (structured datatype) and returns
a bool depending on some criteria.
Returns
List of openmc.Track objects
Return type
Tracks
See also:
openmc.Track.filter
plot()
Produce a 3D plot of particle tracks
Returns
Axes for plot
Return type
matplotlib.axes.Axes
write_to_vtk(filename=PosixPath('tracks.vtp'))
Creates a VTP file of the tracks
Parameters
filename (path-like) – Name of the VTP file to write.
Returns
the VTK vtkPolyData object produced
Return type
vtk.vtkPolyData

The following classes and functions are used for functional expansion reconstruction.
openmc.ZernikeRadial Create radial only Zernike polynomials given coeffi-

cients and domain.
openmc.ZernikeRadial
class openmc.ZernikeRadial(coef, radius=1)

Create radial only Zernike polynomials given coefficients and domain.
The radial only Zernike polynomials are defined as in ZernikeRadialFilter.
Parameters
• coef (Iterable of float) – A list of coefficients of each term in radial only Zernike
polynomials
• radius (float) – Domain of Zernike polynomials to be applied on. Default is 1.
Variables
• order (int) – The maximum (even) order of Zernike polynomials.
• radius (float) – Domain of Zernike polynomials to be applied on. Default is 1.
• norm_coef (iterable of float) – The list of coefficients of each term in the polynomials
after normalization.
openmc.legendre_from_expcoef Return a Legendre series object based on expansion co-

efficients.
openmc.legendre_from_expcoef
openmc.legendre_from_expcoef(coef, domain=(-1, 1))

Return a Legendre series object based on expansion coefficients.
Given a list of coefficients from FET tally and a array of down, return the numpy Legendre object.
Parameters
• coef (Iterable of float) – A list of coefficients of each term in Legendre polynomials
• domain ((2,) List of float) – Domain of the Legendre polynomial
Returns
A numpy Legendre series class
Return type
numpy.polynomial.Legendre
Various classes may be created when performing tally slicing and/or arithmetic:

openmc.arithmetic.CrossScore A special-purpose tally score used to encapsulate all

combinations of two tally's scores as an outer product
for tally arithmetic.
openmc.arithmetic.CrossNuclide A special-purpose nuclide used to encapsulate all com-
binations of two tally's nuclides as an outer product for
tally arithmetic.
openmc.arithmetic.CrossFilter A special-purpose filter used to encapsulate all combi-
nations of two tally's filter bins as an outer product for
tally arithmetic.
openmc.arithmetic.AggregateScore A special-purpose tally score used to encapsulate an ag-
gregate of a subset or all of tally's scores for tally aggre-
gation.
openmc.arithmetic.AggregateNuclide A special-purpose tally nuclide used to encapsulate an
aggregate of a subset or all of tally's nuclides for tally
aggregation.
openmc.arithmetic.AggregateFilter A special-purpose tally filter used to encapsulate an ag-
gregate of a subset or all of a tally filter's bins for tally
aggregation.
openmc.arithmetic.CrossScore
class openmc.arithmetic.CrossScore(left_score, right_score, binary_op)

A special-purpose tally score used to encapsulate all combinations of two tally’s scores as an outer product for
tally arithmetic.
Parameters
• left_score (str or CrossScore) – The left score in the outer product
• right_score (str or CrossScore) – The right score in the outer product
• binary_op (str) – The tally arithmetic binary operator (e.g., ‘+’, ‘-’, etc.) used to combine
two tally’s scores with this CrossNuclide
Variables
• left_score (str or CrossScore) – The left score in the outer product
• right_score (str or CrossScore) – The right score in the outer product
two tally’s scores with this CrossScore
openmc.arithmetic.CrossNuclide
class openmc.arithmetic.CrossNuclide(left_nuclide, right_nuclide, binary_op)

A special-purpose nuclide used to encapsulate all combinations of two tally’s nuclides as an outer product for
tally arithmetic.
Parameters
• left_nuclide (openmc.Nuclide or CrossNuclide) – The left nuclide in the outer
product
• right_nuclide (openmc.Nuclide or CrossNuclide) – The right nuclide in the outer
product

two tally’s nuclides with this CrossNuclide
Variables
• left_nuclide (openmc.Nuclide or CrossNuclide) – The left nuclide in the outer
product
• right_nuclide (openmc.Nuclide or CrossNuclide) – The right nuclide in the outer
product
two tally’s nuclides with this CrossNuclide
openmc.arithmetic.CrossFilter
class openmc.arithmetic.CrossFilter(left_filter, right_filter, binary_op)

A special-purpose filter used to encapsulate all combinations of two tally’s filter bins as an outer product for tally
arithmetic.
Parameters
• left_filter (Filter or CrossFilter) – The left filter in the outer product
• right_filter (Filter or CrossFilter) – The right filter in the outer product
two tally’s filter bins with this CrossFilter
Variables
• type (str) – The type of the crossfilter (e.g., ‘energy / energy’)
• left_filter (Filter or CrossFilter) – The left filter in the outer product
• right_filter (Filter or CrossFilter) – The right filter in the outer product
two tally’s filter bins with this CrossFilter
• bins (dict of Iterable) – A dictionary of the bins from each filter keyed by the types
of the left / right filters
• num_bins (Integral) – The number of filter bins (always 1 if aggregate_filter is defined)
Returns the index in the CrossFilter for some bin.
Parameters
filter_bin (2-tuple) – A 2-tuple where each value corresponds to the bin of interest in
the left and right filter, respectively. A bin is the integer ID for ‘material’, ‘surface’, ‘cell’,
the energy boundaries of the bin of interest. The bin is a (x,y,z) 3-tuple for ‘mesh’ filters
Returns
Return type
Integral

get_pandas_dataframe(data_size, summary=None)
Builds a Pandas DataFrame for the CrossFilter’s bins.
This method constructs a Pandas DataFrame object for the CrossFilter with columns annotated by filter
bin information. This is a helper method for the Tally.get_pandas_dataframe(. . . ) method. This method
recursively builds and concatenates Pandas DataFrames for the left and right filters and crossfilters.
This capability has been tested for Pandas >=0.13.1. However, it is recommended to use v0.16 or newer
versions of Pandas since this method uses Pandas’ Multi-index functionality.
Parameters
• data_size (Integral) – The total number of bins in the tally corresponding to this filter
• summary (None or Summary) – An optional Summary object to be used to construct
columns for distribcell tally filters (default is None). The geometric information in the
Summary object is embedded into a Multi-index column with a geometric “path” to each
distribcell instance.
Returns
A Pandas DataFrame with columns of strings that characterize the crossfilter’s bins. Each
entry in the DataFrame will include one or more binary operations used to construct the
crossfilter’s bins. The number of rows in the DataFrame is the same as the total number of bins
in the corresponding tally, with the filter bins appropriately tiled to map to the corresponding
tally bins.
Return type
pandas.DataFrame
See also:
Tally.get_pandas_dataframe, Filter.get_pandas_dataframe
openmc.arithmetic.AggregateScore
class openmc.arithmetic.AggregateScore(scores=None, aggregate_op=None)

A special-purpose tally score used to encapsulate an aggregate of a subset or all of tally’s scores for tally aggre-
gation.
Parameters
• scores (Iterable of str or CrossScore) – The scores included in the aggregation
• aggregate_op (str) – The tally aggregation operator (e.g., ‘sum’, ‘avg’, etc.) used to ag-
gregate across a tally’s scores with this AggregateScore
Variables
• scores (Iterable of str or CrossScore) – The scores included in the aggregation
gregate across a tally’s scores with this AggregateScore

openmc.arithmetic.AggregateNuclide
class openmc.arithmetic.AggregateNuclide(nuclides=None, aggregate_op=None)

A special-purpose tally nuclide used to encapsulate an aggregate of a subset or all of tally’s nuclides for tally
aggregation.
Parameters
• nuclides (Iterable of str or openmc.Nuclide or CrossNuclide) – The nu-
clides included in the aggregation
gregate across a tally’s nuclides with this AggregateNuclide
Variables
• nuclides (Iterable of str or openmc.Nuclide or CrossNuclide) – The nu-
clides included in the aggregation
gregate across a tally’s nuclides with this AggregateNuclide
openmc.arithmetic.AggregateFilter
class openmc.arithmetic.AggregateFilter(aggregate_filter, bins=None, aggregate_op=None)

A special-purpose tally filter used to encapsulate an aggregate of a subset or all of a tally filter’s bins for tally
aggregation.
Parameters
• aggregate_filter (Filter or CrossFilter) – The filter included in the aggregation
• bins (Iterable of tuple) – The filter bins included in the aggregation
gregate across a tally filter’s bins with this AggregateFilter
Variables
• type (str) – The type of the aggregatefilter (e.g., ‘sum(energy)’, ‘sum(cell)’)
• aggregate_filter (filter) – The filter included in the aggregation
gregate across a tally filter’s bins with this AggregateFilter
• bins (Iterable of tuple) – The filter bins included in the aggregation
• num_bins (Integral) – The number of filter bins (always 1 if aggregate_filter is defined)
can_merge(other)
Determine if AggregateFilter can be merged with another.
Parameters
other (AggregateFilter) – Filter to compare with
Returns
Return type
bool

Returns the index in the AggregateFilter for some bin.
Parameters
filter_bin (Integral or tuple of Real) – A tuple of value(s) corresponding to the
bin of interest in the aggregated filter. The bin is the integer ID for ‘material’, ‘surface’, ‘cell’,
‘cellborn’, and ‘universe’ Filters. The bin is the integer cell instance ID for ‘distribcell’ Filters.
The bin is a 2-tuple of floats for ‘energy’ and ‘energyout’ filters corresponding to the energy
boundaries of the bin of interest. The bin is a (x,y,z) 3-tuple for ‘mesh’ filters corresponding
to the mesh cell of interest.
Returns
filter_index – The index in the Tally data array for this filter bin. For an AggregateTally the
filter bin index is always unity.
Return type
Integral
Raises
ValueError – When the filter_bin is not part of the aggregated filter’s bins
get_pandas_dataframe(data_size, stride, summary=None, **kwargs)
Builds a Pandas DataFrame for the AggregateFilter’s bins.
This method constructs a Pandas DataFrame object for the AggregateFilter with columns annotated by filter
bin information. This is a helper method for the Tally.get_pandas_dataframe(. . . ) method.
Parameters
• summary (None or Summary) – An optional Summary object to be used to construct
columns for distribcell tally filters (default is None). NOTE: This parameter is not used
by the AggregateFilter and simply mirrors the method signature for the CrossFilter.
Returns
A Pandas DataFrame with columns of strings that characterize the aggregatefilter’s bins. Each
entry in the DataFrame will include one or more aggregation operations used to construct
the aggregatefilter’s bins. The number of rows in the DataFrame is the same as the total
number of bins in the corresponding tally, with the filter bins appropriately tiled to map to the
corresponding tally bins.
Return type
pandas.DataFrame
See also:
Tally.get_pandas_dataframe, Filter.get_pandas_dataframe, CrossFilter.
get_pandas_dataframe
merge(other)
Merge this aggregatefilter with another.
Parameters
other (AggregateFilter) – Filter to merge with
Returns
merged_filter – Filter resulting from the merge

Return type
AggregateFilter
6.1.9 Coarse Mesh Finite Difference Acceleration
CMFD is implemented in OpenMC and allows users to accelerate fission source convergence during inactive neutron
batches. To use CMFD, the openmc.cmfd.CMFDRun class executes OpenMC through the C API, solving the CMFD
system between fission generations and modifying the source weights. Note that the openmc.cmfd module is not
imported by default with the openmc namespace and needs to be imported explicitly.
openmc.cmfd.CMFDMesh A structured Cartesian mesh used for CMFD accelera-

tion.
openmc.cmfd.CMFDRun Class for running CMFD acceleration through the C
API.
openmc.cmfd.CMFDMesh
class openmc.cmfd.CMFDMesh
A structured Cartesian mesh used for CMFD acceleration.
Variables
• lower_left (Iterable of float) – The lower-left corner of a regular structured mesh.
If only two coordinates are given, it is assumed that the mesh is an x-y mesh.
• upper_right (Iterable of float) – The upper-right corner of a regular structured
mesh. If only two coordinates are given, it is assumed that the mesh is an x-y mesh.
• dimension (Iterable of int) – The number of mesh cells in each direction for a regular
structured mesh.
• width (Iterable of float) – The width of mesh cells in each direction for a regular
structured mesh
• energy (Iterable of float) – Energy bins in eV, listed in ascending order (e.g. [0.0,
0.625e-1, 20.0e6]) for CMFD tallies and acceleration. If no energy bins are listed, OpenMC
automatically assumes a one energy group calculation over the entire energy range.
• albedo (Iterable of float) – Surface ratio of incoming to outgoing partial currents on
global boundary conditions. They are listed in the following order: -x +x -y +y -z +z.
• map (Iterable of int) – An optional acceleration map can be specified to overlay on the
coarse mesh spatial grid. If this option is used, a 0 is used for a non-accelerated region and
a 1 is used for an accelerated region. For a simple 4x4 coarse mesh with a 2x2 fuel lattice
surrounded by reflector, the map is:
[0, 0, 0, 0,
0, 1, 1, 0,
0, 1, 1, 0,
0, 0, 0, 0]
Therefore a 2x2 system of equations is solved rather than a 4x4. This is extremely important
to use in reflectors as neutrons will not contribute to any tallies far away from fission source
neutron regions. A 1 must be used to identify any fission source region.

• mesh_type (str) – Type of structured mesh to use. Acceptable values are: * “regular” - Use
RegularMesh to define CMFD mesh * “rectilinear” - Use RectilinearMesh to define CMFD
• grid (Iterable of Iterable of float) – Grid used to define RectilinearMesh. First
dimension must have length 3 where grid[0], grid[1], and grid[2] correspond to the x-, y-,
and z-grids respectively
openmc.cmfd.CMFDRun
class openmc.cmfd.CMFDRun
Class for running CMFD acceleration through the C API.
Variables
• tally_begin (int) – Batch number at which CMFD tallies should begin accumulating
• solver_begin (int) – Batch number at which CMFD solver should start executing
• ref_d (list of floats) – List of reference diffusion coefficients to fix CMFD parameters
to
• display (dict) – Dictionary indicating which CMFD results to output. Note that CMFD
k-effective will always be outputted. Acceptable keys are:
– ”balance” - Whether to output RMS [%] of the residual from the neutron balance equation
on CMFD tallies (bool)
– ”dominance” - Whether to output the estimated dominance ratio from the CMFD iterations
(bool)
– ”entropy” - Whether to output the entropy of the CMFD predicted fission source (bool)
– ”source” - Whether to output the RMS [%] between the OpenMC fission source and
CMFD fission source (bool)
• downscatter (bool) – Indicate whether an effective downscatter cross section should be
used when using 2-group CMFD.
• feedback (bool) – Indicate whether or not the CMFD diffusion result is used to adjust the
weight of fission source neutrons on the next OpenMC batch. Defaults to False.
• cmfd_ktol (float) – Tolerance on the eigenvalue when performing CMFD power iteration
• mesh (openmc.cmfd.CMFDMesh) – Structured mesh to be used for acceleration
• norm (float) – Normalization factor applied to the CMFD fission source distribution
• power_monitor (bool) – View convergence of power iteration during CMFD acceleration
• run_adjoint (bool) – Perform adjoint calculation on the last batch
• w_shift (float) – Optional Wielandt shift parameter for accelerating power iterations. By
default, it is very large so there is effectively no impact.
• stol (float) – Tolerance on the fission source when performing CMFD power iteration
• reset (list of int) – List of batch numbers at which CMFD tallies should be reset
• write_matrices (bool) – Write sparse matrices that are used during CMFD acceleration
(loss, production) and resultant normalized flux vector phi to file
• spectral (float) – Optional spectral radius that can be used to accelerate the convergence
of Gauss-Seidel iterations during CMFD power iteration.

• gauss_seidel_tolerance (Iterable of float) – Two parameters specifying the ab-

solute inner tolerance and the relative inner tolerance for Gauss-Seidel iterations when per-
forming CMFD.
• adjoint_type ({'physical', 'math'}) – Stores type of adjoint calculation that should be
performed. run_adjoint must be true for an adjoint calculation to be performed. Options
are:
– ”physical” - Create adjoint matrices from physical parameters of CMFD problem
– ”math” - Create adjoint matrices mathematically as the transpose of loss and production
CMFD matrices
• window_type ({'expanding', 'rolling', 'none'}) – Specifies type of tally window
scheme to use to accumulate CMFD tallies. Options are:
– ”expanding” - Have an expanding window that doubles in size to give more weight to more
recent tallies as more generations are simulated
– ”rolling” - Have a fixed window size that aggregates tallies from the same number of
previous generations tallied
– ”none” - Don’t use a windowing scheme so that all tallies from last time they were reset
are used for the CMFD algorithm.
• window_size (int) – Size of window to use for tally window scheme. Only relevant when
window_type is set to “rolling”
• indices (numpy.ndarray) – Stores spatial and group dimensions as [nx, ny, nz, ng]
• cmfd_src (numpy.ndarray) – CMFD source distribution calculated from solving CMFD
equations
• entropy (list of floats) – “Shannon entropy” from CMFD fission source, stored for
each generation that CMFD is invoked
• balance (list of floats) – RMS of neutron balance equations, stored for each genera-
tion that CMFD is invoked
• src_cmp (list of floats) – RMS deviation of OpenMC and CMFD normalized source,
stored for each generation that CMFD is invoked
• dom (list of floats) – Dominance ratio from solving CMFD matrix equations, stored
for each generation that CMFD is invoked
• k_cmfd (list of floats) – List of CMFD k-effectives, stored for each generation that
CMFD is invoked
• time_cmfd (float) – Time for entire CMFD calculation, in seconds
• time_cmfdbuild (float) – Time for building CMFD matrices, in seconds
• time_cmfdsolve (float) – Time for solving CMFD matrix equations, in seconds
• use_all_threads (bool) – Whether to use all threads allocated to OpenMC for CMFD
solver
• intracomm (mpi4py.MPI.Intracomm or None) – MPI intercommunicator for running
MPI commands
finalize()
Finalize simulation by calling openmc.lib.simulation_finalize() and print out CMFD timing infor-
mation.

init()
Initialize CMFDRun instance by setting up CMFD parameters and calling openmc.lib.
simulation_init()
iter_batches()
Iterator over batches.
This function returns a generator-iterator that allows Python code to be run between batches
when running an OpenMC simulation with CMFD. It should be used in conjunction with
:funcòpenmc.cmfd.CMFDRun.run_in_memory` to ensure proper initialization/finalization of CMFDRun
instance.
next_batch()
Run next batch for CMFDRun.
Returns
Status after running a batch (0=normal, 1=reached maximum number of batches, 2=tally trig-
gers reached)
Return type
int
run(**kwargs)
Run OpenMC with coarse mesh finite difference acceleration
This method is called by the user to run CMFD once instance variables of CMFDRun class are set
Parameters
**kwargs – All keyword arguments are passed to openmc.lib.run_in_memory().
run_in_memory(**kwargs)
Context manager for running CMFD functions with OpenMC shared library functions.
This function can be used with a ‘with’ statement to ensure the CMFDRun class is properly initial-
ized/finalized. For example:
from openmc import cmfd

cmfd_run = cmfd.CMFDRun()
with cmfd_run.run_in_memory():
do_stuff_before_simulation_start()
for _ in cmfd_run.iter_batches():
do_stuff_between_batches()
Parameters
**kwargs – All keyword arguments passed to openmc.lib.run_in_memory().
statepoint_write(filename=None)
Write all simulation parameters to statepoint
Parameters
filename (str) – Filename of statepoint
At the minimum, a CMFD mesh needs to be specified in order to run CMFD. Once the mesh and other optional
properties are set, a simulation can be run with CMFD turned on using openmc.cmfd.CMFDRun.run().

6.2 openmc.model – Model Building
6.2.1 Convenience Functions
openmc.model.borated_water Return a Material with the composition of boron dis-

solved in water.
openmc.model.cylinder_from_points Return a cylinder given points that define the axis and a
radius.
openmc.model.hexagonal_prism Create a hexagon region from six surface planes.
openmc.model.rectangular_prism Get an infinite rectangular prism from four planar sur-
faces.
openmc.model.subdivide Create regions separated by a series of surfaces.
openmc.model.pin Convenience function for building a fuel pin
openmc.model.borated_water
openmc.model.borated_water(boron_ppm, temperature=293.0, pressure=0.1013, temp_unit='K',

press_unit='MPa', density=None, **kwargs)
Return a Material with the composition of boron dissolved in water.
The water density can be determined from a temperature and pressure, or it can be set directly.
The concentration of boron has no effect on the stoichiometric ratio of H and O—they are fixed at 2-1.
Parameters
• boron_ppm (float) – The weight fraction in parts-per-million of elemental boron in the
water.
• temperature (float) – Temperature in [K] used to compute water density.
• pressure (float) – Pressure in [MPa] used to compute water density.
• temp_unit ({'K', 'C', 'F'}) – The units used for the temperature argument.
• press_unit ({'MPa', 'psi'}) – The units used for the pressure argument.
• density (float) – Water density in [g / cm^3]. If specified, this value overrides the tem-
perature and pressure arguments.
• **kwargs – All keyword arguments are passed to the created Material object.
Return type
openmc.Material
openmc.model.cylinder_from_points
openmc.model.cylinder_from_points(p1, p2, r=1.0, **kwargs)

Return a cylinder given points that define the axis and a radius.
Parameters
• p1 (3-tuples) – Points that pass through the plane, p1 will be used as (x0, y0, z0)
• p2 (3-tuples) – Points that pass through the plane, p1 will be used as (x0, y0, z0)


• kwargs (dict) – Keyword arguments passed to the Cylinder constructor
Returns
Cylinder that has an axis through the points p1 and p2, and a radius r.
Return type
Cylinder
openmc.model.hexagonal_prism
openmc.model.hexagonal_prism(edge_length=1.0, orientation='y', origin=(0.0, 0.0),

boundary_type='transmission', corner_radius=0.0)
Create a hexagon region from six surface planes.
Changed in version 0.11: This function was renamed from get_hexagonal_prism to hexagonal_prism.
Parameters
• edge_length (float) – Length of a side of the hexagon in cm
• orientation ({'x', 'y'}) – An ‘x’ orientation means that two sides of the hexagon are
parallel to the x-axis and a ‘y’ orientation means that two sides of the hexagon are parallel
to the y-axis.
• origin (Iterable of two floats) – Origin of the prism. Defaults to (0., 0.).
• boundary_type ({'transmission, 'vacuum', 'reflective', 'periodic'}) – Bound-
ary condition that defines the behavior for particles hitting the surfaces comprising the hexag-
onal prism (default is ‘transmission’).
• corner_radius (float) – Prism corner radius in units of cm. Defaults to 0.
Returns
The inside of a hexagonal prism
Return type
openmc.Region
openmc.model.rectangular_prism
openmc.model.rectangular_prism(width, height, axis='z', origin=(0.0, 0.0), boundary_type='transmission',

corner_radius=0.0)
Get an infinite rectangular prism from four planar surfaces.
Changed in version 0.11: This function was renamed from get_rectangular_prism to rectangular_prism.
Parameters
• width (float) – Prism width in units of cm. The width is aligned with the y, x, or x axes
for prisms parallel to the x, y, or z axis, respectively.
• height (float) – Prism height in units of cm. The height is aligned with the z, z, or y axes
for prisms parallel to the x, y, or z axis, respectively.
• axis ({'x', 'y', 'z'}) – Axis with which the infinite length of the prism should be aligned.
Defaults to ‘z’.
• origin (Iterable of two floats) – Origin of the prism. The two floats correspond to
(y,z), (x,z) or (x,y) for prisms parallel to the x, y or z axis, respectively. Defaults to (0., 0.).
6.2. openmc.model – Model Building 345

• boundary_type ({'transmission, 'vacuum', 'reflective', 'periodic'}) – Bound-

ary condition that defines the behavior for particles hitting the surfaces comprising the rect-
angular prism (default is ‘transmission’).
• corner_radius (float) – Prism corner radius in units of cm. Defaults to 0.
Returns
The inside of a rectangular prism
Return type
openmc.Region
openmc.model.subdivide
openmc.model.subdivide(surfaces)
Create regions separated by a series of surfaces.
This function allows regions to be constructed from a set of a surfaces that are “in order”. For example, if you
had four instances of openmc.ZPlane at z=-10, z=-5, z=5, and z=10, this function would return a list of regions
corresponding to z < -10, -10 < z < -5, -5 < z < 5, 5 < z < 10, and 10 < z. That is, for n surfaces, n+1 regions are
returned.
Parameters
surfaces (sequence of openmc.Surface) – Surfaces separating regions
Returns
Regions formed by the given surfaces
Return type
list of openmc.Region
openmc.model.pin
openmc.model.pin(surfaces, items, subdivisions=None, divide_vols=True, **kwargs)

Convenience function for building a fuel pin
Parameters
• surfaces (iterable of openmc.Cylinder) – Cylinders used to define boundaries between
items. All cylinders must be concentric and of the same orientation, e.g. all openmc.
ZCylinder
• items (iterable) – Objects to go between surfaces. These can be anything that can fill
a openmc.Cell, including openmc.Material, or other openmc.Universe objects. There
must be one more item than surfaces, which will span all space outside the final ring.
• subdivisions (None or dict of int to int) – Dictionary describing which rings to
subdivide and how many times. Keys are indexes of the annular rings to be divided. Will
construct equal area rings
• divide_vols (bool) – If this evaluates to True, then volumes of subdivided openmc.
Material instances will also be divided by the number of divisions. Otherwise the volume
of the original material will not be modified before subdivision
• kwargs – Additional key-word arguments to be passed to openmc.Universe, like
name="Fuel pin"
Returns
Universe of concentric cylinders filled with the desired items

Return type
openmc.Universe
6.2.2 Composite Surfaces
openmc.model.CylinderSector Infinite cylindrical sector composite surface.

openmc.model.IsogonalOctagon Infinite isogonal octagon composite surface
openmc.model.RectangularParallelepiped Rectangular parallelpiped composite surface
openmc.model.RightCircularCylinder Right circular cylinder composite surface
openmc.model.XConeOneSided One-sided cone parallel the x-axis
openmc.model.YConeOneSided One-sided cone parallel the y-axis
openmc.model.ZConeOneSided One-sided cone parallel the z-axis
openmc.model.CylinderSector
class openmc.model.CylinderSector(r1, r2, theta1, theta2, center=(0.0, 0.0), axis='z', **kwargs)

Infinite cylindrical sector composite surface.
A cylinder sector is composed of two cylindrical and two planar surfaces. The cylindrical surfaces are concentric,
and the planar surfaces intersect the central axis of the cylindrical surfaces.
This class acts as a proper surface, meaning that unary + and - operators applied to it will produce a half-space.
The negative side is defined to be the region inside of the cylinder sector.
Parameters
• r1 (float) – Inner radius of sector. Must be less than r2.
• r2 (float) – Outer radius of sector. Must be greater than r1.
• theta1 (float) – Clockwise-most bound of sector in degrees. Assumed to be in the coun-
terclockwise direction with respect to the first basis axis (+y, +z, or +x). Must be less than
theta2.
• theta2 (float) – Counterclockwise-most bound of sector in degrees. Assumed to be in
the counterclockwise direction with respect to the first basis axis (+y, +z, or +x). Must be
greater than theta1.
• center (iterable of float) – Coordinate for central axes of cylinders in the (y, z), (z,
x), or (x, y) basis. Defaults to (0,0).
• axis ({'x', 'y', 'z'}) – Central axis of the cylinders defining the inner and outer surfaces
of the sector. Defaults to ‘z’.
• **kwargs (dict) – Keyword arguments passed to the Cylinder and Plane constructors.
Variables
• outer_cyl (openmc.ZCylinder, openmc.YCylinder, or openmc.XCylinder) –
Outer cylinder surface.
• inner_cyl (openmc.ZCylinder, openmc.YCylinder, or openmc.XCylinder) – In-
ner cylinder surface.
• plane1 (openmc.Plane) – Plane at angle 𝜃1 relative to the first basis axis.
• plane2 (openmc.Plane) – Plane at angle 𝜃2 relative to the first basis axis.

classmethod from_theta_alpha(r1, r2, theta, alpha, center=(0.0, 0.0), axis='z', **kwargs)

Alternate constructor for CylinderSector. Returns a CylinderSector object based on a central angle
𝜃 and an angular offset 𝛼. Note that 𝜃1 = 𝛼 and 𝜃2 = 𝛼 + 𝜃.
Parameters
• r1 (float) – Inner radius of sector. Must be less than r2.
• r2 (float) – Outer radius of sector. Must be greater than r1.
• theta (float) – Central angle, 𝜃, of the sector in degrees. Must be greater that 0 and less
than 360.
• alpha (float) – Angular offset, 𝛼, of sector in degrees. The offset is in the counter-
clockwise direction with respect to the first basis axis (+y, +z, or +x). Note that negative
values translate to an offset in the clockwise direction.
• center (iterable of float) – Coordinate for central axes of cylinders in the (y, z), (z,
x), or (x, y) basis. Defaults to (0,0).
• axis ({'x', 'y', 'z'}) – Central axis of the cylinders defining the inner and outer surfaces
of the sector. Defaults to ‘z’.
• **kwargs (dict) – Keyword arguments passed to the Cylinder and Plane constructors.
Returns
CylinderSector with the given central angle at the given offset.
Return type
CylinderSector
openmc.model.IsogonalOctagon
class openmc.model.IsogonalOctagon(center, r1, r2, axis='z', **kwargs)

Infinite isogonal octagon composite surface
An isogonal octagon is composed of eight planar surfaces. The prism is parallel to the x, y, or z axis. The
remaining two axes (y and z, z and x, or x and y) serve as a basis for constructing the surfaces. Two surfaces are
parallel to the first basis axis, two surfaces are parallel to the second basis axis, and the remaining four surfaces
intersect both basis axes at 45 degree angles.
The negative side is defined to be the region inside of the octogonal prism.
Parameters
• center (iterable of float) – Coordinate for the central axis of the octagon in the (y,
z), (z, x), or (x, y) basis.
• r1 (float) – Half-width
√ of octagon across its basis axis-parallel sides in units of cm. Must
be less than 𝑟2 2.
• r2 (float) – Half-width√of octagon across its basis axis intersecting sides in units of cm.
Must be less than than 𝑟1 2.
• axis ({'x', 'y', 'z'}) – Central axis of octagon. Defaults to ‘z’
• **kwargs – Keyword arguments passed to underlying plane classes
Variables

• top (openmc.ZPlane, openmc.XPlane, or openmc.YPlane) – Top planar surface of

octagon
• bottom (openmc.ZPlane, openmc.XPlane, or openmc.YPlane) – Bottom planar sur-
face of octagon
• right (openmc.YPlane, openmc.ZPlane, or openmc.XPlane) – Right planar surface
of octagon
• left (openmc.YPlane, openmc.ZPlane, or openmc.XPlane) – Left planar surface of
octagon
• upper_right (openmc.Plane) – Upper right planar surface of octagon
• lower_right (openmc.Plane) – Lower right planar surface of octagon
• lower_left (openmc.Plane) – Lower left planar surface of octagon
• upper_left (openmc.Plane) – Upper left planar surface of octagon
openmc.model.RectangularParallelepiped
class openmc.model.RectangularParallelepiped(xmin, xmax, ymin, ymax, zmin, zmax, **kwargs)

Rectangular parallelpiped composite surface
A rectangular parallelpiped is composed of six planar surfaces. This class acts as a proper surface, meaning that
unary + and - operators applied to it will produce a half-space. The negative side is defined to be the region
inside of the rectangular parallelpiped.
Parameters
• xmin (float) – Minimum and maximum x coordinates of the parallelepiped
• xmax (float) – Minimum and maximum x coordinates of the parallelepiped
• ymin (float) – Minimum and maximum y coordinates of the parallelepiped
• ymax (float) – Minimum and maximum y coordinates of the parallelepiped
• zmin (float) – Minimum and maximum z coordinates of the parallelepiped
• zmax (float) – Minimum and maximum z coordinates of the parallelepiped
Variables
• xmax (xmin,) – Sides of the parallelepiped
• ymax (ymin,) – Sides of the parallelepiped
• zmax (zmin,) – Sides of the parallelepiped

openmc.model.RightCircularCylinder
class openmc.model.RightCircularCylinder(center_base, height, radius, axis='z', **kwargs)

Right circular cylinder composite surface
A right circular cylinder is composed of a cylinder and two planar surface perpendicular to the axis of the cylinder.
The negative side is defined to be the region inside of the right circular cylinder.
Parameters
• center_base (iterable of float) – Cartesian coordinate of the center of the base of
the cylinder
• height (float) – Height of the cylinder
• radius (float) – Radius of the cylinder
• axis ({'x', 'y', 'z'}) – Axis of the cylinder
• **kwargs – Keyword arguments passed to underlying cylinder and plane classes
Variables
• cyl (openmc.Cylinder) – Underlying cylinder surface
• bottom (openmc.Plane) – Bottom planar surface of the cylinder
• top (openmc.Plane) – Top planar surface of the cylinder
openmc.model.XConeOneSided
class openmc.model.XConeOneSided(x0=0.0, y0=0.0, z0=0.0, r2=1.0, up=True, **kwargs)

One-sided cone parallel the x-axis
A one-sided cone is composed of a normal cone surface and an “ambiguity” surface that eliminates the ambiguity
as to which region of space is included. This class acts as a proper surface, meaning that unary + and - operators
applied to it will produce a half-space. The negative side is defined to be the region inside of the cone.
Parameters
• x0 (float, optional) – x-coordinate of the apex. Defaults to 0.
• y0 (float, optional) – y-coordinate of the apex. Defaults to 0.
• z0 (float, optional) – z-coordinate of the apex. Defaults to 0.
• up (bool) – Whether to select the side of the cone that extends to infinity in the positive
direction of the coordinate axis (the positive half-space of the ambiguity plane)
Variables
• cone (openmc.XCone) – Regular two-sided cone
• plane (openmc.XPlane) – Ambiguity surface

openmc.model.YConeOneSided
class openmc.model.YConeOneSided(x0=0.0, y0=0.0, z0=0.0, r2=1.0, up=True, **kwargs)

One-sided cone parallel the y-axis
Parameters
Variables
• cone (openmc.YCone) – Regular two-sided cone
• plane (openmc.YPlane) – Ambiguity surface
openmc.model.ZConeOneSided
class openmc.model.ZConeOneSided(x0=0.0, y0=0.0, z0=0.0, r2=1.0, up=True, **kwargs)

One-sided cone parallel the z-axis
Parameters

Variables
• cone (openmc.ZCone) – Regular two-sided cone
• plane (openmc.ZPlane) – Ambiguity surface
6.2.3 TRISO Fuel Modeling
Classes
openmc.model.TRISO Tristructural-isotopic (TRISO) micro fuel particle
openmc.model.TRISO
class openmc.model.TRISO(outer_radius, fill, center=(0.0, 0.0, 0.0))

Tristructural-isotopic (TRISO) micro fuel particle
Parameters
• outer_radius (float) – Outer radius of TRISO particle
• fill (openmc.Universe) – Universe which contains all layers of the TRISO particle
• center (Iterable of float) – Cartesian coordinates of the center of the TRISO particle
in cm
Variables
• id (int) – Unique identifier for the TRISO cell
• name (str) – Name of the TRISO cell
• center (numpy.ndarray) – Cartesian coordinates of the center of the TRISO particle in
cm
• fill (openmc.Universe) – Universe that contains the TRISO layers
• region (openmc.Region) – Region of space within the TRISO particle
classify(lattice)
Determine lattice element indices which might contain the TRISO particle.
Parameters
lattice (openmc.RectLattice) – Lattice to check
Returns
(z,y,x) lattice element indices which might contain the TRISO particle.
Return type
list of tuple

Functions
openmc.model.create_triso_lattice Create a lattice containing TRISO particles for opti-

mized tracking.
openmc.model.pack_spheres Generate a random, non-overlapping configuration of
spheres within a container.
openmc.model.create_triso_lattice
openmc.model.create_triso_lattice(trisos, lower_left, pitch, shape, background)

Create a lattice containing TRISO particles for optimized tracking.
Parameters
• trisos (list of openmc.model.TRISO) – List of TRISO particles to put in lattice
• lower_left (Iterable of float) – Lower-left Cartesian coordinates of the lattice
• pitch (Iterable of float) – Pitch of the lattice elements in the x-, y-, and z-directions
• shape (Iterable of float) – Number of lattice elements in the x-, y-, and z-directions
• background (openmc.Material) – A background material that is used anywhere within
the lattice but outside a TRISO particle
Returns
lattice – A lattice containing the TRISO particles
Return type
openmc.RectLattice
openmc.model.pack_spheres
openmc.model.pack_spheres(radius, region, pf=None, num_spheres=None, initial_pf=0.3,

contraction_rate=0.001, seed=1)
Generate a random, non-overlapping configuration of spheres within a container.
Parameters
• radius (float) – Outer radius of spheres.
• region (openmc.Region) – Container in which the spheres are packed. Supported shapes
are rectangular prism, cylinder, sphere, and spherical shell.
• pf (float) – Packing fraction of the spheres. One of ‘pf’ and ‘num_spheres’ must be
specified; the other will be calculated. If both are specified, ‘pf’ takes precedence over
‘num_spheres’.
• num_spheres (int) – Number of spheres to pack in the domain. One of ‘num_spheres’ and
‘pf’ must be specified; the other will be calculated.
• initial_pf (float, optional) – Packing fraction used to initialize the configuration
of spheres in the domain. Default value is 0.3. It is not recommended to set the initial
packing fraction much higher than 0.3 as the random sequential packing algorithm becomes
prohibitively slow as it approaches its limit (~0.38).

• contraction_rate (float, optional) – Contraction rate of the outer diameter. Higher

packing fractions can be reached using a smaller contraction rate, but the algorithm will take
longer to converge.
• seed (int, optional) – RNG seed.
Returns
Cartesian coordinates of sphere centers.
Return type
numpy.ndarray
Notes
The sphere configuration is generated using a combination of random sequential packing (RSP) and close random
packing (CRP). RSP performs better than CRP for lower packing fractions (pf), but it becomes prohibitively
slow as it approaches its packing limit (~0.38). CRP can achieve higher pf of up to ~0.64 and scales better with
increasing pf.
If the desired pf is below some threshold for which RSP will be faster than CRP (‘initial_packing_fraction’), only
RSP is used. If a higher pf is required, spheres with a radius smaller than the desired final radius (and therefore
with a smaller pf) are initialized within the domain using RSP. This initial configuration of spheres is then used
as a starting point for CRP using Jodrey and Tory’s algorithm1 .
In RSP, sphere centers are placed one by one at random, and placement attempts for a sphere are made until the
sphere is not overlapping any others. This implementation of the algorithm uses a mesh over the domain to speed
up the nearest neighbor search by only searching for a sphere’s neighbors within that mesh cell.
In CRP, each sphere is assigned two diameters, an inner and an outer, which approach each other during the
simulation. The inner diameter, defined as the minimum center-to-center distance, is the true diameter of the
spheres and defines the pf. At each iteration the worst overlap between spheres based on outer diameter is
eliminated by moving the spheres apart along the line joining their centers. Iterations continue until the two
diameters converge or until the desired pf is reached.
References
6.2.4 Model Container
Classes
openmc.model.Model Model container.
openmc.model.Model
class openmc.model.Model(geometry=None, materials=None, settings=None, tallies=None, plots=None)

Model container.
This class can be used to store instances of openmc.Geometry, openmc.Materials, openmc.Settings,
openmc.Tallies, and openmc.Plots, thus making a complete model. The Model.export_to_xml()
method will export XML files for all attributes that have been set. If the Model.materials attribute is not
set, it will attempt to create a materials.xml file based on all materials appearing in the geometry.
Changed in version 0.13.0: The model information can now be loaded in to OpenMC directly via openmc.lib
1 W. S. Jodrey and E. M. Tory, “Computer simulation of close random packing of equal spheres”, Phys. Rev. A 32 (1985) 2347-2351.

Parameters
• geometry (openmc.Geometry, optional) – Geometry information
• materials (openmc.Materials, optional) – Materials information
• settings (openmc.Settings, optional) – Settings information
• tallies (openmc.Tallies, optional) – Tallies information
• plots (openmc.Plots, optional) – Plot information
Variables
• geometry (openmc.Geometry) – Geometry information
• materials (openmc.Materials) – Materials information
• settings (openmc.Settings) – Settings information
• tallies (openmc.Tallies) – Tallies information
• plots (openmc.Plots) – Plot information
calculate_volumes(threads=None, output=True, cwd='.', openmc_exec='openmc', mpi_args=None,
apply_volumes=True)
Runs an OpenMC stochastic volume calculation and, if requested, applies volumes to the model
Parameters
OpenMP threading enabled, the default is implementation-dependent but is usually equal
to the number of hardware threads available (or a value set by the OMP_NUM_THREADS en-
vironment variable). This currenty only applies to the case when not using the C API.
This only applies to the case when not using the C API.
arguments to pass, e.g. [‘mpiexec’, ‘-n’, ‘8’]. This only applies to the case when not using
the C API.
• cwd (str, optional) – Path to working directory to run in. Defaults to the current work-
ing directory.
• apply_volumes (bool, optional) – Whether apply the volume calculation results from
this calculation to the model. Defaults to applying the volumes.
deplete(timesteps, method='cecm', final_step=True, operator_kwargs=None, directory='.', output=True,
**integrator_kwargs)
Deplete model using specified timesteps/power
Changed in version 0.13.0: The final_step, operator_kwargs, directory, and output arguments were added.
Parameters
• timesteps (iterable of float) – Array of timesteps in units of [s]. Note that values
are not cumulative.
• method (str, optional) – Integration method used for depletion (e.g., ‘cecm’, ‘predic-
tor’). Defaults to ‘cecm’.

• final_step (bool, optional) – Indicate whether or not a transport solve should be run
at the end of the last timestep. Defaults to running this transport solve.
• operator_kwargs (dict) – Keyword arguments passed to the depletion operator initial-
izer (e.g., openmc.deplete.Operator())
• directory (str, optional) – Directory to write XML files to. If it doesn’t exist already,
it will be created. Defaults to the current working directory
• integrator_kwargs (dict) – Remaining keyword arguments passed to the depletion
Integrator initializer (e.g., openmc.deplete.integrator.cecm()).
export_to_xml(directory='.', remove_surfs=False)
Export model to XML files.
Parameters
• directory (str) – Directory to write XML files to. If it doesn’t exist already, it will be
created.
• remove_surfs (bool) – Whether or not to remove redundant surfaces from the geometry
when exporting.
finalize_lib()
Finalize simulation and free memory allocated for the C API
classmethod from_xml(geometry='geometry.xml', materials='materials.xml', settings='settings.xml',
tallies='tallies.xml', plots='plots.xml')
Create model from existing XML files
Parameters
• geometry (str) – Path to geometry.xml file
• materials (str) – Path to materials.xml file
• settings (str) – Path to settings.xml file
• tallies (str) – Path to tallies.xml file
• plots (str) – Path to plots.xml file
Returns
Model created from XML files
Return type
openmc.model.Model
import_properties(filename)
Import physical properties
Changed in version 0.13.0: This method now updates values as loaded in memory with the C API
Parameters
filename (str) – Path to properties HDF5 file

See also:
openmc.lib.export_properties
init_lib(threads=None, geometry_debug=False, restart_file=None, tracks=False, output=True,
event_based=None, intracomm=None)
Initializes the model in memory via the C API
Parameters
vironment variable).
Defaults to False.
• event_based (None or bool, optional) – Turns on event-based parallelism if True.
If None, the value in the Settings will be used.
• intracomm (mpi4py.MPI.Intracomm or None, optional) – MPI intracommunica-
tor
plot_geometry(output=True, cwd='.', openmc_exec='openmc')
Creates plot images as specified by the Model.plots attribute
Parameters
ing directory.
This only applies to the case when not using the C API.
rotate_cells(names_or_ids, vector)
Rotate the identified cell(s) by the specified rotation vector. The rotation is only applied to cells filled with
a universe.
Note: If applying this change to a name that is not unique, then the change will be applied to all objects
of that name.

Parameters
• names_or_ids (Iterable of str or int) – The cell names (if str) or id (if int) that
are to be translated or rotated. This parameter can include a mix of names and ids.
• vector (Iterable of float) – The rotation vector of length 3 to apply. This array
specifies the angles in degrees about the x, y, and z axes, respectively.

run(particles=None, threads=None, geometry_debug=False, restart_file=None, tracks=False, output=True,

cwd='.', openmc_exec='openmc', mpi_args=None, event_based=None)
Runs OpenMC. If the C API has been initialized, then the C API is used, otherwise, this method creates
the XML files and runs OpenMC via a system call. In both cases this method returns the path to the last
statepoint file generated.
Changed in version 0.12: Instead of returning the final k-effective value, this function now returns the path
to the final statepoint written.
Changed in version 0.13.0: This method can utilize the C API for execution
Parameters
• particles (int, optional) – Number of particles to simulate per generation.
vironment variable).
Defaults to False.
ing directory.
• event_based (None or bool, optional) – Turns on event-based parallelism if True.
If None, the value in the Settings will be used.
Returns
Path to the last statepoint written by this run (None if no statepoint was written)
Return type
Path
translate_cells(names_or_ids, vector)
Translate the identified cell(s) by the specified translation vector. The translation is only applied to cells
filled with a universe.
of that name.

Parameters
are to be translated or rotated. This parameter can include a mix of names and ids.
• vector (Iterable of float) – The translation vector of length 3 to apply. This array
specifies the x, y, and z dimensions of the translation.

update_cell_temperatures(names_or_ids, temperature)
Update the temperature of a set of cells to the given value
of that name.

Parameters
are to be updated. This parameter can include a mix of names and ids.
• temperature (float) – The temperature to apply in units of Kelvin
update_densities(names_or_ids, density, density_units='atom/b-cm')
Update the density of a given set of materials to a new value
of that name.

Parameters
• names_or_ids (Iterable of str or int) – The material names (if str) or id (if int)
that are to be updated. This parameter can include a mix of names and ids.
• density (float) – The density to apply in the units specified by density_units
• density_units ({'atom/b-cm', 'g/cm3'}, optional) – Units for density. Defaults to
‘atom/b-cm’
update_material_volumes(names_or_ids, volume)
Update the volume of a set of materials to the given value
of that name.

Parameters
• names_or_ids (Iterable of str or int) – The material names (if str) or id (if int)
that are to be updated. This parameter can include a mix of names and ids.
• volume (float) – The volume to apply in units of cm^3

6.3 openmc.examples – Example Models
6.3.1 Simple Models
openmc.examples.slab_mg Create a 1D slab model.
openmc.examples.slab_mg
openmc.examples.slab_mg(num_regions=1, mat_names=None, mgxslib_name='2g.h5')

Create a 1D slab model.
Parameters
• num_regions (int, optional) – Number of regions in the problem, each with a unique
MGXS dataset. Defaults to 1.
• mat_names (Iterable of str, optional) – List of the material names to use; defaults
to [‘mat_1’, ‘mat_2’,. . . ].
• mgxslib_name (str, optional) – MGXS Library file to use; defaults to ‘2g.h5’.
Returns
model – One-group, 1D slab model
Return type
openmc.model.Model
6.3.2 Reactor Models
openmc.examples.pwr_pin_cell Create a PWR pin-cell model.

openmc.examples.pwr_assembly Create a PWR assembly model.
openmc.examples.pwr_core Create a PWR full-core model.
openmc.examples.pwr_pin_cell
openmc.examples.pwr_pin_cell()
Create a PWR pin-cell model.
This model is a single fuel pin with 2.4 w/o enriched UO2 corresponding to a beginning-of-cycle condition and
borated water. The specifications are from the BEAVRS benchmark. Note that the number of particles/batches
is initially set very low for testing purposes.
Returns
model – A PWR pin-cell model
Return type
openmc.model.Model

openmc.examples.pwr_assembly
openmc.examples.pwr_assembly()
Create a PWR assembly model.
This model is a reflected 17x17 fuel assembly from the the BEAVRS benchmark. The fuel is 2.4 w/o enriched
UO2 corresponding to a beginning-of-cycle condition. Note that the number of particles/batches is initially set
very low for testing purposes.
Returns
model – A PWR assembly model
Return type
openmc.model.Model
openmc.examples.pwr_core
openmc.examples.pwr_core()
Create a PWR full-core model.
This model is the OECD/NEA Monte Carlo Performance benchmark which is a grossly simplified pressurized
water reactor (PWR) with 241 fuel assemblies. Note that the number of particles/batches is initially set very low
for testing purposes.
Returns
model – Full-core PWR model
Return type
openmc.model.Model
6.4 openmc.deplete – Depletion
6.4.1 Primary API
The two primary requirements to perform depletion with openmc.deplete are:

1) A transport operator
2) A time-integration scheme
The former is responsible for calculating and retaining important information required for depletion. The most com-
mon examples are reaction rates and power normalization data. The latter is responsible for projecting reaction rates
and compositions forward in calendar time across some step size ∆𝑡, and obtaining new compositions given a power
or power density. The CoupledOperator class is provided to obtain reaction rates via tallies through OpenMC’s
transport solver, and the IndependentOperator class is provided to obtain reaction rates from cross-section data.
Several classes are provided that implement different time-integration algorithms for depletion calculations, which are
described in detail in Colin Josey’s thesis, Development and analysis of high order neutron transport-depletion coupling
algorithms.
6.4. openmc.deplete – Depletion 361

PredictorIntegrator Deplete using a first-order predictor algorithm.

CECMIntegrator Deplete using the CE/CM algorithm.
CELIIntegrator Deplete using the CE/LI CFQ4 algorithm.
CF4Integrator Deplete using the CF4 algorithm.
EPCRK4Integrator Deplete using the EPC-RK4 algorithm.
LEQIIntegrator Deplete using the LE/QI CFQ4 algorithm.
SICELIIntegrator Deplete using the SI-CE/LI CFQ4 algorithm.
SILEQIIntegrator Deplete using the SI-LE/QI CFQ4 algorithm.
openmc.deplete.PredictorIntegrator
class openmc.deplete.PredictorIntegrator(operator, timesteps, power=None, power_density=None,

source_rates=None, timestep_units='s', solver='cram48')
Deplete using a first-order predictor algorithm.
Implements the first-order predictor algorithm. This algorithm is mathematically defined as:
n𝑖+1 = exp (ℎA(n𝑖 )) n𝑖
Parameters
• operator (openmc.deplete.abc.TransportOperator) – Operator to perform transport
simulations
• timesteps (iterable of float or iterable of tuple) – Array of timesteps. Note
that values are not cumulative. The units are specified by the timestep_units argument when
timesteps is an iterable of float. Alternatively, units can be specified for each step by passing
an iterable of (value, unit) tuples.
• power (float or iterable of float, optional) – Power of the reactor in [W]. A
single value indicates that the power is constant over all timesteps. An iterable indicates
potentially different power levels for each timestep. For a 2D problem, the power can be
given in [W/cm] as long as the “volume” assigned to a depletion material is actually an area
in [cm^2]. Either power, power_density, or source_rates must be specified.
• power_density (float or iterable of float, optional) – Power density of the
reactor in [W/gHM]. It is multiplied by initial heavy metal inventory to get total power if
power is not specified.
• source_rates (float or iterable of float, optional) – Source rate in [neu-
tron/sec] or neutron flux in [neutron/s-cm^2] for each interval in timesteps
• timestep_units ({'s', 'min', 'h', 'd', 'MWd/kg'}) – Units for values specified in the
timesteps argument. ‘s’ means seconds, ‘min’ means minutes, ‘h’ means hours, and
‘MWd/kg’ indicates that the values are given in burnup (MW-d of energy deposited per
kilogram of initial heavy metal).
• solver (str or callable, optional) – If a string, must be the name of the solver re-
sponsible for solving the Bateman equations. Current options are:
– cram16 - 16th order IPF CRAM
– cram48 - 48th order IPF CRAM [default]
If a function or other callable, must adhere to the requirements in solver.

Variables
simulations
• chain (openmc.deplete.Chain) – Depletion chain
• timesteps (iterable of float) – Size of each depletion interval in [s]
• source_rates (iterable of float) – Source rate in [W] or [neutron/sec] for each in-
terval in timesteps
• solver (callable) – Function that will solve the Bateman equations 𝜕𝑡 𝜕
⃗𝑛 = 𝐴𝑖⃗𝑛𝑖 with
a step size 𝑡𝑖 . Can be configured using the solver argument. User-supplied functions are
expected to have the following signature: solver(A, n0, t) -> n1 where
– A is a scipy.sparse.csr_matrix making up the depletion matrix
– n0 is a 1-D numpy.ndarray of initial compositions for a given material in atoms/cm3
– t is a float of the time step size in seconds, and
– n1 is a numpy.ndarray of compositions at the next time step. Expected to be of the same
shape as n0
__call__(conc, rates, dt, source_rate, _i=None)
Perform the integration across one time step
Parameters
• conc (numpy.ndarray) – Initial concentrations for all nuclides in [atom]
• rates (openmc.deplete.ReactionRates) – Reaction rates from operator
• dt (float) – Time in [s] for the entire depletion interval
• source_rate (float) – Power in [W] or source rate in [neutron/sec]
• _i (int or None) – Iteration index. Not used
Returns
• proc_time (float) – Time spent in CRAM routines for all materials in [s]
• conc_list (list of numpy.ndarray) – Concentrations at end of interval
• op_results (empty list) – Kept for consistency with API. No intermediate calls to operator
with predictor
__iter__()
Return pair of time step in [s] and source rate in [W] or [neutron/sec]
__len__()
Return integer number of depletion intervals
integrate(final_step=True, output=True)
Perform the entire depletion process across all steps
Parameters
at the end of the last timestep.

• output (bool, optional) – Indicate whether to display information about progress

openmc.deplete.CECMIntegrator
class openmc.deplete.CECMIntegrator(operator, timesteps, power=None, power_density=None,

Deplete using the CE/CM algorithm.
Implements the second order CE/CM predictor-corrector algorithm.
“CE/CM” stands for constant extrapolation on predictor and constant midpoint on corrector. This algorithm is
mathematically defined as:
(︂ )︂
ℎ
n𝑖+1/2 = exp A(n𝑖 ) n𝑖
2
(︀ )︀
n𝑖+1 = exp ℎA(n𝑖+1/2 ) n𝑖 .
Parameters
simulations
Variables


simulations
terval in timesteps
shape as n0
Integrate using CE/CM
Parameters
• _i (int, optional) – Current iteration count. Not used
Returns
• conc_list (list of numpy.ndarray) – Concentrations at each of the intermediate points with
the final concentration as the last element
• op_results (list of openmc.deplete.OperatorResult) – Eigenvalue and reaction rates from
transport simulations
__iter__()
__len__()
Parameters


openmc.deplete.CELIIntegrator
class openmc.deplete.CELIIntegrator(operator, timesteps, power=None, power_density=None,

Deplete using the CE/LI CFQ4 algorithm.
Implements the CE/LI Predictor-Corrector algorithm using the fourth order commutator-free integrator.
“CE/LI” stands for constant extrapolation on predictor and linear interpolation on corrector. This algorithm is
n𝑝𝑖+1 = exp (ℎA(n𝑖 )) n𝑖

(︂ )︂ (︂ )︂
ℎ 5ℎ 5ℎ ℎ
n𝑖+1 = exp A(n𝑖 ) + A(n𝑝𝑖+1 ) exp A(n𝑖 ) + A(n𝑝𝑖+1 ) n𝑖 .
12 12 12 12
Parameters
simulations
Variables


simulations
terval in timesteps
shape as n0
__call__(bos_conc, rates, dt, source_rate, _i=None)
Parameters
• bos_conc (numpy.ndarray) – Initial concentrations for all nuclides in [atom]
• _i (int, optional) – Current iteration count. Not used
Returns
intermediate transport simulation
__iter__()
__len__()
Parameters


openmc.deplete.CF4Integrator
class openmc.deplete.CF4Integrator(operator, timesteps, power=None, power_density=None,

Deplete using the CF4 algorithm.
Implements the fourth order commutator-free Lie algorithm. This algorithm is mathematically defined as:
A1 = ℎA(n𝑖 )
(︂ )︂
A1
n̂1 = exp n𝑖
2
A2 = ℎA(n̂1 )
(︂ )︂
A2
n̂2 = exp n𝑖
2
A3 = ℎA(n̂2 )
(︂ )︂
A1
n̂3 = exp − + A3 n̂1
2
A4 = ℎA(n̂3 )
(︂ )︂ (︂ )︂
A1 A2 A3 A4 A1 A2 A3 A4
n𝑖+1 = exp + + − exp − + + − n𝑖 .
4 6 6 12 12 6 6 4
Parameters
simulations

Variables
simulations
terval in timesteps
shape as n0
__call__(bos_conc, bos_rates, dt, source_rate, _i=None)
Parameters
• bos_conc (numpy.ndarray) – Initial concentrations for all nuclides in [atom]
• bos_rates (openmc.deplete.ReactionRates) – Reaction rates from operator
• _i (int, optional) – Current depletion step index. Not used
Returns
intermediate transport simulations
__iter__()

__len__()
Parameters
openmc.deplete.EPCRK4Integrator
class openmc.deplete.EPCRK4Integrator(operator, timesteps, power=None, power_density=None,

Deplete using the EPC-RK4 algorithm.
Implements an extended predictor-corrector algorithm with traditional Runge-Kutta 4 method. This algorithm
is mathematically defined as:
A1 = ℎA(n𝑖 )
(︂ )︂
A1
n̂1 = exp n𝑖
2
A2 = ℎA(n̂1 )
(︂ )︂
A2
n̂2 = exp n𝑖
2
A3 = ℎA(n̂2 )
n̂3 = exp (A3 ) n𝑖
A4 = ℎA(n̂3 )
(︂ )︂
A1 A2 A3 A4
n𝑖+1 = exp + + + n𝑖 .
6 3 3 6
Parameters
simulations


Variables
simulations
terval in timesteps
shape as n0
Parameters
• _i (int, optional) – Current depletion step index, unused.
Returns


__iter__()
__len__()
Parameters
openmc.deplete.LEQIIntegrator
class openmc.deplete.LEQIIntegrator(operator, timesteps, power=None, power_density=None,

Deplete using the LE/QI CFQ4 algorithm.
Implements the LE/QI Predictor-Corrector algorithm using the fourth order commutator-free integrator.
“LE/QI” stands for linear extrapolation on predictor and quadratic interpolation on corrector. This algorithm is
A−1 = A(n𝑖−1 )
A0 = A(n𝑖 )
−ℎ𝑖 6ℎ𝑖−1 + ℎ𝑖
F1 = A−1 + A0
12ℎ𝑖−1 12ℎ𝑖−1
−5ℎ𝑖 6ℎ𝑖−1 + 5ℎ𝑖
F2 = A−1 + A0
12ℎ𝑖−1 12ℎ𝑖−1
n𝑝𝑖+1 = exp(ℎ𝑖 F1 ) exp(ℎ𝑖 F2 )n𝑖
A1 = A(n𝑝𝑖+1 )
−ℎ2𝑖 5ℎ2 + 6ℎ𝑖 ℎ𝑖−1 + ℎ2𝑖 ℎ𝑖−1
F3 = A−1 + 𝑖−1 A0 + A1
12ℎ𝑖−1 (ℎ𝑖−1 + ℎ𝑖 ) 12ℎ𝑖−1 (ℎ𝑖−1 + ℎ𝑖 ) 12(ℎ𝑖−1 + ℎ𝑖 )
−ℎ2𝑖 ℎ2 + 2ℎ𝑖 ℎ𝑖−1 + ℎ2𝑖 5ℎ2𝑖−1 + 4ℎ𝑖 ℎ𝑖−1
F4 = A−1 + 𝑖−1 A0 + A1
12ℎ𝑖−1 (ℎ𝑖−1 + ℎ𝑖 ) 12ℎ𝑖−1 (ℎ𝑖−1 + ℎ𝑖 ) 12ℎ𝑖−1 (ℎ𝑖−1 + ℎ𝑖 )
n𝑖+1 = exp(ℎ𝑖 F4 ) exp(ℎ𝑖 F3 )n𝑖
It is initialized using the CE/LI algorithm.

Parameters
simulations


Variables
simulations
terval in timesteps
shape as n0

__call__(bos_conc, bos_rates, dt, source_rate, i)

Parameters
• i (int) – Current depletion step index
Returns
__iter__()
__len__()
Parameters
openmc.deplete.SICELIIntegrator
class openmc.deplete.SICELIIntegrator(operator, timesteps, power=None, power_density=None,

source_rates=None, timestep_units='s', n_steps=10,
solver='cram48')
Deplete using the SI-CE/LI CFQ4 algorithm.
Implements the stochastic implicit CE/LI predictor-corrector algorithm using the fourth order commutator-free
integrator.
Detailed algorithm can be found in section 3.2 in Colin Josey’s thesis.
Parameters
simulations


• n_steps (int, optional) – Number of stochastic iterations per depletion interval. Must
be greater than zero. Default : 10
Variables
simulations
• power (iterable of float) – Power of the reactor in [W] for each interval in timesteps
• n_steps (int) – Number of stochastic iterations per depletion interval
shape as n0


__call__(bos_conc, bos_rates, dt, source_rate, _i=None)
Parameters
• bos_conc (numpy.ndarray) – Initial bos_concentrations for all nuclides in [atom]
• bos_rates (openmc.deplete.ReactionRates) – Reaction rates from operator
• _i (int, optional) – Current depletion step index. Not used
Returns
• bos_conc_list (list of numpy.ndarray) – Concentrations at each of the intermediate points
with the final bos_concentration as the last element
__iter__()
__len__()
integrate(output=True)
Parameters
output (bool, optional) – Indicate whether to display information about progress
openmc.deplete.SILEQIIntegrator
class openmc.deplete.SILEQIIntegrator(operator, timesteps, power=None, power_density=None,

solver='cram48')
Deplete using the SI-LE/QI CFQ4 algorithm.
Implements the Stochastic Implicit LE/QI Predictor-Corrector algorithm using the fourth order commutator-free
integrator.
Detailed algorithm can be found in Section 3.2 in Colin Josey’s thesis.
Parameters
simulations


Variables
simulations
shape as n0
__call__(bos_conc, bos_rates, dt, source_rate, i)
Parameters

• bos_conc (list of numpy.ndarray) – Initial concentrations for all nuclides in [atom]

for all depletable materials
• bos_rates (list of openmc.deplete.ReactionRates) – Reaction rates from oper-
ator for all depletable materials
Returns
__iter__()
__len__()
Parameters
Each of these classes expects a “transport operator” to be passed. OpenMC provides the following transport operator
classes:
CoupledOperator Transport-coupled transport operator.

IndependentOperator Transport-independent transport operator that uses one-
group cross sections to calculate reaction rates.
openmc.deplete.CoupledOperator
class openmc.deplete.CoupledOperator(model, chain_file=None, prev_results=None,

diff_burnable_mats=False, normalization_mode='fission-q',
fission_q=None, dilute_initial=1000.0,
fission_yield_mode='constant', fission_yield_opts=None,
reaction_rate_mode='direct', reaction_rate_opts=None,
reduce_chain=False, reduce_chain_level=None)
Transport-coupled transport operator.
Instances of this class can be used to perform transport-coupled depletion using OpenMC’s transport solver.
Normally, a user needn’t call methods of this class directly. Instead, an instance of this class is passed to an
integrator class, such as openmc.deplete.CECMIntegrator.
Changed in version 0.13.0: The geometry and settings parameters have been replaced with a model parameter
that takes a Model object

Changed in version 0.13.1: Name changed from Operator to CoupledOperator

Parameters
• model (openmc.model.Model) – OpenMC model object
• chain_file (str, optional) – Path to the depletion chain XML file. Defaults to the file
listed under depletion_chain in OPENMC_CROSS_SECTIONS environment variable.
• prev_results (Results, optional) – Results from a previous depletion calculation. If
this argument is specified, the depletion calculation will start from the latest state in the
previous results.
• diff_burnable_mats (bool, optional) – Whether to differentiate burnable materials
with multiple instances. Volumes are divided equally from the original material volume.
• normalization_mode ({"energy-deposition", "fission-q", "source-rate"})
– Indicate how tally results should be normalized. "energy-deposition" computes the
total energy deposited in the system and uses the ratio of the power to the energy produced as
a normalization factor. "fission-q" uses the fission Q values from the depletion chain to
compute the total energy deposited. "source-rate" normalizes tallies based on the source
rate (for fixed source calculations).
• fission_q (dict, optional) – Dictionary of nuclides and their fission Q values
[eV]. If not given, values will be pulled from the chain_file. Only applicable if
"normalization_mode" == "fission-q"
• dilute_initial (float, optional) – Initial atom density [atoms/cm^3] to add for nu-
clides that are zero in initial condition to ensure they exist in the decay chain. Only done for
nuclides with reaction rates.
• fission_yield_mode ({"constant", "cutoff", "average"}) – Key indicating what
fission product yield scheme to use. The key determines what fission energy helper is used:
– ”constant”: ConstantFissionYieldHelper
– ”cutoff”: FissionYieldCutoffHelper
– ”average”: AveragedFissionYieldHelper
The documentation on these classes describe their methodology and differences. Default:
"constant"
• fission_yield_opts (dict of str to option, optional) – Optional arguments to
pass to the helper determined by fission_yield_mode. Will be passed directly on to the
helper. Passing a value of None will use the defaults for the associated helper.
• reaction_rate_mode ({"direct", "flux"}, optional) – Indicate how one-group
reaction rates should be calculated. The “direct” method tallies transmutation reaction rates
directly. The “flux” method tallies a multigroup flux spectrum and then collapses one-group
reaction rates after a transport solve (with an option to tally some reaction rates directly).
• reaction_rate_opts (dict, optional) – Keyword arguments that are passed to the re-
action rate helper class. When reaction_rate_mode is set to “flux”, energy group bound-
aries can be set using the “energies” key. See the FluxCollapseHelper class for all options.
• reduce_chain (bool, optional) – If True, use openmc.deplete.Chain.reduce() to
reduce the depletion chain up to reduce_chain_level.

• reduce_chain_level (int, optional) – Depth of the search when reducing the deple-
tion chain. Only used if reduce_chain evaluates to true. The default value of None implies
no limit on the depth.
Variables
• model (openmc.model.Model) – OpenMC model object
• geometry (openmc.Geometry) – OpenMC geometry object
• settings (openmc.Settings) – OpenMC settings object
• dilute_initial (float) – Initial atom density [atoms/cm^3] to add for nuclides that are
zero in initial condition to ensure they exist in the decay chain. Only done for nuclides with
reaction rates.
• output_dir (pathlib.Path ) – Path to output directory to save results.
• round_number (bool) – Whether or not to round output to OpenMC to 8 digits. Useful in
testing, as OpenMC is incredibly sensitive to exact values.
• number (openmc.deplete.AtomNumber) – Total number of atoms in simulation.
• nuclides_with_data (set of str) – A set listing all unique nuclides available from
cross_sections.xml.
• chain (openmc.deplete.Chain) – The depletion chain information necessary to form ma-
trices and tallies.
• reaction_rates (openmc.deplete.ReactionRates) – Reaction rates from the last op-
erator step.
• burnable_mats (list of str) – All burnable material IDs
• heavy_metal (float) – Initial heavy metal inventory [g]
• local_mats (list of str) – All burnable material IDs being managed by a single process
• prev_res (Results or None) – Results from a previous depletion calculation. None if no
results are to be used.
• cleanup_when_done (bool) – Whether to finalize and clear the shared library memory
when the depletion operation is complete. Defaults to clearing the library.
__call__(vec, source_rate)
Runs a simulation.
Simulation will abort under the following circumstances:
1) No energy is computed using OpenMC tallies.
Parameters
• vec (list of numpy.ndarray) – Total atoms to be used in function.
Returns
Eigenvalue and reaction rates resulting from transport operator
Return type
openmc.deplete.OperatorResult

finalize()
Finalize a depletion simulation and release resources.
initial_condition()
Performs final setup and returns initial condition.
Returns
Total density for initial conditions.
Return type
list of numpy.ndarray
static write_bos_data(step)
Write a state-point file with beginning of step data
Parameters
step (int) – Current depletion step including restarts
openmc.deplete.IndependentOperator
class openmc.deplete.IndependentOperator(materials, micro_xs, chain_file, keff=None,

normalization_mode='fission-q', fission_q=None,
dilute_initial=1000.0, prev_results=None,
reduce_chain=False, reduce_chain_level=None,
fission_yield_opts=None)
Transport-independent transport operator that uses one-group cross sections to calculate reaction rates.
Instances of this class can be used to perform depletion using one-group cross sections and constant flux or
constant power. Normally, a user needn’t call methods of this class directly. Instead, an instance of this class is
passed to an integrator class, such as openmc.deplete.CECMIntegrator.
Parameters
• materials (openmc.Materials) – Materials to deplete.
• micro_xs (MicroXS) – One-group microscopic cross sections in [b] .
• chain_file (str) – Path to the depletion chain XML file.
• keff (2-tuple of float, optional) – keff eigenvalue and uncertainty from transport
calculation. Default is None.
• prev_results (Results, optional) – Results from a previous depletion calculation.
• normalization_mode ({"fission-q", "source-rate"}) – Indicate how reaction rates
should be calculated. "fission-q" uses the fission Q values from the depletion chain to
compute the flux based on the power. "source-rate" uses a the source rate (assumed to
be neutron flux) to calculate the reaction rates.
• fission_q (dict, optional) – Dictionary of nuclides and their fission Q values
[eV]. If not given, values will be pulled from the chain_file. Only applicable if
"normalization_mode" == "fission-q".

• fission_yield_opts (dict of str to option, optional) – Optional arguments to
pass to the openmc.deplete.helpers.FissionYieldHelper object. Will be passed di-
rectly on to the helper. Passing a value of None will use the defaults for the associated helper.
Variables
• materials (openmc.Materials) – All materials present in the model
• cross_sections (MicroXS) – Object containing one-group cross-sections in [cm^2].
reaction rates.
cross_sections.xml.
trices and tallies.
erator step.
__call__(vec, source_rate)
Obtain the reaction rates
Parameters
• source_rate (float) – Power in [W] or flux in [neutron/cm^2-s]
Returns
Return type
classmethod from_nuclides(volume, nuclides, micro_xs, chain_file, nuc_units='atom/b-cm', keff=None,
normalization_mode='fission-q', fission_q=None, dilute_initial=1000.0,
prev_results=None, reduce_chain=False, reduce_chain_level=None,
fission_yield_opts=None)
Alternate constructor from a dictionary of nuclide concentrations

volume
[float] Volume of the material being depleted in [cm^3]
nuclides
[dict of str to float] Dictionary with nuclide names as keys and nuclide concentrations as values.
micro_xs
[MicroXS] One-group microscopic cross sections.
chain_file
[str] Path to the depletion chain XML file.
nuc_units
[{‘atom/cm3’, ‘atom/b-cm’}] Units for nuclide concentration.
keff
[2-tuple of float, optional] keff eigenvalue and uncertainty from transport calculation. Default is None.
normalization_mode
[{“fission-q”, “source-rate”}] Indicate how reaction rates should be calculated. "fission-q" uses the
fission Q values from the depletion chain to compute the flux based on the power. "source-rate"
uses the source rate (assumed to be neutron flux) to calculate the reaction rates.
fission_q
[dict, optional] Dictionary of nuclides and their fission Q values [eV]. If not given, values will be pulled
from the chain_file. Only applicable if "normalization_mode" == "fission-q".
dilute_initial
[float] Initial atom density [atoms/cm^3] to add for nuclides that are zero in initial condition to ensure
they exist in the decay chain. Only done for nuclides with reaction rates.
prev_results
[Results, optional] Results from a previous depletion calculation.
reduce_chain
[bool, optional] If True, use openmc.deplete.Chain.reduce() to reduce the depletion chain up to
reduce_chain_level. Default is False.
reduce_chain_level
[int, optional] Depth of the search when reducing the depletion chain. Only used if reduce_chain
evaluates to true. The default value of None implies no limit on the depth.
fission_yield_opts
[dict of str to option, optional] Optional arguments to pass to the openmc.deplete.helpers.
FissionYieldHelper class. Will be passed directly on to the helper. Passing a value of None will
use the defaults for the associated helper.
initial_condition()
Returns
Return type
The CoupledOperator and IndependentOperator classes must also have some knowledge of how nuclides trans-
mute and decay. This is handled by the Chain class.

6.4.2 Minimal Example
A minimal example for performing depletion would be:
>>> import openmc

>>> import openmc.deplete
>>> geometry = openmc.Geometry.from_xml()
>>> settings = openmc.Settings.from_xml()
>>> model = openmc.model.Model(geometry, settings)
# Representation of a depletion chain

>>> chain_file = "chain_casl.xml"
>>> operator = openmc.deplete.CoupledOperator(
... model, chain_file)
# Set up 5 time steps of one day each

>>> dt = [24 * 60 * 60] * 5
>>> power = 1e6 # constant power of 1 MW
# Deplete using mid-point predictor-corrector

>>> cecm = openmc.deplete.CECMIntegrator(
... operator, dt, power)
>>> cecm.integrate()
6.4.3 Internal Classes and Functions
When running in parallel using mpi4py, the MPI intercommunicator used can be changed by modifying the following
module variable. If it is not explicitly modified, it defaults to mpi4py.MPI.COMM_WORLD.
openmc.deplete.comm
MPI intercommunicator used to call OpenMC library
Type
mpi4py.MPI.Comm
During a depletion calculation, the depletion chain, reaction rates, and number densities are managed through a series
of internal classes that are not normally visible to a user. However, should you find yourself wondering about these
classes (e.g., if you want to know what decay modes or reactions are present in a depletion chain), they are documented
here. The following classes store data for a depletion chain:
Chain Full representation of a depletion chain.

DecayTuple Decay mode information
Nuclide Decay modes, reactions, and fission yields for a single
nuclide.
ReactionTuple Transmutation reaction information
FissionYieldDistribution Energy-dependent fission product yields for a single nu-
clide
FissionYield Mapping for fission yields of a parent at a specific energy

openmc.deplete.Chain
class openmc.deplete.Chain
Full representation of a depletion chain.
A depletion chain can be created by using the from_endf() method which requires a list of ENDF incident
neutron, decay, and neutron fission product yield sublibrary files. The depletion chain used during a depletion
simulation is indicated by either an argument to openmc.deplete.CoupledOperator or openmc.deplete.
IndependentOperator, or through the depletion_chain item in the OPENMC_CROSS_SECTIONS environ-
ment variable.
Variables
• nuclides (list of openmc.deplete.Nuclide) – Nuclides present in the chain.
• reactions (list of str) – Reactions that are tracked in the depletion chain
• nuclide_dict (OrderedDict of str to int) – Maps a nuclide name to an index in
nuclides.
• fission_yields (None or iterable of dict) – List of effective fission yields for ma-
terials. Each dictionary should be of the form {parent: {product: yield}} with
types {str: {str: float}}, where yield is the fission product yield for isotope
parent producing isotope product. A single entry indicates yields are constant across
all materials. Otherwise, an entry can be added for each material to be burned. Ordering
should be identical to how the operator orders reaction rates for burnable materials.
add_nuclide(nuclide)
Add a nuclide to the depletion chain
Parameters
nuclide (openmc.deplete.Nuclide) – Nuclide to add
export_to_xml(filename)
Writes a depletion chain XML file.
Parameters
filename (str) – The path to the depletion chain XML file.
form_matrix(rates, fission_yields=None)
Forms depletion matrix.
Parameters
• rates (numpy.ndarray) – 2D array indexed by (nuclide, reaction)
• fission_yields (dict, optional) – Option to use a custom set of fission yields.
Expected to be of the form {parent : {product : f_yield}} with string nuclide
names for parent and product, and f_yield as the respective fission yield
Returns
Sparse matrix representing depletion.
Return type
scipy.sparse.csr_matrix
See also:
get_default_fission_yields()

classmethod from_endf(decay_files, fpy_files, neutron_files, reactions=('(n,2n)', '(n,3n)', '(n,4n)',

'(n,gamma)', '(n,p)', '(n,a)'), progress=True)
Create a depletion chain from ENDF files.
String arguments in decay_files, fpy_files, and neutron_files will be treated as file names to be
read. Alternatively, openmc.data.endf.Evaluation instances can be included in these arguments.
Parameters
• decay_files (list of str or openmc.data.endf.Evaluation) – List of ENDF
decay sub-library files
• fpy_files (list of str or openmc.data.endf.Evaluation) – List of ENDF
neutron-induced fission product yield sub-library files
• neutron_files (list of str or openmc.data.endf.Evaluation) – List of
ENDF neutron reaction sub-library files
• reactions (iterable of str, optional) – Transmutation reactions to include in the
depletion chain, e.g., [“(n,2n)”, “(n,gamma)”]. Note that fission is always included if it is
present. A complete listing of transmutation reactions can be found in openmc.deplete.
chain.REACTIONS.
• progress (bool, optional) – Flag to print status messages during processing. Does
not effect warning messages
Return type
Chain
Notes
When an actinide is missing fission product yield (FPY) data, yields will copied from a parent isotope,
found according to:
1. If the nuclide is in a ground state and a metastable state exists with fission yields, copy the yields from
the metastable
2. Find an isotone (same number of neutrons) and copy those yields
3. Copy the yields of U235 if the previous two checks fail
classmethod from_xml(filename, fission_q=None)
Reads a depletion chain XML file.
Parameters
• filename (str) – The path to the depletion chain XML file.
• fission_q (dict, optional) – Dictionary of nuclides and their fission Q values [eV].
If not given, values will be pulled from filename
get_branch_ratios(reaction='(n,gamma)')
Return a dictionary with reaction branching ratios
Parameters
reaction (str, optional) – Reaction name like "(n,gamma)" [default], or "(n,
alpha)".

Returns
branches – nested dict of parent nuclide keys with reaction targets and branching ratios.
Consider the capture, "(n,gamma)", reaction for Am241:
{"Am241": {"Am242": 0.91, "Am242_m1": 0.09}}
Return type
dict
See also:
set_branch_ratios()
get_default_fission_yields()
Return fission yields at lowest incident neutron energy
Used as the default set of fission yields for form_matrix() if fission_yields are not provided
Returns
fission_yields – Dictionary of {parent: {product: f_yield}} where parent and
product are both string names of nuclides with yield data and f_yield is a float for the
fission yield.
Return type
dict
reduce(initial_isotopes, level=None)
Reduce the size of the chain by following transmutation paths
As an example, consider a simple chain with the following isotopes and transmutation paths:
U235 (n,gamma) U236

(n,fission) (Xe135, I135, Cs135)
I135 (beta decay) Xe135 (beta decay) Cs135
Xe135 (n,gamma) Xe136
Calling chain.reduce(["I135"]) will produce a depletion chain that contains only isotopes that would
originate from I135: I135, Xe135, Cs135, and Xe136. U235 and U236 will not be included, but multiple
isotopes can be used to start the search.
The level value controls the depth of the search. chain.reduce(["U235"], level=1) would return a
chain with all isotopes except Xe136, since it is two transmutations removed from U235 in this case.
While targets will not be included in the new chain, the total destruction rate and decay rate of included
isotopes will be preserved.
Parameters
• initial_isotopes (iterable of str) – Start the search based on the contents of these
isotopes
• level (int, optional) – Depth of transmuation path to follow. Must be greater than
or equal to zero. A value of zero returns a chain with initial_isotopes. The default
value of None implies that all isotopes that appear in the transmutation paths of the initial
isotopes and their progeny should be explored
Returns
Depletion chain containing isotopes that would appear after following up to level reactions
and decay paths

Return type
Chain
set_branch_ratios(branch_ratios, reaction='(n,gamma)', strict=True, tolerance=1e-05)
Set the branching ratios for a given reactions
Parameters
• branch_ratios (dict of {str: {str: float}}) – Capture branching ratios to be
inserted. First layer keys are names of parent nuclides, e.g. "Am241". The branching ratios
for these parents will be modified. Corresponding values are dictionaries of {target:
branching_ratio}
• reaction (str, optional) – Reaction name like "(n,gamma)" [default], or "(n,
alpha)".
• strict (bool, optional) – Error control. If this evalutes to True, then errors will be
raised if inconsistencies are found. Otherwise, warnings will be raised for most issues.
• tolerance (float, optional) – Tolerance on the sum of all branching ratios for a single
parent. Will be checked with:
1 - tol < sum_br < 1 + tol
Raises
• IndexError – If no isotopes were found on the chain that have the requested reaction
• KeyError – If strict evaluates to False and a parent isotope in branch_ratios does
not exist on the chain
• AttributeError – If strict evaluates to False and a parent isotope in branch_ratios
does not have the requested reaction
• ValueError – If strict evalutes to False and the sum of one parents branch ratios is
outside 1 +/- tolerance
See also:
get_branch_ratios()
validate(strict=True, quiet=False, tolerance=0.0001)
Search for possible inconsistencies
The following checks are performed for all nuclides present:
1) For all non-fission reactions, does the sum of branching ratios equal about one?
2) For fission reactions, does the sum of fission yield fractions equal about two?
Parameters
• strict (bool, optional) – Raise exceptions at the first inconsistency if true. Otherwise
mark a warning
• quiet (bool, optional) – Flag to suppress warnings and return immediately at the first
inconsistency. Used only if strict does not evaluate to True.
• tolerance (float, optional) – Absolute tolerance for comparisons. Used to compare
computed value x to intended value y as:
valid = (y - tolerance <= x <= y + tolerance)

Returns
valid – True if no inconsistencies were found
Return type
bool
Raises
ValueError – If strict evaluates to True and an inconistency was found
See also:
openmc.deplete.Nuclide.validate
openmc.deplete.DecayTuple
class openmc.deplete.DecayTuple(type, target, branching_ratio)

Decay mode information
Parameters
• type (str) – Type of the decay mode, e.g., ‘beta-’
• target (str or None) – Nuclide resulting from decay. A value of None implies the target
does not exist in the currently configured depletion chain
• branching_ratio (float) – Branching ratio of the decay mode
openmc.deplete.Nuclide
class openmc.deplete.Nuclide(name=None)
Decay modes, reactions, and fission yields for a single nuclide.
Parameters
name (str, optional) – GND name of this nuclide, e.g. "He4", "Am242_m1"
Variables
• name (str or None) – Name of nuclide.
• half_life (float or None) – Half life of nuclide in [s].
• decay_energy (float) – Energy deposited from decay in [eV].
• n_decay_modes (int) – Number of decay pathways.
• decay_modes (list of openmc.deplete.DecayTuple) – Decay mode information.
Each element of the list is a named tuple with attributes ‘type’, ‘target’, and ‘branching_ratio’.
• n_reaction_paths (int) – Number of possible reaction pathways.
• reactions (list of openmc.deplete.ReactionTuple) – Reaction information. Each
element of the list is a named tuple with attribute ‘type’, ‘target’, ‘Q’, and ‘branching_ratio’.
• yield_data (FissionYieldDistribution or None) – Fission product yields at tabu-
lated energies for this nuclide. Can be treated as a nested dictionary {energy: {product:
yield}}
• yield_energies (tuple of float or None) – Energies at which fission product yields
exist

add_decay_mode(type, target, branching_ratio)

Add decay mode to the nuclide
Parameters
• type (str) – Type of the decay mode, e.g., ‘beta-’
• target (str or None) – Nuclide resulting from decay. A value of None implies the
target does not exist in the currently configured depletion chain
• branching_ratio (float) – Branching ratio of the decay mode
add_reaction(type, target, Q, branching_ratio)
Add transmutation reaction to the nuclide
Parameters
• type (str) – Type of the reaction, e.g., ‘fission’
• target (str or None) – Nuclide resulting from reaction. A value of None implies either
no single target, e.g. from fission, or that the target nuclide is not considered in the current
depletion chain
• Q (float) – Q value of the reaction in [eV]
• branching_ratio (float) – Branching ratio of the reaction
classmethod from_xml(element, root=None, fission_q=None)
Read nuclide from an XML element.
Parameters
• element (xml.etree.ElementTree.Element) – XML element to read nuclide data
from
• root (xml.etree.ElementTree.Element, optional) – Root XML element for chain
file (only used when fission product yields are borrowed from another parent)
• fission_q (None or float) – User-supplied fission Q value [eV]. Will be read from the
element if not given
Returns
nuc – Instance of a nuclide
Return type
openmc.deplete.Nuclide
to_xml_element()
Write nuclide to XML element.
Returns
elem – XML element to write nuclide data to
Return type
validate(strict=True, quiet=False, tolerance=0.0001)
Search for possible inconsistencies
The following checks are performed:
1) for all non-fission reactions and decay modes, does the sum of branching ratios equal about one?
2) for fission reactions, does the sum of fission yield fractions equal about two?

Parameters
• strict (bool, optional) – Raise exceptions at the first inconsistency if true. Otherwise
mark a warning
• quiet (bool, optional) – Flag to suppress warnings and return immediately at the first
inconsistency. Used only if strict does not evaluate to True.
• tolerance (float, optional) – Absolute tolerance for comparisons. Used to compare
computed value x to intended value y as:
valid = (y - tolerance <= x <= y + tolerance)
Returns
valid – True if no inconsistencies were found
Return type
bool
Raises
ValueError – If strict evaluates to True and an inconistency was found
See also:
openmc.deplete.Chain.validate
openmc.deplete.ReactionTuple
class openmc.deplete.ReactionTuple(type, target, Q, branching_ratio)

Transmutation reaction information
Parameters
• type (str) – Type of the reaction, e.g., ‘fission’
• target (str or None) – Nuclide resulting from reaction. A value of None implies either
no single target, e.g. from fission, or that the target nuclide is not considered in the current
depletion chain
• Q (float) – Q value of the reaction in [eV]
• branching_ratio (float) – Branching ratio of the reaction
openmc.deplete.FissionYieldDistribution
class openmc.deplete.FissionYieldDistribution(fission_yields)
Energy-dependent fission product yields for a single nuclide
Can be used as a dictionary mapping energies and products to fission yields:
>>> fydist = FissionYieldDistribution(

... {0.0253: {"Xe135": 0.021}})
>>> fydist[0.0253]["Xe135"]
0.021
Parameters
fission_yields (dict) – Dictionary of energies and fission product yields for that energy.
Expected to be of the form {float: {str: float}}. The first float is the energy, typically

in eV, that represents this distribution. The underlying dictionary maps fission products to their
respective yields.
Variables
• energies (tuple) – Energies for which fission yields exist. Sorted by increasing energy
• products (tuple) – Fission products produced at all energies. Sorted by name.
• yield_matrix (numpy.ndarray) – Array (n_energy, n_products) where
yield_matrix[g, j] is the fission yield of product j for energy group g.
See also:
• from_xml_element() - Construction methods

• FissionYield - Class used for storing yields at a given energy
classmethod from_xml_element(element)
Construct a distribution from a depletion chain xml file
Parameters
element (xml.etree.ElementTree.Element) – XML element to pull fission yield data
from
Return type
FissionYieldDistribution
restrict_products(possible_products)
Return a new distribution with select products
Parameters
possible_products (iterable of str) – Candidate pool of fission products. Existing
products not contained here will not exist in the new instance
Returns
A value of None indicates no values in possible_products exist in products
Return type
FissionYieldDistribution or None
to_xml_element(root)
Write fission yield data to an xml element
Parameters
root (xml.etree.ElementTree.Element) – Element to write distribution data to
openmc.deplete.FissionYield
class openmc.deplete.FissionYield(products, yields)

Mapping for fission yields of a parent at a specific energy
Separated to support nested dictionary-like behavior for FissionYieldDistribution, and allowing math op-
erations on a single vector of yields. Can in turn be used like a dictionary to fetch fission yields. Supports
multiplication of a scalar to scale the fission yields and addition of another set of yields.
Does not support resizing / inserting new products that do not exist.
Parameters

• products (tuple of str) – Sorted products for this specific distribution

• yields (numpy.ndarray) – Fission product yields for each product in products
Variables
• products (tuple of str) – Products for this specific distribution
• yields (numpy.ndarray) – Fission product yields for each product in products
Examples
>>> import numpy

>>> fy_vector = FissionYield(
... ("I129", "Sm149", "Xe135"),
... numpy.array((0.001, 0.0003, 0.002)))
>>> fy_vector["Xe135"]
0.002
>>> new = FissionYield(fy_vector.products, fy_vector.yields.copy())
>>> fy_vector *= 2
>>> fy_vector["Xe135"]
0.004
>>> new["Xe135"]
0.002
>>> (new + fy_vector)["Sm149"]
0.0009
>>> dict(new) == {"Xe135": 0.002, "I129": 0.001, "Sm149": 0.0003}
True
items()
Return pairs of product, yield
The Chain class uses information from the following module variable:
chain.REACTIONS
Dictionary that maps transmutation reaction names to information needed when a chain is being generated: MT
values, the change in atomic/mass numbers resulting from the reaction, and what secondaries are produced.
Type
dict
The following classes are used during a depletion simulation and store auxiliary data, such as number densities and
reaction rates for each material.
AtomNumber Stores local material compositions (atoms of each nu-

clide).
MicroXS Microscopic cross section data for use in transport-
independent depletion.
OperatorResult Result of applying transport operator
ReactionRates Reaction rates resulting from a transport operator call
Results Results from a depletion simulation
StepResult Result of a single depletion timestep

openmc.deplete.AtomNumber
class openmc.deplete.AtomNumber(local_mats, nuclides, volume, n_nuc_burn)

Stores local material compositions (atoms of each nuclide).
Parameters
• local_mats (list of str) – Material IDs
• nuclides (list of str) – Nuclides to be tracked
• volume (dict) – Volume of each material in [cm^3]
• n_nuc_burn (int) – Number of nuclides to be burned.
Variables
• index_mat (dict) – A dictionary mapping material ID as string to index.
• index_nuc (dict) – A dictionary mapping nuclide name to index.
• volume (numpy.ndarray) – Volume of each material in [cm^3]. If a volume is not found,
it defaults to 1 so that reading density still works correctly.
• number (numpy.ndarray) – Array storing total atoms for each material/nuclide
• materials (list of str) – Material IDs as strings
• nuclides (list of str) – All nuclide names
• burnable_nuclides (list of str) – Burnable nuclides names. Used for sorting the
simulation.
• n_nuc_burn (int) – Number of burnable nuclides.
• n_nuc (int) – Number of nuclides.
get_atom_densities(mat, units='atom/b-cm')
Return atom densities for a given material
Parameters
• mat (str, int, openmc.Material or slice) – Material index.
• units ({"atom/b-cm", "atom/cm3"}, optional) – Units for the returned concentra-
tion. Default is "atom/b-cm"
Returns
Dictionary mapping nuclides to atom densities
Return type
dict
get_atom_density(mat, nuc)
Return atom density of given material and nuclide
Parameters
• nuc (str, int or slice) – Nuclide index.
Returns
Density in [atom/cm^3]

Return type
numpy.ndarray
get_mat_slice(mat)
Gets atom quantity indexed by mats for all burned nuclides
Parameters
mat (str, int, openmc.Material or slice) – Material index.
Returns
The slice requested in [atom].
Return type
numpy.ndarray
get_mat_volume(mat)
Return material volume
Parameters
mat (str, int, openmc.Material, or slice) – Material index.
Returns
Material volume in [cm^3]
Return type
float
set_atom_density(mat, nuc, val)
Sets atom density instead of total number.
Parameters
• nuc (str, int or slice) – Nuclide index.
• val (numpy.ndarray) – Array of densities to set in [atom/cm^3]
set_density(total_density)
Sets density.
Sets the density in the exact same order as total_density_list outputs, allowing for internal consistency
Parameters
total_density (list of numpy.ndarray) – Total atoms.
set_mat_slice(mat, val)
Sets atom quantity indexed by mats for all burned nuclides
Parameters
• mat (str, int, openmc.Material, or slice) – Material index.
• val (numpy.ndarray) – The slice to set in [atom]

openmc.deplete.MicroXS
class openmc.deplete.MicroXS(data=None, index: Optional[Collection[Any]] = None, columns:

Optional[Collection[Any]] = None, dtype: Optional[Union[ExtensionDtype,
str, dtype, Type[Union[str, float, int, complex, bool, object]]]] = None, copy:
Optional[bool] = None)
Microscopic cross section data for use in transport-independent depletion.
classmethod from_array(nuclides, reactions, data)
Creates a MicroXS object from arrays.
Parameters
• nuclides (list of str) – List of nuclide symbols for that have data for at least one
reaction.
• reactions (list of str) – List of reactions. All reactions must match those in
openmc.deplete.chain.REACTIONS
• data (ndarray of floats) – Array containing one-group microscopic cross section val-
ues for each nuclide and reaction. Cross section values are assumed to be in [b].
Return type
MicroXS
classmethod from_csv(csv_file, **kwargs)
Load a MicroXS object from a .csv file.
Parameters
• csv_file (str) – Relative path to csv-file containing microscopic cross section data.
Cross section values are assumed to be in [b]
• **kwargs (dict) – Keyword arguments to pass to pandas.read_csv().
Return type
MicroXS
classmethod from_model(model, reaction_domain, chain_file, dilute_initial=1000.0, energy_bounds=(0,
20000000.0), run_kwargs=None)
Generate a one-group cross-section dataframe using OpenMC. Note that the openmc executable must be
compiled.
Parameters
• model (openmc.Model) – OpenMC model object. Must contain geometry, materials, and
settings.
• reaction_domain (openmc.Material or openmc.Cell or openmc.Universe or
openmc.RegularMesh) – Domain in which to tally reaction rates.
• chain_file (str) – Path to the depletion chain XML file that will be used in depletion
simulation. Used to determine cross sections for materials not present in the inital compo-
sition.
• dilute_initial (float) – Initial atom density [atoms/cm^3] to add for nuclides that
are zero in initial condition to ensure they exist in the cross section data. Only done for
• reactions (list of str, optional) – Reaction names to tally

• energy_bound (2-tuple of float, optional) – Bounds for the energy group.

• run_kwargs (dict, optional) – Keyword arguments passed to openmc.model.
Model.run()
Returns
Cross section data in [b]
Return type
MicroXS
class openmc.deplete.OperatorResult(k, rates)

Result of applying transport operator
Parameters
• k (uncertainties.ufloat) – Resulting eigenvalue and standard deviation
• rates (openmc.deplete.ReactionRates) – Resulting reaction rates
openmc.deplete.ReactionRates
class openmc.deplete.ReactionRates(local_mats, nuclides, reactions, from_results=False)

Reaction rates resulting from a transport operator call
This class is a subclass of numpy.ndarray with a few custom attributes that make it easy to determine what
index corresponds to a given material, nuclide, and reaction rate.
Parameters
• local_mats (list of str) – Material IDs
• nuclides (list of str) – Depletable nuclides
• reactions (list of str) – Transmutation reactions being tracked
• from_results (boolean) – If the reaction rates are loaded from results, indexing dictio-
naries need to be kept the same.
Variables
• index_mat (OrderedDict of str to int) – A dictionary mapping material ID as string
to index.
• index_nuc (OrderedDict of str to int) – A dictionary mapping nuclide name as
string to index.
• index_rx (OrderedDict of str to int) – A dictionary mapping reaction name as
string to index.
• n_mat (int) – Number of materials.
• n_nuc (int) – Number of nucs.
• n_react (int) – Number of reactions.
get(mat, nuc, rx)
Get reaction rate by material/nuclide/reaction
Parameters

• mat (str) – Material ID as a string

• nuc (str) – Nuclide name
• rx (str) – Name of the reaction
Returns
Reaction rate corresponding to given material, nuclide, and reaction
Return type
float
set(mat, nuc, rx, value)
Set reaction rate by material/nuclide/reaction
Parameters
• mat (str) – Material ID as a string
• nuc (str) – Nuclide name
• rx (str) – Name of the reaction
• value (float) – Corresponding reaction rate to set
openmc.deplete.Results
class openmc.deplete.Results(filename=None)
Results from a depletion simulation
The Results class acts as a list that stores the results from each depletion step and provides extra methods for
interrogating these results.
Changed in version 0.13.1: Name changed from ResultsList to Results
Parameters
filename (str) – Path to depletion result file
export_to_materials(burnup_index, nuc_with_data=None) → Materials
Return openmc.Materials object based on results at a given step
Parameters
• burn_index (int) – Index of burnup step to evaluate. See also: get_step_where for ob-
taining burnup step indices from other data such as the time.
• nuc_with_data (Iterable of str, optional) – Nuclides to include in resulting ma-
terials. This can be specified if not all nuclides appearing in depletion results have associ-
ated neutron cross sections, and as such cannot be used in subsequent transport calculations.
If not provided, nuclides from the cross_sections element of materials.xml will be used. If
that element is not present, nuclides from OPENMC_CROSS_SECTIONS will be used.
Returns
mat_file – A modified Materials instance containing depleted material data and original iso-
topic compositions of non-depletable materials
Return type
Materials

classmethod from_hdf5(filename)
Load in depletion results from a previous file
Parameters
filename (str) – Path to depletion result file
Returns
New instance of depletion results
Return type
Results
get_atoms(mat, nuc, nuc_units='atoms', time_units='s')
Get number of nuclides over time from a single material
Note: Initial values for some isotopes that do not appear in initial concentrations may be non-zero, depend-
ing on the value of the openmc.deplete.CoupledOperator.dilute_initial attribute. The openmc.
deplete.CoupledOperator class adds isotopes according to this setting, which can be set to zero.
Parameters
• mat (openmc.Material, str) – Material object or material id to evaluate
• nuc (str) – Nuclide name to evaluate
• nuc_units ({"atoms", "atom/b-cm", "atom/cm3"}, optional) – Units for the re-
turned concentration. Default is "atoms"
• time_units ({"s", "min", "h", "d", "a"}, optional) – Units for the returned
time array. Default is "s" to return the value in seconds. Other options are minutes "min",
hours "h", days "d", and Julian years "a".
Returns
• times (numpy.ndarray) – Array of times in units of time_units
• concentrations (numpy.ndarray) – Concentration of specified nuclide in units of
nuc_units
get_depletion_time()
Return an array of the average time to deplete a material
Note: The return value will have one fewer values than several other methods, such as get_keff(),
because no depletion is performed at the final transport stage.
Returns
times – Vector of average time to deplete a single material across all processes and materials.
Return type
numpy.ndarray

get_keff(time_units='s')
Evaluates the eigenvalue from a results list.
Parameters
time_units ({"s", "d", "min", "h", "a"}, optional) – Desired units for the times
array. Options are seconds "s", minutes "min", hours "h", days "d", and Julian years "a".
Returns
• times (numpy.ndarray) – Array of times in specified units
• eigenvalues (numpy.ndarray) – k-eigenvalue at each time. Column 0 contains the eigen-
value, while column 1 contains the associated uncertainty
get_reaction_rate(mat, nuc, rx)
Get reaction rate in a single material/nuclide over time
Note: Initial values for some isotopes that do not appear in initial concentrations may be non-zero, depend-
ing on the value of openmc.deplete.CoupledOperator dilute_initial The openmc.deplete.
CoupledOperator adds isotopes according to this setting, which can be set to zero.
Parameters
• mat (openmc.Material, str) – Material object or material id to evaluate
• nuc (str) – Nuclide name to evaluate
• rx (str) – Reaction rate to evaluate
Returns
• times (numpy.ndarray) – Array of times in [s]
• rates (numpy.ndarray) – Array of reaction rates
get_step_where(time, time_units='d', atol=1e-06, rtol=0.001) → int

Return the index closest to a given point in time
In the event time lies exactly between two points, the lower index will be returned. It is possible that the
index will be at most one past the point in time requested, but only according to tolerances requested.
Passing atol=math.inf and rtol=math.inf will return the closest index to the requested point.
Parameters
• time (float) – Desired point in time
• time_units ({"s", "d", "min", "h", "a"}, optional) – Units on time. Default:
days "d". Other options are seconds "s", minutes "min", hours "h" and Julian years "a".
• atol (float, optional) – Absolute tolerance (in time_units) if time is not found.
• rtol (float, optional) – Relative tolerance if time is not found.
Return type
int

get_times(time_units='d') → ndarray
Return the points in time that define the depletion schedule
Parameters
time_units ({"s", "d", "min", "h", "a"}, optional) – Return the vector in these
units. Default is to convert to days "d". Other options are seconds "s", minutes "min", hours
"h", days "d", and Julian years "a".
Returns
1-D vector of time points
Return type
numpy.ndarray
openmc.deplete.StepResult
class openmc.deplete.StepResult
Result of a single depletion timestep
Changed in version 0.13.1: Name changed from Results to StepResult
Variables
• k (list of (float, float)) – Eigenvalue and uncertainty for each substep.
• time (list of float) – Time at beginning, end of step, in seconds.
• source_rate (float) – Source rate during timestep in [W] or [neutron/sec]
• n_mat (int) – Number of mats.
• n_nuc (int) – Number of nuclides.
• rates (list of ReactionRates) – The reaction rates for each substep.
• volume (OrderedDict of str to float) – Dictionary mapping mat id to volume.
• mat_to_ind (OrderedDict of str to int) – A dictionary mapping mat ID as string to
index.
• nuc_to_ind (OrderedDict of str to int) – A dictionary mapping nuclide name as
string to index.
• mat_to_hdf5_ind (OrderedDict of str to int) – A dictionary mapping mat ID as
string to global index.
• n_hdf5_mats (int) – Number of materials in entire geometry.
• n_stages (int) – Number of stages in simulation.
• data (numpy.ndarray) – Atom quantity, stored by stage, mat, then by nuclide.
• proc_time (int) – Average time spent depleting a material across all materials and pro-
cesses
allocate(volume, nuc_list, burn_list, full_burn_list, stages)
Allocate memory for depletion step data
Parameters
• volume (dict of str float) – Volumes corresponding to materials in full_burn_dict
• nuc_list (list of str) – A list of all nuclide names. Used for sorting the simulation.

• burn_list (list of int) – A list of all mat IDs to be burned. Used for sorting the
simulation.
• full_burn_list (list of str) – List of all burnable material IDs
• stages (int) – Number of stages in simulation.
distribute(local_materials, ranges)
Create a new object containing data for distributed materials
Parameters
• local_materials (iterable of str) – Materials for this process
• ranges (iterable of int) – Slice-like object indicating indicies of local_materials
in the material dimension of data and each element in rates
Returns
New results object
Return type
StepResult
export_to_hdf5(filename, step)
Export results to an HDF5 file
Parameters
• filename (str) – The filename to write to
• step (int) – What step is this?
classmethod from_hdf5(handle, step)
Loads results object from HDF5.
Parameters
• handle (h5py.File or h5py.Group) – An HDF5 file or group type to load from.
• step (int) – Index for depletion step
static save(op, x, op_results, t, source_rate, step_ind, proc_time=None)
Creates and writes depletion results to disk
Parameters
• op (openmc.deplete.abc.TransportOperator) – The operator used to generate these
results.
• x (list of list of numpy.array) – The prior x vectors. Indexed [i][cell] using the
above equation.
• op_results (list of openmc.deplete.OperatorResult) – Results of applying
transport operator
• t (list of float) – Time indices.
• source_rate (float) – Source rate during time step in [W] or [neutron/sec]
• step_ind (int) – Step index.
• proc_time (float or None) – Total process time spent depleting materials. This may
be process-dependent and will be reduced across MPI processes.

transfer_volumes(model)
Transfers volumes from depletion results to geometry
Parameters
model (OpenMC model to be used in a depletion restart) – calculation
The following class and functions are used to solve the depletion equations, with cram.CRAM48() being the default.
cram.IPFCramSolver CRAM depletion solver that uses incomplete partial fac-

torization
openmc.deplete.cram.IPFCramSolver
class openmc.deplete.cram.IPFCramSolver(alpha, theta, alpha0)

CRAM depletion solver that uses incomplete partial factorization
Provides a __call__() that utilizes an incomplete partial factorization (IPF) for the Chebyshev Rational Ap-
proximation Method (CRAM), as described in the following paper: M. Pusa, “Higher-Order Chebyshev Rational
Approximation Method and Application to Burnup Equations,” Nucl. Sci. Eng., 182:3, 297-318.
Parameters
• alpha (numpy.ndarray) – Complex residues of poles used in the factorization. Must be a
vector with even number of items.
• theta (numpy.ndarray) – Complex poles. Must have an equal size as alpha.
• alpha0 (float) – Limit of the approximation at infinity
Variables
• alpha (numpy.ndarray) – Complex residues of poles theta in the incomplete partial fac-
torization. Denoted as 𝛼
˜
• theta (numpy.ndarray) – Complex poles 𝜃 of the rational approximation
• alpha0 (float) – Limit of the approximation at infinity
__call__(A, n0, dt)
Solve depletion equations using IPF CRAM
Parameters
• A (scipy.sparse.csr_matrix) – Sparse transmutation matrix A[j, i] desribing rates
at which isotope i transmutes to isotope j
• n0 (numpy.ndarray) – Initial compositions, typically given in number of atoms in some
material or an atom density
• dt (float) – Time [s] of the specific interval to be solved
Returns
Final compositions after dt
Return type
numpy.ndarray
cram.CRAM16 Solve depletion equations using IPF CRAM

cram.CRAM48 Solve depletion equations using IPF CRAM
pool.deplete Deplete materials using given reaction rates for a speci-
fied time

openmc.deplete.cram.CRAM16
openmc.deplete.cram.CRAM16(A, n0, dt)

Parameters
• A (scipy.sparse.csr_matrix) – Sparse transmutation matrix A[j, i] desribing rates at
which isotope i transmutes to isotope j
Returns
Return type
numpy.ndarray
openmc.deplete.cram.CRAM48
openmc.deplete.cram.CRAM48(A, n0, dt)

Parameters
• A (scipy.sparse.csr_matrix) – Sparse transmutation matrix A[j, i] desribing rates at
which isotope i transmutes to isotope j
Returns
Return type
numpy.ndarray
openmc.deplete.pool.deplete
openmc.deplete.pool.deplete(func, chain, x, rates, dt, matrix_func=None)

Deplete materials using given reaction rates for a specified time
Parameters
• func (callable) – Function to use to get new compositions. Expected to have the signature
func(A, n0, t) -> n1
• x (list of numpy.ndarray) – Atom number vectors for each material
• rates (openmc.deplete.ReactionRates) – Reaction rates (from transport operator)
• dt (float) – Time in [s] to deplete for

• maxtrix_func (callable, optional) – Function to form the depletion matrix after

calling matrix_func(chain, rates, fission_yields), where fission_yields =
{parent: {product: yield_frac}} Expected to return the depletion matrix required
by func
Returns
x_result – Updated atom number vectors for each material
Return type
pool.USE_MULTIPROCESSING
Boolean switch to enable or disable the use of multiprocessing when solving the Bateman equations. The
default is to use multiprocessing, but can cause the simulation to hang in some computing environments,
namely due to MPI and networking restrictions. Disabling this option will result in only a single CPU core being
used for depletion.
Type
bool
pool.NUM_PROCESSES
Number of worker processes used for depletion calculations, which rely on the multiprocessing.pool.Pool
class. If set to None (default), the number returned by os.cpu_count() is used.
The following classes are used to help the openmc.deplete.CoupledOperator compute quantities like effective
fission yields, reaction rates, and total system energy.
helpers.AveragedFissionYieldHelper Class that computes fission yields based on average fis-

sion energy
helpers.ChainFissionHelper Computes normalization using fission Q values from de-
pletion chain
helpers.ConstantFissionYieldHelper Class that uses a single set of fission yields on each iso-
tope
helpers.DirectReactionRateHelper Class for generating one-group reaction rates with direct
tallies
helpers.EnergyScoreHelper Class responsible for obtaining system energy via a tally
score
helpers.FissionYieldCutoffHelper Helper that computes fission yields based on a cutoff en-
ergy
helpers.FluxCollapseHelper Class that generates one-group reaction rates using
multigroup flux
openmc.deplete.helpers.AveragedFissionYieldHelper
class openmc.deplete.helpers.AveragedFissionYieldHelper(chain_nuclides)
Class that computes fission yields based on average fission energy
Computes average energy at which fission events occurred with
∫︀ ∞
¯ 𝐸𝜎𝑓 (𝐸)𝜑(𝐸)𝑑𝐸
𝐸 = ∫︀0 ∞
0
𝜎𝑓 (𝐸)𝜑(𝐸)𝑑𝐸
If the average energy for a nuclide is below the lowest energy with yield data, that set of fission yields is taken.
Conversely, if the average energy is above the highest energy with yield data, that set of fission yields is used. For
the case where the average energy is between two sets of yields, the effective fission yield computed by linearly
interpolating between yields provided at the nearest energies above and below the average.

Parameters
chain_nuclides (iterable of openmc.deplete.Nuclide) – Nuclides tracked in the de-
pletion chain. All nuclides are not required to have fission yield data.
Variables
• constant_yields (collections.defaultdict) – Fission yields for all nuclides that
only have one set of fission yield data. Dictionary of form {str: {str: float}} rep-
resenting yields for {parent: {product: yield}}. Default return object is an empty
dictionary
• results (None or numpy.ndarray) – If tallies have been generated and unpacked, then
the array will have shape (n_mats, n_tnucs), where n_mats is the number of materials
where fission reactions were tallied and n_tnucs is the number of nuclides with multiple
sets of fission yields. Data in the array are the average energy of fission events for tallied
nuclides across burnable materials.
classmethod from_operator(operator, **kwargs)
Return a new helper with data from an operator
All keyword arguments should be identical to their counterpart in the main __init__ method
Parameters
• operator (openmc.deplete.CoupledOperator) – Operator with a depletion chain
• kwargs – Additional keyword arguments to be used in construction
Return type
AveragedFissionYieldHelper
generate_tallies(materials, mat_indexes)
Construct tallies to determine average energy of fissions
Parameters
• materials (iterable of openmc.lib.Material) – Materials to be used in openmc.lib.
MaterialFilter
• mat_indexes (iterable of int) – Indices of tallied materials that will have
their fission yields computed by this helper. Necessary as the openmc.deplete.
CoupledOperator that uses this helper may only burn a subset of all materials when
running in parallel mode.
unpack()
Unpack tallies and populate results with average energies
update_tally_nuclides(nuclides)
Tally nuclides with non-zero density and multiple yields
Must be run after generate_tallies().
Parameters
nuclides (iterable of str) – Potential nuclides to be tallied, such as those with non-zero
density at this stage.
Returns
nuclides – Union of input nuclides and those that have multiple sets of yield data. Sorted by
nuclide name
Return type
tuple of str

Raises
AttributeError – If tallies not generated
weighted_yields(local_mat_index)
Return fission yields for a specific material
Use the computed average energy of fission events to determine fission yields. If average energy is between
two sets of yields, linearly interpolate between the two. Otherwise take the closet set of yields.
Parameters
local_mat_index (int) – Index for specific burnable material. Effective yields will be
produced using self.results[local_mat_index]
Returns
library – Dictionary of {parent: {product: fyield}}. Default return value is an
empty dictionary
Return type
collections.defaultdict
openmc.deplete.helpers.ChainFissionHelper
class openmc.deplete.helpers.ChainFissionHelper
Computes normalization using fission Q values from depletion chain
Variables
• nuclides (list of str) – All nuclides with desired reaction rates. Ordered to be consis-
tent with openmc.deplete.CoupledOperator
• energy (float) – Total energy [J/s/source neutron] produced in a transport simulation. Up-
dated in the material iteration with update().
prepare(chain_nucs, rate_index)
Populate the fission Q value vector from a chain.
Parameters
• chain_nucs (iterable of openmc.deplete.Nuclide) – Nuclides used in this depletion
chain. Do not need to be ordered
• rate_index (dict of str to int) – Dictionary mapping names of nuclides, e.g.
"U235", to a corresponding index in the desired fission Q vector.
update(fission_rates)
Update energy produced with fission rates in a material
Parameters
fission_rates (numpy.ndarray) – fission reaction rate for each isotope in the specified
material. Should be ordered corresponding to initial rate_index used in prepare()

openmc.deplete.helpers.ConstantFissionYieldHelper
class openmc.deplete.helpers.ConstantFissionYieldHelper(chain_nuclides, energy=0.0253)

Class that uses a single set of fission yields on each isotope
Parameters
• chain_nuclides (iterable of openmc.deplete.Nuclide) – Nuclides tracked in the
depletion chain. All nuclides are not required to have fission yield data.
• energy (float, optional) – Key in openmc.deplete.Nuclide.yield_data corre-
sponding to the desired set of fission yield data. Typically one of {0.0253, 500000,
14000000} corresponding to 0.0253 eV, 500 keV, and 14 MeV yield libraries. If the specific
key is not found, will fall back to closest energy present. Default: 0.0253 eV for thermal
yields
Variables
dictionary
• energy (float) – Energy of fission yield libraries.
Return a new ConstantFissionYieldHelper using operator data
Parameters
• operator (openmc.deplete.abc.TransportOperator) – operator with a depletion
chain
Return type
ConstantFissionYieldHelper
weighted_yields(_local_mat_index=None)
Return fission yields for all nuclides requested
Parameters
_local_mat_index (int, optional) – Current material index. Not used since all yields
are constant
Returns
library – Dictionary of {parent: {product: fyield}}
Return type

openmc.deplete.helpers.DirectReactionRateHelper
class openmc.deplete.helpers.DirectReactionRateHelper(n_nuc, n_react)

Class for generating one-group reaction rates with direct tallies
This class generates reaction rate tallies for each nuclide and transmutation reaction relevant for a depletion
calculation.
Parameters
• n_nucs (int) – Number of burnable nuclides tracked by openmc.deplete.
CoupledOperator
• n_react (int) – Number of reactions tracked by an instance of openmc.deplete.
CoupledOperator
Variables
nuclides (list of str) – All nuclides with desired reaction rates.
generate_tallies(materials, scores)
Produce one-group reaction rate tally
Uses the openmc.lib to generate a tally of relevant reactions across all burnable materials.
Parameters
• materials (iterable of openmc.Material) – Burnable materials in the problem. Used
to construct a openmc.MaterialFilter
• scores (iterable of str) – Reaction identifiers, e.g. "(n, fission)", "(n,
gamma)", needed for the reaction rate tally.
get_material_rates(mat_id, nuc_index, react_index)
Return an array of reaction rates for a material
Parameters
• mat_id (int) – Unique ID for the requested material
• nuc_index (iterable of int) – Index for each nuclide in nuclides in the desired
reaction rate matrix
• react_index (iterable of int) – Index for each reaction scored in the tally
Returns
rates – Array with shape (n_nuclides, n_rxns) with the reaction rates in this material
Return type
numpy.ndarray
property nuclides
List of nuclides with requested reaction rates

openmc.deplete.helpers.EnergyScoreHelper
class openmc.deplete.helpers.EnergyScoreHelper(score='heating-local')
Class responsible for obtaining system energy via a tally score
Parameters
score (string) – Valid score to use when obtaining system energy from OpenMC. Defaults to
“heating-local”
Variables
• nuclides (list of str) – List of nuclides with reaction rates. Not needed, but provided
for a consistent API across other NormalizationHelper
• energy (float) – System energy [eV] computed from the tally. Will be zero for all MPI
processes that are not the “master” process to avoid artificially increasing the tallied energy.
• score (str) – Score used to obtain system energy
prepare(*args, **kwargs)
Create a tally for system energy production
Input arguments are not used, as the only information needed is score
reset()
Obtain system energy from tally
Only the master process, comm.rank == 0 will have a non-zero energy taken from the tally. This avoids
accidentally scaling the system power by the number of MPI processes
openmc.deplete.helpers.FissionYieldCutoffHelper
class openmc.deplete.helpers.FissionYieldCutoffHelper(chain_nuclides, n_bmats, cutoff=112.0,

thermal_energy=0.0253,
fast_energy=500000.0)
Helper that computes fission yields based on a cutoff energy
Tally fission rates above and below the cutoff energy. Assume that all fissions below cutoff energy have use
thermal fission product yield distributions, while all fissions above use a faster set of yield distributions.
Uses a limit of 20 MeV for tallying fission.
Parameters
• chain_nuclides (iterable of openmc.deplete.Nuclide) – Nuclides tracked in the
depletion chain. All nuclides are not required to have fission yield data.
• n_bmats (int, optional) – Number of burnable materials tracked in the problem
• cutoff (float, optional) – Cutoff energy in [eV] below which all fissions will be use
thermal yields. All other fissions will use a faster set of yields. Default: 112 [eV]
• thermal_energy (float, optional) – Energy of yield data corresponding to thermal
yields. Default: 0.0253 [eV]
• fast_energy (float, optional) – Energy of yield data corresponding to fast yields.
Variables
• n_bmats (int) – Number of burnable materials tracked in the problem. Must be set prior to
generating tallies

• thermal_yields (dict) – Dictionary of the form {parent: {product: yield}}

with thermal yields
• fast_yields (dict) – Dictionary of the form {parent: {product: yield}} with
fast yields
dictionary
• results (numpy.ndarray) – Array of fission rate fractions with shape (n_mats, 2,
n_nucs). results[:, 0] corresponds to the fraction of all fissions that occurred below
cutoff. The number of materials in the first axis corresponds to the number of materials
burned by the openmc.deplete.CoupledOperator
Construct a helper from an operator
Parameters
• operator (openmc.deplete.CoupledOperator) – Operator with a chain and burnable
materials
Return type
FissionYieldCutoffHelper
Use C API to produce a fission rate tally in burnable materials
Include a openmc.lib.EnergyFilter to tally fission rates above and below cutoff energy.
Parameters
MaterialFilter
unpack()
Obtain fast and thermal fission fractions from tally
weighted_yields(local_mat_index)
For nuclides with both yield data above and below the cutoff energy, the effective yield for nuclide A will
be a weighted sum of fast and thermal yields. The weights will be the fraction of A fission events in the
above and below the cutoff energy.
If A has fission product distribution F for fast fissions and T for thermal fissions, and 70% of A fissions are
considered thermal, then the effective fission product yield distributions for A is 0.7 * T + 0.3 * F
Parameters
local_mat_index (int) – Index for specific burnable material. Effective yields will be
produced using self.results[local_mat_index]

Returns
library – Dictionary of {parent: {product: fyield}}
Return type
openmc.deplete.helpers.FluxCollapseHelper
class openmc.deplete.helpers.FluxCollapseHelper(n_nucs, n_reacts, energies, reactions=None,

nuclides=None)
Class that generates one-group reaction rates using multigroup flux
This class generates a multigroup flux tally that is used afterward to calculate a one-group reaction rate by col-
lapsing it with continuous-energy cross section data. Additionally, select nuclides/reactions can be treated with a
direct reaction rate tally when using a multigroup flux spectrum would not be sufficiently accurate. This is often
the case for (n,gamma) and fission reactions.
Parameters
• n_nucs (int) – Number of burnable nuclides tracked by openmc.deplete.
CoupledOperator
• n_react (int) – Number of reactions tracked by openmc.deplete.CoupledOperator
• energies (iterable of float) – Energy group boundaries for flux spectrum in [eV]
• reactions (iterable of str) – Reactions for which rates should be directly tallied
• nuclides (iterable of str) – Nuclides for which some reaction rates should be directly
tallied. If None, then reactions will be used for all nuclides.
Variables
generate_tallies(materials, scores)
Produce multigroup flux spectrum tally
Uses the openmc.lib module to generate a multigroup flux tally for each burnable material.
Parameters
• materials (iterable of openmc.Material) – Burnable materials in the problem. Used
to construct a openmc.MaterialFilter
• scores (iterable of str) – Reaction identifiers, e.g. "(n, fission)", "(n,
gamma)", needed for the reaction rate tally.
get_material_rates(mat_index, nuc_index, react_index)
Return an array of reaction rates for a material
Parameters
• mat_index (int) – Index for material
• nuc_index (iterable of int) – Index for each nuclide in nuclides in the desired
reaction rate matrix
• react_index (iterable of int) – Index for each reaction scored in the tally
Returns
rates – Array with shape (n_nuclides, n_rxns) with the reaction rates in this material

Return type
numpy.ndarray
property nuclides
The openmc.deplete.IndependentOperator uses inner classes subclassed from those listed above to perform sim-
ilar calculations.
6.4.4 Intermediate Classes
Specific implementations of abstract base classes may utilize some of the same methods and data structures. These
methods and data are stored in intermediate classes.
Methods common to tally-based implementation of FissionYieldHelper are stored in helpers.
TalliedFissionYieldHelper
helpers.TalliedFissionYieldHelper Abstract class for computing fission yields with tallies
openmc.deplete.helpers.TalliedFissionYieldHelper
class openmc.deplete.helpers.TalliedFissionYieldHelper(chain_nuclides)
Abstract class for computing fission yields with tallies
Generates a basic fission rate tally in all burnable materials with generate_tallies(), and set nu-
clides to be tallied with update_tally_nuclides(). Subclasses will need to implement unpack() and
weighted_yields().
Parameters
pletion chain. Not necessary that all have yield data.
Variables
• constant_yields (dict of str to openmc.deplete.FissionYield) – Fission yields for
all nuclides that only have one set of fission yield data. Can be accessed as {parent:
{product: yield}}
• results (None or numpy.ndarray) – Tally results shaped in a manner useful to this
helper.
Construct the fission rate tally
Parameters
MaterialFilter
abstract unpack()
Unpack tallies after a transport run.
Abstract because each subclass will need to arrange its tally data.

Tally nuclides with non-zero density and multiple yields
Must be run after generate_tallies().
Parameters
nuclides (iterable of str) – Potential nuclides to be tallied, such as those with non-zero
density at this stage.
Returns
nuclides – Union of input nuclides and those that have multiple sets of yield data. Sorted by
nuclide name
Return type
list of str
Raises
AttributeError – If tallies not generated
Methods common to OpenMC-specific implementations of TransportOperator are stored in openmc_operator.
OpenMCOperator
openmc_operator.OpenMCOperator Abstract class holding OpenMC-specific functions for

running depletion calculations.
openmc.deplete.openmc_operator.OpenMCOperator
class openmc.deplete.openmc_operator.OpenMCOperator(materials=None, cross_sections=None,

chain_file=None, prev_results=None,
diff_burnable_mats=False, fission_q=None,
dilute_initial=0.0, helper_kwargs=None,
reduce_chain=False,
reduce_chain_level=None)
Abstract class holding OpenMC-specific functions for running depletion calculations.
Specific classes for running transport-coupled or transport-independent depletion calculations are implemented
as subclasses of OpenMCOperator.
Parameters
• materials (openmc.Materials) – List of all materials in the model
• cross_sections (str or pandas.DataFrame) – Path to continuous energy cross sec-
tion library, or object containing one-group cross-sections.
• chain_file (str, optional) – Path to the depletion chain XML file. Defaults to the file
listed under depletion_chain in OPENMC_CROSS_SECTIONS environment variable.
• prev_results (Results, optional) – Results from a previous depletion calculation. If
this argument is specified, the depletion calculation will start from the latest state in the
previous results.
• diff_burnable_mats (bool, optional) – Whether to differentiate burnable materials
with multiple instances. Volumes are divided equally from the original material volume.
• fission_q (dict, optional) – Dictionary of nuclides and their fission Q values [eV].

• helper_kwargs (dict) – Keyword arguments for helper classes

Variables
• materials (openmc.Materials) – All materials present in the model
• cross_sections (str or MicroXS) – Path to continuous energy cross section library, or
object containing one-group cross-sections.
reaction rates.
cross_sections.xml.
trices and tallies.
erator step.
get_results_info()
Returns volume list, material lists, and nuc lists.
Returns
• volume (dict of str float) – Volumes corresponding to materials in full_burn_dict
• burn_list (list of int) – A list of all material IDs to be burned. Used for sorting the simu-
lation.
• full_burn_list (list) – List of all burnable material IDs
initial_condition(materials)
Parameters
materials (list of str) – list of material IDs

Returns
Return type
write_bos_data(step)
Document beginning of step data for a given step
Called at the beginning of a depletion step and at the final point in the simulation.
Parameters
6.4.5 Abstract Base Classes
A good starting point for extending capabilities in openmc.deplete is to examine the following abstract base classes.
Custom classes can inherit from abc.TransportOperator to implement alternative schemes for collecting reaction
rates and other data prior to depleting materials
abc.TransportOperator Abstract class defining a transport operator
openmc.deplete.abc.TransportOperator
class openmc.deplete.abc.TransportOperator(chain_file, fission_q=None, dilute_initial=1000.0,

prev_results=None)
Abstract class defining a transport operator
Each depletion integrator is written to work with a generic transport operator that takes a vector of material
compositions and returns an eigenvalue and reaction rates. This abstract class sets the requirements for such
a transport operator. Users should instantiate openmc.deplete.CoupledOperator or openmc.deplete.
IndependentOperator rather than this class.
Parameters
• chain_file (str) – Path to the depletion chain XML file
• fission_q (dict, optional) – Dictionary of nuclides and their fission Q values [eV]. If
not given, values will be pulled from the chain_file.
nuclides with reaction rates. Defaults to 1.0e3.
• prev_results (Results, optional) – Results from a previous depletion calculation.
Variables
reaction rates.
trices and tallies.

abstract __call__(vec, source_rate)

Runs a simulation.
Parameters
Returns
Return type
property dilute_initial
Initial atom density for nuclides with zero initial concentration
abstract get_results_info()
Returns volume list, cell lists, and nuc lists.
Returns
• volume (dict of str to float) – Volumes corresponding to materials in burn_list
• burn_list (list of int) – A list of all cell IDs to be burned. Used for sorting the simulation.
• full_burn_list (list of int) – All burnable materials in the geometry.
abstract initial_condition()
Returns
Return type
abstract write_bos_data(step)
Document beginning of step data for a given step
Called at the beginning of a depletion step and at the final point in the simulation.
Parameters
The following classes are abstract classes used to pass information from transport simulations (in the case of transport-
coupled depletion) or to simply calculate these quantities directly (in the case of transport-independent depletion) back
on to the abc.TransportOperator
abc.NormalizationHelper Abstract class for obtaining normalization factor on tal-

lies
abc.FissionYieldHelper Abstract class for processing energy dependent fission
yields
abc.ReactionRateHelper Abstract class for generating reaction rates for operators

openmc.deplete.abc.NormalizationHelper
class openmc.deplete.abc.NormalizationHelper
Abstract class for obtaining normalization factor on tallies
This helper class determines how reaction rates calculated by an instance of openmc.deplete.abc.
TransportOperator should be normalized for the purpose of constructing a burnup matrix. Based on the
method chosen, the power or source rate provided by the user, and reaction rates from a ReactionRateHelper,
this class will scale reaction rates to the correct values.
Variables
nuclides (list of str) – All nuclides with desired reaction rates. Ordered to be consistent
with openmc.deplete.abc.TransportOperator
abstract factor(source_rate)
Return normalization factor
Parameters
source_rate (float) – Power in [W] or source rate in [neutron/sec]
Returns
Normalization factor for tallies
Return type
float
property nuclides
abstract prepare(chain_nucs, rate_index)
Perform work needed to obtain energy produced
This method is called prior to calculating the reaction rates in openmc.deplete.abc.
TransportOperator.initial_condition(). Only used for energy-based normalization.
Parameters
• chain_nucs (list of str) – All nuclides to be tracked in this problem
• rate_index (dict of str to int) – Mapping from nuclide name to index in the fis-
sion_rates for update().
reset()
Reset state for normalization
update(fission_rates)
Update the normalization based on fission rates (only used for energy-based normalization)
Parameters
fission_rates (numpy.ndarray) – fission reaction rate for each isotope in the specified
material. Should be ordered corresponding to initial rate_index used in prepare()

openmc.deplete.abc.FissionYieldHelper
class openmc.deplete.abc.FissionYieldHelper(chain_nuclides)
Abstract class for processing energy dependent fission yields
Parameters
pletion chain. All nuclides are not required to have fission yield data.
Variables
constant_yields (collections.defaultdict) – Fission yields for all nuclides that only
have one set of fission yield data. Dictionary of form {str: {str: float}} representing
yields for {parent: {product: yield}}. Default return object is an empty dictionary
Create a new instance by pulling data from the operator
Parameters
• operator (openmc.deplete.abc.TransportOperator) – Operator with a depletion
chain
• kwargs (optional) – Additional keyword arguments to be used in constuction
static generate_tallies(materials, mat_indexes)
Construct tallies necessary for computing fission yields
Called during the operator set up phase prior to depleting. Not necessary for subclasses to implement
Parameters
• materials (iterable of C-API materials) – Materials to be used in openmc.lib.
MaterialFilter
static unpack()
Unpack tally data prior to compute fission yields.
Called after a openmc.deplete.abc.TransportOperator.__call__() routine during the normaliza-
tion of reaction rates.
Not necessary for all subclasses to implement, unless tallies are used.
Return nuclides with non-zero densities and yield data
Parameters
nuclides (iterable of str) – Nuclides with non-zero densities from the openmc.
deplete.abc.TransportOperator
Returns
nuclides – Union of nuclides that the openmc.deplete.abc.TransportOperator says
have non-zero densities at this stage and those that have yield data. Sorted by nuclide name
Return type
list of str

abstract weighted_yields(local_mat_index)
Parameters
local_mat_index (int) – Index for the material with requested fission yields. Should
correspond to the material represented in mat_indexes[local_mat_index] during
generate_tallies().
Returns
library – Dictionary-like object mapping {str: {str: float}. This reflects fission
yields for {parent: {product: fyield}}.
Return type
collections.abc.Mapping
openmc.deplete.abc.ReactionRateHelper
class openmc.deplete.abc.ReactionRateHelper(n_nucs, n_react)

Abstract class for generating reaction rates for operators
Responsible for generating reaction rate tallies for burnable materials, given nuclides and scores from the oper-
ator.
Reaction rates are passed back to the operator to be used by an openmc.deplete.OperatorResult instance.
Parameters
• n_nucs (int) – Number of burnable nuclides tracked by openmc.deplete.abc.
TransportOperator
• n_react (int) – Number of reactions tracked by openmc.deplete.abc.
TransportOperator
Variables
divide_by_adens(number)
Normalize reaction rates by number of nuclides
Acts on the current material examined by get_material_rates()
Parameters
number (iterable of float) – Number density [atoms/b-cm] of each nuclide tracked in
the calculation.
Returns
results – Array of reactions rates of shape (n_nuclides, n_rxns) normalized by the num-
ber of nuclides
Return type
numpy.ndarray
abstract generate_tallies(materials, scores)
Use the C API to build tallies needed for reaction rates
abstract get_material_rates(mat_id, nuc_index, react_index)
Return 2D array of [nuclide, reaction] reaction rates
Parameters
• mat_id (int) – Unique ID for the requested material

• nuc_index (list of str) – Ordering of desired nuclides

• react_index (list of str) – Ordering of reactions
property nuclides
Custom integrators or depletion solvers can be developed by subclassing from the following abstract base classes:
abc.Integrator Abstract class for solving the time-integration for deple-

tion
abc.SIIntegrator Abstract class for the Stochastic Implicit Euler integra-
tors
abc.DepSystemSolver Abstract class for solving depletion equations
openmc.deplete.abc.Integrator
class openmc.deplete.abc.Integrator(operator, timesteps, power=None, power_density=None,

Abstract class for solving the time-integration for depletion
Parameters
simulations


Variables
simulations
terval in timesteps
shape as n0
abstract __call__(conc, rates, dt, source_rate, i)
Parameters
Returns
__iter__()
__len__()
Parameters

openmc.deplete.abc.SIIntegrator
class openmc.deplete.abc.SIIntegrator(operator, timesteps, power=None, power_density=None,

solver='cram48')
Abstract class for the Stochastic Implicit Euler integrators
Does not provide a __call__ method, but scales and resets the number of particles used in initial transport
calculation
Parameters
simulations

Variables
simulations
shape as n0
abstract __call__(conc, rates, dt, source_rate, i)
Parameters
Returns
__iter__()
__len__()
Parameters

openmc.deplete.abc.DepSystemSolver
class openmc.deplete.abc.DepSystemSolver
Abstract class for solving depletion equations
Responsible for solving
⃗
𝜕𝑁
= 𝐴¯𝑁
⃗ (𝑡),
𝜕𝑡
for 0 < 𝑡 ≤ 𝑡 + ∆𝑡, given 𝑁

⃗ (0) = 𝑁
⃗0
abstract __call__(A, n0, dt)

Solve the linear system of equations for depletion
Parameters
• A (scipy.sparse.csr_matrix) – Sparse transmutation matrix A[j, i] describing rates
at which isotope i transmutes to isotope j
Returns
Final compositions after dt. Should be of identical shape to n0.
Return type
numpy.ndarray
6.5 openmc.mgxs – Multi-Group Cross Section Generation
6.5.1 Energy Groups
Module Variables
openmc.mgxs.GROUP_STRUCTURES
Dictionary of commonly used energy group structures:
• “CASMO-X” (where X is 2, 4, 8, 16, 25, 40 or 70) from the CASMO lattice physics code
• “XMAS-172” designed for LWR analysis ([SAR1990], [SAN2004])
• “SHEM-361” designed for LWR analysis to eliminate self-shielding calculations of thermal resonances
([HFA2005], [SAN2007], [HEB2008])
• “SCALE-44” designed for criticality analysis ([ZAL1999])
• “ECCO-1968” designed for fine group reactor cell calculations for fast, intermediate and thermal reactor
applications ([SAR1990])
• activation energy group structures “VITAMIN-J-42”, “VITAMIN-J-175”, “TRIPOLI-315”, “CCFE-709”
and “UKAEA-1102”
6.5. openmc.mgxs – Multi-Group Cross Section Generation 425

Classes
openmc.mgxs.EnergyGroups An energy groups structure used for multi-group cross-

sections.
openmc.mgxs.EnergyGroups
class openmc.mgxs.EnergyGroups(group_edges=None)
An energy groups structure used for multi-group cross-sections.
Parameters
group_edges (Iterable of Real) – The energy group boundaries [eV]
Variables
• group_edges (Iterable of Real) – The energy group boundaries [eV]
• num_groups (int) – The number of energy groups
can_merge(other)
Determine if energy groups can be merged with another.
Parameters
other (openmc.mgxs.EnergyGroups) – EnergyGroups to compare with
Returns
Whether the energy groups can be merged
Return type
bool
get_condensed_groups(coarse_groups)
Return a coarsened version of this EnergyGroups object.
This method merges together energy groups in this object into wider energy groups as defined by the list
of groups specified by the user, and returns a new, coarse EnergyGroups object.
Parameters
coarse_groups (Iterable of 2-tuple) – The energy groups of interest - a list of 2-
tuples, each directly corresponding to one of the new coarse groups. The values in the 2-
tuples are upper/lower energy groups used to construct a new coarse group. For example, if
[(1,2), (3,4)] was used as the coarse groups, fine groups 1 and 2 would be merged into coarse
group 1 while fine groups 3 and 4 would be merged into coarse group 2.
Returns
A coarsened version of this EnergyGroups object.
Return type
Raises
ValueError – If the group edges have not yet been set.
get_group(energy)
Returns the energy group in which the given energy resides.
Parameters
energy (float) – The energy of interest in eV

Returns
The energy group index, starting at 1 for the highest energies
Return type
Integral
Raises
get_group_bounds(group)
Returns the energy boundaries for the energy group of interest.
Parameters
group (int) – The energy group index, starting at 1 for the highest energies
Returns
The low and high energy bounds for the group in eV
Return type
2-tuple
Raises
get_group_indices(groups='all')
Returns the array indices for one or more energy groups.
Parameters
groups (str, tuple) – The energy groups of interest - a tuple of the energy group indices,
starting at 1 for the highest energies (default is ‘all’)
Returns
The ndarray array indices for each energy group of interest
Return type
numpy.ndarray
Raises
ValueError – If the group edges have not yet been set, or if a group is requested that is
outside the bounds of the number of energy groups.
merge(other)
Merge this energy groups with another.
Parameters
other (openmc.mgxs.EnergyGroups) – EnergyGroups to merge with
Returns
merged_groups – EnergyGroups resulting from the merge
Return type

6.5.2 Multi-group Cross Sections
openmc.mgxs.MGXS An abstract multi-group cross section for some energy

group structure within some spatial domain.
openmc.mgxs.MatrixMGXS An abstract multi-group cross section for some energy
group structure within some spatial domain.
openmc.mgxs.AbsorptionXS An absorption multi-group cross section.
openmc.mgxs.CaptureXS A capture multi-group cross section.
openmc.mgxs.Chi The fission spectrum.
openmc.mgxs.Current A current multi-group cross section.
openmc.mgxs.DiffusionCoefficient A diffusion coefficient multi-group cross section.
openmc.mgxs.FissionXS A fission multi-group cross section.
openmc.mgxs.InverseVelocity An inverse velocity multi-group cross section.
openmc.mgxs.KappaFissionXS A recoverable fission energy production rate multi-
group cross section.
openmc.mgxs.MultiplicityMatrixXS The scattering multiplicity matrix.
openmc.mgxs.NuFissionMatrixXS A fission production matrix multi-group cross section.
openmc.mgxs.ReducedAbsorptionXS A reduced absorption multi-group cross section.
openmc.mgxs.ScatterXS A scattering multi-group cross section.
openmc.mgxs.ScatterMatrixXS A scattering matrix multi-group cross section with the
cosine of the change-in-angle represented as one or more
Legendre moments or a histogram.
openmc.mgxs.ScatterProbabilityMatrix The group-to-group scattering probability matrix.
openmc.mgxs.TotalXS A total multi-group cross section.
openmc.mgxs.TransportXS A transport-corrected total multi-group cross section.
openmc.mgxs.ArbitraryXS A multi-group cross section for an arbitrary reaction
type.
openmc.mgxs.ArbitraryMatrixXS A multi-group matrix cross section for an arbitrary reac-
tion type.
openmc.mgxs.MeshSurfaceMGXS An abstract multi-group cross section for some energy
group structure on the surfaces of a mesh domain.
openmc.mgxs.MGXS
class openmc.mgxs.MGXS(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

name='', num_polar=1, num_azimuthal=1)
An abstract multi-group cross section for some energy group structure within some spatial domain.
This class can be used for both OpenMC input generation and tally data post-processing to compute spatially-
homogenized and energy-integrated multi-group cross sections for multi-group neutronics calculations.
Note: Users should instantiate the subclasses of this abstract class.
Parameters
• domain (openmc.Material or openmc.Cell or openmc.Universe or openmc.
RegularMesh) – The domain for spatial homogenization
• domain_type ({'material', 'cell', 'distribcell', 'universe', 'mesh'}) – The do-
main type for spatial homogenization

• energy_groups (openmc.mgxs.EnergyGroups) – The energy group structure for energy

condensation
• by_nuclide (bool) – If true, computes cross sections for each nuclide in domain
• name (str, optional) – Name of the multi-group cross section. Used as a label to identify
tallies in OpenMC ‘tallies.xml’ file.
• num_polar (Integral, optional) – Number of equi-width polar angle bins for angle
discretization; defaults to one bin
• num_azimuthal (Integral, optional) – Number of equi-width azimuthal angle bins for
angle discretization; defaults to one bin
Variables
• name (str, optional) – Name of the multi-group cross section
• rxn_type (str) – Reaction type (e.g., ‘total’, ‘nu-fission’, etc.)
RegularMesh) – Domain for spatial homogenization
• domain_type ({'material', 'cell', 'distribcell', 'universe', 'mesh'}) – Domain
type for spatial homogenization
• energy_groups (openmc.mgxs.EnergyGroups) – Energy group structure for energy con-
densation
• num_polar (Integral) – Number of equi-width polar angle bins for angle discretization
• num_azimuthal (Integral) – Number of equi-width azimuthal angle bins for angle dis-
cretization
• tally_trigger (openmc.Trigger) – An (optional) tally precision trigger given to each
tally used to compute the cross section
• scores (list of str) – The scores in each tally used to compute the multi-group cross
section
• filters (list of openmc.Filter) – The filters in each tally used to compute the multi-
group cross section
• tally_keys (list of str) – The keys into the tallies dictionary for each tally used to
compute the multi-group cross section
• estimator ({'tracklength', 'collision', 'analog'}) – The tally estimator used to
• tallies (collections.OrderedDict) – OpenMC tallies needed to compute the multi-
group cross section
• rxn_rate_tally (openmc.Tally) – Derived tally for the reaction rate tally used in the
numerator to compute the multi-group cross section. This attribute is None unless the multi-
group cross section has been computed.
• xs_tally (openmc.Tally) – Derived tally for the multi-group cross section. This attribute
is None unless the multi-group cross section has been computed.
• num_subdomains (int) – The number of subdomains is unity for ‘material’, ‘cell’ and ‘uni-
verse’ domain types. This is equal to the number of cell instances for ‘distribcell’ domain
types (it is equal to unity prior to loading tally data from a statepoint file) and the number of
mesh cells for ‘mesh’ domain types.

• num_nuclides (int) – The number of nuclides for which the multi-group cross section is
being tracked. This is unity if the by_nuclide attribute is False.
• nuclides (Iterable of str or 'sum') – The optional user-specified nuclides for which
to compute cross sections (e.g., ‘U238’, ‘O16’). If by_nuclide is True but nuclides are not
specified by the user, all nuclides in the spatial domain are included. This attribute is ‘sum’
if by_nuclide is false.
• sparse (bool) – Whether or not the MGXS’ tallies use SciPy’s LIL sparse matrix format
for compressed data storage
• loaded_sp (bool) – Whether or not a statepoint file has been loaded with tally data
• derived (bool) – Whether or not the MGXS is merged from one or more other MGXS
• mgxs_type (str) – The name of this MGXS type, to be used when printing and indexing
in an HDF5 data store
build_hdf5_store(filename='mgxs.h5', directory='mgxs', subdomains='all', nuclides='all',

xs_type='macro', row_column='inout', append=True, libver='earliest')
Export the multi-group cross section data to an HDF5 binary file.
This method constructs an HDF5 file which stores the multi-group cross section data. The data is stored
in a hierarchy of HDF5 groups from the domain type, domain id, subdomain id (for distribcell domains),
nuclides and cross section type. Two datasets for the mean and standard deviation are stored for each
subdomain entry in the HDF5 file.
Note: This requires the h5py Python package.
Parameters
• filename (str) – Filename for the HDF5 file. Defaults to ‘mgxs.h5’.
• directory (str) – Directory for the HDF5 file. Defaults to ‘mgxs’.
• subdomains (Iterable of Integral or 'all') – The subdomain IDs of the cross sec-
tions to include in the report. Defaults to ‘all’.
• nuclides (Iterable of str or 'all' or 'sum') – The nuclides of the cross-sections
to include in the report. This may be a list of nuclide name strings (e.g., [‘U235’, ‘U238’]).
The special string ‘all’ will report the cross sections for all nuclides in the spatial domain.
The special string ‘sum’ will report the cross sections summed over all nuclides. Defaults
to ‘all’.
• xs_type ({'macro', 'micro'}) – Store the macro or micro cross section in units of cm^-1
or barns. Defaults to ‘macro’.
• row_column ({'inout', 'outin'}) – Store scattering matrices indexed first by incoming
group and second by outgoing group (‘inout’), or vice versa (‘outin’). Defaults to ‘inout’.
• append (bool) – If true, appends to an existing HDF5 file with the same filename directory
(if one exists). Defaults to True.

Raises
ValueError – When this method is called before the multi-group cross section is computed
from tally data.
can_merge(other)
Determine if another MGXS can be merged with this one
If results have been loaded from a statepoint, then MGXS are only mergeable along one and only one of
enegy groups or nuclides.
Parameters
other (openmc.mgxs.MGXS) – MGXS to check for merging
export_xs_data(filename='mgxs', directory='mgxs', format='csv', groups='all', xs_type='macro')
Export the multi-group cross section data to a file.
This method leverages the functionality in the Pandas library to export the multi-group cross section data
in a variety of output file formats for storage and/or post-processing.
Parameters
• filename (str) – Filename for the exported file. Defaults to ‘mgxs’.
• directory (str) – Directory for the exported file. Defaults to ‘mgxs’.
• format ({'csv', 'excel', 'pickle', 'latex'}) – The format for the exported data file.
Defaults to ‘csv’.
• groups (Iterable of Integral or 'all') – Energy groups of interest. Defaults to
‘all’.
get_condensed_xs(coarse_groups)
Construct an energy-condensed version of this cross section.
Parameters
coarse_groups (openmc.mgxs.EnergyGroups) – The coarse energy group structure of
interest
Returns
A new MGXS condensed to the group structure of interest
Return type
MGXS
get_flux(groups='all', subdomains='all', order_groups='increasing', value='mean', squeeze=True,
**kwargs)
Returns an array of the fluxes used to weight the MGXS.
This method constructs a 2D NumPy array for the requested weighting flux for one or more subdomains
(1st dimension), and energy groups (2nd dimension).
Parameters
‘all’.
• subdomains (Iterable of Integral or 'all') – Subdomain IDs of interest. Defaults
to ‘all’.

• order_groups ({'increasing', 'decreasing'}) – Return the cross section indexed ac-

cording to increasing or decreasing energy groups (decreasing or increasing energies). De-
faults to ‘increasing’.
• value ({'mean', 'std_dev', 'rel_err'}) – A string for the type of value to return. De-
faults to ‘mean’.
• squeeze (bool) – A boolean representing whether to eliminate the extra dimensions of
the multi-dimensional array to be returned. Defaults to True.
Returns
A NumPy array of the flux indexed in the order each group and subdomain is listed in the
parameters.
Return type
numpy.ndarray
Raises
ValueError – When this method is called before the data is available from tally data, or,
when this is used on an MGXS type without a flux score.
get_homogenized_mgxs(other_mgxs)
Construct a homogenized mgxs with other MGXS objects.
Parameters
other_mgxs (openmc.mgxs.MGXS or Iterable of openmc.mgxs.MGXS) – The MGXS
to homogenize with this one.
Returns
A new homogenized MGXS
Return type
openmc.mgxs.MGXS
Raises
ValueError – If the other_mgxs is of a different type.
static get_mgxs(mgxs_type, domain=None, domain_type=None, energy_groups=None, by_nuclide=False,
Return a MGXS subclass object for some energy group structure within some spatial domain for some
reaction type.
This is a factory method which can be used to quickly create MGXS subclass objects for various reaction
types.
Parameters
• mgxs_type (str or Integral) – The type of multi-group cross section object to return;
valid values are members of MGXS_TYPES, or the reaction types that are the keys of
REACTION_MT. Note that if a reaction type from REACTION_MT is used, it can be
appended with ‘ matrix’ to obtain a multigroup matrix (from incoming to outgoing energy
groups) for reactions with a neutron in an outgoing channel.
• domain_type ({'material', 'cell', 'distribcell', 'universe', 'mesh'}) – The
domain type for spatial homogenization
• energy_groups (openmc.mgxs.EnergyGroups) – The energy group structure for en-
ergy condensation

• by_nuclide (bool) – If true, computes cross sections for each nuclide in domain. Defaults
to False
• name (str, optional) – Name of the multi-group cross section. Used as a label to iden-
tify tallies in OpenMC ‘tallies.xml’ file. Defaults to the empty string.
• num_polar (Integral, optional) – Number of equi-width polar angles for angle dis-
cretization; defaults to no discretization
• num_azimuthal (Integral, optional) – Number of equi-width azimuthal angles for
angle discretization; defaults to no discretization
Returns
A subclass of the abstract MGXS class for the multi-group cross section type requested by
the user
Return type
openmc.mgxs.MGXS
get_nuclide_densities(nuclides='all')
Get an array of atomic number densities in units of atom/b-cm for all nuclides in the cross section’s spatial
domain.
Parameters
nuclides (Iterable of str or 'all' or 'sum') – A list of nuclide name strings (e.g.,
[‘U235’, ‘U238’]). The special string ‘all’ will return the atom densities for all nuclides in
the spatial domain. The special string ‘sum’ will return the atom density summed across all
nuclides in the spatial domain. Defaults to ‘all’.
Returns
An array of the atomic number densities (atom/b-cm) for each of the nuclides in the spatial
domain
Return type
numpy.ndarray of float
Raises
ValueError – When this method is called before the spatial domain has been set.
get_nuclide_density(nuclide)
Get the atomic number density in units of atoms/b-cm for a nuclide in the cross section’s spatial domain.
Parameters
nuclide (str) – A nuclide name string (e.g., ‘U235’)
Returns
The atomic number density (atom/b-cm) for the nuclide of interest
Return type
float
get_nuclides()
Get all nuclides in the cross section’s spatial domain.
Returns
A list of the string names for each nuclide in the spatial domain (e.g., [‘U235’, ‘U238’, ‘O16’])
Return type
list of str
Raises

get_pandas_dataframe(groups='all', nuclides='all', xs_type='macro', paths=True)

Build a Pandas DataFrame for the MGXS data.
This method leverages openmc.Tally.get_pandas_dataframe(), but renames the columns with ter-
minology appropriate for cross section data.
Parameters
‘all’.
to include in the dataframe. This may be a list of nuclide name strings (e.g., [‘U235’,
‘U238’]). The special string ‘all’ will include the cross sections for all nuclides in the
spatial domain. The special string ‘sum’ will include the cross sections summed over all
nuclides. Defaults to ‘all’.
• xs_type ({'macro', 'micro'}) – Return macro or micro cross section in units of cm^-1
Returns
A Pandas DataFrame for the cross section data.
Return type
pandas.DataFrame
Raises
from tally data.
get_slice(nuclides=[], groups=[])
Build a sliced MGXS for the specified nuclides and energy groups.
This method constructs a new MGXS to encapsulate a subset of the data represented by this MGXS. The
subset of data to include in the tally slice is determined by the nuclides and energy groups specified in the
input parameters.
Parameters
is [])
• groups (list of int) – A list of energy group indices starting at 1 for the high energies
(e.g., [1, 2, 3]; default is [])
Returns
A new MGXS object which encapsulates the subset of data requested for the nuclide(s) and/or
energy group(s) requested in the parameters.
Return type
openmc.mgxs.MGXS
get_subdomain_avg_xs(subdomains='all')
Construct a subdomain-averaged version of this cross section.
This method is useful for averaging cross sections across distribcell instances. The method performs spatial
homogenization to compute the scalar flux-weighted average cross section across the subdomains.

Parameters
subdomains (Iterable of Integral or 'all') – The subdomain IDs to average across.
Defaults to ‘all’.
Returns
A new MGXS averaged across the subdomains of interest
Return type
openmc.mgxs.MGXS
Raises
from tally data.
get_units(xs_type='macro')
This method returns the units of a MGXS based on a desired xs_type.
Parameters
xs_type ({'macro', 'micro'}) – Return the macro or micro cross section units. Defaults to
‘macro’.
Returns
A string representing the units of the MGXS.
Return type
str
get_xs(groups='all', subdomains='all', nuclides='all', xs_type='macro', order_groups='increasing',
value='mean', squeeze=True, **kwargs)
Returns an array of multi-group cross sections.
This method constructs a 3D NumPy array for the requested multi-group cross section data for one or more
subdomains (1st dimension), energy groups (2nd dimension), and nuclides (3rd dimension).
Parameters
‘all’.
to ‘all’.
• nuclides (Iterable of str or 'all' or 'sum') – A list of nuclide name strings (e.g.,
[‘U235’, ‘U238’]). The special string ‘all’ will return the cross sections for all nuclides in
the spatial domain. The special string ‘sum’ will return the cross section summed over all
• xs_type ({'macro', 'micro'}) – Return the macro or micro cross section in units of cm^-1

Returns
A NumPy array of the multi-group cross section indexed in the order each group, subdomain
and nuclide is listed in the parameters.
Return type
numpy.ndarray
Raises
from tally data.
load_from_statepoint(statepoint)
Extracts tallies in an OpenMC StatePoint with the data needed to compute multi-group cross sections.
This method is needed to compute cross section data from tallies in an OpenMC StatePoint object.
Note: The statepoint must be linked with an OpenMC Summary object.
Parameters
statepoint (openmc.StatePoint) – An OpenMC StatePoint object with tally data
Raises
ValueError – When this method is called with a statepoint that has not been linked with a
summary object.
merge(other)
Merge another MGXS with this one
MGXS are only mergeable if their energy groups and nuclides are either identical or mutually exclusive.
energy groups or nuclides.
Parameters
other (openmc.mgxs.MGXS) – MGXS to merge with this one
Returns
merged_mgxs – Merged MGXS
Return type
openmc.mgxs.MGXS
print_xs(subdomains='all', nuclides='all', xs_type='macro')
Print a string representation for the multi-group cross section.
Parameters
to ‘all’.

openmc.mgxs.MatrixMGXS
class openmc.mgxs.MatrixMGXS(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

An abstract multi-group cross section for some energy group structure within some spatial domain. This class is
specifically intended for cross sections which depend on both the incoming and outgoing energy groups and are
therefore represented by matrices. Examples of this include the scattering and nu-fission matrices.
homogenized and energy-integrated multi-group cross sections for multi-group neutronics calculations.
Parameters
condensation
Variables
densation
cretization
section

group cross section
group cross section

Parameters

to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest

Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.

types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises

Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
get_slice(nuclides=[], in_groups=[], out_groups=[])
Build a sliced MatrixMGXS object for the specified nuclides and energy groups.
input parameters.
Parameters

is [])
• in_groups (list of int) – A list of incoming energy group indices starting at 1 for the
high energies (e.g., [1, 2, 3]; default is [])
• out_groups (list of int) – A list of outgoing energy group indices starting at 1 for
the high energies (e.g., [1, 2, 3]; default is [])
Returns
A new MatrixMGXS object which encapsulates the subset of data requested for the nuclide(s)
and/or energy group(s) requested in the parameters.
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
get_xs(in_groups='all', out_groups='all', subdomains='all', nuclides='all', xs_type='macro',
order_groups='increasing', row_column='inout', value='mean', squeeze=True, **kwargs)
subdomains (1st dimension), energy groups in (2nd dimension), energy groups out (3rd dimension), and
nuclides (4th dimension).
Parameters
• in_groups (Iterable of Integral or 'all') – Incoming energy groups of interest.

• out_groups (Iterable of Integral or 'all') – Outgoing energy groups of interest.

to ‘all’.
• row_column ({'inout', 'outin'}) – Return the cross section indexed first by incoming
Returns
A NumPy array of the multi-group cross section indexed in the order each group and subdo-
main is listed in the parameters.
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)

Parameters
Returns
Return type
openmc.mgxs.MGXS
Prints a string representation for the multi-group cross section.
Parameters
to ‘all’.
openmc.mgxs.AbsorptionXS
class openmc.mgxs.AbsorptionXS(domain=None, domain_type=None, energy_groups=None,

by_nuclide=False, name='', num_polar=1, num_azimuthal=1)
An absorption multi-group cross section.
Absorption is defined as all reactions that do not produce secondary neutrons (disappearance) plus fission reac-
tions.
homogenized and energy-integrated multi-group absorption cross sections for multi-group neutronics calcula-
tions. At a minimum, one needs to set the AbsorptionXS.energy_groups and AbsorptionXS.domain prop-
erties. Tallies for the flux and appropriate reaction rates over the specified domain are generated automatically
via the AbsorptionXS.tallies property, which can then be appended to a openmc.Tallies instance.
For post-processing, the MGXS.load_from_statepoint() will pull in the necessary data to compute multi-
group cross sections from a openmc.StatePoint instance. The derived multi-group cross section can then be
obtained from the AbsorptionXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the absorption cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸
𝑟∈𝑉
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜎𝑎 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜓(𝑟, 𝐸, Ω)
Parameters
condensation

Variables
densation
cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.

can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.

Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False

Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises


Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.CaptureXS
class openmc.mgxs.CaptureXS(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

A capture multi-group cross section.
The neutron capture reaction rate is defined as the difference between OpenMC’s ‘absorption’ and ‘fission’ reac-
tion rate score types. This includes not only radiative capture, but all forms of neutron disappearance aside from
fission (i.e., MT > 100).
homogenized and energy-integrated multi-group capture cross sections for multi-group neutronics calculations.
At a minimum, one needs to set the CaptureXS.energy_groups and CaptureXS.domain properties. Tal-
lies for the flux and appropriate reaction rates over the specified domain are generated automatically via the
CaptureXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the CaptureXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the capture cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝐸𝑔
𝑑𝐸 [𝜎𝑎 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω) − 𝜎𝑓 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)]
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉
Parameters
condensation
Variables


densation
cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters

Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters

Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame

Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str


Parameters
‘all’.
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.

merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.
openmc.mgxs.Chi
class openmc.mgxs.Chi(domain=None, domain_type=None, energy_groups=None, prompt=False,

The fission spectrum.
homogenized and energy-integrated multi-group cross sections for multi-group neutronics calculations. At a
minimum, one needs to set the Chi.energy_groups and Chi.domain properties. Tallies for the flux and
appropriate reaction rates over the specified domain are generated automatically via the Chi.tallies property,
which can then be appended to a openmc.Tallies instance.
obtained from the Chi.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the fission spectrum is calculated as:
∫︁ ∫︁ ∫︁ ∞ ∫︁ 𝐸𝑔−1
′ ′
⟨𝜈𝜎 𝑓,𝑔 ′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜈𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 𝐸𝑔
∫︁ ∫︁ ∫︁ ∞ ∫︁∞
⟨𝜈𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝐸 𝜒(𝐸)𝜈𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
⟨𝜈𝜎𝑓,𝑔′ →𝑔 𝜑⟩
𝜒𝑔 =
⟨𝜈𝜎𝑓 𝜑⟩

This class can also be used to gather a prompt-chi (which only includes the outgoing energy spectrum of prompt
neutrons). This is accomplished by setting the Chi.prompt attribute to True.
Parameters
• groups (openmc.mgxs.EnergyGroups) – The energy group structure for energy conden-
sation
• prompt (bool) – If true, computes cross sections which only includes prompt neutrons;
defaults to False which includes prompt and delayed in total
Variables
• prompt (bool) – If true, computes cross sections which only includes prompt neutrons
densation
cretization
section
group cross section
• estimator ('analog') – The tally estimator used to compute the multi-group cross section


group cross section. The keys are strings listed in the Chi.tally_keys property and values
are instances of openmc.Tally.
types (it is equal to unity prior to loading tally data from a statepoint file).
Parameters
to ‘all’.

Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)


Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters


ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float

get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
Build a sliced Chi for the specified nuclides and energy groups.
input parameters.
Parameters
is [])
• groups (list of Integral) – A list of energy group indices starting at 1 for the high
energies (e.g., [1, 2, 3]; default is [])

Returns
A new MGXS which encapsulates the subset of data requested for the nuclide(s) and/or energy
group(s) requested in the parameters.
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Returns the units of Chi.
This method returns the units of Chi, which is “%” for both macro and micro xs types.
Parameters
‘macro’.
Returns
A string representing the units of Chi.
Return type
str
Returns an array of the fission spectrum.
Parameters
‘all’.
to ‘all’.

• xs_type ({'macro', 'micro'}) – This parameter is not relevant for chi but is included here
to mirror the parent MGXS.get_xs(. . . ) class method
Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Merge another Chi with this one
If results have been loaded from a statepoint, then Chi are only mergeable along one and only one of energy
groups or nuclides.
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters


to ‘all’.
openmc.mgxs.Current
class openmc.mgxs.Current(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

name='')
A current multi-group cross section.
This class can be used for both OpenMC input generation and tally data post-processing to compute surface- and
energy-integrated multi-group current cross sections for multi-group neutronics calculations. At a minimum,
one needs to set the Current.energy_groups and Current.domain properties. Tallies for the appropriate
reaction rates over the specified domain are generated automatically via the Current.tallies property, which
can then be appended to a openmc.Tallies instance.
obtained from the Current.xs_tally property. For a spatial domain 𝑆 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the total
cross section is calculated as:
∫︀ ∫︀ 𝐸
𝑟∈𝑆
𝑑𝑆 𝐸𝑔𝑔−1 𝑑𝐸 𝐽(𝑟, 𝐸)
∫︀ ∫︀ 𝐸 .
𝑟∈𝑆
𝑑𝑆 𝐸𝑔𝑔−1 𝑑𝐸

Parameters
• domain (openmc.RegularMesh) – The domain for spatial homogenization
• domain_type (('mesh'}) – The domain type for spatial homogenization
sation
• by_nuclide (bool) – Unused in MeshSurfaceMGXS
Variables
• domain (openmc.RegularMesh) – Domain for spatial homogenization
• domain_type ({'mesh'}) – Domain type for spatial homogenization
densation

section
group cross section
• estimator ({'analog'}) – The tally estimator used to compute the multi-group cross section
group cross section. The keys are strings listed in the TotalXS.tally_keys property and
values are instances of openmc.Tally.
• num_subdomains (int) – The number of subdomains is equal to the number of mesh sur-
faces times two to account for both the incoming and outgoing current from the mesh cell
surfaces.
• num_nuclides (int) – Unused in MeshSurfaceMGXS
• nuclides (Iterable of str or 'sum') – Unused in MeshSurfaceMGXS
Parameters


to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns

Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.

Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters

Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
• nuclides (Iterable of str or 'all' or 'sum') – Unused in MeshSurfaceMGXS, its
value will be ignored. The nuclides dimension of the resultant array will always have a
length of 1.
• xs_type ({'macro'}) – ‘micro’ unused in MeshSurfaceMGXS.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])

Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.
length of 1.
• xs_type ({'macro'}) – The ‘macro’/’micro’ distinction does not apply to MeshSur-
faceMGXS. The calculation of a ‘micro’ xs_type is omited in this class.


Returns
Return type
numpy.ndarray
Raises
from tally data.
Note: The statepoint must first be linked with a openmc.Summary object.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters


to ‘all’.
openmc.mgxs.DiffusionCoefficient
class openmc.mgxs.DiffusionCoefficient(domain=None, domain_type=None, energy_groups=None,

nu=False, by_nuclide=False, name='', num_polar=1,
num_azimuthal=1)
A diffusion coefficient multi-group cross section.
homogenized and energy-integrated multi-group cross sections for multi-group neutronics calculations. At a min-
imum, one needs to set the DiffusionCoefficient.energy_groups and DiffusionCoefficient.domain
properties. Tallies for the flux and appropriate reaction rates over the specified domain are generated automati-
cally via the DiffusionCoefficient.tallies property, which can then be appended to a openmc.Tallies
instance.
obtained from the DiffusionCoefficient.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the diffusion coefficient is calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜎𝑡 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸𝜎𝑡 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
𝑟∈𝑉 4𝜋 𝐸𝑔
∫︁ ∫︁ ∫︁ 𝐸𝑔−1 ∫︁ ∫︁ ∞ ∫︁ 1
′ ′
⟨𝜎𝑠1 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω 𝑑𝐸 𝑑𝜇 𝜇𝜎𝑠 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜑(𝑟, 𝐸 ′ , Ω)
𝑟∈𝑉 4𝜋 𝐸𝑔 4𝜋 0 −1
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝜓(𝑟, 𝐸, Ω)
⟨𝜎𝑡 𝜑⟩ − ⟨𝜎𝑠1 𝜑⟩
𝜎𝑡𝑟 =
⟨𝜑⟩
1
𝐷=
3𝜎𝑡𝑟
To incorporate the effect of scattering multiplication in the above relation, the nu parameter can be set to True.
Parameters
sation
• nu (bool) – If True, the cross section data will include neutron multiplication; defaults to
False.

Variables
• nu (bool) – If True, the cross section data will include neutron multiplication
densation
cretization
section
group cross section
group cross section. The keys are strings listed in the TransportXS.tally_keys property
and values are instances of openmc.Tally.

Parameters
to ‘all’.
Raises
from tally data.

can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.

Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False

Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises


Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.FissionXS
class openmc.mgxs.FissionXS(domain=None, domain_type=None, energy_groups=None, nu=False,

prompt=False, by_nuclide=False, name='', num_polar=1, num_azimuthal=1)
A fission multi-group cross section.
homogenized and energy-integrated multi-group fission cross sections for multi-group neutronics calculations.
At a minimum, one needs to set the FissionXS.energy_groups and FissionXS.domain properties. Tal-
FissionXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the FissionXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the fission cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝑑𝐸 𝜎𝑓 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
𝐸𝑔
∫︀ ∫︀ ∫︀ 𝐸𝑔−1 .
𝑟∈𝑉
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔 𝑑𝐸 𝜓(𝑟, 𝐸, Ω)
To incorporate the effect of neutron multiplication in the above relation, the nu parameter can be set to True.
This class can also be used to gather a prompt-nu-fission cross section (which only includes the contributions
from prompt neutrons). This is accomplished by setting the FissionXS.prompt attribute to True. Since the
prompt-nu-fission cross section requires neutron multiplication, the nu parameter will automatically be set to
True if prompt is also True.
Parameters
sation
False
defaults to False which includes prompt and delayed in total. Setting this to True will also
set nu to True
Variables

densation
cretization
section
group cross section
group cross section. The keys are strings listed in the FissionXS.tally_keys property

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters

Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray

Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user

Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.
openmc.mgxs.InverseVelocity
class openmc.mgxs.InverseVelocity(domain=None, domain_type=None, energy_groups=None,

An inverse velocity multi-group cross section.
homogenized and energy-integrated multi-group neutron inverse velocities for multi-group neutronics calcu-
lations. The units of inverse velocity are seconds per centimeter. At a minimum, one needs to set the
InverseVelocity.energy_groups and InverseVelocity.domain properties. Tallies for the flux and ap-
propriate reaction rates over the specified domain are generated automatically via the InverseVelocity.
tallies property, which can then be appended to a openmc.Tallies instance.

obtained from the InverseVelocity.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the neutron inverse velocities are calculated by tallying
the flux-weighted inverse velocity and the flux. The inverse velocity is then the flux-weighted inverse velocity
divided by the flux:
∫︀ 𝐸
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜓(𝑟,𝐸,Ω)
∫︀ ∫︀
𝑟∈𝑉 𝑣(𝑟,𝐸)
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
Parameters
condensation
Variables
densation
cretization
section
group cross section

group cross section
Parameters


to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns

Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.

Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters

Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])

(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Returns the units of InverseVelocity.
This method returns the units of an InverseVelocity based on a desired xs_type.
Parameters
‘macro’.
Returns
A string representing the units of the InverseVelocity.
Return type
str
Parameters
‘all’.
to ‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS


Parameters
to ‘all’.
openmc.mgxs.KappaFissionXS
class openmc.mgxs.KappaFissionXS(domain=None, domain_type=None, energy_groups=None,

A recoverable fission energy production rate multi-group cross section.
The recoverable energy per fission, 𝜅, is defined as the fission product kinetic energy, prompt and delayed neutron
kinetic energies, prompt and delayed 𝛾-ray total energies, and the total energy released by the delayed 𝛽 particles.
The neutrino energy does not contribute to this response. The prompt and delayed 𝛾-rays are assumed to deposit
their energy locally.
minimum, one needs to set the KappaFissionXS.energy_groups and KappaFissionXS.domain properties.
Tallies for the flux and appropriate reaction rates over the specified domain are generated automatically via the
KappaFissionXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the KappaFissionXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the recoverable fission energy production rate cross section
is calculated as:
∫︀ ∫︀ ∫︀ 𝐸
𝑟∈𝑉
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜅𝜎𝑓 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉
Parameters
condensation

Variables
densation
cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.

can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.

Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False

Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises


Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.MultiplicityMatrixXS
class openmc.mgxs.MultiplicityMatrixXS(domain=None, domain_type=None, energy_groups=None,

The scattering multiplicity matrix.
imum, one needs to set the MultiplicityMatrixXS.energy_groups and MultiplicityMatrixXS.domain
cally via the MultiplicityMatrixXS.tallies property, which can then be appended to a openmc.Tallies
instance.
obtained from the MultiplicityMatrixXS.xs_tally property.
For a spatial domain 𝑉 , incoming energy group [𝐸𝑔′ , 𝐸𝑔′ −1 ], and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the multi-
plicity is calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ ∫︁ 𝐸𝑔−1 ∑︁
′ ′
⟨𝜐𝜎 𝑠,𝑔 ′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω 𝑑𝐸 𝜐𝑖 𝜎𝑖 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝐷 4𝜋 𝐸𝑔 ′ 4𝜋 𝐸𝑔 𝑖
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ ∫︁ 𝐸𝑔−1 ∑︁
⟨𝜎𝑠,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑Ω 𝑑𝐸 𝜐𝑖 𝜎𝑖 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝐷 4𝜋 𝐸𝑔 ′ 4𝜋 𝐸𝑔 𝑖
⟨𝜐𝜎𝑠,𝑔′ →𝑔 ⟩
𝜐𝑔′ →𝑔 =
⟨𝜎𝑠,𝑔′ →𝑔 ⟩
where 𝜐𝑖 is the multiplicity for the 𝑖-th reaction.

Parameters
condensation
Variables


densation
cretization
section
group cross section
group cross section


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
Returns
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.NuFissionMatrixXS
class openmc.mgxs.NuFissionMatrixXS(domain=None, domain_type=None, energy_groups=None,

by_nuclide=False, name='', num_polar=1, num_azimuthal=1,
prompt=False)
A fission production matrix multi-group cross section.
imum, one needs to set the NuFissionMatrixXS.energy_groups and NuFissionMatrixXS.domain prop-
via the NuFissionMatrixXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the NuFissionMatrixXS.xs_tally property.
For a spatial domain 𝑉 , incoming energy group [𝐸𝑔′ , 𝐸𝑔′ −1 ], and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the fission
production is calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ 𝐸𝑔−1
′ ′
⟨𝜈𝜎𝑓,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜈𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 𝐸𝑔 ′ 𝐸𝑔
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜈𝜎𝑓,𝑔′ →𝑔 𝜑⟩
𝜈𝜎𝑓,𝑔′ →𝑔 =
⟨𝜑⟩
Parameters
sation
defaults to False which includes prompt and delayed in total
Variables


densation
cretization
section
group cross section
group cross section. The keys are strings listed in the NuFissionMatrixXS.tally_keys
property and values are instances of openmc.Tally.


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
Returns
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.ReducedAbsorptionXS
class openmc.mgxs.ReducedAbsorptionXS(domain=None, domain_type=None, energy_groups=None,

A reduced absorption multi-group cross section.
The reduced absorption reaction rate is defined as the difference between absorption and the production of neu-
trons due to (n,xn) reactions.
homogenized and energy-integrated multi-group capture cross sections for multi-group neutronics calculations.
At a minimum, one needs to set the CaptureXS.energy_groups and CaptureXS.domain properties. Tal-
CaptureXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the CaptureXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the reduced absorption cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝐸𝑔
𝑑𝐸 (𝜎𝑎 (𝑟, 𝐸) − 𝜎𝑛,2𝑛 (𝑟, 𝐸) − 2𝜎𝑛,3𝑛 (𝑟, 𝐸) − 3𝜎𝑛,4𝑛 (𝑟, 𝐸)) 𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉

Parameters
condensation
Variables


densation
cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters

Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters

Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame

Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str


Parameters
‘all’.
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.

merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.
openmc.mgxs.ScatterXS
class openmc.mgxs.ScatterXS(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

name='', num_polar=1, num_azimuthal=1, nu=False)
A scattering multi-group cross section.
The scattering cross section is defined as the difference between the total and absorption cross sections.
minimum, one needs to set the ScatterXS.energy_groups and ScatterXS.domain properties. Tallies for
the flux and appropriate reaction rates over the specified domain are generated automatically via the ScatterXS.
tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the ScatterXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the scattering cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝐸𝑔
𝑑𝐸 [𝜎𝑡 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω) − 𝜎𝑎 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)]
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉
To incorporate the effect of scattering multiplication from (n,xn) reactions in the above relation, the nu parameter
can be set to True.

Parameters
sation
False
Variables
densation
cretization
section
group cross section


group cross section. The keys are strings listed in the ScatterXS.tally_keys property
Parameters
to ‘all’.

Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)


Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters


ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float

get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])

Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.


Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters


to ‘all’.
openmc.mgxs.ScatterMatrixXS
class openmc.mgxs.ScatterMatrixXS(domain=None, domain_type=None, energy_groups=None,

by_nuclide=False, name='', num_polar=1, num_azimuthal=1,
nu=False)
A scattering matrix multi-group cross section with the cosine of the change-in-angle represented as one or more
Legendre moments or a histogram.
minimum, one needs to set the ScatterMatrixXS.energy_groups and ScatterMatrixXS.domain proper-
ties. Tallies for the flux and appropriate reaction rates over the specified domain are generated automatically via
the ScatterMatrixXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the ScatterMatrixXS.xs_tally property.
For a spatial domain 𝑉 , incoming energy group [𝐸𝑔′ , 𝐸𝑔′ −1 ], and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the Leg-
endre scattering moments are calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ ∫︁ 𝐸𝑔−1
′ ′
⟨𝜎𝑠,ℓ,𝑔 →𝑔 𝜑⟩ =
′ 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω 𝑑𝐸 𝑃ℓ (Ω · Ω′ )𝜎𝑠 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 𝐸𝑔 ′ 4𝜋 𝐸𝑔
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜎𝑠,ℓ,𝑔′ →𝑔 𝜑⟩
𝜎𝑠,ℓ,𝑔′ →𝑔 =
⟨𝜑⟩
If the order is zero and a 𝑃0 transport-correction is applied (default), the scattering matrix elements are:
∑︀
⟨𝜎𝑠,0,𝑔′ →𝑔 𝜑⟩ − 𝛿𝑔𝑔′ 𝑔′′ ⟨𝜎𝑠,1,𝑔′′ →𝑔 𝜑⟩
𝜎𝑠,𝑔′ →𝑔 =
⟨𝜑⟩
To incorporate the effect of neutron multiplication from (n,xn) reactions in the above relation, the nu parameter
can be set to True.
An alternative form of the scattering matrix is computed when the formulation property is set to ‘consistent’
rather than the default of ‘simple’. This formulation computes the scattering matrix multi-group cross section as
the product of the scatter cross section and group-to-group scattering probabilities.
Unlike the default ‘simple’ formulation, the ‘consistent’ formulation is computed from the groupwise scattering
cross section which uses a tracklength estimator. This ensures that reaction rate balance is exactly preserved with
a TotalXS computed using a tracklength estimator.
For a scattering probability matrix 𝑃𝑠,ℓ,𝑔′ →𝑔 and scattering cross section 𝜎𝑠 (𝑟, 𝐸) for incoming energy group
[𝐸𝑔′ , 𝐸𝑔′ −1 ] and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the Legendre scattering moments are calculated as:
𝜎𝑠,ℓ,𝑔′ →𝑔 = 𝜎𝑠 (𝑟, 𝐸) × 𝑃𝑠,ℓ,𝑔′ →𝑔

To incorporate the effect of neutron multiplication from (n,xn) reactions in the ‘consistent’ scattering matrix, the
nu parameter can be set to True such that the Legendre scattering moments are calculated as:
𝜎𝑠,ℓ,𝑔′ →𝑔 = 𝜐𝑔′ →𝑔 × 𝜎𝑠 (𝑟, 𝐸) × 𝑃𝑠,ℓ,𝑔′ →𝑔
Parameters
sation
• num_polar (int, optional) – Number of equi-width polar angle bins for angle discretiza-
tion; defaults to one bin
• num_azimuthal (int, optional) – Number of equi-width azimuthal angle bins for angle
False
Variables
• formulation ('simple' or 'consistent') – The calculation approach to use (‘simple’ by
default). The ‘simple’ formulation simply divides the group-to-group scattering rates by the
groupwise flux, each computed from analog tally estimators. The ‘consistent’ formulation
multiplies the groupwise scattering rates by the group-to-group scatter probability matrix,
the former computed from tracklength tallies and the latter computed from analog tallies.
The ‘consistent’ formulation is designed to better conserve reaction rate balance with the
total and absorption cross sections computed using tracklength tally estimators.
• correction ('P0' or None) – Apply the P0 correction to scattering matrices if set to ‘P0’;
this is used only if ScatterMatrixXS.scatter_format is ‘legendre’
• scatter_format ({'legendre', or 'histogram'}) – Representation of the angular scat-
tering distribution (default is ‘legendre’)
• legendre_order (int) – The highest Legendre moment in the scattering matrix; this is
used if ScatterMatrixXS.scatter_format is ‘legendre’. (default is 0)
• histogram_bins (int) – The number of equally-spaced bins for the histogram rep-
resentation of the angular scattering distribution; this is used if ScatterMatrixXS.
scatter_format is ‘histogram’. (default is 16)


densation
• num_polar (int) – Number of equi-width polar angle bins for angle discretization
• num_azimuthal (int) – Number of equi-width azimuthal angle bins for angle discretization
section
group cross section
group cross section. The keys are strings listed in the ScatterMatrixXS.tally_keys

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters

‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
get_pandas_dataframe(groups='all', nuclides='all', xs_type='macro', paths=False)
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
get_slice(nuclides=[], in_groups=[], out_groups=[], legendre_order='same')
Build a sliced ScatterMatrix for the specified nuclides and energy groups.
input parameters.
Parameters
is [])
• legendre_order (int or 'same') – The highest Legendre moment in the sliced MGXS.
If order is ‘same’ then the sliced MGXS will have the same Legendre moments as the
original MGXS (default). If order is an integer less than the original MGXS’ order, then
only those Legendre moments up to that order will be included in the sliced MGXS.
Returns
A new MatrixMGXS which encapsulates the subset of data requested for the nuclide(s) and/or
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
get_xs(in_groups='all', out_groups='all', subdomains='all', nuclides='all', moment='all', xs_type='macro',
order_groups='increasing', row_column='inout', value='mean', squeeze=True)
This method constructs a 5D NumPy array for the requested multi-group cross section data for one or
more subdomains (1st dimension), energy groups in (2nd dimension), energy groups out (3rd dimension),
nuclides (4th dimension), and moments/histograms (5th dimension).
Note: The scattering moments are not multiplied by the (2ℓ + 1)/2 prefactor in the expansion of the
scattering source into Legendre moments in the neutron transport equation.
Parameters
to ‘all’.
• moment (int or 'all') –
The scattering matrix moment to return. All moments will be
returned if the moment is ‘all’ (default); otherwise, a specific moment will be returned.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
print_xs(subdomains='all', nuclides='all', xs_type='macro', moment=0)
Parameters
to ‘all’.
• moment (int) – The scattering moment to print (default is 0)

openmc.mgxs.ScatterProbabilityMatrix
class openmc.mgxs.ScatterProbabilityMatrix(domain=None, domain_type=None, energy_groups=None,

by_nuclide=False, name='', num_polar=1,
num_azimuthal=1)
The group-to-group scattering probability matrix.
This class can be used for both OpenMC input generation and tally data post-processing to compute
spatially-homogenized and energy-integrated multi-group cross sections for multi-group neutronics cal-
culations. At a minimum, one needs to set the ScatterProbabilityMatrix.energy_groups and
ScatterProbabilityMatrix.domain properties. Tallies for the appropriate reaction rates over the speci-
fied domain are generated automatically via the ScatterProbabilityMatrix.tallies property, which can
then be appended to a openmc.Tallies instance.
obtained from the ScatterProbabilityMatrix.xs_tally property.
For a spatial domain 𝑉 , incoming energy group [𝐸𝑔′ , 𝐸𝑔′ −1 ], and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the group-
to-group scattering probabilities are calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ ∫︁ 𝐸𝑔−1
′ ′
⟨𝜎𝑠,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω 𝑑𝐸 𝜎𝑠 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 𝐸𝑔 ′ 4𝜋 𝐸𝑔
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ ∫︁ ∞
′ ′
⟨𝜎 𝑠,0,𝑔 ′ 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω 𝑑𝐸 𝜎𝑠 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 𝐸𝑔 ′ 4𝜋 0
⟨𝜎𝑠,𝑔′ →𝑔 𝜑⟩
𝑃𝑠,𝑔′ →𝑔 =
⟨𝜎𝑠,𝑔′ 𝜑⟩
Parameters
condensation
Variables


densation
cretization
section
group cross section
group cross section


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
Returns
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.TotalXS
class openmc.mgxs.TotalXS(domain=None, domain_type=None, energy_groups=None, by_nuclide=False,

A total multi-group cross section.
homogenized and energy-integrated multi-group total cross sections for multi-group neutronics calculations. At a
minimum, one needs to set the TotalXS.energy_groups and TotalXS.domain properties. Tallies for the flux
and appropriate reaction rates over the specified domain are generated automatically via the TotalXS.tallies
property, which can then be appended to a openmc.Tallies instance.
obtained from the TotalXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the total cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸𝑔−1
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝐸𝑔
𝑑𝐸 𝜎𝑡 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀ ∫︀ 𝐸𝑔−1 .
𝑟∈𝑉
Parameters
condensation
Variables
densation

cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.

Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns

Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters

Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame

Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str


Parameters
‘all’.
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.

merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.
openmc.mgxs.TransportXS
class openmc.mgxs.TransportXS(domain=None, domain_type=None, energy_groups=None, nu=False,

A transport-corrected total multi-group cross section.
minimum, one needs to set the TransportXS.energy_groups and TransportXS.domain properties. Tal-
TransportXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the TransportXS.xs_tally property.

For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the transport-corrected total cross section is calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜎𝑡 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸𝜎𝑡 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︁ ∫︁ ∫︁ 𝐸𝑔−1 ∫︁ ∫︁ ∞ ∫︁ 1
⟨𝜎𝑠1 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝜇 𝜇𝜎𝑠 (𝑟, 𝐸 ′ → 𝐸, Ω′ · Ω)𝜑(𝑟, 𝐸 ′ , Ω)
𝑟∈𝑉 4𝜋 𝐸𝑔 4𝜋 0 −1
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜎𝑡 𝜑⟩ − ⟨𝜎𝑠1 𝜑⟩
𝜎𝑡𝑟 =
⟨𝜑⟩
To incorporate the effect of scattering multiplication in the above relation, the nu parameter can be set to True.
Parameters
sation
False.
Variables
densation
cretization


section
group cross section
group cross section. The keys are strings listed in the TransportXS.tally_keys property
Parameters


to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.

Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises


reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type

Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.

input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str

Parameters
‘all’.
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)

Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.
openmc.mgxs.ArbitraryXS
class openmc.mgxs.ArbitraryXS(rxn_type, domain=None, domain_type=None, energy_groups=None,

A multi-group cross section for an arbitrary reaction type.
homogenized and energy-integrated multi-group total cross sections for multi-group neutronics calculations.
At a minimum, one needs to set the ArbitraryXS.energy_groups and ArbitraryXS.domain properties.
ArbitraryXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the ArbitraryXS.xs_tally property.
For a spatial domain 𝑉 and energy group [𝐸𝑔 , 𝐸𝑔−1 ], the requested cross section is calculated as:
∫︀ ∫︀ ∫︀ 𝐸
𝑟∈𝑉
𝑑𝑟 4𝜋
𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜎𝑋 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀ ∫︀ 𝐸
𝑟∈𝑉
where 𝜎𝑋 is the requested reaction type of interest.

Parameters
condensation

Variables
densation
cretization
section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.

can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.

Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False

Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises


Parameters
‘all’.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.ArbitraryMatrixXS
class openmc.mgxs.ArbitraryMatrixXS(rxn_type, domain=None, domain_type=None, energy_groups=None,

A multi-group matrix cross section for an arbitrary reaction type.
imum, one needs to set the ArbitraryMatrixXS.energy_groups and ArbitraryMatrixXS.domain prop-
via the ArbitraryMatrixXS.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the ArbitraryMatrixXS.xs_tally property.
For a spatial domain 𝑉 , incoming energy group [𝐸𝑔′ , 𝐸𝑔′ −1 ], and outgoing energy group [𝐸𝑔 , 𝐸𝑔−1 ], the fission
production is calculated as:
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ 𝐸𝑔−1
′ ′
⟨𝜎𝑋,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜎𝑋 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
⟨𝜎𝑋,𝑔′ →𝑔 𝜑⟩
𝜎𝑋,𝑔′ →𝑔 =
⟨𝜑⟩
where 𝜎𝑋 is the requested reaction type of interest.

Parameters
condensation
Variables


densation
cretization
section
group cross section
group cross section


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation
to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
Returns
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
to ‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

openmc.mgxs.MeshSurfaceMGXS
class openmc.mgxs.MeshSurfaceMGXS(domain=None, domain_type=None, energy_groups=None,

by_nuclide=False, name='')
An abstract multi-group cross section for some energy group structure on the surfaces of a mesh domain.
This class can be used for both OpenMC input generation and tally data post-processing to compute surface- and
energy-integrated multi-group cross sections for multi-group neutronics calculations.

Parameters
• domain (openmc.RegularMesh) – The domain for spatial homogenization
• domain_type ({'mesh'}) – The domain type for spatial homogenization
condensation
Variables
• domain (Mesh ) – Domain for spatial homogenization
• domain_type ({'mesh'}) – Domain type for spatial homogenization
densation
section
group cross section
• estimator ({'analog'}) – The tally estimator used to compute the multi-group cross section
group cross section

• num_subdomains (int) – The number of subdomains is equal to the number of mesh sur-
faces times two to account for both the incoming and outgoing current from the mesh cell
surfaces.
• num_nuclides (int) – Unused in MeshSurfaceMGXS
• nuclides (Iterable of str or 'sum') – Unused in MeshSurfaceMGXS
Parameters
to ‘all’.

Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.


Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
ergy condensation

to False
Returns
the user
Return type
openmc.mgxs.MGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises


Parameters
‘all’.
length of 1.
• xs_type ({'macro'}) – ‘micro’ unused in MeshSurfaceMGXS.
Returns
Return type
pandas.DataFrame
Raises
from tally data.
input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
Returns
Return type
openmc.mgxs.MGXS
Parameters

Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.
length of 1.
• xs_type ({'macro'}) – The ‘macro’/’micro’ distinction does not apply to MeshSur-
faceMGXS. The calculation of a ‘micro’ xs_type is omited in this class.
Returns
Return type
numpy.ndarray

Raises
from tally data.
Note: The statepoint must first be linked with a openmc.Summary object.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MGXS
Parameters
to ‘all’.

6.5.3 Multi-delayed-group Cross Sections
openmc.mgxs.MDGXS An abstract multi-delayed-group cross section for some

energy and delayed group structures within some spatial
domain.
openmc.mgxs.MatrixMDGXS An abstract multi-delayed-group cross section for some
energy group and delayed group structure within some
spatial domain.
openmc.mgxs.ChiDelayed The delayed fission spectrum.
openmc.mgxs.DelayedNuFissionXS A fission delayed neutron production multi-group cross
section.
openmc.mgxs.DelayedNuFissionMatrixXS A fission delayed neutron production matrix multi-group
cross section.
openmc.mgxs.Beta The delayed neutron fraction.
openmc.mgxs.DecayRate The decay rate for delayed neutron precursors.
openmc.mgxs.MDGXS
class openmc.mgxs.MDGXS(domain=None, domain_type=None, energy_groups=None, delayed_groups=None,

An abstract multi-delayed-group cross section for some energy and delayed group structures within some spatial
domain.
homogenized and energy-integrated multi-group and multi-delayed-group cross sections for downstream neu-
tronics calculations.
NOTE: Users should instantiate the subclasses of this abstract class.
Parameters
condensation
• delayed_groups (list of int, optional) – Delayed groups to filter out the xs
Variables
• rxn_type (str) – Reaction type (e.g., ‘chi-delayed’, ‘beta’, etc.)

densation
cretization
section
group cross section
• estimator ({'tracklength', 'analog'}) – The tally estimator used to compute the multi-
group cross section
group cross section
• num_subdomains (int) – The number of subdomains is unity for ‘material’, ‘cell’, and
‘universe’ domain types. This is equal to the number of cell instances for ‘distribcell’ domain

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
export_xs_data(filename='mgxs', directory='mgxs', format='csv', groups='all', xs_type='macro',
delayed_groups='all')

Export the multi-delayed-group cross section data to a file.

Parameters
‘all’.
• delayed_groups (list of int or 'all') – Delayed groups of interest. Defaults to
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.

Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
static get_mgxs(mdgxs_type, domain=None, domain_type=None, energy_groups=None,
delayed_groups=None, by_nuclide=False, name='', num_polar=1, num_azimuthal=1)
Return a MDGXS subclass object for some energy group structure within some spatial domain for some
reaction type.
This is a factory method which can be used to quickly create MDGXS subclass objects for various reaction
types.
Parameters
• mdgxs_type ({'delayed-nu-fission', 'chi-delayed', 'beta', 'decay-rate',
'delayed-nu-fission matrix'}) – The type of multi-delayed-group cross section
object to return
• domain (openmc.Material or openmc.Cell or openmc.Universe or) –
openmc.RegularMesh The domain for spatial homogenization
ergy condensation
to False
• num_azimuthal (Integral, optional) – Number of equi-width azimuthal angle bins
for angle discretization; defaults to one bin

Returns
A subclass of the abstract MDGXS class for the multi-delayed-group cross section type re-
quested by the user
Return type
openmc.mgxs.MDGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
get_pandas_dataframe(groups='all', nuclides='all', xs_type='macro', paths=True, delayed_groups='all')
Build a Pandas DataFrame for the MDGXS data.
Parameters
‘all’.


‘all’.
Returns
Return type
pandas.DataFrame
Raises
ValueError – When this method is called before the multi-delayed-group cross section is
computed from tally data.
get_slice(nuclides=[], groups=[], delayed_groups=[])
Build a sliced MDGXS for the specified nuclides, energy groups, and delayed groups.
This method constructs a new MDGXS to encapsulate a subset of the data represented by this MDGXS.
The subset of data to include in the tally slice is determined by the nuclides, energy groups, delayed groups
specified in the input parameters.
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
• delayed_groups (list of int) – A list of delayed group indices (e.g., [1, 2, 3]; default
is [])
Returns
A new MDGXS object which encapsulates the subset of data requested for the nuclide(s)
and/or energy group(s) and/or delayed group(s) requested in the parameters.
Return type
openmc.mgxs.MDGXS
Parameters
Returns

Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
value='mean', delayed_groups='all', squeeze=True, **kwargs)
Returns an array of multi-delayed-group cross sections.
This method constructs a 4D NumPy array for the requested multi-delayed-group cross section data for one
or more subdomains (1st dimension), delayed groups (2nd demension), energy groups (3rd dimension),
and nuclides (4th dimension).
Parameters
‘all’.
to ‘all’.
‘all’.
Returns
and nuclide as listed in the parameters.

Return type
numpy.ndarray
Raises
Parameters
Raises
summary object.
merge(other)
Parameters
other (openmc.mgxs.MDGXS) – MDGXS to merge with this one
Returns
merged_mdgxs – Merged MDGXS
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.MatrixMDGXS
class openmc.mgxs.MatrixMDGXS(domain=None, domain_type=None, energy_groups=None,

delayed_groups=None, by_nuclide=False, name='', num_polar=1,
num_azimuthal=1)
An abstract multi-delayed-group cross section for some energy group and delayed group structure within some
spatial domain. This class is specifically intended for cross sections which depend on both the incoming and
outgoing energy groups and are therefore represented by matrices. An example of this is the delayed-nu-fission
matrix.
homogenized and energy-integrated multi-group and multi-delayed-group cross sections for downstream neu-
tronics calculations.
NOTE: Users should instantiate the subclasses of this abstract class.
Parameters
condensation
• delayed_groups (list of int) – Delayed groups to filter out the xs
Variables
densation
cretization


section
group cross section
group cross section

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters
‘all’.


‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises
Parameters
Returns

Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False
Returns
quested by the user
Return type
openmc.mgxs.MDGXS
domain.
Parameters

Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.
‘all’.
Returns

Return type
pandas.DataFrame
Raises
get_slice(nuclides=[], in_groups=[], out_groups=[], delayed_groups=[])
Build a sliced MatrixMDGXS object for the specified nuclides and energy groups.
This method constructs a new MdGXS to encapsulate a subset of the data represented by this MdGXS. The
subset of data to include in the tally slice is determined by the nuclides, energy groups, and delayed groups
Parameters
is [])
is [])
Returns
A new MatrixMDGXS object which encapsulates the subset of data requested for the nu-
clide(s) and/or energy group(s) requested in the parameters.
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.

Returns
Return type
str
order_groups='increasing', row_column='inout', value='mean', delayed_groups='all', squeeze=True,
**kwargs)
subdomains (1st dimension), delayed groups (2nd dimension), energy groups in (3rd dimension), energy
groups out (4th dimension), and nuclides (5th dimension).
Parameters
to ‘all’.
‘all’.
Returns
Return type
numpy.ndarray
Raises
from tally data.

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.ChiDelayed
class openmc.mgxs.ChiDelayed(domain=None, domain_type=None, energy_groups=None,

num_azimuthal=1)
The delayed fission spectrum.
homogenized and energy-integrated multi-group and multi-delayed-group cross sections for multi-group neu-
tronics calculations. At a minimum, one needs to set the ChiDelayed.energy_groups and ChiDelayed.
domain properties. Tallies for the flux and appropriate reaction rates over the specified domain are generated
automatically via the ChiDelayed.tallies property, which can then be appended to a openmc.Tallies in-
stance.
obtained from the ChiDelayed.xs_tally property.
For a spatial domain 𝑉 , energy group [𝐸𝑔 , 𝐸𝑔−1 ], and delayed group 𝑑, the delayed fission spectrum is calculated
as:
∫︁ ∫︁ ∫︁ ∞ ∫︁ 𝐸𝑔−1
⟨𝜈 𝑑 𝜎𝑓,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝐸 𝜒(𝐸)𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 𝐸𝑔
∫︁ ∫︁ ∫︁ ∞ ∫︁∞
⟨𝜈 𝑑 𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝐸 𝜒(𝐸)𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
𝑑
⟨𝜈 𝜎𝑓,𝑔′ →𝑔 𝜑⟩
𝜒𝑑𝑔 =
⟨𝜈 𝑑 𝜎𝑓 𝜑⟩
Parameters
sation
Variables


densation
cretization
section
group cross section
group cross section. The keys are strings listed in the ChiDelayed.tally_keys property


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray

Raises
Construct a homogenized MGXS with other MGXS objects.
This method constructs a new MGXS object that is the flux-weighted combination of two MGXS objects. It
is equivalent to what one would obtain if the tally spatial domain were designed to encompass the individual
domains for both MGXS objects.
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False

Returns
quested by the user
Return type
openmc.mgxs.MDGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.


‘all’.
Returns
Return type
pandas.DataFrame
Raises
Build a sliced ChiDelayed for the specified nuclides and energy

groups.
input parameters.
Parameters
is [])
• groups (list of Integral) – A list of energy group indices starting at 1 for the high
energies (e.g., [1, 2, 3]; default is [])
is [])
Returns
A new MDGXS which encapsulates the subset of data requested for the nuclide(s) and/or
energy group(s) and/or delayed group(s) requested in the parameters.
Return type
openmc.mgxs.MDGXS
Parameters

Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Returns an array of the delayed fission spectrum.
Parameters
‘all’.
‘all’.
to ‘all’.
• xs_type ({'macro', 'micro'}) – This parameter is not relevant for chi but is included here
to mirror the parent MGXS.get_xs(. . . ) class method

Returns
A NumPy array of the multi-group and multi-delayed-group cross section indexed in the order
each group, subdomain and nuclide is listed in the parameters.
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Merge another ChiDelayed with this one
If results have been loaded from a statepoint, then ChiDelayed are only mergeable along one and only one
of energy groups or nuclides.
Parameters
other (openmc.mdgxs.MGXS) – MGXS to merge with this one
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.DelayedNuFissionXS
class openmc.mgxs.DelayedNuFissionXS(domain=None, domain_type=None, energy_groups=None,

num_azimuthal=1)
A fission delayed neutron production multi-group cross section.
homogenized and energy-integrated multi-group fission neutron production cross sections for multi-group
neutronics calculations. At a minimum, one needs to set the DelayedNuFissionXS.energy_groups and
DelayedNuFissionXS.domain properties. Tallies for the flux and appropriate reaction rates over the speci-
fied domain are generated automatically via the DelayedNuFissionXS.tallies property, which can then be
appended to a openmc.Tallies instance.
obtained from the DelayedNuFissionXS.xs_tally property.
For a spatial domain 𝑉 , energy group [𝐸𝑔 , 𝐸𝑔−1 ], and delayed group 𝑑, the fission delayed neutron production
∫︀ 𝐸
𝑑𝑟 4𝜋 𝑑Ω 𝐸𝑔𝑔−1 𝑑𝐸 𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸)𝜓(𝑟, 𝐸, Ω)
∫︀ ∫︀
𝑟∈𝑉
∫︀ ∫︀ ∫︀ 𝐸 .
𝑟∈𝑉
Parameters
sation
Variables


densation
cretization
section
group cross section
group cross section
group cross section. The keys are strings listed in the DelayedNuFissionXS.tally_keys

Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters

‘all’.
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray
Raises

Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False
Returns
quested by the user
Return type
openmc.mgxs.MDGXS
domain.

Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

‘all’.
Returns
Return type
pandas.DataFrame
Raises
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
is [])
Returns
Return type
openmc.mgxs.MDGXS
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
from tally data.

Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.
‘all’.
Returns
Return type
numpy.ndarray
Raises

Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.DelayedNuFissionMatrixXS
class openmc.mgxs.DelayedNuFissionMatrixXS(domain=None, domain_type=None, energy_groups=None,

delayed_groups=None, by_nuclide=False, name='',
num_polar=1, num_azimuthal=1)
A fission delayed neutron production matrix multi-group cross section.
homogenized and energy-integrated multi-group fission neutron production cross sections for multi-group neu-
tronics calculations. At a minimum, one needs to set the DelayedNuFissionMatrixXS.energy_groups and
DelayedNuFissionMatrixXS.domain properties. Tallies for the flux and appropriate reaction rates over the
specified domain are generated automatically via the DelayedNuFissionMatrixXS.tallies property, which
can then be appended to a openmc.Tallies instance.
obtained from the DelayedNuFissionMatrixXS.xs_tally property.
For a spatial domain 𝑉 , energy group [𝐸𝑔 , 𝐸𝑔−1 ], and delayed group 𝑑, the fission delayed neutron production
∫︁ ∫︁ ∫︁ 𝐸𝑔′ −1 ∫︁ 𝐸𝑔−1
⟨𝜈𝜎𝑓,𝑔′ →𝑔 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝐸 𝜒(𝐸)𝜈𝜎𝑓𝑑 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
∫︁ ∫︁ ∫︁ 𝐸𝑔−1
𝑑
⟨𝜈𝜎𝑓,𝑔 ′ →𝑔 𝜑⟩
𝜈𝜎𝑓,𝑔′ →𝑔 =
⟨𝜑⟩
Parameters
sation
Variables


densation
cretization
section
group cross section
group cross section. The keys are strings listed in the DelayedNuFissionXS.tally_keys


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray

Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False
Returns
quested by the user
Return type
openmc.mgxs.MDGXS

domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.

‘all’.
Returns
Return type
pandas.DataFrame
Raises
get_slice(nuclides=[], in_groups=[], out_groups=[], delayed_groups=[])
Build a sliced MatrixMDGXS object for the specified nuclides and energy groups.
This method constructs a new MdGXS to encapsulate a subset of the data represented by this MdGXS. The
subset of data to include in the tally slice is determined by the nuclides, energy groups, and delayed groups
Parameters
is [])
is [])
Returns
A new MatrixMDGXS object which encapsulates the subset of data requested for the nu-
clide(s) and/or energy group(s) requested in the parameters.
Return type
Parameters
Returns
Return type
openmc.mgxs.MGXS

Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
order_groups='increasing', row_column='inout', value='mean', delayed_groups='all', squeeze=True,
**kwargs)
subdomains (1st dimension), delayed groups (2nd dimension), energy groups in (3rd dimension), energy
groups out (4th dimension), and nuclides (5th dimension).
Parameters
to ‘all’.
‘all’.

Returns
Return type
numpy.ndarray
Raises
from tally data.
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.Beta
class openmc.mgxs.Beta(domain=None, domain_type=None, energy_groups=None, delayed_groups=None,

The delayed neutron fraction.
homogenized and energy-integrated multi-group and multi-delayed group cross sections for multi-group neu-
tronics calculations. At a minimum, one needs to set the Beta.energy_groups and Beta.domain properties.
Beta.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the Beta.xs_tally property.
For a spatial domain 𝑉 , energy group [𝐸𝑔 , 𝐸𝑔−1 ], and delayed group 𝑑, the delayed neutron fraction is calculated
as:
∫︁ ∫︁ ∫︁ ∞ ∫︁ ∞
′ ′
𝑑
⟨𝜈 𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
∫︁ ∫︁ ∫︁ ∞ ∫︁ ∞
′ ′
⟨𝜈𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜈𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
𝛽𝑑,𝑔 =
⟨𝜈𝜎𝑓 𝜑⟩
NOTE: The Beta MGXS is the delayed neutron fraction computed directly from the nuclear data. Often the
delayed neutron fraction is “importance-weighted” by the adjoint flux and called “beta-effective”. It is important
to make clear that this Beta is not importance-weighted.
Parameters
sation
Variables


densation
cretization
section
group cross section
group cross section
group cross section. The keys are strings listed in the Beta.tally_keys property and values
are instances of openmc.Tally.


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters

Parameters
‘all’.
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray

Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False

Returns
quested by the user
Return type
openmc.mgxs.MDGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.


‘all’.
Returns
Return type
pandas.DataFrame
Raises
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
is [])
Returns
Return type
openmc.mgxs.MDGXS
Parameters
Returns

Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
Parameters
‘all’.
to ‘all’.
‘all’.
Returns

Return type
numpy.ndarray
Raises
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

openmc.mgxs.DecayRate
class openmc.mgxs.DecayRate(domain=None, domain_type=None, energy_groups=None,

num_azimuthal=1)
The decay rate for delayed neutron precursors.
homogenized and energy-integrated multi-group and multi-delayed group cross sections for multi-group neu-
tronics calculations. At a minimum, one needs to set the DecayRate.energy_groups and DecayRate.domain
cally via the DecayRate.tallies property, which can then be appended to a openmc.Tallies instance.
obtained from the DecayRate.xs_tally property.
For a spatial domain 𝑉 , energy group [𝐸𝑔 , 𝐸𝑔−1 ], and delayed group 𝑑, the decay rate is calculated as:
∫︁ ∫︁ ∫︁ ∞ ∫︁ ∞
⟨𝜆𝑑 𝜈 𝑑 𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω′ 𝑑𝐸 ′ 𝑑𝐸 𝜆𝑑 𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
∫︁ ∫︁ ∫︁ ∞ ∫︁ ∞
′ ′
𝑑
⟨𝜈 𝜎𝑓 𝜑⟩ = 𝑑𝑟 𝑑Ω 𝑑𝐸 𝑑𝐸 𝜒(𝐸)𝜈 𝑑 𝜎𝑓 (𝑟, 𝐸 ′ )𝜓(𝑟, 𝐸 ′ , Ω′ )
𝑟∈𝑉 4𝜋 0 0
⟨𝜆𝑑 𝜈 𝑑 𝜎𝑓 𝜑⟩
𝜆𝑑 =
Parameters
sation
Variables


densation
cretization
section
group cross section
group cross section
group cross section. The keys are strings listed in the DecayRate.tally_keys property


Parameters
to ‘all’.
Raises
from tally data.
can_merge(other)
Parameters
Parameters


‘all’.
‘all’.
Parameters
interest
Returns
Return type
MGXS
**kwargs)
Parameters
‘all’.
to ‘all’.
Returns
parameters.
Return type
numpy.ndarray

Raises
Parameters
Returns
Return type
openmc.mgxs.MGXS
Raises
reaction type.
types.
Parameters
object to return
ergy condensation
to False

Returns
quested by the user
Return type
openmc.mgxs.MDGXS
domain.
Parameters
Returns
domain
Return type
Raises
Parameters
Returns
Return type
float
get_nuclides()
Returns
Return type
list of str
Raises
Parameters
‘all’.


‘all’.
Returns
Return type
pandas.DataFrame
Raises
Parameters
is [])
(e.g., [1, 2, 3]; default is [])
is [])
Returns
Return type
openmc.mgxs.MDGXS
Parameters
Returns

Return type
openmc.mgxs.MGXS
Raises
from tally data.
Parameters
‘macro’.
Returns
Return type
str
get_xs(subdomains='all', nuclides='all', xs_type='macro', order_groups='increasing', value='mean',
delayed_groups='all', squeeze=True, **kwargs)
Parameters
to ‘all’.
‘all’.
Returns
Return type
numpy.ndarray

Raises
Parameters
Raises
summary object.
merge(other)
Parameters
Returns
Return type
openmc.mgxs.MDGXS
Parameters
to ‘all’.

6.5.4 Multi-group Cross Section Libraries
openmc.mgxs.Library A multi-energy-group and multi-delayed-group cross

section library for some energy group structure.
openmc.mgxs.Library
class openmc.mgxs.Library(geometry, by_nuclide=False, mgxs_types=None, name='')

A multi-energy-group and multi-delayed-group cross section library for some energy group structure.
homogenized and energy-integrated multi-group cross sections for deterministic neutronics calculations.
This class helps automate the generation of MGXS and MDGXS objects for some energy group structure and
domain type. The Library serves as a collection for MGXS and MDGXS objects with routines to automate the
initialization of tallies for input files, the loading of tally data from statepoint files, data storage, energy group
condensation and more.
Parameters
• geometry (openmc.Geometry) – A geometry which has been initialized with a root uni-
verse
• by_nuclide (bool) – If true, computes cross sections for each nuclide in each domain
• mgxs_types (Iterable of str) – The types of cross sections in the library (e.g., [‘total’,
‘scatter’])
• name (str, optional) – Name of the multi-group cross section library. Used as a label to
identify tallies in OpenMC ‘tallies.xml’ file.
Variables
• geometry (openmc.Geometry) – An geometry which has been initialized with a root uni-
verse
• by_nuclide (bool) – If true, computes cross sections for each nuclide in each domain
• mgxs_types (Iterable of str) – The types of cross sections in the library (e.g., [‘total’,
‘scatter’])
• domains (Iterable of openmc.Material, openmc.Cell, openmc.Universe or
openmc.RegularMesh) – The spatial domain(s) for which MGXS in the Library are
computed
• correction ({'P0', None}) – Apply the P0 correction to scattering matrices if set to ‘P0’
• scatter_format ({'legendre', 'histogram'}) – Representation of the angular scattering
distribution (default is ‘legendre’)
• legendre_order (int) – The highest Legendre moment in the scattering matrix; this is
used if ScatterMatrixXS.scatter_format is ‘legendre’. (default is 0)
• histogram_bins (int) – The number of equally-spaced bins for the histogram rep-
resentation of the angular scattering distribution; this is used if ScatterMatrixXS.
scatter_format is ‘histogram’. (default is 16)


densation
cretization
• estimator (str or None) – The tally estimator used to compute multi-group cross sec-
tions. If None, the default for each MGXS type is used.
• all_mgxs (collections.OrderedDict) – MGXS objects keyed by domain ID and cross
section type
• sp_filename (str) – The filename of the statepoint with tally data used to the compute
cross sections
• keff (Real or None) – The combined keff from the statepoint file with tally data used to
compute cross sections (for eigenvalue calculations only)
• name (str, optional) – Name of the multi-group cross section library. Used as a label to
identify tallies in OpenMC ‘tallies.xml’ file.
• sparse (bool) – Whether or not the Library’s tallies use SciPy’s LIL sparse matrix format
add_to_tallies_file(tallies_file, merge=True)
Add all tallies from all MGXS objects to a tallies file.
NOTE: This assumes that Library.build_library() has been called
Parameters
• tallies_file (openmc.Tallies) – A Tallies collection to add each MGXS’ tallies to
generate a ‘tallies.xml’ input file for OpenMC
• merge (bool) – Indicate whether tallies should be merged when possible. Defaults to True.
xs_type='macro', row_column='inout', libver='earliest')
Export the multi-group cross section library to an HDF5 binary file.
This method constructs an HDF5 file which stores the library’s multi-group cross section data. The data
is stored in a hierarchy of HDF5 groups from the domain type, domain id, subdomain id (for distribcell
domains), nuclides and cross section types. Two datasets for the mean and standard deviation are stored for
each subdomain entry in the HDF5 file. The number of groups is stored as a file attribute.
NOTE: This requires the h5py Python package.
Parameters
• subdomains ({'all', 'avg'}) – Report all subdomains or the average of all subdomain
cross sections in the report. Defaults to ‘all’.

• nuclides ({'all', 'sum'}) – The nuclides of the cross-sections to include in the report.
This may be a list of nuclide name strings (e.g., [‘U235’, ‘U238’]). The special string ‘all’
will report the cross sections for all nuclides in the spatial domain. The special string ‘sum’
will report the cross sections summed over all nuclides. Defaults to ‘all’.
Raises
ValueError – When this method is called before a statepoint has been loaded
See also:
MGXS.build_hdf5_store, directory, xs_type
build_library()
Initialize MGXS objects in each domain and for each reaction type in the library.
This routine will populate the all_mgxs instance attribute dictionary with MGXS subclass objects keyed
by each domain ID (e.g., Material IDs) and cross section type (e.g., ‘nu-fission’, ‘total’, etc.).
check_library_for_openmc_mgxs()
This routine will check the MGXS Types within a Library to ensure the MGXS types provided can be used
to create a MGXS Library for OpenMC’s Multi-Group mode.
The rules to check include:
• Either total or transport must be present.
– Both can be available if one wants, but we should use whatever corresponds to Library.correction
(if P0: transport)
• Absorption is required.
• A nu-fission cross section and chi values are not required as a fixed source problem could be the target.
• Fission and kappa-fission are not required as they are only needed to support tallies the user may wish
to request.
• Scattering multiplicity should have been tallied for increased model accuracy, either using a multiplic-
ity or scatter and nu-scatter matrix tally.
See also:
Library.create_mg_library, Library.create_mg_mode
create_mg_library(xs_type='macro', xsdata_names=None, apply_domain_chi=False)
Creates an openmc.MGXSLibrary object to contain the MGXS data for the Multi-Group mode of OpenMC.
Note that this library will not make use of nested temperature tables. Every dataset in the library will be
treated as if it was at the same default temperature.
Parameters
• xs_type ({'macro', 'micro'}) – Provide the macro or micro cross section in units of cm^-
1 or barns. Defaults to ‘macro’. If the Library object is not tallied by nuclide this will be
set to ‘macro’ regardless.

• xsdata_names (Iterable of str) – List of names to apply to the “xsdata” entries in

the resultant mgxs data file. Defaults to ‘set1’, ‘set2’, . . .
• apply_domain_chi (bool) – This parameter sets whether (True) or not (False) the
domain-averaged values of chi, chi-prompt, and chi-delayed are to be applied to each of
the nuclide-dependent fission energy spectra of a domain. In effect, if this is True, then
every nuclide in the domain receives the same flux-weighted Chi. This is useful for down-
stream multigroup solvers that precompute a material-specific chi before the transport solve
provides group-wise fluxes. Defaults to False.
Returns
mgxs_file – Multi-Group Cross Section File that is ready to be printed to the file of choice by
the user.
Return type
openmc.MGXSLibrary
Raises
ValueError – When the Library object is initialized with insufficient types of cross sections
for the Library.
See also:
Library.dump_to_file, Library.create_mg_mode
create_mg_mode(xsdata_names=None, bc=['reflective', 'reflective', 'reflective', 'reflective', 'reflective',
'reflective'], apply_domain_chi=False)
Creates an openmc.MGXSLibrary object to contain the MGXS data for the Multi-Group mode of OpenMC
as well as the associated openmc.Materials and openmc.Geometry objects.
The created Geometry is the same as that used to generate the MGXS data, with the only differences being
modifications to point to newly-created Materials which point to the multi-group data. This method only
creates a macroscopic MGXS Library even if nuclidic tallies are specified in the Library. Note that this
library will not make use of nested temperature tables. Every dataset in the library will be treated as if it
was at the same default temperature.
Parameters
• xsdata_names (Iterable of str) – List of names to apply to the “xsdata” entries in
the resultant mgxs data file. Defaults to ‘set1’, ‘set2’, . . .
• bc (iterable of {'reflective', 'periodic', 'transmission', or 'vacuum'}) –
Boundary conditions for each of the four faces of a rectangle (if applying to a 2D mesh) or
six faces of a parallelepiped (if applying to a 3D mesh) provided in the following order: [x
min, x max, y min, y max, z min, z max]. 2-D cells do not contain the z min and z max
entries.
Returns
• mgxs_file (openmc.MGXSLibrary) – Multi-Group Cross Section File that is ready to be
printed to the file of choice by the user.
• materials (openmc.Materials) – Materials file ready to be printed with all the macroscopic
data present within this Library.

• geometry (openmc.Geometry) – Materials file ready to be printed with all the macroscopic
data present within this Library.
Raises
for the Library.
See also:
Library.create_mg_library, Library.dump_to_file
dump_to_file(filename='mgxs', directory='mgxs')
Store this Library object in a pickle binary file.
Parameters
• filename (str) – Filename for the pickle file. Defaults to ‘mgxs’.
• directory (str) – Directory for the pickle file. Defaults to ‘mgxs’.
See also:
Library.load_from_file, directory
get_condensed_library(coarse_groups)
Construct an energy-condensed version of this library.
This routine condenses each of the multi-group cross sections in the library to a coarse energy group struc-
ture. NOTE: This routine must be called after the load_from_statepoint(. . . ) routine loads the tallies from
the statepoint into each of the cross sections.
Parameters
interest
Returns
A new multi-group cross section library condensed to the group structure of interest
Return type
openmc.mgxs.Library
Raises
See also:
MGXS.get_condensed_xs
get_mgxs(domain, mgxs_type)
Return the MGXS object for some domain and reaction rate type.
This routine searches the library for an MGXS object for the spatial domain and reaction rate type requested
by the user.
NOTE: This routine must be called after the build_library() routine.
Parameters
RegularMesh or Integral) – The material, cell, or universe object of interest (or its
ID)
• mgxs_type (str) – The type of multi-group cross section object to return; allowable values
are those MGXS to the Library and present in the mgxs_types attribute.

Returns
The MGXS object for the requested domain and reaction rate type
Return type
openmc.mgxs.MGXS
Raises
ValueError – If no MGXS object can be found for the requested domain or multi-group
cross section type
get_subdomain_avg_library()
Construct a subdomain-averaged version of this library.
This routine averages each multi-group cross section across distribcell instances. The method performs
spatial homogenization to compute the scalar flux-weighted average cross section across the subdomains.
NOTE: This method is only relevant for distribcell domain types and simplys returns a deep copy of the
library for all other domains types.
Returns
A new multi-group cross section library averaged across subdomains
Return type
openmc.mgxs.Library
Raises
See also:
MGXS.get_subdomain_avg_xs
get_xsdata(domain, xsdata_name, nuclide='total', xs_type='macro', subdomain=None,
apply_domain_chi=False)
Generates an openmc.XSdata object describing a multi-group cross section dataset for writing to an
openmc.MGXSLibrary object.
Note that this method does not build an XSdata object with nested temperature tables. The temperature of
each XSdata object will be left at the default value of 294K.
Parameters
• xsdata_name (str) – Name to apply to the “xsdata” entry produced by this method
• nuclide (str) – A nuclide name string (e.g., ‘U235’). Defaults to ‘total’ to obtain a
material-wise macroscopic cross section.
• xs_type ({'macro', 'micro'}) – Provide the macro or micro cross section in units of cm^-
1 or barns. Defaults to ‘macro’. If the Library object is not tallied by nuclide this will be
set to ‘macro’ regardless.
• subdomain (iterable of int) – This parameter is not used unless using a mesh do-
main. In that case, the subdomain is an [i,j,k] index (1-based indexing) of the mesh cell of
interest in the openmc.RegularMesh object. Note: this parameter currently only supports
subdomains within a mesh, and not the subdomains of a distribcell.

Returns
xsdata – Multi-Group Cross Section dataset object.
Return type
openmc.XSdata
Raises
for the Library.
See also:
Library.create_mg_library
static load_from_file(filename='mgxs', directory='mgxs')
Load a Library object from a pickle binary file.
Parameters
• filename (str) – Filename for the pickle file. Defaults to ‘mgxs’.
• directory (str) – Directory for the pickle file. Defaults to ‘mgxs’.
Returns
A Library object loaded from the pickle binary file
Return type
openmc.mgxs.Library
See also:
Library.dump_to_file, filename, directory
NOTE: The statepoint must first be linked with an OpenMC Summary object.
Parameters
Raises
summary object.

6.6 openmc.stats – Statistics
6.6.1 Univariate Probability Distributions
openmc.stats.Univariate Probability distribution of a single random variable.

openmc.stats.Discrete Distribution characterized by a probability mass func-
tion.
openmc.stats.Uniform Distribution with constant probability over a finite inter-
val [a,b]
openmc.stats.PowerLaw Distribution with power law probability over a finite in-
terval [a,b]
openmc.stats.Maxwell Maxwellian distribution in energy.
openmc.stats.Watt Watt fission energy spectrum.
openmc.stats.Tabular Piecewise continuous probability distribution.
openmc.stats.Legendre Probability density given by a Legendre polynomial ex-
𝑁
pansion 2ℓ+1
∑︀
2 𝑎ℓ 𝑃ℓ (𝜇).
ℓ=0
openmc.stats.Mixture Probability distribution characterized by a mixture of
random variables.
openmc.stats.Normal Normally distributed sampling.
openmc.stats.Muir Muir energy spectrum.
openmc.stats.Univariate
class openmc.stats.Univariate
Probability distribution of a single random variable.
The Univariate class is an abstract class that can be derived to implement a specific probability distribution.
integral()
Return integral of distribution
Returns
Integral of distribution
Return type
float
abstract sample(seed=None)
Sample the univariate distribution
Parameters
• n_samples (int) – Number of sampled values to generate
• seed (int or None) – Initial random number seed.
Returns
A 1-D array of sampled values
Return type
numpy.ndarray
6.6. openmc.stats – Statistics 681

openmc.stats.Discrete
class openmc.stats.Discrete(x, p)
Distribution characterized by a probability mass function.
The Discrete distribution assigns probability values to discrete values of a random variable, rather than expressing
the distribution as a continuous random variable.
Parameters
• x (Iterable of float) – Values of the random variable
• p (Iterable of float) – Discrete probability for each value
Variables
• x (numpy.ndarray) – Values of the random variable
• p (numpy.ndarray) – Discrete probability for each value
Generate discrete distribution from an XML element
Parameters
Returns
Discrete distribution generated from XML element
Return type
integral()
Returns
Integral of discrete distribution
Return type
float
classmethod merge(dists, probs)
Merge multiple discrete distributions into a single distribution
Parameters
• dists (iterable of openmc.stats.Discrete) – Discrete distributions to combine
• probs (iterable of float) – Probability of each distribution
Returns
Combined discrete distribution
Return type
normalize()
Normalize the probabilities stored on the distribution

sample(n_samples=1, seed=None)
Parameters
Returns
Return type
numpy.ndarray
to_xml_element(element_name)
Return XML representation of the discrete distribution
Parameters
element_name (str) – XML element name
Returns
element – XML element containing discrete distribution data
Return type
openmc.stats.Uniform
class openmc.stats.Uniform(a=0.0, b=1.0)

Distribution with constant probability over a finite interval [a,b]
Parameters
• a (float, optional) – Lower bound of the sampling interval. Defaults to zero.
• b (float, optional) – Upper bound of the sampling interval. Defaults to unity.
Variables
• a (float) – Lower bound of the sampling interval
• b (float) – Upper bound of the sampling interval
Generate uniform distribution from an XML element
Parameters
Returns
Uniform distribution generated from XML element
Return type
openmc.stats.Uniform
Parameters

Returns
Return type
numpy.ndarray
Return XML representation of the uniform distribution
Parameters
Returns
element – XML element containing uniform distribution data
Return type
openmc.stats.PowerLaw
class openmc.stats.PowerLaw(a=0.0, b=1.0, n=0)

Distribution with power law probability over a finite interval [a,b]
The power law distribution has density function 𝑝(𝑥)𝑑𝑥 = 𝑐𝑥𝑛 𝑑𝑥.
Parameters
• a (float, optional) – Lower bound of the sampling interval. Defaults to zero.
• b (float, optional) – Upper bound of the sampling interval. Defaults to unity.
• n (float, optional) – Power law exponent. Defaults to zero, which is equivalent to a
uniform distribution.
Variables
• a (float) – Lower bound of the sampling interval
• b (float) – Upper bound of the sampling interval
• n (float) – Power law exponent
Generate power law distribution from an XML element
Parameters
Returns
Distribution generated from XML element
Return type
openmc.stats.PowerLaw
Parameters

Returns
Return type
numpy.ndarray
Return XML representation of the power law distribution
Parameters
Returns
element – XML element containing distribution data
Return type
openmc.stats.Maxwell
class openmc.stats.Maxwell(theta)
Maxwellian distribution in energy.
The Maxwellian
√ distribution in energy is characterized by a single parameter 𝜃 and has a density function
𝑝(𝐸)𝑑𝐸 = 𝑐 𝐸𝑒−𝐸/𝜃 𝑑𝐸.
Parameters
theta (float) – Effective temperature for distribution in eV
Variables
theta (float) – Effective temperature for distribution in eV
Generate Maxwellian distribution from an XML element
Parameters
Returns
Maxwellian distribution generated from XML element
Return type
openmc.stats.Maxwell
Parameters
Returns
Return type
numpy.ndarray

Return XML representation of the Maxwellian distribution
Parameters
Returns
element – XML element containing Maxwellian distribution data
Return type
openmc.stats.Watt
class openmc.stats.Watt(a=988000.0, b=2.249e-06)

Watt fission energy spectrum.
The Watt fission
√ energy spectrum is characterized by two parameters 𝑎 and 𝑏 and has density function 𝑝(𝐸)𝑑𝐸 =
𝑐𝑒−𝐸/𝑎 sinh 𝑏 𝐸𝑑𝐸.
Parameters
• a (float) – First parameter of distribution in units of eV
• b (float) – Second parameter of distribution in units of 1/eV
Variables
• a (float) – First parameter of distribution in units of eV
• b (float) – Second parameter of distribution in units of 1/eV
Generate Watt distribution from an XML element
Parameters
Returns
Watt distribution generated from XML element
Return type
openmc.stats.Watt
Parameters
Returns
Return type
numpy.ndarray
Return XML representation of the Watt distribution

Parameters
Returns
element – XML element containing Watt distribution data
Return type
openmc.stats.Tabular
class openmc.stats.Tabular(x, p, interpolation='linear-linear', ignore_negative=False)

Piecewise continuous probability distribution.
This class is used to represent a probability distribution whose density function is tabulated at specific values
with a specified interpolation scheme.
Parameters
• x (Iterable of float) – Tabulated values of the random variable
• p (Iterable of float) – Tabulated probabilities
• interpolation ({'histogram', 'linear-linear', 'linear-log', 'log-linear',
'log-log'}, optional) – Indicate whether the density function is constant between
tabulated points or linearly-interpolated. Defaults to ‘linear-linear’.
• ignore_negative (bool) – Ignore negative probabilities
Variables
• x (numpy.ndarray) – Tabulated values of the random variable
• p (numpy.ndarray) – Tabulated probabilities
• interpolation ({'histogram', 'linear-linear', 'linear-log', 'log-linear',
'log-log'}, optional) – Indicate whether the density function is constant between
tabulated points or linearly-interpolated.
Generate tabular distribution from an XML element
Parameters
Returns
Tabular distribution generated from XML element
Return type
openmc.stats.Tabular
integral()
Returns
Integral of tabular distrbution
Return type
float

mean()
Compute the mean of the tabular distribution
normalize()
Parameters
Returns
Return type
numpy.ndarray
Return XML representation of the tabular distribution
Parameters
Returns
element – XML element containing tabular distribution data
Return type
openmc.stats.Legendre
class openmc.stats.Legendre(coefficients)
𝑁
Probability density given by a Legendre polynomial expansion 2ℓ+1
∑︀
2 𝑎ℓ 𝑃ℓ (𝜇).
ℓ=0
Parameters
coefficients (Iterable of Real) – Expansion coefficients 𝑎ℓ . Note that the (2ℓ + 1)/2
factor should not be included.
Variables
coefficients (Iterable of Real) – Expansion coefficients 𝑎ℓ . Note that the (2ℓ + 1)/2
factor should not be included.
Parameters
Returns
Return type
numpy.ndarray

openmc.stats.Mixture
class openmc.stats.Mixture(probability, distribution)

Probability distribution characterized by a mixture of random variables.
Parameters
• probability (Iterable of Real) – Probability of selecting a particular distribution
• distribution (Iterable of Univariate) – List of distributions with corresponding
probabilities
Variables
• probability (Iterable of Real) – Probability of selecting a particular distribution
• distribution (Iterable of Univariate) – List of distributions with corresponding
probabilities
Generate mixture distribution from an XML element
Parameters
Returns
Mixture distribution generated from XML element
Return type
openmc.stats.Mixture
integral()
Return integral of the distribution
Returns
Integral of the distribution
Return type
float
normalize()
Parameters
Returns
Return type
numpy.ndarray

Return XML representation of the mixture distribution
Parameters
Returns
element – XML element containing mixture distribution data
Return type
openmc.stats.Normal
class openmc.stats.Normal(mean_value, std_dev)

Normally distributed sampling.
The Normal Distribution is characterized by two parameters 𝜇 and 𝜎 and has density function 𝑝(𝑋)𝑑𝑋 =
√ 2 2
1/( 2𝜋𝜎)𝑒−(𝑋−𝜇) /(2𝜎 )
Parameters
• mean_value (float) – Mean value of the distribution
• std_dev (float) – Standard deviation of the Normal distribution
Variables
• mean_value (float) – Mean of the Normal distribution
• std_dev (float) – Standard deviation of the Normal distribution
Generate Normal distribution from an XML element
Parameters
Returns
Normal distribution generated from XML element
Return type
openmc.stats.Normal
Parameters
Returns
Return type
numpy.ndarray

Return XML representation of the Normal distribution
Parameters
Returns
Return type
openmc.stats.Muir
class openmc.stats.Muir(e0=14080000.0, m_rat=5.0, kt=20000.0)

Muir energy spectrum.
The Muir energy spectrum is a Gaussian spectrum, but for convenience reasons allows the user 3 parameters to
define the distribution, e0 the mean energy of particles, the mass of reactants m_rat, and the ion temperature kt.
Parameters
• e0 (float) – Mean of the Muir distribution in units of eV
• m_rat (float) – Ratio of the sum of the masses of the reaction inputs to an AMU
• kt (float) – Ion temperature for the Muir distribution in units of eV
Variables
• e0 (float) – Mean of the Muir distribution in units of eV
• m_rat (float) – Ratio of the sum of the masses of the reaction inputs to an AMU
• kt (float) – Ion temperature for the Muir distribution in units of eV
Generate Muir distribution from an XML element
Parameters
Returns
Muir distribution generated from XML element
Return type
openmc.stats.Muir
Parameters
Returns
Return type
numpy.ndarray

Return XML representation of the Watt distribution
Parameters
Returns
Return type
6.6.2 Angular Distributions
openmc.stats.UnitSphere Distribution of points on the unit sphere.

openmc.stats.PolarAzimuthal Angular distribution represented by polar and azimuthal
angles
openmc.stats.Isotropic Isotropic angular distribution.
openmc.stats.Monodirectional Monodirectional angular distribution.
openmc.stats.UnitSphere
class openmc.stats.UnitSphere(reference_uvw=None)
Distribution of points on the unit sphere.
This abstract class is used for angular distributions, since a direction is represented as a unit vector (i.e., vector
on the unit sphere).
Parameters
reference_uvw (Iterable of float) – Direction from which polar angle is measured
Variables
reference_uvw (Iterable of float) – Direction from which polar angle is measured
openmc.stats.PolarAzimuthal
class openmc.stats.PolarAzimuthal(mu=None, phi=None, reference_uvw=(0.0, 0.0, 1.0))

Angular distribution represented by polar and azimuthal angles
This distribution allows one to specify the distribution of the cosine of the polar angle and the azimuthal angle
independently of one another. The polar angle is measured relative to the reference angle.
Parameters
• mu (openmc.stats.Univariate) – Distribution of the cosine of the polar angle
• phi (openmc.stats.Univariate) – Distribution of the azimuthal angle in radians
• reference_uvw (Iterable of float) – Direction from which polar angle is measured.
Defaults to the positive z-direction.
Variables
• mu (openmc.stats.Univariate) – Distribution of the cosine of the polar angle
• phi (openmc.stats.Univariate) – Distribution of the azimuthal angle in radians

Generate angular distribution from an XML element
Parameters
Returns
Angular distribution generated from XML element
Return type
openmc.stats.PolarAzimuthal
to_xml_element()
Return XML representation of the angular distribution
Returns
element – XML element containing angular distribution data
Return type
openmc.stats.Isotropic
class openmc.stats.Isotropic
Isotropic angular distribution.
Generate isotropic distribution from an XML element
Parameters
Returns
Isotropic distribution generated from XML element
Return type
openmc.stats.Isotropic
to_xml_element()
Return XML representation of the isotropic distribution
Returns
element – XML element containing isotropic distribution data
Return type
openmc.stats.Monodirectional
class openmc.stats.Monodirectional(reference_uvw=[1.0, 0.0, 0.0])

Monodirectional angular distribution.
A monodirectional angular distribution is one for which the polar and azimuthal angles are always the same. It
is completely specified by the reference direction vector.
Parameters
reference_uvw (Iterable of float) – Direction from which polar angle is measured. De-
faults to the positive x-direction.

Generate monodirectional distribution from an XML element
Parameters
Returns
Monodirectional distribution generated from XML element
Return type
openmc.stats.Monodirectional
to_xml_element()
Return XML representation of the monodirectional distribution
Returns
element – XML element containing monodirectional distribution data
Return type
6.6.3 Spatial Distributions
openmc.stats.Spatial Distribution of locations in three-dimensional Euclidean

space.
openmc.stats.CartesianIndependent Spatial distribution with independent x, y, and z distri-
butions.
openmc.stats.CylindricalIndependent Spatial distribution represented in cylindrical coordi-
nates.
openmc.stats.SphericalIndependent Spatial distribution represented in spherical coordinates.
openmc.stats.Box Uniform distribution of coordinates in a rectangular
cuboid.
openmc.stats.Point Delta function in three dimensions.
openmc.stats.Spatial
class openmc.stats.Spatial
Distribution of locations in three-dimensional Euclidean space.
Classes derived from this abstract class can be used for spatial distributions of source sites.
openmc.stats.CartesianIndependent
class openmc.stats.CartesianIndependent(x, y, z)
Spatial distribution with independent x, y, and z distributions.
This distribution allows one to specify coordinates whose x-, y-, and z- components are sampled independently
from one another.
Parameters
• x (openmc.stats.Univariate) – Distribution of x-coordinates
• y (openmc.stats.Univariate) – Distribution of y-coordinates
• z (openmc.stats.Univariate) – Distribution of z-coordinates

Variables
• x (openmc.stats.Univariate) – Distribution of x-coordinates
• y (openmc.stats.Univariate) – Distribution of y-coordinates
• z (openmc.stats.Univariate) – Distribution of z-coordinates
Generate spatial distribution from an XML element
Parameters
Returns
Spatial distribution generated from XML element
Return type
openmc.stats.CartesianIndependent
to_xml_element()
Return XML representation of the spatial distribution
Returns
element – XML element containing spatial distribution data
Return type
openmc.stats.CylindricalIndependent
class openmc.stats.CylindricalIndependent(r, phi, z, origin=(0.0, 0.0, 0.0))

Spatial distribution represented in cylindrical coordinates.
This distribution allows one to specify coordinates whose 𝑟, 𝜑, and 𝑧 components are sampled independently
from one another and in a reference frame whose origin is specified by the coordinates (x0, y0, z0).
Parameters
• r (openmc.stats.Univariate) – Distribution of r-coordinates in a reference frame spec-
ified by the origin parameter
• phi (openmc.stats.Univariate) – Distribution of phi-coordinates (azimuthal angle) in
a reference frame specified by the origin parameter
• z (openmc.stats.Univariate) – Distribution of z-coordinates in a reference frame spec-
• origin (Iterable of float, optional) – coordinates (x0, y0, z0) of the center of the
cylindrical reference frame. Defaults to (0.0, 0.0, 0.0)
Variables
• r (openmc.stats.Univariate) – Distribution of r-coordinates in the local reference frame
the local reference frame
• z (openmc.stats.Univariate) – Distribution of z-coordinates in the local reference frame
cylindrical reference frame. Defaults to (0.0, 0.0, 0.0)

Parameters
Returns
Return type
openmc.stats.CylindricalIndependent
to_xml_element()
Returns
Return type
openmc.stats.SphericalIndependent
class openmc.stats.SphericalIndependent(r, cos_theta, phi, origin=(0.0, 0.0, 0.0))

Spatial distribution represented in spherical coordinates.
This distribution allows one to specify coordinates whose 𝑟, 𝜃, and 𝜑 components are sampled independently
from one another and centered on the coordinates (x0, y0, z0).
Changed in version 0.13.1: Accepts cos_theta instead of theta
Parameters
• r (openmc.stats.Univariate) – Distribution of r-coordinates in a reference frame spec-
• cos_theta (openmc.stats.Univariate) – Distribution of the cosine of the theta-
coordinates (angle relative to the z-axis) in a reference frame specified by the origin pa-
rameter
a reference frame specified by the origin parameter
spherical reference frame for the source. Defaults to (0.0, 0.0, 0.0)
Variables
• r (openmc.stats.Univariate) – Distribution of r-coordinates in the local reference frame
• cos_theta (openmc.stats.Univariate) – Distribution of the cosine of the theta-
coordinates (angle relative to the z-axis) in the local reference frame
the local reference frame
spherical reference frame. Defaults to (0.0, 0.0, 0.0)

Parameters
Returns
Return type
to_xml_element()
Returns
Return type
openmc.stats.Box
class openmc.stats.Box(lower_left, upper_right, only_fissionable=False)

Uniform distribution of coordinates in a rectangular cuboid.
Parameters
• lower_left (Iterable of float) – Lower-left coordinates of cuboid
• upper_right (Iterable of float) – Upper-right coordinates of cuboid
• only_fissionable (bool, optional) – Whether spatial sites should only be accepted if
they occur in fissionable materials
Variables
• lower_left (Iterable of float) – Lower-left coordinates of cuboid
• upper_right (Iterable of float) – Upper-right coordinates of cuboid
• only_fissionable (bool, optional) – Whether spatial sites should only be accepted if
they occur in fissionable materials
Generate box distribution from an XML element
Parameters
Returns
Box distribution generated from XML element
Return type
openmc.stats.Box
to_xml_element()
Return XML representation of the box distribution
Returns
element – XML element containing box distribution data

Return type
openmc.stats.Point
class openmc.stats.Point(xyz=(0.0, 0.0, 0.0))

Delta function in three dimensions.
This spatial distribution can be used for a point source where sites are emitted at a specific location given by its
Cartesian coordinates.
Parameters
xyz (Iterable of float, optional) – Cartesian coordinates of location. Defaults to (0.,
0., 0.).
Variables
xyz (Iterable of float) – Cartesian coordinates of location
Generate point distribution from an XML element
Parameters
Returns
Point distribution generated from XML element
Return type
openmc.stats.Point
to_xml_element()
Return XML representation of the point distribution
Returns
element – XML element containing point distribution location
Return type
openmc.stats.spherical_uniform Return a uniform spatial distribution over a spherical

shell.
openmc.stats.spherical_uniform
openmc.stats.spherical_uniform(r_outer, r_inner=0.0, thetas=(0.0, 3.141592653589793), phis=(0.0,

6.283185307179586), origin=(0.0, 0.0, 0.0))
Return a uniform spatial distribution over a spherical shell.
This function provides a uniform spatial distribution over a spherical shell between r_inner and r_outer. Option-
ally, the range of angles can be restricted by the thetas and phis arguments.
Parameters
• r_outer (float) – Outer radius of the spherical shell in [cm]
• r_inner (float, optional) – Inner radius of the spherical shell in [cm]

• thetas (iterable of float, optional) – Starting and ending theta coordinates (angle
relative to the z-axis) in radius in a reference frame centered at origin
• phis (iterable of float, optional) – Starting and ending phi coordinates (azimuthal
angle) in radians in a reference frame centered at origin
• origin (iterable of float, optional) – Coordinates (x0, y0, z0) of the center of the
spherical reference frame for the distribution.
Returns
Uniform distribution over the spherical shell
Return type
6.7 openmc.data – Nuclear Data Interface
6.7.1 Core Classes
The following classes are used for incident neutron data, decay data, fission and product yields.
IncidentNeutron Continuous-energy neutron interaction data.

Reaction A nuclear reaction
Product Secondary particle emitted in a nuclear reaction
FissionEnergyRelease Energy relased by fission reactions.
DataLibrary Collection of cross section data libraries.
Decay Radioactive decay data.
FissionProductYields Independent and cumulative fission product yields.
WindowedMultipole Resonant cross sections represented in the windowed
multipole format.
ProbabilityTables Unresolved resonance region probability tables.
openmc.data.IncidentNeutron
class openmc.data.IncidentNeutron(name, atomic_number, mass_number, metastable, atomic_weight_ratio,

kTs)
Continuous-energy neutron interaction data.
This class stores data derived from an ENDF-6 format neutron interaction sublibrary. Instances of this class
are not normally instantiated by the user but rather created using the factory methods IncidentNeutron.
from_hdf5(), IncidentNeutron.from_ace(), and IncidentNeutron.from_endf().
Parameters
• name (str) – Name of the nuclide using the GND naming convention
• atomic_number (int) – Number of protons in the target nucleus
• mass_number (int) – Number of nucleons in the target nucleus
• metastable (int) – Metastable state of the target nucleus. A value of zero indicates ground
state.
• atomic_weight_ratio (float) – Atomic mass ratio of the target nuclide.
6.7. openmc.data – Nuclear Data Interface 699

• kTs (Iterable of float) – List of temperatures of the target nuclide in the data set. The
temperatures have units of eV.
Variables
• atomic_symbol (str) – Atomic symbol of the nuclide, e.g., ‘Zr’
• atomic_weight_ratio (float) – Atomic weight ratio of the target nuclide.
• fission_energy (None or openmc.data.FissionEnergyRelease) – The energy re-
leased by fission, tabulated by component (e.g. prompt neutrons or beta particles) and de-
pendent on incident neutron energy
• mass_number (int) – Number of nucleons in the target nucleus
• metastable (int) – Metastable state of the target nucleus. A value of zero indicates ground
state.
• reactions (collections.OrderedDict) – Contains the cross sections, secondary angle
and energy distributions, and other associated data for each reaction. The keys are the MT
values and the values are Reaction objects.
• resonances (openmc.data.Resonances or None) – Resonance parameters
• resonance_covariance (openmc.data.ResonanceCovariance or None) – Covari-
ance for resonance parameters
• temperatures (list of str) – List of string representations of the temperatures of the
target nuclide in the data set. The temperatures are strings of the temperature, rounded to the
nearest integer; e.g., ‘294K’
• urr (dict) – Dictionary whose keys are temperatures (e.g., ‘294K’) and values are unre-
solved resonance region probability tables.
add_elastic_0K_from_endf(filename, overwrite=False)
Append 0K elastic scattering cross section from an ENDF file.
Parameters
• filename (str) – Path to ENDF file
• overwrite (bool) – If existing 0 K data is present, this flag can be used to indicate that it
should be overwritten. Otherwise, an exception will be thrown.
Raises
ValueError – If 0 K data is already present and the overwrite parameter is False.
add_temperature_from_ace(ace_or_filename, metastable_scheme='nndc')
Append data from an ACE file at a different temperature.
Parameters
• ace_or_filename (openmc.data.ace.Table or str) – ACE table to read from. If
given as a string, it is assumed to be the filename for the ACE file.
• metastable_scheme ({'nndc', 'mcnp'}) – Determine how ZAID identifiers are to be in-
terpreted in the case of a metastable nuclide. Because the normal ZAID (=1000*Z + A)
does not encode metastable information, different conventions are used among different

libraries. In MCNP libraries, the convention is to add 400 for a metastable nuclide except
for Am242m, for which 95242 is metastable and 95642 (or 1095242 in newer libraries) is
the ground state. For NNDC libraries, ZAID is given as 1000*Z + A + 100*m.
export_to_hdf5(path, mode='a', libver='earliest')
Export incident neutron data to an HDF5 file.
Parameters
• path (str) – Path to write HDF5 file to
• mode ({'r+', 'w', 'x', 'a'}) – Mode that is used to open the HDF5 file. This is the second
argument to the h5py.File constructor.
classmethod from_ace(ace_or_filename, metastable_scheme='nndc')
Generate incident neutron continuous-energy data from an ACE table
Parameters
the value is a string, it is assumed to be the filename for the ACE file.
• metastable_scheme ({'nndc', 'mcnp'}) – Determine how ZAID identifiers are to be in-
terpreted in the case of a metastable nuclide. Because the normal ZAID (=1000*Z + A)
does not encode metastable information, different conventions are used among different
libraries. In MCNP libraries, the convention is to add 400 for a metastable nuclide except
for Am242m, for which 95242 is metastable and 95642 (or 1095242 in newer libraries) is
the ground state. For NNDC libraries, ZAID is given as 1000*Z + A + 100*m.
Returns
Incident neutron continuous-energy data
Return type
classmethod from_endf(ev_or_filename, covariance=False)
Generate incident neutron continuous-energy data from an ENDF evaluation
Parameters
• ev_or_filename (openmc.data.endf.Evaluation or str) – ENDF evaluation to
read from. If given as a string, it is assumed to be the filename for the ENDF file.
• covariance (bool) – Flag to indicate whether or not covariance data from File 32 should
be retrieved
Returns
Incident neutron continuous-energy data
Return type
classmethod from_hdf5(group_or_filename)
Generate continuous-energy neutron interaction data from HDF5 group
Parameters
group_or_filename (h5py.Group or str) – HDF5 group containing interaction data. If
given as a string, it is assumed to be the filename for the HDF5 file, and the first group is used
to read from.

Returns
Continuous-energy neutron interaction data
Return type
classmethod from_njoy(filename, temperatures=None, evaluation=None, **kwargs)
Generate incident neutron data by running NJOY.
Parameters
• temperatures (iterable of float) – Temperatures in Kelvin to produce data at. If
omitted, data is produced at room temperature (293.6 K)
• evaluation (openmc.data.endf.Evaluation, optional) – If the ENDF file con-
tains multiple material evaluations, this argument indicates which evaluation to use.
• **kwargs – Keyword arguments passed to openmc.data.njoy.make_ace()
Returns
data – Incident neutron continuous-energy data
Return type
get_reaction_components(mt)
Determine what reactions make up redundant reaction.
Parameters
mt (int) – ENDF MT number of the reaction to find components of.
Returns
mts – ENDF MT numbers of reactions that make up the redundant reaction and have cross
sections provided.
Return type
list of int
openmc.data.Reaction
class openmc.data.Reaction(mt)
A nuclear reaction
A Reaction object represents a single reaction channel for a nuclide with an associated cross section and, if
present, a secondary angle and energy distribution.
Parameters
mt (int) – The ENDF MT number for this reaction.
Variables
• center_of_mass (bool) – Indicates whether scattering kinematics should be performed in
the center-of-mass or laboratory reference frame. grid above the threshold value in barns.
• redundant (bool) – Indicates whether or not this is a redundant reaction
• mt (int) – The ENDF MT number for this reaction.
• q_value (float) – The Q-value of this reaction in eV.

• xs (dict of str to openmc.data.Function1D) – Microscopic cross section for this

reaction as a function of incident energy; these cross sections are provided in a dictionary
where the key is the temperature of the cross section set.
• products (Iterable of openmc.data.Product) – Reaction products
• derived_products (Iterable of openmc.data.Product) – Derived reaction prod-
ucts. Used for ‘total’ fission neutron data when prompt/delayed data also exists.
classmethod from_endf(ev, mt)
Generate a reaction from an ENDF evaluation
Parameters
• ev (openmc.data.endf.Evaluation) – ENDF evaluation
• mt (int) – The MT value of the reaction to get data for
Returns
rx – Reaction data
Return type
classmethod from_hdf5(group, energy)
Generate reaction from an HDF5 group
Parameters
• energy (dict) – Dictionary whose keys are temperatures (e.g., ‘300K’) and values are
arrays of energies at which cross sections are tabulated at.
Returns
Reaction data
Return type
to_hdf5(group)
Write reaction to an HDF5 group
Parameters
group (h5py.Group) – HDF5 group to write to
openmc.data.Product
class openmc.data.Product(particle='neutron')
Secondary particle emitted in a nuclear reaction
Parameters
particle (str, optional) – The particle type of the reaction product. Defaults to ‘neutron’.
Variables
• applicability (Iterable of openmc.data.Tabulated1D) – Probability of sampling
a given distribution for this product.
• decay_rate (float) – Decay rate in inverse seconds
• distribution (Iterable of openmc.data.AngleEnergy) – Distributions of energy
and angle of product.

• emission_mode ({'prompt', 'delayed', 'total'}) – Indicate whether the particle is

emitted immediately or whether it results from the decay of reaction product (e.g., neutron
emitted from a delayed neutron precursor). A special value of ‘total’ is used when the yield
represents particles from prompt and delayed sources.
• particle (str) – The particle type of the reaction product
• yield (openmc.data.Function1D) – Yield of secondary particle in the reaction.
Generate reaction product from HDF5 data
Parameters
Returns
Reaction product
Return type
openmc.data.Product
to_hdf5(group)
Write product to an HDF5 group
Parameters
openmc.data.FissionEnergyRelease
class openmc.data.FissionEnergyRelease(fragments, prompt_neutrons, delayed_neutrons, prompt_photons,

delayed_photons, betas, neutrinos)
Energy relased by fission reactions.
Energy is carried away from fission reactions by many different particles. The attributes of this class specify
how much energy is released in the form of fission fragments, neutrons, photons, etc. Each component is also
(in general) a function of the incident neutron energy.
Following a fission reaction, most of the energy release is carried by the daughter nuclei fragments. These
fragments accelerate apart from the Coulomb force on the time scale of ~10^-20 s [1]. Those fragments emit
prompt neutrons between ~10^-18 and ~10^-13 s after scission (although some prompt neutrons may come
directly from the scission point) [1]. Prompt photons follow with a time scale of ~10^-14 to ~10^-7 s [1]. The
fission products then emit delayed neutrons with half lives between 0.1 and 100 s. The remaining fission energy
comes from beta decays of the fission products which release beta particles, photons, and neutrinos (that escape
the reactor and do not produce usable heat).
Use the class methods to instantiate this class from an HDF5 or ENDF dataset. The FissionEnergyRelease.
from_hdf5() method builds this class from the usual OpenMC HDF5 data files. FissionEnergyRelease.
from_endf() uses ENDF-formatted data.

References
[1] D. G. Madland, “Total prompt energy release in the neutron-induced fission of ^235U, ^238U, and ^239Pu”,
Nuclear Physics A 772:113–137 (2006). <http://dx.doi.org/10.1016/j.nuclphysa.2006.03.013>
Variables
• fragments (Callable) – Function that accepts incident neutron energy value(s) and returns
the kinetic energy of the fission daughter nuclides (after prompt neutron emission).
• prompt_neutrons (Callable) – Function of energy that returns the kinetic energy of
prompt fission neutrons.
• delayed_neutrons (Callable) – Function of energy that returns the kinetic energy of
delayed neutrons emitted from fission products.
• prompt_photons (Callable) – Function of energy that returns the kinetic energy of prompt
fission photons.
• delayed_photons (Callable) – Function of energy that returns the kinetic energy of de-
layed photons.
• betas (Callable) – Function of energy that returns the kinetic energy of delayed beta par-
ticles.
• neutrinos (Callable) – Function of energy that returns the kinetic energy of neutrinos.
• recoverable (Callable) – Function of energy that returns the kinetic energy of all prod-
ucts that can be absorbed in the reactor (all of the energy except for the neutrinos).
• total (Callable) – Function of energy that returns the kinetic energy of all products.
• q_prompt (Callable) – Function of energy that returns the prompt fission Q-value (frag-
ments + prompt neutrons + prompt photons - incident neutron energy).
• q_recoverable (Callable) – Function of energy that returns the recoverable fission Q-
value (total release - neutrinos - incident neutron energy). This value is sometimes referred
to as the pseudo-Q-value.
• q_total (Callable) – Function of energy that returns the total fission Q-value (total release
- incident neutron energy).
classmethod from_endf(ev, incident_neutron)
Generate fission energy release data from an ENDF file.
Parameters
• incident_neutron (openmc.data.IncidentNeutron) – Corresponding incident neu-
tron dataset
Returns
Fission energy release data
Return type
Generate fission energy release data from an HDF5 group.
Parameters

Returns
Fission energy release data
Return type
to_hdf5(group)
Write energy release data to an HDF5 group
Parameters
openmc.data.DataLibrary
class openmc.data.DataLibrary
Collection of cross section data libraries.
Variables
libraries (list of dict) – List in which each item is a dictionary summarizing cross section
data from a single file. The dictionary has keys ‘path’, ‘type’, and ‘materials’.
export_to_xml(path='cross_sections.xml')
Export cross section data library to an XML file.
Parameters
path (str) – Path to file to write. Defaults to ‘cross_sections.xml’.
classmethod from_xml(path=None)
Read cross section data library from an XML file.
Parameters
path (str, optional) – Path to XML file to read. If not provided, the
OPENMC_CROSS_SECTIONS environment variable will be used.
Returns
data – Data library object initialized from the provided XML
Return type
openmc.data.DataLibrary
get_by_material(name, data_type='neutron')
Return the library dictionary containing a given material.
Parameters
• name (str) – Name of material, e.g. ‘Am241’
• data_type (str) – Name of data type, e.g. ‘neutron’, ‘photon’, ‘wmp’, or ‘thermal’
Returns
library – Dictionary summarizing cross section data from a single file; the dictionary has
keys ‘path’, ‘type’, and ‘materials’.
Return type
dict or None
register_file(filename)
Register a file with the data library.

Parameters
filename (str or Path ) – Path to the file to be registered. If an xml file, treat as the
depletion chain file without materials.
openmc.data.Decay
class openmc.data.Decay(ev_or_filename)
Radioactive decay data.
Parameters
ev_or_filename (str of openmc.data.endf.Evaluation) – ENDF radioactive decay
data evaluation to read from. If given as a string, it is assumed to be the filename for the ENDF
file.
Variables
• average_energies (dict) – Average decay energies in eV of each type of radiation for
decay heat applications.
• decay_constant (uncertainties.UFloat) – Decay constant in inverse seconds.
• decay_energy (uncertainties.UFloat) – Average energy in [eV] per decay for decay
heat applications
• half_life (uncertainties.UFloat) – Half-life of the decay in seconds.
• modes (list) – Decay mode information for each mode of decay.
• nuclide (dict) – Dictionary describing decaying nuclide with keys ‘name’, ‘excited_state’,
‘mass’, ‘stable’, ‘spin’, and ‘parity’.
• spectra (dict) – Resulting radiation spectra for each radiation type.
• sources (dict) – Radioactive decay source distributions represented as a dictionary map-
ping particle types (e.g., ‘photon’) to instances of openmc.stats.Univariate.
classmethod from_endf(ev_or_filename)
Generate radioactive decay data from an ENDF evaluation
Parameters
ev_or_filename (str or openmc.data.endf.Evaluation) – ENDF radioactive decay
data evaluation to read from. If given as a string, it is assumed to be the filename for the
ENDF file.
Returns
Radioactive decay data
Return type
openmc.data.Decay
property sources
Radioactive decay source distributions

openmc.data.FissionProductYields
class openmc.data.FissionProductYields(ev_or_filename)
Independent and cumulative fission product yields.
Parameters
ev_or_filename (str of openmc.data.endf.Evaluation) – ENDF fission product yield
evaluation to read from. If given as a string, it is assumed to be the filename for the ENDF file.
Variables
• cumulative (list of dict) – Cumulative yields for each tabulated energy. Each item in
the list is a dictionary whose keys are nuclide names and values are cumulative yields. The
i-th dictionary corresponds to the i-th incident neutron energy.
• energies (Iterable of float or None) – Energies at which fission product yields are
tabulated.
• independent (list of dict) – Independent yields for each tabulated energy. Each item
in the list is a dictionary whose keys are nuclide names and values are independent yields.
The i-th dictionary corresponds to the i-th incident neutron energy.
• nuclide (dict) – Properties of the fissioning nuclide.
Notes
Neutron fission yields are typically not measured with a monoenergetic source of neutrons. As such, if the
fission yields are given at, e.g., 0.0253 eV, one should interpret this as meaning that they are derived from a
typical thermal reactor flux spectrum as opposed to a monoenergetic source at 0.0253 eV.
Generate fission product yield data from an ENDF evaluation
Parameters
ev_or_filename (str or openmc.data.endf.Evaluation) – ENDF fission product
yield evaluation to read from. If given as a string, it is assumed to be the filename for the
ENDF file.
Returns
Fission product yield data
Return type
openmc.data.FissionProductYields
openmc.data.WindowedMultipole
class openmc.data.WindowedMultipole(name)
Resonant cross sections represented in the windowed multipole format.
Parameters
name (str) – Name of the nuclide using the GND naming convention
Variables
• spacing (float) – The width of each window in sqrt(E)-space. For example, the frst
window will end at (sqrt(E_min) + spacing)**2 and the second window at (sqrt(E_min)
+ 2*spacing)**2.

• sqrtAWR (float) – Square root of the atomic weight ratio of the target nuclide.
• E_min (float) – Lowest energy in eV the library is valid for.
• E_max (float) – Highest energy in eV the library is valid for.
• data (np.ndarray) – A 2D array of complex poles and residues. data[i, 0] gives the energy
at which pole i is located. data[i, 1:] gives the residues associated with the i-th pole. There
are 3 residues, one each for the scattering, absorption, and fission channels.
• windows (np.ndarray) – A 2D array of Integral values. windows[i, 0] - 1 is the index of
the first pole in window i. windows[i, 1] - 1 is the index of the last pole in window i.
• broaden_poly (np.ndarray) – A 1D array of boolean values indicating whether or not the
polynomial curvefit in that window should be Doppler broadened.
• curvefit (np.ndarray) – A 3D array of Real curvefit polynomial coefficients. curvefit[i,
0, :] gives coefficients for the scattering cross section in window i. curvefit[i, 1, :] gives
absorption coefficients and curvefit[i, 2, :] gives fission coefficients. The polynomial terms
are increasing powers of sqrt(E) starting with 1/E e.g: a/E + b/sqrt(E) + c + d sqrt(E) + . . .
Export windowed multipole data to an HDF5 file.
Parameters
classmethod from_endf(endf_file, log=False, vf_options=None, wmp_options=None)
Generate windowed multipole neutron data from an ENDF evaluation.
Parameters
• endf_file (str) – Path to ENDF evaluation
• log (bool or int, optional) – Whether to print running logs (use int for verbosity
control)
• vf_options (dict, optional) – Dictionary of keyword arguments, e.g. {‘njoy_error’:
0.001}, passed to openmc.data.multipole.vectfit_nuclide()
• wmp_options (dict, optional) – Dictionary of keyword arguments, e.g. {‘search’:
True, ‘rtol’: 0.01}, passed to openmc.data.WindowedMultipole.from_multipole()
Returns
Return type
Construct a WindowedMultipole object from an HDF5 group or file.
Parameters
group_or_filename (h5py.Group or str) – HDF5 group containing multipole data. If

to read from.
Returns
Return type
classmethod from_multipole(mp_data, search=None, log=False, **kwargs)
Generate windowed multipole neutron data from multipole data.
Parameters
• mp_data (dictionary or str) – Dictionary or Path to the multipole data stored in a
pickle file
• search (bool, optional) – Whether to search for optimal window size and curvefit
order. Defaults to True if no windowing parameters are specified.
• log (bool or int, optional) – Whether to print running logs (use int for verbosity
control)
• **kwargs – Keyword arguments passed to openmc.data.multipole._windowing()
Returns
Return type
openmc.data.ProbabilityTables
class openmc.data.ProbabilityTables(energy, table, interpolation, inelastic_flag=-1, absorption_flag=-1,

multiply_smooth=False)
Unresolved resonance region probability tables.
Parameters
• energy (Iterable of float) – Energies in eV at which probability tables exist
• table (numpy.ndarray) – Probability tables for each energy. This array is of shape (N, 6,
M) where N is the number of energies and M is the number of bands. The second dimension
indicates whether the value is for the cumulative probability (0), total (1), elastic (2), fission
(3), (𝑛, 𝛾) (4), or heating number (5).
• interpolation ({2, 5}) – Interpolation scheme between tables
• inelastic_flag (int) – A value less than zero indicates that the inelastic cross section is
zero within the unresolved energy range. A value greater than zero indicates the MT number
for a reaction whose cross section is to be used in the unresolved range.
• absorption_flag (int) – A value less than zero indicates that the “other absorption” cross
section is zero within the unresolved energy range. A value greater than zero indicates the
MT number for a reaction whose cross section is to be used in the unresolved range.
• multiply_smooth (bool) – Indicate whether probability table values are cross sections
(False) or whether they must be multiply by the corresponding “smooth” cross sections
(True).
Variables

• energy (Iterable of float) – Energies in eV at which probability tables exist

• table (numpy.ndarray) – Probability tables for each energy. This array is of shape (N, 6,
M) where N is the number of energies and M is the number of bands. The second dimension
indicates whether the value is for the cumulative probability (0), total (1), elastic (2), fission
(3), (𝑛, 𝛾) (4), or heating number (5).
• interpolation ({2, 5}) – Interpolation scheme between tables
• inelastic_flag (int) – A value less than zero indicates that the inelastic cross section is
zero within the unresolved energy range. A value greater than zero indicates the MT number
for a reaction whose cross section is to be used in the unresolved range.
• absorption_flag (int) – A value less than zero indicates that the “other absorption” cross
section is zero within the unresolved energy range. A value greater than zero indicates the
MT number for a reaction whose cross section is to be used in the unresolved range.
• multiply_smooth (bool) – Indicate whether probability table values are cross sections
(False) or whether they must be multiply by the corresponding “smooth” cross sections
(True).
classmethod from_ace(ace)
Generate probability tables from an ACE table
Parameters
ace (openmc.data.ace.Table) – ACE table to read from
Returns
Unresolved resonance region probability tables
Return type
Generate probability tables from HDF5 data
Parameters
Returns
Probability tables
Return type
to_hdf5(group)
Write probability tables to an HDF5 group
Parameters
The following classes are used for storing atomic data (incident photon cross sections, atomic relaxation):
IncidentPhoton Photon interaction data.

PhotonReaction Photon-induced reaction
AtomicRelaxation Atomic relaxation data.

openmc.data.IncidentPhoton
class openmc.data.IncidentPhoton(atomic_number)
Photon interaction data.
This class stores photo-atomic, photo-nuclear, atomic relaxation, Compton profile, stopping power, and
bremsstrahlung data assembled from different sources. To create an instance, the factory method
IncidentPhoton.from_endf() can be used. To add atomic relaxation or Compton profile data, set the
IncidentPhoton.atomic_relaxation and IncidentPhoton.compton_profiles attributes directly.
Parameters
atomic_number (int) – Number of protons in the target nucleus
Variables
• atomic_relaxation (openmc.data.AtomicRelaxation or None) – Atomic relax-
ation data
• bremsstrahlung (dict) – Dictionary of bremsstrahlung data with keys ‘I’ (mean excitation
energy in [eV]), ‘num_electrons’ (number of electrons in each subshell), ‘ionization_energy’
(ionization potential of each subshell), ‘electron_energy’ (incident electron kinetic energy
values in [eV]), ‘photon_energy’ (ratio of the energy of the emitted photon to the incident
electron kinetic energy), and ‘dcs’ (cross section values in [b]). The cross sections are in
scaled form: (𝛽 2 /𝑍 2 )𝐸𝑘 (𝑑𝜎/𝑑𝐸𝑘 ), where 𝐸𝑘 is the energy of the emitted photon. A nega-
tive number of electrons in a subshell indicates conduction electrons.
• compton_profiles (dict) – Dictionary of Compton profile data with keys
‘num_electrons’ (number of electrons in each subshell), ‘binding_energy’ (ionization
potential of each subshell), and ‘J’ (Hartree-Fock Compton profile as a function of the
projection of the electron momentum on the scattering vector, 𝑝𝑧 for each subshell). Note
that subshell occupancies may not match the atomic relaxation data.
• reactions (collections.OrderedDict) – Contains the cross sections for each photon
reaction. The keys are MT values and the values are instances of PhotonReaction.
Export incident photon data to an HDF5 file.
Parameters
classmethod from_ace(ace_or_filename)
Generate incident photon data from an ACE table
Parameters
ace_or_filename (str or openmc.data.ace.Table) – ACE table to read from. If
Returns
Photon interaction data
Return type

classmethod from_endf(photoatomic, relaxation=None)

Generate incident photon data from an ENDF evaluation
Parameters
• photoatomic (str or openmc.data.endf.Evaluation) – ENDF photoatomic data
evaluation to read from. If given as a string, it is assumed to be the filename for the ENDF
file.
• relaxation (str or openmc.data.endf.Evaluation, optional) – ENDF atomic
relaxation data evaluation to read from. If given as a string, it is assumed to be the filename
for the ENDF file.
Returns
Return type
Generate photon reaction from an HDF5 group
Parameters
to read from.
Returns
Return type
openmc.data.PhotonReaction
class openmc.data.PhotonReaction(mt)
Photon-induced reaction
Parameters
mt (int) – The ENDF MT number for this reaction.
Variables
• anomalous_real (openmc.data.Tabulated1D) – Real part of the anomalous scattering
factor
• anomlaous_imag (openmc.data.Tabulated1D) – Imaginary part of the anomalous scatt-
tering factor
• mt (int) – The ENDF MT number for this reaction.
• scattering_factor (openmc.data.Tabulated1D) – Coherent or incoherent form factor.
• xs (Callable) – Cross section as a function of incident photon energy
classmethod from_ace(ace, mt)
Generate photon reaction from an ACE table
Parameters
• ace (openmc.data.ace.Table) – ACE table to read from


Returns
Photon reaction data
Return type
Generate photon reaction from an ENDF evaluation
Parameters
• ev (openmc.data.endf.Evaluation) – ENDF photo-atomic interaction data evaluation
Returns
Return type
classmethod from_hdf5(group, mt, energy)
Generate photon reaction from an HDF5 group
Parameters
• energy (Iterable of float) – arrays of energies at which cross sections are tabulated
at
Returns
Return type
to_hdf5(group, energy, Z)
Write photon reaction to an HDF5 group
Parameters
• group (h5py.Group) – HDF5 group to write to
• energy (Iterable of float) – arrays of energies at which cross sections are tabulated
at
• Z (int) – atomic number

openmc.data.AtomicRelaxation
class openmc.data.AtomicRelaxation(binding_energy, num_electrons, transitions)

Atomic relaxation data.
This class stores the binding energy, number of electrons, and electron transitions possible from ioniziation for
each electron subshell of an atom. All of the data originates from an ENDF-6 atomic relaxation sub-library
(NSUB=6). Instances of this class are not normally instantiated directly but rather created using the factory
method 𝐴𝑡𝑜𝑚𝑖𝑐𝑅𝑒𝑙𝑎𝑥𝑎𝑡𝑖𝑜𝑛.𝑓 𝑟𝑜𝑚𝑒 𝑛𝑑𝑓 .
Parameters
• binding_energy (dict) – Dictionary indicating the binding energy in eV (values) for given
subshells (keys). The subshells should be given as strings, e.g., ‘K’, ‘L1’, ‘L2’, etc.
• num_electrons (dict) – Dictionary indicating the number of electrons in a subshell when
neutral (values) for given subshells (keys). The subshells should be given as strings, e.g.,
‘K’, ‘L1’, ‘L2’, etc.
• transitions (pandas.DataFrame) – Dictionary indicating allowed transitions and their
probabilities (values) for given subshells (keys). The subshells should be given as strings,
e.g., ‘K’, ‘L1’, ‘L2’, etc. The transitions are represented as a DataFrame with columns indi-
cating the secondary and tertiary subshell, the energy of the transition in eV, and the fractional
probability of the transition.
Variables
• binding_energy (dict) – Dictionary indicating the binding energy in eV (values) for given
subshells (keys). The subshells should be given as strings, e.g., ‘K’, ‘L1’, ‘L2’, etc.
• num_electrons (dict) – Dictionary indicating the number of electrons in a subshell when
neutral (values) for given subshells (keys). The subshells should be given as strings, e.g.,
‘K’, ‘L1’, ‘L2’, etc.
• transitions (pandas.DataFrame) – Dictionary indicating allowed transitions and their
probabilities (values) for given subshells (keys). The subshells should be given as strings,
e.g., ‘K’, ‘L1’, ‘L2’, etc. The transitions are represented as a DataFrame with columns indi-
cating the secondary and tertiary subshell, the energy of the transition in eV, and the fractional
probability of the transition.
See also:
IncidentPhoton
classmethod from_ace(ace)
Generate atomic relaxation data from an ACE file
Parameters
ace (openmc.data.ace.Table) – ACE table to read from
Returns
Atomic relaxation data
Return type
Generate atomic relaxation data from an ENDF evaluation
Parameters
ev_or_filename (str or openmc.data.endf.Evaluation) – ENDF atomic relaxation

evaluation to read from. If given as a string, it is assumed to be the filename for the ENDF
file.
Returns
Return type
Generate atomic relaxation data from an HDF5 group
Parameters
Returns
Return type
to_hdf5(group, shell)
Write atomic relaxation data to an HDF5 group
Parameters
• shell (str) – The subshell to write data for
The following classes are used for storing thermal neutron scattering data:
ThermalScattering A ThermalScattering object contains thermal scattering

data as represented by an S(alpha, beta) table.
ThermalScatteringReaction Thermal scattering reaction
CoherentElastic Coherent elastic scattering data from a crystalline mate-
rial
IncoherentElastic Incoherent elastic scattering cross section
openmc.data.ThermalScattering
class openmc.data.ThermalScattering(name, atomic_weight_ratio, energy_max, kTs)

A ThermalScattering object contains thermal scattering data as represented by an S(alpha, beta) table.
Parameters
• name (str) – Name of the material using GND convention, e.g. c_H_in_H2O
Variables
• energy_max (float) – Maximum energy for thermal scattering data in [eV]
• elastic (openmc.data.ThermalScatteringReaction or None) – Elastic scattering
derived in the coherent or incoherent approximation

• inelastic (openmc.data.ThermalScatteringReaction) – Inelastic scattering cross

section derived in the incoherent approximation
• name (str) – Name of the material using GND convention, e.g. c_H_in_H2O
• temperatures (Iterable of str) – List of string representations the temperatures of the
target nuclide in the data set. The temperatures are strings of the temperature, rounded to the
nearest integer; e.g., ‘294K’
• nuclides (Iterable of str) – Nuclide names that the thermal scattering data applies to
add_temperature_from_ace(ace_or_filename, name=None)
Add data to the ThermalScattering object from an ACE file at a different temperature.
Parameters
• name (str) – GND-conforming name of the material, e.g. c_H_in_H2O. If none is passed,
the appropriate name is guessed based on the name of the ACE table.
Returns
Thermal scattering data
Return type
Export table to an HDF5 file.
Parameters
classmethod from_ace(ace_or_filename, name=None)
Generate thermal scattering data from an ACE table
Parameters
• name (str) – GND-conforming name of the material, e.g. c_H_in_H2O. If none is passed,
the appropriate name is guessed based on the name of the ACE table.
Returns
Return type
Generate thermal scattering data from an ENDF file

Parameters
ev_or_filename (openmc.data.endf.Evaluation or str) – ENDF evaluation to read
from. If given as a string, it is assumed to be the filename for the ENDF file.
Returns
Return type
Generate thermal scattering data from HDF5 group
Parameters
to read from.
Returns
Neutron thermal scattering data
Return type
classmethod from_njoy(filename, filename_thermal, temperatures=None, evaluation=None,
evaluation_thermal=None, use_endf_data=True, **kwargs)
Generate thermal scattering data by running NJOY.
Parameters
• filename (str) – Path to ENDF neutron sublibrary file
• filename_thermal (str) – Path to ENDF thermal scattering sublibrary file
• temperatures (iterable of float) – Temperatures in Kelvin to produce data at. If
omitted, data is produced at all temperatures in the ENDF thermal scattering sublibrary.
• evaluation (openmc.data.endf.Evaluation, optional) – If the ENDF neutron
sublibrary file contains multiple material evaluations, this argument indicates which eval-
uation to use.
• evaluation_thermal (openmc.data.endf.Evaluation, optional) – If the ENDF
thermal scattering sublibrary file contains multiple material evaluations, this argument in-
dicates which evaluation to use.
• use_endf_data (bool) – If the material has incoherent elastic scattering, the ENDF data
will be used rather than the ACE data.
• **kwargs – Keyword arguments passed to openmc.data.njoy.make_ace_thermal()
Returns
data – Thermal scattering data
Return type

openmc.data.ThermalScatteringReaction
class openmc.data.ThermalScatteringReaction(xs, distribution)

Thermal scattering reaction
This class is used to hold the integral and differential cross sections for either elastic or inelastic thermal scatter-
ing.
Parameters
• xs (dict of str to Function1D) – Integral cross section at each temperature
• distribution (dict of str to AngleEnergy) – Secondary angle-energy distribution
at each temperature
Variables
• xs (dict of str to Function1D) – Integral cross section at each temperature
• distribution (dict of str to AngleEnergy) – Secondary angle-energy distribution
at each temperature
classmethod from_hdf5(group, name, temperatures)
Generate thermal scattering reaction data from HDF5
Parameters
• name ({'elastic', 'inelastic'}) – Name of the reaction to read
• temperatures (Iterable of str) – Temperatures to read
Returns
Thermal scattering reaction data
Return type
openmc.data.ThermalScatteringReaction
to_hdf5(group, name)
Write thermal scattering reaction to HDF5
Parameters
• name ({'elastic', 'inelastic'}) – Name of reaction to write
openmc.data.CoherentElastic
class openmc.data.CoherentElastic(bragg_edges, factors)

Coherent elastic scattering data from a crystalline material
The integrated cross section for coherent elastic scattering from a powdered crystalline material may be repre-
sented as:
𝐸𝑖 <𝐸
1 ∑︁
𝜎(𝐸, 𝑇 ) = 𝑠𝑖 (𝑇 )
𝐸 𝑖=1
where 𝑠𝑖 (𝑇 ) is proportional the structure factor in [eV-b] at the moderator temperature 𝑇 in Kelvin.
Parameters

• bragg_edges (Iterable of float) – Bragg edge energies in eV

𝐸∑︀
𝑖 <𝐸
• factors (Iterable of float) – Partial sum of structure factors, 𝑠𝑖
𝑖=1
Variables
• bragg_edges (Iterable of float) – Bragg edge energies in eV
𝐸∑︀
𝑖 <𝐸
• factors (Iterable of float) – Partial sum of structure factors, 𝑠𝑖
𝑖=1
classmethod from_hdf5(dataset)
Read coherent elastic scattering from an HDF5 dataset
Parameters
dataset (h5py.Dataset) – HDF5 dataset to read from
Returns
Coherent elastic scattering cross section
Return type
openmc.data.CoherentElastic
Write coherent elastic scattering to an HDF5 group
Parameters
• name (str) – Name of the dataset to create
openmc.data.IncoherentElastic
class openmc.data.IncoherentElastic(bound_xs, debye_waller)

Incoherent elastic scattering cross section
Elastic scattering can be treated in the incoherent approximation for partially ordered systems such as ZrHx and
polyethylene. The integrated cross section can be obtained as:
(︃ ′
)︃
𝜎𝑏 1 − 𝑒−4𝐸𝑊 (𝑇 )
𝜎(𝐸, 𝑇 ) =
2 2𝐸𝑊 ′ (𝑇 )
where 𝜎𝑏 is the characteristic bound cross section, and 𝑊 ′ (𝑇 ) is the Debye-Waller integral divided by the atomic
mass in [eV−1 ].
Parameters
• bound_xs (float) – Characteristic bound cross section in [b]
• debye_waller (float) – Debye-Waller integral in [eV−1 ]
Variables
• bound_xs (float) – Characteristic bound cross section in [b]
• debye_waller (float) – Debye-Waller integral in [eV−1 ]

Read incoherent elastic scattering from an HDF5 dataset
Parameters
dataset (h5py.Dataset) – HDF5 dataset to read from
Returns
Incoherent elastic scattering cross section
Return type
openmc.data.IncoherentElastic
Write incoherent elastic scattering to an HDF5 group
Parameters
6.7.2 Core Functions
atomic_mass Return atomic mass of isotope in atomic mass units.

atomic_weight Return atomic weight of an element in atomic mass
units.
combine_distributions Combine distributions with specified probabilities
decay_constant Return decay constant of isotope in [s^-1]
dose_coefficients Return effective dose conversion coefficients from
ICRP-116
gnd_name Return nuclide name using GND convention
half_life Return half-life of isotope in seconds or None if isotope
is stable
isotopes Return naturally occurring isotopes and their abun-
dances
kalbach_slope Returns Kalbach-Mann slope from calculations.
linearize Return a tabulated representation of a one-variable func-
tion
thin Check for (x,y) points that can be removed.
water_density Return the density of liquid water at a given temperature
and pressure.
zam Return tuple of (atomic number, mass number,
metastable state)
openmc.data.atomic_mass
openmc.data.atomic_mass(isotope)
Return atomic mass of isotope in atomic mass units.
Atomic mass data comes from the Atomic Mass Evaluation 2016.
Parameters
isotope (str) – Name of isotope, e.g., ‘Pu239’

Returns
Atomic mass of isotope in [amu]
Return type
float
openmc.data.atomic_weight
openmc.data.atomic_weight(element)
Return atomic weight of an element in atomic mass units.
Computes an average of the atomic mass of each of element’s naturally occurring isotopes weighted by their
relative abundance.
Parameters
element (str) – Element symbol (e.g., ‘H’) or name (e.g., ‘helium’)
Returns
Atomic weight of element in [amu]
Return type
float
openmc.data.combine_distributions
openmc.data.combine_distributions(dists, probs)
Combine distributions with specified probabilities
This function can be used to combine multiple instances of Discrete and ~openmc.stats.Tabular. Multiple
discrete distributions are merged into a single distribution and the remainder of the distributions are put into a
Mixture distribution.
Parameters
• dists (iterable of openmc.stats.Univariate) – Distributions to combine
• probs (iterable of float) – Probability (or intensity) of each distribution
openmc.data.decay_constant
openmc.data.decay_constant(isotope)
Return decay constant of isotope in [s^-1]
Decay constants are based on half-life values from the half_life() function. When the isotope is stable, a
decay constant of zero is returned.
Parameters
Returns
Decay constant of isotope in [s^-1]
Return type
float

See also:
openmc.data.half_life
openmc.data.dose_coefficients
openmc.data.dose_coefficients(particle, geometry='AP')
Return effective dose conversion coefficients from ICRP-116
This function provides fluence (and air kerma) to effective dose conversion coefficients for various types of
external exposures based on values in ICRP Publication 116. Corrected values found in a correigendum are used
rather than the values in theoriginal report.
Parameters
• particle ({'neutron', 'photon', 'photon kerma', 'electron', 'positron'}) – In-
cident particle
• geometry ({'AP', 'PA', 'LLAT', 'RLAT', 'ROT', 'ISO'}) – Irradiation geometry assumed.
Refer to ICRP-116 (Section 3.2) for the meaning of the options here.
Returns
• energy (numpy.ndarray) – Energies at which dose conversion coefficients are given
• dose_coeffs (numpy.ndarray) – Effective dose coefficients in [pSv cm^2] at provided ener-
gies. For ‘photon kerma’, the coefficients are given in [Sv/Gy].
openmc.data.gnd_name
openmc.data.gnd_name(Z, A, m=0)
Return nuclide name using GND convention
Parameters
• Z (int) – Atomic number
• A (int) – Mass number
• m (int, optional) – Metastable state
Returns
Nuclide name in GND convention, e.g., ‘Am242_m1’
Return type
str
openmc.data.half_life
openmc.data.half_life(isotope)
Return half-life of isotope in seconds or None if isotope is stable
Half-life values are from the ENDF/B-VIII.0 decay sublibrary.
Parameters

Returns
Half-life of isotope in [s]
Return type
float
openmc.data.isotopes
openmc.data.isotopes(element)
Return naturally occurring isotopes and their abundances
Parameters
element (str) – Element symbol (e.g., ‘H’) or name (e.g., ‘helium’)
Returns
A list of tuples of (isotope, abundance)
Return type
list
Raises
ValueError – If the element name is not recognized
openmc.data.kalbach_slope
openmc.data.kalbach_slope(energy_projectile, energy_emitted, za_projectile, za_emitted, za_target)

Returns Kalbach-Mann slope from calculations.
The associated reaction is defined as: A + a -> C -> B + b
Where:
• A is the targeted nucleus,
• a is the projectile,
• C is the compound,
• B is the residual nucleus,
• b is the emitted particle.
The Kalbach-Mann slope calculation is done as defined in ENDF-6 manual BNL-203218-2018-INRE, Revision
215, File 6 description for LAW=1 and LANG=2. One exception to this, is that the entrance and emission channel
energies are not calculated with the AWR number, but approximated with the number of mass instead.
Parameters
• energy_projectile (float) – Energy of the projectile in the laboratory system in eV
• energy_emitted (float) – Energy of the emitted particle in the center of mass system in
eV
• za_projectile (int) – ZA identifier of the projectile
• za_emitted (int) – ZA identifier of the emitted particle
• za_target (int) – ZA identifier of the targeted nucleus

Raises
NotImplementedError – When the projectile is not a neutron
Returns
slope – Kalbach-Mann slope given with the same format as ACE file.
Return type
float
openmc.data.linearize
openmc.data.linearize(x, f, tolerance=0.001)
Return a tabulated representation of a one-variable function
Parameters
• x (Iterable of float) – Initial x values at which the function should be evaluated
• f (Callable) – Function of a single variable
• tolerance (float) – Tolerance on the interpolation error
Returns
• numpy.ndarray – Tabulated values of the independent variable
• numpy.ndarray – Tabulated values of the dependent variable
openmc.data.thin
openmc.data.thin(x, y, tolerance=0.001)
Check for (x,y) points that can be removed.
Parameters
• x (numpy.ndarray) – Independent variable
• y (numpy.ndarray) – Dependent variable
• tolerance (float) – Tolerance on interpolation error
Returns
• numpy.ndarray – Tabulated values of the independent variable
• numpy.ndarray – Tabulated values of the dependent variable
openmc.data.water_density
openmc.data.water_density(temperature, pressure=0.1013)
Return the density of liquid water at a given temperature and pressure.
The density is calculated from a polynomial fit using equations and values from the 2012 version of the IAPWS-
IF97 formulation. Only the equations for region 1 are implemented here. Region 1 is limited to liquid water
below 100 [MPa] with a temperature above 273.15 [K], below 623.15 [K], and below saturation.
Reference: International Association for the Properties of Water and Steam, “Revised Release on the IAPWS
Industrial Formulation 1997 for the Thermodynamic Properties of Water and Steam”, IAPWS R7-97(2012).
Parameters

• temperature (float) – Water temperature in units of [K]

• pressure (float) – Water pressure in units of [MPa]
Returns
Water density in units of [g/cm^3]
Return type
float
openmc.data.zam
openmc.data.zam(name)
Return tuple of (atomic number, mass number, metastable state)
Parameters
name (str) – Name of nuclide using GND convention, e.g., ‘Am242_m1’
Returns
Atomic number, mass number, and metastable state
Return type
3-tuple of int
6.7.3 One-dimensional Functions
Function1D A function of one independent variable with HDF5 sup-

port.
Tabulated1D A one-dimensional tabulated function.
Polynomial A power series class.
Combination Combination of multiple functions with a user-defined
operator
Sum Sum of multiple functions.
Regions1D Piecewise composition of multiple functions.
ResonancesWithBackground Cross section in resolved resonance region.
openmc.data.Function1D
class openmc.data.Function1D
A function of one independent variable with HDF5 support.
Generate function from an HDF5 dataset
Parameters
dataset (h5py.Dataset) – Dataset to read from
Returns
Function read from dataset
Return type

abstract to_hdf5(group, name='xy')

Write function to an HDF5 group
Parameters
openmc.data.Tabulated1D
class openmc.data.Tabulated1D(x, y, breakpoints=None, interpolation=None)

A one-dimensional tabulated function.
This class mirrors the TAB1 type from the ENDF-6 format. A tabulated function is specified by tabulated (x,y)
pairs along with interpolation rules that determine the values between tabulated pairs.
Once an object has been created, it can be used as though it were an actual function, e.g.:
>>> f = Tabulated1D([0, 10], [4, 5])

>>> [f(xi) for xi in numpy.linspace(0, 10, 5)]
[4.0, 4.25, 4.5, 4.75, 5.0]
Parameters
• x (Iterable of float) – Independent variable
• y (Iterable of float) – Dependent variable
• breakpoints (Iterable of int) – Breakpoints for interpolation regions
• interpolation (Iterable of int) – Interpolation scheme identification number, e.g.,
3 means y is linear in ln(x).
Variables
• x (Iterable of float) – Independent variable
• y (Iterable of float) – Dependent variable
• breakpoints (Iterable of int) – Breakpoints for interpolation regions
• interpolation (Iterable of int) – Interpolation scheme identification number, e.g.,
3 means y is linear in ln(x).
• n_regions (int) – Number of interpolation regions
• n_pairs (int) – Number of tabulated (x,y) pairs
classmethod from_ace(ace, idx=0, convert_units=True)

Create a Tabulated1D object from an ACE table.
Parameters
• ace (openmc.data.ace.Table) – An ACE table
• idx (int) – Offset to read from in XSS array (default of zero)
• convert_units (bool) – If the abscissa represents energy, indicate whether to convert
MeV to eV.
Returns
Tabulated data object

Return type
Generate tabulated function from an HDF5 dataset
Parameters
Returns
Return type
integral()
Integral of the tabulated function over its tabulated range.
Returns
Array of same length as the tabulated data that represents partial integrals from the bottom of
the range to each tabulated point.
Return type
numpy.ndarray
to_hdf5(group, name='xy')
Write tabulated function to an HDF5 group
Parameters
openmc.data.Polynomial
class openmc.data.Polynomial(coef, domain=None, window=None)

A power series class.
Parameters
coef (Iterable of float) – Polynomial coefficients in order of increasing degree
Generate function from an HDF5 dataset
Parameters
Returns
Return type
Write polynomial function to an HDF5 group
Parameters

openmc.data.Combination
class openmc.data.Combination(functions, operations)

Combination of multiple functions with a user-defined operator
This class allows you to create a callable object which represents the combination of other callable objects by
way of a series of user-defined operators connecting each of the callable objects.
Parameters
• functions (Iterable of Callable) – Functions to combine according to operations
• operations (Iterable of numpy.ufunc) – Operations to perform between functions;
note that the standard order of operations will not be followed, but can be simulated by
combinations of Combination objects. The operations parameter must have a length one less
than the number of functions.
Variables
• functions (Iterable of Callable) – Functions to combine according to operations
• operations (Iterable of numpy.ufunc) – Operations to perform between functions;
note that the standard order of operations will not be followed, but can be simulated by
combinations of Combination objects. The operations parameter must have a length one less
than the number of functions.
openmc.data.Sum
class openmc.data.Sum(functions)
Sum of multiple functions.
This class allows you to create a callable object which represents the sum of other callable objects. This is used
for redundant reactions whereby the cross section is defined as the sum of other cross sections.
Parameters
functions (Iterable of Callable) – Functions which are to be added together
Variables
functions (Iterable of Callable) – Functions which are to be added together
Generate sum of functions from an HDF5 group
Parameters
group (h5py.Group) – Group to read from
Returns
Functions read from the group
Return type
openmc.data.Sum
Write sum of functions to an HDF5 group
Parameters

openmc.data.Regions1D
class openmc.data.Regions1D(functions, breakpoints)

Piecewise composition of multiple functions.
This class allows you to create a callable object which is composed of multiple other callable objects, each
applying to a specific interval
Parameters
• functions (Iterable of Callable) – Functions which are to be combined in a piece-
wise fashion
• breakpoints (Iterable of float) – The values of the dependent variable that define
the domain of each function. The ith and (i+1)th values are the limits of the domain of the
ith function. Values must be monotonically increasing.
Variables
• functions (Iterable of Callable) – Functions which are to be combined in a piece-
wise fashion
• breakpoints (Iterable of float) – The breakpoints between each function
openmc.data.ResonancesWithBackground
class openmc.data.ResonancesWithBackground(resonances, background, mt)

Cross section in resolved resonance region.
Parameters
• resonances (openmc.data.Resonances) – Resolved resonance parameter data
• background (Callable) – Background cross section as a function of energy
• mt (int) – MT value of the reaction
Variables
• resonances (openmc.data.Resonances) – Resolved resonance parameter data
• background (Callable) – Background cross section as a function of energy
• mt (int) – MT value of the reaction

6.7.4 Angle-Energy Distributions
AngleEnergy Distribution in angle and energy of a secondary particle.

KalbachMann Kalbach-Mann distribution
CorrelatedAngleEnergy Correlated angle-energy distribution
UncorrelatedAngleEnergy Uncorrelated angle-energy distribution
NBodyPhaseSpace N-body phase space distribution
LaboratoryAngleEnergy Laboratory angle-energy distribution
AngleDistribution Angle distribution as a function of incoming energy
EnergyDistribution Abstract superclass for all energy distributions.
ArbitraryTabulated Arbitrary tabulated function given in ENDF MF=5,
LF=1 represented as
GeneralEvaporation General evaporation spectrum given in ENDF MF=5,
LF=5 represented as
MaxwellEnergy Simple Maxwellian fission spectrum represented as
Evaporation Evaporation spectrum represented as
WattEnergy Energy-dependent Watt spectrum represented as
MadlandNix Energy-dependent fission neutron spectrum (Madland
and Nix) given in ENDF MF=5, LF=12 represented as
DiscretePhoton Discrete photon energy distribution
LevelInelastic Level inelastic scattering
ContinuousTabular Continuous tabular distribution
CoherentElasticAE Differential cross section for coherent elastic scattering
IncoherentElasticAE Differential cross section for incoherent elastic scatter-
ing
IncoherentElasticAEDiscrete Discrete angle representation of incoherent elastic scat-
tering
IncoherentInelasticAEDiscrete Discrete angle representation of incoherent inelastic
scattering
MixedElasticAE Secondary distribution for mixed coherent/incoherent
thermal elastic
openmc.data.AngleEnergy
class openmc.data.AngleEnergy
Distribution in angle and energy of a secondary particle.
static from_ace(ace, location_dist, location_start, rx=None)
Generate an angle-energy distribution from ACE data
Parameters
• location_dist (int) – Index in the XSS array corresponding to the start of a block, e.g.
JXS(11) for the the DLW block.
• location_start (int) – Index in the XSS array corresponding to the start of an energy
distribution array
• rx (Reaction) – Reaction this energy distribution will be associated with
Returns
distribution – Secondary angle-energy distribution

Return type
Generate angle-energy distribution from HDF5 data
Parameters
Returns
Angle-energy distribution
Return type
openmc.data.KalbachMann
class openmc.data.KalbachMann(breakpoints, interpolation, energy, energy_out, precompound, slope)

Kalbach-Mann distribution
Parameters
• breakpoints (Iterable of int) – Breakpoints defining interpolation regions
• interpolation (Iterable of int) – Interpolation codes
• energy (Iterable of float) – Incoming energies at which distributions exist
• energy_out (Iterable of openmc.stats.Univariate) – Distribution of outgoing en-
ergies corresponding to each incoming energy
• precompound (Iterable of openmc.data.Tabulated1D) – Precompound factor ‘r’ as
a function of outgoing energy for each incoming energy
• slope (Iterable of openmc.data.Tabulated1D) – Kalbach-Chadwick angular distri-
bution slope value ‘a’ as a function of outgoing energy for each incoming energy
Variables
• precompound (Iterable of openmc.data.Tabulated1D) – Precompound factor ‘r’ as
a function of outgoing energy for each incoming energy
• slope (Iterable of openmc.data.Tabulated1D) – Kalbach-Chadwick angular distri-
bution slope value ‘a’ as a function of outgoing energy for each incoming energy
classmethod from_ace(ace, idx, ldis)
Generate Kalbach-Mann energy-angle distribution from ACE data
Parameters
• idx (int) – Index in XSS array of the start of the energy distribution data (LDIS + LOCC
- 1)

• ldis (int) – Index in XSS array of the start of the energy distribution block (e.g. JXS[11])
Returns
Kalbach-Mann energy-angle distribution
Return type
classmethod from_endf(file_obj, za_emitted, za_target, projectile_mass)
Generate Kalbach-Mann distribution from an ENDF evaluation.
If the projectile is a neutron, the slope is calculated when it is not given explicitly.
Changed in version 0.13.1: Arguments changed to accommodate slope calculation
Parameters
• file_obj (file-like object) – ENDF file positioned at the start of the Kalbach-Mann
distribution
• za_emitted (int) – ZA identifier of the emitted particle
• za_target (int) – ZA identifier of the target
• projectile_mass (float) – Mass of the projectile
Warns
UserWarning – If the mass of the projectile is not equal to 1 (other than a neutron), the slope
is not calculated and set to 0 if missing.
Returns
Kalbach-Mann energy-angle distribution
Return type
Generate Kalbach-Mann distribution from HDF5 data
Parameters
Returns
Kalbach-Mann energy distribution
Return type
to_hdf5(group)
Write distribution to an HDF5 group
Parameters

openmc.data.CorrelatedAngleEnergy
class openmc.data.CorrelatedAngleEnergy(breakpoints, interpolation, energy, energy_out, mu)

Correlated angle-energy distribution
Parameters
• mu (Iterable of Iterable of openmc.stats.Univariate) – Distribution of scatter-
ing cosine for each incoming/outgoing energy
Variables
• mu (Iterable of Iterable of openmc.stats.Univariate) – Distribution of scatter-
ing cosine for each incoming/outgoing energy
Generate correlated angle-energy distribution from ACE data
Parameters
- 1)
Returns
Return type
classmethod from_endf(file_obj)
Generate correlated angle-energy distribution from an ENDF evaluation
Parameters
file_obj (file-like object) – ENDF file positioned at the start of a section for a corre-
lated angle-energy distribution
Returns
Return type

Generate correlated angle-energy distribution from HDF5 data
Parameters
Returns
Return type
to_hdf5(group)
Parameters
openmc.data.UncorrelatedAngleEnergy
class openmc.data.UncorrelatedAngleEnergy(angle=None, energy=None)

Uncorrelated angle-energy distribution
Parameters
• angle (openmc.data.AngleDistribution) – Distribution of outgoing angles repre-
sented as scattering cosines
• energy (openmc.data.EnergyDistribution) – Distribution of outgoing energies
Variables
• angle (openmc.data.AngleDistribution) – Distribution of outgoing angles repre-
sented as scattering cosines
• energy (openmc.data.EnergyDistribution) – Distribution of outgoing energies
Generate uncorrelated angle-energy distribution from HDF5 data
Parameters
Returns
Uncorrelated angle-energy distribution
Return type
openmc.data.UncorrelatedAngleEnergy
to_hdf5(group)
Parameters

openmc.data.NBodyPhaseSpace
class openmc.data.NBodyPhaseSpace(total_mass, n_particles, atomic_weight_ratio, q_value)

N-body phase space distribution
Parameters
• total_mass (float) – Total mass of product particles
• n_particles (int) – Number of product particles
• atomic_weight_ratio (float) – Atomic weight ratio of target nuclide
• q_value (float) – Q value for reaction in eV
Variables
• total_mass (float) – Total mass of product particles
• atomic_weight_ratio (float) – Atomic weight ratio of target nuclide
• q_value (float) – Q value for reaction in eV
classmethod from_ace(ace, idx, q_value)
Generate N-body phase space distribution from ACE data
Parameters
- 1)
• q_value (float) – Q-value for reaction in eV
Returns
Return type
Generate N-body phase space distribution from an ENDF evaluation
Parameters
file_obj (file-like object) – ENDF file positions at the start of the N-body phase space
distribution
Returns
Return type
Generate N-body phase space distribution from HDF5 data
Parameters
Returns

Return type
to_hdf5(group)
Parameters
openmc.data.LaboratoryAngleEnergy
class openmc.data.LaboratoryAngleEnergy(breakpoints, interpolation, energy, mu, energy_out)

Laboratory angle-energy distribution
Parameters
• mu (Iterable of openmc.stats.Univariate) – Distribution of scattering cosines for
each incoming energy
• energy_out (Iterable of Iterable of openmc.stats.Univariate) – Distribution
of outgoing energies for each incoming energy/scattering cosine
Variables
• mu (Iterable of openmc.stats.Univariate) – Distribution of scattering cosines for
each incoming energy
• energy_out (Iterable of Iterable of openmc.stats.Univariate) – Distribution
of outgoing energies for each incoming energy/scattering cosine
Generate laboratory angle-energy distribution from an ENDF evaluation
Parameters
file_obj (file-like object) – ENDF file positioned at the start of a section for a corre-
lated angle-energy distribution
Returns
Laboratory angle-energy distribution
Return type
openmc.data.LaboratoryAngleEnergy

openmc.data.AngleDistribution
class openmc.data.AngleDistribution(energy, mu)

Angle distribution as a function of incoming energy
Parameters
• energy (Iterable of float) – Incoming energies in eV at which distributions exist
• mu (Iterable of openmc.stats.Univariate) – Distribution of scattering cosines cor-
responding to each incoming energy
Variables
• energy (Iterable of float) – Incoming energies in eV at which distributions exist
• mu (Iterable of openmc.stats.Univariate) – Distribution of scattering cosines cor-
responding to each incoming energy
classmethod from_ace(ace, location_dist, location_start)
Generate an angular distribution from ACE data
Parameters
• location_dist (int) – Index in the XSS array corresponding to the start of a block, e.g.
JXS(9).
• location_start (int) – Index in the XSS array corresponding to the start of an angle
distribution array
Returns
Angular distribution
Return type
Generate an angular distribution from an ENDF evaluation
Parameters
• mt (int) – The MT value of the reaction to get angular distributions for
Returns
Return type
Generate angular distribution from HDF5 data
Parameters
Returns
Return type

to_hdf5(group)
Write angle distribution to an HDF5 group
Parameters
openmc.data.EnergyDistribution
class openmc.data.EnergyDistribution
Abstract superclass for all energy distributions.
static from_endf(file_obj, params)
Generate energy distribution from an ENDF evaluation
Parameters
• file_obj (file-like object) – ENDF file positioned at the start of a section for an
energy distribution.
• params (list) – List of parameters at the start of the energy distribution that includes the
LF value indicating what type of energy distribution is present.
Returns
A sub-class of openmc.data.EnergyDistribution
Return type
Generate energy distribution from HDF5 data
Parameters
Returns
Energy distribution
Return type
openmc.data.ArbitraryTabulated
class openmc.data.ArbitraryTabulated(energy, pdf )

Arbitrary tabulated function given in ENDF MF=5, LF=1 represented as
𝑓 (𝐸 → 𝐸 ′ ) = 𝑔(𝐸 → 𝐸 ′ )
Parameters
• energy (numpy.ndarray) – Array of incident neutron energies
• pdf (list of openmc.data.Tabulated1D) – Tabulated outgoing energy distribution
probability density functions
Variables
• energy (numpy.ndarray) – Array of incident neutron energies
• pdf (list of openmc.data.Tabulated1D) – Tabulated outgoing energy distribution
probability density functions

classmethod from_endf(file_obj, params)

Generate arbitrary tabulated distribution from an ENDF evaluation
Parameters
Returns
Arbitrary tabulated distribution
Return type
openmc.data.ArbitraryTabulated
openmc.data.GeneralEvaporation
class openmc.data.GeneralEvaporation(theta, g, u)
General evaporation spectrum given in ENDF MF=5, LF=5 represented as
𝑓 (𝐸 → 𝐸 ′ ) = 𝑔(𝐸 ′ /𝜃(𝐸))
Parameters
• theta (openmc.data.Tabulated1D) – Tabulated function of incident neutron energy 𝐸
• g (openmc.data.Tabulated1D) – Tabulated function of 𝑥 = 𝐸 ′ /𝜃(𝐸)
• u (float) – Constant introduced to define the proper upper limit for the final particle energy
such that 0 ≤ 𝐸 ′ ≤ 𝐸 − 𝑈
Variables
• theta (openmc.data.Tabulated1D) – Tabulated function of incident neutron energy 𝐸
• g (openmc.data.Tabulated1D) – Tabulated function of 𝑥 = 𝐸 ′ /𝜃(𝐸)
Generate general evaporation spectrum from an ENDF evaluation
Parameters
Returns
General evaporation spectrum
Return type
openmc.data.GeneralEvaporation

openmc.data.MaxwellEnergy
class openmc.data.MaxwellEnergy(theta, u)
Simple Maxwellian fission spectrum represented as
√
′ 𝐸 ′ −𝐸 ′ /𝜃(𝐸)
𝑓 (𝐸 → 𝐸 ) = 𝑒
𝐼
Parameters
• theta (openmc.data.Tabulated1D) – Tabulated function of incident neutron energy
Variables
classmethod from_ace(ace, idx=0)
Create a Maxwell distribution from an ACE table
Parameters
Returns
Maxwell distribution
Return type
Generate Maxwell distribution from an ENDF evaluation
Parameters
Returns
Return type
Generate Maxwell distribution from HDF5 data
Parameters
Returns

Return type
to_hdf5(group)
Parameters
openmc.data.Evaporation
class openmc.data.Evaporation(theta, u)
Evaporation spectrum represented as
𝐸 ′ −𝐸 ′ /𝜃(𝐸)
𝑓 (𝐸 → 𝐸 ′ ) = 𝑒
𝐼
Parameters
Variables
classmethod from_ace(ace, idx=0)
Create an evaporation spectrum from an ACE table
Parameters
Returns
Evaporation spectrum
Return type
Generate evaporation spectrum from an ENDF evaluation
Parameters
Returns
Return type

Generate evaporation spectrum from HDF5 data
Parameters
Returns
Return type
to_hdf5(group)
Parameters
openmc.data.WattEnergy
class openmc.data.WattEnergy(a, b, u)
Energy-dependent Watt spectrum represented as
′ (︁√
𝑒−𝐸 /𝑎 )︁
𝑓 (𝐸 → 𝐸 ′ ) = sinh 𝑏𝐸 ′
𝐼
Parameters
• a (openmc.data.Tabulated1D) – Energy-dependent parameters tabulated as function of
incident neutron energy
• b (openmc.data.Tabulated1D) – Energy-dependent parameters tabulated as function of
incident neutron energy
Variables
• b (a,) – Energy-dependent parameters tabulated as function of incident neutron energy
classmethod from_ace(ace, idx)
Create a Watt fission spectrum from an ACE table
Parameters
Returns
Watt fission spectrum
Return type


Generate Watt fission spectrum from an ENDF evaluation
Parameters
Returns
Return type
Generate Watt fission spectrum from HDF5 data
Parameters
Returns
Return type
to_hdf5(group)
Parameters
openmc.data.MadlandNix
class openmc.data.MadlandNix(efl, efh, tm)

Energy-dependent fission neutron spectrum (Madland and Nix) given in ENDF MF=5, LF=12 represented as
1
𝑓 (𝐸 → 𝐸 ′ ) = [𝑔(𝐸 ′ , 𝐸𝐹 (𝐿)) + 𝑔(𝐸 ′ , 𝐸𝐹 (𝐻))]
2
where
[︂ (︂ )︂ (︂ )︂]︂
1 3/2 3/2 3 3
𝑔(𝐸 ′ , 𝐸𝐹 ) = √ 𝑢2 𝐸1 (𝑢2 ) − 𝑢1 𝐸1 (𝑢1 ) + 𝛾 , 𝑢2 − 𝛾 , 𝑢1
3 𝐸𝐹 𝑇𝑀 2 2
(︁√ √︀ )︁2
𝑢1 = 𝐸 ′ − 𝐸𝐹 /𝑇𝑀
(︁√ √︀ )︁2
𝑢2 = 𝐸 ′ + 𝐸𝐹 /𝑇𝑀 .
Parameters
• efl (float) – Constants which represent the average kinetic energy per nucleon of the fis-
sion fragment (efl = light, efh = heavy)
• efh (float) – Constants which represent the average kinetic energy per nucleon of the fis-
sion fragment (efl = light, efh = heavy)

• tm (openmc.data.Tabulated1D) – Parameter tabulated as a function of incident neutron

energy
Variables
• efh (efl,) – Constants which represent the average kinetic energy per nucleon of the fission
fragment (efl = light, efh = heavy)
• tm (openmc.data.Tabulated1D) – Parameter tabulated as a function of incident neutron
energy
Generate Madland-Nix fission spectrum from an ENDF evaluation
Parameters
Returns
Madland-Nix fission spectrum
Return type
Generate Madland-Nix fission spectrum from HDF5 data
Parameters
Returns
Madland-Nix fission spectrum
Return type
to_hdf5(group)
Parameters
openmc.data.DiscretePhoton
class openmc.data.DiscretePhoton(primary_flag, energy, atomic_weight_ratio)

Discrete photon energy distribution
Parameters
• primary_flag (int) – Indicator of whether the photon is a primary or non-primary photon.
• energy (float) – Photon energy (if lp==0 or lp==1) or binding energy (if lp==2).
• atomic_weight_ratio (float) – Atomic weight ratio of the target nuclide responsible for
the emitted particle
Variables
• primary_flag (int) – Indicator of whether the photon is a primary or non-primary photon.

• energy (float) – Photon energy (if lp==0 or lp==1) or binding energy (if lp==2).
• atomic_weight_ratio (float) – Atomic weight ratio of the target nuclide responsible for
the emitted particle
Generate discrete photon energy distribution from an ACE table
Parameters
Returns
Return type
Generate discrete photon energy distribution from HDF5 data
Parameters
Returns
Return type
to_hdf5(group)
Parameters
openmc.data.LevelInelastic
class openmc.data.LevelInelastic(threshold, mass_ratio)

Level inelastic scattering
Parameters
• threshold (float) – Energy threshold in the laboratory system, (𝐴 + 1)/𝐴 * |𝑄|
• mass_ratio (float) – (𝐴/(𝐴 + 1))2
Variables
• threshold (float) – Energy threshold in the laboratory system, (𝐴 + 1)/𝐴 * |𝑄|
• mass_ratio (float) – (𝐴/(𝐴 + 1))2
Generate level inelastic distribution from an ACE table
Parameters

Returns
Level inelastic scattering distribution
Return type
Generate level inelastic distribution from HDF5 data
Parameters
Returns
Level inelastic scattering distribution
Return type
to_hdf5(group)
Parameters
openmc.data.ContinuousTabular
class openmc.data.ContinuousTabular(breakpoints, interpolation, energy, energy_out)

Continuous tabular distribution
Parameters
Variables
Generate continuous tabular energy distribution from ACE data
Parameters
- 1)

Returns
Continuous tabular energy distribution
Return type
Generate continuous tabular distribution from HDF5 data
Parameters
Returns
Continuous tabular energy distribution
Return type
to_hdf5(group)
Parameters
openmc.data.CoherentElasticAE
class openmc.data.CoherentElasticAE(coherent_xs)
Differential cross section for coherent elastic scattering
The differential cross section for coherent elastic scattering from a powdered crystalline material may be repre-
sented as:
𝐸𝑖 <𝐸
𝑑2 𝜎 ′ 1 ∑︁
(𝐸 → 𝐸 , 𝜇, 𝑇 ) = 𝑠𝑖 (𝑇 )𝛿(𝜇 − 𝜇𝑖 )𝛿(𝐸 − 𝐸 ′ )/(2𝜋)
𝑑𝐸 ′ 𝑑Ω 𝐸 𝑖=1
where 𝐸𝑖 are the energies of the Bragg edges in [eV], 𝑠𝑖 (𝑇 ) is the structure factor in [eV-b] at the moderator
temperature 𝑇 in [K], and 𝜇𝑖 = 1 − 2𝐸𝑖 /𝐸.
Parameters
coherent_xs (openmc.data.CoherentElastic) – Coherent elastic scattering cross section
Variables
coherent_xs (openmc.data.CoherentElastic) – Coherent elastic scattering cross section
Generate coherent elastic distribution from HDF5 data
Parameters
Returns
Coherent elastic distribution
Return type
openmc.data.CoherentElasticAE

to_hdf5(group)
Write coherent elastic distribution to an HDF5 group
Parameters
openmc.data.IncoherentElasticAE
class openmc.data.IncoherentElasticAE(debye_waller)
Differential cross section for incoherent elastic scattering
The differential cross section for incoherent elastic scattering may be represented as:
𝑑2 𝜎 𝜎𝑏 −2𝐸𝑊 ′ (𝑇 )(1−𝜇)
(𝐸 → 𝐸 ′ , 𝜇, 𝑇 ) = 𝑒 𝛿(𝐸 − 𝐸 ′ )
𝑑𝐸 ′ 𝑑Ω 4𝜋
where 𝜎𝑏 is the characteristic cross section in [b] and 𝑊 ′ (𝑇 ) is the Debye-Waller integral divided by the atomic
mass in [eV−1 ].
Parameters
debye_waller (float) – Debye-Waller integral in [eV−1 ]
Variables
debye_waller (float) – Debye-Waller integral in [eV−1 ]
Generate incoherent elastic distribution from HDF5 data
Parameters
Returns
Incoherent elastic distribution
Return type
openmc.data.IncoherentElasticAE
to_hdf5(group)
Write incoherent elastic distribution to an HDF5 group
Parameters
openmc.data.IncoherentElasticAEDiscrete
class openmc.data.IncoherentElasticAEDiscrete(mu_out)
Discrete angle representation of incoherent elastic scattering
Parameters
mu_out (numpy.ndarray) – Equi-probable discrete angles at each incoming energy
Generate discrete incoherent elastic distribution from HDF5 data
Parameters
Returns
Discrete incoherent elastic distribution

Return type
openmc.data.IncoherentElasticAEDiscrete
to_hdf5(group)
Write discrete incoherent elastic distribution to an HDF5 group
Parameters
openmc.data.IncoherentInelasticAEDiscrete
class openmc.data.IncoherentInelasticAEDiscrete(energy_out, mu_out, skewed=False)

Discrete angle representation of incoherent inelastic scattering
Parameters
• energy_out (numpy.ndarray) – Outgoing energies for each incoming energy
• mu_out (numpy.ndarray) – Discrete angles for each incoming/outgoing energy
• skewed (bool) – Whether discrete angles are equi-probable or have a skewed distribution
Variables
• energy_out (numpy.ndarray) – Outgoing energies for each incoming energy
• mu_out (numpy.ndarray) – Discrete angles for each incoming/outgoing energy
• skewed (bool) – Whether discrete angles are equi-probable or have a skewed distribution
Generate discrete incoherent inelastic distribution from HDF5 data
Parameters
Returns
Discrete incoherent inelastic distribution
Return type
openmc.data.IncoherentInelasticAEDiscrete
to_hdf5(group)
Write discrete incoherent inelastic distribution to an HDF5 group
Parameters
openmc.data.MixedElasticAE
class openmc.data.MixedElasticAE(coherent, incoherent)

Secondary distribution for mixed coherent/incoherent thermal elastic
Parameters
• coherent (AngleEnergy) – Secondary distribution for coherent elastic scattering
• incoherent (AngleEnergy) – Secondary distribution for incoherent elastic scattering
Variables

• coherent (AngleEnergy) – Secondary distribution for coherent elastic scattering

• incoherent (AngleEnergy) – Secondary distribution for incoherent elastic scattering
Generate mixed thermal elastic distribution from HDF5 data
Parameters
Returns
Mixed thermal elastic distribution
Return type
openmc.data.MixedElasticAE
to_hdf5(group)
Write mixed elastic distribution to an HDF5 group
Parameters
6.7.5 Resonance Data
Resonances Resolved and unresolved resonance data

ResonanceRange Resolved resonance range
SingleLevelBreitWigner Single-level Breit-Wigner resolved resonance formalism
data.
MultiLevelBreitWigner Multi-level Breit-Wigner resolved resonance formalism
data.
ReichMoore Reich-Moore resolved resonance formalism data.
RMatrixLimited R-matrix limited resolved resonance formalism data.
ResonanceCovariances Resolved resonance covariance data
ResonanceCovarianceRange Resonace covariance range.
SingleLevelBreitWignerCovariance Single-level Breit-Wigner resolved resonance formalism
covariance data.
MultiLevelBreitWignerCovariance Multi-level Breit-Wigner resolved resonance formalism
covariance data.
ReichMooreCovariance Reich-Moore resolved resonance formalism covariance
data.
ParticlePair
SpinGroup Resonance spin group

Unresolved Unresolved resonance parameters as identified by
LRU=2 in MF=2.

openmc.data.Resonances
class openmc.data.Resonances(ranges)
Resolved and unresolved resonance data
Parameters
ranges (list of openmc.data.ResonanceRange) – Distinct energy ranges for resonance
data
Variables
• ranges (list of openmc.data.ResonanceRange) – Distinct energy ranges for reso-
nance data
• resolved (openmc.data.ResonanceRange or None) – Resolved resonance range
• unresolved (openmc.data.Unresolved or None) – Unresolved resonance range
classmethod from_endf(ev)
Generate resonance data from an ENDF evaluation.
Parameters
ev (openmc.data.endf.Evaluation) – ENDF evaluation
Returns
Resonance data
Return type
openmc.data.Resonances
openmc.data.ResonanceRange
class openmc.data.ResonanceRange(target_spin, energy_min, energy_max, channel, scattering)

Resolved resonance range
Parameters
• target_spin (float) – Intrinsic spin, 𝐼, of the target nuclide
• energy_min (float) – Minimum energy of the resolved resonance range in eV
• energy_max (float) – Maximum energy of the resolved resonance range in eV
• channel (dict) – Dictionary whose keys are l-values and values are channel radii as a
function of energy
• scattering (dict) – Dictionary whose keys are l-values and values are scattering radii as
a function of energy
Variables
• channel_radius (dict) – Dictionary whose keys are l-values and values are channel radii
as a function of energy
• scattering_radius (dict) – Dictionary whose keys are l-values and values are scattering
radii as a function of energ

classmethod from_endf(ev, file_obj, items)

Create resonance range from an ENDF evaluation.
This factory method is only used when LRU=0, indicating that only a scattering radius appears in MF=2,
MT=151. All subclasses of ResonanceRange override this method with their own.
Parameters
• file_obj (file-like object) – ENDF file positioned at the second record of a reso-
nance range subsection in MF=2, MT=151
• items (list) – Items from the CONT record at the start of the resonance range subsection
Returns
Resonance range data
Return type
openmc.data.ResonanceRange
reconstruct(energies)
Evaluate cross section at specified energies.
Parameters
energies (float or Iterable of float) – Energies at which the cross section should
be evaluated
Returns
Elastic, capture, and fission cross sections at the specified energies
Return type
3-tuple of float or numpy.ndarray
openmc.data.SingleLevelBreitWigner
class openmc.data.SingleLevelBreitWigner(target_spin, energy_min, energy_max, channel, scattering)

Single-level Breit-Wigner resolved resonance formalism data.
Single-level Breit-Wigner resolved resonance data is is identified by LRF=1 in the ENDF-6 format.
Parameters
function of energy
Variables
• atomic_weight_ratio (float) – Atomic weight ratio of the target nuclide given as a
function of l-value. Note that this may be different than the value for the evaluation as a
whole.


• parameters (pandas.DataFrame) – Energies, spins, and resonances widths for each res-
onance
• q_value (dict) – Q-value to be added to incident particle’s center-of-mass energy to de-
termine the channel energy for use in the penetrability factor. The keys of the dictionary are
l-values.
radii as a function of energy
openmc.data.MultiLevelBreitWigner
class openmc.data.MultiLevelBreitWigner(target_spin, energy_min, energy_max, channel, scattering)

Multi-level Breit-Wigner resolved resonance formalism data.
Multi-level Breit-Wigner resolved resonance data is identified by LRF=2 in the ENDF-6 format.
Parameters
function of energy
Variables
whole.
onance
• q_value (dict) – Q-value to be added to incident particle’s center-of-mass energy to de-
termine the channel energy for use in the penetrability factor. The keys of the dictionary are
l-values.


Create MLBW data from an ENDF evaluation.
Parameters
Returns
Multi-level Breit-Wigner resonance parameters
Return type
openmc.data.MultiLevelBreitWigner
openmc.data.ReichMoore
class openmc.data.ReichMoore(target_spin, energy_min, energy_max, channel, scattering)

Reich-Moore resolved resonance formalism data.
Reich-Moore resolved resonance data is identified by LRF=3 in the ENDF-6 format.
Parameters
function of energy
Variables
• angle_distribution (bool) – Indicate whether parameters can be used to compute an-
gular distributions
whole.
• num_l_convergence (int) – Number of l-values which must be used to converge the cal-
culation
onance


Create Reich-Moore resonance data from an ENDF evaluation.
Parameters
Returns
Reich-Moore resonance parameters
Return type
openmc.data.ReichMoore
openmc.data.RMatrixLimited
class openmc.data.RMatrixLimited(energy_min, energy_max, particle_pairs, spin_groups)

R-matrix limited resolved resonance formalism data.
R-matrix limited resolved resonance data is identified by LRF=7 in the ENDF-6 format.
Parameters
• particle_pairs (list of dict) – List of particle pairs. Each particle pair is represented
by a dictionary that contains the mass, atomic number, spin, and parity of each particle as
well as other characteristics.
• spin_groups (list of dict) – List of spin groups. Each spin group is characterized by
channels, resonance energies, and resonance widths.
Variables
• reduced_width (bool) – Flag indicating whether channel widths in eV or reduced-width
amplitudes in eV^1/2 are given
• formalism (int) – Flag to specify which formulae for the R-matrix are to be used
• particle_pairs (list of dict) – List of particle pairs. Each particle pair is represented
by a dictionary that contains the mass, atomic number, spin, and parity of each particle as
well as other characteristics.
• spin_groups (list of dict) – List of spin groups. Each spin group is characterized by
channels, resonance energies, and resonance widths.
Read R-Matrix limited resonance data from an ENDF evaluation.
Parameters

Returns
R-matrix limited resonance parameters
Return type
openmc.data.RMatrixLimited
openmc.data.ResonanceCovariances
class openmc.data.ResonanceCovariances(ranges)
Resolved resonance covariance data
Parameters
ranges (list of openmc.data.ResonanceCovarianceRange) – Distinct energy ranges for
resonance data
Variables
ranges (list of openmc.data.ResonanceCovarianceRange) – Distinct energy ranges for
resonance data
classmethod from_endf(ev, resonances)
Generate resonance covariance data from an ENDF evaluation.
Parameters
• resonances (openmc.data.Resonance object) – openmc.data.Resonanance object
generated from the same evaluation used to import values not contained in File 32
Returns
Resonance covariance data
Return type
openmc.data.ResonanceCovariances
openmc.data.ResonanceCovarianceRange
class openmc.data.ResonanceCovarianceRange(energy_min, energy_max)

Resonace covariance range. Base class for different formalisms.
Parameters
Variables
• parameters (pandas.DataFrame) – Resonance parameters
• covariance (numpy.array) – The covariance matrix contained within the ENDF evalua-
tion
• lcomp (int) – Flag indicating format of the covariance matrix within the ENDF file

• file2res (openmc.data.ResonanceRange object) – Corresponding resonance range

with File 2 data.
• mpar (int) – Number of parameters in covariance matrix for each individual resonance
• formalism (str) – String descriptor of formalism
sample(n_samples)
Sample resonance parameters based on the covariances provided within an ENDF evaluation.
Parameters
n_samples (int) – The number of samples to produce
Returns
samples – List of samples size n_samples
Return type
list of openmc.data.ResonanceCovarianceRange objects
subset(parameter_str, bounds)
Produce a subset of resonance parameters and the corresponding covariance matrix to an IncidentNeutron
object.
Parameters
• parameter_str (str) – parameter to be discriminated (i.e. ‘energy’, ‘captureWidth’,
‘fissionWidthA’. . . )
• bounds (np.array) – [low numerical bound, high numerical bound]
Returns
res_cov_range – ResonanceCovarianceRange object that contains a subset of the covariance
matrix (upper triangular) as well as a subset parameters within self.file2params
Return type
openmc.data.ResonanceCovarianceRange
openmc.data.SingleLevelBreitWignerCovariance
class openmc.data.SingleLevelBreitWignerCovariance(energy_min, energy_max, parameters, covariance,

mpar, lcomp, file2res)
Single-level Breit-Wigner resolved resonance formalism covariance data. Single-level Breit-Wigner resolved
resonance data is is identified by LRF=1 in the ENDF-6 format.
Parameters
Variables
tion


with File 2 data.
openmc.data.MultiLevelBreitWignerCovariance
class openmc.data.MultiLevelBreitWignerCovariance(energy_min, energy_max, parameters, covariance,

mpar, lcomp, file2res)
Multi-level Breit-Wigner resolved resonance formalism covariance data. :param energy_min: Minimum energy
of the resolved resonance range in eV :type energy_min: float :param energy_max: Maximum energy of the
resolved resonance range in eV :type energy_max: float
Variables
tion
with File 2 data.
classmethod from_endf(ev, file_obj, items, resonance)
Create MLBW covariance data from an ENDF evaluation.
Parameters
• resonance (openmc.data.ResonanceRange object) – Corresponding resonance
range with File 2 data.
Returns
Multi-level Breit-Wigner resonance covariance parameters
Return type
openmc.data.MultiLevelBreitWignerCovariance

openmc.data.ReichMooreCovariance
class openmc.data.ReichMooreCovariance(energy_min, energy_max, parameters, covariance, mpar, lcomp,

file2res)
Reich-Moore resolved resonance formalism covariance data.
Reich-Moore resolved resonance data is identified by LRF=3 in the ENDF-6 format.
Parameters
Variables
tion
with File 2 data.
classmethod from_endf(ev, file_obj, items, resonance)
Create Reich-Moore resonance covariance data from an ENDF evaluation. Includes the resonance param-
eters contained separately in File 32.
Parameters
• resonance (openmc.data.Resonance object) – openmc.data.Resonanance object
generated from the same evaluation used to import values not contained in File 32
Returns
Reich-Moore resonance covariance parameters
Return type
openmc.data.ReichMooreCovariance

openmc.data.ParticlePair
class openmc.data.ParticlePair(first, second, q_value, penetrability, shift, mt)
openmc.data.SpinGroup
class openmc.data.SpinGroup(spin, parity, channels, parameters)

Resonance spin group
Variables
• spin (float) – Total angular momentum (nuclear spin)
• parity ({'+', '-'}) – Even (+) or odd(-) parity
• channels (list of openmc.data.Channel) – Available channels
• parameters (pandas.DataFrame) – Energies/widths for each resonance/channel
openmc.data.Unresolved
class openmc.data.Unresolved(target_spin, energy_min, energy_max, channel, scattering)

Unresolved resonance parameters as identified by LRU=2 in MF=2.
Parameters
• energy_min (float) – Minimum energy of the unresolved resonance range in eV
• energy_max (float) – Maximum energy of the unresolved resonance range in eV
• channel (openmc.data.Function1D) – Channel radii as a function of energy
• scattering (openmc.data.Function1D) – Scattering radii as a function of energy
Variables
• add_to_background (bool) – If True, file 3 contains partial cross sections to be added to
the average unresolved cross sections calculated from parameters.
• atomic_weight_ratio (float) – Atomic weight ratio of the target nuclide
• channel_radius (openmc.data.Function1D) – Channel radii as a function of energy
• energies (Iterable of float) – Energies at which parameters are tabulated
• energy_max (float) – Maximum energy of the unresolved resonance range in eV
• energy_min (float) – Minimum energy of the unresolved resonance range in eV
• parameters (list of pandas.DataFrame) – Average resonance parameters at each en-
ergy
• scattering_radius (openmc.data.Function1D) – Scattering radii as a function of en-
ergy

classmethod from_endf(file_obj, items, fission_widths)

Read unresolved resonance data from an ENDF evaluation.
Parameters
• fission_widths (bool) – Whether fission widths are given
Returns
Unresolved resonance region parameters
Return type
openmc.data.Unresolved
6.7.6 ACE Format
Classes
ace.Library A Library objects represents an ACE-formatted file

which may contain multiple tables with data.
ace.Table ACE cross section table
ace.TableType Type of ACE data table.
openmc.data.ace.Library
class openmc.data.ace.Library(filename, table_names=None, verbose=False)

A Library objects represents an ACE-formatted file which may contain multiple tables with data.
Parameters
• filename (str) – Path of the ACE library file to load.
• table_names (None, str, or iterable, optional) – Tables from the file to read in.
If None, reads in all of the tables. If str, reads in only the single table of a matching name.
• verbose (bool, optional) – Determines whether output is printed to the stdout when
reading a Library
Variables
tables (list) – List of Table instances
openmc.data.ace.Table
class openmc.data.ace.Table(name, atomic_weight_ratio, temperature, pairs, nxs, jxs, xss)

ACE cross section table
Parameters
• name (str) – ZAID identifier of the table, e.g. ‘92235.70c’.
• temperature (float) – Temperature of the target nuclide in MeV.

• pairs (list of tuple) – 16 pairs of ZAIDs and atomic weight ratios. Used for thermal
scattering tables to indicate what isotopes scattering is applied to.
• nxs (numpy.ndarray) – Array that defines various lengths with in the table
• jxs (numpy.ndarray) – Array that gives locations in the xss array for various blocks of
data
• xss (numpy.ndarray) – Raw data for the ACE table
Variables
data_type (TableType) – Type of the ACE data
openmc.data.ace.TableType
class openmc.data.ace.TableType(value)
Type of ACE data table.
classmethod from_suffix(suffix)
Determine ACE table type from a suffix.
Parameters
suffix (str) – Single letter ACE table designator, e.g., ‘c’
Returns
ACE table type
Return type
TableType
Functions
ace.ascii_to_binary Convert an ACE file in ASCII format (type 1) to binary

format (type 2).
ace.get_libraries_from_xsdir Determine paths to ACE files from an MCNP xsdir file.
ace.get_libraries_from_xsdata Determine paths to ACE files from a Serpent xsdata file.
openmc.data.ace.ascii_to_binary
openmc.data.ace.ascii_to_binary(ascii_file, binary_file)
Convert an ACE file in ASCII format (type 1) to binary format (type 2).
Parameters
• ascii_file (str) – Filename of ASCII ACE file
• binary_file (str) – Filename of binary ACE file to be written

openmc.data.ace.get_libraries_from_xsdir
openmc.data.ace.get_libraries_from_xsdir(path)
Determine paths to ACE files from an MCNP xsdir file.
Parameters
path (str or path-like) – Path to xsdir file
Returns
List of paths to ACE libraries
Return type
list
openmc.data.ace.get_libraries_from_xsdata
openmc.data.ace.get_libraries_from_xsdata(path)
Determine paths to ACE files from a Serpent xsdata file.
Parameters
path (str or path-like) – Path to xsdata file
Returns
List of paths to ACE libraries
Return type
list
6.7.7 ENDF Format
Classes
endf.Evaluation ENDF material evaluation with multiple files/sections
openmc.data.endf.Evaluation
class openmc.data.endf.Evaluation(filename_or_obj)
ENDF material evaluation with multiple files/sections
Parameters
filename_or_obj (str or file-like) – Path to ENDF file to read or an open file positioned
at the start of an ENDF material
Variables
• info (dict) – Miscellaneous information about the evaluation.
• target (dict) – Information about the target material, such as its mass, isomeric state,
whether it’s stable, and whether it’s fissionable.
• projectile (dict) – Information about the projectile such as its mass.
• reaction_list (list of 4-tuples) – List of sections in the evaluation. The entries of
the tuples are the file (MF), section (MT), number of records (NC), and modification indicator
(MOD).

Functions
endf.float_endf
endf.get_cont_record Return data from a CONT record in an ENDF-6 file.

endf.get_evaluations Return a list of all evaluations within an ENDF file.
endf.get_head_record Return data from a HEAD record in an ENDF-6 file.
endf.get_tab1_record Return data from a TAB1 record in an ENDF-6 file.
endf.get_tab2_record
endf.get_text_record Return data from a TEXT record in an ENDF-6 file.
openmc.data.endf.float_endf
openmc.data.endf.float_endf()
openmc.data.endf.get_cont_record
openmc.data.endf.get_cont_record(file_obj, skip_c=False)
Return data from a CONT record in an ENDF-6 file.
Parameters
• file_obj (file-like object) – ENDF-6 file to read from
• skip_c (bool) – Determine whether to skip the first two quantities (C1, C2) of the CONT
record.
Returns
The six items within the CONT record
Return type
tuple
openmc.data.endf.get_evaluations
openmc.data.endf.get_evaluations(filename)
Return a list of all evaluations within an ENDF file.
Parameters
filename (str) – Path to ENDF-6 formatted file
Returns
A list of openmc.data.endf.Evaluation instances.
Return type
list

openmc.data.endf.get_head_record
openmc.data.endf.get_head_record(file_obj)
Return data from a HEAD record in an ENDF-6 file.
Parameters
file_obj (file-like object) – ENDF-6 file to read from
Returns
The six items within the HEAD record
Return type
tuple
openmc.data.endf.get_tab1_record
openmc.data.endf.get_tab1_record(file_obj)
Return data from a TAB1 record in an ENDF-6 file.
Parameters
Returns
• list – The six items within the header
• openmc.data.Tabulated1D – The tabulated function
openmc.data.endf.get_tab2_record
openmc.data.endf.get_tab2_record(file_obj)
openmc.data.endf.get_text_record
openmc.data.endf.get_text_record(file_obj)
Return data from a TEXT record in an ENDF-6 file.
Parameters
Returns
Text within the TEXT record
Return type
str

6.7.8 NJOY Interface
njoy.run Run NJOY with given commands

njoy.make_pendf Generate pointwise ENDF file from an ENDF file
njoy.make_ace Generate incident neutron ACE file from an ENDF file
njoy.make_ace_thermal Generate thermal scattering ACE file from ENDF files
openmc.data.njoy.run
openmc.data.njoy.run(commands, tapein, tapeout, input_filename=None, stdout=False, njoy_exec='njoy')

Run NJOY with given commands
Parameters
• commands (str) – Input commands for NJOY
• tapein (dict) – Dictionary mapping tape numbers to paths for any input files
• tapeout (dict) – Dictionary mapping tape numbers to paths for any output files
• input_filename (str, optional) – File name to write out NJOY input commands
• stdout (bool, optional) – Whether to display output when running NJOY
• njoy_exec (str, optional) – Path to NJOY executable
Raises
subprocess.CalledProcessError – If the NJOY process returns with a non-zero status
openmc.data.njoy.make_pendf
openmc.data.njoy.make_pendf(filename, pendf='pendf', error=0.001, stdout=False)

Generate pointwise ENDF file from an ENDF file
Parameters
• pendf (str, optional) – Path of pointwise ENDF file to write
• error (float, optional) – Fractional error tolerance for NJOY processing
• stdout (bool) – Whether to display NJOY standard output
Raises
openmc.data.njoy.make_ace
openmc.data.njoy.make_ace(filename, temperatures=None, acer=True, xsdir=None, output_dir=None,

pendf=False, error=0.001, broadr=True, heatr=True, gaspr=True, purr=True,
evaluation=None, smoothing=True, **kwargs)
Generate incident neutron ACE file from an ENDF file
File names can be passed to [acer, xsdir, pendf, broadr, heatr, gaspr, purr] to specify the exact
output for the given module. Otherwise, the files will be writen to the current directory or directory specified by
output_dir. Default file names mirror the variable names, e.g. heatr output will be written to a file named
heatr unless otherwise specified.

Parameters
• temperatures (iterable of float, optional) – Temperatures in Kelvin to produce
ACE files at. If omitted, data is produced at room temperature (293.6 K).
• acer (bool or str, optional) – Flag indicating if acer should be run. If a string is give,
write the resulting ace file to this location. Path of ACE file to write. Defaults to "ace"
• xsdir (str, optional) – Path of xsdir file to write. Defaults to "xsdir" in the same
directory as acer
• output_dir (str, optional) – Directory to write output for requested modules. If not
provided and at least one of [pendf, broadr, heatr, gaspr, purr, acer] is True,
then write output files to current directory. If given, must be a path to a directory.
• pendf (str, optional) – Path of pendf file to write. If omitted, the pendf file is not saved.
• broadr (bool or str, optional) – Indicating whether to Doppler broaden XS when
running NJOY. If string, write the output tape to this file.
• heatr (bool or str, optional) – Indicating whether to add heating kerma when run-
ning NJOY. If string, write the output tape to this file.
• gaspr (bool or str, optional) – Indicating whether to add gas production data when
running NJOY. If string, write the output tape to this file.
• purr (bool or str, optional) – Indicating whether to add probability table when run-
ning NJOY. If string, write the output tape to this file.
• evaluation (openmc.data.endf.Evaluation, optional) – If the ENDF file contains
multiple material evaluations, this argument indicates which evaluation should be used.
• smoothing (bool, optional) – If the smoothing option (ACER card 6) is on (True) or
off (False).
• **kwargs – Keyword arguments passed to openmc.data.njoy.run()
Raises
• subprocess.CalledProcessError – If the NJOY process returns with a non-zero status
• IOError – If output_dir does not point to a directory
openmc.data.njoy.make_ace_thermal
openmc.data.njoy.make_ace_thermal(filename, filename_thermal, temperatures=None, ace='ace',

xsdir=None, output_dir=None, error=0.001, iwt=2, evaluation=None,
evaluation_thermal=None, table_name=None, zaids=None,
nmix=None, **kwargs)
Generate thermal scattering ACE file from ENDF files
Parameters
• filename (str) – Path to ENDF neutron sublibrary file
• filename_thermal (str) – Path to ENDF thermal scattering sublibrary file

• temperatures (iterable of float, optional) – Temperatures in Kelvin to produce

data at. If omitted, data is produced at all temperatures given in the ENDF thermal scattering
sublibrary.
• ace (str, optional) – Path of ACE file to write
• xsdir (str, optional) – Path of xsdir file to write. Defaults to "xsdir" in the same
directory as ace
• output_dir (str, optional) – Directory to write ace and xsdir files. If not provided,
then write output files to current directory. If given, must be a path to a directory.
• iwt (int) – iwt parameter used in NJOR/ACER card 9
• evaluation (openmc.data.endf.Evaluation, optional) – If the ENDF neutron sub-
library file contains multiple material evaluations, this argument indicates which evaluation
to use.
• evaluation_thermal (openmc.data.endf.Evaluation, optional) – If the ENDF
thermal scattering sublibrary file contains multiple material evaluations, this argument indi-
cates which evaluation to use.
• table_name (str, optional) – Name to assign to ACE table
• zaids (list of int, optional) – ZAIDs that the thermal scattering data applies to
• nmix (int, optional) – Number of atom types in mixed moderator
• **kwargs – Keyword arguments passed to openmc.data.njoy.run()
Raises
6.8 openmc.lib – Python bindings to the C/C++ API
This module provides bindings to C/C++ functions defined by OpenMC shared library. When the openmc.lib package
is imported, the OpenMC shared library is automatically loaded. Calls to the OpenMC library can then be via functions
or objects in openmc.lib, for example:
openmc.lib.init()
openmc.lib.run()
openmc.lib.finalize()
6.8. openmc.lib – Python bindings to the C/C++ API 769

6.8.1 Functions
calculate_volumes Run stochastic volume calculation

export_properties Export physical properties.
finalize Finalize simulation and free memory
find_cell Find the cell at a given point
find_material Find the material at a given point
hard_reset Reset tallies, timers, and pseudo-random number gener-
ator state.
import_properties Import physical properties.
init Initialize OpenMC
iter_batches Iterator over batches.
keff Return the calculated k-eigenvalue and its standard de-
viation.
load_nuclide Load cross section data for a nuclide.
next_batch Run next batch.
num_realizations Number of realizations of global tallies.
plot_geometry Plot geometry
reset Reset tally results
run Run simulation
run_in_memory Provides context manager for calling OpenMC shared li-
brary functions.
sample_external_source Sample external source
simulation_init Initialize simulation
simulation_finalize Finalize simulation
source_bank Return source bank as NumPy array
statepoint_write Write a statepoint file.
openmc.lib.calculate_volumes
openmc.lib.calculate_volumes(output=True)
Run stochastic volume calculation
Changed in version 0.13.0: The output argument was added.
Parameters
output (bool, optional) – Whether or not to show output. Defaults to showing output
openmc.lib.export_properties(filename=None, output=True)
Export physical properties.
Parameters
• filename (str or None) – Filename to export properties to (defaults to “properties.h5”)
• output (bool, optional) – Whether or not to show output. Defaults to showing output
See also:
openmc.lib.import_properties

openmc.lib.finalize
openmc.lib.finalize()
Finalize simulation and free memory
openmc.lib.find_cell
openmc.lib.find_cell(xyz)
Find the cell at a given point
Parameters
xyz (iterable of float) – Cartesian coordinates of position
Returns
• openmc.lib.Cell – Cell containing the point
• int – If the cell at the given point is repeated in the geometry, this indicates which instance
it is, i.e., 0 would be the first instance.
openmc.lib.find_material
openmc.lib.find_material(xyz)
Find the material at a given point
Parameters
xyz (iterable of float) – Cartesian coordinates of position
Returns
Material containing the point, or None is no material is found
Return type
openmc.lib.Material or None
openmc.lib.hard_reset
openmc.lib.hard_reset()
Reset tallies, timers, and pseudo-random number generator state.
openmc.lib.import_properties
openmc.lib.import_properties(filename)
Import physical properties.
Parameters
filename (str) – Filename to import properties from
See also:

openmc.lib.init
openmc.lib.init(args=None, intracomm=None, output=True)

Initialize OpenMC
Parameters
• args (list of str, optional) – Command-line arguments
• intracomm (mpi4py.MPI.Intracomm or None, optional) – MPI intracommunicator
• output (bool, optional) – Whether or not to show output. Defaults to showing output
openmc.lib.iter_batches
openmc.lib.iter_batches()
Iterator over batches.
This function returns a generator-iterator that allows Python code to be run between batches in an OpenMC
simulation. It should be used in conjunction with openmc.lib.simulation_init() and openmc.lib.
simulation_finalize(). For example:
with openmc.lib.run_in_memory():
openmc.lib.simulation_init()
for _ in openmc.lib.iter_batches():
# Look at convergence of tallies, for example
...
openmc.lib.simulation_finalize()
See also:
openmc.lib.next_batch
openmc.lib.keff
openmc.lib.keff()
Return the calculated k-eigenvalue and its standard deviation.
Returns
Mean k-eigenvalue and standard deviation of the mean
Return type
tuple
openmc.lib.load_nuclide
openmc.lib.load_nuclide(name)
Load cross section data for a nuclide.
Parameters

openmc.lib.next_batch
openmc.lib.next_batch()
Run next batch.
Returns
Status after running a batch (0=normal, 1=reached maximum number of batches, 2=tally triggers
reached)
Return type
int
openmc.lib.num_realizations
openmc.lib.num_realizations()
Number of realizations of global tallies.
openmc.lib.plot_geometry
openmc.lib.plot_geometry(output=True)
Plot geometry
Parameters
openmc.lib.reset
openmc.lib.reset()
Reset tally results
openmc.lib.run
openmc.lib.run(output=True)
Run simulation
Parameters
openmc.lib.run_in_memory
openmc.lib.run_in_memory(**kwargs)
Provides context manager for calling OpenMC shared library functions.
This function is intended to be used in a ‘with’ statement and ensures that OpenMC is properly initial-
ized/finalized. At the completion of the ‘with’ block, all memory that was allocated during the block is freed.
For example:

with openmc.lib.run_in_memory():
for i in range(n_iters):
openmc.lib.reset()
do_stuff()
openmc.lib.run()
Parameters
**kwargs – All keyword arguments are passed to init().
openmc.lib.sample_external_source
openmc.lib.sample_external_source(n_samples=1, prn_seed=None)
Sample external source
Parameters
• n_samples (int) – Number of samples
• prn_seed (int) – Pseudorandom number generator (PRNG) seed; if None, one will be
generated randomly.
Returns
List of samples source particles
Return type
list of openmc.SourceParticle
openmc.lib.simulation_init
openmc.lib.simulation_init()
Initialize simulation
openmc.lib.simulation_finalize
openmc.lib.simulation_finalize()
Finalize simulation
openmc.lib.source_bank
openmc.lib.source_bank()
Return source bank as NumPy array
Returns
Source sites
Return type
numpy.ndarray

openmc.lib.statepoint_write
openmc.lib.statepoint_write(filename=None, write_source=True)
Write a statepoint file.
Parameters
• filename (str or None) – Path to the statepoint to write. If None is passed, a default
name that contains the current batch will be written.
• write_source (bool) – Whether or not to include the source bank in the statepoint.
6.8.2 Classes
Cell Cell stored internally.

EnergyFilter
MaterialFilter
Material Material stored internally.

MeshFilter
MeshSurfaceFilter
Nuclide Nuclide stored internally.

RegularMesh RegularMesh stored internally.
Tally Tally stored internally.
openmc.lib.Cell
class openmc.lib.Cell(uid=None, new=True, index=None)

Cell stored internally.
This class exposes a cell that is stored internally in the OpenMC library. To obtain a view of a cell with a given
ID, use the openmc.lib.cells mapping.
Parameters
• uid (int or None) – Unique ID of the cell
• new (bool) – When index is None, this argument controls whether a new object is created
or a view to an existing object is returned.
• index (int) – Index in the cells array.
Variables
• id (int) – ID of the cell
• fill (openmc.lib.Material or list of openmc.lib.Material) – Indicates what
the region of space is filled with
• name (str) – Name of the cell
• num_instances (int) – Number of unique cell instances
• bounding_box (2-tuple of numpy.ndarray) – Lower-left and upper-right coordinates
of bounding box

• translation (Iterable of float) – 3-D coordinates of the translation vector

• rotation (Iterable of float) – The rotation matrix or angles of the universe filling the
cell. This can either be a fully specified 3 x 3 rotation matrix or an Iterable of length 3 with
the angles in degrees about the x, y, and z axes, respectively.
get_temperature(instance=None)
Get the temperature of a cell
Parameters
instance (int or None) – Which instance of the cell
set_temperature(T, instance=None, set_contained=False)
Set the temperature of a cell
Parameters
• T (float) – Temperature in K
• instance (int or None) – Which instance of the cell
• set_contained (bool) – If cell is not filled by a material, whether to set the temperature
of all filled cells
openmc.lib.EnergyFilter
class openmc.lib.EnergyFilter(obj=None, uid=None, new=True, index=None)
openmc.lib.MaterialFilter
class openmc.lib.MaterialFilter(obj=None, uid=None, new=True, index=None)
openmc.lib.Material
class openmc.lib.Material(uid=None, new=True, index=None)

Material stored internally.
This class exposes a material that is stored internally in the OpenMC library. To obtain a view of a material with
a given ID, use the openmc.lib.materials mapping.
Parameters
• uid (int or None) – Unique ID of the material
or a view to an existing object is returned.
• index (int or None) – Index in the materials array.
Variables
• id (int) – ID of the material
• nuclides (list of str) – List of nuclides in the material
• densities (numpy.ndarray) – Array of densities in atom/b-cm
• name (str) – Name of the material
• temperature (float) – Temperature of the material in [K]

• volume (float) – Volume of the material in [cm^3]

add_nuclide(name, density)
Add a nuclide to a material.
Parameters
• name (str) – Name of nuclide, e.g. ‘U235’
• density (float) – Density in atom/b-cm
get_density(units='atom/b-cm')
Get density of a material.
Parameters
units ({'atom/b-cm', 'g/cm3'}) – Units for density
Returns
Density in requested units
Return type
float
set_densities(nuclides, densities)
Set the densities of a list of nuclides in a material
Parameters
• nuclides (iterable of str) – Nuclide names
• densities (iterable of float) – Corresponding densities in atom/b-cm
set_density(density, units='atom/b-cm')
Set density of a material.
Parameters
• density (float) – Density
• units ({'atom/b-cm', 'g/cm3'}) – Units for density
openmc.lib.MeshFilter
class openmc.lib.MeshFilter(obj=None, uid=None, new=True, index=None)
openmc.lib.MeshSurfaceFilter
class openmc.lib.MeshSurfaceFilter(obj=None, uid=None, new=True, index=None)

openmc.lib.Nuclide
class openmc.lib.Nuclide(*args)
Nuclide stored internally.
This class exposes a nuclide that is stored internally in the OpenMC solver. To obtain a view of a nuclide with a
given name, use the openmc.lib.nuclides mapping.
Parameters
index (int) – Index in the nuclides array.
Variables
collapse_rate(MT, temperature, energy, flux)
Calculate reaction rate based on group-wise flux distribution
Parameters
• MT (int) – ENDF MT value of the desired reaction
• temperature (float) – Temperature in [K] at which to evaluate cross sections
• energy (iterable of float) – Energy group boundaries in [eV]
• flux (iterable of float) – Flux in each energt group (not normalized per eV)
Returns
Reaction rate
Return type
float
openmc.lib.RegularMesh
class openmc.lib.RegularMesh(uid=None, new=True, index=None)

RegularMesh stored internally.
This class exposes a mesh that is stored internally in the OpenMC library. To obtain a view of a mesh with a
given ID, use the openmc.lib.meshes mapping.
Parameters
index (int) – Index in the meshes array.
Variables
• id (int) – ID of the mesh
• dimension (iterable of int) – The number of mesh cells in each direction.
• lower_left (numpy.ndarray) – The lower-left corner of the structured mesh. If only two
coordinate are given, it is assumed that the mesh is an x-y mesh.
• upper_right (numpy.ndarray) – The upper-right corner of the structrued mesh. If only
two coordinate are given, it is assumed that the mesh is an x-y mesh.
• width (numpy.ndarray) – The width of mesh cells in each direction.

openmc.lib.Tally
class openmc.lib.Tally(uid=None, new=True, index=None)

Tally stored internally.
This class exposes a tally that is stored internally in the OpenMC library. To obtain a view of a tally with a given
ID, use the openmc.lib.tallies mapping.
Parameters
• uid (int or None) – Unique ID of the tally
or a view of an existing object is returned.
• index (int or None) – Index in the tallies array.
Variables
• id (int) – ID of the tally
• estimator (str) – Estimator type of tally (analog, tracklength, collision)
• filters (list) – List of tally filters
• mean (numpy.ndarray) – An array containing the sample mean for each bin
• nuclides (list of str) – List of nuclides to score results for
• num_realizations (int) – Number of realizations
• results (numpy.ndarray) – Array of tally results
• std_dev (numpy.ndarray) – An array containing the sample standard deviation for each
bin
• type (str) – Type of tally (volume, mesh_surface, surface)
ci_width(alpha=0.05)
Confidence interval half-width based on a Student t distribution
Parameters
alpha (float) – Significance level (one minus the confidence level!)
Returns
Half-width of a two-sided (1 - 𝑎𝑙𝑝ℎ𝑎) confidence interval
Return type
float
reset()
Reset results and num_realizations of tally

6.9 openmc.openmoc_compatible – OpenMOC Compatibility
6.9.1 Core Classes
openmc.openmoc_compatible. Return an OpenMOC material corresponding to an

get_openmoc_material OpenMC material.
openmc.openmoc_compatible. Return an OpenMC material corresponding to an Open-
get_openmc_material MOC material.
openmc.openmoc_compatible. Return an OpenMOC surface corresponding to an
get_openmoc_surface OpenMC surface.
openmc.openmoc_compatible. Return an OpenMC surface corresponding to an Open-
get_openmc_surface MOC surface.
openmc.openmoc_compatible.get_openmoc_cell Return an OpenMOC cell corresponding to an OpenMC
cell.
openmc.openmoc_compatible.get_openmc_cell Return an OpenMC cell corresponding to an OpenMOC
cell.
openmc.openmoc_compatible. Return an OpenMOC universe corresponding to an
get_openmoc_universe OpenMC universe.
openmc.openmoc_compatible. Return an OpenMC universe corresponding to an Open-
get_openmc_universe MOC universe.
openmc.openmoc_compatible. Return an OpenMOC lattice corresponding to an Open-
get_openmoc_lattice MOC lattice.
openmc.openmoc_compatible. Return an OpenMC lattice corresponding to an Open-
get_openmc_lattice MOC lattice.
openmc.openmoc_compatible. Return an OpenMC geometry corresponding to an
get_openmoc_geometry OpenMOC geometry.
openmc.openmoc_compatible. Return an OpenMC geometry corresponding to an
get_openmc_geometry OpenMOC geometry.
openmc.openmoc_compatible.get_openmoc_material
openmc.openmoc_compatible.get_openmoc_material(openmc_material)
Return an OpenMOC material corresponding to an OpenMC material.
Parameters
openmc_material (openmc.Material) – OpenMC material
Returns
openmoc_material – Equivalent OpenMOC material
Return type
openmoc.Material

openmc.openmoc_compatible.get_openmc_material
openmc.openmoc_compatible.get_openmc_material(openmoc_material)
Return an OpenMC material corresponding to an OpenMOC material.
Parameters
openmoc_material (openmoc.Material) – OpenMOC material
Returns
openmc_material – Equivalent OpenMC material
Return type
openmc.Material
openmc.openmoc_compatible.get_openmoc_surface
openmc.openmoc_compatible.get_openmoc_surface(openmc_surface)
Return an OpenMOC surface corresponding to an OpenMC surface.
Parameters
openmc_surface (openmc.Surface) – OpenMC surface
Returns
openmoc_surface – Equivalent OpenMOC surface
Return type
openmoc.Surface
openmc.openmoc_compatible.get_openmc_surface
openmc.openmoc_compatible.get_openmc_surface(openmoc_surface)
Return an OpenMC surface corresponding to an OpenMOC surface.
Parameters
openmoc_surface (openmoc.Surface) – OpenMOC surface
Returns
openmc_surface – Equivalent OpenMC surface
Return type
openmc.Surface
openmc.openmoc_compatible.get_openmoc_cell
openmc.openmoc_compatible.get_openmoc_cell(openmc_cell)
Return an OpenMOC cell corresponding to an OpenMC cell.
Parameters
openmc_cell (openmc.Cell) – OpenMC cell
Returns
openmoc_cell – Equivalent OpenMOC cell
Return type
openmoc.Cell
6.9. openmc.openmoc_compatible – OpenMOC Compatibility 781

openmc.openmoc_compatible.get_openmc_cell
openmc.openmoc_compatible.get_openmc_cell(openmoc_cell)
Return an OpenMC cell corresponding to an OpenMOC cell.
Parameters
openmoc_cell (openmoc.Cell) – OpenMOC cell
Returns
openmc_cell – Equivalent OpenMC cell
Return type
openmc.Cell
openmc.openmoc_compatible.get_openmoc_universe
openmc.openmoc_compatible.get_openmoc_universe(openmc_universe)
Return an OpenMOC universe corresponding to an OpenMC universe.
Parameters
openmc_universe (openmc.Universe) – OpenMC universe
Returns
openmoc_universe – Equivalent OpenMOC universe
Return type
openmoc.Universe
openmc.openmoc_compatible.get_openmc_universe
openmc.openmoc_compatible.get_openmc_universe(openmoc_universe)
Return an OpenMC universe corresponding to an OpenMOC universe.
Parameters
openmoc_universe (openmoc.Universe) – OpenMOC universe
Returns
openmc_universe – Equivalent OpenMC universe
Return type
openmc.Universe
openmc.openmoc_compatible.get_openmoc_lattice
openmc.openmoc_compatible.get_openmoc_lattice(openmc_lattice)
Return an OpenMOC lattice corresponding to an OpenMOC lattice.
Parameters
openmc_lattice (openmc.RectLattice) – OpenMC lattice
Returns
openmoc_lattice – Equivalent OpenMOC lattice
Return type
openmoc.Lattice

openmc.openmoc_compatible.get_openmc_lattice
openmc.openmoc_compatible.get_openmc_lattice(openmoc_lattice)
Return an OpenMC lattice corresponding to an OpenMOC lattice.
Parameters
openmoc_lattice (openmoc.Lattice) – OpenMOC lattice
Returns
openmc_lattice – Equivalent OpenMC lattice
Return type
openmc.RectLattice
openmc.openmoc_compatible.get_openmoc_geometry
openmc.openmoc_compatible.get_openmoc_geometry(openmc_geometry)
Return an OpenMC geometry corresponding to an OpenMOC geometry.
Parameters
openmc_geometry (openmc.Geometry) – OpenMC geometry
Returns
openmoc_geometry – Equivalent OpenMOC geometry
Return type
openmoc.Geometry
openmc.openmoc_compatible.get_openmc_geometry
openmc.openmoc_compatible.get_openmc_geometry(openmoc_geometry)
Return an OpenMC geometry corresponding to an OpenMOC geometry.
Parameters
openmoc_geometry (openmoc.Geometry) – OpenMOC geometry
Returns
openmc_geometry – Equivalent OpenMC geometry
Return type
openmc.Geometry
6.9. openmc.openmoc_compatible – OpenMOC Compatibility 783


CHAPTER
SEVEN
C/C++ API
The libopenmc shared library that is built when installing OpenMC exports a number of C interoperable functions
and global variables that can be used for in-memory coupling. While it is possible to directly use the C/C++ API as
documented here for coupling, most advanced users will find it easier to work with the Python bindings in the openmc.
lib module.
Warning: The C/C++ API is still experimental and may undergo substantial changes in future releases.
7.1 Type Definitions
type Bank
Attributes of a source particle.
double wgt
Weight of the particle
double xyz[3]
Position of the particle (units of cm)
double uvw[3]
Unit vector indicating direction of the particle
double E
Energy of the particle in eV
int delayed_group
If the particle is a delayed neutron, indicates which delayed precursor group it was born from. If not a
delayed neutron, this member is zero.
7.2 Functions
int openmc_calculate_volumes()
Run a stochastic volume calculation
Returns
Return status (negative if an error occurred)
Return type
int
785
int openmc_cell_get_fill(int32_t index, int *type, int32_t **indices, int32_t *n)

Get the fill for a cell
Parameters
• index (int32_t) – Index in the cells array
• type (int*) – Type of the fill
• indices (int32_t**) – Array of material indices for cell
• n (int32_t*) – Length of indices array
Returns
Return type
int
int openmc_cell_get_id(int32_t index, int32_t *id)
Get the ID of a cell
Parameters
• id (int32_t*) – ID of the cell
Returns
Return type
int
int openmc_cell_get_temperature(int32_t index, const int32_t *instance, double *T)
Get the temperature of a cell
Parameters
• instance (int32_t*) – Which instance of the cell. If a null pointer is passed, the temper-
ature of the first instance is returned.
• T (double*) – temperature of the cell
Returns
Return type
int
int openmc_cell_set_fill(int32_t index, int type, int32_t n, const int32_t *indices)
Set the fill for a cell
Parameters
• type (int) – Type of the fill
• n (int32_t) – Length of indices array
• indices (const int32_t*) – Array of material indices for cell
Returns
786 Chapter 7. C/C++ API

Return type
int
int openmc_cell_set_id(int32_t index, int32_t id)
Set the ID of a cell
Parameters
• id (int32_t) – ID of the cell
Returns
Return type
int
int openmc_cell_set_temperature(index index, double T, const int32_t *instance, bool set_contained)
Set the temperature of a cell.
Parameters
• T (double) – Temperature in Kelvin
• instance (const int32_t*) – Which instance of the cell. To set the temperature for all
instances, pass a null pointer.
• set_contained – If the cell is not filled by a material, whether to set the temperatures of
all filled cells
Returns
Return type
int
int openmc_energy_filter_get_bins(int32_t index, double **energies, int32_t *n)
Return the bounding energies for an energy filter
Parameters
• index (int32_t) – Index in the filters array
• energies (double**) – Bounding energies of the bins for the energy filter
• n (int32_t*) – Number of energies specified
Returns
Return type
int
int openmc_energy_filter_set_bins(int32_t index, int32_t n, const double *energies)
Set the bounding energies for an energy filter
Parameters
• n (int32_t) – Number of energies specified
• energies (const double*) – Bounding energies of the bins for the energy filter
7.2. Functions 787

Returns
Return type
int
int openmc_extend_cells(int32_t n, int32_t *index_start, int32_t *index_end)
Extend the cells array by n elements
Parameters
• n (int32_t) – Number of cells to create
• index_start (int32_t*) – Index of first new cell
• index_end (int32_t*) – Index of last new cell
Returns
Return type
int
int openmc_extend_filters(int32_t n, int32_t *index_start, int32_t *index_end)
Extend the filters array by n elements
Parameters
• n (int32_t) – Number of filters to create
• index_start (int32_t*) – Index of first new filter
• index_end (int32_t*) – Index of last new filter
Returns
Return type
int
int openmc_extend_materials(int32_t n, int32_t *index_start, int32_t *index_end)
Extend the materials array by n elements
Parameters
• n (int32_t) – Number of materials to create
• index_start (int32_t*) – Index of first new material
• index_end (int32_t*) – Index of last new material
Returns
Return type
int
int openmc_extend_sources(int32_t n, int32_t *index_start, int32_t *index_end)
Extend the external sources array by n elements
Parameters
• n (int32_t) – Number of sources to create
• index_start (int32_t*) – Index of first new source

• index_end (int32_t*) – Index of last new source

Returns
Return type
int
int openmc_extend_tallies(int32_t n, int32_t *index_start, int32_t *index_end)
Extend the tallies array by n elements
Parameters
• n (int32_t) – Number of tallies to create
• index_start (int32_t*) – Index of first new tally
• index_end (int32_t*) – Index of last new tally
Returns
Return type
int
int openmc_filter_get_id(int32_t index, int32_t *id)
Get the ID of a filter
Parameters
• id (int32_t*) – ID of the filter
Returns
Return type
int
int openmc_filter_set_id(int32_t index, int32_t id)
Set the ID of a filter
Parameters
• id (int32_t) – ID of the filter
Returns
Return type
int
int openmc_finalize()
Finalize a simulation
Returns
Return status (negative if an error occurs)
Return type
int
7.2. Functions 789

int openmc_find(double *xyz, int rtype, int32_t *id, int32_t *instance)

Determine the ID of the cell/material containing a given point
Parameters
• xyz (double[3]) – Cartesian coordinates
• rtype (int) – Which ID to return (1=cell, 2=material)
• id (int32_t*) – ID of the cell/material found. If a material is requested and the point is in
a void, the ID is 0. If an error occurs, the ID is -1.
• instance (int32_t*) – If a cell is repeated in the geometry, the instance of the cell that
was found and zero otherwise.
Returns
Return type
int
int openmc_get_cell_index(int32_t id, int32_t *index)
Get the index in the cells array for a cell with a given ID
Parameters
• id (int32_t) – ID of the cell
• index (int32_t*) – Index in the cells array
Returns
Return type
int
int openmc_get_filter_index(int32_t id, int32_t *index)
Get the index in the filters array for a filter with a given ID
Parameters
• id (int32_t) – ID of the filter
• index (int32_t*) – Index in the filters array
Returns
Return type
int
void openmc_get_filter_next_id(int32_t *id)
Get an integer ID that has not been used by any filters.
Parameters
• id (int32_t*) – Unused integer ID
int openmc_get_keff(double k_combined[2])
Parameters
• k_combined (double[2]) – Combined estimate of k-effective
Returns

Return type
int
int openmc_get_material_index(int32_t id, int32_t *index)
Get the index in the materials array for a material with a given ID
Parameters
• id (int32_t) – ID of the material
• index (int32_t*) – Index in the materials array
Returns
Return type
int
int openmc_get_n_batches(int *n_batches, bool get_max_batches)
Get number of batches to simulate
Parameters
• n_batches (int*) – Number of batches to simulate
• get_max_batches (bool) – Whether to return n_batches or n_max_batches (only relevant
when triggers are used)
Returns
Return type
int
int openmc_get_nuclide_index(const char name[], int *index)
Get the index in the nuclides array for a nuclide with a given name
Parameters
• name (const char[]) – Name of the nuclide
• index (int*) – Index in the nuclides array
Returns
Return type
int
int openmc_get_tally_index(int32_t id, int32_t *index)
Get the index in the tallies array for a tally with a given ID
Parameters
• id (int32_t) – ID of the tally
• index (int32_t*) – Index in the tallies array
Returns
Return type
int
7.2. Functions 791

int openmc_hard_reset()
Reset tallies, timers, and pseudo-random number generator state
Returns
Return type
int
int openmc_init(int argc, char **argv, const void *intracomm)
Initialize OpenMC
Parameters
• argc (int) – Number of command-line arguments (including command)
• argv (char**) – Command-line arguments
• intracomm (const void*) – MPI intracommunicator. If MPI is not being used, a null
pointer should be passed.
Returns
Return type
int
int openmc_load_nuclide(const char *name, const double *temps, int n)
Load data for a nuclide from the HDF5 data library.
Parameters
• name (const char*) – Name of the nuclide.
• temps (const double*) – Temperatures in [K] to load data at
• n (int) – Number of temperatures
Returns
Return type
int
int openmc_material_add_nuclide(int32_t index, const char name[], double density)
Add a nuclide to an existing material. If the nuclide already exists, the density is overwritten.
Parameters
• index (int32_t) – Index in the materials array
• name (const char[]) – Name of the nuclide
• density (double) – Density in atom/b-cm
Returns
Return type
int
int openmc_material_get_densities(int32_t index, int **nuclides, double **densities, int *n)
Get density for each nuclide in a material.
Parameters


• nuclides (int**) – Pointer to array of nuclide indices
• densities (double**) – Pointer to the array of densities
• n (int*) – Length of the array
Returns
Return type
int
int openmc_material_get_density(int32_t index, double *density)
Get density of a material.
Parameters
• density (double*) – Pointer to a density
Returns
Return type
int
int openmc_material_get_id(int32_t index, int32_t *id)
Get the ID of a material
Parameters
• id (int32_t*) – ID of the material
Returns
Return type
int
int openmc_material_set_density(int32_t index, double density, const char *units)
Set the density of a material.
Parameters
• density (double) – Density of the material
• units (const char*) – Units for density
Returns
Return type
int
int openmc_material_set_densities(int32_t index, int n, const char **name, const double *density)
Parameters
7.2. Functions 793

• n (int) – Length of name/density

• name (const char**) – Array of nuclide names
• density (const double*) – Array of densities
Returns
Return type
int
int openmc_material_set_id(int32_t index, int32_t id)
Set the ID of a material
Parameters
• id (int32_t) – ID of the material
Returns
Return type
int
int openmc_material_filter_get_bins(int32_t index, int32_t **bins, int32_t *n)
Get the bins for a material filter
Parameters
• bins (int32_t**) – Index in the materials array for each bin
• n (int32_t*) – Number of bins
Returns
Return type
int
int openmc_material_filter_set_bins(int32_t index, int32_t n, const int32_t *bins)
Set the bins for a material filter
Parameters
• n (int32_t) – Number of bins
• bins (const int32_t*) – Index in the materials array for each bin
Returns
Return type
int
int openmc_mesh_filter_set_mesh(int32_t index, int32_t index_mesh)
Set the mesh for a mesh filter
Parameters


• index_mesh (int32_t) – Index in the meshes array
Returns
Return type
int
int openmc_next_batch()
Simulate next batch of particles. Must be called after openmc_simulation_init().
Returns
Integer indicating whether simulation has finished (negative) or not finished (zero).
Return type
int
int openmc_nuclide_name(int index, char **name)
Get name of a nuclide
Parameters
• index (int) – Index in the nuclides array
• name (char**) – Name of the nuclide
Returns
Return type
int
int openmc_plot_geometry()
Run plotting mode.
Returns
Return type
int
int openmc_reset()
Resets all tally scores
Returns
Return type
int
int openmc_remove_tally(int32_t index);
Given an index of a tally, remove it from the tallies array :param int index: Index in tallies array :return: Return
status (negative if an error occurs) :rtype: int
int openmc_run()
Run a simulation
Returns
Return type
int
7.2. Functions 795

int openmc_set_n_batches(int32_t n_batches, bool set_max_batches, bool add_statepoint_batch)

Set number of batches and number of max batches
Parameters
• n_batches (int32_t) – Number of batches to simulate
• set_max_batches (bool) – Whether to set settings::n_max_batches or settings::n_batches
(only relevant when triggers are used)
• add_statepoint_batch (bool) – Whether to add n_batches to settings::statepoint_batch
Returns
Return type
int
int openmc_simulation_finalize()
Finalize a simulation.
Returns
Return type
int
int openmc_simulation_init()
Initialize a simulation. Must be called after openmc_init().
Returns
Return type
int
int openmc_source_bank(struct Bank **ptr, int64_t *n)
Return a pointer to the source bank array.
Parameters
• ptr (struct Bank**) – Pointer to the source bank array
• n (int64_t*) – Length of the source bank array
Returns
Return type
int
int openmc_source_set_strength(int32_t index, double strength)
Set the strength of an external source
Parameters
• index (int32_t) – Index in the external source array
• strength (double) – Source strength
Returns
Return type
int

int openmc_statepoint_write(const char filename[], const bool *write_source)

Write a statepoint file
Parameters
• filename (const char[]) – Name of file to create. If a null pointer is passed, a filename
is assigned automatically.
• write_source (const bool*) – Whether to include the source bank
Returns
Return type
int
int openmc_tally_get_id(int32_t index, int32_t *id)
Get the ID of a tally
Parameters
• index (int32_t) – Index in the tallies array
• id (int32_t*) – ID of the tally
Returns
Return type
int
int openmc_tally_get_filters(int32_t index, int32_t **indices, int *n)
Get filters specified in a tally
Parameters
• indices (int32_t**) – Array of filter indices
• n (int*) – Number of filters
Returns
Return type
int
int openmc_tally_get_n_realizations(int32_t index, int32_t *n)
Parameters
• n (int32_t*) – Number of realizations
Returns
Return type
int
int openmc_tally_get_nuclides(int32_t index, int **nuclides, int *n)
Get nuclides specified in a tally
Parameters
7.2. Functions 797


• nuclides (int**) – Array of nuclide indices
• n (int*) – Number of nuclides
Returns
Return type
int
int openmc_tally_get_scores(int32_t index, int **scores, int *n)
Get scores specified for a tally
Parameters
• scores (int**) – Array of scores
• n (int*) – Number of scores
Returns
Return type
int
int openmc_tally_results(int32_t index, double **ptr, int shape_[3])
Get a pointer to tally results array.
Parameters
• ptr (double**) – Pointer to the results array
• shape (int[3]) – Shape of the results array
Returns
Return type
int
int openmc_tally_set_filters(int32_t index, int n, const int32_t *indices)
Set filters for a tally
Parameters
• n (int) – Number of filters
• indices (const int32_t*) – Array of filter indices
Returns
Return type
int

int openmc_tally_set_id(int32_t index, int32_t id)

Set the ID of a tally
Parameters
• id (int32_t) – ID of the tally
Returns
Return type
int
int openmc_tally_set_nuclides(int32_t index, int n, const char **nuclides)
Set the nuclides for a tally
Parameters
• n (int) – Number of nuclides
• nuclides (const char**) – Array of nuclide names
Returns
Return type
int
int openmc_tally_set_scores(int32_t index, int n, const int *scores)
Set scores for a tally
Parameters
• n (int) – Number of scores
• scores (const int*) – Array of scores
Returns
Return type
int
7.2. Functions 799


CHAPTER
EIGHT
FILE FORMAT SPECIFICATIONS
8.1 Input Files
8.1.1 Geometry Specification – geometry.xml
<surface> Element
Each <surface> element can have the following attributes or sub-elements:

id
A unique integer that can be used to identify the surface.
Default: None
name
An optional string name to identify the surface in summary output files.
Default: “”
type
The type of the surfaces. This can be “x-plane”, “y-plane”, “z-plane”, “plane”, “x-
cylinder”, “y-cylinder”, “z-cylinder”, “sphere”, “x-cone”, “y-cone”, “z-cone”, “quadric”,
“x-torus”, “y-torus”, or “z-torus”.
Default: None
coeffs
The corresponding coefficients for the given type of surface. See below for a list a what
coefficients to specify for a given surface
Default: None
boundary
The boundary condition for the surface. This can be “transmission”, “vacuum”,
“reflective”, or “periodic”. Periodic boundary conditions can only be applied to
x-, y-, and z-planes. Only axis-aligned periodicity is supported, i.e., x-planes can
only be paired with x-planes. Specify which planes are periodic and the code will
automatically identify which planes are paired together.
Default: “transmission”
periodic_surface_id
If a periodic boundary condition is applied, this attribute identifies the id of the corre-
sponding periodic surface.
The following quadratic surfaces can be modeled:
801
x-plane
A plane perpendicular to the x axis, i.e. a surface of the form 𝑥 − 𝑥0 = 0. The coefficients
specified are “𝑥0 ”.
y-plane
A plane perpendicular to the y axis, i.e. a surface of the form 𝑦 − 𝑦0 = 0. The coefficients
specified are “𝑦0 ”.
z-plane
A plane perpendicular to the z axis, i.e. a surface of the form 𝑧 − 𝑧0 = 0. The coefficients
specified are “𝑧0 ”.
plane
An arbitrary plane of the form 𝐴𝑥 + 𝐵𝑦 + 𝐶𝑧 = 𝐷. The coefficients specified are
“𝐴 𝐵 𝐶 𝐷”.
x-cylinder
An infinite cylinder whose length is parallel to the x-axis. This is a quadratic surface of
the form (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 . The coefficients specified are “𝑦0 𝑧0 𝑅”.
y-cylinder
An infinite cylinder whose length is parallel to the y-axis. This is a quadratic surface of
the form (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 . The coefficients specified are “𝑥0 𝑧0 𝑅”.
z-cylinder
An infinite cylinder whose length is parallel to the z-axis. This is a quadratic surface of
the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑅2 . The coefficients specified are “𝑥0 𝑦0 𝑅”.
sphere
A sphere of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 . The coefficients specified
are “𝑥0 𝑦0 𝑧0 𝑅”.
x-cone
A cone parallel to the x-axis of the form (𝑦 − 𝑦0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (𝑥 − 𝑥0 )2 . The
coefficients specified are “𝑥0 𝑦0 𝑧0 𝑅2 ”.
y-cone
A cone parallel to the y-axis of the form (𝑥 − 𝑥0 )2 + (𝑧 − 𝑧0 )2 = 𝑅2 (𝑦 − 𝑦0 )2 . The
z-cone
A cone parallel to the x-axis of the form (𝑥 − 𝑥0 )2 + (𝑦 − 𝑦0 )2 = 𝑅2 (𝑧 − 𝑧0 )2 . The
quadric
A general quadric surface of the form 𝐴𝑥2 + 𝐵𝑦 2 + 𝐶𝑧 2 + 𝐷𝑥𝑦 + 𝐸𝑦𝑧 + 𝐹 𝑥𝑧 + 𝐺𝑥 +
𝐻𝑦 + 𝐽𝑧 + 𝐾 = 0 The coefficients specified are “𝐴 𝐵 𝐶 𝐷 𝐸 𝐹 𝐺 𝐻 𝐽 𝐾”.
<cell> Element
Each <cell> element can have the following attributes or sub-elements:

id
A unique integer that can be used to identify the cell.
Default: None
name
An optional string name to identify the cell in summary output files.
Default: “”
802 Chapter 8. File Format Specifications

universe
The id of the universe that this cell is contained in.
Default: 0
fill
The id of the universe that fills this cell.
Note: If a fill is specified, no material should be given.
Default: None
material
The id of the material that this cell contains. If the cell should contain no material, this
can also be set to “void”. A list of materials can be specified for the “distributed material”
feature. This will give each unique instance of the cell its own material.
Note: If a material is specified, no fill should be given.
Default: None
region
A Boolean expression of half-spaces that defines the spatial region which the cell occupies.
Each half-space is identified by the unique ID of the surface prefixed by - or + to indicate
that it is the negative or positive half-space, respectively. The + sign for a positive half-
space can be omitted. Valid Boolean operators are parentheses, union |, complement ~,
and intersection. Intersection is implicit and indicated by the presence of whitespace. The
order of operator precedence is parentheses, complement, intersection, and then union.
As an example, the following code gives a cell that is the union of the negative half-space
of surface 3 and the complement of the intersection of the positive half-space of surface 5
and the negative half-space of surface 2:
<cell id="1" material="1" region="-3 | ~(5 -2)" />
Note: The region attribute/element can be omitted to make a cell fill its entire universe.
Default: A region filling all space.

temperature
The temperature of the cell in Kelvin. The temperature may be used in windowed multipole
Doppler broadening or interpolation of pointwise cross sections versus temperature. A list
of temperatures can be specified for the “distributed temperature” feature. This will give
each unique instance of the cell its own temperature.
Default: If a material default temperature is supplied, it is used. In the absence of a material
default temperature, the global default temperature is used.
rotation
If the cell is filled with a universe, this element specifies the angles in degrees about the
x, y, and z axes that the filled universe should be rotated. Should be given as three real
numbers. For example, if you wanted to rotate the filled universe by 90 degrees about the
z-axis, the cell element would look something like:
8.1. Input Files 803

<cell fill="..." rotation="0 0 90" />
The rotation applied is an intrinsic rotation whose Tait-Bryan angles are given as those
specified about the x, y, and z axes respectively. That is to say, if the angles are (𝜑, 𝜃, 𝜓),
then the rotation matrix applied is 𝑅𝑧 (𝜓)𝑅𝑦 (𝜃)𝑅𝑥 (𝜑) or
⎡ ⎤
cos 𝜃 cos 𝜓 − cos 𝜑 sin 𝜓 + sin 𝜑 sin 𝜃 cos 𝜓 sin 𝜑 sin 𝜓 + cos 𝜑 sin 𝜃 cos 𝜓
⎣ cos 𝜃 sin 𝜓 cos 𝜑 cos 𝜓 + sin 𝜑 sin 𝜃 sin 𝜓 − sin 𝜑 cos 𝜓 + cos 𝜑 sin 𝜃 sin 𝜓 ⎦
− sin 𝜃 sin 𝜑 cos 𝜃 cos 𝜑 cos 𝜃
Default: None
translation
If the cell is filled with a universe, this element specifies a vector that is used to translate
(shift) the universe. Should be given as three real numbers.
Note: Any translation operation is applied after a rotation, if also specified.
Default: None
<lattice> Element
The <lattice> can be used to represent repeating structures (e.g. fuel pins in an assembly) or other geometry which
fits onto a rectilinear grid. Each cell within the lattice is filled with a specified universe. A <lattice> accepts the
following attributes or sub-elements:
id
A unique integer that can be used to identify the lattice.
name
An optional string name to identify the lattice in summary output files.
Default: “”
dimension
Two or three integers representing the number of lattice cells in the x- and y- (and z-)
directions, respectively.
Default: None
lower_left
The coordinates of the lower-left corner of the lattice. If the lattice is two-dimensional,
only the x- and y-coordinates are specified.
Default: None
pitch
If the lattice is 3D, then three real numbers that express the distance between the centers
of lattice cells in the x-, y-, and z- directions. If the lattice is 2D, then omit the third value.
Default: None
outer
The unique integer identifier of a universe that will be used to fill all space outside of the
lattice. The universe will be tiled repeatedly as if it were placed in a lattice of infinite size.
This element is optional.
Default: An error will be raised if a particle leaves a lattice with no outer universe.

universes
A list of the universe numbers that fill each cell of the lattice.
Default: None
Here is an example of a properly defined 2d rectangular lattice:
<lattice id="10" dimension="3 3" outer="1">

<lower_left> -1.5 -1.5 </lower_left>
<pitch> 1.0 1.0 </pitch>
<universes>
2 2 2
2 1 2
2 2 2
</universes>
</lattice>
<hex_lattice> Element
The <hex_lattice> can be used to represent repeating structures (e.g. fuel pins in an assembly) or other geometry
which naturally fits onto a hexagonal grid or hexagonal prism grid. Each cell within the lattice is filled with a specified
universe. This lattice uses the “flat-topped hexagon” scheme where two of the six edges are perpendicular to the y-axis.
A <hex_lattice> accepts the following attributes or sub-elements:
id
A unique integer that can be used to identify the lattice.
name
An optional string name to identify the hex_lattice in summary output files.
Default: “”
n_rings
An integer representing the number of radial ring positions in the xy-plane. Note that this
number includes the degenerate center ring which only has one element.
Default: None
n_axial
An integer representing the number of positions along the z-axis. This element is optional.
Default: None
orientation
The orientation of the hexagonal lattice. The string “x” indicates that two sides of the
lattice are parallel to the x-axis, whereas the string “y” indicates that two sides are parallel
to the y-axis.
Default: “y”
center
The coordinates of the center of the lattice. If the lattice does not have axial sections then
only the x- and y-coordinates are specified.
Default: None
pitch
If the lattice is 3D, then two real numbers that express the distance between the centers of
lattice cells in the xy-plane and along the z-axis, respectively. If the lattice is 2D, then omit
the second value.

Default: None
outer
The unique integer identifier of a universe that will be used to fill all space outside of the
lattice. The universe will be tiled repeatedly as if it were placed in a lattice of infinite size.
This element is optional.
Default: An error will be raised if a particle leaves a lattice with no outer universe.
universes
A list of the universe numbers that fill each cell of the lattice.
Default: None
Here is an example of a properly defined 2d hexagonal lattice:
<hex_lattice id="10" n_rings="3" outer="1">

<center> 0.0 0.0 </center>
<pitch> 1.0 </pitch>
<universes>
202
202 202
202 202 202
202 202
202 101 202
202 202
202 202 202
202 202
202
</universes>
</hex_lattice>
<dagmc_universe> Element
Each <dagmc_universe> element can have the following attributes or sub-elements:

id
A unique integer used to identify the universe.
Default: None
name
An optional string name to identify the surface in summary output files.
Default: None
auto_geom_ids
Boolean value indicating whether the existing geometry IDs will be used or appended to
the existing ID space of natively defined OpenMC geometry entities.
Default: false
auto_mat_ids
Boolean value indicating whether the existing material IDs will be used or appended to the
existing ID space of natively defined OpenMC materials.
Default: false
filename
A required string indicating the file to be loaded representing the DAGMC universe.

Default: None
Note: A geometry.xml file containing only a DAGMC model for a file named dagmc.h5m (no CSG) looks
as follows
<?xml version='1.0' encoding='utf-8'?>

<geometry>
<dagmc_universe filename="dagmc.h5m" id="1" />
</geometry>
8.1.2 Materials Specification – materials.xml
<cross_sections> Element
The <cross_sections> element has no attributes and simply indicates the path to an XML cross section listing file
(usually named cross_sections.xml). If this element is absent from the settings.xml file, the OPENMC_CROSS_SECTIONS
environment variable will be used to find the path to the XML cross section listing when in continuous-energy mode,
and the OPENMC_MG_CROSS_SECTIONS environment variable will be used in multi-group mode.
<material> Element
Each material element can have the following attributes or sub-elements:

id
A unique integer that can be used to identify the material.
name
An optional string name to identify the material in summary output files.
Default: “”
depletable
Boolean value indicating whether the material is depletable.
volume
Volume of the material in cm^3.
temperature
Temperature of the material in Kelvin.
Default: If a material default temperature is not given and a cell temperature is not speci-
fied, the global default temperature is used.
density
An element with attributes/sub-elements called value and units. The value attribute
is the numeric value of the density while the units can be “g/cm3”, “kg/m3”, “atom/b-
cm”, “atom/cm3”, or “sum”. The “sum” unit indicates that values appearing in ao or wo
attributes for <nuclide> and <element> sub-elements are to be interpreted as absolute
nuclide/element densities in atom/b-cm or g/cm3, and the total density of the material is
taken as the sum of all nuclides/elements. The “macro” unit is used with a macroscopic
quantity to indicate that the density is already included in the library and thus not needed
here. However, if a value is provided for the value, then this is treated as a number density
multiplier on the macroscopic cross sections in the multi-group data. This can be used, for
example, when perturbing the density slightly.

Default: None
Note: A macroscopic quantity can not be used in conjunction with a nuclide,

element, or sab quantity.
nuclide
An element with attributes/sub-elements called name, and ao or wo. The name attribute
is the name of the cross-section for a desired nuclide. Finally, the ao and wo attributes
specify the atom or weight percent of that nuclide within the material, respectively. One
example would be as follows:
<nuclide name="H1" ao="2.0" />

<nuclide name="O16" ao="1.0" />
Note: If one nuclide is specified in atom percent, all others must also be given in atom
percent. The same applies for weight percentages.
Default: None
sab
Associates an S(a,b) table with the material. This element has an attribute/sub-element
called name. The name attribute is the name of the S(a,b) table that should be associated
with the material. There is also an optional fraction element which indicates what frac-
tion of the relevant nuclides will be affected by the S(a,b) table (e.g. which fraction of a
material is crystalline versus amorphous). fraction defaults to unity.
Default: None
Note: This element is not used in the multi-group <energy_mode> Element.
isotropic
The isotropic element indicates a list of nuclides for which elastic scattering should be
treated as though it were isotropic in the laboratory system. This element may be most use-
ful when using OpenMC to compute multi-group cross-sections for deterministic transport
codes and to quantify the effects of anisotropic scattering.
Default: No nuclides are treated as have isotropic elastic scattering.
macroscopic
The macroscopic element is similar to the nuclide element, but, recognizes that some
multi-group libraries may be providing material specific macroscopic cross sections in-
stead of always providing nuclide specific data like in the continuous-energy case. To that
end, the macroscopic element has one attribute/sub-element called name. The name at-
tribute is the name of the cross-section for a desired nuclide. One example would be as
follows:
<macroscopic name="UO2" />

Note: This element is only used in the multi-group <energy_mode> Element.
Default: None
8.1.3 Settings Specification – settings.xml
All simulation parameters and miscellaneous options are specified in the settings.xml file.
<batches> Element
The <batches> element indicates the total number of batches to execute, where each batch corresponds to a tally real-
ization. In a fixed source calculation, each batch consists of a number of source particles. In an eigenvalue calculation,
each batch consists of one or many fission source iterations (generations), where each generation itself consists of a
number of source neutrons.
Default: None
<confidence_intervals> Element
The <confidence_intervals> element has no attributes and has an accepted value of “true” or “false”. If set to
“true”, uncertainties on tally results will be reported as the half-width of the 95% two-sided confidence interval. If set
to “false”, uncertainties on tally results will be reported as the sample standard deviation.
Default: false
<create_fission_neutrons> Element
The <create_fission_neutrons> element indicates whether fission neutrons should be created or not. If this ele-
ment is set to “true”, fission neutrons will be created; otherwise the fission is treated as capture and no fission neutron
will be created. Note that this option is only applied to fixed source calculation. For eigenvalue calculation, fission will
always be treated as real fission.
Default: true
<cutoff> Element
The <cutoff> element indicates two kinds of cutoffs. The first is the weight cutoff used below which particles undergo
Russian roulette. Surviving particles are assigned a user-determined weight. Note that weight cutoffs and Russian
rouletting are not turned on by default. The second is the energy cutoff which is used to kill particles under certain
energy. The energy cutoff should not be used unless you know particles under the energy are of no importance to results
you care. This element has the following attributes/sub-elements:
weight
The weight below which particles undergo Russian roulette.
Default: 0.25
weight_avg
The weight that is assigned to particles that are not killed after Russian roulette.
Default: 1.0

energy_neutron
The energy under which neutrons will be killed.
Default: 0.0
energy_photon
The energy under which photons will be killed.
Default: 1000.0
energy_electron
The energy under which electrons will be killed.
Default: 0.0
energy_positron
The energy under which positrons will be killed.
Default: 0.0
<delayed_photon_scaling>
Determines whether to scale the fission photon yield to account for delayed photon energy. The photon yields are
scaled as (EGP + EGD)/EGP where EGP and EGD are the prompt and delayed photon components of energy release,
respectively, from MF=1, MT=458 on an ENDF evaluation.
Default: true
<electron_treatment> Element
When photon transport is enabled, the <electron_treatment> element tells OpenMC whether to deposit all energy
from electrons locally (led) or create secondary bremsstrahlung photons (ttb).
Default: ttb
<energy_mode> Element
The <energy_mode> element tells OpenMC if the run-mode should be continuous-energy or multi-group. Options for
entry are: continuous-energy or multi-group.
Default: continuous-energy
<entropy_mesh> Element
The <entropy_mesh> element indicates the ID of a mesh that is to be used for calculating Shannon entropy. The mesh
should cover all possible fissionable materials in the problem and is specified using a <mesh> Element.

<event_based>
Determines whether to use event-based parallelism instead of the default history-based parallelism.
Default: false
<generations_per_batch> Element
The <generations_per_batch> element indicates the number of total fission source iterations per batch for an eigen-
value calculation. This element is ignored for all run modes other than “eigenvalue”.
Default: 1
<inactive> Element
The <inactive> element indicates the number of inactive batches used in a k-eigenvalue calculation. In general, the
starting fission source iterations in an eigenvalue calculation can not be used to contribute to tallies since the fission
source distribution and eigenvalue are generally not converged immediately. This element is ignored for all run modes
other than “eigenvalue”.
Default: 0
<keff_trigger> Element
The <keff_trigger> element (ignored for all run modes other than “eigenvalue”.) specifies a precision trigger on
the combined 𝑘𝑒𝑓 𝑓 . The trigger is a convergence criterion on the uncertainty of the estimated eigenvalue. It has the
following attributes/sub-elements:
type
The type of precision trigger. Accepted options are “variance”, “std_dev”, and “rel_err”.
variance
Variance of the batch mean 𝜎 2
std_dev
Standard deviation of the batch mean 𝜎
rel_err
Relative error of the batch mean 𝜎
𝜇
Default: None
threshold
The precision trigger’s convergence criterion for the combined 𝑘𝑒𝑓 𝑓 .
Default: None
Note: See section on the <trigger> Element for more information.

<log_grid_bins> Element
The <log_grid_bins> element indicates the number of bins to use for the logarithmic-mapped energy grid. Using
more bins will result in energy grid searches over a smaller range at the expense of more memory. The default is based
on the recommended value in LA-UR-14-24530.
Default: 8000
<material_cell_offsets>
By default, OpenMC will count the number of instances of each cell filled with a material and generate “offset tables”
that are used for cell instance tallies. The <material_cell_offsets> element allows a user to override this default
setting and turn off the generation of offset tables, if desired, by setting it to false.
Default: true
<max_particles_in_flight> Element
This element indicates the number of neutrons to run in flight concurrently when using event-based parallelism. A
higher value uses more memory, but may be more efficient computationally.
Default: 100000
<max_order> Element
The <max_order> element allows the user to set a maximum scattering order to apply to every nuclide/material in the
problem. That is, if the data library has 𝑃3 data available, but <max_order> was set to 1, then, OpenMC will only use
up to the 𝑃1 data.
Default: Use the maximum order in the data library
Note: This element is not used in the continuous-energy <energy_mode> Element.
<mesh> Element
The <mesh> element describes a mesh that is used either for calculating Shannon entropy, applying the uniform fission
site method, or in tallies. For Shannon entropy meshes, the mesh should cover all possible fissionable materials in the
problem. It has the following attributes/sub-elements:
id
A unique integer that is used to identify the mesh.
dimension
The number of mesh cells in the x, y, and z directions, respectively.
Default: If this tag is not present, the number of mesh cells is automatically determined by
the code.

lower_left
The Cartesian coordinates of the lower-left corner of the mesh.
Default: None
upper_right
The Cartesian coordinates of the upper-right corner of the mesh.
Default: None
<no_reduce> Element
The <no_reduce> element has no attributes and has an accepted value of “true” or “false”. If set to “true”, all user-
defined tallies and global tallies will not be reduced across processors in a parallel calculation. This means that the
accumulate score in one batch on a single processor is considered as an independent realization for the tally random
variable. For a problem with large tally data, this option can significantly improve the parallel efficiency.
Default: false
<output> Element
The <output> element determines what output files should be written to disk during the run. The sub-elements are
described below, where “true” will write out the file and “false” will not.
summary
Writes out an HDF5 summary file describing all of the user input files that were read in.
Default: true
tallies
Write out an ASCII file of tally results.
Default: true
Note: The tally results will always be written to a binary/HDF5 state point file.
path
Absolute or relative path where all output files should be written to. The specified path
must exist or else OpenMC will abort.
Default: Current working directory
<particles> Element
This element indicates the number of neutrons to simulate per fission source iteration when a k-eigenvalue calculation
is performed or the number of particles per batch for a fixed source simulation.
Default: None

<photon_transport> Element
The <photon_transport> element determines whether photon transport is enabled. This element has no attributes
or sub-elements and can be set to either “false” or “true”.
Default: false
<ptables> Element
The <ptables> element determines whether probability tables should be used in the unresolved resonance range if
available. This element has no attributes or sub-elements and can be set to either “false” or “true”.
Default: true
<resonance_scattering> Element
The resonance_scattering element indicates to OpenMC that a method be used to properly account for resonance
elastic scattering (typically for nuclides with Z > 40). This element can contain one or more of the following attributes
or sub-elements:
enable
Indicates whether a resonance elastic scattering method should be turned on. Accepts
values of “true” or “false”.
Default: If the <resonance_scattering> element is present, “true”.
method
Which resonance elastic scattering method is to be applied: “rvs” (relative velocity sam-
pling) or “dbrc” (Doppler broadening rejection correction). Descriptions of each of these
methods are documented here.
Default: “rvs”
energy_min
The energy in eV above which the resonance elastic scattering method should be applied.
Default: 0.01 eV
energy_max
The energy in eV below which the resonance elastic scattering method should be applied.
Default: 1000.0 eV
nuclides
A list of nuclides to which the resonance elastic scattering method should be applied.
Default: If <resonance_scattering> is present but the <nuclides> sub-element is
not given, the method is applied to all nuclides with 0 K elastic scattering data present.
Note: If the resonance_scattering element is not given, the free gas, constant cross section scattering
model, which has historically been used by Monte Carlo codes to sample target velocities, is used to treat
the target motion of all nuclides. If resonance_scattering is present, the constant cross section method
is applied below energy_min and the target-at-rest (asymptotic) kernel is used above energy_max.

<run_mode> Element
The <run_mode> element indicates which run mode should be used when OpenMC is executed. This element has no
attributes or sub-elements and can be set to “eigenvalue”, “fixed source”, “plot”, “volume”, or “particle restart”.
Default: None
<seed> Element
The seed element is used to set the seed used for the linear congruential pseudo-random number generator.
Default: 1
<source> Element
The source element gives information on an external source distribution to be used either as the source for a fixed
source calculation or the initial source guess for criticality calculations. Multiple <source> elements may be specified
to define different source distributions. Each one takes the following attributes/sub-elements:
strength
The strength of the source. If multiple sources are present, the source strength indicates
the relative probability of choosing one source over the other.
Default: 1.0
particle
The source particle type, either neutron or photon.
Default: neutron
file
If this attribute is given, it indicates that the source is to be read from a binary source file
whose path is given by the value of this element. Note, the number of source sites needs
to be the same as the number of particles simulated in a fission source generation.
Default: None
library
If this attribute is given, it indicates that the source is to be instantiated from an externally
compiled source function. This source can be as complex as is required to define the source
for your problem. The library has a few basic requirements:
• It must contain a class that inherits from openmc::Source;
• The class must implement a function called sample();
• There must be an openmc_create_source() function that creates the source as a
unique pointer. This function can be used to pass parameters through to the source
from the XML, if needed.
More documentation on how to build sources can be found in Custom Sources.
Default: None

parameters
If this attribute is given, it provides the parameters to pass through to the class generated
using the library parameter . More documentation on how to build parametrized sources
can be found in Custom Parameterized Sources.
Default: None
space
An element specifying the spatial distribution of source sites. This element has the follow-
ing attributes:
type
The type of spatial distribution. Valid options are “box”, “fission”, “point”,
“cartesian”, “cylindrical”, and “spherical”. A “box” spatial distribution has co-
ordinates sampled uniformly in a parallelepiped. A “fission” spatial distribution
samples locations from a “box” distribution but only locations in fissionable ma-
terials are accepted. A “point” spatial distribution has coordinates specified by
a triplet. A “cartesian” spatial distribution specifies independent distributions
of x-, y-, and z-coordinates. A “cylindrical” spatial distribution specifies inde-
pendent distributions of r-, phi-, and z-coordinates where phi is the azimuthal
angle and the origin for the cylindrical coordinate system is specified by ori-
gin. A “spherical” spatial distribution specifies independent distributions of r-,
cos_theta-, and phi-coordinates where cos_theta is the cosine of the angle with
respect to the z-axis, phi is the azimuthal angle, and the sphere is centered on
the coordinate (x0,y0,z0).
Default: None
parameters
For a “box” or “fission” spatial distribution, parameters should be given as
six real numbers, the first three of which specify the lower-left corner of a par-
allelepiped and the last three of which specify the upper-right corner. Source
sites are sampled uniformly through that parallelepiped.
For a “point” spatial distribution, parameters should be given as three real
numbers which specify the (x,y,z) location of an isotropic point source.
For an “cartesian” distribution, no parameters are specified. Instead, the x, y,
and z elements must be specified.
For a “cylindrical” distribution, no parameters are specified. Instead, the r,
phi, z, and origin elements must be specified.
For a “spherical” distribution, no parameters are specified. Instead, the r,
theta, phi, and origin elements must be specified.
Default: None
x
For an “cartesian” distribution, this element specifies the distribution of x-
coordinates. The necessary sub-elements/attributes are those of a univariate
probability distribution (see the description in Univariate Probability Distribu-
tions).
y
For an “cartesian” distribution, this element specifies the distribution of y-
tions).

z
For both “cartesian” and “cylindrical” distributions, this element specifies the
distribution of z-coordinates. The necessary sub-elements/attributes are those
of a univariate probability distribution (see the description in Univariate Prob-
ability Distributions).
r
For “cylindrical” and “spherical” distributions, this element specifies the distri-
bution of r-coordinates (cylindrical radius and spherical radius, respectively).
The necessary sub-elements/attributes are those of a univariate probability dis-
tribution (see the description in Univariate Probability Distributions).
theta
For a “spherical” distribution, this element specifies the distribution of theta-
tions).
phi
For “cylindrical” and “spherical” distributions, this element specifies the distri-
bution of phi-coordinates. The necessary sub-elements/attributes are those of a
univariate probability distribution (see the description in Univariate Probability
Distributions).
origin
For “cylindrical and “spherical” distributions, this element specifies the coor-
dinates for the origin of the coordinate system.
angle
An element specifying the angular distribution of source sites. This element has the fol-
lowing attributes:
type
The type of angular distribution. Valid options are “isotropic”, “monodirec-
tional”, and “mu-phi”. The angle of the particle emitted from a source site
is isotropic if the “isotropic” option is given. The angle of the particle emit-
ted from a source site is the direction specified in the reference_uvw ele-
ment/attribute if “monodirectional” option is given. The “mu-phi” option pro-
duces directions with the cosine of the polar angle and the azimuthal angle
explicitly specified.
Default: isotropic
reference_uvw
The direction from which the polar angle is measured. Represented by the x-,
y-, and z-components of a unit vector. For a monodirectional distribution, this
defines the direction of all sampled particles.
mu
An element specifying the distribution of the cosine of the polar angle. Only
relevant when the type is “mu-phi”. The necessary sub-elements/attributes are
those of a univariate probability distribution (see the description in Univariate
Probability Distributions).
phi
An element specifying the distribution of the azimuthal angle. Only relevant
when the type is “mu-phi”. The necessary sub-elements/attributes are those of a
univariate probability distribution (see the description in Univariate Probability
Distributions).

energy
An element specifying the energy distribution of source sites. The necessary sub-
elements/attributes are those of a univariate probability distribution (see the description
in Univariate Probability Distributions).
Default: Watt spectrum with 𝑎 = 0.988 MeV and 𝑏 = 2.249 MeV -1
write_initial
An element specifying whether to write out the initial source bank used at the beginning
of the first batch. The output file is named “initial_source.h5”
Default: false
Univariate Probability Distributions
Various components of a source distribution involve probability distributions of a single random variable, e.g. the
distribution of the energy, the distribution of the polar angle, and the distribution of x-coordinates. Each of these com-
ponents supports the same syntax with an element whose tag signifies the variable and whose sub-elements/attributes
are as follows:
type
The type of the distribution. Valid options are “uniform”, “discrete”, “tabular”, “maxwell”, “watt”,
and “mixture”. The “uniform” option produces variates sampled from a uniform distribution over
a finite interval. The “discrete” option produces random variates that can assume a finite number
of values (i.e., a distribution characterized by a probability mass function). The “tabular” option
produces random variates sampled from a tabulated distribution where the density function is either
a histogram or linearly-interpolated between tabulated points. The “watt” option produces random
variates is sampled from a Watt fission spectrum (only used for energies). The “maxwell” option
produce variates sampled from a Maxwell fission spectrum (only used for energies). The “mixture”
option produces samples from univariate sub-distributions with given probabilities.
Default: None
parameters
For a “uniform” distribution, parameters should be given as two real numbers 𝑎 and 𝑏 that define
the interval [𝑎, 𝑏] over which random variates are sampled.
For a “powerlaw” distribution, parameters should be given as three real numbers 𝑎 and 𝑏 that
define the interval [𝑎, 𝑏] over which random variates are sampled and 𝑛 that defines the exponent of
the probability distribution 𝑝(𝑥) = 𝑐𝑥𝑛
For a “discrete” or “tabular” distribution, parameters provides the (𝑥, 𝑝) pairs defining the dis-
crete/tabular distribution. All 𝑥 points are given first followed by corresponding 𝑝 points.
For a “watt” distribution, parameters should
√ be given as two real numbers 𝑎 and 𝑏 that parameterize
the distribution 𝑝(𝑥)𝑑𝑥 = 𝑐𝑒−𝑥/𝑎 sinh 𝑏 𝑥𝑑𝑥.
For a “maxwell” distribution, parameters should be given as one real number 𝑎 that parameterizes
the distribution 𝑝(𝑥)𝑑𝑥 = 𝑐𝑥𝑒−𝑥/𝑎 𝑑𝑥.
Note: The above format should be used even when using the multi-group <energy_mode> Element.
interpolation
For a “tabular” distribution, interpolation can be set to “histogram” or “linear-linear” thereby
specifying how tabular points are to be interpolated.
Default: histogram

pair
For a “mixture” distribution, this element provides a distribution and its corresponding probability.
probability
An attribute or pair that provides the probability of a univariate distribution within a
“mixture” distribution.
dist
This sub-element of a pair element provides information on the corresponding uni-
variate distribution.
<state_point> Element
The <state_point> element indicates at what batches a state point file should be written. A state point file can be
used to restart a run or to get tally results at any batch. The default behavior when using this tag is to write out the
source bank in the state_point file. This behavior can be customized by using the <source_point> element. This
element has the following attributes/sub-elements:
batches
A list of integers separated by spaces indicating at what batches a state point file should be
written.
Default: Last batch only
<source_point> Element
The <source_point> element indicates at what batches the source bank should be written. The source bank can be ei-
ther written out within a state point file or separately in a source point file. This element has the following attributes/sub-
elements:
batches
A list of integers separated by spaces indicating at what batches a state point file should be
written. It should be noted that if the separate attribute is not set to “true”, this list must
be a subset of state point batches.
Default: Last batch only
separate
If this element is set to “true”, a separate binary source point file will be written. Otherwise,
the source sites will be written in the state point directly.
Default: false
write
If this element is set to “false”, source sites are not written to the state point or source point
file. This can substantially reduce the size of state points if large numbers of particles per
batch are used.
Default: true
overwrite_latest
If this element is set to “true”, a source point file containing the source bank will be written
out to a separate file named source.binary or source.h5 depending on if HDF5 is
enabled. This file will be overwritten at every single batch so that the latest source bank
will be available. It should be noted that a user can set both this element to “true” and
specify batches to write a permanent source bank.
Default: false

<surf_source_read> Element
The <surf_source_read> element specifies a surface source file for OpenMC to read source bank for initializing
histories. This element has the following attributes/sub-elements:
path
Absolute or relative path to a surface source file to read in source bank.
Default: surface_source.h5 in current working directory
<surf_source_write> Element
The <surf_source_write> element triggers OpenMC to bank particles crossing certain surfaces and write out the
source bank in a separate file called surface_source.h5. This element has the following attributes/sub-elements:
surface_ids
A list of integers separated by spaces indicating the unique IDs of surfaces for which cross-
ing particles will be banked.
Default: None
max_particles
An integer indicating the maximum number of particles to be banked on specified surfaces
per processor. The size of source bank in surface_source.h5 is limited to this value
times the number of processors.
Default: None
<survival_biasing> Element
The <survival_biasing> element has no attributes and has an accepted value of “true” or “false”. If set to “true”,
this option will enable the use of survival biasing, otherwise known as implicit capture or absorption.
Default: false
<tabular_legendre> Element
The optional <tabular_legendre> element specifies how the multi-group Legendre scattering kernel is represented
if encountered in a multi-group problem. Specifically, the options are to either convert the Legendre expansion to a
tabular representation or leave it as a set of Legendre coefficients. Converting to a tabular representation will cost
memory but can allow for a decrease in runtime compared to leaving as a set of Legendre coefficients. This element
has the following attributes/sub-elements:
enable
This attribute/sub-element denotes whether or not the conversion of a Legendre scattering
expansion to the tabular format should be performed or not. A value of “true” means the
conversion should be performed, “false” means it will not.
Default: true
num_points
If the conversion is to take place the number of tabular points is required. This
attribute/sub-element allows the user to set the desired number of points.
Default: 33

Note: This element is only used in the multi-group <energy_mode> Element.
<temperature_default> Element
The <temperature_default> element specifies a default temperature in Kelvin that is to be applied to cells in the
absence of an explicit cell temperature or a material default temperature.
Default: 293.6 K
<temperature_method> Element
The <temperature_method> element has an accepted value of “nearest” or “interpolation”. A value of “nearest”
indicates that for each cell, the nearest temperature at which cross sections are given is to be applied, within a given
tolerance (see <temperature_tolerance> Element). A value of “interpolation” indicates that cross sections are to be
linear-linear interpolated between temperatures at which nuclear data are present (see Temperature Treatment).
Default: “nearest”
<temperature_multipole> Element
The <temperature_multipole> element toggles the windowed multipole capability on or off. If this element is set
to “True” and the relevant data is available, OpenMC will use the windowed multipole method to evaluate and Doppler
broaden cross sections in the resolved resonance range. This override other methods like “nearest” and “interpolation”
in the resolved resonance range.
Default: False
<temperature_range> Element
The <temperature_range> element specifies a minimum and maximum temperature in Kelvin above and below
which cross sections should be loaded for all nuclides and thermal scattering tables. This can be used for multi-physics
simulations where the temperatures might change from one iteration to the next.
Default: None
<temperature_tolerance> Element
The <temperature_tolerance> element specifies a tolerance in Kelvin that is to be applied when the “nearest”
temperature method is used. For example, if a cell temperature is 340 K and the tolerance is 15 K, then the closest
temperature in the range of 325 K to 355 K will be used to evaluate cross sections.
Default: 10 K

<trace> Element
The <trace> element can be used to print out detailed information about a single particle during a simulation. This
element should be followed by three integers: the batch number, generation number, and particle number.
Default: None
<track> Element
The <track> element specifies particles for which OpenMC will output binary files describing particle position at
every step of its transport. This element should be followed by triplets of integers. Each triplet describes one particle.
The integers in each triplet specify the batch number, generation number, and particle number, respectively.
Default: None
<trigger> Element
OpenMC includes tally precision triggers which allow the user to define uncertainty thresholds on 𝑘𝑒𝑓 𝑓 in the
<keff_trigger> subelement of settings.xml, and/or tallies in tallies.xml. When using triggers, OpenMC
will run until it completes as many batches as defined by <batches>. At this point, the uncertainties on all tallied
values are computed and compared with their corresponding trigger thresholds. If any triggers have not been met,
OpenMC will continue until either all trigger thresholds have been satisfied or <max_batches> has been reached.
The <trigger> element provides an active “toggle switch” for tally precision trigger(s), the maximum number of
batches and the batch interval. It has the following attributes/sub-elements:
active
This determines whether or not to use trigger(s). Trigger(s) are used when this tag is set
to “true”.
max_batches
This describes the maximum number of batches allowed when using trigger(s).
Note: When max_batches is set, the number of batches shown in the <batches> ele-
ment represents minimum number of batches to simulate when using the trigger(s).
batch_interval
This tag describes the number of batches in between convergence checks. OpenMC will
check if the trigger has been reached at each batch defined by batch_interval after the
minimum number of batches is reached.
Note: If this tag is not present, the batch_interval is predicted dynamically by

OpenMC for each convergence check. The predictive model assumes no correlation be-
tween fission sources distributions from batch-to-batch. This assumption is reasonable for
fixed source and small criticality calculations, but is very optimistic for highly coupled
full-core reactor problems.

<ufs_mesh> Element
The <ufs_mesh> element indicates the ID of a mesh that is used for re-weighting source sites at every generation based
on the uniform fission site methodology described in Kelly et al., “MC21 Analysis of the Nuclear Energy Agency Monte
Carlo Performance Benchmark Problem,” Proceedings of Physor 2012, Knoxville, TN (2012). The mesh should cover
all possible fissionable materials in the problem and is specified using a <mesh> Element.
<verbosity> Element
The <verbosity> element tells the code how much information to display to the standard output. A higher verbosity
corresponds to more information being displayed. The text of this element should be an integer between between 1 and
10. The verbosity levels are defined as follows:
1
don’t display any output
2
only show OpenMC logo
3
all of the above + headers
4
all of the above + results
5
all of the above + file I/O
6
all of the above + timing statistics and initialization messages
7
all of the above + 𝑘 by generation
9
all of the above + indicate when each particle starts
10
all of the above + event information
Default: 7
<volume_calc> Element
The <volume_calc> element indicates that a stochastic volume calculation should be run at the beginning of the
simulation. This element has the following sub-elements/attributes:
cells
The unique IDs of cells for which the volume should be estimated.
Default: None
samples
The number of samples used to estimate volumes.
Default: None
lower_left
The lower-left Cartesian coordinates of a bounding box that is used to sample points within.
Default: None

upper_right
The upper-right Cartesian coordinates of a bounding box that is used to sample points
within.
Default: None
<weight_windows> Element
The <weight_windows> element specifies all necessary parameters for mesh-based weight windows. This element
has the following sub-elements/attributes:
id
A unique integer that is used to identify the weight windows
mesh
ID of a mesh that is to be used for weight windows
Default: None
particle_type
The particle that the weight windows will apply to (e.g., ‘neutron’)
Default: None
energy_bins
Monotonically increasing list of bounding energies in [eV] to be used for weight windows
Default: None
lower_ww_bounds
Lower weight window bound for each (energy bin, mesh bin) combination.
Default: None
upper_ww_bounds
Upper weight window bound for each (energy bin, mesh bin) combination.
Default: None
survival
The ratio of survival weight and lower weight window bound.
Default: 3.0
max_lower_bound_ratio
Maximum allowed ratio of a particle’s weight to the weight window’s lower bound. A
factor will be applied to raise the weight window to be lower than the particle’s weight by
a factor of max_lower_bound_ratio during transport if exceeded.
max_split
Maximum allowable number of particles when splitting
Default: 10
weight_cutoff
Threshold below which particles will be terminated
Default: 10−38

8.1.4 Tallies Specification – tallies.xml
The tallies.xml file allows the user to tell the code what results he/she is interested in, e.g. the fission rate in a given
cell or the current across a given surface. There are two pieces of information that determine what quantities should be
scored. First, one needs to specify what region of phase space should count towards the tally and secondly, the actual
quantity to be scored also needs to be specified. The first set of parameters we call filters since they effectively serve to
filter events, allowing some to score and preventing others from scoring to the tally.
The structure of tallies in OpenMC is flexible in that any combination of filters can be used for a tally. The following
types of filter are available: cell, universe, material, surface, birth region, pre-collision energy, post-collision energy,
and an arbitrary structured mesh.
The five valid elements in the tallies.xml file are <tally>, <filter>, <mesh>, <derivative>, and
<assume_separate>.
<tally> Element
The <tally> element accepts the following sub-elements:

name
An optional string name to identify the tally in summary output files.
Default: “”
filters
A space-separated list of the IDs of filter elements.
nuclides
If specified, the scores listed will be for particular nuclides, not the summation of reac-
tions from all nuclides. Nuclides are expressed using the GNDS naming convention, e.g.
“U235” or “Am242_m1”. The reaction rate for all nuclides can be obtained with “total”.
For example, to obtain the reaction rates for U235, Pu239, and all nuclides in a material,
this element should be:
<nuclides>U235 Pu239 total</nuclides>
Default: total
estimator
The estimator element is used to force the use of either analog, collision, or
tracklength tally estimation. analog is generally the least efficient though it can be
used with every score type. tracklength is generally the most efficient, but neither
tracklength nor collision can be used to score a tally that requires post-collision
information. For example, a scattering tally with outgoing energy filters cannot be used
with tracklength or collision because the code will not know the outgoing energy
distribution.
Default: tracklength but will revert to analog if necessary.
scores
A space-separated list of the desired responses to be accumulated. A full list of valid scores
can be found in the user’s guide.
trigger
Precision trigger applied to all filter bins and nuclides for this tally. It must specify
the trigger’s type, threshold and scores to which it will be applied. It has the
following attributes/sub-elements:

type
The type of the trigger. Accepted options are “variance”, “std_dev”, and
“rel_err”.
variance
Variance of the batch mean 𝜎 2
std_dev
Standard deviation of the batch mean 𝜎
rel_err
Relative error of the batch mean 𝜎
𝜇
Default: None
threshold
The precision trigger’s convergence criterion for tallied values.
Default: None
scores
The score(s) in this tally to which the trigger should be applied.
Note: The scores in trigger must have been defined in scores in tally.
An optional “all” may be used to select all scores in this tally.
Default: “all”
derivative
The id of a derivative element. This derivative will be applied to all scores in the tally.
Differential tallies are currently only implemented for collision and analog estimators.
Default: None
<filter> Element
Filters can be used to modify tally behavior. Most tallies (e.g. cell, energy, and material) restrict the tally so
that only particles within certain regions of phase space contribute to the tally. Others (e.g. delayedgroup and
energyfunction) can apply some other function to the scored values. The filter element has the following
attributes/sub-elements:
type
The type of the filter. Accepted options are “cell”, “cellfrom”, “cellborn”, “surface”, “ma-
terial”, “universe”, “energy”, “energyout”, “mu”, “polar”, “azimuthal”, “mesh”, “distrib-
cell”, “delayedgroup”, “energyfunction”, and “particle”.
bins
A description of the bins for each type of filter can be found in Filter Types.
energy
energyfunction filters multiply tally scores by an arbitrary function. The function is
described by a piecewise linear-linear set of (energy, y) values. This entry specifies the
energy values. The function will be evaluated as zero outside of the bounds of this energy
grid. (Only used for energyfunction filters)
y
energyfunction filters multiply tally scores by an arbitrary function. The function is
described by a piecewise linear-linear set of (energy, y) values. This entry specifies the y
values. (Only used for energyfunction filters)

Filter Types
For each filter type, the following table describes what the bins attribute should be set to:
cell
A list of unique IDs for cells in which the tally should be accumulated.
surface
This filter allows the tally to be scored when crossing a surface. A list of surface IDs should be given.
By default, net currents are tallied, and to tally a partial current from one cell to another, this should
be used in combination with a cell or cell_from filter that defines the other cell. This filter should not
be used in combination with a meshfilter.
cellfrom
This filter allows the tally to be scored when crossing a surface and the particle came from a specified
cell. A list of cell IDs should be given. To tally a partial current from a cell to another, this filter
should be used in combination with a cell filter, to define the other cell. This filter should not be used
in combination with a meshfilter.
cellborn
This filter allows the tally to be scored to only when particles were originally born in a specified cell.
A list of cell IDs should be given.
material
A list of unique IDs for materials in which the tally should be accumulated.
universe
A list of unique IDs for universes in which the tally should be accumulated.
energy
In continuous-energy mode, this filter should be provided as a monotonically increasing list of bound-
ing pre-collision energies for a number of groups. For example, if this filter is specified as
<filter type="energy" bins="0.0 1.0e6 20.0e6" />
then two energy bins will be created, one with energies between 0 and 1 MeV and the other with
energies between 1 and 20 MeV.
In multi-group mode the bins provided must match group edges defined in the multi-group library.
energyout
In continuous-energy mode, this filter should be provided as a monotonically increasing list of bound-
ing post-collision energies for a number of groups. For example, if this filter is specified as
<filter type="energyout" bins="0.0 1.0e6 20.0e6" />
then two post-collision energy bins will be created, one with energies between 0 and 1 MeV and the
other with energies between 1 and 20 MeV.
In multi-group mode the bins provided must match group edges defined in the multi-group library.
mu
A monotonically increasing list of bounding post-collision cosines of the change in a particle’s angle
(i.e., 𝜇 = Ω̂ · Ω̂′ ), which represents a portion of the possible values of [−1, 1]. For example, spanning
all of [−1, 1] with five equi-width bins can be specified as:
<filter type="mu" bins="-1.0 -0.6 -0.2 0.2 0.6 1.0" />

Alternatively, if only one value is provided as a bin, OpenMC will interpret this to mean the complete
range of [−1, 1] should be automatically subdivided in to the provided value for the bin. That is, the
above example of five equi-width bins spanning [−1, 1] can be instead written as:
<filter type="mu" bins="5" />
polar
A monotonically increasing list of bounding particle polar angles which represents a portion of the
possible values of [0, 𝜋]. For example, spanning all of [0, 𝜋] with five equi-width bins can be specified
as:
<filter type="polar" bins="0.0 0.6283 1.2566 1.8850 2.5132 3.1416"/>
range of [0, 𝜋] should be automatically subdivided in to the provided value for the bin. That is, the
above example of five equi-width bins spanning [0, 𝜋] can be instead written as:
<filter type="polar" bins="5" />
azimuthal
A monotonically increasing list of bounding particle azimuthal angles which represents a portion of
the possible values of [−𝜋, 𝜋). For example, spanning all of [−𝜋, 𝜋) with two equi-width bins can
be specified as:
<filter type="azimuthal" bins="0.0 3.1416 6.2832" />
range of [−𝜋, 𝜋) should be automatically subdivided in to the provided value for the bin. That is, the
above example of five equi-width bins spanning [−𝜋, 𝜋) can be instead written as:
<filter type="azimuthal" bins="2" />
mesh
The unique ID of a mesh to be tallied over.
distribcell
The single cell which should be tallied uniquely for all instances.
Note: The distribcell filter will take a single cell ID and will tally each unique occurrence of that
cell separately. This filter will not accept more than one cell ID. It is not recommended to combine
this filter with a cell or mesh filter.
delayedgroup
A list of delayed neutron precursor groups for which the tally should be accumulated. For instance,
to tally to all 6 delayed groups in the ENDF/B-VII.1 library the filter is specified as:
<filter type="delayedgroup" bins="1 2 3 4 5 6" />
energyfunction
energyfunction filters do not use the bins entry. Instead they use energy and y.
particle
A list of integers indicating the type of particles to tally (‘neutron’ = 1, ‘photon’ = 2, ‘electron’ = 3,
‘positron’ = 4).

<mesh> Element
If a mesh is desired as a filter for a tally, it must be specified in a separate element with the tag name <mesh>. This
element has the following attributes/sub-elements:
type
The type of mesh. This can be either “regular”, “rectilinear”, “cylindrical”, “spherical”,
or “unstructured”.
dimension
The number of mesh cells in each direction. (For regular mesh only.)
length_multiplier
A multiplicative factor to apply to the mesh coordinates in all directions. (For unstructured
mesh only.)
lower_left
The lower-left corner of the structured mesh. If only two coordinates are given, it is as-
sumed that the mesh is an x-y mesh. (For regular mesh only.)
upper_right
The upper-right corner of the structured mesh. If only two coordinates are given, it is
assumed that the mesh is an x-y mesh. (For regular mesh only.)
width
The width of mesh cells in each direction. (For regular mesh only.)
x_grid
The mesh divisions along the x-axis. (For rectilinear mesh only.)
y_grid
The mesh divisions along the y-axis. (For rectilinear mesh only.)
z_grid
The mesh divisions along the z-axis. (For rectilinear and cylindrical meshes only.)
r_grid
The mesh divisions along the r-axis. (For cylindrical and spherical meshes only.)
phi_grid
The mesh divisions along the phi-axis. (For cylindrical and spherical meshes only.)
theta_grid
The mesh divisions along the theta-axis. (For spherical mesh only.)
library
The mesh library used to represent an unstructured mesh. This can be either “moab” or
“libmesh”. (For unstructured mesh only.)
filename
The name of the mesh file to be loaded at runtime. (For unstructured mesh only.)
Note: One of <upper_right> or <width> must be specified, but not both (even if they are consistent
with one another).

<derivative> Element
OpenMC can take the first-order derivative of many tallies with respect to material perturbations. It works by prop-
agating a derivative through the transport equation. Essentially, OpenMC keeps track of how each particle’s weight
would change as materials are perturbed, and then accounts for that weight change in the tallies. Note that this assumes
material perturbations are small enough not to change the distribution of fission sites. This element has the following
id
A unique integer that can be used to identify the derivative.
variable
The independent variable of the derivative. Accepted options are “density”, “nu-
clide_density”, and “temperature”. A “density” derivative will give the derivative with
respect to the density of the material in [g / cm^3]. A “nuclide_density” derivative will
give the derivative with respect to the density of a particular nuclide in units of [atom / b /
cm]. A “temperature” derivative is with respect to a material temperature in units of [K].
The temperature derivative requires windowed multipole to be turned on. Note also that the
temperature derivative only accounts for resolved resonance Doppler broadening. It does
not account for thermal expansion, S(a, b) scattering, resonance scattering, or unresolved
Doppler broadening.
material
The perturbed material. (Necessary for all derivative types)
nuclide
The perturbed nuclide. (Necessary only for “nuclide_density”)
<assume_separate> Element
In cases where the user needs to specify many different tallies each of which are spatially separate, this tag can be used
to cut down on some of the tally overhead. The effect of assuming all tallies are spatially separate is that once one tally
is scored to, the same event is assumed not to score to any other tallies. This element should be followed by “true” or
“false”.
Warning: If used incorrectly, the assumption that all tallies are spatially separate can lead to incorrect
results.
Default: false
8.1.5 Geometry Plotting Specification – plots.xml
Basic plotting capabilities are available in OpenMC by creating a plots.xml file and subsequently running with the
--plot command-line flag. The root element of the plots.xml is simply <plots> and any number output plots can be
defined with <plot> sub-elements. Two plot types are currently implemented in openMC:
• slice 2D pixel plot along one of the major axes. Produces a PNG image file.
• voxel 3D voxel data dump. Produces an HDF5 file containing voxel xyz position and cell or material id.

<plot> Element
Each plot is specified by a combination of the following attributes or sub-elements:

id
The unique id of the plot.
Default: None - Required entry
filename
Filename for the output plot file.
Default: “plot”
color_by
Keyword for plot coloring. This can be either “cell” or “material”, which colors regions by
cells and materials, respectively. For voxel plots, this determines which id (cell or material)
is associated with each position.
Default: “cell”
level
Universe depth to plot at (optional). This parameter controls how many universe levels
deep to pull cell and material ids from when setting plot colors. If a given location does
not have as many levels as specified, colors will be taken from the lowest level at that
location. For example, if level is set to zero colors will be taken from top-level (universe
zero) cells only. However, if level is set to 1 colors will be taken from cells in universes
that fill top-level fill-cells, and from top-level cells that contain materials.
Default: Whatever the deepest universe is in the model
origin
Specifies the (x,y,z) coordinate of the center of the plot. Should be three floats separated
by spaces.
width
Specifies the width of the plot along each of the basis directions. Should be two or three
floats separated by spaces for 2D plots and 3D plots, respectively.
type
Keyword for type of plot to be produced. Currently only “slice” and “voxel” plots are
implemented. The “slice” plot type creates 2D pixel maps saved in the PNG file format.
The “voxel” plot type produces a binary datafile containing voxel grid positioning and the
cell or material (specified by the color tag) at the center of each voxel. Voxel plot files can
be processed into VTK files using the openmc-voxel-to-vtk script provided with OpenMC
and subsequently viewed with a 3D viewer such as VISIT or Paraview. See the Voxel Plot
File Format for information about the datafile structure.
Note: High-resolution voxel files produced by OpenMC can be quite large, but the equiv-
alent VTK files will be significantly smaller.
Default: “slice”
<plot> elements of type “slice” and “voxel” must contain the pixels attribute or sub-element:

pixels
Specifies the number of pixels or voxels to be used along each of the basis directions for
“slice” and “voxel” plots, respectively. Should be two or three integers separated by spaces.
Warning: If the aspect ratio defined in pixels does not match the aspect ratio defined
in width the plot may appear stretched or squeezed.
Warning: Geometry features along a basis direction smaller than width/pixels

along that basis direction may not appear in the plot.
Default: None - Required entry for “slice” and “voxel” plots

<plot> elements of type “slice” can also contain the following attributes or sub-elements. These are not used in
“voxel” plots:
basis
Keyword specifying the plane of the plot for “slice” type plots. Can be one of: “xy”, “xz”,
“yz”.
Default: “xy”
background
Specifies the RGB color of the regions where no OpenMC cell can be found. Should be
three integers separated by spaces.
Default: 0 0 0 (black)
color
Any number of this optional tag may be included in each <plot> element, which can
override the default random colors for cells or materials. Each color element must contain
id and rgb sub-elements.
id
Specifies the cell or material unique id for the color specification.
rgb
Specifies the custom color for the cell or material. Should be 3 integers sepa-
rated by spaces.
As an example, if your plot is colored by material and you want material 23 to be blue, the
corresponding color element would look like:
<color id="23" rgb="0 0 255" />
Default: None
mask
The special mask sub-element allows for the selective plotting of only user-specified cells
or materials. Only one mask element is allowed per plot element, and it must contain as
attributes or sub-elements a background masking color and a list of cells or materials to
plot:
components
List of unique id numbers of the cells or materials to plot. Should be any
number of integers separated by spaces.

background
Color to apply to all cells or materials not in the components list of cells or
materials to plot. This overrides any color color specifications.
Default: 255 255 255 (white)
meshlines
The meshlines sub-element allows for plotting the boundaries of a regular mesh on top
of a plot. Only one meshlines element is allowed per plot element, and it must contain
as attributes or sub-elements a mesh type and a linewidth. Optionally, a color may be
specified for the overlay:
meshtype
The type of the mesh to be plotted. Valid options are “tally”, “entropy”, “ufs”,
and “cmfd”. If plotting “tally” meshes, the id of the mesh to plot must be spec-
ified with the id sub-element.
id
A single integer id number for the mesh specified on tallies.xml that should
be plotted. This element is only required for meshtype="tally".
linewidth
A single integer number of pixels of linewidth to specify for the mesh bound-
aries. Specifying this as 0 indicates that lines will be 1 pixel thick, specifying
1 indicates 3 pixels thick, specifying 2 indicates 5 pixels thick, etc.
color
Specifies the custom color for the meshlines boundaries. Should be 3 integers
separated by whitespace. This element is optional.
Default: 0 0 0 (black)
Default: None
8.2 Data Files
8.2.1 Cross Sections Listing – cross_sections.xml
<directory> Element
The <directory> element specifies a root directory to which the path for all files listed in a <library> Element are
given relative to. This element has no attributes or sub-elements; the directory should be given within the text node.
For example,
<directory>/opt/data/cross_sections/</directory>
8.2. Data Files 833

<library> Element
The <library> element indicates where an HDF5 data file is located, whether it contains incident neutron, incident
photon, thermal scattering, or windowed multipole data, and what materials are listed within. It has the following
attributes:
materials
A space-separated list of nuclides or thermal scattering tables. For example,
<library materials="U234 U235 U238" />

<library materials="c_H_in_H2O c_D_in_G2O" />
Often, just a single nuclide or thermal scattering table is contained in a given file.
path
Path to the HDF5 file. If the <directory> Element is specified, the path is relative to the
directory given. Otherwise, it is relative to the directory containing the cross_sections.
xml file.
type
The type of data contained in the file. Accepted values are ‘neutron’, ‘thermal’, ‘photon’,
and ‘wmp’.
<depletion_chain> Element
The <depletion_chain> element indicates the location of the depletion chain file. This file contains information
describing how nuclides decay and transmute to other nuclides through the depletion process. This element has a
single attribute, path, pointing to the location of the chain file.
<depletion_chain path="/opt/data/chain_endfb7.xml"/>
The structure of the depletion chain file is explained in Depletion Chain – chain.xml.
8.2.2 Depletion Chain – chain.xml
A depletion chain file has a <depletion_chain> root element with one or more <nuclide> child elements. The
decay, reaction, and fission product data for each nuclide appears as child elements of <nuclide>.
<nuclide> Element
The <nuclide> element contains information on the decay modes, reactions, and fission product yields for a given
nuclide in the depletion chain. This element may have the following attributes:
name
Name of the nuclide
half_life
Half-life of the nuclide in [s]
decay_modes
Number of decay modes present
decay_energy
Decay energy released in [eV]

reactions
Number of reactions present
For each decay mode, a <decay> Element appears as a child of <nuclide>. For each reaction present, a <reaction>
Element appears as a child of <nuclide>. If the nuclide is fissionable, a <neutron_fission_yields> Element appears
as well.
<decay> Element
The <decay> element represents a single decay mode and has the following attributes:
type
The type of the decay, e.g. ‘ec/beta+’
target
The daughter nuclide produced from the decay
branching_ratio
The branching ratio for this decay mode
<reaction> Element
The <reaction> element represents a single transmutation reaction. This element has the following attributes:
type
The type of the reaction, e.g., ‘(n,gamma)’
Q
The Q value of the reaction in [eV]
target
The nuclide produced in the reaction (absent if the type is ‘fission’)
branching_ratio
The branching ratio for the reaction
<neutron_fission_yields> Element
The <neutron_fission_yields> element provides yields of fission products for fissionable nuclides. Normally, it
has the follow sub-elements:
energies
Energies in [eV] at which yields for products are tabulated
fission_yields
Fission product yields for a single energy point. This element itself has a number of
energy
Energy in [eV] at which yields are tabulated
products
Names of fission products
data
Independent yields for each fission product
In the event that a nuclide doesn’t have any known fission product yields, it is possible to have that nuclide borrow
yields from another nuclide by indicating the other nuclide in a single parent attribute. For example:
8.2. Data Files 835

<neutron_fission_yields parent="U235"/>
8.2.3 Nuclear Data File Formats
Incident Neutron Data
/
Attributes
• filetype (char[]) – String indicating the type of file
• version (int[2]) – Major and minor version of the data
/<nuclide name>/
Attributes
• A (int) – Mass number. For a natural element, A=0 is given.
• metastable (int) – Metastable state (0=ground, 1=first excited, etc.)
• atomic_weight_ratio (double) – Mass in units of neutron masses
• n_reaction (int) – Number of reactions
Datasets
• energy (double[]) – Energies in [eV] at which cross sections are tabulated
/<nuclide name>/kTs/
<TTT>K is the temperature in Kelvin, rounded to the nearest integer, of the temperature-dependent data set. For
example, the data set corresponding to 300 Kelvin would be located at 300K.
Datasets
• <TTT>K (double) – kT values in [eV] for each temperature TTT (in Kelvin)
/<nuclide name>/reactions/reaction_<mt>/
Attributes
• mt (int) – ENDF MT reaction number
• label (char[]) – Name of the reaction
• Q_value (double) – Q value in eV
• center_of_mass (int) – Whether the reference frame for scattering is center-of-mass (1) or lab-
oratory (0)
• n_product (int) – Number of reaction products
• redundant (int) – Whether reaction is redundant
/<nuclide name>/reactions/reaction_<mt>/<TTT>K/
Datasets

• xs (double[]) – Cross section values tabulated against the nuclide energy grid for temperature
TTT (in Kelvin)
Attributes
– threshold_idx (int) – Index on the energy grid that the reaction threshold corre-
sponds to for temperature TTT (in Kelvin)
/<nuclide name>/reactions/reaction_<mt>/product_<j>/
Reaction product data is described in Reaction Products.
/<nuclide name>/urr/<TTT>K/
Attributes
• interpolation (int) – interpolation scheme
• inelastic (int) – flag indicating inelastic scattering
• other_absorb (int) – flag indicating other absorption
• factors (int) – flag indicating whether tables are absolute or multipliers
Datasets
• energy (double[]) – Energy at which probability tables exist
• table (double[][][]) – Probability tables
/<nuclide name>/total_nu/
This special product is used to define the total number of neutrons produced from fission. It is formatted
as a reaction product, described in Reaction Products.
/<nuclide name>/fission_energy_release/
Datasets
• fragments (function) – Energy released in the form of fragments as a function of incident neu-
tron energy.
• prompt_neutrons (function) – Energy released in the form of prompt neutrons as a function of
incident neutron energy.
• delayed_neutrons (function) – Energy released in the form of delayed neutrons as a function of
• prompt_photons (function) – Energy released in the form of prompt photons as a function of
• delayed_photons (function) – Energy released in the form of delayed photons as a function of
• betas (function) – Energy released in the form of betas as a function of incident neutron energy.
• neutrinos (function) – Energy released in the form of neutrinos as a function of incident neutron
energy.
• q_prompt (function) – The prompt fission Q-value (fragments + prompt neutrons + prompt
photons - incident energy)
• q_recoverable (function) – The recoverable fission Q-value (Q_prompt + delayed neutrons +
delayed photons + betas)
8.2. Data Files 837

Incident Photon Data
/
Attributes
/<element>/
Attributes
Datasets
• energy (double[]) – Energies in [eV] at which cross sections are tabulated
/<element>/bremsstrahlung/
Attributes
• I (double) – Mean excitation energy in [eV]
Datasets
• electron_energy (double[]) – Incident electron energy in [eV]
• photon_energy (double[]) – Outgoing photon energy as fraction of incident electron energy
• dcs (double[][]) – Bremsstrahlung differential cross section at each incident energy in [mb/eV]
• ionization_energy (double[]) – Ionization potential of each subshell in [eV]
• num_electrons (int[]) – Number of electrons per subshell, with conduction electrons indicated
by a negative value
/<element>/coherent/
Datasets
• xs (double[]) – Coherent scattering cross section in [b]
• integrated_scattering_factor (tabulated) – Integrated coherent scattering form factor
• anomalous_real (tabulated) – Real part of the anomalous scattering factor
• anomalous_imag (tabulated) – Imaginary part of the anomalous scattering factor
/<element>/compton_profiles/
Datasets
• binding_energy (double[]) – Binding energy for each subshell in [eV]
• num_electrons (double[]) – Number of electrons in each subshell
• pz (double[]) – Projection of the electron momentum on the scattering vector in units of 𝑚𝑒2 /ℏ
where 𝑚 is the electron rest mass and 𝑒 is the electron charge
• J (double[][]) – Compton profile for each subshell in units of ℏ/(𝑚𝑒2 )
/<element>/heating/
Datasets
• xs (double[]) – Total heating cross section in [b-eV]

/<element>/incoherent/
Datasets
• xs (double[]) – Incoherent scattering cross section in [b]
• scattering_factor (tabulated) –
/<element>/pair_production_electron/
Datasets
• xs (double[]) – Pair production (electron field) cross section in [b]
/<element>/pair_production_nuclear/
Datasets
• xs (double[]) – Pair production (nuclear field) cross section in [b]
/<element>/photoelectric/
Datasets
• xs (double[]) – Total photoionization cross section in [b]
/<element>/subshells/
Attributes
• designators (char[][]) – Designator for each shell, e.g. ‘M2’
/<element>/subshells/<designator>/
Attributes
• binding_energy (double) – Binding energy of the subshell in [eV]
• num_electrons (double) – Number of electrons in the subshell
Datasets
• transitions (double[][]) – Atomic relaxation data
• xs (double[]) – Photoionization cross section for subshell in [b] tabulated against the main energy
grid
Attributes
– threshold_idx (int) – Index on the energy grid of the reaction threshold
Thermal Neutron Scattering Data
/
Attributes
/<thermal name>/
Attributes
• atomic_weight_ratio (double) – Mass in units of neutron masses
• energy_max (double) – Maximum energy in [eV]
• nuclides (char[][]) – Names of nuclides for which the thermal scattering data applies to
8.2. Data Files 839

/<thermal name>/kTs/
Datasets
• <TTT>K (double) – kT values (in eV) for each temperature TTT (in Kelvin)
/<thermal name>/elastic/<TTT>K/
Datasets
• xs (function) – Thermal elastic scattering cross section for temperature TTT (in Kelvin)
Groups
• distribution – Format for angle-energy distributions are detailed in Angle-Energy Distributions.
/<thermal name>/inelastic/<TTT>K/
Datasets
• xs (function) – Thermal inelastic scattering cross section for temperature TTT (in Kelvin)
Groups
• distribution – Format for angle-energy distributions are detailed in Angle-Energy Distributions.
Reaction Products
Object type
Group
Attributes
• particle (char[]) – Type of particle
• emission_mode (char[]) – Emission mode (prompt, delayed, total)
• decay_rate (double) – Rate of decay in inverse seconds
• n_distribution (int) – Number of angle/energy distributions
Datasets
• yield (function) – Energy-dependent yield of the product.
Groups
• distribution_<k> – Formats for angle-energy distributions are detailed in Angle-Energy Distri-
butions. When multiple angle-energy distributions occur, one dataset also may appear for each
distribution:
Datasets
– applicability (function) – Probability of selecting this distribution as a function of
incident energy

One-dimensional Functions
Scalar
Object type
Dataset
Datatype
double
Attributes
• type (char[]) – ‘constant’
Tabulated
Object type
Dataset
Datatype
double[2][]
Description
x-values are listed first followed by corresponding y-values
Attributes
• type (char[]) – ‘Tabulated1D’
• breakpoints (int[]) – Region breakpoints
• interpolation (int[]) – Region interpolation codes
Polynomial
Object type
Dataset
Datatype
double[]
Description
Polynomial coefficients listed in order of increasing power
Attributes
• type (char[]) – ‘Polynomial’
8.2. Data Files 841

Coherent elastic scattering
Object type
Dataset
Datatype
double[2][]
Description
The first row lists Bragg edges and the second row lists structure factor cumulative sums.
Attributes
• type (char[]) – ‘CoherentElastic’
Incoherent elastic scattering
Object type
Dataset
Datatype
double[2]
Description
The first value is the characteristic bound cross section in [b] and the second value is the Debye-Waller
integral in [eV−1 ].
Attributes
• type (char[]) – ‘IncoherentElastic’
Sum of functions
Object type
Group
Attributes
• type (char[]) – “Sum”
• n (int) – Number of functions
Datasets
• *func_<i> (function) – Dataset for the i-th function (indexing starts at 1)
Angle-Energy Distributions
Uncorrelated Angle-Energy
Object type
Group
Attributes
• type (char[]) – ‘uncorrelated’
Datasets

• angle/energy (double[]) – energies at which angle distributions exist

• angle/mu (double[3][]) – tabulated angular distributions for each energy. The first row gives
𝜇 values, the second row gives the probability density, and the third row gives the cumulative
distribution.
Attributes
– offsets (int[]) – indices indicating where each angular distribution starts
– interpolation (int[]) – interpolation code for each angular distribution
Groups
• energy/ (energy distribution)
Correlated Angle-Energy
Object type
Group
Attributes
• type (char[]) – ‘correlated’
Datasets
• energy (double[]) – Incoming energies at which distributions exist
Attributes
– interpolation (double[2][]) – Breakpoints and interpolation codes for incoming
energy regions
• energy_out (double[5][]) – Distribution of outgoing energies corresponding to each incoming
energy. The distributions are flattened into a single array; the start of a given distribution can
be determined using the offsets attribute. The first row gives outgoing energies, the second
row gives the probability density, the third row gives the cumulative distribution, the fourth row
gives interpolation codes for angular distributions, and the fifth row gives offsets for angular
distributions.
Attributes
– offsets (double[]) – Offset for each distribution
– interpolation (int[]) – Interpolation code for each distribution
– n_discrete_lines (int[]) – Number of discrete lines in each distribution
• mu (double[3][]) – Distribution of angular cosines corresponding to each pair of incoming
and outgoing energies. The distributions are flattened into a single array; the start of a given
distribution can be determined using offsets in the fifth row of the energy_out dataset. The
first row gives angular cosines, the second row gives the probability density, and the third row
gives the cumulative distribution.
8.2. Data Files 843

Kalbach-Mann
Object type
Group
Attributes
• type (char[]) – ‘kalbach-mann’
Datasets
Attributes
energy regions
• distribution (double[5][]) – Distribution of outgoing energies and angles corresponding to each
incoming energy. The distributions are flattened into a single array; the start of a given distri-
bution can be determined using the offsets attribute. The first row gives outgoing energies,
the second row gives the probability density, the third row gives the cumulative distribution, the
fourth row gives Kalbach-Mann precompound factors, and the fifth row gives Kalbach-Mann
angular distribution slopes.
Attributes
N-Body Phase Space
Object type
Group
Attributes
• type (char[]) – ‘nbody’
• total_mass (double) – Total mass of product particles
• atomic_weight_ratio (double) – Atomic weight ratio of the target nuclide in neutron masses
• q_value (double) – Q value for the reaction in eV
Coherent Elastic
This angle-energy distribution is used specifically for coherent elastic thermal neutron scattering.
Object type
Group
Attributes
• type (char[]) – “coherent_elastic”
Hard link

• xs – Link to the coherent elastic scattering cross section
Incoherent Elastic
This angle-energy distribution is used specifically for incoherent elastic thermal neutron scattering (derived from an
ENDF file directly).
Object type
Group
Attributes
• type (char[]) – “incoherent_elastic”
Datasets
• debye_waller (double) – Debye-Waller integral in [eV−1 ]
Incoherent Elastic (Discrete)
This angle-energy distribution is used for discretized incoherent elastic thermal neutron scattering distributions that are
present in ACE files.
Object type
Group
Attributes
• type (char[]) – “incoherent_elastic_discrete”
Datasets
• mu_out (double[][]) – Equiprobable discrete outgoing angles for each incident neutron energy
tabulated
Incoherent Inelastic
This angle-energy distribution is used specifically for (continuous) incoherent inelastic thermal neutron scattering.
Object type
Group
Attributes
• type (char[]) – “incoherent_inelastic”
Datasets
The datasets for this angle-energy distribution are the same as for correlated angle-energy distribu-
tions.
8.2. Data Files 845

Incoherent Inelastic (Discrete)
This angle-energy distribution is used specifically for incoherent inelastic thermal neutron scattering where the distri-
butions have been discretized into equiprobable bins.
Object type
Group
Attributes
• type (char[]) – “incoherent_inelastic_discrete”
Datasets
• energy_out (double[][]) – Distribution of outgoing energies for each incoming energy.
• mu_out (double[][][]) – Distribution of scattering cosines for each pair of incoming and out-
going energies.
• skewed (int8_t) – Whether discrete angles are equi-probable (0) or have a skewed distribution
(1).
Mixed Elastic
This angle-energy distribution is used when an evaluation specifies both coherent and incoherent elastic thermal neutron
scattering.
Object type
Group
Attributes
• type (char[]) – “mixed_elastic”
Groups
• coherent – Distribution for coherent elastic scattering. The format is given in Angle-Energy
Distributions.
• incoherent – Distribution for incoherent elastic scattering. The format is given in Angle-Energy
Distributions.
Energy Distributions
Maxwell
Object type
Group
Attributes
• type (char[]) – ‘maxwell’
• u (double) – Restriction energy in eV
Datasets
• theta (tabulated) – Maxwellian temperature as a function of energy

Evaporation
Object type
Group
Attributes
• type (char[]) – ‘evaporation’
Datasets
• theta (tabulated) – Evaporation temperature as a function of energy
Watt Fission Spectrum
Object type
Group
Attributes
• type (char[]) – ‘watt’
Datasets
• a (tabulated) – Watt parameter 𝑎 as a function of incident energy
• b (tabulated) – Watt parameter 𝑏 as a function of incident energy
Madland-Nix
Object type
Group
Attributes
• type (char[]) – ‘watt’
• efl (double) – Average energy of light fragment in eV
• efh (double) – Average energy of heavy fragment in eV
Discrete Photon
Object type
Group
Attributes
• type (char[]) – ‘discrete_photon’
• primary_flag (int) – Whether photon is a primary
• energy (double) – Photon energy in eV
• atomic_weight_ratio (double) – Atomic weight ratio of target nuclide in neutron masses
8.2. Data Files 847

Level Inelastic
Object type
Group
Attributes
• type (char[]) – ‘level’
• threshold (double) – Energy threshold in the laboratory system in eV
• mass_ratio (double) – (𝐴/(𝐴 + 1))2
Continuous Tabular
Object type
Group
Attributes
• type (char[]) – ‘continuous’
Datasets
Attributes
energy regions
• distribution (double[3][]) – Distribution of outgoing energies corresponding to each incoming
energy. The distributions are flattened into a single array; the start of a given distribution can be
determined using the offsets attribute. The first row gives outgoing energies, the second row
gives the probability density, and the third row gives the cumulative distribution.
Attributes
8.2.4 Multi-Group Cross Section Library Format
OpenMC can be run in continuous-energy mode or multi-group mode, provided the nuclear data is available. In
continuous-energy mode, the cross_sections.xml file contains necessary meta-data for each dataset, including
the name and a file system location where the complete library can be found. In multi-group mode, the multi-group
meta-data and the nuclear data itself is contained within an mgxs.h5 file. This portion of the manual describes the
format of the multi-group data library required to be used in the mgxs.h5 file.
The multi-group library is provided in the HDF5 format. This library must provide some meta-data about the library
itself (such as the number of energy groups, delayed groups, and the energy group structure, etc.) as well as the actual
cross section data itself for each of the necessary nuclides or materials.
The current version of the multi-group library file format is 1.0.

MGXS Library Specification
/
Attributes
• filetype (char[]) – String indicating the type of file; for this library it will be ‘mgxs’.
• version (int[2]) – Major and minor version of the multi-group library file format.
• energy_groups (int) – Number of energy groups
• delayed_groups (int) – Number of delayed groups (optional)
• group structure (double[]) – Monotonically increasing list of group boundaries, in units of eV.
The length of this array should be the number of groups plus 1.
/<library name>/
The data within <library name> contains the temperature-dependent multi-group data for the nuclide or material that
it represents.
Attributes
• atomic_weight_ratio (double) – The atomic weight ratio (optional, i.e. it is not meaningful for
material-wise data).
• fissionable (bool) – Whether the dataset is fissionable (True) or not (False).
• representation (char[]) – The method used to generate and represent the multi-group cross
sections. That is, whether they were generated with scalar flux weighting (or reduced to a sim-
ilar representation) and thus are angle-independent, or if the data was generated with angular
dependent fluxes and thus the data is angle-dependent. Valid values are either “isotropic” or
“angle”.
• num_azimuthal (int) – Number of equal width angular bins that the azimuthal angular domain
is subdivided if the representation attribute is “angle”. This parameter is ignored otherwise.
• num_polar (int) – Number of equal width angular bins that the polar angular domain is subdi-
vided if the representation attribute is “angle”. This parameter is ignored otherwise.
• scatter_format (char[]) – The representation of the scattering angular distribution. The options
are either “legendre”, “histogram”, or “tabular”. If not provided, the default of “legendre” will
be assumed.
• order (int) – Either the Legendre order, number of bins, or number of points (depending on the
value of scatter_format) used to describe the angular distribution associated with each group-
to-group transfer probability.
• scatter_shape (char[]) – The shape of the provided scatter and multiplicity matrix. The values
provided are strings describing the ordering the scattering array is provided in row-major (i.e.,
C/C++ and Python) indexing. Valid values are “[Order][G][G’]” or “[Order][G’][G]” where
“G’” denotes the secondary/outgoing energy groups, “G” denotes the incoming energy groups,
and “Order” is the angular distribution index. This value is not required; if not the default value
of “[Order][G][G’]” will be assumed.
/<library name>/kTs/
Datasets
• <TTT>K (double) – kT values (in eV) for each temperature TTT (in Kelvin), rounded to the
nearest integer
8.2. Data Files 849

/<library name>/<TTT>K/
Temperature-dependent data, provided for temperature <TTT>K.
Datasets
• total (double[] or double[][][]) – Total cross section. This is a 1-D vector if represen-
tation is “isotropic”, or a 3-D vector if representation is “angle” with dimensions of [po-
lar][azimuthal][groups].
• absorption (double[] or double[][][]) – Absorption cross section. This is a 1-D vector if
representation is “isotropic”, or a 3-D vector if representation is “angle” with dimensions of
[groups][azimuthal][polar].
• fission (double[] or double[][][]) – Fission cross section. This is a 1-D vector if represen-
tation is “isotropic”, or a 3-D vector if representation is “angle” with dimensions of [po-
lar][azimuthal][groups]. This is only required if the dataset is fissionable and fission-tallies
are expected to be used.
• kappa-fission (double[] or double[][][]) – Kappa-Fission (energy-release from fission) cross
section. This is a 1-D vector if representation is “isotropic”, or a 3-D vector if representation
is “angle” with dimensions of [polar][azimuthal][groups]. This is only required if the dataset is
fissionable and fission-tallies are expected to be used.
• chi (double[] or double[][][]) – Fission neutron energy spectra. This is a 1-D vector if rep-
resentation is “isotropic”, or a 3-D vector if representation is “angle” with dimensions of [po-
lar][azimuthal][groups]. This is only required if the dataset is fissionable and fission-tallies are
expected to be used.
• nu-fission (double[] to double[][][][]) – Nu-Fission cross section. If chi is provided, then
nu-fission has the same dimensionality as fission. If chi is not provided, then the nu-fission
data must represent the fission neutron energy spectra as well and thus will have one additional
dimension for the outgoing energy group. In this case, nu-fission has the same dimensionality
as multiplicity matrix.
• inverse-velocity (double[] or double[][][]) – Average inverse velocity for each of the groups in
the library. This dataset is optional. This is a 1-D vector if representation is “isotropic”, or a
3-D vector if representation is “angle” with dimensions of [polar][azimuthal][groups].
/<library name>/<TTT>K/scatter_data/
Data specific to neutron scattering for the temperature <TTT>K
Datasets
• g_min (int[] or int[][][]) – Minimum (most energetic) groups with non-zero values of the scat-
tering matrix provided. If scatter_shape is “[Order][G][G’]” then g_min will describe the mini-
mum values of “G’” for each “G”; if scatter_shape is “[Order][G’][G]” then g_min will describe
the minimum values of “G” for each “G’”. These group numbers use the standard ordering where
the fastest neutron energy group is group 1 while the slowest neutron energy group is group G.
The dimensionality of g_min is: g_min[g], or g_min[num_polar][num_azimuthal][g]. The for-
mer is used when representation is “isotropic”, and the latter when representation is “angle”.
• g_max (int[] or int[][][]) – Similar to g_min, except this dataset describes the maximum (least
energetic) groups with non-zero values of the scattering matrix.
• scatter_matrix (double[]) – Flattened representation of the scattering moment matrices. The
pre-flattened array corresponds to the shape provied in scatter_shape, but if representation is
“angle” the dimensionality in scatter_shape is prepended by “[num_polar][num_azimuthal]”
dimensions. The right-most energy group dimension will only include the entries between g_min
and g_max. dimension has a dimensionality of g_min to g_max.

• multiplicity_matrix (double[]) – Flattened representation of the scattering moment matrices.

This dataset provides the code with a scaling factor to account for neutrons being produced in
(n,xn) reactions. This is assumed isotropic and therefore is not repeated for every Legendre mo-
ment or histogram/tabular bin. This dataset is optional, if it is not provided no multiplication (i.e.,
values of 1.0) will be assumed. The pre-flattened array is shapes consistent with scatter_matrix
except the “[Order]” dimension in scatter_shape is ignored since this data is assumed isotropic.
8.2.5 Windowed Multipole Library Format
/
Attributes
/<nuclide name>/
Datasets
•broaden_poly (int[])
If 1, Doppler broaden curve fit for window with corresponding index. If 0, do not.
•curvefit (double[][][])
Curve fit coefficients. Indexed by (window index, coefficient index, reaction type).
•data (complex[][])
Complex poles and residues. Each pole has a corresponding set of residues. For example,
the 𝑖-th pole and corresponding residues are stored as
data[:, 𝑖] = [pole, residue1 , residue2 , . . .]
The residues are in the order: scattering, absorption, fission. Complex numbers are stored
by forming a type with “𝑟” and “𝑖” identifiers, similar to how h5py does it.
•E_max (double)
Highest energy the windowed multipole part of the library is valid for.
•E_min (double)
Lowest energy the windowed multipole part of the library is valid for.
•spacing (double)
√ √
𝐸𝑚𝑎𝑥 − 𝐸𝑚𝑖𝑛
𝑛𝑤
Where 𝐸𝑚𝑎𝑥 is the maximum energy the windows go up to. 𝐸𝑚𝑖𝑛 is the minimum energy,
and 𝑛𝑤 is the number of windows, given by windows.
•sqrtAWR (double)
Square root of the atomic weight ratio.
•windows (int[][])
The poles to start from and end at for each window. windows[i, 0] and windows[i, 1] are,
respectively, the indexes (1-based) of the first and last pole in window i.
8.2. Data Files 851

8.3 Output Files
8.3.1 State Point File Format
The current version of the statepoint file format is 17.0.

/
Attributes
• filetype (char[]) – String indicating the type of file.
• version (int[2]) – Major and minor version of the statepoint file format.
• openmc_version (int[3]) – Major, minor, and release version number for OpenMC.
• git_sha1 (char[40]) – Git commit SHA-1 hash.
• date_and_time (char[]) – Date and time the summary was written.
• path (char[]) – Path to directory containing input files.
• tallies_present (int) – Flag indicating whether tallies are present (1) or not (0).
• source_present (int) – Flag indicating whether the source bank is present (1) or not (0).
Datasets
• seed (int8_t) – Pseudo-random number generator seed.
• energy_mode (char[]) – Energy mode of the run, either ‘continuous-energy’ or ‘multi-group’.
• run_mode (char[]) – Run mode used, either ‘eigenvalue’ or ‘fixed source’.
• n_particles (int8_t) – Number of particles used per generation.
• n_batches (int) – Number of batches to simulate.
• current_batch (int) – The number of batches already simulated.
• n_inactive (int) – Number of inactive batches. Only present when run_mode is ‘eigenvalue’.
• generations_per_batch (int) – Number of generations per batch. Only present when run_mode
is ‘eigenvalue’.
• k_generation (double[]) – k-effective for each generation simulated.
• entropy (double[]) – Shannon entropy for each generation simulated.
• k_col_abs (double) – Sum of product of collision/absorption estimates of k-effective.
• k_col_tra (double) – Sum of product of collision/track-length estimates of k-effective.
• k_abs_tra (double) – Sum of product of absorption/track-length estimates of k-effective.
• k_combined (double[2]) – Mean and standard deviation of a combined estimate of k-effective.
• n_realizations (int) – Number of realizations for global tallies.
• global_tallies (double[][2]) – Accumulated sum and sum-of-squares for each global tally.
• source_bank (Compound type) – Source bank information for each particle. The compound
type has fields r, u, E, time, wgt, delayed_group, surf_id, and particle, which repre-
sent the position, direction, energy, time, weight, delayed group, surface ID, and particle type
(0=neutron, 1=photon, 2=electron, 3=positron), respectively. Only present when run_mode is
‘eigenvalue’.

/tallies/
Attributes
• n_tallies (int) – Number of user-defined tallies.
• ids (int[]) – User-defined unique ID of each tally.
/tallies/meshes/
Attributes
• n_meshes (int) – Number of meshes in the problem.
• ids (int[]) – User-defined unique ID of each mesh.
/tallies/meshes/mesh <uid>/
Datasets
• type (char[]) – Type of mesh.
• dimension (int) – Number of mesh cells in each dimension.
• lower_left (double[]) – Coordinates of lower-left corner of mesh.
• upper_right (double[]) – Coordinates of upper-right corner of mesh.
• width (double[]) – Width of each mesh cell in each dimension.
•Unstructured Mesh Only:
– filename (char[]) – Name of the mesh file.
–library (char[]) – Mesh library used to represent the
mesh (“moab” or “libmesh”).
– length_multiplier (double) Scaling factor applied to the mesh.
– volumes (double[]) – Volume of each mesh cell.
– vertices (double[]) – x, y, z values of the mesh vertices.
– connectivity (int[]) – Connectivity array for the mesh cells.
– element_types (int[]) – Mesh element types.
/tallies/filters/
Attributes
• n_filters (int) – Number of filters in the problem.
• ids (int[]) – User-defined unique ID of each filter.
/tallies/filters/filter <uid>/
Datasets
• type (char[]) – Type of the j-th filter. Can be ‘universe’, ‘material’, ‘cell’, ‘cellborn’, ‘surface’,
‘mesh’, ‘energy’, ‘energyout’, ‘distribcell’, ‘mu’, ‘polar’, ‘azimuthal’, ‘delayedgroup’, or ‘ener-
gyfunction’.
• n_bins (int) – Number of bins for the j-th filter. Not present for ‘energyfunction’ filters.
• bins (int[] or double[]) – Value for each filter bin of this type. Not present for ‘energyfunction’
filters.
• energy (double[]) – Energy grid points for energyfunction interpolation. Only used for ‘ener-
gyfunction’ filters.
8.3. Output Files 853

• y (double[]) – Interpolant values for energyfunction interpolation. Only used for ‘energyfunc-
tion’ filters.
/tallies/derivatives/derivative <id>/
Datasets
• independent variable (char[]) – Independent variable of tally derivative.
• material (int) – ID of the perturbed material.
• nuclide (char[]) – Alias of the perturbed nuclide.
• estimator (char[]) – Type of tally estimator, either ‘analog’, ‘tracklength’, or ‘collision’.
/tallies/tally <uid>/
Attributes
• internal (int) – Flag indicating the presence of tally data (0) or absence of tally data (1). All
user defined tallies will have a value of 0 unless otherwise instructed.
Datasets
• n_realizations (int) – Number of realizations.
• n_filters (int) – Number of filters used.
• filters (int[]) – User-defined unique IDs of the filters on the tally
• nuclides (char[][]) – Array of nuclides to tally. Note that if no nuclide is specified in the user
input, a single ‘total’ nuclide appears here.
• derivative (int) – ID of the derivative applied to the tally.
• n_score_bins (int) – Number of scoring bins for a single nuclide.
• score_bins (char[][]) – Values of specified scores.
• results (double[][][2]) – Accumulated sum and sum-of-squares for each bin of the i-th tally. The
first dimension represents combinations of filter bins, the second dimensions represents scoring
bins, and the third dimension has two entries for the sum and the sum-of-squares.
/runtime/
All values are given in seconds and are measured on the master process.
Datasets
• total initialization (double) – Time spent reading inputs, allocating arrays, etc.
• reading cross sections (double) – Time spent loading cross section libraries (this is a subset of
initialization).
• simulation (double) – Time spent between initialization and finalization.
• transport (double) – Time spent transporting particles.
• inactive batches (double) – Time spent in the inactive batches (including non-transport activities
like communicating sites).
• active batches (double) – Time spent in the active batches (including non-transport activities
like communicating sites).
• synchronizing fission bank (double) – Time spent sampling source particles from fission sites
and communicating them to other processes for load balancing.
• sampling source sites (double) – Time spent sampling source particles from fission sites.

• SEND-RECV source sites (double) – Time spent communicating source sites between pro-
cesses for load balancing.
• accumulating tallies (double) – Time spent communicating tally results and evaluating their
statistics.
• writing statepoints (double) – Time spent writing statepoint files
8.3.2 Source File Format
Normally, source data is stored in a state point file. However, it is possible to request that the source be written separately,
in which case the format used is that documented here.
When surface source writing is triggered, a source file named surface_source.h5 is written with only the sources
on specified surfaces, following the same format.
/
Attributes
Datasets
• source_bank (Compound type) – Source bank information for each particle. The compound
type has fields r, u, E, time, wgt, delayed_group, surf_id and particle, which repre-
sent the position, direction, energy, time, weight, delayed group, surface ID, and particle type
(0=neutron, 1=photon, 2=electron, 3=positron), respectively.
8.3.3 Summary File Format
The current version of the summary file format is 6.0.

/
Attributes
• version (int[2]) – Major and minor version of the summary file format.
/geometry/
Attributes
• n_cells (int) – Number of cells in the problem.
• n_surfaces (int) – Number of surfaces in the problem.
• n_universes (int) – Number of unique universes in the problem.
• n_lattices (int) – Number of lattices in the problem.
/geometry/cells/cell <uid>/
Datasets
• name (char[]) – User-defined name of the cell.

• universe (int) – Universe assigned to the cell. If none is specified, the default universe (0) is
assigned.
• fill_type (char[]) – Type of fill for the cell. Can be ‘material’, ‘universe’, or ‘lattice’.
• material (int or int[]) – Unique ID of the material(s) assigned to the cell. This dataset is present
only if fill_type is set to ‘normal’. The value ‘-1’ signifies void material. The data is an array if
the cell uses distributed materials, otherwise it is a scalar.
• temperature (double[]) – Temperature of the cell in Kelvin.
• translation (double[3]) – Translation applied to the fill universe. This dataset is present only if
fill_type is set to ‘universe’.
• rotation (double[3]) – Angles in degrees about the x-, y-, and z-axes for which the fill universe
should be rotated. This dataset is present only if fill_type is set to ‘universe’.
• lattice (int) – Unique ID of the lattice which fills the cell. Only present if fill_type is set to
‘lattice’.
• region (char[]) – Region specification for the cell.
• geom_type (char[]) – Type of geometry used to create the cell. Either ‘csg’ or ‘dagmc’.
/geometry/surfaces/surface <uid>/
Datasets
• name (char[]) – Name of the surface.
• type (char[]) – Type of the surface. Can be ‘x-plane’, ‘y-plane’, ‘z-plane’, ‘plane’, ‘x-cylinder’,
‘y-cylinder’, ‘z-cylinder’, ‘sphere’, ‘x-cone’, ‘y-cone’, ‘z-cone’, ‘quadric’, ‘x-torus’, ‘y-torus’, or
‘z-torus’.
• coefficients (double[]) – Array of coefficients that define the surface. See <surface> Element
for what coefficients are defined for each surface type.
• boundary_condition (char[]) – Boundary condition applied to the surface. Can be ‘transmis-
sion’, ‘vacuum’, ‘reflective’, or ‘periodic’.
/geometry/universes/universe <uid>/
Datasets
• cells (int[]) – Array of unique IDs of cells that appear in the universe.
• filename (char[]) – Name of the DAGMC file representing this universe. Only present for
DAGMC Universes.
Attributes
• auto_geom_ids (int) – 1 if geometry IDs of the DAGMC model will be appended to the ID
space of the natively defined CSG geometry, 0 if the existing DAGMC IDs will be used.
• auto_mat_ids (int) – 1 if UWUW material IDs of the DAGMC model will be appended to the
ID space of the natively defined OpenMC materials, 0 if the existing UWUW IDs will be used.
/geometry/lattices/lattice <uid>/
Datasets
• name (char[]) – Name of the lattice.

• type (char[]) – Type of the lattice, either ‘rectangular’ or ‘hexagonal’.

• pitch (double[]) – Pitch of the lattice in centimeters.
• outer (int) – Outer universe assigned to lattice cells outside the defined range.
• universes (int[][][]) – Three-dimensional array of universes assigned to each cell of the lattice.
• dimension (int[]) – The number of lattice cells in each direction. This dataset is present only
when the ‘type’ dataset is set to ‘rectangular’.
• lower_left (double[]) – The coordinates of the lower-left corner of the lattice. This dataset is
present only when the ‘type’ dataset is set to ‘rectangular’.
• n_rings (int) – Number of radial ring positions in the xy-plane. This dataset is present only
when the ‘type’ dataset is set to ‘hexagonal’.
• n_axial (int) – Number of lattice positions along the z-axis. This dataset is present only when
the ‘type’ dataset is set to ‘hexagonal’.
• center (double[]) – Coordinates of the center of the lattice. This dataset is present only when
the ‘type’ dataset is set to ‘hexagonal’.
/materials/
Attributes
• n_materials (int) – Number of materials in the problem.
/materials/material <uid>/
Datasets
• name (char[]) – Name of the material.
• atom_density (double[]) – Total atom density of the material in atom/b-cm.
• nuclides (char[][]) – Array of nuclides present in the material, e.g., ‘U235’. This data set is
only present if nuclides are used.
• nuclide_densities (double[]) – Atom density of each nuclide. This data set is only present if
‘nuclides’ data set is present.
• macroscopics (char[][]) – Array of macroscopic data sets present in the material. This dataset
is only present if macroscopic data sets are used in multi-group mode.
• sab_names (char[][]) – Names of S(𝛼, 𝛽) tables assigned to the material.
Attributes
• volume (double[]) – Volume of this material [cm^3]. Only present if volume supplied
• temperature (double[]) – Temperature of this material [K]. Only present if temperature is
supplied
• depletable (int) – 1 if the material can be depleted, 0 otherwise. Always present
/nuclides/
Attributes
• n_nuclides (int) – Number of nuclides in the problem.
Datasets
• names (char[][]) – Names of nuclides.
• awrs (float[]) – Atomic weight ratio of each nuclide.

/macroscopics/
Attributes
• n_macroscopics (int) – Number of macroscopic data sets in the problem.
Datasets
• names (char[][]) – Names of the macroscopic data sets.
/tallies/tally <uid>/
Datasets
• name (char[]) – Name of the tally.
8.3.4 Properties File Format
The current version of the properties file format is 1.0.

/
Attributes
• path (char[]) – Path to directory containing input files.
/geometry/
Attributes
• n_cells (int) – Number of cells in the problem.
/geometry/cells/cell <uid>/
Datasets
• temperature (double[]) – Temperature of the cell in [K].
/materials/
Attributes
• n_materials (int) – Number of materials in the problem.
/materials/material <uid>/
Attributes
• atom_density (double) – Total density in [atom/b-cm].
• mass_density (double) – Total density in [g/cm^3].

8.3.5 Depletion Results File Format
The current version of the depletion results file format is 1.1.

/
Attributes
Datasets
• eigenvalues (double[][][2]) – k-eigenvalues at each time/stage. This array has shape (number
of timesteps, number of stages, value). The last axis contains the eigenvalue and the associated
uncertainty
• number (double[][][][]) – Total number of atoms. This array has shape (number of timesteps,
number of stages, number of materials, number of nuclides).
• reaction rates (double[][][][][]) – Reaction rates used to build depletion matrices. This array
has shape (number of timesteps, number of stages, number of materials, number of nuclides,
number of reactions).
• time (double[][2]) – Time in [s] at beginning/end of each step.
• source_rate (double[][]) – Power in [W] or source rate in [neutron/sec]. This array has shape
(number of timesteps, number of stages).
• depletion time (double[]) – Average process time in [s] spent depleting a material across all
burnable materials and, if applicable, MPI processes.
/materials/<id>/
Attributes
• index (int) – Index used in results for this material
• volume (double) – Volume of this material in [cm^3]
/nuclides/<name>/
Attributes
• atom number index (int) – Index in array of total atoms for this nuclide
• reaction rate index (int) – Index in array of reaction rates for this nuclide
/reactions/<name>/
Attributes
• index (int) – Index user in results for this reaction
Note: The reaction rates for some isotopes not originally present may be non-zero, but should be negligible compared
to other atoms. This can be controlled by changing the openmc.deplete.Operator dilute_initial attribute.

8.3.6 Particle Restart File Format
The current version of the particle restart file format is 2.0.

/
Attributes
• version (int[2]) – Major and minor version of the particle restart file format.
Datasets
• current_batch (int) – The number of batches already simulated.
• generations_per_batch (int) – Number of generations per batch.
• current_generation (int) – The number of generations already simulated.
• n_particles (int8_t) – Number of particles used per generation.
• run_mode (char[]) – Run mode used, either ‘fixed source’, ‘eigenvalue’, or ‘particle restart’.
• id (int8_t) – Unique identifier of the particle.
• weight (double) – Weight of the particle.
• energy (double) – Energy of the particle in eV for continuous-energy mode, or the energy group
of the particle for multi-group mode.
• xyz (double[3]) – Position of the particle.
• uvw (double[3]) – Direction of the particle.
• time (double) – Time of the particle in [s].
8.3.7 Track File Format
The current revision of the particle track file format is 3.0.

/
Attributes
• version (int[2]) – Major and minor version of the track file format.
Datasets
• track_<b>_<g>_<p> (Compound type) – Particle track information for source particle in batch
b, generation g, and particle number p. particle. The compound type has fields r, u, E, time,
wgt, cell_id, cell_instance, and material_id, which represent the position (each coor-
dinate in [cm]), direction, energy in [eV], time in [s], weight, cell ID, cell instance, and material
ID, respectively. When the particle is present in a cell with no material assigned, the material
ID is given as -1. Note that this array contains information for one or more primary/secondary
particles originating. The starting index for each primary/secondary particle is given by the
offsets attribute.
Attributes

– n_particles (int) – Number of primary/secondary particles for the source history.

– offsets (int[]) Offset (starting index) into the array for each primary/secondary
particle. The last offset should match the total size of the array.
– particles (int[]) – Particle type for each primary/secondary particle (0=neutron,
1=photon, 2=electron, 3=positron).
8.3.8 Voxel Plot File Format
The current version of the voxel file format is 1.0.

/
Attributes
• version (int[2]) – Major and minor version of the voxel file format.
• num_voxels (int[3]) – Number of voxels in the x-, y-, and z- directions.
• voxel_width (double[3]) – Width of a voxel in centimeters.
• lower_left (double[3]) – Cartesian coordinates of the lower-left corner of the plot.
Datasets
• data (int[][][]) – Data for each voxel that represents a material or cell ID.
8.3.9 Volume File Format
The current version of the volume file format is 1.0.

/
Attributes
• version (int[2]) – Major and minor version of the summary file format.
• domain_type (char[]) – The type of domain for which volumes are calculated, either ‘cell’,
‘material’, or ‘universe’.
• samples (int) – Number of samples
• lower_left (double[3]) – Lower-left coordinates of bounding box
• upper_right (double[3]) – Upper-right coordinates of bounding box
• threshold (double) – Threshold used for volume uncertainty
• trigger_type (char[]) – Trigger type used for volume uncertainty

/domain_<id>/
Datasets
• volume (double[2]) – Calculated volume and its uncertainty in cubic centimeters
• nuclides (char[][]) – Names of nuclides identified in the domain
• atoms (double[][2]) – Total number of atoms of each nuclide and its uncertainty

CHAPTER
NINE
PUBLICATIONS
9.1 Overviews
• Paul K. Romano, Nicholas E. Horelik, Bryan R. Herman, Adam G. Nelson, Benoit Forget, and Kord Smith,
“OpenMC: A State-of-the-Art Monte Carlo Code for Research and Development,” Ann. Nucl. Energy, 82,
90–97 (2015).
• Paul K. Romano, Bryan R. Herman, Nicholas E. Horelik, Benoit Forget, Kord Smith, and Andrew R. Siegel,
“Progress and Status of the OpenMC Monte Carlo Code,” Proc. Int. Conf. Mathematics and Computational
Methods Applied to Nuclear Science and Engineering, Sun Valley, Idaho, May 5–9 (2013).
• Paul K. Romano and Benoit Forget, “The OpenMC Monte Carlo Particle Transport Code,” Ann. Nucl. Energy,
51, 274–281 (2013).
9.2 Benchmarking
• Travis J. Labossiere-Hickman and Benoit Forget, “Selected VERA Core Physics Benchmarks in OpenMC,”
Trans. Am. Nucl. Soc., 117, 1520-1523 (2017).
• Khurrum S. Chaudri and Sikander M. Mirza, “Burnup dependent Monte Carlo neutron physics calculations of
IAEA MTR benchmark,” Prog. Nucl. Energy, 81, 43-52 (2015).
• Daniel J. Kelly, Brian N. Aviles, Paul K. Romano, Bryan R. Herman, Nicholas E. Horelik, and Benoit Forget,
“Analysis of select BEAVRS PWR benchmark cycle 1 results using MC21 and OpenMC,” Proc. PHYSOR,
Kyoto, Japan, Sep. 28–Oct. 3 (2014).
• Bryan R. Herman, Benoit Forget, Kord Smith, Paul K. Romano, Thomas M. Sutton, Daniel J. Kelly, III, and
Brian N. Aviles, “Analysis of tally correlations in large light water reactors,” Proc. PHYSOR, Kyoto, Japan, Sep.
28–Oct. 3 (2014).
• Nicholas Horelik, Bryan Herman, Benoit Forget, and Kord Smith, “Benchmark for Evaluation and Validation of
Reactor Simulations,” Proc. Int. Conf. Mathematics and Computational Methods Applied to Nuclear Science
and Engineering, Sun Valley, Idaho, May 5–9 (2013).
• Jonathan A. Walsh, Benoit Forget, and Kord S. Smith, “Validation of OpenMC Reactor Physics Simulations with
the B&W 1810 Series Benchmarks,” Trans. Am. Nucl. Soc., 109, 1301–1304 (2013).
863
9.3 Coupling and Multi-physics
• Miriam A. Kreher, Benoit Forget, and Kord Smith, “Single-Batch Monte Carlo Multiphysics Coupling,” Proc.
M&C, 1789-1797, Portland, Oregon, Aug. 25-29 (2019).
• Ze-Long Zhao, Yongwei Yang, and Shuang Hong, “Application of FLUKA and OpenMC in coupled physics
calculation of target and subcritical reactor for ADS,” Nucl. Sci. Tech., 30: 10 (2019).
• April Novak, Paul Romano, Brycen Wendt, Ron Rahaman, Elia Merzari, Leslie Kerby, Cody Permann, Richard
Martineau, and Rachel N. Slaybaugh, “Preliminary Coupling of OpenMC and Nek5000 within the MOOSE
Framework,” Proc. PHYSOR, Cancun, Mexico, Apr. 22-26 (2018).
• Sterling Harper, Kord Smith, and Benoit Forget, “Faster Monte Carlo multiphysics using temperature deriva-
tives,” Proc. PHYSOR, Cancun, Mexico, Apr. 22-26 (2018).
• Jun Chen, Liangzhi Cao, Chuanqi Zhao, and Zhouyu Liu, “Development of Subchannel Code SUBSC for high-
fidelity multi-physics coupling application”, Energy Procedia, 127, 264-274 (2017).
• Tianliang Hu, Liangzhu Cao, Hongchun Wu, Xianan Du, and Mingtao He, “Coupled neutronics and thermal-
hydraulics simulation of molten salt reactors based on OpenMC/TANSY,” Ann. Nucl. Energy, 109, 260-276
(2017).
• Matthew Ellis, Derek Gaston, Benoit Forget, and Kord Smith, “Preliminary Coupling of the Monte Carlo Code
OpenMC and the Multiphysics Object-Oriented Simulation Environment for Analyzing Doppler Feedback in
Monte Carlo Simulations,” Nucl. Sci. Eng., 185, 184-193 (2017).
• Matthew Ellis, Benoit Forget, Kord Smith, and Derek Gaston, “Continuous Temperature Representation in Cou-
pled OpenMC/MOOSE Simulations,” Proc. PHYSOR 2016, Sun Valley, Idaho, May 1-5, 2016.
• Antonios G. Mylonakis, Melpomeni Varvayanni, and Nicolas Catsaros, “Investigating a Matrix-free, Newton-
based, Neutron-Monte Carlo/Thermal-Hydraulic Coupling Scheme”, Proc. Int. Conf. Nuclear Energy for New
Europe, Portoroz, Slovenia, Sep .14-17 (2015).
• Matt Ellis, Benoit Forget, Kord Smith, and Derek Gaston, “Preliminary coupling of the Monte Carlo code
OpenMC and the Multiphysics Object-Oriented Simulation Environment (MOOSE) for analyzing Doppler feed-
back in Monte Carlo simulations,” Proc. Joint Int. Conf. M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23
(2015).
• Bryan R. Herman, Benoit Forget, and Kord Smith, “Progress toward Monte Carlo-thermal hydraulic coupling
using low-order nonlinear diffusion acceleration methods,” Ann. Nucl. Energy, 84, 63-72 (2015).
• Bryan R. Herman, Benoit Forget, and Kord Smith, “Utilizing CMFD in OpenMC to Estimate Dominance Ratio
and Adjoint,” Trans. Am. Nucl. Soc., 109, 1389-1392 (2013).
9.4 Geometry and Visualization
• Patrick C. Shriwise, Xiaokang Zhang, and Andrew Davis, “DAG-OpenMC: CAD-Based Geometry in OpenMC”,
Trans. Am. Nucl. Soc., 122, 395-398 (2020).
• Sterling Harper, Paul Romano, Benoit Forget, and Kord Smith, “Efficient dynamic threadsafe neighbor lists for
Monte Carlo ray tracing,” Proc. M&C, 918-926, Portland, Oregon, Aug. 25-29 (2019).
• Jin-Yang Li, Long Gu, Hu-Shan Xu, Nadezha Korepanova, Rui Yu, Yan-Lei Zhu, and Chang-Ping Qin, “CAD
modeling study on FLUKA and OpenMC for accelerator driven system simulation”, Ann. Nucl. Energy, 114,
329-341 (2018).
• Logan Abel, William Boyd, Benoit Forget, and Kord Smith, “Interactive Visualization of Multi-Group Cross
Sections on High-Fidelity Spatial Meshes,” Trans. Am. Nucl. Soc., 114, 391-394 (2016).
864 Chapter 9. Publications

• Derek M. Lax, “Memory efficient indexing algorithm for physical properties in OpenMC,” S. M. Thesis, Mas-
sachusetts Institute of Technology (2015).
• Derek Lax, William Boyd, Nicholas Horelik, Benoit Forget, and Kord Smith, “A memory efficient algorithm
for classifying unique regions in constructive solid geometries,” Proc. PHYSOR, Kyoto, Japan, Sep. 28–Oct. 3
(2014).
9.5 Miscellaneous
• Shikhar Kumar, Benoit Forget, and Kord Smith, “Stationarity Diagnostic using Functional Expansion Tallies”,
Ann. Nucl. Energy, 143, 107388 (2020).
• T. Eade, B. Colling, J. Naish, L. W. Packer, and A. Valentine, “Shutdown dose rate benchmarking using modern
particle transport codes, Nucl. Fusion, 60, 056024 (2020).
• Jiankai Yu, Qiudong Wang, Ding She, and Benoit Forget, “Modelling of the HTR-PM Pebble-bed Reactor using
OpenMC”, Trans. Am. Nucl. Soc., 122, 643-646 (2020).
• Sharif Abu Darda, Abdelfattah Y. Soliman, Mohammed S. Aljohani, and Ned Xoubi, “Technical feasibility study
of BAEC TRIGA reactor (BTRR) as a neutron source for BNCT using OpenMC Monte Carlo code”, Prog. Nucl.
Energy, 126, 103418 (2020).
• Stefano Segantin, Raffaella Testoni, and Massimo Zucchetti, “ARC reactor – Neutron irradiation analysis”, Fus.
Eng. Design, 159, 111792 (2020).
• Muhammad Ilham, Helen Raflis, and Zaki Suud, “Full Core Optimization of Small Modular Gas-Cooled Fast
Reactors Using OpenMC Program Code”, J. Phys.: Conf. Series, 1493, 012007 (2020).
• Ned Xoubi, Sharif Abu Darda, Abdelfattah Y. Soliman, and Tareq Abulfaraj, “An investigative study of enrich-
ment reduction impact on the neutron flux in the in-core flux-trap facility of MTR research reactors”, Nucl. Eng.
Technol., 52, 469-476 (2020).
• J. Rolando Granada, J. Ignacio Marquez Damian, and Christian Helman, “Studies on Reflector Materials for
Cold Neutrons, Eur. Phys. J. Web Conf., 231, 04002 (2020).
• Govatsa Acharya, “Investigating the Application of Self-Actuated Passive Shutdown System in a Small Lead-
Cooled Reactor,” M.S. Thesis, KTH Royal Institute of Technology (2019).
• Ilham Variansyah, Benjamin R. Betzler, and William R. Martin, “𝛼-weighted transition rate matrix method”,
Proc. M&C, 1368-1377, Portland, Oregon, Aug. 25-29 (2019).
• Shikhar Kumar, Benoit Forget, and Kord Smith, “Analysis of fission source convergence for a 3-D SMR core
using functional expansion tallies,” Proc. M&C, 937-947, Portland, Oregon, Aug. 25-29 (2019).
• Faisal Qayyum, Muhammad R. Ali, Awais Zahur, and R. Khan, “Improvements in methodology to determine
feedback reactivity coefficients,” Nucl. Sci. Tech., 30: 63 (2019).
• M. Sajjad, Muhammad Rizwan Ali, M. Naveed Ashraf, Rustam Khan, Tasneem Fatima, “KANUPP Reactor
Core Model and its Validation,” International Conference on Power Generation Systems and Renewable Energy
Technologies, Islamabad, Pakistan, Sep. 10-12 (2018).
• Muhammad Waqas Tariq, Muhammad Sohail, and Sikander Majid Mirza, “Calculation of Neutronic Parameters
using OpenMC for Potential Dispersed Fuels of MNSR,” International Conference on Power Generation Systems
and Renewable Energy Technologies, Islamabad, Pakistan, Sep. 10-12 (2018).
• Amanda L. Lund and Paul K. Romano, “Implementation and Validation of Photon Transport in OpenMC”,
Argonne National Laboratory, Technical Report ANL/MCS-TM-381 (2018).
• Bruno Merk, Dzianis Litskevich, R. Gregg, and A. R. Mount, “Demand driven salt clean-up in a molten salt fast
reactor – Defining a priority list”, PLOS One, 13, e0192020 (2018).
9.5. Miscellaneous 865

• Adam G. Nelson, Samuel Shaner, William Boyd, and Paul K. Romano, “Incorporation of a Multigroup Transport
Capability in the OpenMC Monte Carlo Particle Transport Code,” Trans. Am. Nucl. Soc., 117, 679-681 (2017).
• Youqi Zheng, Yunlong Xiao, and Hongchun Wu, “Application of the virtual density theory in fast reactor analysis
based on the neutron transport calculation,” Nucl. Eng. Des., 320, 200-206 (2017).
• Amanda L. Lund, Paul K. Romano, and Andrew R. Siegel, “Accelerating Source Convergence in Monte Carlo
Criticality Calculations Using a Particle Ramp-Up Technique,” Proc. Int. Conf. Mathematics & Computational
Methods Applied to Nuclear Science and Engineering, Jeju, Korea, Apr. 16-20, 2017.
• Antonios G. Mylonakis, M. Varvayanni, D.G.E. Grigoriadis, and N. Catsaros, “Developing and investigating a
pure Monte-Carlo module for transient neutron transport analysis,” Ann. Nucl. Energy, 104, 103-112 (2017).
• Timothy P. Burke, Brian C. Kiedrowski, William R. Martin, and Forrest B. Brown, “GPU Acceleration of Kernel
Density Estimators in Monte Carlo Neutron Transport Simulations,” Trans. Am. Nucl. Soc., 115, 531-534 (2016).
• Timothy P. Burke, Brian C. Kiedrowski, and William R. Martin, “Cylindrical Kernel Density Estimators for
Monte Carlo Neutron Transport Reactor Physics Problems,” Trans. Am. Nucl. Soc., 115, 563-566 (2016).
• Yunzhao Li, Qingming He, Liangzhi Cao, Hongchun Wu, and Tiejun Zu, “Resonance Elastic Scattering and
Interference Effects Treatments in Subgroup Method,” Nucl. Eng. Tech., 48, 339-350 (2016).
• William Boyd, Sterling Harper, and Paul K. Romano, “Equipping OpenMC for the big data era,” Proc. PHYSOR,
Sun Valley, Idaho, May 1-5, 2016.
• Michal Kostal, Vojtech Rypar, Jan Milcak, Vlastimil Juricek, Evzen Losa, Benoit Forget, and Sterling Harper,
“Study of graphite reactivity worth on well-defined cores assembled on LR-0 reactor,” Ann. Nucl. Energy, 87,
601-611 (2016).
• Qicang Shen, William Boyd, Benoit Forget, and Kord Smith, “Tally precision triggers for the OpenMC Monte
Carlo code,” Trans. Am. Nucl. Soc., 112, 637-640 (2015).
• Kyungkwan Noh and Deokjung Lee, “Whole Core Analysis using OpenMC Monte Carlo Code,” Trans. Kor.
Nucl. Soc. Autumn Meeting, Gyeongju, Korea, Oct. 24-25, 2013.
• Timothy P. Burke, Brian C. Kiedrowski, and William R. Martin, “Flux and Reaction Rate Kernel Density Esti-
mators in OpenMC,” Trans. Am. Nucl. Soc., 109, 683-686 (2013).
9.6 Multigroup Cross Section Generation
• Ilham Variansyah, Benjamin R. Betzler, and William R. Martin, “Multigroup Constant Calculation with Static
𝛼-Eigenvalue Monte Carlo for Time-Dependent Neutron Transport Simulation”, Nucl. Sci. Eng., 2020.
• Chenghui Wan, Tianliang Hu, and Liangzhi Cao, “Multi-physics numerical analysis of the fuel-addition tran-
sients in the liquid-fuel molten salt reactor”, Ann. Nucl. Energy, 144, 107514 (2020).
• William Boyd, Adam Nelson, Paul K. Romano, Samuel Shaner, Benoit Forget, and Kord Smith, “Multigroup
Cross-Section Generation with the OpenMC Monte Carlo Particle Transport Code,” Nucl. Technol., 205, 928-
944 (2019).
• William Boyd, Benoit Forget, and Kord Smith, “A single-step framework to generate spatially self-shielded
multi-group cross sections from Monte Carlo transport simulations,” Ann. Nucl. Energy, 125, 261-271 (2019).
• Kun Zhuang, Xiaobin Tang, and Liangzhi Cao, “Development and verification of a model for generation of
MSFR few-group homogenized cross-sections based on a Monte Carlo code OpenMC,” Ann. Nucl. Energy,
124, 187-197 (2019).
• Changho Lee and Yeon Sang Jung, “Verification of the Cross Section Library Generated Using OpenMC and
MC2 -3 for PROTEUS,” Proc. PHYSOR, Cancun, Mexico, Apr. 22-26 (2018).

• Zhaoyuan Liu, Kord Smith, Benoit Forget, and Javier Ortensi, “Cumulative migration method for computing
rigorous diffusion coefficients and transport cross sections from Monte Carlo,” Ann. Nucl. Energy, 112, 507-
516 (2018).
• Gang Yang, Tongkyu Park, and Won Sik Yang, “Effects of Fuel Salt Velocity Field on Neutronics Performances
in Molten Salt Reactors with Open Flow Channels,” Trans. Am. Nucl. Soc., 117, 1339-1342 (2017).
• William Boyd, Nathan Gibson, Benoit Forget, and Kord Smith, “An analysis of condensation errors in multi-
group cross section generation for fine-mesh neutron transport calculations,” Ann. Nucl. Energy, 112, 267-276
(2018).
• Hong Shuang, Yang Yongwei, Zhang Lu, and Gao Yucui, “Fabrication and validation of multigroup cross section
library based on the OpenMC code,” Nucl. Techniques 40 (4), 040504 (2017). (in Mandarin)
• Nicholas E. Stauff, Changho Lee, Paul K. Romano, and Taek K. Kim, “Verification of Mixed Stochas-
tic/Deterministic Approach for Fast and Thermal Reactor Analysis,” Proc. ICAPP, Fukui and Kyoto, Japan,
Apr. 24-28, 2017.
• Zhauyuan Liu, Kord Smith, and Benoit Forget, “Progress of Cumulative Migration Method for Computing Dif-
fusion Coefficients with OpenMC,” Proc. Int. Conf. Mathematics & Computational Methods Applied to Nuclear
Science and Engineering, Jeju, Korea, Apr. 16-20, 2017.
• Geoffrey Gunow, Samuel Shaner, William Boyd, Benoit Forget, and Kord Smith, “Accuracy and Performance of
3D MOC for Full-Core PWR Problems,” Proc. Int. Conf. Mathematics & Computational Methods Applied to
Nuclear Science and Engineering, Jeju, Korea, Apr. 16-20, 2017.
• Tianliang Hu, Liangzhi Cao, Hongchun Wu, and Kun Zhuang, “A coupled neutronics and thermal-hydraulic
modeling approach to the steady-state and dynamic behavior of MSRs,” Proc. Int. Conf. Mathematics & Com-
putational Methods Applied to Nuclear Science and Engineering, Jeju, Korea, Apr. 16-20, 2017.
• William R. D. Boyd, “Reactor Agnostic Multi-Group Cross Section Generation for Fine-Mesh Deterministic
Neutron Transport Simulations,” Ph.D. Thesis, Massachusetts Institute of Technology (2017).
• Zhaoyuan Liu, Kord Smith, and Benoit Forget, “A Cumulative Migration Method for Computing Rigorous Trans-
port Cross Sections and Diffusion Coefficients for LWR Lattices with Monte Carlo,” Proc. PHYSOR, Sun Valley,
Idaho, May 1-5, 2016.
• Adam G. Nelson and William R. Martin, “Improved Monte Carlo tallying of multi-group scattering moments
using the NDPP code,” Trans. Am. Nucl. Soc., 113, 645-648 (2015)
• Adam G. Nelson and William R. Martin, “Improved Monte Carlo tallying of multi-group scattering moment
matrices,” Trans. Am. Nucl. Soc., 110, 217-220 (2014).
• Adam G. Nelson and William R. Martin, “Improved Convergence of Monte Carlo Generated Multi-Group Scat-
tering Moments,” Proc. Int. Conf. Mathematics and Computational Methods Applied to Nuclear Science and
Engineering, Sun Valley, Idaho, May 5–9 (2013).
9.7 Doppler Broadening
• Jonathan A. Walsh, Benoit Forget, Kord S. Smith, and Forrest B. Brown, “On-the-fly Doppler broadening of
unresolved resonance region cross sections,” Prog. Nucl. Energy, 101, 444-460 (2017).
• Colin Josey, Pablo Ducru, Benoit Forget, and Kord Smith, “Windowed multipole for cross section Doppler broad-
ening,” J. Comput. Phys., 307, 715-727 (2016).
• Jonathan A. Walsh, Benoit Forget, Kord S. Smith, and Forrest B. Brown, “On-the-fly Doppler Broadening of
Unresolved Resonance Region Cross Sections via Probability Band Interpolation,” Proc. PHYSOR, Sun Valley,
Idaho, May 1-5, 2016.
9.7. Doppler Broadening 867

• Jonathan A. Walsh, Benoit Forget, Kord S. Smith, Brian C. Kiedrowski, and Forrest B. Brown, “Direct, on-the-
fly calculation of unresolved resonance region cross sections in Monte Carlo simulations,” Proc. Joint Int. Conf.
M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23 (2015).
• Colin Josey, Benoit Forget, and Kord Smith, “Windowed multipole sensitivity to target accuracy of the optimiza-
tion procedure,” J. Nucl. Sci. Technol., 52, 987-992 (2015).
• Paul K. Romano and Timothy H. Trumbull, “Comparison of algorithms for Doppler broadening pointwise tab-
ulated cross sections,” Ann. Nucl. Energy, 75, 358–364 (2015).
• Tuomas Viitanen, Jaakko Leppanen, and Benoit Forget, “Target motion sampling temperature treatment tech-
nique with track-length esimators in OpenMC – Preliminary results,” Proc. PHYSOR, Kyoto, Japan, Sep. 28–Oct.
3 (2014).
• Benoit Forget, Sheng Xu, and Kord Smith, “Direct Doppler broadening in Monte Carlo simulations using the
multipole representation,” Ann. Nucl. Energy, 64, 78–85 (2014).
9.8 Nuclear Data
• Jonathan A. Walsh, “Comparison of Unresolved Resonance Region Cross Section Formalisms in Transport Sim-
ulations,” Trans. Am. Nucl. Soc., 117, 749-752 (2017).
• Jonathan A. Walsh, Benoit Forget, Kord S. Smith, and Forrest B. Brown, “Uncertainty in Fast Reactor-Relevant
Critical Benchmark Simulations Due to Unresolved Resonance Structure,” Proc. Int. Conf. Mathematics &
Computational Methods Applied to Nuclear Science and Engineering, Jeju, Korea, Apr. 16-20, 2017.
• Vivian Y. Tran, Jonathan A. Walsh, and Benoit Forget, “Treatments for Neutron Resonance Elastic Scattering
Using the Multipole Formalism in Monte Carlo Codes,” Trans. Am. Nucl. Soc., 115, 1133-1137 (2016).
• Paul K. Romano and Sterling M. Harper, “Nuclear data processing capabilities in OpenMC”, Proc. Nuclear
Data, Sep. 11-16, 2016.
• Jonathan A. Walsh, Benoit Froget, Kord S. Smith, and Forrest B. Brown, “Neutron Cross Section Processing
Methods for Improved Integral Benchmarking of Unresolved Resonance Region Evaluations,” Eur. Phys. J.
Web Conf. 111, 06001 (2016).
• Jonathan A. Walsh, Paul K. Romano, Benoit Forget, and Kord S. Smith, “Optimizations of the energy grid search
algorithm in continuous-energy Monte Carlo particle transport codes”, Comput. Phys. Commun., 196, 134-142
(2015).
• Amanda L. Lund, Andrew R. Siegel, Benoit Forget, Colin Josey, and Paul K. Romano, “Using fractional cas-
cading to accelerate cross section lookups in Monte Carlo particle transport calculations,” Proc. Joint Int. Conf.
M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23 (2015).
• Ronald O. Rahaman, Andrew R. Siegel, and Paul K. Romano, “Monte Carlo performance analysis for varying
cross section parameter regimes,” Proc. Joint Int. Conf. M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23
(2015).
• Jonathan A. Walsh, Benoit Forget, and Kord S. Smith, “Accelerated sampling of the free gas resonance elastic
scattering kernel,” Ann. Nucl. Energy, 69, 116–124 (2014).

9.9 Parallelism
• Paul K. Romano and Andrew R. Siegel, “Limits on the efficiency of event-based algorithms for Monte Carlo
neutron transport,” Proc. Int. Conf. Mathematics & Computational Methods Applied to Nuclear Science and
Engineering, Jeju, Korea, Apr. 16-20, 2017.
• Paul K. Romano, John R. Tramm, and Andrew R. Siegel, “Efficacy of hardware threading for Monte Carlo
particle transport calculations on multi- and many-core systems,” PHYSOR 2016, Sun Valley, Idaho, May 1-5,
2016.
• David Ozog, Allen D. Malony, and Andrew R. Siegel, “A performance analysis of SIMD algorithms for Monte
Carlo simulations of nuclear reactor cores,” Proc. IEEE Int. Parallel and Distributed Processing Symposium,
Hyderabad, India, May 25–29 (2015).
• David Ozog, Allen D. Malony, and Andrew Siegel, “Full-core PWR transport simulations on Xeon Phi clusters,”
Proc. Joint Int. Conf. M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23 (2015).
• Paul K. Romano, Andrew R. Siegel, and Ronald O. Rahaman, “Influence of the memory subsystem on Monte
Carlo code performance,” Proc. Joint Int. Conf. M&C+SNA+MC, Nashville, Tennessee, Apr. 19–23 (2015).
• Hajime Fujita, Nan Dun, Aiman Fang, Zachary A. Rubinstein, Ziming Zheng, Kamil Iskra, Jeff Hammond,
Anshu Dubey, Pavan Balaji, and Andrew A. Chien, “Using Global View Resilience (GVR) to add Resilience to
Exascale Applications,” Proc. Supercomputing, New Orleans, Louisiana, Nov. 16–21, 2014.
• Nicholas Horelik, Benoit Forget, Kord Smith, and Andrew Siegel, “Domain decomposition and terabyte tallies
with the OpenMC Monte Carlo neutron transport code,” Proc. PHYSOR, Kyoto Japan, Sep. 28–Oct. 3 (2014).
• John R. Tramm, Andrew R. Siegel, Tanzima Islam, and Martin Schulz, “XSBench – the development and ver-
ification of a performance abstraction for Monte Carlo reactor analysis,” Proc. PHYSOR, Kyoto, Japan, Sep
28–Oct. 3, 2014.
• Nicholas Horelik, Andrew Siegel, Benoit Forget, and Kord Smith, “Monte Carlo domain decomposition for
robust nuclear reactor analysis,” Parallel Comput., 40, 646–660 (2014).
• Andrew Siegel, Kord Smith, Kyle Felker, Paul Romano, Benoit Forget, and Peter Beckman, “Improved cache
performance in Monte Carlo transport calculations using energy banding,” Comput. Phys. Commun., 185 (4),
1195–1199 (2014).
• Paul K. Romano, Benoit Forget, Kord Smith, and Andrew Siegel, “On the use of tally servers in Monte Carlo
simulations of light-water reactors,” Proc. Joint International Conference on Supercomputing in Nuclear Appli-
cations and Monte Carlo, Paris, France, Oct. 27–31 (2013).
• Kyle G. Felker, Andrew R. Siegel, Kord S. Smith, Paul K. Romano, and Benoit Forget, “The energy band memory
server algorithm for parallel Monte Carlo calculations,” Proc. Joint International Conference on Supercomputing
in Nuclear Applications and Monte Carlo, Paris, France, Oct. 27–31 (2013).
• John R. Tramm and Andrew R. Siegel, “Memory Bottlenecks and Memory Contention in Multi-Core Monte
Carlo Transport Codes,” Proc. Joint International Conference on Supercomputing in Nuclear Applications and
Monte Carlo, Paris, France, Oct. 27–31 (2013).
• Andrew R. Siegel, Kord Smith, Paul K. Romano, Benoit Forget, and Kyle Felker, “Multi-core performance studies
of a Monte Carlo neutron transport code,” Int. J. High Perform. Comput. Appl., 28 (1), 87–96 (2014).
• Paul K. Romano, Andrew R. Siegel, Benoit Forget, and Kord Smith, “Data decomposition of Monte Carlo particle
transport simulations via tally servers,” J. Comput. Phys., 252, 20–36 (2013).
• Andrew R. Siegel, Kord Smith, Paul K. Romano, Benoit Forget, and Kyle Felker, “The effect of load imbalances
on the performance of Monte Carlo codes in LWR analysis,” J. Comput. Phys., 235, 901–911 (2013).
• Paul K. Romano and Benoit Forget, “Reducing Parallel Communication in Monte Carlo Simulations via Batch
Statistics,” Trans. Am. Nucl. Soc., 107, 519–522 (2012).
9.9. Parallelism 869

• Paul K. Romano and Benoit Forget, “Parallel Fission Bank Algorithms in Monte Carlo Criticality Calculations,”
Nucl. Sci. Eng., 170, 125–135 (2012).
9.10 Depletion
• Binhang Zhang, XianBao Yuan, Yonghong Zhang, Haibo Tang, and Liangzhi Cao, “Development of a versatile
depletion code AMAC”, Ann. Nucl. Energy, 143, 107446 (2020).
• Zelong Zhao, Yongwei Yang, and Qingyu Gao, “Development and verification of code IMPC-Depletion for
nuclide depletion calculation”, Nucl. Eng. Des., 363, 110616 (2020).
• Kun Zhuang, Ting Li, Qian Zhang, Qinghua He, and Tengfei Zhang, “Extended development of a Monte Carlo
code OpenMC for fuel cycle simulation of molten salt reactor”, Prog. Nucl. Energy, 118, 103115 (2020).
• Jose L. Salcedo-Perez, Benoit Forget, Kord Smith, and Paul Romano, “Hybrid tallies to improve performance in
depletion Monte Carlo simulations,” Proc. M&C, 927-936, Portland, Oregon, Aug. 25-29 (2019).
• Zhao-Qing Liu, Ze-Long Zhao, Yong-Wei Yang, Yu-Cui Gao, Hai-Yan Meng, and Qing-Yu Gao, “Development
and validation of depletion code system IMPC-Burnup for ADS,” Nucl. Sci. Tech., 30: 44 (2019).
• Colin Josey, Benoit Forget, and Kord Smith, “High order methods for the integration of the Bateman equations
and other problems of the form of y’ = F(y,t)y,” J. Comput. Phys., 350, 296-313 (2017).
• Matthew S. Ellis, Colin Josey, Benoit Forget, and Kord Smith, “Spatially Continuous Depletion Algorithm for
Monte Carlo Simulations,” Trans. Am. Nucl. Soc., 115, 1221-1224 (2016).
• Anas Gul, K. S. Chaudri, R. Khan, and M. Azeen, “Development and verification of LOOP: A Linkage of
ORIGEN2.2 and OpenMC,” Ann. Nucl. Energy, 99, 321–327 (2017).
• Kai Huang, Hongchun Wu, Yunzhao Li, and Liangzhi Cao, “Generalized depletion chain simplification based
of significance analysis,” Proc. PHYSOR, Sun Valley, Idaho, May 1-5, 2016.
9.11 Sensitivity Analysis
• Abdulla Alhajri and Benoit Forget, “Eigenvalue Sensitivity in Monte Carlo Simulations to Nuclear Data Param-
eters using the Multipole Formalism,” Proc. M&C, 1895-1906, Portland, Oregon, Aug. 25-29 (2019).
• Xingjie Peng, Jingang Liang, Benoit Forget, and Kord Smith, “Calculation of adjoint-weighted reactor kinetics
parameters in OpenMC”, Ann. Nucl. Energy, 128, 231-235 (2019).
• Zeyun Wu, Jingang Liang, Xingjie Peng, and Hany S. Abdel-Khalik, “GPT-Free Sensitivity Analysis for Monte
Carlo Models”, Nucl. Technol. (2019).
• Xingjie Peng, Jingang Liang, Abdulla Alhajri, Benoit Forget, and Kord Smith, “Development of continuous-
energy sensitivity analysis capability in OpenMC”, Ann. Nucl. Energy, 110, 362-383 (2017).

CHAPTER
TEN
LICENSE AGREEMENT
Copyright © 2011-2022 Massachusetts Institute of Technology, UChicago Argonne LLC, and OpenMC contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documen-
tation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR-
TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT-
WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
871
872 Chapter 10. License Agreement

BIBLIOGRAPHY
[Gelbard] Ely M. Gelbard, “Epithermal Scattering in VIM,” FRA-TM-123, Argonne National Laboratory (1979).
[Squires] G. L. Squires, Introduction to the Theory of Thermal Neutron Scattering, Cambridge University Press
(1978).
[Williams] M. M. R. Williams, The Slowing Down and Thermalization of Neutrons, North-Holland Publishing Co.,
Amsterdam (1966). Note: This book can be obtained for free from the OECD.
[Lieberoth] J. Lieberoth, “A Monte Carlo Technique to Solve the Static Eigenvalue Problem of the Boltzmann Trans-
port Equation,” Nukleonik, 11, 213-219 (1968).
[Romano] Paul K. Romano, “Application of the Stochastic Oscillator to Assess Source Convergence in Monte Carlo
Criticality Calculations,” Proc. International Conference on Mathematics, Computational Methods, and
Reactor Physics, Saratoga Springs, New York (2009).
[Sutton] Daniel J. Kelly, Thomas M. Sutton, and Stephen C. Wilson, “MC21 Analysis of the Nuclear Energy
Agency Monte Carlo Performance Benchmark Problem,” Proc. PHYSOR 2012, Knoxville, Tennessee,
Apr. 15–20 (2012).
[Ueki] Taro Ueki, “On-the-Fly Judgments of Monte Carlo Fission Source Convergence,” Trans. Am. Nucl. Soc.,
98, 512 (2008).
[Mack97] Abdou, M.A., Maynard, C.W., and Wright, R.Q. MACK: computer program to calculate neutron en-
ergy release parameters (fluence-to-kerma factors) and multigroup neutron reaction cross sections from
nuclear data in ENDF Format. Oak Ridge National Laboratory report ORNL-TM-3994.
[Troubetzkoy] E. Troubetzkoy, H. Steinberg, and M. Kalos, “Monte Carlo Radiation Penetration Calculations on a
Parallel Computer,” Trans. Am. Nucl. Soc., 17, 260 (1973).
[BEAVRS] Nick Horelik, Bryan Herman. Benchmark for Evaluation And Verification of Reactor Simulations. Mas-
sachusetts Institute of Technology, https://crpg.mit.edu/research/beavrs , 2013.
[Gill] Daniel F. Gill. Newton-Krylov methods for the solution of the k-eigenvalue problem in multigroup neu-
tronics calculations. Ph.D. thesis, Pennsylvania State University, 2010.
[Hebert] Alain Hebert. Applied reactor physics. Presses Internationales Polytechnique, Montreal, 2009.
[Herman] Bryan R. Herman, Benoit Forget, Kord Smith, and Brian N. Aviles. Improved diffusion coefficients gen-
erated from Monte Carlo codes. In Proceedings of M&C 2013, Sun Valley, ID, USA, May 5 - 9, 2013.
[HermanThesis] Bryan R. Herman. Monte Carlo and Thermal Hydraulic Coupling using Low-Order Nonlinear Dif-
fusion Acceleration. Sc.D. thesis, Massachusetts Institute of Technology, 2014.
[Knoll] D.A. Knoll, H. Park, and C. Newman. Acceleration of k-eigenvalue/criticality calculations using the
Jacobian-free Newton-Krylov method. Nuclear Science and Engineering, 167:133–140, 2011.
873
[Park] H. Park, D.A. Knoll, and C.K. Newman. Nonlinear acceleration of transport criticality problems. Nuclear
Science and Engineering, 172:52–65, 2012.
[Rhodes] Joel Rhodes and Malte Edenius. CASMO-4 — A Fuel Assembly Burnup Program. User’s Manual.
Studsvik of America, ssp-09/443-u rev 0, proprietary edition, 2001.
[Smith] Kord S Smith and Joel D Rhodes III. Full-core, 2-D, LWR core calculations with CASMO-4E. In Pro-
ceedings of PHYSOR 2002, Seoul, Korea, October 7 - 10, 2002.
[SAR1990] Sartori, E., OECD/NEA Data Bank: Standard Energy Group Structures of Cross Section Libraries for
Reactor Shielding, Reactor Cell and Fusion Neutronics Applications: VITAMIN-J, ECCO-33, ECCO-
2000 and XMAS JEF/DOC-315 Revision 3 - DRAFT (December 11, 1990).
[SAN2004] Santamarina, A., Collignon, C., & Garat, C. (2004). French calculation schemes for light water reactor
analysis. United States: American Nuclear Society - ANS.
[HFA2005] Hfaiedh, N. & Santamarina, A., “Determination of the Optimized SHEM Mesh for Neutron Transport
Calculations,” Proc. Top. Mtg. in Mathematics & Computations, Supercomputing, Reactor Physics and
Nuclear and Biological Applications, September 12-15, Avignon, France, 2005.
[SAN2007] Santamarina, A. & Hfaiedh, N. (2007). The SHEM energy mesh for accurate fuel depletion and BUC
calculations. Proceedings of the International Conference on Safety Criticality ICNC 2007, St Peterburg
(Russia), Vol. I pp. 446-452.
[HEB2008] Hébert, Alain & Santamarina, Alain. (2008). Refinement of the Santamarina-Hfaiedh energy mesh be-
tween 22.5 eV and 11.4 keV. International Conference on the Physics of Reactors 2008, PHYSOR 08. 2.
929-938.
[ZAL1999] K. Záleský and L. Marková (1999), Assessment of Nuclear Data Needs for Broad-Group SCALE Library
Related to VVER Spent Fuel Applications, IAEA.
874 Bibliography
PYTHON MODULE INDEX
o
openmc.data, 699
openmc.deplete, 361
openmc.lib, 769
875

OpenMC 0.13.1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OpenMC 0.13.1

Uploaded by

Copyright:

Available Formats

OpenMC Documentation

Aug 19, 2022

1 Quick Install Guide 3

3 Theory and Methodology 43

4 User’s Guide 125

5 Developer’s Guide 185

6 Python API 195

7 C/C++ API 785

8 File Format Specifications 801

10 License Agreement 871

Python Module Index 875

Recommended publication for citing

QUICK INSTALL GUIDE

1.1 Installing on Linux/Mac with Mamba and conda-forge

conda config --add channels conda-forge

conda create -n openmc-env

Then install mamba, which will be used to install OpenMC.

conda install mamba

mamba search openmc

OpenMC can then be installed with:

mamba install openmc

1.2 Installing on Linux/Mac/Windows with Docker

docker run openmc/openmc:latest

1.3 Installing from Source using Spack

spack install py-openmc

1.4 Installing from Source on Ubuntu

sudo apt install g++ cmake libhdf5-dev libpng-dev

1.5 Installing from Source on Linux or Mac OS X

git clone --recurse-submodules https://github.com/openmc-dev/openmc.git

4 Chapter 1. Quick Install Guide

1.5. Installing from Source on Linux or Mac OS X 5

6 Chapter 1. Quick Install Guide

2.1 What’s New in 0.13.1

2.1.2 Compatibility Notes and Deprecations

• The openmc.deplete.Operator class has been renamed openmc.deplete.CoupledOperator.

Old option New option

2.1.3 New Features

• Two new composite surfaces: openmc.model.IsogonalOctagon and openmc.model.CylinderSector.

8 Chapter 2. Release Notes

2.1.4 Bug Fixes

• Fix bug when a rotation matrix is passed to Halfspace.rotate

2.1. What’s New in 0.13.1 9

2.2 What’s New in 0.13.0

10 Chapter 2. Release Notes

2.2.2 New Features

2.2.3 Bug Fixes

• Fix for shared fission bank memory errors

2.2. What’s New in 0.13.0 11

2.3 What’s New in 0.12.2

2.3.2 New Features

Three tally-related enhancements were added to the code in this release:

12 Chapter 2. Release Notes

2.3.3 Bug Fixes

• Reset particle coordinates during find cell operation

This release contains new contributions from the following people:

2.4 What’s New in 0.12.1

2.4. What’s New in 0.12.1 13

2.4.2 New Features

2.4.3 Bug Fixes

• Proper detection of MPI wrappers

14 Chapter 2. Release Notes

• Examine if region exists before removing redundant surfaces

This release contains new contributions from the following people: