Add template for RAG metadata in tests

src/formal/divergence_1D_s.F90

@@ -27,6 +27,11 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
 
 #endif
 
+  ! PURPOSE: Definition of procedure to compute the product of a scalar and a divergence
+  ! KEYWORDS: scalar multiplication
+  ! CONTEXT: Invoke this function via the binary infix operator "*" with scalar and divergence left- and
+  !          right-hand operands, respectively
+
   module procedure premultiply_scalar_1D
     call_julienne_assert(size(scalar_1D%values_) .equalsExpected. size(divergence_1D%values_) + 2)
     scalar_x_divergence_1D%tensor_1D_t = &
@@ -38,18 +43,42 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
 #endif
     call_julienne_assert(size(scalar_x_divergence_1D%weights_) .equalsExpected. size(divergence_1D%values_)+2)
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to compute the product of a divergence and a scalar
+  ! KEYWORDS: scalar multiplication
+  ! CONTEXT: Invoke this function via the binary infix operator "*" with divergence and scalar left- and
+  !          right-hand operands, respectively
 
   module procedure postmultiply_scalar_1D
     scalar_x_divergence_1D = premultiply_scalar_1D(scalar_1D, divergence_1D) 
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to provide the cell-centered values of divergences.
+  ! KEYWORDS: staggered grid, divergence
+  ! CONTEXT: Invoke this function via the "values" generic binding to produce discrete divergence values.
 
   module procedure divergence_1D_values
     cell_centered_values = self%values_
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to provide staggered-grid locations at which divergence values are stored: cell centers.
+  ! KEYWORDS: cell centers, staggered grid, divergence
+  ! CONTEXT: Invoke this function via the "grid" generic binding to produce discrete gradient-vector locations for
+  !          initialization-function sampling, printing, or plotting.
 
   module procedure divergence_1D_grid
     cell_centers = cell_center_locations(self%x_min_, self%x_max_, self%cells_)
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to compute the quadrature weights for use in the mimetic inner products of a scalar
+  !          and the divergence of a vector.
+  ! KEYWORDS: quadrature, numerical integration, coefficients, weights
+  ! CONTEXT: Invoke this function via the "weights" generic binding to produce the quadrature weights
+  !          associated with mimetic approximations to divergences.
 
   module procedure divergence_1D_weights
       integer c 
@@ -72,5 +101,5 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
       call_julienne_assert(self%cells_ .isAtLeast. 2*size(skin))
       call_julienne_assert(size(weights) .equalsExpected. self%cells_+2)
   end procedure
-
-end submodule divergence_1D_s
+  ! END CODE CHUNK
+end submodule divergence_1D_s

src/formal/divergence_operator_1D_s.F90

@@ -36,6 +36,10 @@ pure function negate_and_flip(A) result(Ap)
 
 #endif
 
+  ! PURPOSE: Definition of procedure to construct an object representing a 1D mimetic divergence operator.
+  ! KEYWORDS: 1D, divergence operator, sparse matrix, constructor
+  ! CONTEXT: Use this type to assemble a divergence-operator matrix for printing.
+
   module procedure construct_1D_divergence_operator
 
     double precision, allocatable :: Ap(:,:)
@@ -100,6 +104,7 @@ pure function M(k, dx) result(row)
     end function
 
   end procedure construct_1D_divergence_operator
+  ! END CODE CHUNK
 
   module procedure submatrix_A_rows
     call_julienne_assert(allocated(self%upper_))
@@ -186,4 +191,4 @@ pure function e(dir, length) result(unit_vector)
 
   end procedure
 
-end submodule divergence_operator_1D_s
+end submodule divergence_operator_1D_s

src/formal/gradient_1D_s.F90

@@ -16,6 +16,12 @@
 
 contains
 
+  ! PURPOSE: Definition of procedure to compute the quadrature weights for use in the mimetic inner products of a vector
+  !          and the gradient of a scalar.
+  ! KEYWORDS: quadrature, numerical integration, coefficients, weights
+  ! CONTEXT: Inovke this function via the "weights" generic binding to produce the quadrature weights
+  !          associated with mimetic approximations to gradients.
+
   module procedure gradient_1D_weights
 
     integer face
