mirror of
https://github.com/openmc-dev/openmc.git
synced 2026-07-28 06:05:58 -04:00
Merge branch 'develop' into new-scatt-mat
This commit is contained in:
Will Boyd
commit
e640146f8f
64 changed files with 15896 additions and 1606 deletions
|
|
@ -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 <https://github.com/paulromano>`_
|
||||
* `Bryan Herman <https://github.com/bhermanmit>`_
|
||||
|
|
@ -14,6 +15,9 @@ Active development of the OpenMC Monte Carlo code is currently led by:
|
|||
* `Sterling Harper <https://github.com/smharper>`_
|
||||
* `Will Boyd <https://github.com/wbinventor>`_
|
||||
* `Samuel Shaner <https://github.com/samuelshaner>`_
|
||||
* `Jingang Liang <https://github.com/liangjg>`_
|
||||
* `Colin Josey <https://github.com/cjosey>`_
|
||||
* `Amanda Lund <https://github.com/amandalund>`_
|
||||
* `Benoit Forget <http://web.mit.edu/nse/people/faculty/forget.html>`_
|
||||
* `Kord Smith <http://web.mit.edu/nse/people/faculty/smith.html>`_
|
||||
* `Andrew Siegel <http://www.mcs.anl.gov/person/andrew-siegel>`_
|
||||
|
|
|
|||
|
|
@ -15,5 +15,5 @@ as debugging.
|
|||
structures
|
||||
styleguide
|
||||
workflow
|
||||
xml-parsing
|
||||
user-input
|
||||
docbuild
|
||||
|
|
|
|||
73
docs/source/devguide/user-input.rst
Normal file
73
docs/source/devguide/user-input.rst
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
.. _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.
|
||||
|
||||
7. Finally, a set of `RELAX NG`_ schemas exists that enables validation of input
|
||||
files. You should modify the RELAX NG schema for the file you changed. The
|
||||
easiest way to do this is to change the `compact syntax`_ file
|
||||
(e.g. ``src/relaxng/geometry.rnc``) and then convert it to regular XML syntax
|
||||
using trang_::
|
||||
|
||||
trang geometry.rnc geometry.rng
|
||||
|
||||
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
|
||||
.. _RELAX NG: http://relaxng.org/
|
||||
.. _compact syntax: http://relaxng.org/compact-tutorial-20030326.html
|
||||
.. _trang: http://www.thaiopensource.com/relaxng/trang.html
|
||||
.. _developers mailing list: https://groups.google.com/forum/?fromgroups=#!forum/openmc-dev
|
||||
|
|
@ -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
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -839,17 +839,27 @@ problem. It has the following attributes/sub-elements:
|
|||
|
||||
*Default*: None
|
||||
|
||||
.. _verbosity:
|
||||
|
||||
``<verbosity>`` Element
|
||||
-----------------------
|
||||
|
||||
The ``<verbosity>`` element tells the code how much information to display to
|
||||
the standard output. A higher verbosity corresponds to more information being
|
||||
displayed. This element takes the following attributes:
|
||||
displayed. The text of this element should be an integer between between 1
|
||||
and 10. The verbosity levels are defined as follows:
|
||||
|
||||
:value:
|
||||
The specified verbosity between 1 and 10.
|
||||
:1: don't display any output
|
||||
:2: only show OpenMC logo
|
||||
:3: all of the above + headers
|
||||
:4: all of the above + results
|
||||
:5: all of the above + file I/O
|
||||
:6: all of the above + timing statistics and initialization messages
|
||||
:7: all of the above + :math:`k` by generation
|
||||
:9: all of the above + indicate when each particle starts
|
||||
:10: all of the above + event information
|
||||
|
||||
*Default*: 5
|
||||
*Default*: 7
|
||||
|
||||
``<create_fission_neutrons>`` Element
|
||||
-------------------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue