Cleaned up dox for Recon1d

adcroft · Oct 15, 2024 · e6d706e · e6d706e
1 parent a16fd6c
commit e6d706e
Show file tree

Hide file tree

Showing 16 changed files with 256 additions and 236 deletions.
diff --git a/docs/zotero.bib b/docs/zotero.bib
@@ -2947,18 +2947,3 @@ @article{Young1994
 	year={1994}
 }
 
-@article{Colella_Woodward_1984,
-	title = {The {Piecewise} {Parabolic} {Method} ({PPM}) for gas-dynamical simulations},
-	volume = {54},
-	issn = {0021-9991},
-	url = {http://www.sciencedirect.com/science/article/pii/0021999184901438},
-	doi = {10.1016/0021-9991(84)90143-8},
-	language = {en},
-	number = {1},
-	journal = {Journal of Computational Physics},
-	author = {Colella, Phillip and Woodward, Paul R},
-	month = apr,
-	year = {1984},
-	pages = {174--201},
-}
-
diff --git a/src/ALE/Recon1d_EMPLM_CWK.F90 b/src/ALE/Recon1d_EMPLM_CWK.F90
@@ -1,11 +1,10 @@
-!> Piecewise Linear Method 1D reconstruction
+!> Piecewise Linear Method 1D reconstruction in index space and boundary extrapolation
 !!
-!! This implementation of PLM follows Colella and Woodward, 1984, with cells resorting to PCM for
-!! extrema including first and last cells in column. The cell-wise reconstructions are limited so
-!! that the edge values (which are also the extrema in a cell) are bounded by the neighbors. The
-!! limiter yields monotonicity for the CFL<1 transport problem where parts of a cell can only move
-!! to a neighboring cell, but does not yield monotonic profiles for the general remapping problem.
-!! The first and last cells are always limited to PCM.
+!! This implementation of PLM follows Colella and Woodward, 1984 \cite colella1984, except for assuming
+!! uniform resolution so that the method is independent of grid spacing. The cell-wise reconstructions
+!! are limited so that the edge values (which are also the extrema in a cell) are bounded by the neighbors.
+!! The slope of the first and last cells are set so that the first interior edge values match the interior
+!! cell (i.e. extrapolates from the interior).
 module Recon1d_EMPLM_CWK
 
 ! This file is part of MOM6. See LICENSE.md for the license.
@@ -19,18 +18,20 @@ module Recon1d_EMPLM_CWK
 
 !> PLM reconstruction following Colella and Woodward, 1984
 !!
+!! Implemented by extending recon1d_mplm_cwk.
+!!
 !! The source for the methods ultimately used by this class are:
-!!   init()                 -> MPLM_CWK -> PLM_CW%init()
-!!   reconstruct()             *locally defined
-!!   average()              -> MPLM_CWK -> PLM_CW%average()
-!!   f()                    -> MPLM_CWK -> PLM_CW%f()
-!!   dfdx()                 -> MPLM_CWK -> PLM_CW%dfdx()
-!!   check_reconstruction() -> MPLM_CWK%check_reconstruction()
-!!   unit_tests()              *locally defined
-!!   destroy()              -> MPLM_CWK -> PLM_CW%destroy()
-!!   remap_to_sub_grid()    -> Recon1d%remap_to_sub_grid()
-!!   init_parent()          -> init()
-!!   reconstruct_parent()   -> MPLM_CWK%reconstruct()
+!! - init()                 -> recon1d_mplm_cwk -> recon1d_plm_cw.init()
+!! - reconstruct()             *locally defined
+!! - average()              -> recon1d_mplm_cwk -> recon1d_plm_cw.average()
+!! - f()                    -> recon1d_mplm_cwk -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_mplm_cwk -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction() -> recon1d_mplm_cwk.check_reconstruction()
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_mplm_cwk -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()    -> recon1d_type.remap_to_sub_grid()
+!! - init_parent()          -> init()
+!! - reconstruct_parent()   -> recon1d_mplm_cwk.reconstruct()
 type, extends (MPLM_CWK) :: EMPLM_CWK
 
 contains

diff --git a/src/ALE/Recon1d_EMPLM_WA.F90 b/src/ALE/Recon1d_EMPLM_WA.F90
@@ -1,7 +1,7 @@
 !> Extrapolated-Monotonized Piecewise Linear Method 1D reconstruction
 !!
-!! This extends MPLM_WA, following White and Adcroft, 2008, by extrapolating for the slopes of the
-!! first and last cells. This extrapolation is used by White et al., 2009 during grid-generation.
+!! This extends MPLM_WA, following White and Adcroft, 2008 \cite white2008, by extrapolating for the slopes of the
+!! first and last cells. This extrapolation is used by White et al., 2009, during grid-generation.
 module Recon1d_EMPLM_WA
 
 ! This file is part of MOM6. See LICENSE.md for the license.
@@ -15,17 +15,17 @@ module Recon1d_EMPLM_WA
 !> Extraplated Monotonic PLM reconstruction of White and Adcroft, 2008
 !!
 !! The source for the methods ultimately used by this class are:
-!!   init()                 -> MPLM_WA%init()              -> PLM_CW%init()
-!!   reconstruct()             *locally defined
-!!   average()              -> MPLM_WA%average()           -> PLM_CW%average()
-!!   f()                    -> MPLM_WA%f()                 -> PLM_CW%f()
-!!   dfdx()                 -> MPLM_WA%dfdx()              -> PLM_CW%dfdx()
-!!   check_reconstruction() -> MPLM_WA%check_reconstruction()
-!!   unit_tests()              *locally defined
-!!   destroy()              -> MPLM_WA%destroy()           -> PLM_CW%destroy()
-!!   remap_to_sub_grid()    -> MPLM_WA%remap_to_sub_grid() -> PLM_CW%remap_to_sub_grd() -> Recon1d%remap_to_sub_grid()
-!!   init_parent()          -> MPLM_WA%init_parent()       -> PLM_CW%init()
-!!   reconstruct_parent()   -> MPLM_WA%reconstruct()
+!! - init()                 -> recon1d_mplm_wa           -> recon1d_plm_cw.init()
+!! - reconstruct()             *locally defined
+!! - average()              -> recon1d_mplm_wa           -> recon1d_plm_cw.average()
+!! - f()                    -> recon1d_mplm_wa           -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_mplm_wa           -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction() -> recon1d_mplm_wa.check_reconstruction()
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_mplm_wa           -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()    -> recon1d_mplm_wa           -> recon1d_plm_cw        -> recon1d_type.remap_to_sub_grid()
+!! - init_parent()          -> recon1d_mplm_wa           -> recon1d_plm_cw.init()
+!! - reconstruct_parent()   -> recon1d_mplm_wa.reconstruct()
 type, extends (MPLM_WA) :: EMPLM_WA
 
 contains

diff --git a/src/ALE/Recon1d_EMPLM_WA_poly.F90 b/src/ALE/Recon1d_EMPLM_WA_poly.F90
@@ -1,7 +1,7 @@
 !> Extrapolated-Monotonized Piecewise Linear Method 1D reconstruction
 !!
-!! This extends MPLM_poly, following White and Adcroft, 2008, by extraplating for the slopes of the
-!! first and last cells. This extrapolation is used by White et al., 2009 during grid-generation.
+!! This extends MPLM_poly, following White and Adcroft, 2008 \cite white2008, by extraplating for the slopes of the
+!! first and last cells. This extrapolation is used by White et al., 2009, during grid-generation.
 !!
 !! This stores and evaluates the reconstruction using a polynomial representation which is not preferred
 !! but was the form used in OM4.
@@ -18,17 +18,17 @@ module Recon1d_EMPLM_WA_poly
 !> Extrapolation Limited Monotonic PLM reconstruction following White and Adcroft, 2008
 !!
 !! The source for the methods ultimately used by this class are:
-!!   init()                 -> MPLM_WA_poly%init()
-!!   reconstruct()          -> MPLM_WA_poly%reconstruct()
-!!   average()              -> MPLM_WA_poly%average()
-!!   f()                    -> MPLM_WA_poly%f()         -> MPLM_WA_poly%f()       -> PLM_CW%f()
-!!   dfdx()                 -> MPLM_WA_poly%dfdx()      -> MPLM_WA_poly%dfdx()    -> PLM_CW%dfdx()
-!!   check_reconstruction()    *locally defined
-!!   unit_tests()              *locally defined
-!!   destroy()              -> MPLM_WA_poly%destroy()   -> MPLM_WA%destroy()      -> PLM_CW%destroy()
-!!   remap_to_sub_grid()       *locally defined
-!!   init_parent()          -> MPLM_WA_poly%init()
-!!   reconstruct_parent()   -> MPLM_WA_poly%reconstruct()
+!! - init()                 -> recon1d_mplm_wa_poly.init()
+!! - reconstruct()          -> recon1d_mplm_wa_poly.reconstruct()
+!! - average()              -> recon1d_mplm_wa_poly.average()
+!! - f()                    -> recon1d_mplm_wa_poly           -> recon1d_mplm_wa -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_mplm_wa_poly           -> recon1d_mplm_wa -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction()    *locally defined
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_mplm_wa_poly           -> recon1d_mplm_wa -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()       *locally defined
+!! - init_parent()          -> recon1d_mplm_wa_poly           -> recon1d_mplm_wa.init()
+!! - reconstruct_parent()   -> recon1d_mplm_wa_poly           -> recon1d_mplm_wa.reconstruct()
 type, extends (MPLM_WA_poly) :: EMPLM_WA_poly
 
 contains

diff --git a/src/ALE/Recon1d_EPPM_CWK.F90 b/src/ALE/Recon1d_EPPM_CWK.F90
@@ -3,7 +3,7 @@
 !!
 !! This implementation of PPM follows Colella and Woodward, 1984, using uniform thickness
 !! and with cells resorting to PCM for local extrema. First and last cells use a PLM
-!! representation with linear extrapolation.
+!! representation with slope set by matching the edge of the first interior cell.
 module Recon1d_EPPM_CWK
 
 ! This file is part of MOM6. See LICENSE.md for the license.

diff --git a/src/ALE/Recon1d_MPLM_CWK.F90 b/src/ALE/Recon1d_MPLM_CWK.F90
@@ -1,10 +1,8 @@
-!> Piecewise Linear Method 1D reconstruction
+!> Piecewise Linear Method 1D reconstruction in index space
 !!
-!! This implementation of PLM follows Colella and Woodward, 1984, with cells resorting to PCM for
-!! extrema including first and last cells in column. The cell-wise reconstructions are limited so
-!! that the edge values (which are also the extrema in a cell) are bounded by the neighbors. The
-!! limiter yields monotonicity for the CFL<1 transport problem where parts of a cell can only move
-!! to a neighboring cell, but does not yield monotonic profiles for the general remapping problem.
+!! This implementation of PLM follows Colella and Woodward, 1984 \cite colella1984, except for assuming
+!! uniform resolution so that the method is independent of grid spacing. The cell-wise reconstructions
+!! are limited so that the edge values (which are also the extrema in a cell) are bounded by the neighbors.
 !! The first and last cells are always limited to PCM.
 module Recon1d_MPLM_CWK
 
@@ -19,18 +17,20 @@ module Recon1d_MPLM_CWK
 
 !> PLM reconstruction following Colella and Woodward, 1984
 !!
+!! Implemented by extending recon1d_plm_cwk.
+!!
 !! The source for the methods ultimately used by this class are:
-!!   init()                 -> MPLM_CWK -> PLM_CW%init()
-!!   reconstruct()             *locally defined
-!!   average()              -> MPLM_CWK -> PLM_CW%average()
-!!   f()                    -> MPLM_CWK -> PLM_CW%f()
-!!   dfdx()                 -> MPLM_CWK -> PLM_CW%dfdx()
-!!   check_reconstruction()    *locally defined
-!!   unit_tests()              *locally defined
-!!   destroy()              -> MPLM_CWK -> PLM_CW%destroy()
-!!   remap_to_sub_grid()    -> Recon1d%remap_to_sub_grid()
-!!   init_parent()          -> init()
-!!   reconstruct_parent()   -> reconstruct()
+!! - init()                 -> recon1d_plm_cwk -> recon1d_plm_cw.init()
+!! - reconstruct()             *locally defined
+!! - average()              -> recon1d_plm_cwk -> recon1d_plm_cw.average()
+!! - f()                    -> recon1d_plm_cwk -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_plm_cwk -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction()    *locally defined
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_plm_cwk -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()    -> recon1d_type.remap_to_sub_grid()
+!! - init_parent()          -> init()
+!! - reconstruct_parent()   -> reconstruct()
 type, extends (PLM_CWK) :: MPLM_CWK
 
 contains

diff --git a/src/ALE/Recon1d_MPLM_WA.F90 b/src/ALE/Recon1d_MPLM_WA.F90
@@ -1,8 +1,12 @@
 !> Monotonized Piecewise Linear Method 1D reconstruction
 !!
-!! This implementation of PLM follows White and Adcroft, 2008. The PLM slopes are first limited following
-!! Colella and Woodward, 1984, but are then further limited to ensure the edge values moving across cell
-!! boundaries are monotone.  The first and last cells are always limited to PCM.
+!! This implementation of PLM follows White and Adcroft, 2008 \cite white2008.
+!! The PLM slopes are first limited following Colella and Woodward, 1984, but are then
+!! further limited to ensure the edge values moving across cell boundaries are monotone.
+!! The first and last cells are always limited to PCM.
+!!
+!! This differs from recon1d_mplm_wa_poly in the internally not polynomial representations
+!! are referred to.
 module Recon1d_MPLM_WA
 
 ! This file is part of MOM6. See LICENSE.md for the license.
@@ -16,17 +20,17 @@ module Recon1d_MPLM_WA
 !> Limited Monotonic PLM reconstruction following White and Adcroft, 2008
 !!
 !! The source for the methods ultimately used by this class are:
-!!   init()                 -> PLM_CW%init()
-!!   reconstruct()             *locally defined
-!!   average()              -> PLM_CW%average()
-!!   f()                    -> PLM_CW%f()
-!!   dfdx()                 -> PLM_CW%dfdx()
-!!   check_reconstruction()    *locally defined
-!!   unit_tests()              *locally defined
-!!   destroy()              -> PLM_CW%destroy()
-!!   remap_to_sub_grid()    -> PLM_CW%remap_to_sub_grd() -> Recon1d%remap_to_sub_grid()
-!!   init_parent()          -> PLM_CW%init()
-!!   reconstruct_parent()   -> reconstruct()
+!! - init()                 -> recon1d_plm_cw.init()
+!! - reconstruct()             *locally defined
+!! - average()              -> recon1d_plm_cw.average()
+!! - f()                    -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction()    *locally defined
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()    -> recon1d_plm_cw           -> recon1d_type.remap_to_sub_grid()
+!! - init_parent()          -> recon1d_plm_cw.init()
+!! - reconstruct_parent()   -> reconstruct()
 type, extends (PLM_CW) :: MPLM_WA
 
 contains

diff --git a/src/ALE/Recon1d_MPLM_WA_poly.F90 b/src/ALE/Recon1d_MPLM_WA_poly.F90
@@ -1,11 +1,12 @@
 !> Monotonized Piecewise Linear Method 1D reconstruction using polynomial representation
 !!
-!! This implementation of PLM follows White and Adcroft, 2008. The PLM slopes are first limited following
-!! Colella and Woodward, 1984, but are then further limited to ensure the edge values moving across cell
-!! boundaries are monotone.  The first and last cells are always limited to PCM.
+!! This implementation of PLM follows White and Adcroft, 2008 \cite white2008.
+!! The PLM slopes are first limited following Colella and Woodward, 1984, but are then
+!! further limited to ensure the edge values moving across cell boundaries are monotone.
+!! The first and last cells are always limited to PCM.
 !!
-!! This stores and evaluates the reconstruction using a polynomial representation which is not preferred
-!! but was the form used in OM4.
+!! This stores and evaluates the reconstruction using a polynomial representation which is
+!! not preferred but was the form used in OM4.
 module Recon1d_MPLM_WA_poly
 
 ! This file is part of MOM6. See LICENSE.md for the license.
@@ -19,17 +20,17 @@ module Recon1d_MPLM_WA_poly
 !> Limited Monotonic PLM reconstruction following White and Adcroft, 2008
 !!
 !! The source for the methods ultimately used by this class are:
-!!   init()                    *locally defined
-!!   reconstruct()             *locally defined
-!!   average()                 *locally defined
-!!   f()                    -> MPLM_WA%f()         -> PLM_CW%f()
-!!   dfdx()                 -> MPLM_WA%dfdx()      -> PLM_CW%dfdx()
-!!   check_reconstruction()    *locally defined
-!!   unit_tests()              *locally defined
-!!   destroy()              -> MPLM_WA%destroy()   -> PLM_CW%destroy()
-!!   remap_to_sub_grid()       *locally defined
-!!   init_parent()          -> init()
-!!   reconstruct_parent()   -> reconstruct()
+!! - init()                    *locally defined
+!! - reconstruct()             *locally defined
+!! - average()                 *locally defined
+!! - f()                    -> recon1d_mplm_wa   -> recon1d_plm_cw.f()
+!! - dfdx()                 -> recon1d_mplm_wa   -> recon1d_plm_cw.dfdx()
+!! - check_reconstruction()    *locally defined
+!! - unit_tests()              *locally defined
+!! - destroy()              -> recon1d_mplm_wa   -> recon1d_plm_cw.destroy()
+!! - remap_to_sub_grid()       *locally defined
+!! - init_parent()          -> init()
+!! - reconstruct_parent()   -> reconstruct()
 type, extends (MPLM_WA) :: MPLM_WA_poly
 
   ! Legacy representation

diff --git a/src/ALE/Recon1d_PLM_CW.F90 b/src/ALE/Recon1d_PLM_CW.F90
@@ -1,11 +1,10 @@
 !> Piecewise Linear Method 1D reconstruction
 !!
-!! This implementation of PLM follows Colella and Woodward, 1984, with cells resorting to PCM for
-!! extrema including first and last cells in column. The cell-wise reconstructions are limited so
-!! that the edge values (which are also the extrema in a cell) are bounded by the neighbors. The
-!! limiter yields monotonicity for the CFL<1 transport problem where parts of a cell can only move
-!! to a neighboring cell, but does not yield monotonic profiles for the general remapping problem.
-!! The first and last cells are always limited to PCM.
+!! This implementation of PLM follows Colella and Woodward, 1984 \cite colella1984, with cells
+!! resorting to PCM for extrema including the first and last cells in column.
+!! The cell-wise reconstructions are limited so that the edge values (which are also the extrema
+!! in a cell) are bounded by the neighboring cell means.
+!! This does not yield monotonic profiles for the general remapping problem.
 module Recon1d_PLM_CW
 
 ! This file is part of MOM6. See LICENSE.md for the license.
@@ -19,17 +18,17 @@ module Recon1d_PLM_CW
 !> PLM reconstruction following Colella and Woodward, 1984
 !!
 !! The source for the methods ultimately used by this class are:
-!!   init()                    *locally defined
-!!   reconstruct()             *locally defined
-!!   average()                 *locally defined
-!!   f()                       *locally defined
-!!   dfdx()                    *locally defined
-!!   check_reconstruction()    *locally defined
-!!   unit_tests()              *locally defined
-!!   destroy()                 *locally defined
-!!   remap_to_sub_grid()    -> Recon1d%remap_to_sub_grid()
-!!   init_parent()          -> init()
-!!   reconstruct_parent()   -> reconstruct()
+!! - init()                    *locally defined
+!! - reconstruct()             *locally defined
+!! - average()                 *locally defined
+!! - f()                       *locally defined
+!! - dfdx()                    *locally defined
+!! - check_reconstruction()    *locally defined
+!! - unit_tests()              *locally defined
+!! - destroy()                 *locally defined
+!! - remap_to_sub_grid()    -> recon1d_type.remap_to_sub_grid()
+!! - init_parent()          -> init()
+!! - reconstruct_parent()   -> reconstruct()
 type, extends (Recon1d) :: PLM_CW
 
   real, allocatable :: ul(:) !< Left edge value [A]