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

Merge pull request #911 from smharper/style_docs

Browse source 
Update the style guide with C++ guidelines
This commit is contained in:
Paul Romano 2017-12-18 17:17:38 +07:00 • committed by GitHub
commit c2e1adf94c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 141 additions and 177 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -12,7 +12,6 @@ as debugging.
:numbered:
:maxdepth: 3
structures
styleguide
workflow
user-input

155
docs/source/devguide/structures.rst
View file

@ -1,155 +0,0 @@
.. _devguide_structures:
===============
Data Structures
===============
The purpose of this section is to give you an overview of the major data
structures in OpenMC and how they are logically related. A majority of variables
in OpenMC are `derived types`_ (similar to a struct in C). These derived types
are defined in the various header modules, e.g. src/geometry_header.F90. Most
important variables are found in the `global module`_. Have a look through that
module to get a feel for what variables you'll often come across when looking at
OpenMC code.
--------
Particle
--------
Perhaps the variable that you will see most often is simply called ``p`` and is
of type(Particle). This variable stores information about a particle's physical
characteristics (coordinates, direction, energy), what cell and material it's
currently in, how many collisions it has undergone, etc. In practice, only one
particle is followed at a time so there is no array of type(Particle). The
Particle type is defined in the `particle_header module`_.
You will notice that the direction and angle of the particle is stored in a
linked list of type(LocalCoord). In geometries with multiple :ref:`universes`,
the coordinates in each universe are stored in this linked list. If universes or
lattices are not used in a geometry, only one LocalCoord is present in the
linked list.
The LocalCoord type has a component called cell which gives the index in the
``cells`` array in the `global module`_. The ``cells`` array is of type(Cell)
and stored information about each region defined by the user.
----
Cell
----
The Cell type is defined in the `geometry_header module`_ along with other
geometry-related derived types. Each cell in the problem is described in terms
of its bounding surfaces, which are listed on the ``surfaces`` component. The
absolute value of each item in the ``surfaces`` component contains the index of
the corresponding surface in the ``surfaces`` array defined in the `global
module`_. The sign on each item in the ``surfaces`` component indicates whether
the cell exists on the positive or negative side of the surface (see
:ref:`methods_geometry`).
Each cell can either be filled with another universe/lattice or with a
material. If it is filled with a material, the ``material`` component gives the
index of the material in the ``materials`` array defined in the `global
module`_.
-------
Surface
-------
The Surface type is defined in the `geometry_header module`_. A surface is
defined by a type (sphere, cylinder, etc.) and a list of coefficients for that
surface type. The simplest example would be a plane perpendicular to the xy, yz,
or xz plane which needs only one parameter. The ``type`` component indicates the
type through integer parameters such as SURF_SPHERE or SURF_CYL_Y (these are
defined in the `constants module`_). The ``coeffs`` component gives the
necessary coefficients to parameterize the surface type (see
:ref:`surface_element`).
--------
Material
--------
The Material type is defined in the `material_header module`_. Each material
contains a number of nuclides at a given atom density. Each item in the
``nuclide`` component corresponds to the index in the global ``nuclides`` array
(as usual, found in the `global module`_). The ``atom_density`` component is the
same length as the ``nuclides`` component and lists the corresponding atom
density in atom/barn-cm for each nuclide in the ``nuclides`` component.
If the material contains nuclides for which binding effects are important in
low-energy scattering, a :math:`S(\alpha,\beta)` can be associated with that
material through the ``sab_table`` component. Again, this component contains the
index in the ``sab_tables`` array from the `global module`_.
-------
Nuclide
-------
The Nuclide derived type stores cross section and interaction data for a nucleus
and is defined in the `ace_header module`_. The ``energy`` component is an array
that gives the discrete energies at which microscopic cross sections are
tabulated. The actual microscopic cross sections are stored in a separate
derived type, Reaction. An arrays of Reactions is present in the ``reactions``
component. There are a few summary microscopic cross sections stored in other
components, such as ``total``, ``elastic``, ``fission``, and ``nu_fission``.
If a Nuclide is fissionable, the prompt and delayed neutron yield and energy
distributions are also stored on the Nuclide type. Many nuclides also have
unresolved resonance probability table data. If present, this data is stored in
the component ``urr_data`` of derived type UrrData. A complete description of
the probability table method is given in :ref:`probability_tables`.
The list of nuclides present in a problem is stored in the ``nuclides`` array
defined in the `global module`_.
----------
SAlphaBeta
----------
The SAlphaBeta derived type stores :math:`S(\alpha,\beta)` data to account for
molecular binding effects when treating thermal scattering. Each SAlphaBeta
table is associated with a specific nuclide as identified in the ``zaid``
component. A complete description of the :math:`S(\alpha,\beta)` treatment can
be found in :ref:`sab_tables`.
---------
XsListing
---------
The XsListing derived type stores information on the location of an ACE cross
section table based on the data in cross_sections.xml and is defined in the
`ace_header module`_. For each ``<ace_table>`` you see in cross_sections.xml,
there is a XsListing with its information. When the user input is read, the
array ``xs_listings`` in the `global module`_ that is of derived type XsListing
is used to locate the ACE data to parse.
--------------
NuclideMicroXS
--------------
The NuclideMicroXS derived type, defined in the `ace_header module`_, acts as a
'cache' for microscopic cross sections. As a particle is traveling through
different materials, cross sections can be reused if the energy of the particle
hasn't changed. The components ``total``, ``elastic``, ``absorption``,
``fission``, and ``nu_fission`` represent those microscopic cross sections at
the current energy of the particle for a given nuclide. An array ``micro_xs`` in
the `global module`_ that is the same length as the ``nuclides`` array stores
these cached cross sections for each nuclide in the problem.
---------------
MaterialMacroXS
---------------
In addition to the NuclideMicroXS type, there is also a MaterialMacroXS derived
type, defined in the `ace_header module`_ that stored cached *macroscopic* cross
sections for the current material. These macroscopic cross sections are used for
both physics and tallying purposes. The variable ``material_xs`` in the `global
module`_ is of type MaterialMacroXS.
.. _derived types: http://nf.nci.org.au/training/FortranAdvanced/slides/slides.025.html
.. _global module: https://github.com/mit-crpg/openmc/blob/master/src/global.F90
.. _particle_header module: https://github.com/mit-crpg/openmc/blob/master/src/particle_header.F90
.. _geometry_header module: https://github.com/mit-crpg/openmc/blob/master/src/geometry_header.F90
.. _constants module: https://github.com/mit-crpg/openmc/blob/master/src/constants.F90
.. _material_header module: https://github.com/mit-crpg/openmc/blob/master/src/material_header.F90
.. _ace_header module: https://github.com/mit-crpg/openmc/blob/master/src/ace_header.F90

