crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-28 06:05:58 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Updates to documentation. Replace XML parsing section with user input changes

Browse source 
section.
This commit is contained in:
Paul Romano 2017-03-03 11:20:00 -06:00
parent d85c4ec54c
commit 302816b4ef
5 changed files with 84 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/source/devguide/index.rst
View file

@ -15,5 +15,5 @@ as debugging.
structures
styleguide
workflow
xml-parsing
user-input
docbuild

62
docs/source/devguide/user-input.rst Normal file
View file

@ -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

118
docs/source/devguide/xml-parsing.rst
View file

@ -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 <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