Replace shape_value etc for interpolations with `reference_shape_va…

…lue` (#997)

This patch is a follow up to #721 and replaces `shape_value`,
`shape_gradient` etc for interpolations, which return evaluations in the
reference domain, with new functions `reference_shape_value`,
`reference_shape_gradient`, etc. The new functions are public but not
exported.

Separating these functions make it possible to support
`reference_shape_value` etc for `CellValues` too in the future.

CHANGELOG.md

@@ -308,12 +308,13 @@ more discussion).
   `FacetQuadratureRule{RefTriangle}(order)` (similar to how `QuadratureRule` is constructed).
   ([#716][github-716])
 
-- New methods `shape_value(::Interpolation, ξ::Vec, i::Int)` and
-  `shape_gradient(::Interpolation, ξ::Vec, i::Int)` for evaluating the value/gradient of the
-  `i`th shape function of an interpolation in local reference coordinate `ξ`. Note that
-  these methods return the value/gradient wrt. the reference coordinate `ξ`, whereas the
-  corresponding methods for `CellValues` etc return the value/gradient wrt the spatial
-  coordinate `x`. ([#721][github-721])
+- New functions `Ferrite.reference_shape_value(::Interpolation, ξ::Vec, i::Int)` and
+  `Ferrite.reference_shape_gradient(::Interpolation, ξ::Vec, i::Int)` for evaluating the
+  value/gradient of the `i`th shape function of an interpolation in local reference
+  coordinate `ξ`. These methods are public but not exported. (Note that these methods return
+  the value/gradient wrt. the reference coordinate `ξ`, whereas the corresponding methods
+  for `CellValues` etc return the value/gradient wrt the spatial coordinate `x`.)
+  ([#721][github-721])
 
 - `FacetIterator` and `FacetCache` have been added. These work similarly to `CellIterator` and
   `CellCache` but are used to iterate over (boundary) face sets instead. These simplify

docs/src/devdocs/interpolations.md

@@ -15,7 +15,7 @@ Ferrite.shape_gradient(::Interpolation, ::Vec, ::Int)
 Ferrite.shape_gradient_and_value
 Ferrite.boundarydof_indices
 Ferrite.dirichlet_boundarydof_indices
-Ferrite.shape_values!
+Ferrite.reference_shape_values!
 Ferrite.shape_gradients!
 Ferrite.shape_gradients_and_values!
 ```

docs/src/topics/SimpleCellValues_literate.jl

@@ -42,10 +42,10 @@ function SimpleCellValues(qr::QuadratureRule, ip_fun::Interpolation, ip_geo::Int
     ## Precalculate function and geometric shape values and gradients
     for (qp, ξ) in pairs(Ferrite.getpoints(qr))
         for i in 1:n_func_basefuncs
-            dNdξ[i, qp], N[i, qp] = Ferrite.shape_gradient_and_value(ip_fun, ξ, i)
+            dNdξ[i, qp], N[i, qp] = Ferrite.reference_shape_gradient_and_value(ip_fun, ξ, i)
         end
         for i in 1:n_geom_basefuncs
-            dMdξ[i, qp], M[i, qp] = Ferrite.shape_gradient_and_value(ip_geo, ξ, i)
+            dMdξ[i, qp], M[i, qp] = Ferrite.reference_shape_gradient_and_value(ip_geo, ξ, i)
         end
     end
 

src/FEValues/FacetValues.jl

@@ -206,7 +206,7 @@ function BCValues(::Type{T}, func_interpol::Interpolation{refshape}, geom_interp
 
     for n_boundary_entity in 1:n_boundary_entities
         for (qp, ξ) in pairs(qrs[n_boundary_entity].points)
-            shape_values!(@view(M[:, qp, n_boundary_entity]), geom_interpol, ξ)
+            reference_shape_values!(@view(M[:, qp, n_boundary_entity]), geom_interpol, ξ)
         end
         nqp[n_boundary_entity] = length(qrs[n_boundary_entity].points)
     end

src/FEValues/FunctionValues.jl

@@ -89,13 +89,13 @@ function FunctionValues{DiffOrder}(::Type{T}, ip::Interpolation, qr::QuadratureR
 end
 
 function precompute_values!(fv::FunctionValues{0}, qr_points::Vector{<:Vec})
-    shape_values!(fv.Nξ, fv.ip, qr_points)
+    reference_shape_values!(fv.Nξ, fv.ip, qr_points)
 end
 function precompute_values!(fv::FunctionValues{1}, qr_points::Vector{<:Vec})
-    shape_gradients_and_values!(fv.dNdξ, fv.Nξ, fv.ip, qr_points)
+    reference_shape_gradients_and_values!(fv.dNdξ, fv.Nξ, fv.ip, qr_points)
 end
 function precompute_values!(fv::FunctionValues{2}, qr_points::Vector{<:Vec})
-    shape_hessians_gradients_and_values!(fv.d2Ndξ2, fv.dNdξ, fv.Nξ, fv.ip, qr_points)
+    reference_shape_hessians_gradients_and_values!(fv.d2Ndξ2, fv.dNdξ, fv.Nξ, fv.ip, qr_points)
 end
 
 function Base.copy(v::FunctionValues)

src/FEValues/GeometryMapping.jl

@@ -85,13 +85,13 @@ function GeometryMapping{2}(::Type{T}, ip::ScalarInterpolation, qr::QuadratureRu
 end
 
 function precompute_values!(gm::GeometryMapping{0}, qr_points::Vector{<:Vec})
-    shape_values!(gm.M, gm.ip, qr_points)
+    reference_shape_values!(gm.M, gm.ip, qr_points)
 end
 function precompute_values!(gm::GeometryMapping{1}, qr_points::Vector{<:Vec})
-    shape_gradients_and_values!(gm.dMdξ, gm.M, gm.ip, qr_points)
+    reference_shape_gradients_and_values!(gm.dMdξ, gm.M, gm.ip, qr_points)
 end
 function precompute_values!(gm::GeometryMapping{2}, qr_points::Vector{<:Vec})
-    shape_hessians_gradients_and_values!(gm.d2Mdξ2, gm.dMdξ, gm.M, gm.ip, qr_points)
+    reference_shape_hessians_gradients_and_values!(gm.d2Mdξ2, gm.dMdξ, gm.M, gm.ip, qr_points)
 end
 
 function Base.copy(v::GeometryMapping)

src/FEValues/common_values.jl

@@ -347,20 +347,20 @@ end
 _copy_or_nothing(x) = copy(x)
 _copy_or_nothing(::Nothing) = nothing
 
-function shape_values!(values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
+function reference_shape_values!(values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
     for (qp, ξ) in pairs(qr_points)
-        shape_values!(@view(values[:, qp]), ip, ξ)
+        reference_shape_values!(@view(values[:, qp]), ip, ξ)
     end
 end
 
-function shape_gradients_and_values!(gradients::AbstractMatrix, values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
+function reference_shape_gradients_and_values!(gradients::AbstractMatrix, values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
     for (qp, ξ) in pairs(qr_points)
-        shape_gradients_and_values!(@view(gradients[:, qp]), @view(values[:, qp]), ip, ξ)
+        reference_shape_gradients_and_values!(@view(gradients[:, qp]), @view(values[:, qp]), ip, ξ)
     end
 end
 
-function shape_hessians_gradients_and_values!(hessians::AbstractMatrix, gradients::AbstractMatrix, values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
+function reference_shape_hessians_gradients_and_values!(hessians::AbstractMatrix, gradients::AbstractMatrix, values::AbstractMatrix, ip, qr_points::Vector{<:Vec})
     for (qp, ξ) in pairs(qr_points)
-        shape_hessians_gradients_and_values!(@view(hessians[:, qp]), @view(gradients[:, qp]), @view(values[:, qp]), ip, ξ)
+        reference_shape_hessians_gradients_and_values!(@view(hessians[:, qp]), @view(gradients[:, qp]), @view(values[:, qp]), ip, ξ)
     end
 end

src/PointEvalHandler.jl

@@ -127,7 +127,7 @@ function find_local_coordinate(interpolation, cell_coordinates::Vector{<:Vec{dim
         J = zero(Tensor{2, dim, T})
         # TODO batched eval after 764 is merged.
         for j in 1:n_basefuncs
-            dNdξ, N = shape_gradient_and_value(interpolation, local_guess, j)
+            dNdξ, N = reference_shape_gradient_and_value(interpolation, local_guess, j)
             global_guess += N * cell_coordinates[j]
             J += cell_coordinates[j] ⊗ dNdξ
         end

src/deprecations.jl

@@ -339,9 +339,9 @@ function Base.show(io::IO, ::CrouzeixRaviart{shape, order}) where {shape, order}
     print(io, "CrouzeixRaviart{$(shape), $(order)}()")
 end
 
-@deprecate value(ip::Interpolation, ξ::Vec) [shape_value(ip, ξ, i) for i in 1:getnbasefunctions(ip)] false
-@deprecate derivative(ip::Interpolation, ξ::Vec) [shape_gradient(ip, ξ, i) for i in 1:getnbasefunctions(ip)] false
-@deprecate value(ip::Interpolation, i::Int, ξ::Vec) shape_value(ip, ξ, i) false
+@deprecate value(ip::Interpolation, ξ::Vec) [reference_shape_value(ip, ξ, i) for i in 1:getnbasefunctions(ip)] false
+@deprecate derivative(ip::Interpolation, ξ::Vec) [reference_shape_gradient(ip, ξ, i) for i in 1:getnbasefunctions(ip)] false
+@deprecate value(ip::Interpolation, i::Int, ξ::Vec) reference_shape_value(ip, ξ, i) false
 
 export MixedDofHandler
 function MixedDofHandler(::AbstractGrid)