162
docs/source/devguide/styleguide.rst
View file

@ -12,21 +12,18 @@ adding new code in OpenMC.
Fortran
-------
General Rules
Miscellaneous
-------------
Conform to the Fortran 2008 standard.
Make sure code can be compiled with most common compilers, especially gfortran
and the Intel Fortran compiler. This supercedes the previous rule --- if a
and the Intel Fortran compiler. This supersedes the previous rule --- if a
Fortran 2003/2008 feature is not implemented in a common compiler, do not use
it.
Do not use special extensions that can be only be used from certain compilers.
In general, write your code in lower-case. Having code in all caps does not
enhance code readability or otherwise.
Always include comments to describe what your code is doing. Do not be afraid of
using copious amounts of comments.
@ -38,6 +35,28 @@ Don't use ``print *`` or ``write(*,*)``. If writing to a file, use a specific
unit. Writing to standard output or standard error should be handled by the
``write_message`` subroutine or functionality in the error module.
Naming
------
In general, write your code in lower-case. Having code in all caps does not
enhance code readability or otherwise.
Module names should be lower-case with underscores if needed, e.g.
``xml_interface``.
Class names should be CamelCase, e.g. ``HexLattice``.
Functions and subroutines (including type-bound methods) should be lower-case
with underscores, e.g. ``get_indices``.
Local variables, global variables, and type attributes should be lower-case
with underscores (e.g. ``n_cells``) except for physics symbols that are written
differently by convention (e.g. ``E`` for energy).
Constant (parameter) variables should be in upper-case with underscores, e.g.
``SQRT_PI``. If they are used by more than one module, define them in the
constants.F90 module.
Procedures
----------
@ -55,18 +74,10 @@ Variables
Never, under any circumstances, should implicit variables be used! Always
include ``implicit none`` and define all your variables.
Variable names should be all lower-case and descriptive, i.e. not a random
assortment of letters that doesn't give any information to someone seeing it for
the first time. Variables consisting of multiple words should be separated by
underscores, not hyphens or in camel case.
Constant (parameter) variables should be in ALL CAPITAL LETTERS and defined in
in the constants.F90 module.
32-bit reals (real(4)) should never be used. Always use 64-bit reals (real(8)).
For arbitrary length character variables, use the pre-defined lengths
MAX_LINE_LEN, MAX_WORD_LEN, and MAX_FILE_LEN if possible.
``MAX_LINE_LEN``, ``MAX_WORD_LEN``, and ``MAX_FILE_LEN`` if possible.
Do not use old-style character/array length (e.g. character*80, real*8).
@ -92,7 +103,7 @@ allocation instead. Use allocatable variables instead of pointer variables when
possible.
Shared/Module Variables
+++++++++++++++++++++++
-----------------------
Always put shared variables in modules. Access module variables through a
``use`` statement. Always use the ``only`` specifier on the ``use`` statement
@ -100,12 +111,6 @@ except for variables from the global, constants, and various header modules.
Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements.
Derived Types and Classes
-------------------------
Derived types and classes should have CamelCase names with words not separated
by underscores or hyphens.
Indentation
-----------
@ -158,6 +163,120 @@ each side.
Do not leave trailing whitespace at the end of a line.
---
C++
---
Miscellaneous
-------------
Follow the `C++ Core Guidelines`_ except when they conflict with another
guideline listed here. For convenience, many important guidelines from that
list are repeated here.
Conform to the C++11 standard. Note that this is a significant difference
between our style and the C++ Core Guidelines. Many suggestions in those
Guidelines require C++14.
Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It
is more difficult to comment out a large section of code that uses C-style
comments.)
Header files should always use include guards with the following style (See
`SF.8 <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf8-use-include-guards-for-all-h-files>`_:
.. code-block:: C++
#ifndef MODULE_NAME_H
#define MODULE_NAME_H
...
content
...
#endif // MODULE_NAME_H
Do not use C-style casting. Always use the C++-style casts ``static_cast``,
``const_cast``, or ``reinterpret_cast``. (See `ES.49 <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es49-if-you-must-use-a-cast-use-a-named-cast>`_)
Naming
------
In general, write your code in lower-case. Having code in all caps does not
enhance code readability or otherwise.
Struct and class names should be CamelCase, e.g. ``HexLattice``.
Functions (including member functions) should be lower-case with underscores,
e.g. ``get_indices``.
Local variables, global variables, and struct/class attributes should be
lower-case with underscores (e.g. ``n_cells``) except for physics symbols that
are written differently by convention (e.g. ``E`` for energy).
Const variables should be in upper-case with underscores, e.g. ``SQRT_PI``.
Curly braces
------------
For a function definition, the opening and closing braces should each be on
their own lines. This helps distinguish function code from the argument list.
If the entire function fits on one line, then the braces can be on the same
line. e.g.:
.. code-block:: C++
return_type function(type1 arg1, type2 arg2)
{
content();
}
return_type
function_with_many_args(type1 arg1, type2 arg2, type3 arg3,
type4 arg4)
{
content();
}
int return_one() {return 1;}
For a conditional, the opening brace should be on the same line as the end of
the conditional statement. If there is a following ``else if`` or ``else``
statement, the closing brace should be on the same line as that following
statement. Otherwise, the closing brace should be on its own line. A one-line
conditional can have the closing brace on the same line or it can omit the
braces entirely e.g.:
.. code-block:: C++
if (condition) {
content();
}
if (condition1) {
content();
} else if (condition 2) {
more_content();
} else {
further_content();
}
if (condition) {content()};
if (condition) content();
For loops similarly have an opening brace on the same line as the statement and
a closing brace on its own line. One-line loops may have the closing brace on
the same line or omit the braces entirely.
.. code-block:: C++
for (int i = 0; i < 5; i++) {
content();
}
for (int i = 0; i < 5; i++) {content();}
for (int i = 0; i < 5; i++) content();
------
Python
------
@ -172,6 +291,7 @@ Use of third-party Python packages should be limited to numpy_, scipy_, and
h5py_. Use of other third-party packages must be implemented as optional
dependencies rather than required dependencies.
.. _C++ Core Guidelines: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _numpy: http://www.numpy.org/