Merge pull request #432 from GiudGiud/PR_docs3

Fix arguments list for doxygen
mit-crpg · Jul 13, 2019 · 7940c0b · 7940c0b
2 parents 3013360 + 019c0ed
commit 7940c0b
Show file tree

Hide file tree

Showing 36 changed files with 107 additions and 85 deletions.
diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile
@@ -614,7 +614,7 @@ WARNINGS               = YES
 # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
 # automatically be disabled.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some
@@ -1789,4 +1789,4 @@ GENERATE_LEGEND        = YES
 # remove the intermediate dot files that are used to generate
 # the various graphs.
 
-DOT_CLEANUP            = YES
+DOT_CLEANUP            = YES
diff --git a/docs/img/cmfd-axial-prolongation.png → docs/img/cmfd-axial-interpolation.png b/docs/img/cmfd-axial-prolongation.png → docs/img/cmfd-axial-interpolation.png
diff --git a/docs/source/api/cmfd.txt → docs/source/api/cmfd.rst b/docs/source/api/cmfd.txt → docs/source/api/cmfd.rst
diff --git a/docs/source/api/cpulssolver.txt → docs/source/api/cpulssolver.rst b/docs/source/api/cpulssolver.txt → docs/source/api/cpulssolver.rst
@@ -1,8 +1,8 @@
 .. _cpulssolver:
 
-=========
+===========
 CPULSSolver
-=========
+===========
 
 .. doxygenclass:: CPULSSolver
    :project: OpenMOC

diff --git a/docs/source/api/halfspace.txt → docs/source/api/halfspace.rst b/docs/source/api/halfspace.txt → docs/source/api/halfspace.rst
diff --git a/docs/source/api/region.txt → docs/source/api/region.rst b/docs/source/api/region.txt → docs/source/api/region.rst
diff --git a/docs/source/api/trackgenerator3D.txt → docs/source/api/trackgenerator3D.rst b/docs/source/api/trackgenerator3D.txt → docs/source/api/trackgenerator3D.rst
diff --git a/docs/source/api/zcylinder.txt → docs/source/api/zcylinder.rst b/docs/source/api/zcylinder.txt → docs/source/api/zcylinder.rst
diff --git a/docs/source/methods/cmfd.rst b/docs/source/methods/cmfd.rst
@@ -4,7 +4,7 @@
 Coarse Mesh Finite Difference Acceleration
 ==========================================
 
-While MOC offers many benefits including treatment of complex geometries and amenability to parallelization, it suffers from slow convergence which necessitates the use of acceleration methods. Numerous acceleration schemes have been proposed for MOC such as CMFD [Smith-1983]_, coarse mesh rebalance (CMR) [Yamamoto-2002]_, [Yamamoto-2005]_, [Yamamoto-2008]_, [Lewis]_, and low order transport operator acceleration [Li]_ with CMFD being the most widely adopted due to its simplicity and acceleration performance. OpenMOC uses the CMFD nonlinear diffusion acceleration (NDA) scheme to reduce the number of iterations required for convergence. Acceleration schemes, such as NDA, are necessary when solving full-core problems which require thousands of power iterations in LWR problems that tend to have high dominance ratios. CMFD was first proposed by Smith [1]_ and has been widely used in accelerating neutron diffusion and transport problems for many years. In particular, it has been shown that CMFD acceleration gives :math:`>` 100x speedups on large LWR problems [Smith-2002]_.
+While MOC offers many benefits including treatment of complex geometries and amenability to parallelization, it suffers from slow convergence which necessitates the use of acceleration methods. Numerous acceleration schemes have been proposed for MOC such as CMFD [Smith-1983]_, coarse mesh rebalance (CMR) [Yamamoto-2002]_, [Yamamoto-2005]_, [Yamamoto-2008]_, [Lewis]_, and low order transport operator acceleration [Li]_ with CMFD being the most widely adopted due to its simplicity and acceleration performance. OpenMOC uses the CMFD nonlinear diffusion acceleration (NDA) scheme to reduce the number of iterations required for convergence. Acceleration schemes, such as NDA, are necessary when solving full-core problems which require thousands of power iterations in LWR problems that tend to have high dominance ratios. CMFD was first proposed by Smith [Smith-1983]_ and has been widely used in accelerating neutron diffusion and transport problems for many years. In particular, it has been shown that CMFD acceleration gives :math:`>` 100x speedups on large LWR problems [Smith-2002]_.
 
 CMFD acceleration functions by using the solution of a coarse mesh diffusion problem to accelerate the convergence of a fine mesh transport problem. It is implemented by overlaying a 2D (or 3D) cartesian mesh over an FSR mesh. :ref:`Figure 1 <figure-fsr-mesh-regions>` gives an illustration of the FSR mesh layout and coarse mesh layout used for solving a 17 x 17 PWR assembly problem.
 
