Merge branch 'master' into cmfd_parallel

docs/source/methods/introduction.rst

@@ -4,7 +4,131 @@
 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 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:
+
+.. math::
+
+    \sigma^2 \propto \frac{1}{N}.
+
+where :math:`\sigma^2` is the variance of the sample mean and :math:`N` is the
+number of realizations.
+
+------------------------
+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. 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 ACE format cross-sections 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 fixed source problem, source sites are sampled from the specified
+    source. In a criticality problem, source sites are sampled from some initial
+    source distribution or from a source file. The source sites consist of
+    coordinates, a direction, and an energy.
+
+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 :math:`\Sigma_t`, this can be shown to be
+
+     .. math::
+
+         d = -\frac{\ln \xi}{\Sigma_t}
+
+     where :math:`\sigma` is a `pseudorandom number`_ sampled from a uniform
+     distribution on [0,1).
+
+  5. 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.
+
+  6. 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 :math:`i` is
+     :math:`\Sigma_{t,i}`, then the probability that any nuclide is sampled is
+
+     .. math::
+
+         P(i) = \frac{\Sigma_{t,i}}{\Sigma_t}
+
+  7. Once the specific nuclide is sampled, the random samples a reaction for
+     that nuclide based on the microscopic cross sections. If the microscopic
+     cross-section for some reaction :math:`x` is :math:`\sigma_x` and the total
+     microscopic cross section for the nuclide is :math:`\sigma_t`, then the
+     probability that reaction :math:`x` will occur is
+
+     .. math::
+
+         P(x) = \frac{\sigma_x}{\sigma_t}
+
+  8. If the sampled reaction is elastic or inelastic scattering, the outgoing
+     energy and angle is sampled from the appropriate distribution.  If the
+     reaction is (n,xn), it's also treated as scattering and the weight of the
+     particle is increased by the multiplicity of the reaction. The 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
+
+  - All allocatable arrays are deallocated.
+
 ---------------------
 Criticality Algorithm
 ---------------------
 
+.. _probability distributions: http://en.wikipedia.org/wiki/Probability_distribution
+.. _Monte Carlo: http://en.wikipedia.org/wiki/Monte_Carlo_method
+.. _central limit theorem: http://en.wikipedia.org/wiki/Central_limit_theorem
+.. _pseudorandom number: http://en.wikipedia.org/wiki/Pseudorandom_number_generator

docs/source/publications.rst

@@ -4,7 +4,11 @@
 Publications
 ============
 
-- Paul K. Romano and Beonit Forget, "The OpenMC Monte Carlo Particle Transport
+- Paul K. Romano and Benoit Forget, "Reducing Parallel Communication in Monte
+  Carlo Simulations via Batch Statistics," *Trans. Am. Nucl. Soc.*, Submitted
+  (2012).
+
+- Paul K. Romano and Benoit Forget, "The OpenMC Monte Carlo Particle Transport
   Code," *Annals of Nuclear Energy*, Submitted (2012).
 
 - Andrew R. Siegel, Kord Smith, Paul K. Romano, Benoit Forget, and Kyle Felker,

docs/source/usersguide/beginners.rst

@@ -22,7 +22,7 @@ quantity one is interested in) very accurately.
 Using Monte Carlo methods to determine the average behavior of various physical
 quantities in a nuclear reactor 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 in a reactor is so-called `determinstic`_
+neutrons and reactions rates in a reactor 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
@@ -138,7 +138,7 @@ and `Volume II`_. You may also find it helpful to review the following terms:
 .. _nuclear reactor: http://en.wikipedia.org/wiki/Nuclear_reactor
 .. _Monte Carlo: http://en.wikipedia.org/wiki/Monte_Carlo_method
 .. _fission: http://en.wikipedia.org/wiki/Nuclear_fission
-.. _determinstic: http://en.wikipedia.org/wiki/Deterministic_algorithm
+.. _deterministic: http://en.wikipedia.org/wiki/Deterministic_algorithm
 .. _neutron transport: http://en.wikipedia.org/wiki/Neutron_transport
 .. _discretization: http://en.wikipedia.org/wiki/Discretization
 .. _constructive solid geometry: http://en.wikipedia.org/wiki/Constructive_solid_geometry

docs/source/usersguide/input.rst

@@ -579,17 +579,16 @@ The following filters can be specified for a tally:
 
   :energy:
     A monotonically increasing list of bounding **pre-collision** energies for a
-    number of groups. For example, if the following energy filter is specified
-    as ``<energy>0.0 1.0 20.0</energy>``, 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.
+    number of groups. For example, if this filter is specified as ``<energy>0.0
+    1.0 20.0</energy>``, 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.
 
   :energyout:
     A monotonically increasing list of bounding **post-collision** energies for
-    a number of groups. For example, if the following energy filter is specified
-    as ``<energy>0.0 1.0 20.0</energy>``, 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.
+    a number of groups. For example, if this filter is specified as
+    ``<energyout>0.0 1.0 20.0</energyout>``, 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.
 
   :mesh:
     The ``id`` of a structured mesh to be tallied over.

src/physics.F90

@@ -61,6 +61,9 @@ contains
     ! Initialize number of events to zero
     n_event = 0
 
+    ! Force calculation of cross-sections by setting last energy to zero 
+    micro_xs % last_E = ZERO
+
     do while (p % alive)
 
        ! Calculate microscopic and macroscopic cross sections -- note: if the