Merge branch 'release-0.6.0'

Author: paulromano

.gitignore

@@ -21,6 +21,12 @@ src/openmc
 docs/build
 docs/source/_images/*.pdf
 
+# Source build
+src/build
+
+# build from src/utils/setup.py
+src/utils/build
+
 # xml-fortran reader
 src/xml-fortran/xmlreader
 
@@ -32,3 +38,6 @@ results_error.dat
 
 # HDF5 files
 *.h5
+
+# Data downloaded from NNDC
+data/nndc

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/xml/fox"]
+	path = src/xml/fox
+	url = https://github.com/mit-crpg/fox.git

data/get_nndc_data.py

@@ -6,17 +6,19 @@
 import subprocess
 import sys
 import tarfile
+import glob
 
 try:
     from urllib.request import urlopen
 except ImportError:
     from urllib2 import urlopen
 
+cwd = os.getcwd()
+sys.path.append(os.path.join(cwd, '..', 'src', 'utils'))
+from convert_binary import ascii_to_binary
+
 baseUrl = 'http://www.nndc.bnl.gov/endf/b7.1/aceFiles/'
 files = ['ENDF-B-VII.1-neutron-293.6K.tar.gz',
-         'ENDF-B-VII.1-neutron-300K.tar.gz',
-         'ENDF-B-VII.1-neutron-900K.tar.gz',
-         'ENDF-B-VII.1-neutron-1500K.tar.gz',
          'ENDF-B-VII.1-tsl.tar.gz']
 block_size = 16384
 
@@ -73,6 +75,17 @@
         print('Extracting {0}...'.format(f))
         tgz.extractall(path='nndc/' + suffix)
 
+#===============================================================================
+# EDIT GRAPHITE ZAID (6012 to 6000)
+
+print('Changing graphite ZAID from 6012 to 6000')
+graphite = os.path.join('nndc', 'tsl', 'graphite.acer')
+with open(graphite) as fh:
+    text = fh.read()
+text = text.replace('6012', '6000', 1)
+with open(graphite, 'w') as fh:
+    fh.write(text)
+
 # ==============================================================================
 # COPY CROSS_SECTIONS.XML
 
@@ -94,3 +107,43 @@
         if os.path.exists(f):
             print('Removing {0}...'.format(f))
             os.remove(f)
+
+# ==============================================================================
+# PROMPT USER TO CONVERT ASCII TO BINARY
+
+# Ask user to convert
+if sys.version_info[0] < 3:
+    response = raw_input('Convert ACE files to binary? ([y]/n) ')
+else:
+    response = input('Convert ACE files to binary? ([y]/n) ')
+
+# Convert files if requested
+if not response or response.lower().startswith('y'):
+
+    # get a list of directories
+    ace_dirs = glob.glob(os.path.join('nndc', '*K'))
+    ace_dirs += glob.glob(os.path.join('nndc', 'tsl'))
+
+    # loop around ace directories
+    for d in ace_dirs:
+        print('Coverting {0}...'.format(d))
+
+        # get a list of files to convert
+        ace_files = glob.glob(os.path.join(d, '*.ace*'))
+
+        # convert files
+        for f in ace_files:
+            print('    Coverting {0}...'.format(os.path.split(f)[1]))
+            ascii_to_binary(f, f)
+
+    # Change cross_sections.xml file
+    xs_file = os.path.join('nndc', 'cross_sections.xml')
+    asc_str = "<filetype>ascii</filetype>"
+    bin_str = "<filetype> binary </filetype>\n "
+    bin_str += "<record_length> 4096 </record_length>\n "
+    bin_str += "<entries> 512 </entries>"
+    with open(xs_file) as fh:
+        text = fh.read()
+    text = text.replace(asc_str, bin_str)
+    with open(xs_file, 'w') as fh:
+        fh.write(text)

docs/source/conf.py

@@ -46,9 +46,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "0.5"
+version = "0.6"
 # The full version, including alpha/beta/rc tags.
-release = "0.5.3"
+release = "0.6.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

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 = [email protected]: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