1.. _usersguide_beginners: 2 3============================ 4A Beginner's Guide to OpenMC 5============================ 6 7-------------------- 8What does OpenMC do? 9-------------------- 10 11In a nutshell, OpenMC simulates neutral particles (presently neutrons and 12photons) moving stochastically through an arbitrarily defined model that 13represents an real-world experimental setup. The experiment could be as simple 14as a sphere of metal or as complicated as a full-scale `nuclear reactor`_. This 15is what's known as `Monte Carlo`_ simulation. In the case of a nuclear reactor 16model, neutrons are especially important because they are the particles that 17induce `fission`_ in isotopes of uranium and other elements. Knowing the 18behavior of neutrons allows one to determine how often and where fission 19occurs. The amount of energy released is then directly proportional to the 20fission reaction rate since most heat is produced by fission. By simulating 21many neutrons (millions or billions), it is possible to determine the average 22behavior of these neutrons (or the behavior of the energy produced, or any 23other quantity one is interested in) very accurately. 24 25Using Monte Carlo methods to determine the average behavior of various physical 26quantities in a system is quite different from other means of solving the same 27problem. The other class of methods for determining the behavior of neutrons and 28reactions rates is so-called `deterministic`_ methods. In these methods, the 29starting point is not randomly simulating particles but rather writing an 30equation that describes the average behavior of the particles. The equation that 31describes the average behavior of neutrons is called the `neutron transport`_ 32equation. This equation is a seven-dimensional equation (three for space, three 33for velocity, and one for time) and is very difficult to solve directly. For all 34but the simplest problems, it is necessary to make some sort of 35`discretization`_. As an example, we can divide up all space into small sections 36which are homogeneous and then solve the equation on those small sections. After 37these discretizations and various approximations, one can arrive at forms that 38are suitable for solution on a computer. Among these are discrete ordinates, 39method of characteristics, finite-difference diffusion, and nodal methods. 40 41So why choose Monte Carlo over deterministic methods? Each method has its pros 42and cons. Let us first take a look at few of the salient pros and cons of 43deterministic methods: 44 45- **Pro**: Depending on what method is used, solution can be determined very 46 quickly. 47 48- **Pro**: The solution is a global solution, i.e. we know the average behavior 49 everywhere. 50 51- **Pro**: Once the problem is converged, the solution is known. 52 53- **Con**: If the model is complex, it is necessary to do sophisticated mesh 54 generation. 55 56- **Con**: It is necessary to generate multi-group cross sections which requires 57 knowing the solution *a priori*. 58 59Now let's look at the pros and cons of Monte Carlo methods: 60 61- **Pro**: No mesh generation is required to build geometry. By using 62 `constructive solid geometry`_, it's possible to build complex 63 models with curved surfaces. 64 65- **Pro**: Monte Carlo methods can be used with either continuous-energy or 66 multi-group cross sections. 67 68- **Pro**: Running simulations in parallel is conceptually very simple. 69 70- **Con**: Because they rely on repeated random sampling, they are 71 computationally very expensive. 72 73- **Con**: A simulation doesn't automatically give you the global solution 74 everywhere -- you have to specifically ask for those quantities you want. 75 76- **Con**: Even after the problem is converged, it is necessary to simulate 77 many particles to reduce stochastic uncertainty. 78 79Because fewer approximations are made in solving a problem by the Monte Carlo 80method, it is often seen as a "gold standard" which can be used as a benchmark 81for a solution of the same problem by deterministic means. However, it comes at 82the expense of a potentially longer simulation. 83 84----------------- 85How does it work? 86----------------- 87 88In order to do anything, the code first needs to have a model of some problem of 89interest. This could be a nuclear reactor or any other physical system with 90fissioning material. You, as the code user, will need to describe the model so 91that the code can do something with it. A basic model consists of a few things: 92 93- A description of the geometry -- the problem must be split up into regions of 94 homogeneous material composition. 95- For each different material in the problem, a description of what nuclides are 96 in the material and at what density. 97- Various parameters telling the code how many particles to simulate and what 98 options to use. 99- A list of different physical quantities that the code should return at the end 100 of the simulation. In a Monte Carlo simulation, if you don't ask for anything, 101 it will not give you any answers (other than a few default quantities). 102 103----------------------- 104What do I need to know? 105----------------------- 106 107If you are starting to work with OpenMC, there are a few things you should be 108familiar with. Whether you plan on working in Linux, macOS, or Windows, you 109should be comfortable working in a command line environment. There are many 110resources online for learning command line environments. If you are using Linux 111or Mac OS X (also Unix-derived), `this tutorial 112<http://www.ee.surrey.ac.uk/Teaching/Unix/>`_ will help you get acquainted with 113commonly-used commands. 114 115To reap the full benefits of OpenMC, you should also have basic proficiency in 116the use of `Python <https://www.python.org/>`_, as OpenMC includes a rich Python 117API that offers many usability improvements over dealing with raw XML input 118files. 119 120OpenMC uses a version control software called `git`_ to keep track of changes to 121the code, document bugs and issues, and other development tasks. While you don't 122necessarily have to have git installed in order to download and run OpenMC, it 123makes it much easier to receive updates if you do have it installed and have a 124basic understanding of how it works. There are a list of good `git tutorials`_ 125at the git documentation website. The `OpenMC source code`_ and documentation 126are hosted at `GitHub`_. In order to receive updates to the code directly, 127submit `bug reports`_, and perform other development tasks, you may want to sign 128up for a free account on GitHub. Once you have an account, you can follow `these 129instructions 130<https://docs.github.com/en/github/getting-started-with-github/set-up-git>`_ on 131how to set up your computer for using GitHub. 132 133If you are new to nuclear engineering, you may want to review the NRC's `Reactor 134Concepts Manual`_. This manual describes the basics of nuclear power for 135electricity generation, the fission process, and the overall systems in a 136pressurized or boiling water reactor. Another resource that is a bit more 137technical than the Reactor Concepts Manual but still at an elementary level is 138the DOE Fundamentals Handbook on Nuclear Physics and Reactor Theory `Volume I`_ 139and `Volume II`_. You may also find it helpful to review the following terms: 140 141- `Neutron cross section`_ 142- `Effective multiplication factor`_ 143- `Flux`_ 144 145.. _nuclear reactor: https://en.wikipedia.org/wiki/Nuclear_reactor 146.. _Monte Carlo: https://en.wikipedia.org/wiki/Monte_Carlo_method 147.. _fission: https://en.wikipedia.org/wiki/Nuclear_fission 148.. _deterministic: https://en.wikipedia.org/wiki/Deterministic_algorithm 149.. _neutron transport: https://en.wikipedia.org/wiki/Neutron_transport 150.. _discretization: https://en.wikipedia.org/wiki/Discretization 151.. _constructive solid geometry: https://en.wikipedia.org/wiki/Constructive_solid_geometry 152.. _git: http://git-scm.com/ 153.. _git tutorials: https://git-scm.com/doc 154.. _Reactor Concepts Manual: http://www.tayloredge.com/periodic/trivia/ReactorConcepts.pdf 155.. _Volume I: https://www.standards.doe.gov/standards-documents/1000/1019-bhdbk-1993-v1 156.. _Volume II: https://www.standards.doe.gov/standards-documents/1000/1019-bhdbk-1993-v2 157.. _OpenMC source code: https://github.com/openmc-dev/openmc 158.. _GitHub: https://github.com/ 159.. _bug reports: https://github.com/openmc-dev/openmc/issues 160.. _Neutron cross section: https://en.wikipedia.org/wiki/Neutron_cross_section 161.. _Effective multiplication factor: https://en.wikipedia.org/wiki/Nuclear_chain_reaction#Effective_neutron_multiplication_factor 162.. _Flux: https://en.wikipedia.org/wiki/Neutron_flux 163