@@ -38,7 +38,7 @@ Variable                                   Description                    Variab
 :math:`{\mathbf{g}}, {\mathbf{g}} \prime`  Energy group index             :math:`x, y`         Position variable
 =========================================  =============================  ===================  =============================
 
-.. _gen-coarse-mesh
+.. _gen-coarse-mesh:
 
 Cross Section Generation
 ========================
@@ -186,7 +186,7 @@ The neutron balance equation in a cell then becomes:
 
 Note that :eq:`eqn-alg-net-current` is the algebraic net current based on the finite difference approximation being applied across the surface of two neighboring cells and not the actual net current in the MOC problem. The actual current from the MOC problem is computed by accumulating the current contribution from every segment that crosses a surface as will be shown in the :ref:`Section 7.3 <nonlinear-dif-coef>`.
 
-.. _nonlinear-dif-coef
+.. _nonlinear-dif-coef:
 
 Introduction to nonlinear diffusion correction factors
 ======================================================
@@ -263,7 +263,7 @@ As shown in :ref:`Figure 1 <figure-fsr-mesh-regions>` the CMFD mesh is often app
 Note that the effective diffusion coefficient depends on the width of the cell and is therefore directional in a 2D (or 3D) mesh. :eq:`eqn-optic-thick-d` can also be used to compute the effective diffusion coefficient in the y-direction, which will differ from the effective diffusion coefficient in the x-direction if the cell is not square. As the size of the cell approaches zero and the optical thickness of the cell approaches the optically thin limit, the effective diffusion coefficient will approach the material diffusion coefficient. For simplicity, we continue to use the surface diffusion coefficient terms in the rest of this thesis without the "eff" superscript.
 
 
-.. _corner-crossings
+.. _corner-crossings:
 
 Treatment of coarse mesh cell corner crossings
 ==============================================

diff --git a/docs/source/methods/eigenvalue_calculations.rst b/docs/source/methods/eigenvalue_calculations.rst
@@ -165,7 +165,8 @@ Exponential Evaluation Method
 
 The algorithms described in this section require a number of floating point operations, including addition, subtraction, multiplication and division. The most expensive operation, however, is the exponential evaluation needed to compute :math:`e^{-\tau_{k,i,g,p}}`. All mainstream compilers provide a library with intrinsic mathematical routines, including an exponential evaluator. One method of avoiding the computational cost of explicitly evaluating exponentials is through the use of a linear interpolation table. A sequence of linear approximations to a simple exponential is illustrated in :ref:`Figure 2 <figure-exponential-tangent>`. In addition to reducing the flop count for an exponential evaluation, the table may be constructed to fit completely in :math:`L1` cache and as a result, can improve the memory performance of the MOC transport sweep algorithm.
 
-.. _warning: The linear interpolation tables were first replaced by quadratic interpolation tables, and those are now superseded by rational fraction approximations, which are faster to compute and more accurate. See [Giudicelli-2019]_ for more details.
+#NOTE
+The linear interpolation tables were first replaced by quadratic interpolation tables, and those are now superseded by rational fraction approximations, which are faster to compute and more accurate. See [Giudicelli-2019]_ for more details.
 
 .. _figure-exponential-tangent:
 
@@ -176,7 +177,7 @@ The algorithms described in this section require a number of floating point oper
 
    **Figure 2**: Linear interpolation of an exponential.
 
-The OpenMOC code incorporates an option to evaluate exponentials using either the compiler's exponential intrinsic function or a linear interpolation table. The following expression for the maximum approximation error :math:`\epsilon` for the linear interpolation method was discussed and validated by [Yamamoto]_:
+The OpenMOC code incorporates an option to evaluate exponentials using either the compiler's exponential intrinsic function or a linear interpolation table. The following expression for the maximum approximation error :math:`\epsilon` for the linear interpolation method was discussed and validated by [Yamamoto-2004]_:
 
 .. math::
    :label: exponential-error
@@ -253,5 +254,5 @@ References
 
 .. [Giudicelli-2019] Giudicelli G., Forget B. and Smith K., Adding a third level of parallelism to OpenMOC, an open-source deterministic neutron transport solver, M&C 2019
 
