Merge remote-tracking branch 'mitcrpgopenmc/develop' into res_scat

docs/source/devguide/index.rst

@@ -10,7 +10,7 @@ as debugging.
 
 .. toctree::
     :numbered:
-    :maxdepth: 2
+    :maxdepth: 3
 
     structures
     styleguide

docs/source/devguide/workflow.rst

@@ -38,7 +38,7 @@ following criteria must be satisfied for all proposed changes:
 
 - Changes have a clear purpose and are useful.
 - Compiles under all conditions (MPI, OpenMP, HDF5, etc.).  This is checked as
-  part of the test suite (see `test_compile.py`_).
+  part of the test suite.
 - Passes the regression suite.
 - If appropriate, test cases are added to regression suite.
 - No memory leaks (checked with valgrind_).
@@ -91,6 +91,133 @@ features and bug fixes. The general steps for contributing are as follows:
 6. After the pull request has been thoroughly vetted, it is merged back into the
    *develop* branch of mit-crpg/openmc.
 
+.. _test suite:
+
+OpenMC Test Suite
+-----------------
+
+The purpose of this test suite is to ensure that OpenMC compiles using various
+combinations of compiler flags and options, and that all user input options can
+be used successfully without breaking the code. The test suite is comprised of 
+regression tests where different types of input files are configured and the
+full OpenMC code is executed. Results from simulations are compared with
+expected results. The test suite is comprised of many build configurations
+(e.g. debug, mpi, hdf5) and the actual tests which reside in sub-directories
+in the tests directory. We recommend to developers to test their branches
+before submitting a formal pull request using gfortran and intel compilers
+if available.
+
+The test suite is designed to integrate with cmake using ctest_.
+It is configured to run with cross sections from NNDC_. To
+download these cross sections please do the following:
+
+.. code-block:: sh
+
+    cd ../data
+    python get_nndc.py
+    export CROSS_SECTIONS=<path_to_data_folder>/nndc/cross_sections.xml
+
+The test suite can be run on an already existing build using:
+
+.. code-block:: sh
+
+    cd build
+    make test
+
+or
+
+.. code-block:: sh
+
+    cd build
+    ctest
+
+There are numerous ctest_ command line options that can be set to have
+more control over which tests are executed.
+
+Before running the test suite python script, the following environmental
+variables should be set if the default paths are incorrect:
+
+    * **FC** - The command of the Fortran compiler (e.g. gfotran, ifort).
+
+        * Default - *gfortran*
+
+    * **MPI_DIR** - The path to the MPI directory.
+
+        * Default - */opt/mpich/3.1-gnu*
+
+    * **HDF5_DIR** - The path to the HDF5 directory.
+
+        * Default - */opt/hdf5/1.8.12-gnu*
+
+    * **PHDF5_DIR** - The path to the parallel HDF5 directory.
+
+        * Default - */opt/phdf5/1.8.12-gnu* 
+
+    * **PETSC_DIR** - The path to the PETSc directory.
+
+        * Default - */opt/petsc/3.4.4-gnu*
+
+To run the full test suite, the following command can be executed in the
+tests directory:
+
+.. code-block:: sh
+
+    python run_tests.py
+
+A subset of build configurations and/or tests can be run. To see how to use
+the script run:
+
+.. code-block:: sh
+
+    python run_tests.py --help
+
+As an example, say we want to run all tests with debug flags only on tests
+that have cone and plot in their name. Also, we would like to run this on
+4 processors. We can run:
+
+.. code-block:: sh
+
+    python run_tests.py -j 4 -C debug -R "cone|plot"
+
+Note that standard regular expression syntax is used for selecting build
+configurations and tests. To print out a list of build configurations, we
+can run:
+
+.. code-block:: sh
+
+    python run_tests.py -p
+
+Adding tests to test suite
+++++++++++++++++++++++++++
+
+To add a new test to the test suite, create a sub-directory in the tests
+directory that conforms to the regular expression *test_*. To configure
+a test you need to add the following files to your new test directory, 
+*test_name* for example:
+
+    * OpenMC input XML files
+    * **test_name.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.
+    * **results.py** - python script that extracts results from statepoint
+      output files. By default it should look for a binary file, but can
+      take an argument to overwrite which statepoint file is processed,
+      whether it is at a different batch or with an HDF5 extension. This
+      script must output a results file that is named *results_test.dat*.
+      It is recommended that any real numbers reported use *12.6E* format.
+    * **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/HDF5, 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 directory will automatically be added
+to the CTest framework.
+
 Private Development
 -------------------
 
