diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 4dc1b2c74c..1a8252383c 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -12,7 +12,6 @@ as debugging. :numbered: :maxdepth: 3 - structures styleguide workflow user-input diff --git a/docs/source/devguide/structures.rst b/docs/source/devguide/structures.rst deleted file mode 100644 index 15777f6065..0000000000 --- a/docs/source/devguide/structures.rst +++ /dev/null @@ -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 ```` 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 diff --git a/docs/source/devguide/styleguide.rst b/docs/source/devguide/styleguide.rst index 936f0c8388..89d5673943 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -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 `_: + +.. 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 `_) + +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/