-.. [Yamamoto] Yamamoto A., Kitamura Y. and Yamane Y., Computational efficiencies of approximated exponential functions for transport calculations of the characteristics method, Annals of Nuclear Energy, vol. 30, 2004
+.. [Yamamoto-2004] Yamamoto A., Kitamura Y. and Yamane Y., Computational efficiencies of approximated exponential functions for transport calculations of the characteristics method, Annals of Nuclear Energy, vol. 30, 2004
 
diff --git a/docs/source/methods/index.rst b/docs/source/methods/index.rst
@@ -13,5 +13,6 @@ Theory and Methodology
     eigenvalue_calculations
     constructive_solid_geometry
     track_generation
+    parallelization
     cmfd
     krylov
diff --git a/docs/source/methods/introduction.rst b/docs/source/methods/introduction.rst
@@ -6,7 +6,7 @@ Introduction
 
 The method of characteristics is one technique for solving partial differential equations.  MOC is one of the most common methods with real world applications in production lattice physics tools used today [Smith]_. The prospects for the MOC algorithm as an eventual successor to low-order diffusion-based method for reactor analysis are promising, and extensive research efforts into the efficient use of the algorithm are ongoing [Wu]_, [Taylor]_, [Liu]_, [Talamo]_. As a result, there is an opportunity for advanced parallel algorithms for high performance computing machines and nonlinear acceleration schemes to propel the application of MOC to full-core reactor physics calculations.
 
-:ref:`Section 2 <method_of_characteristics>` describes how the method of characteristics is applied to solve the steady-state neutron transport equation in OpenMOC. :ref:`Section 3 <eigenvalue_calculations>` presents the algorithms implemented in OpenMOC to solve the MOC equations. :ref:`Section 4 <constructive_solid_geometry>` discusses the constructive solid geometry formulation used to represent geometric models in OpenMOC. :ref:`Section 5 <track_generation>` reviews the angular quadrature and track generation algorithm in OpenMOC. Finally, :ref:`Section 5 <parallelization>` outlines the parallel algorithms in OpenMOC for high performance computing platforms while :ref:`Section 6 <cmfd>` describes CMFD, a nonlinear acceleration method in OpenMOC.
+:ref:`Section 2 <method_of_characteristics>` describes how the method of characteristics is applied to solve the steady-state neutron transport equation in OpenMOC. :ref:`Section 3 <eigenvalue_calculations>` presents the algorithms implemented in OpenMOC to solve the MOC equations. :ref:`Section 4 <constructive_solid_geometry>` discusses the constructive solid geometry formulation used to represent geometric models in OpenMOC. :ref:`Section 5 <track_generation>` reviews the angular quadrature and track generation algorithm in OpenMOC. :ref:`Section 6 <parallelization>` outlines the parallel algorithms in OpenMOC for high performance computing platforms while :ref:`Section 7 <cmfd>` describes CMFD, a nonlinear acceleration method in OpenMOC. :ref:`Section 7 <krylov>` gives elements for replacing the fission iteration algorithm by Krylov subspace algorithms.
 
 
 References

diff --git a/docs/source/methods/method_of_characteristics.rst b/docs/source/methods/method_of_characteristics.rst
@@ -273,7 +273,7 @@ Another common approximation for MOC is to assume that the source :math:`Q_g` is
 The Linear Source Region Approximation
 ======================================
 
-A more accurate description of the source in spatial regions is to assume a linear variation. This is typically sufficient for the moderator in a PWR, when each channel is also cut in azimuthal source regions. The source then varies along each characteristic lines. The reader should refer themselves to `Ferrer`_ and `G. Gunow PhD Thesis`_ for more details on the track-based linear source approximation and its implementation in OpenMOC.
+A more accurate description of the source in spatial regions is to assume a linear variation. This is typically sufficient for the moderator in a PWR, when each channel is also cut in azimuthal source regions. The source then varies along each characteristic lines. The reader should refer themselves to [Ferrer]_ and [Gunow]_ for more details on the track-based linear source approximation and its implementation in OpenMOC.
 
 .. math::
    :label: linear-source
@@ -445,5 +445,5 @@ References
 
 .. [Ferrer] R. Ferrer and J. Rhodes, “A Linear Source Approximation Scheme for the Method of Characteristics,” volume 77, p. 119–136, 1981.
 
-.. [G. Gunow PhD Thesis] G. Gunow "Full Core 3D Neutron Transport Simulation Using the Method of Characteristics with Linear Sources", PhD Thesis, Massachusetts Institute of Technology (2018).
+.. [Gunow] G. Gunow "Full Core 3D Neutron Transport Simulation Using the Method of Characteristics with Linear Sources", PhD Thesis, Massachusetts Institute of Technology (2018).
 
