Merge pull request #2 from openmc-dev/develop

Update alongside openmc-dev

docs/source/devguide/styleguide.rst

@@ -12,6 +12,14 @@ adding new code in OpenMC.
 C++
 ---
 
+.. important:: To ensure consistent styling with little effort, this project
+    uses `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_. The
+    repository contains a ``.clang-format`` file that can be used to
+    automatically apply the style rules that are described below. The easiest
+    way to use clang-format is through a plugin/extension for your editor/IDE
+    that automatically runs clang-format using the ``.clang-format`` file
+    whenever a file is saved.
+
 Indentation
 -----------
 

docs/source/io_formats/settings.rst

@@ -142,7 +142,7 @@ materials in the problem and is specified using a :ref:`mesh_element`.
 ----------------------------
 
 Determines whether to use event-based parallelism instead of the default
-history-based parallelism. 
+history-based parallelism.
 
   *Default*: false
 
@@ -459,6 +459,15 @@ attributes/sub-elements:
 
     *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 only
+    requirement is that there is a function called ``sample_source()``. More
+    documentation on how to build sources can be found in :ref:`custom_source`.
+
+    *Default*: None
+
   :space:
     An element specifying the spatial distribution of source sites. This element
     has the following attributes:
@@ -591,6 +600,67 @@ attributes/sub-elements:
 
     *Default*: false
 
+.. _custom_source:
+
+Custom Sources
+++++++++++++++
+
+It is often the case that one may wish to simulate a complex source
+distribution, which may include physics not present within OpenMC or to be phase
+space complex. It is possible to define a complex source with an externally
+defined source function that is loaded at runtime. A simple example source is
+shown below.
+
+.. code-block:: c++
+
+   #include "openmc/random_lcg.h"
+   #include "openmc/source.h"
+   #include "openmc/particle.h"
+
+   // you must have external C linkage here
+   extern "C" openmc::Particle::Bank sample_source(uint64_t* seed) {
+     openmc::Particle::Bank particle;
+     // weight
+     particle.particle = openmc::Particle::Type::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;
+  }
+
+The above source, creates 14.08 MeV neutrons, with an istropic direction
+vector but 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 function signature must be declared to be 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:
+
+.. code-block:: cmake
+
+   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 :attr:`openmc.Source.library`
+attribute to the path of this shared library will indicate that it should be
+used for sampling source particles at runtime.
+
 .. _univariate:
 
 Univariate Probability Distributions

docs/source/usersguide/depletion.rst

@@ -33,12 +33,11 @@ material compositions over time. Each method appears as a different class.
 For example, :class:`openmc.deplete.CECMIntegrator` runs a depletion calculation
 using the CE/CM algorithm (deplete over a timestep using the middle-of-step
 reaction rates). An instance of :class:`openmc.deplete.Operator` is passed to
-one of these functions along with the power level and timesteps::
+one of these functions along with the timesteps and power level::
 
-    power = 1200.0e6
-    days = 24*60*60
-    timesteps = [10.0*days, 10.0*days, 10.0*days]
-    openmc.deplete.CECMIntegrator(op, power, timesteps).integrate()
+    power = 1200.0e6  # watts
+    timesteps = [10.0, 10.0, 10.0]  # days
+    openmc.deplete.CECMIntegrator(op, timesteps, power, timestep_units='d').integrate()
 
 The coupled transport-depletion problem is executed, and once it is done a
 ``depletion_results.h5`` file is written. The results can be analyzed using the
@@ -67,7 +66,7 @@ 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 
+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::
 
@@ -99,11 +98,11 @@ Local Spectra and Repeated Materials
 ------------------------------------
 
 It is not uncommon to explicitly create a single burnable material across many locations.
-From a pure transport perspective, there is nothing wrong with creating a single 
+From a pure transport perspective, 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, :mod:`openmc.deplete` will deplete a single ``fuel_3`` material using 
+issues with depletion.
+Under this setup, :mod:`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.

docs/source/usersguide/install.rst

@@ -404,7 +404,7 @@ to install the Python package in :ref:`"editable" mode <devguide_editable>`.
 Prerequisites
 -------------
 
-The Python API works with Python 3.4+. In addition to Python itself, the API
+The Python API works with Python 3.5+. 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. To run simulations in parallel using MPI, it is recommended to