From 302816b4ef83e393a26c921c8bc7912e1efba001 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Fri, 3 Mar 2017 11:20:00 -0600 Subject: [PATCH] Updates to documentation. Replace XML parsing section with user input changes section. --- docs/source/developers.rst | 6 +- docs/source/devguide/index.rst | 2 +- docs/source/devguide/user-input.rst | 62 ++++++++++++++ docs/source/devguide/xml-parsing.rst | 118 --------------------------- docs/source/usersguide/install.rst | 22 +++-- 5 files changed, 84 insertions(+), 126 deletions(-) create mode 100644 docs/source/devguide/user-input.rst delete mode 100644 docs/source/devguide/xml-parsing.rst diff --git a/docs/source/developers.rst b/docs/source/developers.rst index 0bdae24160..825fbd1c6d 100644 --- a/docs/source/developers.rst +++ b/docs/source/developers.rst @@ -4,7 +4,8 @@ Development Team ================ -Active development of the OpenMC Monte Carlo code is currently led by: +The following people have contributed to development of the OpenMC Monte Carlo +code: * `Paul Romano `_ * `Bryan Herman `_ @@ -14,6 +15,9 @@ Active development of the OpenMC Monte Carlo code is currently led by: * `Sterling Harper `_ * `Will Boyd `_ * `Samuel Shaner `_ +* `Jingang Liang `_ +* `Colin Josey `_ +* `Amanda Lund `_ * `Benoit Forget `_ * `Kord Smith `_ * `Andrew Siegel `_ diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 37b17bc0fa..4dc1b2c74c 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -15,5 +15,5 @@ as debugging. structures styleguide workflow - xml-parsing + user-input docbuild diff --git a/docs/source/devguide/user-input.rst b/docs/source/devguide/user-input.rst new file mode 100644 index 0000000000..0612dbe0c4 --- /dev/null +++ b/docs/source/devguide/user-input.rst @@ -0,0 +1,62 @@ +.. _devguide_user_input: + +========================= +Making User Input Changes +========================= + +Users are encouraged to use OpenMC's :ref:`pythonapi` to build XML files that +the OpenMC solver then reads during the initialization phase. Thus, to modify, +add, or remove user input options, changes must be made both within the Python +API and the Fortran source that reads XML files produced by the Python API. The +following steps should be followed to make changes to user input: + +1. Determine the Python class you need to change. For example, if you are adding + a new setting, you probably want to change the :class:`openmc.Settings` + class. If you are adding a new surface type, you would need to create a + subclass of :class:`openmc.Surface`. + +2. To add a new option, the class will need a `property attribute`_. For + example, if you wanted to add a "fast_mode" setting, you would need two + methods that look like: + + .. code-block:: python + + @property + def fast_mode(self): + ... + + @fast_mode.setter + def fast_mode(self, fast_mode): + ... + +3. Make sure that when an instance of the class is exported to XML (usually + through a ``export_to_xml()`` or ``to_xml_element()`` method), a new element + is written to the appropriate file. OpenMC uses the + :mod:`xml.etree.ElementTree` API, so refer to the documentation of that + module for guidance on creating elements/attributes. + +4. 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". + +5. Now that you're done with the Python side, you need to make modifications to + the Fortran codebase. Make appropriate changes in the `input_xml module`_ to + read your new user input. You should use procedures and types defined by the + `xml_interface module`_. + +6. If you've made changes in the geometry or materials, make sure they are + written out to the statepoint or summary files and that the + :class:`openmc.StatePoint` and :class:`openmc.Summary` classes read them in. + +For most user input additions and changes, it is simple enough to follow a +"monkey see, monkey do" approach. When in doubt, contact your nearest OpenMC +developer or send a message to the `developers mailing list`_. + + +.. _property attribute: https://docs.python.org/3.6/library/functions.html#property +.. _XML Schema Part 2: http://www.w3.org/TR/xmlschema-2/ +.. _boolean: http://www.w3.org/TR/xmlschema-2/#boolean +.. _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 +.. _developers mailing list: https://groups.google.com/forum/?fromgroups=#!forum/openmc-dev diff --git a/docs/source/devguide/xml-parsing.rst b/docs/source/devguide/xml-parsing.rst deleted file mode 100644 index cf6f238bdb..0000000000 --- a/docs/source/devguide/xml-parsing.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _devguide_xml-parsing: - -================= -XML Input Parsing -================= - -OpenMC relies on the FoX_ Fortran XML library for reading and intrepreting the -XML input files for geometry, materials, settings, tallies, etc. The use of an -XML format makes writing input files considerably more flexible than would -otherwise be possible. - -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`_. - -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". - -3. Add code to check the variable for any possible errors. - -A set of `RELAX NG`_ schemata exists that enables real-time validation of input -files when using the GNU Emacs text editor. You should also modify the RELAX NG -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`_. - -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 ..." to update what will be committed) - # (use "git checkout -- ..." 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 diff --git a/docs/source/usersguide/install.rst b/docs/source/usersguide/install.rst index 91c977ca45..e980407084 100644 --- a/docs/source/usersguide/install.rst +++ b/docs/source/usersguide/install.rst @@ -58,7 +58,7 @@ Now OpenMC should be recognized within the repository and can be installed: .. code-block:: sh - sudo apt-get install openmc + sudo apt install openmc Binary packages from this PPA may exist for earlier versions of Ubuntu, but they are no longer supported. @@ -88,7 +88,16 @@ Prerequisites If you are using Debian or a Debian derivative such as Ubuntu, you can install the gfortran compiler using the following command:: - sudo apt-get install gfortran + sudo apt install gfortran + + * A C/C++ compiler such as gcc_ + + OpenMC includes two libraries written in C and C++, respectively. These + libraries have been tested to work with a wide variety of compilers. If + you are using a Debian-based distribution, you can install the g++ + compiler using the following command:: + + sudo apt install g++ * CMake_ cross-platform build system @@ -97,7 +106,7 @@ Prerequisites derivative such as Ubuntu, you can install CMake using the following command:: - sudo apt-get install cmake + sudo apt install cmake * HDF5_ Library for portable binary output format @@ -125,7 +134,7 @@ Prerequisites .. code-block:: sh - sudo apt-get install libhdf5-8 libhdf5-dev hdf5-helpers + sudo apt install libhdf5-dev hdf5-helpers Note that the exact package names may vary depending on your particular distribution and version. @@ -140,12 +149,13 @@ Prerequisites with the latest versions of both OpenMPI_ and MPICH_. OpenMPI and/or MPICH can be installed on Debian derivatives with:: - sudo apt-get install mpich libmpich-dev - sudo apt-get install openmpi-bin libopenmpi1.6 libopenmpi-dev + sudo apt install mpich libmpich-dev + sudo apt install openmpi-bin libopenmpi-dev * git_ version control software for obtaining source code .. _gfortran: http://gcc.gnu.org/wiki/GFortran +.. _gcc: https://gcc.gnu.org/ .. _CMake: http://www.cmake.org .. _OpenMPI: http://www.open-mpi.org .. _MPICH: http://www.mpich.org