diff --git a/docs/source/methods/parallelization.rst b/docs/source/methods/parallelization.rst
@@ -0,0 +1,7 @@
+.. _parallelization:
+
+======================================================================
+Parallelization of the Method of Characteristics for neutron transport
+======================================================================
+
+Coming soon
diff --git a/src/CPUSolver.cpp b/src/CPUSolver.cpp
@@ -60,7 +60,7 @@ int CPUSolver::getNumThreads() {
  *          fluxes = solver.getFluxes(num_fluxes)
  * @endcode
  *
- * @param fluxes an array of FSR scalar fluxes in each energy group
+ * @param out_fluxes an array of FSR scalar fluxes in each energy group
  * @param num_fluxes the total number of FSR flux values
  */
 void CPUSolver::getFluxes(FP_PRECISION* out_fluxes, int num_fluxes) {
@@ -161,9 +161,9 @@ void CPUSolver::setNumThreads(int num_threads) {
 
 /**
  * @brief Set the flux array for use in transport sweep source calculations.
- * @detail This is a helper method for the checkpoint restart capabilities,
- *         as well as the IRAMSolver in the openmoc.krylov submodule. This
- *         routine may be used as follows from within Python:
+ * @details This is a helper method for the checkpoint restart capabilities,
+ *          as well as the IRAMSolver in the openmoc.krylov submodule. This
+ *          routine may be used as follows from within Python:
  *
  * @code
  *          fluxes = numpy.random.rand(num_FSRs * num_groups, dtype=np.float)

diff --git a/src/Cell.cpp b/src/Cell.cpp
@@ -300,7 +300,7 @@ double* Cell::getRotationMatrix() {
  *          rotation = cell.getRotation(3)
  * @endcode
  *
- * @param rotation an array of rotation angles of length 3 for x, y and z
+ * @param rotations an array of rotation angles of length 3 for x, y and z
  * @param num_axes the number of axes (this must always be 3)
  * @param units the angular units in "radians" or "degrees" (default)
  */
@@ -345,7 +345,7 @@ double* Cell::getTranslation() {
  *          translation = cell.retrieveTranslation(3)
  * @endcode
  *
- * @param translation an array of translations of length 3 for x, y and z
+ * @param translations an array of translations of length 3 for x, y and z
  * @param num_axes the number of axes (this must always be 3)
  */
 void Cell::retrieveTranslation(double* translations, int num_axes) {
@@ -1182,7 +1182,7 @@ void Cell::addNeighborCell(Cell* cell) {
  *          is within the Region. This point is only inside the Cell if it
  *          is on the same side of every Surface bounding the Cell.
  * @param point a pointer to a Point
- * @returns true if the Point is inside the Cell; otherwise false
+ * @return true if the Point is inside the Cell; otherwise false
  */
 bool Cell::containsPoint(Point* point) {
 
@@ -1213,6 +1213,7 @@ bool Cell::containsPoint(Point* point) {
  *          is on the same side of the Surface. This Point is only inside
  *          the Cell if it is on the same side of every Surface in the Cell.
  * @param coords a pointer to a localcoord
+ * @return whether the cell contains the coords or not
  */
 bool Cell::containsCoords(LocalCoords* coords) {
   return containsPoint(coords->getPoint());
@@ -1226,6 +1227,7 @@ bool Cell::containsCoords(LocalCoords* coords) {
  * @details If the trajectory will not intersect any of the Surfaces in the
  *          Cell returns INFINITY.
  * @param coords a pointer to a localcoords
+ * @return distance to nearest intersection with the cell's region boundaries
  */
 double Cell::minSurfaceDist(LocalCoords* coords) {
   if (_region == NULL)
@@ -1245,7 +1247,7 @@ double Cell::minSurfaceDist(LocalCoords* coords) {
  *        (in radians from \f$[0,2\pi]\f$)
  * @param polar the polar angle of the trajectory
  *        (in radians from \f$[0,\pi]\f$)
- * @param min_intersection a pointer to the intersection Point that is found
+ * @return distance to nearest intersection with the cell's region boundaries
  */
 double Cell::minSurfaceDist(Point* point, double azim, double polar) {
   if (_region == NULL)

diff --git a/src/Cmfd.cpp b/src/Cmfd.cpp
@@ -253,7 +253,7 @@ Cmfd::~Cmfd() {
 
 /**
  * @brief Set the number of Mesh cells in a row.
- * @param number of Mesh cells in a row
+ * @param num_x number of Mesh cells in a row
  */
 void Cmfd::setNumX(int num_x) {
 
@@ -272,7 +272,7 @@ void Cmfd::setNumX(int num_x) {
 
 /**
  * @brief Set the number of Mesh cells in a column.
- * @param number of Mesh cells in a column
+ * @param num_y number of Mesh cells in a column
  */
 void Cmfd::setNumY(int num_y) {
 
@@ -291,7 +291,7 @@ void Cmfd::setNumY(int num_y) {
 
 /**
  * @brief Set the number of Mesh cells in the z-direction.
- * @param number of Mesh cells in the z direction
+ * @param num_z number of Mesh cells in the z direction
  */
 void Cmfd::setNumZ(int num_z) {
 
@@ -1963,8 +1963,8 @@ Lattice* Cmfd::getLattice() {
 /**
  * @brief Add an FSR ID to a vector that contains all the FSR IDs
  *        contained within a CMFD mesh cell.
- * @param The CMFD cell ID.
- * @param The FSR ID.
+ * @param cmfd_cell the CMFD cell ID.
+ * @param fsr_id the FSR ID.
  */
 void Cmfd::addFSRToCell(int cmfd_cell, long fsr_id) {
   _cell_fsrs.at(cmfd_cell).push_back(fsr_id);
@@ -1973,7 +1973,7 @@ void Cmfd::addFSRToCell(int cmfd_cell, long fsr_id) {
 
 /**
  * @brief Set the number of MOC energy groups.
- * @param number of MOC energy groups
+ * @param num_groups number of MOC energy groups
  */
 void Cmfd::setNumMOCGroups(int num_groups) {
   _num_moc_groups = num_groups;
@@ -2000,7 +2000,7 @@ int Cmfd::getNumCells() {
 
 /**
  * @brief set the number of FSRs.
- * @param the number of FSRs
+ * @param num_fsrs the number of FSRs
  */
 void Cmfd::setNumFSRs(long num_fsrs) {
   _num_FSRs = num_fsrs;
@@ -2511,7 +2511,7 @@ void Cmfd::setBoundary(int side, boundaryType boundary) {
 
 /**
  * @brief Get the boundaryType for one side of the CMFD mesh.
- * @param the CMFD mesh surface ID.
+ * @param side the CMFD mesh surface ID.
  * @return the boundaryType for the surface.
  */
 int Cmfd::getBoundary(int side) {
@@ -3311,7 +3311,7 @@ double Cmfd::getDistanceToCentroid(Point* centroid, int cell_id,
 
 /**
  * @brief Set a pointer to the Geometry.
- * @param goemetry A pointer to a Geometry object.
+ * @param geometry A pointer to a Geometry object.
  */
 void Cmfd::setGeometry(Geometry* geometry) {
   _geometry = geometry;
@@ -3761,7 +3761,7 @@ void Cmfd::initialize() {
  * @brief Initialize the CMFD lattice and compute mesh dimensions, considering
  *        both uniform/non-uniform and 2D/3D cases.
  * @param offset the offset point of the CMFD Lattice
- * @param whether CMFD will be used in a 2D simulation (true) or 3D
+ * @param is_2D whether CMFD will be used in a 2D simulation (true) or 3D
  */
 void Cmfd::initializeLattice(Point* offset, bool is_2D) {
 
@@ -4073,7 +4073,7 @@ CMFD_PRECISION Cmfd::getSurfaceWidth(int surface, int global_ind) {
 /**
  * @brief Returns the width of the surface perpendicular to a given surface
  * @param surface A surface index, from 0 to NUM_FACES - 1
- * @paran global_ind The CMFD cell global index
+ * @param global_ind The CMFD cell global index
  * @return The perpendicular surface width
  */
 CMFD_PRECISION Cmfd::getPerpendicularSurfaceWidth(int surface, int global_ind) {

diff --git a/src/Cmfd.h b/src/Cmfd.h
@@ -549,7 +549,8 @@ inline int Cmfd::getGlobalCMFDCell(int cmfd_cell) {
  *        the appropriate CMFD mesh cell surface.
  * @param curr_segment the current Track segment
  * @param track_flux the outgoing angular flux for this segment
- * @param polar_weights array of polar weights for some azimuthal angle
+ * @param azim_index azimuthal index of track angle
+ * @param polar_index polar index of track angle
  * @param fwd boolean indicating direction of integration along segment
  */
 inline void Cmfd::tallyCurrent(segment* curr_segment, float* track_flux,