diff --git a/example/extended-gauss-divergence.F90 b/example/extended-gauss-divergence.F90 index ddc9610..e3a182c 100644 --- a/example/extended-gauss-divergence.F90 +++ b/example/extended-gauss-divergence.F90 @@ -26,25 +26,13 @@ program extended_gauss_divergence !! where `.SSS.` and `.SS.` are the 1D equivalents of a volume integral over the whole !! domain and a surface integral over a domain boundary of unit area, respectively. - ! PURPOSE: Import derived types (*_t) and abstract interfaces (*_i) from modules (*_m) that - ! export the public entities provided by the Formal mimetic abstraction library and - ! the Julienne correctness-checking framework. Also import scalar and vector functions - ! from a user-defined module: integrand_operands_m. - ! KEYWORDS: derived type, use association, abstract interface - ! CONTEXT: demonstration of satisfaction of an extended form of the Gauss Divergence Theorem - use julienne_m, only : command_line_t use formal_m, only : scalar_1D_t, scalar_1D_initializer_i, vector_1D_t, vector_1D_initializer_i use integrand_operands_m, only : scalar, vector - ! END CODE CHUNK implicit none - ! PURPOSE: Define procedure pointers for 1D scalar- and vector-field initialization functions - ! KEYWORDS: initial condition, 1D, scalar, vector - ! CONTEXT: pass as the first argument in a scalar_1D_t or vector_1D_t constructor function invocation procedure(scalar_1D_initializer_i), pointer :: scalar_1D_initializer => scalar procedure(vector_1D_initializer_i), pointer :: vector_1D_initializer => vector - ! END CODE CHUNK type numerical_arguments_t !! Define default initializations that can be overridden with the command-line arguments diff --git a/example/vibe-coding/rag-target.F90 b/example/vibe-coding/rag-target.F90 index f4c157e..bdbc379 100644 --- a/example/vibe-coding/rag-target.F90 +++ b/example/vibe-coding/rag-target.F90 @@ -72,12 +72,6 @@ ! that need not be in the code that we desire for the retreival augmented generation (RAG) ! process to generate. -! PURPOSE: User-defined module functions for use in initializing scalar and vector fields on -! a one-dimensional (1D) staggered grid. Scalar functions will be sampled at cell -! centers and domian boundaries (domain interval end points in 1D). Vector functions -! will be sampled at cell faces (subinterval end points). -! KEYWORDS: module function, scalar, vector -! CONTEXT: module rag_integrand_operands_m implicit none contains @@ -95,75 +89,33 @@ pure function vector(x) result(v) end function end module -! END CODE CHUNK program rag_target - ! PURPOSE: Import derived types (*_t) and abstract interfaces (*_i) from modules (*_m) that - ! export the public entities provided by the Formal mimetic abstraction library and - ! the Julienne correctness-checking framework. Also import scalar and vector functions - ! from a user-defined module: rag_integrand_operands_m. - ! KEYWORDS: derived type, use association, abstract interface - ! CONTEXT: demonstration of satisfaction of an extended form of the Gauss Divergence Theorem - use formal_m, only : scalar_1D_t, scalar_1D_initializer_i, vector_1D_t, vector_1D_initializer_i use rag_integrand_operands_m, only : scalar, vector - ! END CODE CHUNK implicit none - ! PURPOSE: Define procedure pointers for 1D scalar- and vector-field initialization functions - ! KEYWORDS: initial condition, 1D, scalar, vector - ! CONTEXT: pass as the first argument in a scalar_1D_t or vector_1D_t constructor function invocation procedure(scalar_1D_initializer_i), pointer :: scalar_1D_initializer => scalar procedure(vector_1D_initializer_i), pointer :: vector_1D_initializer => vector - ! END CODE CHUNK double precision SSS_v_dot_grad_f_dV, SSS_f_div_v_dV, SS_f_v_dot_dA - ! PURPOSE: Construct 1D scalar- and vector-field objects with a specified order of accuracy, - ! number of grid cells, and domain boundaries - ! KEYWORDS: scalar field, vector field, one-dimensional (1D) - ! CONTEXT: construct fields for use as operands in vector-calculus expressions integrand_factors: & associate( & f => scalar_1D_t(scalar_1D_initializer, order=4, cells=200, x_min=0D0, x_max=1D0) & ,v => vector_1D_t(vector_1D_initializer, order=4, cells=200, x_min=0D0, x_max=1D0) & ) - ! END CODE CHUNK differential_volume: & associate(dV => f%dV()) - - ! PURPOSE: Evaluate a volume integral over the problem domain with an integrand formed - ! from the dot product of a vector field v with the gradient of a scalar f - ! KEYWORDS: volume integral, dot product, gradient - ! CONTEXT: Use to verfiy the extended Gauss divergence theorem. SSS_v_dot_grad_f_dV = .SSS. (v .dot. .grad. f) * dV - ! END CODE CHUNK - - ! PURPOSE: Evaluate a volume integral over the problem domain with an integrand formed - ! from the product of a scalar field f with the divergence of a vector field v - ! KEYWORDS: volume integral, divergence - ! CONTEXT: Use to verfiy the extended Gauss divergence theorem. SSS_f_div_v_dV = .SSS. (f * .div. v) * dV - ! END CODE CHUNK - end associate differential_volume differential_area: & associate(dA => v%dA()) - ! PURPOSE: Evaluate a boundary surface integral representing the flux of a vector field formed - ! from the product of a scalar field f and a vector field v - ! KEYWORDS: surface integral, flux - ! CONTEXT: Use to verfiy the extended Gauss divergence theorem. SS_f_v_dot_dA = .SS. (f .x. (v .dot. dA)) - ! END CODE CHUNK - - ! PURPOSE: Verify satisfaction of the Extended Gauss Divergence Theorem by computing a residual - ! formed from the two volume integrals and one surface integral in the theorem. - ! KEYWORDS: Extended Gauss Divergence Theorem, residual - ! CONTEXT: A small resudual verifies the satisfaction of the Extended Guass Divergence Theorem print '(26x,a,g0,a)',"sum = ", SSS_v_dot_grad_f_dV + SSS_f_div_v_dV - SS_f_v_dot_dA, " (residual)" - ! END CODE CHUNK end associate differential_area end associate integrand_factors diff --git a/src/formal/divergence_1D_s.F90 b/src/formal/divergence_1D_s.F90 index 1c12aa1..c4e24bf 100644 --- a/src/formal/divergence_1D_s.F90 +++ b/src/formal/divergence_1D_s.F90 @@ -14,6 +14,16 @@ #ifdef __GFORTRAN__ + ! PURPOSE: Computes the cell-center x-coordinates for a uniform 1D grid given the domain bounds + ! and number of cells, returning an array of cell-center locations offset by half a cell + ! width from x_min. + ! KEYWORDS: grid, cell-center, uniform-mesh, 1D, structured-grid, staggered-grid, utility, gfortran + ! CONTEXT: This helper function is only compiled under gfortran and provides cell-center coordinate + ! computation needed by the divergence_1D submodule. It constructs a uniform grid with cell + ! width dx = (x_max - x_min)/cells and places each cell center at x_min + dx/2 + (cell-1)*dx + ! using an implied do loop. Other compilers may provide this functionality through a different + ! code path or type-bound procedure. This function is used by divergence_1D_grid to return + ! the grid coordinates associated with a divergence_1D_t object. pure function cell_center_locations(x_min, x_max, cells) result(x) double precision, intent(in) :: x_min, x_max integer, intent(in) :: cells @@ -24,14 +34,24 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) x = x_min + dx/2. + [((cell-1)*dx, cell = 1, cells)] end associate end function + ! END CODE CHUNK #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 - + ! PURPOSE: Computes the element-wise product of a scalar_1D field's interior values with a + ! divergence_1D field's cell-centered values, producing a new scalar_x_divergence_1D_t + ! object that carries both the multiplied values and the divergence quadrature weights. + ! KEYWORDS: scalar-multiplication, divergence, operator-overloading, premultiply, scalar_1D, + ! divergence_1D, structured-grid, staggered-grid, quadrature-weights, interior-values + ! CONTEXT: This procedure implements the left-multiplication of a scalar_1D_t by a divergence_1D_t + ! in the formal library's operator overloading framework. The scalar field has two extra + ! boundary values compared to the divergence field's cell-centered values, so the scalar's + ! interior slice (index 2 through size-1) is multiplied element-wise with the divergence + ! values. The result inherits the scalar field's grid metadata and the divergence field's + ! quadrature weights, with a compiler-conditional call to either weights() or + ! divergence_1D_weights() to handle gfortran naming differences. Assertions verify that + ! the scalar field has exactly two more values than the divergence field and that the + ! resulting weights array has the expected size. 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 = & @@ -45,41 +65,60 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) 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 - + ! PURPOSE: Delegates right-multiplication of a divergence_1D field by a scalar_1D field to the + ! premultiply_scalar_1D procedure, ensuring commutativity of scalar-divergence + ! multiplication. + ! KEYWORDS: scalar-multiplication, divergence, operator-overloading, postmultiply, commutativity, + ! scalar_1D, divergence_1D, delegation + ! CONTEXT: This procedure implements the right-multiplication form (divergence * scalar) by + ! delegating to premultiply_scalar_1D (scalar * divergence) in the formal library's + ! operator overloading framework. Since scalar-divergence multiplication is commutative, + ! this thin wrapper avoids duplicating the multiplication logic and ensures both operator + ! orderings produce identical results. 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. - + ! PURPOSE: Returns the cell-centered divergence values stored in a divergence_1D_t object. + ! KEYWORDS: divergence, accessor, cell-centered-values, divergence_1D, getter + ! CONTEXT: This procedure is a simple accessor that exposes the internally stored cell-centered + ! divergence values from a divergence_1D_t object. It is used by test functions and other + ! operators in the formal library to retrieve computed divergence data for comparison + ! against analytical expectations or for use in compound operator expressions. 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. - + ! PURPOSE: Returns the cell-center x-coordinates of the 1D grid associated with a divergence_1D_t + ! object by delegating to the cell_center_locations helper function. + ! KEYWORDS: grid, cell-center, accessor, divergence_1D, structured-grid, staggered-grid, getter + ! CONTEXT: This procedure provides access to the grid coordinates associated with a divergence_1D_t + ! object in the formal library. It delegates to the cell_center_locations function, passing + ! the stored domain bounds and cell count. Test functions use this accessor to retrieve + ! grid coordinates for constructing spatially-varying expected values when verifying + ! divergence operator results. 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. - + ! PURPOSE: Computes the mimetic quadrature weights for a divergence_1D_t object, returning an + ! array of m+2 weights where m is the number of cells, with boundary skin weights that + ! ensure discrete conservation properties and interior weights of 1.0. + ! KEYWORDS: quadrature-weights, mimetic, divergence, boundary-weights, Corbino-Castillo, + ! structured-grid, staggered-grid, 2nd-order, 4th-order, conservation, summation-by-parts + ! CONTEXT: This procedure computes the quadrature weights used for discrete integration involving + ! divergence fields in the formal library's mimetic finite-difference framework. The + ! weights follow the formulation of Corbino & Castillo (2020) Eqs. 14-15 and 19, where + ! boundary "skin" weights deviate from unity to maintain discrete conservation and + ! summation-by-parts properties. For 2nd-order discretizations the skin is empty (all + ! weights are 1.0), while for 4th-order discretizations an 8-element skin array provides + ! the boundary corrections. The skin is mirrored symmetrically at both domain boundaries. + ! Assertions verify that the grid has sufficient cells to accommodate the skin depth on + ! both sides and that the resulting weights array has the expected size of cells+2. + ! Unsupported orders trigger an error stop. module procedure divergence_1D_weights integer c @@ -102,4 +141,5 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) call_julienne_assert(size(weights) .equalsExpected. self%cells_+2) end procedure ! END CODE CHUNK + end submodule divergence_1D_s diff --git a/src/formal/divergence_operator_1D_s.F90 b/src/formal/divergence_operator_1D_s.F90 index 780b003..76521e5 100644 --- a/src/formal/divergence_operator_1D_s.F90 +++ b/src/formal/divergence_operator_1D_s.F90 @@ -14,6 +14,19 @@ #ifdef __GFORTRAN__ + ! PURPOSE: Transforms the upper boundary block submatrix "A" of a mimetic divergence operator into + ! the corresponding lower boundary block "A'" by reversing elements within rows (with sign + ! negation) and then reversing elements within columns, implementing the antisymmetric + ! reflection required by the Corbino & Castillo (2020) mimetic operator structure. + ! KEYWORDS: mimetic, divergence, boundary-block, matrix-transformation, antisymmetric, Corbino-Castillo, + ! gfortran, utility + ! CONTEXT: This helper function is only compiled under gfortran and provides the transformation from + ! the upper block "A" to the lower block "A'" needed when constructing the mimetic divergence + ! operator matrix in the formal library. The mimetic divergence operator has a block structure + ! consisting of an upper boundary block A, a repeated interior row M, and a lower boundary + ! block A' that is derived from A by negating and flipping. Other compilers may access this + ! functionality through a different code path. This function is called by + ! construct_1D_divergence_operator during operator assembly. pure function negate_and_flip(A) result(Ap) !! Transform a mimetic matrix upper block into a lower block double precision, intent(in) :: A(:,:) @@ -33,13 +46,30 @@ pure function negate_and_flip(A) result(Ap) end do reverse_elements_within_columns end function + ! END CODE CHUNK #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. - + ! PURPOSE: Constructs a 1D mimetic divergence operator for a given order of accuracy k and cell + ! width dx on a grid with the specified number of cells. The operator is assembled in the + ! block structure of Corbino & Castillo (2020), consisting of an upper boundary block A, + ! a repeated interior stencil row M, and a lower boundary block A' derived from A via + ! antisymmetric reflection. Internal helper functions A_block and M compute the order- + ! specific stencil coefficients for 2nd-order and 4th-order accuracy. + ! KEYWORDS: mimetic, divergence, operator-construction, Corbino-Castillo, finite-difference, + ! structured-grid, staggered-grid, 2nd-order, 4th-order, boundary-block, interior-stencil, + ! block-matrix + ! CONTEXT: This procedure constructs the divergence_operator_1D_t object in the formal library's + ! mimetic finite-difference framework following the formulation of Corbino & Castillo (2020). + ! The divergence operator maps from m+1 node-centered values to m+2 cell-centered values + ! (with zero boundary rows), where m is the number of cells. The internal function A_block + ! returns the upper boundary submatrix specific to the requested order: an empty matrix for + ! 2nd-order (no boundary correction needed) and a 1x5 row for 4th-order. The internal + ! function M returns the interior stencil row: a 2-point stencil for 2nd-order and a + ! 4-point stencil for 4th-order. The lower block A' is computed from A via negate_and_flip. + ! An assertion verifies the grid has enough cells to accommodate the boundary blocks. The + ! constructed object stores the block components along with the order k, cell width dx, and + ! cell count m for use by the matrix-vector multiply and assembly procedures. module procedure construct_1D_divergence_operator double precision, allocatable :: Ap(:,:) @@ -106,11 +136,37 @@ pure function M(k, dx) result(row) end procedure construct_1D_divergence_operator ! END CODE CHUNK + ! PURPOSE: Returns the number of rows in the upper boundary block submatrix A of the mimetic + ! divergence operator. + ! KEYWORDS: mimetic, divergence, boundary-block, submatrix-rows, accessor, getter + ! CONTEXT: This procedure is a simple accessor that returns the row count of the upper boundary + ! block A stored in a divergence_operator_1D_t object. The number of rows in A determines + ! the depth of the boundary region where the divergence stencil differs from the interior + ! stencil. This information is used when partitioning the operator into boundary and + ! interior regions for matrix-vector multiplication and convergence analysis. module procedure submatrix_A_rows call_julienne_assert(allocated(self%upper_)) rows = size(self%upper_,1) end procedure + ! END CODE CHUNK + ! PURPOSE: Computes the matrix-vector product of the mimetic divergence operator with an input + ! vector of m+1 node-centered values, producing an output vector of m+2 cell-centered + ! values with zero boundary entries, by applying the upper block A, the repeated interior + ! stencil M via do concurrent, and the lower block A' separately. + ! KEYWORDS: mimetic, divergence, matrix-vector-multiply, operator-application, Corbino-Castillo, + ! structured-grid, staggered-grid, do-concurrent, boundary-block, interior-stencil, + ! block-matrix + ! CONTEXT: This procedure implements the action of the mimetic divergence operator on a vector in + ! the formal library's mimetic finite-difference framework. Rather than assembling and + ! storing the full dense matrix, it exploits the block structure of the Corbino & Castillo + ! (2020) operator: the upper boundary rows are computed via matmul with the stored upper + ! block, the interior rows are computed via dot_product with the repeated interior stencil + ! in a do concurrent loop, and the lower boundary rows are computed via matmul with the + ! stored lower block. The first and last entries of the result are set to zero, consistent + ! with the mimetic operator structure. Conditional compilation handles differences in + ! do concurrent syntax support across compilers. An assertion verifies the input vector + ! has size m+1 and the output has size m+2. module procedure divergence_matrix_multiply double precision, allocatable :: product_inner(:) @@ -157,7 +213,24 @@ pure function M(k, dx) result(row) end associate end procedure + ! END CODE CHUNK + ! PURPOSE: Assembles the full dense matrix representation of the mimetic divergence operator by + ! applying the operator to each column of the identity matrix via the matrix-vector + ! multiply procedure, producing an (m+2) x (m+1) matrix. An internal helper function e + ! generates the unit basis vectors used as identity matrix columns. + ! KEYWORDS: mimetic, divergence, matrix-assembly, dense-matrix, identity-matrix, operator-assembly, + ! structured-grid, staggered-grid, do-concurrent, Corbino-Castillo + ! CONTEXT: This procedure constructs the full dense matrix form of the mimetic divergence operator + ! in the formal library. While the operator is typically applied in matrix-free form via + ! divergence_matrix_multiply for efficiency, the dense matrix is useful for debugging, + ! visualization, and verification purposes. The assembly works by applying the operator to + ! each standard basis vector e_i of length m+1 using do concurrent, where each resulting + ! column of the output matrix is the operator's response to that basis vector. Conditional + ! compilation handles differences in do concurrent syntax support across compilers, with + ! a gfortran workaround that calls divergence_matrix_multiply directly rather than using + ! the overloaded .x. operator. The internal function e constructs the i-th unit vector of + ! the specified length. module procedure assemble_divergence associate(rows => self%m_ + 2, cols => self%m_ + 1) @@ -190,5 +263,6 @@ pure function e(dir, length) result(unit_vector) end function end procedure + ! END CODE CHUNK end submodule divergence_operator_1D_s diff --git a/src/formal/gradient_1D_s.F90 b/src/formal/gradient_1D_s.F90 index bbd7f60..d99e426 100644 --- a/src/formal/gradient_1D_s.F90 +++ b/src/formal/gradient_1D_s.F90 @@ -16,12 +16,21 @@ 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. - + ! PURPOSE: Computes the mimetic quadrature weights for a gradient_1D_t object, returning an array + ! of m+1 weights where m is the number of cells, with boundary skin weights that ensure + ! discrete conservation properties and interior weights of 1.0. + ! KEYWORDS: quadrature-weights, mimetic, gradient, boundary-weights, structured-grid, staggered-grid, + ! 2nd-order, 4th-order, conservation, summation-by-parts, accessor + ! CONTEXT: This procedure computes the quadrature weights used for discrete integration involving + ! gradient fields in the formal library's mimetic finite-difference framework. The gradient + ! lives on a staggered-grid with m+1 node-centered values, so the weights array has size + ! m+1. Boundary "skin" weights deviate from unity to maintain discrete conservation and + ! summation-by-parts properties. For 2nd-order discretizations the skin has 2 elements, + ! while for 4th-order discretizations the skin has 7 elements. The skin is mirrored + ! symmetrically at both domain boundaries with unity-valued weights filling the interior. + ! Assertions verify that the grid has sufficient cells to accommodate the skin depth on + ! both sides and that the resulting weights array has the expected size of cells+1. + ! Unsupported orders trigger an error stop. module procedure gradient_1D_weights integer face @@ -46,12 +55,22 @@ 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. - + ! PURPOSE: Computes the element-wise dot product of a vector_1D field with a gradient_1D field, + ! producing a new vector_dot_gradient_1D_t object that carries both the multiplied values + ! and the gradient quadrature weights. + ! KEYWORDS: dot-product, gradient, vector_1D, operator-overloading, structured-grid, staggered-grid, + ! mimetic, quadrature-weights, element-wise-multiplication + ! CONTEXT: This procedure implements the dot product of a vector_1D_t with a gradient_1D_t in the + ! formal library's operator overloading framework. Both fields must live on the same + ! staggered-grid with matching sizes, orders, cell counts, and domain bounds, which are + ! verified via assertions. The element-wise product of the two fields' node-centered values + ! forms the resulting tensor, which inherits the gradient field's grid metadata and + ! quadrature weights. The quadrature weights are retrieved via a compiler-conditional call + ! to either weights() or gradient_1D_weights() to handle gfortran naming differences. The + ! resulting vector_dot_gradient_1D_t object can then be passed to the volume integration + ! operator .SSS. as part of compound expressions such as .SSS. (v .dot. .grad. f) * dV. module procedure dot + call_julienne_assert(size(gradient_1D%values_) .equalsExpected. size(vector_1D%values_)) call_julienne_assert(gradient_1D%order_ .equalsExpected. vector_1D%order_) call_julienne_assert(gradient_1D%cells_ .equalsExpected. vector_1D%cells_) @@ -72,4 +91,5 @@ #endif end procedure ! END CODE CHUNK + end submodule gradient_1D_s diff --git a/src/formal/gradient_operator_1D_s.F90 b/src/formal/gradient_operator_1D_s.F90 index 2c22e39..c8a71b0 100644 --- a/src/formal/gradient_operator_1D_s.F90 +++ b/src/formal/gradient_operator_1D_s.F90 @@ -15,6 +15,19 @@ #ifdef __GFORTRAN__ + ! PURPOSE: Transforms the upper boundary block submatrix "A" of a mimetic gradient operator into + ! the corresponding lower boundary block "A'" by reversing elements within rows (with sign + ! negation) and then reversing elements within columns, implementing the antisymmetric + ! reflection required by the Corbino & Castillo (2020) mimetic operator structure. + ! KEYWORDS: mimetic, gradient, boundary-block, matrix-transformation, antisymmetric, Corbino-Castillo, + ! gfortran, utility + ! CONTEXT: This helper function is only compiled under gfortran and provides the transformation from + ! the upper block "A" to the lower block "A'" needed when constructing the mimetic gradient + ! operator matrix in the formal library. The mimetic gradient operator has a block structure + ! consisting of an upper boundary block A, a repeated interior row M, and a lower boundary + ! block A' that is derived from A by negating and flipping. Other compilers may access this + ! functionality through a different code path. This function is called by + ! construct_1D_gradient_operator during operator assembly. pure function negate_and_flip(A) result(Ap) !! Transform a mimetic matrix upper block into a lower block double precision, intent(in) :: A(:,:) @@ -34,13 +47,32 @@ pure function negate_and_flip(A) result(Ap) end do reverse_elements_within_columns end function + ! END CODE CHUNK #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. - + ! PURPOSE: Constructs a 1D mimetic gradient operator for a given order of accuracy k and cell width + ! dx on a grid with the specified number of cells. The operator is assembled in the block + ! structure of Corbino & Castillo (2020), consisting of an upper boundary block A, a + ! repeated interior stencil row M, and a lower boundary block A' derived from A via + ! antisymmetric reflection. Internal helper functions corbino_castillo_A and + ! corbino_castillo_M compute the order-specific stencil coefficients for 2nd-order and + ! 4th-order accuracy. + ! KEYWORDS: mimetic, gradient, operator-construction, Corbino-Castillo, finite-difference, + ! structured-grid, staggered-grid, 2nd-order, 4th-order, boundary-block, interior-stencil, + ! block-matrix + ! CONTEXT: This procedure constructs the gradient_operator_1D_t object in the formal library's + ! mimetic finite-difference framework following the formulation of Corbino & Castillo (2020). + ! The gradient operator maps from m+2 cell-centered values (including boundary ghost values) + ! to m+1 node-centered values, where m is the number of cells. The internal function + ! corbino_castillo_A returns the upper boundary submatrix specific to the requested order: + ! a 1x3 row for 2nd-order and a 2x5 block for 4th-order. The internal function + ! corbino_castillo_M returns the interior stencil row: a 2-point stencil for 2nd-order and + ! a 4-point stencil for 4th-order. The lower block A' is computed from A via + ! negate_and_flip. An assertion verifies the grid has enough cells to accommodate the + ! boundary blocks. The constructed object stores the block components along with the order + ! k, cell width dx, and cell count m for use by the matrix-vector multiply and assembly + ! procedures. module procedure construct_1D_gradient_operator call_julienne_assert(cells .isAtLeast. 2*k) @@ -98,6 +130,24 @@ pure function corbino_castillo_M(k, dx) result(row) end procedure construct_1D_gradient_operator ! END CODE CHUNK + ! PURPOSE: Computes the matrix-vector product of the mimetic gradient operator with an input vector + ! of m+2 cell-centered values (including boundary ghost values), producing an output vector + ! of m+1 node-centered values, by applying the upper block A, the repeated interior stencil + ! M via do concurrent, and the lower block A' separately. + ! KEYWORDS: mimetic, gradient, matrix-vector-multiply, operator-application, Corbino-Castillo, + ! structured-grid, staggered-grid, do-concurrent, boundary-block, interior-stencil, + ! block-matrix + ! CONTEXT: This procedure implements the action of the mimetic gradient operator on a vector in the + ! formal library's mimetic finite-difference framework. Rather than assembling and storing + ! the full dense matrix, it exploits the block structure of the Corbino & Castillo (2020) + ! operator: the upper boundary rows are computed via matmul with the stored upper block, the + ! interior rows are computed via dot_product with the repeated interior stencil in a do + ! concurrent loop, and the lower boundary rows are computed via matmul with the stored lower + ! block. Unlike the divergence operator, which has zero-padded first and last rows, the + ! gradient operator produces values at all m+1 nodes without zero padding. The interior + ! stencil is applied starting from an offset of 1 to account for the node-centered output + ! grid's relationship to the cell-centered input grid. Conditional compilation handles + ! differences in do concurrent syntax support across compilers. module procedure gradient_matrix_multiply double precision, allocatable :: product_inner(:) @@ -139,7 +189,24 @@ pure function corbino_castillo_M(k, dx) result(row) ] end associate end procedure + ! END CODE CHUNK + ! PURPOSE: Assembles the full dense matrix representation of the mimetic gradient operator by + ! applying the operator to each column of the identity matrix via the matrix-vector + ! multiply procedure, producing an (m+1) x (m+2) matrix. An internal helper function e + ! generates the unit basis vectors used as identity matrix columns. + ! KEYWORDS: mimetic, gradient, matrix-assembly, dense-matrix, identity-matrix, operator-assembly, + ! structured-grid, staggered-grid, do-concurrent, Corbino-Castillo + ! CONTEXT: This procedure constructs the full dense matrix form of the mimetic gradient operator in + ! the formal library. While the operator is typically applied in matrix-free form via + ! gradient_matrix_multiply for efficiency, the dense matrix is useful for debugging, + ! visualization, and verification purposes. The assembly works by applying the operator to + ! each standard basis vector e_i of length m+2 using do concurrent, where each resulting + ! column of the output matrix is the operator's response to that basis vector. Conditional + ! compilation handles differences in do concurrent syntax support across compilers, with a + ! gfortran workaround that calls gradient_matrix_multiply directly rather than using the + ! overloaded .x. operator. The internal function e constructs the i-th unit vector of the + ! specified length. module procedure assemble_gradient associate(rows => self%m_ + 1, cols => self%m_ + 2) @@ -172,5 +239,6 @@ pure function e(dir, length) result(unit_vector) end function end procedure + ! END CODE CHUNK end submodule gradient_operator_1D_s diff --git a/src/formal/laplacian_s.f90 b/src/formal/laplacian_s.f90 index 8bfa87e..25fb50f 100644 --- a/src/formal/laplacian_s.f90 +++ b/src/formal/laplacian_s.f90 @@ -5,9 +5,18 @@ 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. + ! PURPOSE: Returns the number of boundary-adjacent grid locations at which the mimetic Laplacian + ! approximation has reduced-order accuracy compared to the interior stencil. + ! KEYWORDS: laplacian, boundary, order-of-accuracy, mimetic, structured-grid, staggered-grid, + ! accessor, boundary-depth, reduced-order, getter + ! CONTEXT: This procedure is a simple accessor that exposes the internally stored boundary depth + ! from a laplacian_1D_t object in the formal library's mimetic finite-difference framework. + ! Mimetic Laplacian operators achieve their full design-order accuracy in the grid interior + ! but exhibit a reduced convergence rate at a finite number of boundary-adjacent nodes. The + ! returned value indicates the depth of this reduced-accuracy region on each side of the + ! domain. Test functions such as the Laplacian convergence checks use this accessor to + ! separate interior and boundary error measurements when verifying convergence rates, since + ! the boundary region converges at a lower order than the interior. module procedure reduced_order_boundary_depth num_nodes = self%boundary_depth_ diff --git a/src/formal/mimetic_operators_1D_m.F90 b/src/formal/mimetic_operators_1D_m.F90 index 5241c2b..7675776 100644 --- a/src/formal/mimetic_operators_1D_m.F90 +++ b/src/formal/mimetic_operators_1D_m.F90 @@ -13,6 +13,18 @@ module mimetic_operators_1D_m public :: gradient_operator_1D_t public :: divergence_operator_1D_t + ! PURPOSE: Encapsulates the block-structured sparse storage of a 1D mimetic operator matrix + ! consisting of an upper boundary block A, a repeated interior stencil row M, and a lower + ! boundary block A', following the Corbino & Castillo (2020) formulation. + ! KEYWORDS: mimetic, sparse-matrix, block-structure, Corbino-Castillo, structured-grid, + ! staggered-grid, boundary-block, interior-stencil, base-type + ! CONTEXT: This type is the base type for gradient_operator_1D_t and divergence_operator_1D_t in + ! the formal library's mimetic finite-difference framework. Rather than storing the full + ! dense matrix, it stores only the upper boundary block A, the single interior stencil row + ! M (which repeats for all interior rows), and the lower boundary block A'. This compact + ! representation exploits the banded Toeplitz-like structure of mimetic operators where + ! all interior rows share the same stencil. The to_file_t type-bound procedure provides + ! serialization of the stored blocks for debugging and output. type mimetic_matrix_1D_t !! Encapsulate a mimetic matrix with a corresponding matrix-vector product operator private @@ -22,9 +34,19 @@ module mimetic_operators_1D_m contains procedure, non_overridable :: to_file_t end type + ! END CODE CHUNK interface mimetic_matrix_1D_t + ! PURPOSE: Constructs a mimetic_matrix_1D_t object from the provided upper boundary block A, + ! interior stencil row M, and lower boundary block A'. + ! KEYWORDS: mimetic, sparse-matrix, construction, block-structure, Corbino-Castillo, + ! structured-grid, staggered-grid, boundary-block, interior-stencil + ! CONTEXT: This interface provides the constructor for the mimetic_matrix_1D_t base type in the + ! formal library. It accepts the three block components that define a mimetic operator + ! matrix: the upper boundary block A, the repeated interior stencil row M, and the lower + ! boundary block A'. The gradient and divergence operator constructors delegate to this + ! constructor after computing the order-specific stencil coefficients. pure module function construct_matrix_operator(upper, inner, lower) result(mimetic_matrix_1D) !! Construct discrete operator from matrix blocks implicit none @@ -33,13 +55,24 @@ pure module function construct_matrix_operator(upper, inner, lower) result(mimet double precision, intent(in) :: lower(:,:) !! A' submatrix block (cf. Corbino & Castillo, 2020) type(mimetic_matrix_1D_t) mimetic_matrix_1D end function + ! END CODE CHUNK 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. - + ! PURPOSE: Encapsulates a 1D mimetic gradient operator that maps from m+2 cell-centered values + ! (including boundary ghost values) to m+1 node-centered gradient values, extending the + ! mimetic_matrix_1D_t base type with the order of accuracy k, cell count m, and cell + ! width dx. + ! KEYWORDS: mimetic, gradient, operator, sparse-matrix, Corbino-Castillo, structured-grid, + ! staggered-grid, finite-difference, cell-to-node, extended-type + ! CONTEXT: This type extends mimetic_matrix_1D_t in the formal library's mimetic finite-difference + ! framework to represent the gradient operator specifically. It adds the order of accuracy + ! k, cell count m, and cell width dx as private components needed for matrix-vector + ! multiplication and assembly. The type provides a generic .x. operator for matrix-free + ! application of the gradient to a vector and an assemble procedure for constructing the + ! full dense matrix representation. The gradient operator maps from the m+2 extended + ! scalar grid (cell centers plus boundary ghost values) to the m+1 node-centered + ! staggered-grid. type, extends(mimetic_matrix_1D_t) :: gradient_operator_1D_t !! Encapsulate a 1D mimetic gradient operator private @@ -56,10 +89,18 @@ pure module function construct_matrix_operator(upper, inner, lower) result(mimet 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. - + ! PURPOSE: Constructs a 1D mimetic gradient operator for a given order of accuracy k, cell width + ! dx, and number of cells, assembling the block-structured operator matrix following + ! the Corbino & Castillo (2020) formulation. + ! KEYWORDS: mimetic, gradient, operator-construction, Corbino-Castillo, finite-difference, + ! structured-grid, staggered-grid, 2nd-order, 4th-order, boundary-block, + ! interior-stencil + ! CONTEXT: This interface provides the constructor for gradient_operator_1D_t in the formal + ! library's mimetic finite-difference framework. The implementation in + ! gradient_operator_1D_s computes the order-specific upper boundary block A, interior + ! stencil row M, and lower boundary block A' for the requested order of accuracy, and + ! stores them along with k, dx, and the cell count. The constructed operator is used by + ! the .grad. operator applied to scalar_1D_t objects. pure module function construct_1D_gradient_operator(k, dx, cells) result(gradient_operator_1D) !! Construct a mimetic gradient operator implicit none @@ -72,10 +113,21 @@ pure module function construct_1D_gradient_operator(k, dx, cells) result(gradien 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. - + ! PURPOSE: Encapsulates a kth-order 1D mimetic divergence operator that maps from m+1 + ! node-centered values to m+2 cell-centered values (with zero boundary rows), extending + ! the mimetic_matrix_1D_t base type with the order of accuracy k, cell count m, and cell + ! width dx. + ! KEYWORDS: mimetic, divergence, operator, sparse-matrix, Corbino-Castillo, structured-grid, + ! staggered-grid, finite-difference, node-to-cell, extended-type + ! CONTEXT: This type extends mimetic_matrix_1D_t in the formal library's mimetic finite-difference + ! framework to represent the divergence operator specifically. It adds the order of + ! accuracy k, cell count m, and cell width dx as private components needed for + ! matrix-vector multiplication and assembly. The type provides a generic .x. operator for + ! matrix-free application of the divergence to a vector, an assemble procedure for + ! constructing the full dense matrix representation, and a submatrix_A_rows accessor for + ! querying the boundary block depth. The divergence operator maps from the m+1 + ! node-centered staggered-grid to the m+2 cell-centered grid with zero-padded boundary + ! rows. type, extends(mimetic_matrix_1D_t) :: divergence_operator_1D_t !! Encapsulate kth-order mimetic divergence operator on m_ cells of width dx private @@ -92,10 +144,18 @@ pure module function construct_1D_gradient_operator(k, dx, cells) result(gradien 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. - + ! PURPOSE: Constructs a 1D mimetic divergence operator for a given order of accuracy k, cell + ! width dx, and number of cells, assembling the block-structured operator matrix + ! following the Corbino & Castillo (2020) formulation. + ! KEYWORDS: mimetic, divergence, operator-construction, Corbino-Castillo, finite-difference, + ! structured-grid, staggered-grid, 2nd-order, 4th-order, boundary-block, + ! interior-stencil + ! CONTEXT: This interface provides the constructor for divergence_operator_1D_t in the formal + ! library's mimetic finite-difference framework. The implementation in + ! divergence_operator_1D_s computes the order-specific upper boundary block A, interior + ! stencil row M, and lower boundary block A' for the requested order of accuracy, and + ! stores them along with k, dx, and the cell count. The constructed operator is used by + ! the .div. operator applied to vector_1D_t objects. pure module function construct_1D_divergence_operator(k, dx, cells) result(divergence_operator_1D) !! Construct a mimetic gradient operator implicit none @@ -110,13 +170,32 @@ pure module function construct_1D_divergence_operator(k, dx, cells) result(diver interface + ! PURPOSE: Returns the number of rows in the upper boundary block submatrix A of the mimetic + ! divergence operator. + ! KEYWORDS: mimetic, divergence, boundary-block, submatrix-rows, accessor, getter + ! CONTEXT: This interface declares the accessor that returns the row count of the upper boundary + ! block A stored in a divergence_operator_1D_t object. The implementation in + ! divergence_operator_1D_s queries the allocated upper_ component. The number of rows + ! in A determines the depth of the boundary region where the divergence stencil differs + ! from the interior stencil, which is used when partitioning convergence analysis into + ! boundary and interior regions. pure module function submatrix_A_rows(self) result(rows) !! Result is number of rows in the A block of the mimetic divergence matrix operator implicit none class(divergence_operator_1D_t), intent(in) :: self integer rows end function + ! END CODE CHUNK + ! PURPOSE: Computes the matrix-vector product of the mimetic gradient operator with an input + ! vector, producing the node-centered gradient values. + ! KEYWORDS: mimetic, gradient, matrix-vector-multiply, operator-application, Corbino-Castillo, + ! structured-grid, staggered-grid, do-concurrent + ! CONTEXT: This interface declares the matrix-free application of the mimetic gradient operator + ! to a vector in the formal library. The implementation in gradient_operator_1D_s + ! exploits the block structure to apply the upper boundary block, repeated interior + ! stencil, and lower boundary block separately, avoiding assembly of the full dense + ! matrix. This procedure backs the generic .x. operator on gradient_operator_1D_t. pure module function gradient_matrix_multiply(self, vec) result(matvec_product) !! Result is mimetic gradient vector implicit none @@ -124,21 +203,51 @@ pure module function gradient_matrix_multiply(self, vec) result(matvec_product) double precision, intent(in) :: vec(:) double precision, allocatable :: matvec_product(:) end function + ! END CODE CHUNK + ! PURPOSE: Assembles the full dense matrix representation of the mimetic gradient operator, + ! producing an (m+1) x (m+2) matrix. + ! KEYWORDS: mimetic, gradient, matrix-assembly, dense-matrix, operator-assembly, structured-grid, + ! staggered-grid, Corbino-Castillo + ! CONTEXT: This interface declares the assembly of the full dense gradient operator matrix in the + ! formal library. The implementation in gradient_operator_1D_s constructs the matrix by + ! applying the operator to each standard basis vector via do concurrent. While the + ! operator is typically applied in matrix-free form for efficiency, the dense matrix is + ! useful for verifying the summation-by-parts identity and for debugging. pure module function assemble_gradient(self) result(G) !! Result is the assembled 1D mimetic gradient operator matrix implicit none class(gradient_operator_1D_t), intent(in) :: self double precision, allocatable :: G(:,:) end function + ! END CODE CHUNK + ! PURPOSE: Assembles the full dense matrix representation of the mimetic divergence operator, + ! producing an (m+2) x (m+1) matrix. + ! KEYWORDS: mimetic, divergence, matrix-assembly, dense-matrix, operator-assembly, structured-grid, + ! staggered-grid, Corbino-Castillo + ! CONTEXT: This interface declares the assembly of the full dense divergence operator matrix in + ! the formal library. The implementation in divergence_operator_1D_s constructs the + ! matrix by applying the operator to each standard basis vector via do concurrent. While + ! the operator is typically applied in matrix-free form for efficiency, the dense matrix + ! is useful for verifying the summation-by-parts identity and for debugging. pure module function assemble_divergence(self) result(D) !! Result is the assembled 1D mimetic divergence operator matrix implicit none class(divergence_operator_1D_t), intent(in) :: self double precision, allocatable :: D(:,:) end function + ! END CODE CHUNK + ! PURPOSE: Computes the matrix-vector product of the mimetic divergence operator with an input + ! vector, producing the cell-centered divergence values with zero boundary entries. + ! KEYWORDS: mimetic, divergence, matrix-vector-multiply, operator-application, Corbino-Castillo, + ! structured-grid, staggered-grid, do-concurrent + ! CONTEXT: This interface declares the matrix-free application of the mimetic divergence operator + ! to a vector in the formal library. The implementation in divergence_operator_1D_s + ! exploits the block structure to apply the upper boundary block, repeated interior + ! stencil, and lower boundary block separately, avoiding assembly of the full dense + ! matrix. This procedure backs the generic .x. operator on divergence_operator_1D_t. pure module function divergence_matrix_multiply(self, vec) result(matvec_product) !! Result is mimetic divergence defined at cell centers implicit none @@ -146,12 +255,23 @@ pure module function divergence_matrix_multiply(self, vec) result(matvec_product double precision, intent(in) :: vec(:) double precision, allocatable :: matvec_product(:) end function + ! END CODE CHUNK + ! PURPOSE: Serializes the mimetic_matrix_1D_t block components to a file_t object for output + ! and debugging. + ! KEYWORDS: mimetic, serialization, file-output, debugging, sparse-matrix, block-structure + ! CONTEXT: This interface declares the serialization procedure for the mimetic_matrix_1D_t base + ! type in the formal library. The implementation converts the stored upper block A, + ! interior stencil row M, and lower block A' into a file_t representation suitable for + ! writing to disk or displaying during debugging. This procedure is bound to the + ! mimetic_matrix_1D_t type and is inherited by both gradient_operator_1D_t and + ! divergence_operator_1D_t. pure module function to_file_t(self) result(file) implicit none class(mimetic_matrix_1D_t), intent(in) :: self type(file_t) file end function + ! END CODE CHUNK end interface @@ -159,6 +279,18 @@ pure module function to_file_t(self) result(file) #if HAVE_DO_CONCURRENT_TYPE_SPEC_SUPPORT && HAVE_LOCALITY_SPECIFIER_SUPPORT + ! PURPOSE: Transforms the upper boundary block submatrix "A" of a mimetic operator into the + ! corresponding lower boundary block "A'" by reversing elements within rows (with sign + ! negation) and then reversing elements within columns, implementing the antisymmetric + ! reflection required by the Corbino & Castillo (2020) mimetic operator structure. + ! KEYWORDS: mimetic, boundary-block, matrix-transformation, antisymmetric, Corbino-Castillo, + ! do-concurrent, utility + ! CONTEXT: This module-level function is compiled for compilers that support do concurrent with + ! type specifiers and locality specifiers. It provides the transformation from the upper + ! block "A" to the lower block "A'" needed when constructing mimetic gradient and + ! divergence operators in the formal library. The gfortran-specific duplicates of this + ! function are defined in divergence_operator_1D_s and gradient_operator_1D_s. Both the + ! gradient and divergence operator constructors call this function during assembly. pure function negate_and_flip(A) result(Ap) !! Transform a mimetic matrix upper block into a lower block double precision, intent(in) :: A(:,:) @@ -177,6 +309,7 @@ pure function negate_and_flip(A) result(Ap) end do reverse_elements_within_columns end function + ! END CODE CHUNK #else diff --git a/src/formal/scalar_1D_s.F90 b/src/formal/scalar_1D_s.F90 index 06a9774..7c2088f 100644 --- a/src/formal/scalar_1D_s.F90 +++ b/src/formal/scalar_1D_s.F90 @@ -23,12 +23,21 @@ #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. - + ! PURPOSE: Constructs a scalar_1D_t object by evaluating a user-provided initializer function on + ! the extended grid (boundary + cell-center locations) and storing the resulting values + ! along with grid metadata and a pre-built gradient operator for the specified order of + ! accuracy and cell count. + ! KEYWORDS: scalar_1D, construction, initializer, structured-grid, staggered-grid, gradient-operator, + ! finite-difference, mimetic, cell-centered, boundary-values + ! CONTEXT: This procedure constructs a scalar_1D_t object in the formal library's mimetic + ! finite-difference framework. The scalar field is initialized on an extended grid + ! consisting of the two domain boundary points plus all cell-center locations, yielding + ! m+2 values where m is the number of cells. The gradient_operator_1D_t is pre-built and + ! stored within the scalar object so that subsequent calls to the .grad. operator can + ! apply it without reconstruction. Assertions verify that x_max > x_min and that the cell + ! count is at least 2*order to support the mimetic stencil width. This version is compiled + ! for non-gfortran compilers; gfortran uses an alternate definition below due to + ! differences in procedure pointer handling in module procedure definitions. module procedure construct_1D_scalar_from_function call_julienne_assert(x_max .greaterThan. x_min) call_julienne_assert(cells .isAtLeast. 2*order) @@ -39,14 +48,24 @@ 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. +#else + ! PURPOSE: Constructs a scalar_1D_t object by evaluating a user-provided initializer function on + ! the extended grid (boundary + cell-center locations) and storing the resulting values + ! along with grid metadata and a pre-built gradient operator for the specified order of + ! accuracy and cell count. This is the gfortran-specific variant with an explicit function + ! signature. + ! KEYWORDS: scalar_1D, construction, initializer, structured-grid, staggered-grid, gradient-operator, + ! finite-difference, mimetic, cell-centered, boundary-values, gfortran + ! CONTEXT: This function is the gfortran-specific variant of construct_1D_scalar_from_function in + ! the formal library's mimetic finite-difference framework. It provides the same + ! functionality as the non-gfortran module procedure but uses an explicit function + ! signature rather than a module procedure definition, working around gfortran limitations + ! with procedure pointer arguments in module procedure definitions. The scalar field is + ! initialized on an extended grid of m+2 values and the gradient_operator_1D_t is + ! pre-built and stored for subsequent .grad. operator applications. Assertions verify + ! that x_max > x_min and that the cell count is at least 2*order. 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 @@ -65,6 +84,16 @@ pure module function construct_1D_scalar_from_function(initializer, order, cells end function ! END CODE CHUNK + ! PURPOSE: Computes the cell-center x-coordinates for a uniform 1D grid given the domain bounds + ! and number of cells, returning an array of cell-center locations offset by half a cell + ! width from x_min. + ! KEYWORDS: grid, cell-center, uniform-mesh, 1D, structured-grid, staggered-grid, utility, gfortran + ! CONTEXT: This helper function is only compiled under gfortran and provides cell-center coordinate + ! computation needed by the scalar_1D submodule. It constructs a uniform grid with cell + ! width dx = (x_max - x_min)/cells and places each cell center at x_min + dx/2 + (cell-1)*dx + ! using an implied do loop. Other compilers use a cell_center_locations function defined + ! elsewhere. This function is used by scalar_1D_grid_locations to build the extended grid + ! array that includes both boundary points and cell centers. pure function cell_center_locations(x_min, x_max, cells) result(x) double precision, intent(in) :: x_min, x_max integer, intent(in) :: cells @@ -75,13 +104,26 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) x = x_min + dx/2. + [((cell-1)*dx, cell = 1, cells)] end associate end function + ! END CODE CHUNK #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. - + ! PURPOSE: Computes the discrete gradient of the scalar_1D field by applying the mimetic gradient + ! operator to the stored values, producing a gradient_1D_t object that carries the + ! node-centered gradient values, grid metadata, a pre-built divergence operator, and + ! verified quadrature weights satisfying the Corbino & Castillo (2020) Eq. 17 identity. + ! KEYWORDS: gradient, mimetic, operator-application, Corbino-Castillo, structured-grid, + ! staggered-grid, scalar_1D, gradient_1D, divergence-operator, quadrature-weights, + ! summation-by-parts, verification + ! CONTEXT: This procedure implements the .grad. operator for scalar_1D_t objects in the formal + ! library's mimetic finite-difference framework. It constructs a gradient_operator_1D_t + ! from the scalar's order and grid spacing, applies it to the scalar's m+2 extended values + ! to produce m+1 node-centered gradient values, and stores a divergence_operator_1D_t + ! within the resulting gradient_1D_t for subsequent use in compound expressions like + ! .div. (.grad. f). After construction, an assertion verifies the Corbino & Castillo (2020) + ! Eq. 17 identity relating the transpose of the assembled gradient matrix, the gradient + ! quadrature weights, and the boundary vector b = [-1, 0, ..., 0, 1], ensuring the + ! discrete operator satisfies the required summation-by-parts property. module procedure grad integer c @@ -100,10 +142,20 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) 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. - + ! PURPOSE: Computes the discrete Laplacian of the scalar_1D field by composing the divergence and + ! gradient operators, and determines the boundary depth at which the Laplacian has + ! reduced-order accuracy. + ! KEYWORDS: laplacian, divergence, gradient, div-grad, mimetic, operator-composition, + ! structured-grid, staggered-grid, scalar_1D, boundary-depth, reduced-order + ! CONTEXT: This procedure implements the .laplacian. operator for scalar_1D_t objects in the formal + ! library's mimetic finite-difference framework. It computes the Laplacian as the + ! composition .div. (.grad. self), with a compiler-conditional workaround for gfortran + ! that calls div(grad(self)) as named function calls rather than using the overloaded + ! operator syntax. The resulting laplacian_1D_t wraps a divergence_1D_t and additionally + ! stores the boundary depth where the Laplacian exhibits reduced-order accuracy, computed + ! as the number of rows in the divergence operator's upper boundary block A plus one. This + ! boundary depth information is used by convergence tests to separately assess interior + ! and boundary error behavior. module procedure laplacian #ifndef __GFORTRAN__ @@ -119,15 +171,30 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) 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. - + ! PURPOSE: Returns the extended cell-centered values stored in a scalar_1D_t object, including both + ! boundary values and interior cell-center values. + ! KEYWORDS: scalar_1D, accessor, cell-centered-values, extended-values, getter, boundary-values + ! CONTEXT: This procedure is a simple accessor that exposes the internally stored m+2 extended + ! values from a scalar_1D_t object in the formal library. The extended values include the + ! two domain boundary values at x_min and x_max plus the m interior cell-center values. + ! These values are used by other operators and test functions for computation and + ! verification. module procedure scalar_1D_values cell_centers_extended_values = self%values_ end procedure ! END CODE CHUNK + ! PURPOSE: Computes the extended grid locations for a scalar_1D field, consisting of the two domain + ! boundary points bracketing the cell-center locations, returning an array of m+2 values. + ! KEYWORDS: grid, cell-center, boundary-points, extended-grid, uniform-mesh, 1D, structured-grid, + ! staggered-grid, utility + ! CONTEXT: This private helper function constructs the extended grid array used by the scalar_1D + ! submodule in the formal library. The extended grid places the domain boundary points + ! x_min and x_max at the first and last positions, with the m cell-center locations from + ! cell_center_locations filling the interior. This m+2 layout matches the scalar_1D_t + ! value storage convention where boundary ghost values bookend the cell-centered data. + ! This function is called by construct_1D_scalar_from_function during initialization and + ! by scalar_1D_grid to provide grid coordinates. pure function scalar_1D_grid_locations(x_min, x_max, cells) result(x) double precision, intent(in) :: x_min, x_max integer, intent(in) :: cells @@ -138,12 +205,18 @@ pure function scalar_1D_grid_locations(x_min, x_max, cells) result(x) x = [x_min, cell_center_locations(x_min, x_max, cells), x_max] end associate end function + ! END CODE CHUNK - ! 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. - + ! PURPOSE: Returns the extended grid locations for a scalar_1D_t object by delegating to the + ! scalar_1D_grid_locations helper function. + ! KEYWORDS: grid, cell-center, extended-grid, accessor, scalar_1D, structured-grid, staggered-grid, + ! getter + ! CONTEXT: This procedure provides access to the extended grid coordinates associated with a + ! scalar_1D_t object in the formal library. It delegates to scalar_1D_grid_locations, + ! passing the stored domain bounds and cell count. The returned array of m+2 locations + ! includes the boundary points and cell centers. Test functions and other operators use + ! this accessor to retrieve grid coordinates for constructing spatially-varying expected + ! values when verifying operator results. module procedure scalar_1D_grid cell_centers_extended = scalar_1D_grid_locations(self%x_min_, self%x_max_, self%cells_) end procedure diff --git a/src/formal/scalar_x_divergence_1D_s.F90 b/src/formal/scalar_x_divergence_1D_s.F90 index 1d3ea8d..b23563d 100644 --- a/src/formal/scalar_x_divergence_1D_s.F90 +++ b/src/formal/scalar_x_divergence_1D_s.F90 @@ -9,11 +9,21 @@ 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. - + ! PURPOSE: Computes the discrete volume integral of a scalar_x_divergence_1D_t field by performing + ! a weighted sum of the cell-centered values zero-padded at the boundaries, using the + ! mimetic quadrature weights inherited from the divergence field. + ! KEYWORDS: volume-integral, quadrature, mimetic, scalar-divergence-product, structured-grid, + ! staggered-grid, weighted-sum, boundary-padding, summation-by-parts + ! CONTEXT: This procedure implements the .SSS. volume integration operator for + ! scalar_x_divergence_1D_t objects in the formal library's mimetic finite-difference + ! framework. The scalar_x_divergence_1D_t type represents the element-wise product of a + ! scalar field with a divergence field, and carries both the m cell-centered product values + ! and the m+2 mimetic quadrature weights inherited from the divergence field. The integral + ! is computed as the dot product of the weights with the values zero-padded at both + ! boundaries, consistent with the mimetic divergence operator's structure where the first + ! and last rows are zero. An assertion verifies that the weights array has exactly two more + ! elements than the values array. This integration is used in compound expressions such as + ! .SSS. (f * .div. v) * dV within the extended Gauss divergence theorem test. 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]) diff --git a/src/formal/tensor_1D_s.f90 b/src/formal/tensor_1D_s.f90 index f7a6f09..79a5e39 100644 --- a/src/formal/tensor_1D_s.f90 +++ b/src/formal/tensor_1D_s.f90 @@ -5,11 +5,18 @@ 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. - + ! PURPOSE: Constructs a tensor_1D_t object by storing the provided array of field values along with + ! the domain bounds, cell count, and order of accuracy as internal components. + ! KEYWORDS: tensor_1D, construction, initialization, structured-grid, staggered-grid, field-values, + ! grid-metadata + ! CONTEXT: This procedure is the fundamental constructor for the tensor_1D_t base type in the formal + ! library's mimetic finite-difference framework. The tensor_1D_t type serves as the common + ! parent type for scalar_1D_t, vector_1D_t, gradient_1D_t, divergence_1D_t, and other + ! tensor field types, storing the field values array, domain bounds x_min and x_max, cell + ! count, and order of accuracy. Derived type constructors such as + ! construct_1D_scalar_from_function and construct_1D_vector_from_function delegate to this + ! procedure to initialize their tensor_1D_t base component after computing the field values + ! from a user-provided initializer function. module procedure construct_1D_tensor_from_components tensor_1D%values_ = values tensor_1D%x_min_ = x_min @@ -19,10 +26,16 @@ 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. - + ! PURPOSE: Computes and returns the uniform cell width dx for the 1D grid by dividing the domain + ! length by the number of cells. + ! KEYWORDS: cell-width, grid-spacing, uniform-mesh, accessor, tensor_1D, structured-grid, + ! staggered-grid, getter + ! CONTEXT: This procedure provides the uniform cell width dx = (x_max - x_min) / cells for a + ! tensor_1D_t object in the formal library. The cell width is a fundamental grid parameter + ! used throughout the mimetic finite-difference framework when constructing gradient, + ! divergence, and Laplacian operators, computing quadrature weights, and evaluating + ! differential volume and area elements. Rather than storing dx as a separate component, + ! it is computed on the fly from the stored domain bounds and cell count. module procedure dx dx = (self%x_max_ - self%x_min_)/self%cells_ end procedure diff --git a/src/formal/tensors_1D_m.F90 b/src/formal/tensors_1D_m.F90 index 3c817d1..d65053e 100644 --- a/src/formal/tensors_1D_m.F90 +++ b/src/formal/tensors_1D_m.F90 @@ -24,27 +24,12 @@ module tensors_1D_m abstract interface - ! PURPOSE: Interface for procedure to provide values for initializing a scalar_1D_t object at the cell centers and boundaries - ! for use in the mimetic discretization scheme of Corbino-Castillo (2020) - ! KEYWORDS: mimetic discretization, scalar function, sampling, one-dimensional (1D) - ! CONTEXT: This abstract interface is used to declare a procedure pointer that can be associated with - ! a user-defined function. The user's function can be invoked via this abstract interface - ! to sample the function at the appropriate grid locations. - pure function scalar_1D_initializer_i(x) result(f) !! Sampling function for initializing a scalar_1D_t object implicit none double precision, intent(in) :: x(:) double precision, allocatable :: f(:) end function - ! END CODE CHUNK - - ! PURPOSE: Interface for procedure to provide values for initializing a vector function of one spatial dimension at cell faces - ! as defined in the mimetic discretization scheme of Corbino-Castillo (2020). - ! KEYWORDS: mimetic discretization, vector function, sampling, 1D - ! CONTEXT: This abstract interface is used to declare a procedure pointer that can be associated with - ! a user-defined function. The user's function can be invoked via this abstract interface - ! to sample the function at the appropriate grid locations. pure function vector_1D_initializer_i(x) result(v) !! Sampling function for initializing a vector_1D_t object @@ -52,15 +37,23 @@ pure function vector_1D_initializer_i(x) result(v) double precision, intent(in) :: x(:) double precision, allocatable :: v(:) end function - ! END CODE CHUNK end interface - ! PURPOSE: Definition for type to encapsulate the data and operations that are common to most or all tensor_1D_t child types - ! KEYWORDS: type definition, mimetic discretization, grid values, grid functions, 1D - ! CONTEXT: Child types extend this derived type to define specific types of tensors such as scalars, - ! vectors, gradients, and divergences. - + ! PURPOSE: Encapsulates the components common to all 1D tensor field types, including domain bounds, + ! cell count, order of accuracy, and the array of field values at spatial locations. Child + ! types define the differential operators supported by each specific tensor kind. + ! KEYWORDS: tensor_1D, base-type, structured-grid, staggered-grid, mimetic, field-values, + ! grid-metadata, domain-bounds, cell-count, order-of-accuracy + ! CONTEXT: This type is the common base for all 1D tensor field types in the formal library's + ! mimetic finite-difference framework, including scalar_1D_t, vector_1D_t, gradient_1D_t, + ! divergence_1D_t, vector_dot_gradient_1D_t, scalar_x_divergence_1D_t, weighted_product_1D_t, + ! and laplacian_1D_t. It stores the domain bounds x_min and x_max, the number of grid + ! cells, the order of accuracy of the mimetic discretization, and an allocatable array of + ! field values whose size and meaning depend on the child type (m+2 for cell-centered + ! extended scalars, m+1 for face-centered vectors, m for cell-centered divergences, etc.). + ! The type provides private procedures for computing gradient and divergence quadrature + ! weights and a public dV (aliased to dx) accessor for the differential volume element. type tensor_1D_t !! Encapsulate the components that are common to all 1D tensors. !! Child types define the operations supported by each child, including @@ -81,11 +74,15 @@ pure function vector_1D_initializer_i(x) result(v) interface tensor_1D_t - ! PURPOSE: Interface for 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. - + ! PURPOSE: Constructs a tensor_1D_t object by assigning the provided field values, domain bounds, + ! cell count, and order of accuracy to the corresponding components. + ! KEYWORDS: tensor_1D, construction, initialization, field-values, grid-metadata, structured-grid, + ! staggered-grid + ! CONTEXT: This interface provides the user-defined constructor for the tensor_1D_t base type in + ! the formal library. All derived tensor types delegate to this constructor to initialize + ! their tensor_1D_t base component after computing field values from initializer functions + ! or operator applications. The implementation in tensor_1D_s performs direct assignment + ! of the dummy arguments to the corresponding private components. pure module function construct_1D_tensor_from_components(values, x_min, x_max, cells, order) result(tensor_1D) !! User-defined constructor: result is a 1D tensor defined by assigning the dummy arguments to corresponding components implicit none @@ -100,10 +97,18 @@ pure module function construct_1D_tensor_from_components(values, x_min, x_max, c end interface - ! PURPOSE: Definition for type to encapsulate a scalar function of one spatial dimension as a tensor with a gradient operator. - ! KEYWORDS: type definition, 1D scalar field abstraction - ! CONTEXT: Combine with other tensors via expressions that may include differential operators - + ! PURPOSE: Encapsulates a 1D scalar field defined at cell centers and domain boundaries (m+2 + ! values), along with a pre-built gradient operator, and provides the .grad. and + ! .laplacian. differential operators. + ! KEYWORDS: scalar_1D, scalar-field, cell-centered, boundary-values, gradient-operator, laplacian, + ! mimetic, structured-grid, staggered-grid, operator-overloading + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent a scalar field on the extended cell-centered grid (m cell centers + ! plus 2 boundary values). It stores a gradient_operator_1D_t for efficient application of + ! the .grad. operator, which maps the m+2 scalar values to m+1 node-centered gradient + ! values. The .laplacian. operator composes .div. and .grad. to produce the discrete + ! Laplacian. The type also provides grid and values accessors for retrieving the extended + ! grid coordinates and field values respectively. type, extends(tensor_1D_t) :: scalar_1D_t !! Encapsulate scalar values at cell centers and boundaries private @@ -122,12 +127,18 @@ pure module function construct_1D_tensor_from_components(values, x_min, x_max, c interface scalar_1D_t - ! PURPOSE: Interface for 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. - + ! PURPOSE: Constructs a scalar_1D_t object by evaluating a user-provided initializer function on + ! the extended grid and storing the resulting values along with a pre-built gradient + ! operator. + ! KEYWORDS: scalar_1D, construction, initializer, structured-grid, staggered-grid, + ! gradient-operator, mimetic, cell-centered, boundary-values + ! CONTEXT: This interface provides the constructor for scalar_1D_t in the formal library's + ! mimetic finite-difference framework. The implementation in scalar_1D_s evaluates the + ! initializer function pointer on the m+2 extended grid (boundary points plus cell + ! centers), stores the values as the tensor_1D_t base component, and pre-builds a + ! gradient_operator_1D_t for the specified order and grid spacing. Assertions verify + ! that x_max > x_min and that the cell count is at least 2*order. A gfortran-specific + ! variant with an explicit function signature is provided in the implementation. pure module function construct_1D_scalar_from_function(initializer, order, cells, x_min, x_max) result(scalar_1D) !! Result is a collection of cell-centered-extended values with a corresponding mimetic gradient operator implicit none @@ -142,10 +153,22 @@ pure module function construct_1D_scalar_from_function(initializer, order, cells end interface - ! PURPOSE: Definition for type to encapsulate a vector function of one spatial dimension as a tensor with a divergence operator. - ! KEYWORDS: type definition, 1D vector field abstraction - ! CONTEXT: Combine with other tensors via expressions that may include differential operators - + ! PURPOSE: Encapsulates a 1D vector field defined at cell faces (m+1 values), along with a + ! pre-built divergence operator, and provides the .div., .dot., and .x. operators for + ! divergence, surface-normal dot product, and weighted scalar premultiplication + ! respectively. + ! KEYWORDS: vector_1D, vector-field, face-centered, divergence-operator, mimetic, structured-grid, + ! staggered-grid, operator-overloading, surface-normal, weighted-product + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent a vector field on the face-centered staggered-grid (m+1 face + ! locations including both domain boundaries). It stores a divergence_operator_1D_t for + ! efficient application of the .div. operator, which maps the m+1 face values to m+2 + ! cell-centered values (with zero boundary rows). The .dot. operator computes the dot + ! product with a surface normal dS for boundary integrals, and the .x. operator computes + ! the weighted product with a scalar field using the Corbino & Castillo (2020) Eq. 7 + ! boundary operator. The dA accessor returns the differential area element (unity in 1D). + ! A compiler-conditional block exposes the gradient_1D_weights procedure under the generic + ! name weights for the Intel compiler. type, extends(tensor_1D_t) :: vector_1D_t !! Encapsulate 1D vector values at cell faces (of unit area for 1D) and corresponding operators private @@ -168,10 +191,17 @@ pure module function construct_1D_scalar_from_function(initializer, order, cells end type ! END CODE CHUNK - ! PURPOSE: Definition of type to encapsulate a scalar/vector product weighted for integration on a surface - ! KEYWORDS: type definition, 1D product abstraction - ! CONTEXT: Combine with other tensors via expressions that may include the double integrals - + ! PURPOSE: Encapsulates the result of the weighted product of a vector_1D field and a scalar_1D + ! field via the Corbino & Castillo (2020) Eq. 7 boundary operator, and provides the .SS. + ! surface integration operator. + ! KEYWORDS: weighted-product, boundary-operator, surface-integral, mimetic, Corbino-Castillo, + ! structured-grid, staggered-grid, operator-overloading + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of the .x. weighted premultiplication of a vector_1D_t + ! with a scalar_1D_t. The stored values are the products dx * B * v * f, where B is the + ! Corbino & Castillo (2020) boundary operator from Eq. 7. The .SS. operator performs the + ! surface integral by summing the stored values, implementing the discrete surface + ! integral term in the extended Gauss divergence theorem. type, extends(tensor_1D_t) :: weighted_product_1D_t contains generic :: operator(.SS.) => surface_integrate_vector_x_scalar_1D @@ -181,11 +211,18 @@ pure module function construct_1D_scalar_from_function(initializer, order, cells interface vector_1D_t - ! PURPOSE: Interface for procedure to construct a new vector_1D_t object by sampling a function of one spatial dimension. - ! KEYWORDS: 1D vector field constructor - ! CONTEXT: Invoke this constructor with a pointer associated with a function to be sampled at a set - ! of uniformly-spaced cell faces along one spatial dimension bounded by x_min and x_max. - + ! PURPOSE: Constructs a vector_1D_t object by evaluating a user-provided initializer function on + ! the face-centered grid and storing the resulting values along with a pre-built + ! divergence operator. + ! KEYWORDS: vector_1D, construction, initializer, structured-grid, staggered-grid, + ! divergence-operator, mimetic, face-centered + ! CONTEXT: This interface provides the constructor for vector_1D_t from an initializer function + ! in the formal library's mimetic finite-difference framework. The implementation in + ! vector_1D_s evaluates the initializer function pointer on the m+1 face-centered grid, + ! stores the values as the tensor_1D_t base component, and pre-builds a + ! divergence_operator_1D_t for the specified order and grid spacing. Assertions verify + ! that x_max > x_min and that the cell count is at least 2*order+1. A gfortran-specific + ! variant with an explicit function signature is provided in the implementation. pure module function construct_1D_vector_from_function(initializer, order, cells, x_min, x_max) result(vector_1D) !! Result is a 1D vector with values initialized by the provided procedure pointer sampled on the specified !! number of evenly spaced cells covering [x_min, x_max] @@ -199,11 +236,15 @@ pure module function construct_1D_vector_from_function(initializer, order, cells end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to construct a new vector_1D_t object from a parent tensor and a divergence operator object. - ! KEYWORDS: 1D vector field constructor - ! CONTEXT: Invoke this constructor with a an object to be used to define the constructed parent component - ! divergence-operator matrix component. - + ! PURPOSE: Constructs a vector_1D_t object from pre-existing tensor_1D_t and + ! divergence_operator_1D_t components, bypassing initializer function evaluation. + ! KEYWORDS: vector_1D, construction, component-assembly, tensor_1D, divergence-operator, + ! structured-grid, staggered-grid + ! CONTEXT: This interface provides an alternative constructor for vector_1D_t in the formal + ! library when the field values and divergence operator have already been computed + ! separately. The implementation in vector_1D_s directly assigns the provided components. + ! This is used internally when constructing vector fields from intermediate operator + ! results. pure module function construct_from_components(tensor_1D, divergence_operator_1D) result(vector_1D) !! Result is a 1D vector with the provided parent component tensor_1D and the provided divergence operator type(tensor_1D_t), intent(in) :: tensor_1D @@ -214,10 +255,19 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D end interface - ! PURPOSE: Definition of type for a vector child type for capturing gradient data and a scalar (dot) product operator. - ! KEYWORDS: type definition, 1D gradient vector field abstraction - ! CONTEXT: The scalar_1D_t .grad. operator produces this type as a result. - + ! PURPOSE: Encapsulates a 1D mimetic gradient vector field at node-centered locations (m+1 values), + ! extending vector_1D_t with a .dot. operator that computes the element-wise dot product + ! with another vector_1D field, and a weights accessor for the gradient quadrature weights. + ! KEYWORDS: gradient_1D, gradient-field, node-centered, mimetic, structured-grid, staggered-grid, + ! dot-product, quadrature-weights, operator-overloading + ! CONTEXT: This type extends vector_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of applying the .grad. operator to a scalar_1D_t + ! object. It inherits the divergence operator from vector_1D_t (enabling .div. (.grad. f) + ! for Laplacian computation) and adds a .dot. operator for computing v .dot. grad(f) + ! products that produce vector_dot_gradient_1D_t objects suitable for volume integration. + ! The weights accessor (generic name, with compiler-conditional bindings to + ! gradient_1D_weights) provides the mimetic quadrature weights for node-centered + ! integration. type, extends(vector_1D_t) :: gradient_1D_t !! A 1D mimetic gradient vector field abstraction with a public method that produces corresponding numerical quadrature weights contains @@ -229,10 +279,18 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D end type ! END CODE CHUNK - ! PURPOSE: Definition of type for a tensor child type for capturing the scalar (dot) product of a vector and a gradient vector data - ! KEYWORDS: type definition, 1D vector/gradient scalar product - ! CONTEXT: An instance of this type can serve as an integrand in a .SSS. triple-integral operator. - + ! PURPOSE: Encapsulates the element-wise dot product of a 1D vector field with a 1D gradient field, + ! carrying both the node-centered product values and the gradient quadrature weights, and + ! provides the .SSS. volume integration operator. + ! KEYWORDS: vector-dot-gradient, dot-product, volume-integral, quadrature-weights, mimetic, + ! structured-grid, staggered-grid, node-centered, operator-overloading + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of the .dot. operator applied between a vector_1D_t + ! and a gradient_1D_t. It stores both the m+1 node-centered product values and the m+1 + ! gradient quadrature weights needed for volume integration. The .SSS. operator computes + ! the discrete volume integral as a direct weighted sum of the product values, which + ! appears in compound expressions such as .SSS. (v .dot. .grad. f) * dV within the + ! extended Gauss divergence theorem test. type, extends(tensor_1D_t) :: vector_dot_gradient_1D_t !! Result is the dot product of a 1D vector field and a 1D gradient field private @@ -243,11 +301,18 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D end type ! END CODE CHUNK - ! PURPOSE: Definition of type for a tensor child type capturing the divergence of a vector function of one spatial dimension. - ! KEYWORDS: type definition, 1D, divergence - ! CONTEXT: Although a mathematical scalar, this type differs from scalar_1D_t in that the values are stored - ! _only_ at cell centers, whereas a scalar_1D_t object additionally has values at domain boundaries. - + ! PURPOSE: Encapsulates a 1D divergence field at cell centers (m values), providing grid and values + ! accessors, divergence quadrature weights, and multiplication operators for combining with + ! scalar fields. + ! KEYWORDS: divergence_1D, divergence-field, cell-centered, mimetic, structured-grid, staggered-grid, + ! quadrature-weights, scalar-multiplication, operator-overloading + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of applying the .div. operator to a vector_1D_t + ! object. The m cell-centered divergence values (with boundary zeros stripped) are stored + ! in the inherited values_ array. The type provides grid and values accessors, a weights + ! accessor for the divergence quadrature weights, and overloaded * operators for + ! premultiplication and postmultiplication with scalar_1D_t fields, producing + ! scalar_x_divergence_1D_t objects suitable for volume integration. type, extends(tensor_1D_t) :: divergence_1D_t !! Encapsulate divergences at cell centers contains @@ -262,10 +327,18 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D end type ! END CODE CHUNK - ! PURPOSE: Definition of type for a tensor child type for capturing the product of a scalar and divergence - ! KEYWORDS: type definition, 1D scalar/divergence product - ! CONTEXT: An instance of this type can serve as an integrand in a .SSS. triple-integral operator. - + ! PURPOSE: Encapsulates the element-wise product of a 1D scalar field with a 1D divergence field, + ! carrying both the cell-centered product values and the divergence quadrature weights, and + ! provides the .SSS. volume integration operator. + ! KEYWORDS: scalar-divergence-product, volume-integral, quadrature-weights, mimetic, structured-grid, + ! staggered-grid, cell-centered, operator-overloading, boundary-padding + ! CONTEXT: This type extends tensor_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of the * operator applied between a scalar_1D_t and a + ! divergence_1D_t. It stores the m cell-centered product values and the m+2 divergence + ! quadrature weights. The .SSS. volume integration operator zero-pads the values at both + ! boundaries before computing the weighted sum, consistent with the zero boundary rows of + ! the divergence operator. This appears in compound expressions such as + ! .SSS. (f * .div. v) * dV within the extended Gauss divergence theorem test. type, extends(tensor_1D_t) :: scalar_x_divergence_1D_t !! product of a 1D scalar field and a 1D divergence field private @@ -276,12 +349,19 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D end type ! END CODE CHUNK - ! PURPOSE: Definition of type for a divergence child type capturing the result of applying a divergence operator to a gradient. - ! KEYWORDS: type definition, 1D, laplacian - ! CONTEXT: Although a mathematical a divergence, this type additionally provides a type-bound procedure that - ! returns the number of boundary-adjacent points at which the Laplacian approximation's accuracy drops by - ! by one order relative to the parent divergence type. - + ! PURPOSE: Encapsulates a 1D discrete Laplacian field computed as the composition of the divergence + ! and gradient operators, extending divergence_1D_t with a boundary depth indicating where + ! the Laplacian has reduced-order accuracy. + ! KEYWORDS: laplacian_1D, laplacian, div-grad, divergence, gradient, mimetic, structured-grid, + ! staggered-grid, boundary-depth, reduced-order, operator-composition + ! CONTEXT: This type extends divergence_1D_t in the formal library's mimetic finite-difference + ! framework to represent the result of applying the .laplacian. operator to a scalar_1D_t + ! object. The Laplacian is computed as .div. (.grad. f), inheriting all divergence_1D_t + ! functionality. The additional boundary_depth_ component records the number of cells from + ! each boundary where the Laplacian exhibits reduced-order accuracy due to the boundary + ! stencils, computed as the divergence operator's upper block row count plus one. The + ! reduced_order_boundary_depth accessor provides this information for convergence tests + ! that separately assess interior and boundary error behavior. type, extends(divergence_1D_t) :: laplacian_1D_t private integer boundary_depth_ @@ -292,10 +372,15 @@ pure module function construct_from_components(tensor_1D, divergence_operator_1D interface - ! PURPOSE: Interface for procedure to provide the differential area for use in surface integrals. - ! KEYWORDS: surface integral, area integral, double integral, numerical quadrature, mimetic discretization - ! CONTEXT: Use this in expressions of the form .SS. (f .x. (v .dot. dA)) with a scalar_1D_t f and vector_1D_t v - + ! PURPOSE: Returns the differential area element dA for the 1D case, which is always 1.0 since + ! the cross-sectional area of a 1D domain is unity. + ! KEYWORDS: differential-area, surface-element, 1D, vector_1D, accessor, getter, boundary-integral + ! CONTEXT: This interface declares the accessor that returns the differential area element for a + ! vector_1D_t object in the formal library's mimetic finite-difference framework. In one + ! spatial dimension, the surface bounding each cell is a point with unit area, so dA is + ! trivially 1.0. This accessor exists to maintain a consistent interface with + ! higher-dimensional generalizations where dA would be a nontrivial geometric quantity. + ! It is used in surface integral expressions such as .SS. (f .x. (v .dot. dA)). pure module function dA(self) !! Result is the grid's discrete surface-area differential for use in surface integrals of the form !! .SS. (f .x. (v .dot. dA)) @@ -305,10 +390,15 @@ pure module function dA(self) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes and returns the uniform cell width dx for the 1D grid by dividing the domain + ! length by the number of cells. + ! KEYWORDS: cell-width, grid-spacing, uniform-mesh, accessor, tensor_1D, structured-grid, + ! staggered-grid, differential-volume, getter + ! CONTEXT: This interface declares the accessor that returns the uniform cell width + ! dx = (x_max - x_min) / cells for a tensor_1D_t object in the formal library. The cell + ! width serves double duty as the differential volume element dV in 1D (exposed via the + ! generic binding dV => dx). It is used throughout the mimetic framework when + ! constructing operators, computing quadrature weights, and evaluating integrals. pure module function dx(self) !! Result is the uniform cell width implicit none @@ -317,11 +407,15 @@ pure module function dx(self) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Returns the extended grid locations for a scalar_1D_t object, consisting of the two + ! domain boundary points bracketing the cell-center locations (m+2 values). + ! KEYWORDS: grid, cell-center, boundary-points, extended-grid, scalar_1D, accessor, getter, + ! structured-grid, staggered-grid + ! CONTEXT: This interface declares the grid accessor for scalar_1D_t in the formal library. The + ! implementation in scalar_1D_s delegates to the scalar_1D_grid_locations helper + ! function, returning an array of m+2 locations that includes x_min, the m cell-center + ! coordinates, and x_max. These coordinates correspond positionally to the m+2 extended + ! scalar field values. pure module function scalar_1D_grid(self) result(cell_centers_extended) !! Result is the array of locations at which 1D scalars are defined: cell centers augmented by spatial boundaries implicit none @@ -330,11 +424,13 @@ pure module function scalar_1D_grid(self) result(cell_centers_extended) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to provide staggered-grid locations at which vector values are stored: cell faces. - ! KEYWORDS: abcissa, cell faces - ! CONTEXT: Invoke this function via the "grid" generic binding to produce discrete vector locations for - ! initialization-function sampling, printing, or plotting. - + ! PURPOSE: Returns the face-centered grid locations for a vector_1D_t object, consisting of m+1 + ! face locations including both domain boundaries. + ! KEYWORDS: grid, face-centered, vector_1D, accessor, getter, structured-grid, staggered-grid + ! CONTEXT: This interface declares the grid accessor for vector_1D_t in the formal library. The + ! implementation in vector_1D_s delegates to the faces helper function, returning an + ! array of m+1 face locations from x_min to x_max. These coordinates correspond + ! positionally to the m+1 face-centered vector field values. pure module function vector_1D_grid(self) result(cell_faces) !! Result is the array of cell face locations (of unit area for 1D) at which 1D vectors are defined implicit none @@ -343,11 +439,15 @@ pure module function vector_1D_grid(self) result(cell_faces) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Returns the cell-center grid locations for a divergence_1D_t object, consisting of m + ! interior cell-center coordinates. + ! KEYWORDS: grid, cell-center, divergence_1D, accessor, getter, structured-grid, staggered-grid + ! CONTEXT: This interface declares the grid accessor for divergence_1D_t in the formal library. + ! The implementation in divergence_1D_s returns an array of m cell-center coordinates, + ! corresponding to the interior cells where the divergence field is defined. Unlike the + ! scalar_1D grid which includes boundary points, the divergence grid contains only + ! interior cell centers because the divergence operator produces zero boundary rows that + ! are stripped during construction. pure module function divergence_1D_grid(self) result(cell_centers) !! Result is the array of cell centers at which 1D divergences are defined implicit none @@ -356,10 +456,13 @@ pure module function divergence_1D_grid(self) result(cell_centers) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Returns the extended cell-centered values stored in a scalar_1D_t object, including + ! both boundary values and interior cell-center values (m+2 values). + ! KEYWORDS: scalar_1D, accessor, cell-centered-values, extended-values, getter, boundary-values + ! CONTEXT: This interface declares the values accessor for scalar_1D_t in the formal library. The + ! implementation in scalar_1D_s returns the internally stored m+2 extended values + ! including the two domain boundary values at x_min and x_max plus the m interior + ! cell-center values. pure module function scalar_1D_values(self) result(cell_centers_extended_values) !! Result is an array of 1D scalar values at boundaries and cell centers implicit none @@ -368,10 +471,11 @@ pure module function scalar_1D_values(self) result(cell_centers_extended_values) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to provide the cell face-centered values of vector quantities. - ! KEYWORDS: staggered grid, vector field - ! CONTEXT: Invoke this function via the "values" generic binding to produce discrete vector values. - + ! PURPOSE: Returns the face-centered vector values stored in a vector_1D_t object (m+1 values). + ! KEYWORDS: vector_1D, accessor, face-centered-values, getter + ! CONTEXT: This interface declares the values accessor for vector_1D_t in the formal library. The + ! implementation in vector_1D_s returns the internally stored m+1 face-centered values + ! including both domain boundary faces and all interior cell faces. pure module function vector_1D_values(self) result(face_centered_values) !! Result is an array of the 1D vector values at cell faces (of unit area 1D) implicit none @@ -380,10 +484,13 @@ pure module function vector_1D_values(self) result(face_centered_values) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Returns the cell-centered divergence values stored in a divergence_1D_t object (m + ! values). + ! KEYWORDS: divergence_1D, accessor, cell-centered-values, getter + ! CONTEXT: This interface declares the values accessor for divergence_1D_t in the formal library. + ! The implementation in divergence_1D_s returns the internally stored m cell-centered + ! divergence values, which are the interior entries of the divergence operator's output + ! with boundary zeros stripped. pure module function divergence_1D_values(self) result(cell_centered_values) !! Result is an array of 1D divergences at cell centers implicit none @@ -392,10 +499,16 @@ pure module function divergence_1D_values(self) result(cell_centered_values) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the discrete gradient of the scalar_1D field by applying the mimetic gradient + ! operator, producing a gradient_1D_t object with node-centered gradient values and + ! verified quadrature weights satisfying the Corbino & Castillo (2020) Eq. 17 identity. + ! KEYWORDS: gradient, mimetic, operator-application, Corbino-Castillo, scalar_1D, gradient_1D, + ! divergence-operator, quadrature-weights, summation-by-parts, verification + ! CONTEXT: This interface declares the .grad. operator for scalar_1D_t in the formal library. The + ! implementation in scalar_1D_s constructs a gradient_operator_1D_t, applies it to the + ! scalar's m+2 extended values to produce m+1 node-centered gradient values, stores a + ! divergence_operator_1D_t in the result, and verifies the Corbino & Castillo (2020) + ! Eq. 17 summation-by-parts identity. pure module function grad(self) result(gradient_1D) !! Result is mimetic gradient of the scalar_1D_t "self" implicit none @@ -404,10 +517,16 @@ pure module function grad(self) result(gradient_1D) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the discrete Laplacian of the scalar_1D field by composing the divergence and + ! gradient operators, and determines the boundary depth where the Laplacian has + ! reduced-order accuracy. + ! KEYWORDS: laplacian, divergence, gradient, div-grad, mimetic, operator-composition, scalar_1D, + ! laplacian_1D, boundary-depth, reduced-order + ! CONTEXT: This interface declares the .laplacian. operator for scalar_1D_t in the formal library. + ! The implementation in scalar_1D_s computes the Laplacian as .div. (.grad. self) and + ! stores the boundary depth (divergence operator's upper block row count plus one) in + ! the resulting laplacian_1D_t for use in convergence tests that separately assess + ! interior and boundary error behavior. pure module function laplacian(self) result(laplacian_1D) !! Result is mimetic Laplacian of the scalar_1D_t "self" implicit none @@ -416,10 +535,14 @@ pure module function laplacian(self) result(laplacian_1D) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Returns the number of nodes from the boundary at which the Laplacian exhibits + ! reduced-order convergence rate (one degree lower than the interior). + ! KEYWORDS: laplacian_1D, boundary-depth, reduced-order, convergence, accessor, getter + ! CONTEXT: This interface declares the accessor for the boundary depth of a laplacian_1D_t object + ! in the formal library. The boundary depth indicates how many cells from each boundary + ! the Laplacian has reduced-order accuracy due to the boundary stencils in the mimetic + ! gradient and divergence operators. Convergence tests use this value to partition the + ! domain into interior and boundary regions for separate error analysis. pure module function reduced_order_boundary_depth(self) result(num_nodes) !! Result is number of nodes away from the boundary for which convergence rate is one degree lower implicit none @@ -428,10 +551,17 @@ pure module function reduced_order_boundary_depth(self) result(num_nodes) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to compute mimetic approximations to the divergence of a vector field. - ! KEYWORDS: divergence, vector field - ! CONTEXT: Invoke this function via the unary .div. operator with a right-hand-side vector-field operand. - + ! PURPOSE: Computes the discrete divergence of the vector_1D field by applying the mimetic + ! divergence operator, producing a divergence_1D_t object with cell-centered divergence + ! values and verified quadrature weights satisfying the Corbino & Castillo (2020) Eq. 19 + ! identity. + ! KEYWORDS: divergence, mimetic, operator-application, Corbino-Castillo, vector_1D, divergence_1D, + ! quadrature-weights, summation-by-parts, verification + ! CONTEXT: This interface declares the .div. operator for vector_1D_t in the formal library. The + ! implementation in vector_1D_s applies the stored divergence_operator_1D_t to the + ! vector's m+1 face-centered values, strips the zero boundary entries to yield m + ! cell-centered divergence values, and verifies the Corbino & Castillo (2020) Eq. 19 + ! summation-by-parts identity D^T * q = b/dx. pure module function div(self) result(divergence_1D) !! Result is mimetic divergence of the vector_1D_t "self" implicit none @@ -440,11 +570,17 @@ pure module function div(self) result(divergence_1D) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to perform mimetic volume integration of a vector/scalar-gradient dot product. - ! KEYWORDS: triple integral, volume integral - ! CONTEXT: Invoke this function in expressions of the form .SSS. (v .dot. .grad. f) * dV - ! with a vector_1D_t v, a scalar f, and a differential volume dV. - + ! PURPOSE: Computes the discrete volume integral of a vector_dot_gradient_1D_t field by + ! performing a weighted sum of the node-centered product values using the mimetic + ! gradient quadrature weights. + ! KEYWORDS: volume-integral, quadrature, mimetic, vector-dot-gradient, weighted-sum, + ! summation-by-parts, node-centered + ! CONTEXT: This interface declares the .SSS. volume integration operator for + ! vector_dot_gradient_1D_t in the formal library. The implementation in + ! vector_dot_gradient_1D_s computes the integral as a direct weighted sum of the m+1 + ! node-centered product values with the gradient quadrature weights. This appears in + ! compound expressions such as .SSS. (v .dot. .grad. f) * dV within the extended Gauss + ! divergence theorem test. pure module function volume_integrate_vector_dot_grad_scalar_1D(integrand) result(integral) !! Result is the mimetic quadrature corresponding to a volume integral of a vector-gradient dot product implicit none @@ -453,11 +589,17 @@ pure module function volume_integrate_vector_dot_grad_scalar_1D(integrand) resul end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the discrete volume integral of a scalar_x_divergence_1D_t field by + ! performing a weighted sum of the cell-centered product values (zero-padded at + ! boundaries) using the mimetic divergence quadrature weights. + ! KEYWORDS: volume-integral, quadrature, mimetic, scalar-divergence-product, weighted-sum, + ! summation-by-parts, cell-centered, boundary-padding + ! CONTEXT: This interface declares the .SSS. volume integration operator for + ! scalar_x_divergence_1D_t in the formal library. The implementation in + ! scalar_x_divergence_1D_s zero-pads the m product values at both boundaries and + ! computes the weighted sum with the m+2 divergence quadrature weights. This appears in + ! compound expressions such as .SSS. (f * .div. v) * dV within the extended Gauss + ! divergence theorem test. pure module function volume_integrate_scalar_x_divergence_1D(integrand) result(integral) !! Result is the mimetic quadrature corresponding to a volume integral of a scalar-divergence product implicit none @@ -466,11 +608,15 @@ pure module function volume_integrate_scalar_x_divergence_1D(integrand) result(i end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to perform mimetic surface integration of a scalar/vector product. - ! KEYWORDS: double integral, surface integral, flux - ! CONTEXT: Invoke this function in expressions of the form -.SS. (f .x. (v .dot. dA)) - ! with a vector_1D_t v, a scalar_1D_t f, and a differential area dA. - + ! PURPOSE: Computes the discrete surface integral of a weighted_product_1D_t field by summing + ! the stored boundary-weighted product values. + ! KEYWORDS: surface-integral, quadrature, mimetic, Corbino-Castillo, weighted-product, + ! boundary-operator, summation + ! CONTEXT: This interface declares the .SS. surface integration operator for + ! weighted_product_1D_t in the formal library. The implementation sums the stored values + ! that were computed as dx * B * v * f by the weighted_premultiply procedure, where B is + ! the Corbino & Castillo (2020) Eq. 7 boundary operator. This represents the surface + ! integral term in the extended Gauss divergence theorem. pure module function surface_integrate_vector_x_scalar_1D(integrand) result(integral) !! Result is the mimetic quadrature corresponding to a surface integral of a scalar-vector product implicit none @@ -479,11 +625,17 @@ pure module function surface_integrate_vector_x_scalar_1D(integrand) result(inte end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the element-wise dot product of a vector_1D field with a gradient_1D field, + ! producing a vector_dot_gradient_1D_t object that carries both the node-centered + ! product values and the gradient quadrature weights for subsequent volume integration. + ! KEYWORDS: dot-product, vector-gradient, mimetic, node-centered, quadrature-weights, + ! structured-grid, staggered-grid, operator-overloading + ! CONTEXT: This interface declares the .dot. operator between a vector_1D_t and a gradient_1D_t + ! in the formal library. The implementation in gradient_1D_s computes the element-wise + ! product of the vector and gradient face-centered values and stores the result along + ! with the gradient quadrature weights in a vector_dot_gradient_1D_t object. The + ! gradient_1D argument is the passed-object dummy, allowing the syntax + ! v .dot. (.grad. f) where the gradient result is the dispatching object. pure module function dot(vector_1D, gradient_1D) result(vector_dot_gradient_1D) !! Result is the mimetic divergence of the vector_1D_t "self" implicit none @@ -493,11 +645,17 @@ pure module function dot(vector_1D, gradient_1D) result(vector_dot_gradient_1D) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to compute the scalar (not) product of a vector and a differential area. - ! KEYWORDS: dot product, flux, surface-normal - ! CONTEXT: Inovke this function via the .dot. binary infix operator in expressions of the form - ! .SS. (f .x. (v .dot. dA)) with a saclar_1D_t f, a vector_1D_t v, and a differential area A. - + ! PURPOSE: Computes the dot product of a vector_1D field with a surface normal differential area + ! element dS, producing a vector_1D_t object that carries the element-wise product of + ! the face-centered vector values with dS and inherits the vector's divergence operator. + ! KEYWORDS: dot-product, surface-normal, differential-area, vector_1D, operator-overloading, + ! structured-grid, staggered-grid, mimetic, boundary-integral, face-centered + ! CONTEXT: This interface declares the .dot. operator between a vector_1D_t and a scalar dS in + ! the formal library. The implementation in vector_1D_s performs element-wise + ! multiplication of the face-centered vector values with dS and returns a new vector_1D_t + ! that inherits the divergence operator. In 1D the surface normal dS is a scalar, so + ! the operation is a simple scaling. This is used in surface integral expressions such + ! as .SS. (f .x. (v .dot. dA)). pure module function dot_surface_normal(vector_1D, dS) result(v_dot_dS) !! Result is magnitude of a vector/surface-normal dot product for use in surface integrals of the form !! `.SS. (f .x. (v .dot. dA))` @@ -509,11 +667,18 @@ pure module function dot_surface_normal(vector_1D, dS) result(v_dot_dS) end function ! END CODE CHUNK - ! PURPOSE: Interface for procedure to compute a scalar/vector product weighted for subsequent surface integration. - ! KEYWORDS: integrand, surface integral, double integral - ! CONTEXT: Inovke this function .x. binary infix operator in expressions of the form - ! .SS. (f .x. (v .dot. dA)) with a saclar_1D_t f, a vector_1D_t v, and a differential area A. - + ! PURPOSE: Computes the weighted product of a scalar_1D field and a vector_1D field using the + ! mimetic boundary operator B from Corbino & Castillo (2020) Eq. 7, producing a + ! weighted_product_1D_t suitable for surface integration. + ! KEYWORDS: weighted-product, boundary-operator, mimetic, Corbino-Castillo, product-rule, + ! structured-grid, staggered-grid, divergence, gradient, quadrature-weights, + ! summation-by-parts, scalar_1D, vector_1D + ! CONTEXT: This interface declares the .x. operator between a scalar_1D_t and a vector_1D_t in + ! the formal library. The implementation in vector_1D_s assembles the boundary operator + ! B = Q*D + G^T*P from Corbino & Castillo (2020) Eq. 7 and computes + ! dx * B * v * f. The result is a weighted_product_1D_t whose values can be surface- + ! integrated via the .SS. operator to yield the boundary term in the extended Gauss + ! divergence theorem. pure module function weighted_premultiply(scalar_1D, vector_1D) result(weighted_product_1D) !! Result is the product of a boundary-weighted vector_1D_t with a scalar_1D_t implicit none @@ -523,12 +688,18 @@ pure module function weighted_premultiply(scalar_1D, vector_1D) result(weighted_ end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the gradient quadrature weights for a tensor_1D_t object, returning an array + ! of m+1 weights used for weighted inner products involving gradient fields on the + ! node-centered staggered-grid. + ! KEYWORDS: quadrature-weights, gradient, mimetic, node-centered, structured-grid, staggered-grid, + ! summation-by-parts, accessor + ! CONTEXT: This interface declares the gradient quadrature weights accessor for tensor_1D_t in + ! the formal library. The implementation in weights_1D_s computes the m+1 quadrature + ! weights for integrating products on the node-centered grid where gradient fields are + ! defined. These weights appear in the summation-by-parts identities (Corbino & Castillo, + ! 2020, Eq. 17) and in the boundary operator B construction (Eq. 7). The procedure is + ! bound to tensor_1D_t and exposed via the generic name weights on gradient_1D_t and + ! (conditionally) vector_1D_t. pure module function gradient_1D_weights(self) result(weights) !! Result is an array of quadrature coefficients that can be used to compute a weighted !! inner product of a vector_1D_t object and a gradient_1D_t object. @@ -538,12 +709,18 @@ pure module function gradient_1D_weights(self) result(weights) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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. - + ! PURPOSE: Computes the divergence quadrature weights for a tensor_1D_t object, returning an + ! array of m+2 weights used for weighted inner products involving divergence fields on + ! the cell-centered extended grid. + ! KEYWORDS: quadrature-weights, divergence, mimetic, cell-centered, structured-grid, staggered-grid, + ! summation-by-parts, accessor + ! CONTEXT: This interface declares the divergence quadrature weights accessor for tensor_1D_t in + ! the formal library. The implementation in weights_1D_s computes the m+2 quadrature + ! weights for integrating products on the cell-centered extended grid where divergence + ! fields are defined. These weights appear in the summation-by-parts identities (Corbino + ! & Castillo, 2020, Eq. 19) and in the boundary operator B construction (Eq. 7). The + ! procedure is bound to tensor_1D_t and exposed via the generic name weights on + ! divergence_1D_t. pure module function divergence_1D_weights(self) result(weights) !! Result is an array of quadrature coefficients that can be used to compute a weighted !! inner product of a scalar_1D_t object and a divergence_1D_t object. @@ -553,11 +730,18 @@ pure module function divergence_1D_weights(self) result(weights) end function ! END CODE CHUNK - ! PURPOSE: Interface for 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 - + ! PURPOSE: Computes the element-wise product of a scalar_1D field premultiplied onto a + ! divergence_1D field, producing a scalar_x_divergence_1D_t that carries the + ! cell-centered product values and the divergence quadrature weights for subsequent + ! volume integration. + ! KEYWORDS: scalar-divergence-product, premultiply, mimetic, cell-centered, quadrature-weights, + ! structured-grid, staggered-grid, operator-overloading + ! CONTEXT: This interface declares the * operator with a scalar_1D_t on the left and a + ! divergence_1D_t on the right in the formal library. The implementation in + ! divergence_1D_s extracts the interior m cell-center values from the scalar field, + ! multiplies them element-wise with the divergence values, and stores the result along + ! with the divergence quadrature weights in a scalar_x_divergence_1D_t. The pass + ! attribute on divergence_1D makes this a type-bound procedure of divergence_1D_t. pure module function premultiply_scalar_1D(scalar_1D, divergence_1D) result(scalar_x_divergence_1D) !! Result is the point-wise product of a 1D scalar field and the divergence of a 1D vector field implicit none @@ -567,11 +751,17 @@ pure module function premultiply_scalar_1D(scalar_1D, divergence_1D) result(scal end function ! END CODE CHUNK - ! PURPOSE: Interface for 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 - + ! PURPOSE: Computes the element-wise product of a divergence_1D field postmultiplied by a + ! scalar_1D field, producing a scalar_x_divergence_1D_t that carries the cell-centered + ! product values and the divergence quadrature weights for subsequent volume integration. + ! KEYWORDS: scalar-divergence-product, postmultiply, mimetic, cell-centered, quadrature-weights, + ! structured-grid, staggered-grid, operator-overloading + ! CONTEXT: This interface declares the * operator with a divergence_1D_t on the left and a + ! scalar_1D_t on the right in the formal library. The implementation in divergence_1D_s + ! extracts the interior m cell-center values from the scalar field, multiplies them + ! element-wise with the divergence values, and stores the result along with the + ! divergence quadrature weights in a scalar_x_divergence_1D_t. This provides + ! commutativity of the scalar-divergence product. pure module function postmultiply_scalar_1D(divergence_1D, scalar_1D) result(scalar_x_divergence_1D) !! Result is the point-wise product of a 1D scalar field and the divergence of a 1D vector field implicit none @@ -587,6 +777,17 @@ pure module function postmultiply_scalar_1D(divergence_1D, scalar_1D) result(sca contains + ! PURPOSE: Computes the cell-center x-coordinates for a uniform 1D grid given the domain bounds + ! and number of cells, returning an array of cell-center locations offset by half a cell + ! width from x_min. + ! KEYWORDS: grid, cell-center, uniform-mesh, 1D, structured-grid, staggered-grid, utility + ! CONTEXT: This module-level function is compiled for non-gfortran compilers and provides + ! cell-center coordinate computation needed throughout the tensors_1D_m module. It + ! constructs a uniform grid with cell width dx = (x_max - x_min)/cells and places each + ! cell center at x_min + dx/2 + (cell-1)*dx using an implied do loop. For gfortran, an + ! identical function is defined locally within the scalar_1D_s submodule. This function + ! is used by scalar_1D_grid_locations to build the extended grid array that includes both + ! boundary points and cell centers. pure function cell_center_locations(x_min, x_max, cells) result(x) double precision, intent(in) :: x_min, x_max integer, intent(in) :: cells @@ -597,6 +798,7 @@ pure function cell_center_locations(x_min, x_max, cells) result(x) x = x_min + dx/2. + [((cell-1)*dx, cell = 1, cells)] end associate end function + ! END CODE CHUNK #endif diff --git a/src/formal/vector_1D_s.F90 b/src/formal/vector_1D_s.F90 index 65bbf25..38ea22a 100644 --- a/src/formal/vector_1D_s.F90 +++ b/src/formal/vector_1D_s.F90 @@ -22,11 +22,18 @@ contains - ! PURPOSE: Definition of procedure to compute the scalar (not) product of a vector and a differential area. - ! KEYWORDS: dot product, flux, surface-normal - ! CONTEXT: Inovke this function via the .dot. binary infix operator in expressions of the form - ! .SS. (f .x. (v .dot. dA)) with a saclar_1D_t f, a vector_1D_t v, and a differential area A. - + ! PURPOSE: Computes the dot product of a vector_1D field with a surface normal differential area + ! element dS, producing a vector_dot_dS_1D_t object that carries the element-wise product + ! of the face-centered vector values with dS and inherits the vector's divergence operator. + ! KEYWORDS: dot-product, surface-normal, differential-area, vector_1D, operator-overloading, + ! structured-grid, staggered-grid, mimetic, boundary-integral, face-centered + ! CONTEXT: This procedure implements the dot product of a vector_1D_t with the surface normal + ! differential area element in the formal library's mimetic finite-difference framework. + ! In 1D the surface normal dS is a scalar quantity at each face, so the operation is an + ! element-wise multiplication of the face-centered vector values with dS. The resulting + ! vector_dot_dS_1D_t object inherits the vector field's grid metadata and divergence + ! operator, and is used in surface integral expressions such as .SS. (v .dot. dS) within + ! the extended Gauss divergence theorem test. module procedure dot_surface_normal v_dot_dS%tensor_1D_t = tensor_1D_t(vector_1D%values_*dS, vector_1D%x_min_, vector_1D%x_max_, vector_1D%cells_, vector_1D%order_) v_dot_dS%divergence_operator_1D_ = vector_1D%divergence_operator_1D_ @@ -35,11 +42,21 @@ #ifndef __GFORTRAN__ - ! PURPOSE: Definition of procedure to construct a new vector_1D_t object by sampling a function of one spatial dimension. - ! KEYWORDS: 1D vector field constructor - ! CONTEXT: Invoke this constructor with a pointer associated with a function to be sampled at a set - ! of uniformly-spaced cell faces along one spatial dimension bounded by x_min and x_max. - + ! PURPOSE: Constructs a vector_1D_t object by evaluating a user-provided initializer function on + ! the face-centered grid locations and storing the resulting values along with grid + ! metadata and a pre-built divergence operator for the specified order of accuracy and + ! cell count. + ! KEYWORDS: vector_1D, construction, initializer, structured-grid, staggered-grid, divergence-operator, + ! finite-difference, mimetic, face-centered + ! CONTEXT: This procedure constructs a vector_1D_t object in the formal library's mimetic + ! finite-difference framework. The vector field is initialized on a face-centered grid + ! consisting of m+1 face locations (including both domain boundaries), where m is the + ! number of cells. The divergence_operator_1D_t is pre-built and stored within the vector + ! object so that subsequent calls to the .div. operator can apply it without + ! reconstruction. Assertions verify that x_max > x_min and that the cell count is at + ! least 2*order+1 to support the mimetic stencil width. This version is compiled for + ! non-gfortran compilers; gfortran uses an alternate definition below due to differences + ! in procedure pointer handling in module procedure definitions. module procedure construct_1D_vector_from_function call_julienne_assert(x_max .greaterThan. x_min) call_julienne_assert(cells .isAtLeast. 2*order+1) @@ -53,11 +70,20 @@ #else - ! PURPOSE: Definition of procedure to construct a new vector_1D_t object by sampling a function of one spatial dimension. - ! KEYWORDS: 1D vector field constructor - ! CONTEXT: Invoke this constructor with a pointer associated with a function to be sampled at a set - ! of uniformly-spaced cell faces along one spatial dimension bounded by x_min and x_max. - + ! PURPOSE: Constructs a vector_1D_t object by evaluating a user-provided initializer function on + ! the face-centered grid locations and storing the resulting values along with grid + ! metadata and a pre-built divergence operator for the specified order of accuracy and + ! cell count. This is the gfortran-specific variant with an explicit function signature. + ! KEYWORDS: vector_1D, construction, initializer, structured-grid, staggered-grid, divergence-operator, + ! finite-difference, mimetic, face-centered, gfortran + ! CONTEXT: This function is the gfortran-specific variant of construct_1D_vector_from_function in + ! the formal library's mimetic finite-difference framework. It provides the same + ! functionality as the non-gfortran module procedure but uses an explicit function + ! signature rather than a module procedure definition, working around gfortran limitations + ! with procedure pointer arguments in module procedure definitions. The vector field is + ! initialized on a face-centered grid of m+1 values and the divergence_operator_1D_t is + ! pre-built and stored for subsequent .div. operator applications. Assertions verify + ! that x_max > x_min and that the cell count is at least 2*order+1. pure module function construct_1D_vector_from_function(initializer, order, cells, x_min, x_max) result(vector_1D) procedure(vector_1D_initializer_i), pointer :: initializer integer, intent(in) :: order !! order of accuracy @@ -78,21 +104,41 @@ pure module function construct_1D_vector_from_function(initializer, order, cells #endif - ! PURPOSE: Definition of procedure to construct a new vector_1D_t object from a parent tensor and a divergence operator object. - ! KEYWORDS: 1D vector field constructor - ! CONTEXT: Invoke this constructor with a an object to be used to define the constructed parent component - ! divergence-operator matrix component. - + ! PURPOSE: Constructs a vector_1D_t object from pre-existing tensor_1D_t and + ! divergence_operator_1D_t components, bypassing the initializer function evaluation. + ! KEYWORDS: vector_1D, construction, component-assembly, tensor_1D, divergence-operator, + ! structured-grid, staggered-grid + ! CONTEXT: This procedure provides an alternative construction path for vector_1D_t objects in the + ! formal library when the field values and divergence operator have already been computed + ! separately. Rather than evaluating an initializer function on the grid, it directly + ! assigns the provided tensor_1D_t base component and divergence_operator_1D_t. This is + ! used internally when constructing vector fields from intermediate operator results or + ! when reconstituting a vector field from its constituent parts. module procedure construct_from_components vector_1D%tensor_1D_t = tensor_1D vector_1D%divergence_operator_1D_ = divergence_operator_1D end procedure ! END CODE CHUNK - ! PURPOSE: Definition of procedure to compute mimetic approximations to the divergence of a vector field. - ! KEYWORDS: divergence, vector field - ! CONTEXT: Invoke this function via the unary .div. operator with a right-hand-side vector-field operand. - + ! PURPOSE: Computes the discrete divergence of the vector_1D field by applying the mimetic + ! divergence operator to the stored face-centered values, producing a divergence_1D_t + ! object that carries the cell-centered divergence values (with boundary zeros stripped) + ! and verified quadrature weights satisfying the Corbino & Castillo (2020) Eq. 19 + ! identity. + ! KEYWORDS: divergence, mimetic, operator-application, Corbino-Castillo, structured-grid, + ! staggered-grid, vector_1D, divergence_1D, quadrature-weights, summation-by-parts, + ! verification + ! CONTEXT: This procedure implements the .div. operator for vector_1D_t objects in the formal + ! library's mimetic finite-difference framework. It retrieves the stored + ! divergence_operator_1D_t and applies it to the vector's m+1 face-centered values to + ! produce an m+2 result, then strips the zero boundary entries to yield m cell-centered + ! divergence values stored in the resulting divergence_1D_t. After construction, an + ! assertion verifies the Corbino & Castillo (2020) Eq. 19 identity D^T * q = b/dx, + ! where q is the divergence quadrature weights vector, D is the assembled divergence + ! matrix, and b = [-1, 0, ..., 0, 1], ensuring the discrete operator satisfies the + ! required summation-by-parts property. A compiler-conditional associate block with extra + ! parentheses works around a NAG compiler issue with accessing the divergence operator + ! component. module procedure div integer center @@ -119,15 +165,28 @@ pure module function construct_1D_vector_from_function(initializer, order, cells end procedure ! END CODE CHUNK - ! PURPOSE: Definition of procedure to provide the cell face-centered values of vector quantities. - ! KEYWORDS: staggered grid, vector field - ! CONTEXT: Invoke this function via the "values" generic binding to produce discrete vector values. - + ! PURPOSE: Returns the face-centered vector values stored in a vector_1D_t object. + ! KEYWORDS: vector_1D, accessor, face-centered-values, getter + ! CONTEXT: This procedure is a simple accessor that exposes the internally stored m+1 face-centered + ! values from a vector_1D_t object in the formal library. The face-centered values include + ! both domain boundary faces and all interior cell faces. These values are used by other + ! operators and test functions for computation and verification. module procedure vector_1D_values face_centered_values = self%values_ end procedure ! END CODE CHUNK + ! PURPOSE: Computes the face-centered x-coordinates for a uniform 1D grid given the domain bounds + ! and number of cells, returning an array of m+1 face locations including both domain + ! boundaries. + ! KEYWORDS: grid, face-centered, uniform-mesh, 1D, structured-grid, staggered-grid, utility + ! CONTEXT: This private helper function constructs the face-centered grid array used by the + ! vector_1D submodule in the formal library. The face grid places x_min at the first + ! position, x_max at the last position, and m-1 uniformly spaced interior faces between + ! them, yielding m+1 total locations. This layout corresponds to the staggered-grid + ! arrangement where vector quantities live at cell faces while scalar quantities live at + ! cell centers. This function is called by construct_1D_vector_from_function during + ! initialization and by vector_1D_grid to provide grid coordinates. pure function faces(x_min, x_max, cells) result(x) double precision, intent(in) :: x_min, x_max integer, intent(in) :: cells @@ -138,22 +197,43 @@ pure function faces(x_min, x_max, cells) result(x) x = [x_min, x_min + [(cell*dx, cell = 1, cells-1)], x_max] end associate end function + ! END CODE CHUNK - ! PURPOSE: Definition of procedure to provide staggered-grid locations at which vector values are stored: cell faces. - ! KEYWORDS: abcissa, cell faces - ! CONTEXT: Invoke this function via the "grid" generic binding to produce discrete vector locations for - ! initialization-function sampling, printing, or plotting. - + ! PURPOSE: Returns the face-centered grid locations for a vector_1D_t object by delegating to the + ! faces helper function. + ! KEYWORDS: grid, face-centered, accessor, vector_1D, structured-grid, staggered-grid, getter + ! CONTEXT: This procedure provides access to the face-centered grid coordinates associated with a + ! vector_1D_t object in the formal library. It delegates to the faces function, passing + ! the stored domain bounds and cell count. The returned array of m+1 face locations + ! includes both boundary faces and interior faces. Test functions and other operators use + ! this accessor to retrieve grid coordinates for constructing spatially-varying expected + ! values when verifying operator results. module procedure vector_1D_grid cell_faces = faces(self%x_min_, self%x_max_, self%cells_) end procedure ! END CODE CHUNK - ! PURPOSE: Definition of procedure to compute a scalar/vector product weighted for subsequent surface integration. - ! KEYWORDS: integrand, surface integral, double integral - ! CONTEXT: Inovke this function .x. binary infix operator in expressions of the form - ! .SS. (f .x. (v .dot. dA)) with a saclar_1D_t f, a vector_1D_t v, and a differential area A. - + ! PURPOSE: Computes the weighted product of a vector_1D field and a scalar_1D field using the + ! mimetic boundary operator B from Corbino & Castillo (2020) Eq. 7, which combines the + ! divergence and gradient quadrature weights with the assembled operator matrices to form + ! the discrete analogue of the product rule integration term. Internal helper functions + ! premultiply_diagonal and postmultiply_diagonal perform efficient diagonal matrix + ! multiplication. + ! KEYWORDS: weighted-product, boundary-operator, mimetic, Corbino-Castillo, product-rule, + ! structured-grid, staggered-grid, divergence, gradient, quadrature-weights, + ! summation-by-parts, operator-overloading, vector_1D, scalar_1D + ! CONTEXT: This procedure implements the weighted multiplication of a vector_1D_t with a + ! scalar_1D_t in the formal library's mimetic finite-difference framework, following + ! Corbino & Castillo (2020) Eq. 7. The boundary operator B = Q*D + G^T*P combines the + ! divergence matrix D pre-multiplied by the divergence quadrature weights Q with the + ! transpose of the gradient matrix G post-multiplied by the gradient quadrature weights P. + ! The result is computed as dx * B * v * f, where v is the face-centered vector field and + ! f is the extended cell-centered scalar field. Assertions verify that the vector and + ! scalar fields are compatible in size, cell count, order, and domain bounds, and that the + ! assembled operator matrices have the expected dimensions. The internal helper functions + ! premultiply_diagonal and postmultiply_diagonal efficiently multiply a matrix by a + ! diagonal matrix represented as a 1D array, using do concurrent with compiler-conditional + ! syntax variations. module procedure weighted_premultiply !! vector values at faces scalar values at cell centers + boundaries @@ -234,10 +314,18 @@ pure function postmultiply_diagonal(A,d) result(AD) end function end procedure + ! END CODE CHUNK - ! PURPOSE: Definition of procedure to provide the differential area for use in surface integrals. - ! KEYWORDS: surface integral, area integral, double integral, numerical quadrature, mimetic discretization - ! CONTEXT: Use this in expressions of the form .SS. (f .x. (v .dot. dA)) with a scalar_1D_t f and vector_1D_t v + ! PURPOSE: Returns the differential area element dA for the 1D case, which is always 1.0 since + ! the cross-sectional area of a 1D domain is unity. + ! KEYWORDS: differential-area, surface-element, 1D, vector_1D, accessor, getter, boundary-integral + ! CONTEXT: This procedure provides the differential area element for a vector_1D_t object in the + ! formal library's mimetic finite-difference framework. In one spatial dimension, the + ! surface bounding each cell is a point with unit area, so dA is trivially 1.0. This + ! accessor exists to maintain a consistent interface with higher-dimensional + ! generalizations where dA would be a nontrivial geometric quantity. It is used in + ! surface integral expressions such as .SS. (v .dot. dA) within the extended Gauss + ! divergence theorem test. module procedure dA dA = 1D0 end procedure diff --git a/src/formal/vector_dot_gradient_1D_s.F90 b/src/formal/vector_dot_gradient_1D_s.F90 index 93a4149..0556383 100644 --- a/src/formal/vector_dot_gradient_1D_s.F90 +++ b/src/formal/vector_dot_gradient_1D_s.F90 @@ -9,11 +9,22 @@ contains - ! PURPOSE: Definition of procedure to perform mimetic volume integration of a vector/scalar-gradient dot product. - ! KEYWORDS: triple integral, volume integral - ! CONTEXT: Invoke this function in expressions of the form .SSS. (v .dot. .grad. f) * dV - ! with a vector_1D_t v, a scalar f, and a differential volume dV. - + ! PURPOSE: Computes the discrete volume integral of a vector_dot_gradient_1D_t field by performing + ! a weighted sum of the node-centered values using the mimetic quadrature weights inherited + ! from the gradient field. + ! KEYWORDS: volume-integral, quadrature, mimetic, vector-dot-gradient, structured-grid, + ! staggered-grid, weighted-sum, summation-by-parts, node-centered + ! CONTEXT: This procedure implements the .SSS. volume integration operator for + ! vector_dot_gradient_1D_t objects in the formal library's mimetic finite-difference + ! framework. The vector_dot_gradient_1D_t type represents the element-wise dot product of + ! a vector field with a gradient field, and carries both the m+1 node-centered product + ! values and the m+1 mimetic quadrature weights inherited from the gradient field. Unlike + ! the scalar_x_divergence_1D volume integral which requires zero-padding at the + ! boundaries, this integral is a direct weighted sum because the gradient field's + ! node-centered values and weights are defined at all m+1 face locations without zero + ! boundary rows. An assertion verifies that the weights and values arrays have the same + ! size. This integration is used in compound expressions such as + ! .SSS. (v .dot. .grad. f) * dV within the extended Gauss divergence theorem test. module procedure volume_integrate_vector_dot_grad_scalar_1D call_julienne_assert(size(integrand%weights_ ) .equalsExpected. size(integrand%values_)) integral = sum(integrand%weights_ * integrand%values_) diff --git a/src/formal/weighted_product_1D_s.F90 b/src/formal/weighted_product_1D_s.F90 index 23fcd4c..0e46193 100644 --- a/src/formal/weighted_product_1D_s.F90 +++ b/src/formal/weighted_product_1D_s.F90 @@ -6,11 +6,18 @@ contains - ! PURPOSE: Definition of procedure to perform mimetic surface integration of a scalar/vector product. - ! KEYWORDS: double integral, surface integral, flux - ! CONTEXT: Invoke this function in expressions of the form -.SS. (f .x. (v .dot. dA)) - ! with a vector_1D_t v, a scalar_1D_t f, and a differential area dA. - + ! PURPOSE: Computes the discrete surface integral of a weighted_product_1D_t field by summing the + ! stored boundary-weighted product values that were computed as dx * B * v * f by the + ! weighted_premultiply procedure. + ! KEYWORDS: surface-integral, quadrature, mimetic, Corbino-Castillo, weighted-product, + ! boundary-operator, summation, summation-by-parts + ! CONTEXT: This procedure implements the .SS. surface integration operator for + ! weighted_product_1D_t objects in the formal library's mimetic finite-difference + ! framework. The stored values already incorporate the boundary operator B from Corbino & + ! Castillo (2020) Eq. 7 and the cell width dx, so the surface integral reduces to a + ! simple summation of all stored values. This represents the discrete surface integral + ! term in the extended Gauss divergence theorem, appearing in expressions such as + ! .SS. (f .x. (v .dot. dA)). module procedure surface_integrate_vector_x_scalar_1D integral = sum(integrand%values_) end procedure