@@ -108,10 +235,11 @@ from your private repository into a public fork.
 .. _git: http://git-scm.com/
 .. _GitHub: https://github.com/
 .. _git flow: http://nvie.com/git-model
-.. _test_compile.py: https://github.com/mit-crpg/openmc/blob/develop/tests/test_compile/test_compile.py
 .. _valgrind: http://valgrind.org/
 .. _style guide: http://mit-crpg.github.io/openmc/devguide/styleguide.html
 .. _pull request: https://help.github.com/articles/using-pull-requests
 .. _mit-crpg/openmc: https://github.com/mit-crpg/openmc
 .. _paid plan: https://github.com/plans
 .. _Bitbucket: https://bitbucket.org
+.. _ctest: http://www.cmake.org/cmake/help/v2.8.12/ctest.html
+.. _NNDC:  http://http://www.nndc.bnl.gov/endf/b7.1/acefiles.html

docs/source/devguide/xml-parsing.rst

@@ -13,13 +13,13 @@ With the FoX library, extending the user input files to include new tags is
 fairly straightforward. The steps for modifying/adding input are as follows:
 
 1. Add appropriate calls to procedures from the `xml_interface module`_, such as
-``check_for_node``, ``get_node_value``, and ``get_node_array``. All input
-reading is performed in the `input_xml module`_.
+   ``check_for_node``, ``get_node_value``, and ``get_node_array``. All input
+   reading is performed in the `input_xml module`_.
 
 2. 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".
+   `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".
 
 3. Add code to check the variable for any possible errors.
 
@@ -29,10 +29,90 @@ schema for the file you changed (e.g. src/relaxng/geometry.rnc) so that
 those who use Emacs can confirm whether their input is valid before they
 run. You will need to be familiar with RELAX NG `compact syntax`_.
 
-.. _FoX: https://github.com/andreww/fox
+Working with the FoX Submodule
+==============================
+
+The FoX_ library is included as a submodule_ in OpenMC. This means that for a
+given commit in OpenMC, there is an associated commit id that links to FoX.
+The actual FoX source code is maintained at mit-crpg/fox, branch openmc. When
+cloning the OpenMC repo for the first time, you will notice that the directory
+*src/xml/fox* is empty. To fetch the submodule source code, you can manually
+enter the following from the root directory of OpenMC:
+
+.. code-block:: sh
+
+    git submodule init
+    git submodule update
+
+It should be noted that if the submodule is not initialized and updated, *cmake*
+will automatically perform these commands if it cannot file the FoX source code.
+
+If you navigate into the FoX source code in OpenMC, src/xml/fox, and check git
+information, you will notice that you are in a completely different repo. Actually,
+you are in a clone of mit-crpg/fox. If you have write access to this repo, you can 
+make changes to the FoX source code, commit and push just like any other repo.
+Just because you make changes to the FoX source code in OpenMC or in a standalone
+repo, this does not mean that OpenMC will automatically fetch these changes. The
+way submodules work is that they are just stored as a commit id. To save FoX xml
+source changes to your OpenMC branch, do the following:
+
+1. Go into src/xml/fox and check out the appropriate source code state
+
+2. Navigate back out of fox subdirectory and type:
+
+.. code-block:: sh
+
+    git status
+
+3. Make sure you see that git recognized that the state of FoX changed:
+
+::
+
+    # On branch fox_submodule
+    # Changes not staged for commit:
+    #   (use "git add <file>..." to update what will be committed)
+    #   (use "git checkout -- <file>..." to discard changes in working directory)
+    #
+    #   modified:   fox (new commits)
+
+4. Commit and push this change
+
+Editing FoX on Personal Fork
+============================
+
+If you don't have write access to mit-crpg/fox and thus can't make a branch off of the openmc
+branch there, you will need to fork mit-crpg/fox to your personal account. You need to then
+link your branch in your OpenMC repo, to the *openmc* branch on your own personal FoX fork.
+To do this, edit the *.gitmodules* file in the root folder of the repo. It contains the
+following information:
+
+::
+
+    [submodule "src/xml/fox"]
+        path = src/xml/fox
+        url = git@github.com:mit-crpg/fox
+
+Change the url remote to your own fork. The commit id should stay constant until you start
+making modification to FoX yourself. Once you have made changes to your FoX fork and linked
+the new commit id to your OpenMC branch, you can pull request your changes in by peforming
+the following steps:
+
+1. Create a pull request from your fork of FoX to mit-crpg/fox and wait until it
+   is merged into the openmc branch.
+
+2. In your OpenMC repo, change your *.gitmodules* file back to point at mit-crpg/fox.
+
+3. Submit a pull request to mit-crpg/openmc
+
+.. warning:: If you make changes to your FoX submodule inside of an OpenMC repo and do not 
+    commit, do **not** run *git submodule update*. This may throw away any changes that
+    were not committed.
+
+.. _FoX: https://github.com/mit-crpg/fox
 .. _xml_interface module: https://github.com/mit-crpg/openmc/blob/develop/src/xml_interface.F90
 .. _input_xml module: https://github.com/mit-crpg/openmc/blob/develop/src/input_xml.F90
 .. _XML Schema Part 2: http://www.w3.org/TR/xmlschema-2/
 .. _boolean: http://www.w3.org/TR/xmlschema-2/#boolean
 .. _RELAX NG: http://relaxng.org/
 .. _compact syntax: http://relaxng.org/compact-tutorial-20030326.html
+.. _submodule: http://git-scm.com/book/en/Git-Tools-Submodules

docs/source/publications.rst

@@ -14,8 +14,8 @@ Publications
 
 - 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.*
-  (2013). `<http://dx.doi.org/10.1016/j.cpc.2013.10.008>`_
+  using energy banding," *Comput. Phys. Commun.*, **185** (4), 1195--1199
+  (2014). `<http://dx.doi.org/10.1016/j.cpc.2013.10.008>`_
 
 - Jonathan A. Walsh, Benoit Forget, and Kord S. Smith, "Validation of OpenMC
   Reactor Physics Simulations with the B&W 1810 Series Benchmarks,"