@@ -38,6 +44,12 @@
     call_julienne_assert(size(weights) .equalsExpected. self%cells_ + 1)
 
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to compute the scalar (dot) product of a vector and the gradient of a scalar.
+  ! KEYWORDS: scalar product, dot product, inner product
+  ! CONTEXT: Inovke this function via the .dot. binary infix operator in expressions of the form
+  !          g .dot. b with a gradient_1D_t g and a vector_1D_t b.
 
   module procedure dot
     call_julienne_assert(size(gradient_1D%values_) .equalsExpected. size(vector_1D%values_))
@@ -59,5 +71,5 @@
     vector_dot_gradient_1D%weights_ = gradient_1D%gradient_1D_weights()
 #endif
   end procedure
-
+  ! END CODE CHUNK
 end submodule gradient_1D_s

src/formal/gradient_operator_1D_s.F90

@@ -36,7 +36,11 @@ pure function negate_and_flip(A) result(Ap)
   end function
 
 #endif
-
+
+  ! PURPOSE: Definition of procedure to construct a new mimetic gradient-operator matrix representation of kth order for 1D cells of width dx.
+  ! KEYWORDS: 1D, gradient-operator constructor, sparse matrix
+  ! CONTEXT: Use this function to construct a sparse-matrix represntation of a mimetic gradient operator.
+
   module procedure construct_1D_gradient_operator
 
     call_julienne_assert(cells .isAtLeast. 2*k)
@@ -92,6 +96,7 @@ pure function corbino_castillo_M(k, dx) result(row)
     end function
 
   end procedure construct_1D_gradient_operator
+  ! END CODE CHUNK
 
   module procedure gradient_matrix_multiply
 
@@ -168,4 +173,4 @@ pure function e(dir, length) result(unit_vector)
 
   end procedure
 
-end submodule gradient_operator_1D_s
+end submodule gradient_operator_1D_s

src/formal/laplacian_s.f90

@@ -5,8 +5,13 @@
   implicit none
 contains
 
+  ! PURPOSE: Definition of procedure to report the number of boundary-adjacent locations at which the Laplacian has reduced-order accuracy.
+  ! KEYWORDS: Laplacian, boundary, order of accuracy
+  ! CONTEXT: Use this function to determine the region of slightly slower convergence for mimetic Laplacian approximations.
+
   module procedure reduced_order_boundary_depth
     num_nodes = self%boundary_depth_
   end procedure
+  ! END CODE CHUNK
 
 end submodule laplacian_s

src/formal/mimetic_operators_1D_m.F90

