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..e2b3de5c3d 100644 --- a/docs/source/devguide/styleguide.rst +++ b/docs/source/devguide/styleguide.rst @@ -8,35 +8,50 @@ In order to keep the OpenMC code base consistent in style, this guide specifies a number of rules which should be adhered to when modified existing code or adding new code in OpenMC. -------- -Fortran -------- +--------------- +Fortran and C++ +--------------- -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 -Fortran 2003/2008 feature is not implemented in a common compiler, do not use -it. +Make sure code can be compiled with most common compilers, especially the GCC +and Intel compilers. This supersedes the rules about standards---if a Fortran +2003/2008 feature is not implemented in a common compiler then 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. -Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. - Try to keep code within 80 columns when possible. -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. +Don't use ``print *``, ``write(*,*)``, ``fprintf()``, or ``std::cout``. 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 or const) variables should be in upper-case with +underscores, e.g. ``SQRT_PI``. These should usually be defined in the +constants.F90 module. Procedures ---------- @@ -53,28 +68,17 @@ Variables --------- Never, under any circumstances, should implicit variables be used! Always -include ``implicit none`` and define all your variables. +include ``implicit none`` in Fortran source code 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)). +32-bit reals (``real(4)`` and ``float``) should never be used. Always use 64-bit +reals (``real(8)`` and ``double``). For arbitrary length character variables, use the pre-defined lengths -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). +``MAX_LINE_LEN``, ``MAX_WORD_LEN``, and ``MAX_FILE_LEN`` if possible. Integer values being used to indicate a certain state should be defined as named constants (see the constants.F90 module for many examples). -Always use a double colon :: when declaring a variable. - Yes: .. code-block:: fortran @@ -92,20 +96,12 @@ 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 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 +154,110 @@ each side. Do not leave trailing whitespace at the end of a line. +---------------- +Fortran-Specific +---------------- + +Conform to the Fortran 2008 standard. + +Use <, >, <=, >=, ==, and /= rather than .lt., .gt., .le., .ge., .eq., and .ne. + +Do not use old-style character/array length (e.g. character*80, real*8). + +Always use a double colon :: when declaring a variable. + +Never use ``equivalence`` statements, ``common`` blocks, or ``data`` statements. + +------------ +C++-Specific +------------ + +Miscellaneous +------------- + +Conform to the C++11 standard. + +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: + +.. code-block:: C++ + + #ifndef MODULE_NAME_H + #define MODULE_NAME_H + ... + content + ... + #endif // MODULE_NAME_H + +Do not use using-directives e.g. ``using namespace foobar;`` + +Do not use C-style casting. Always use the C++-style casts ``static_cast``, +``const_cast``, or ``reinterpret_cast``. + +Curly braces +------------ + +For a function definition, the opening brace should be on the same line as the +end of the function definition. The closing brace should be on its own line. +If the entire function fits on one line, then the closing brace 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 ------