docs/source/usersguide/install.rst

@@ -322,6 +322,31 @@ This will build an executable named ``openmc``.
 .. _MinGW: http://www.mingw.org
 .. _SourceForge: http://sourceforge.net/projects/mingw
 
+Testing Build
+-------------
+
+If you have ENDF/B-VII.1 cross sections from NNDC_ you can test your build.
+Make sure the **CROSS_SECTIONS** environmental variable is set to the 
+*cross_sections.xml* file in the *data/nndc* directory.
+There are two ways to run tests. The first is to use the Makefile present in
+the source directory and run the following:
+
+.. code-block:: sh
+
+    cd src
+    make test
+
+If you want more options for testing you can use ctest_ command. For example,
+if we wanted to run only the plot tests with 4 processors, we run:
+
+.. code-block:: sh
+
+    cd src/build
+    ctest -j 4 -R plot
+
+If you want to run the full test suite with different build options please
+refer to our :ref:`test suite` documentation.
+
 ---------------------------
 Cross Section Configuration
 ---------------------------
@@ -347,7 +372,8 @@ extract, and set up a confiuration file:
     python get_nndc_data.py
 
 At this point, you should set the :envvar:`CROSS_SECTIONS` environment variable
-to the absolute path of the file ``openmc/data/nndc/cross_sections.xml``.
+to the absolute path of the file ``openmc/data/nndc/cross_sections.xml``. This
+cross section set is used by the test suite.
 
 Using JEFF Cross Sections from OECD/NEA
 ---------------------------------------
@@ -467,3 +493,5 @@ schemas.xml file in your own OpenMC source directory.
 .. _GNU Emacs: http://www.gnu.org/software/emacs/
 .. _validation: http://en.wikipedia.org/wiki/XML_validation
 .. _RELAX NG: http://relaxng.org/
+.. _ctest: http://www.cmake.org/cmake/help/v2.8.12/ctest.html
+.. _NNDC:  http://http://www.nndc.bnl.gov/endf/b7.1/acefiles.html