@@ -36,6 +36,10 @@ pure module function construct_matrix_operator(upper, inner, lower) result(mimet
 
   end interface
 
+  ! PURPOSE: Definition of type to encapsulate a one-dimenstional (1D) mimetic gradient operator matrix.
+  ! KEYWORDS: type definition, 1D gradient operator matrix
+  ! CONTEXT: Use this type to assemble gradient-operator matrix for printing.
+
   type, extends(mimetic_matrix_1D_t) :: gradient_operator_1D_t
     !! Encapsulate a 1D mimetic gradient operator
     private
@@ -48,9 +52,14 @@ pure module function construct_matrix_operator(upper, inner, lower) result(mimet
     generic :: assemble => assemble_gradient
     procedure, non_overridable, private :: assemble_gradient
   end type
+  ! END CODE CHUNK
 
   interface gradient_operator_1D_t
 
+    ! PURPOSE: Interface for procedure to construct a new mimetic gradient-operator matrix representation of kth order for 1D cells of width dx.
+    ! KEYWORDS: 1D, gradient-operator constructor, sparse matrix
+    ! CONTEXT: Use this function to construct a sparse-matrix represntation of a mimetic gradient operator.
+
     pure module function construct_1D_gradient_operator(k, dx, cells) result(gradient_operator_1D)
       !! Construct a mimetic gradient operator
       implicit none
@@ -59,9 +68,14 @@ pure module function construct_1D_gradient_operator(k, dx, cells) result(gradien
       integer, intent(in) :: cells !! number of grid cells
       type(gradient_operator_1D_t) gradient_operator_1D
     end function
+    ! END CODE CHUNK
 
   end interface
 
+  ! PURPOSE: Interface for procedure to encapsulate a 1D mimetic divergence operator matrix.
+  ! KEYWORDS: 1D, divergence operator, sparse matrix
+  ! CONTEXT: Use this type to assemble divergence-operator matrix for printing.
+
   type, extends(mimetic_matrix_1D_t) :: divergence_operator_1D_t
     !! Encapsulate kth-order mimetic divergence operator on m_ cells of width dx
     private
@@ -74,9 +88,14 @@ pure module function construct_1D_gradient_operator(k, dx, cells) result(gradien
     procedure, non_overridable, private :: assemble_divergence
     procedure, non_overridable :: submatrix_A_rows
   end type
+  ! END CODE CHUNK
 
   interface divergence_operator_1D_t
 
+    ! PURPOSE: Interface for procedure to construct an object representing a 1D mimetic divergence operator.
+    ! KEYWORDS: 1D, divergence operator, sparse matrix, constructor
+    ! CONTEXT: Use this type to assemble a divergence-operator matrix for printing.
+
     pure module function construct_1D_divergence_operator(k, dx, cells) result(divergence_operator_1D)
       !! Construct a mimetic gradient operator
       implicit none
@@ -85,6 +104,7 @@ pure module function construct_1D_divergence_operator(k, dx, cells) result(diver
       integer, intent(in) :: cells !! number of grid cells
       type(divergence_operator_1D_t) divergence_operator_1D
     end function
+    ! END CODE CHUNK
 
   end interface
 

src/formal/scalar_1D_s.F90

@@ -23,6 +23,12 @@
 
 #ifndef __GFORTRAN__
 
+  ! PURPOSE: Definition of procedure to construct a new scalar_1D_t object by assigning each argument to a corresponding
+  !          corresponding component of the new object.
+  ! KEYWORDS: 1D scalar field constructor
+  ! CONTEXT: Invoke this constructor with a pointer associated with a function to be sampled at a set
+  !          of uniformly-spaced cell centers along one spatial dimension bounded by x_min and x_max.
+
   module procedure construct_1D_scalar_from_function
     call_julienne_assert(x_max .greaterThan. x_min)
     call_julienne_assert(cells .isAtLeast. 2*order)
@@ -32,9 +38,15 @@
     end associate
     scalar_1D%gradient_operator_1D_ = gradient_operator_1D_t(k=order, dx=(x_max - x_min)/cells, cells=cells)
   end procedure
-
+  ! END CODE CHUNK
 #else
 
+  ! PURPOSE: Definition of procedure to construct a new scalar_1D_t object by assigning each argument to a corresponding
+  !          corresponding component of the new object.
+  ! KEYWORDS: 1D scalar field constructor
+  ! CONTEXT: Invoke this constructor with a pointer associated with a function to be sampled at a set
+  !          of uniformly-spaced cell centers along one spatial dimension bounded by x_min and x_max.
+
   pure module function construct_1D_scalar_from_function(initializer, order, cells, x_min, x_max) result(scalar_1D)
     procedure(scalar_1D_initializer_i), pointer :: initializer
     integer, intent(in) :: order !! order of accuracy
@@ -51,6 +63,7 @@ pure module function construct_1D_scalar_from_function(initializer, order, cells
     end associate
     scalar_1D%gradient_operator_1D_ = gradient_operator_1D_t(k=order, dx=(x_max - x_min)/cells, cells=cells)
   end function
+  ! END CODE CHUNK
 
   pure function cell_center_locations(x_min, x_max, cells) result(x)
     double precision, intent(in) :: x_min, x_max
@@ -65,6 +78,10 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
 
 #endif
 
+  ! PURPOSE: Definition of procedure to compute mimetic approximations to the gradient of scalar fields.
+  ! KEYWORDS: gradient, differential operator
+  ! CONTEXT: Invoke this function via the unary .grad. operator with a right-hand-side, scalar-field operand.
+
   module procedure grad
 
     integer c
@@ -81,6 +98,11 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
     end associate
 
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to compute mimetic approximations to the Laplacian of a scalar field.
+  ! KEYWORDS: Laplacian, differential operator
+  ! CONTEXT: Invoke this function via the unary .laplacian. operator with a right-hand-side, scalar-field operand.
 
   module procedure laplacian
 
@@ -95,10 +117,16 @@ pure function cell_center_locations(x_min, x_max, cells) result(x)
     end associate
 
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to provide the cell-centered values of scalar quantities.
+  ! KEYWORDS: cell centers, staggered grid, scalar field
+  ! CONTEXT: Invoke this function via the "values" generic binding to produce discrete scalar values.
 
   module procedure scalar_1D_values
     cell_centers_extended_values = self%values_
   end procedure
+  ! END CODE CHUNK
 
   pure function scalar_1D_grid_locations(x_min, x_max, cells) result(x)
     double precision, intent(in) :: x_min, x_max
@@ -111,8 +139,14 @@ pure function scalar_1D_grid_locations(x_min, x_max, cells) result(x)
     end associate
   end function
 
+  ! PURPOSE: Definition of procedure to provide the staggered-grid locations at which scalar values are stored: cell centers plus domain boundaries.
+  ! KEYWORDS: staggered grid, scalar field, cell centers
+  ! CONTEXT: Invoke this function via the "grid" generic binding to produce discrete scalar locations for
+  !          initialization-function sampling, printing, or plotting.
+
   module procedure scalar_1D_grid
     cell_centers_extended  = scalar_1D_grid_locations(self%x_min_, self%x_max_, self%cells_)
   end procedure
+  ! END CODE CHUNK
 
-end submodule scalar_1D_s
+end submodule scalar_1D_s

src/formal/scalar_x_divergence_1D_s.F90

@@ -9,9 +9,15 @@
 
 contains
 
+  ! PURPOSE: Definition of procedure to perform mimetic volume integration of a scalar/divergence dot product.
+  ! KEYWORDS: triple integral, volume integral
+  ! CONTEXT: Invoke this function in expressions of the form  .SSS. (f * .div. v) * dV
+  !          with a vector_1D_t v, a scalar f, and a differential volume dV.
+
   module procedure volume_integrate_scalar_x_divergence_1D
     call_julienne_assert(size(integrand%weights_ ) .equalsExpected. size(integrand%values_)+2)
     integral  = sum(integrand%weights_ * [0D0, integrand%values_, 0D0])
   end procedure
+  ! END CODE CHUNK
 
 end submodule scalar_x_divergence_1D_s

src/formal/tensor_1D_s.f90

@@ -5,17 +5,27 @@
   implicit none
 contains
 
+  ! PURPOSE: Definition of procedure to construct a new tensor_1D_t object by assigning each argument to a corresponding
+  !          corresponding component of the new object.
+  ! KEYWORDS: 1D tensor constructor
+  ! CONTEXT: Constructors for child types assign this function's result to to the child object's parent component.
+
   module procedure construct_1D_tensor_from_components
     tensor_1D%values_ = values
     tensor_1D%x_min_  = x_min
     tensor_1D%x_max_  = x_max
     tensor_1D%cells_  = cells 
     tensor_1D%order_  = order
   end procedure
+  ! END CODE CHUNK
+
+  ! PURPOSE: Definition of procedure to provide a uniform cell width along the x-coordinate spatial direction.
+  ! KEYWORDS: abcissa, mesh spacing
+  ! CONTEXT: Use this function to produce cell widths for uniform 1D meshes.
 
   module procedure dx
     dx = (self%x_max_ - self%x_min_)/self%cells_
   end procedure
-
+  ! END CODE CHUNK
 
 end submodule tensor_1D_s