Difference, jump and average operators#

D₋ₓ(arg)

The backward finite difference along the x direction, \(\frac{u_{i} - u_{i-1}}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for backward_finite_difference(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₋ₓ(op::LazyOp{D})

The symbolic backward finite difference of op along the x direction.

Alias for D₋(op, Val(1)).

D₋ₓ!(vₕ, uₕ)

The backward finite difference of uₕ along the x direction, \(\frac{u_{i} - u_{i-1}}{h_i}\), written into vₕ.

The in-place form of D₋ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₋ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_finite_difference!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D₋ᵧ(arg)

The backward finite difference along the y direction, \(\frac{u_{i} - u_{i-1}}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for backward_finite_difference(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₋ᵧ(op::LazyOp{D})

The symbolic backward finite difference of op along the y direction.

Alias for D₋(op, Val(2)).

D₋ᵧ!(vₕ, uₕ)

The backward finite difference of uₕ along the y direction, \(\frac{u_{i} - u_{i-1}}{h_i}\), written into vₕ.

The in-place form of D₋ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₋ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_finite_difference!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D₋₂(arg)

The backward finite difference along the z direction, \(\frac{u_{i} - u_{i-1}}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for backward_finite_difference(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₋₂(op::LazyOp{D})

The symbolic backward finite difference of op along the z direction.

Alias for D₋(op, Val(3)).

D₋₂!(vₕ, uₕ)

The backward finite difference of uₕ along the z direction, \(\frac{u_{i} - u_{i-1}}{h_i}\), written into vₕ.

The in-place form of D₋₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₋₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_finite_difference!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

∇ₕ(arg)

The backward finite difference of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, ∇ₕ(uₕ) is (backward_finite_difference(uₕ, Val(1)), backward_finite_difference(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for backward_finite_difference.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

∇ₕ(op::LazyOp{D})

The symbolic backward finite difference of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

∇ₕ(ops::Tuple)

Applies ∇ₕ component-wise to a tuple of scalar symbolic functions, such as the velocity components (u1, u2) of a composite space. Returns a tuple of results, one per component.

∇ₕ(u::Union{TrialFunction, TestFunction})

The backward gradient tensor of a composite trial or test function u: N rows (one per component of u) of D-tuples (one per spatial direction), ∇ₕ(u)[c][d] the backward difference of component c along direction d.

The rows come in a Bramble._GradientRows, which is not a Tuple. ∇ₕ(u)[c][d], length, iteration, map and broadcasting give what they give on ∇ₕ(components(u)), and Tuple(∇ₕ(u)) is that tuple; anything else tuple-like needs Tuple(∇ₕ(u)). map needs every argument to be such a container; with a plain tuple among them, pass Tuple(∇ₕ(u)). The container also tells inner₊ that row c is built on component c alone, so a captured coefficient over inner₊(∇ₕ(u), ∇ₕ(v)) gives form one concrete type in 3D, which the plain tuple ∇ₕ(components(u)) does not; both assemble the same matrix. In 1D each row is the 1-tuple (D₋ₓ(u(c)),), as in ∇ₕ(components(u)), so ∇ₕ(u)[c][1] is that difference and the two spellings mix. On a scalar space (one component) this is the same D-tuple ∇ₕ already returns for any operator.

D₊ₓ(arg)

The forward finite difference along the x direction, \(\frac{u_{i+1} - u_i}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for forward_finite_difference(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₊ₓ(op::LazyOp{D})

The symbolic forward finite difference of op along the x direction.

Alias for D₊(op, Val(1)).

D₊ₓ!(vₕ, uₕ)

The forward finite difference of uₕ along the x direction, \(\frac{u_{i+1} - u_i}{h_i}\), written into vₕ.

The in-place form of D₊ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₊ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_finite_difference!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D₊ᵧ(arg)

The forward finite difference along the y direction, \(\frac{u_{i+1} - u_i}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for forward_finite_difference(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₊ᵧ(op::LazyOp{D})

The symbolic forward finite difference of op along the y direction.

Alias for D₊(op, Val(2)).

D₊ᵧ!(vₕ, uₕ)

The forward finite difference of uₕ along the y direction, \(\frac{u_{i+1} - u_i}{h_i}\), written into vₕ.

The in-place form of D₊ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₊ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_finite_difference!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D₊₂(arg)

The forward finite difference along the z direction, \(\frac{u_{i+1} - u_i}{h_i}\). The unscaled difference is not divided by the grid spacing; the finite difference is.

Alias for forward_finite_difference(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₊₂(op::LazyOp{D})

The symbolic forward finite difference of op along the z direction.

Alias for D₊(op, Val(3)).

D₊₂!(vₕ, uₕ)

The forward finite difference of uₕ along the z direction, \(\frac{u_{i+1} - u_i}{h_i}\), written into vₕ.

The in-place form of D₊₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D₊₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_finite_difference!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

∇₊ₕ(arg)

The forward finite difference of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, ∇₊ₕ(uₕ) is (forward_finite_difference(uₕ, Val(1)), forward_finite_difference(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for forward_finite_difference.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

∇₊ₕ(op::LazyOp{D})

The symbolic forward finite difference of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

∇₊ₕ(ops::Tuple)

Applies ∇₊ₕ component-wise to a tuple of scalar symbolic functions, such as the velocity components (u1, u2) of a composite space. Returns a tuple of results, one per component.

∇₊ₕ(u::Union{TrialFunction, TestFunction})

The forward twin of ∇ₕ(u::Union{TrialFunction,TestFunction}).

D₋(arg, d)

The backward finite difference along the d direction, \(\frac{u_{i} - u_{i-1}}{h_i}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one D₋ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for backward_finite_difference(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₋(op::LazyOp{D}, ::Val{Dim})

The symbolic backward finite difference of op along direction Dim, as a BackwardDifference node.

The entry point D₋ₓ and its siblings forward through, and the same function the space layer applies to a grid function: D₋(uₕ, Val(1)) computes values, D₋(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

D₊(arg, d)

The forward finite difference along the d direction, \(\frac{u_{i+1} - u_i}{h_i}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one D₊ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for forward_finite_difference(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D₊(op::LazyOp{D}, ::Val{Dim})

The symbolic forward finite difference of op along direction Dim, as a ForwardDifference node.

The entry point D₊ₓ and its siblings forward through, and the same function the space layer applies to a grid function: D₊(uₕ, Val(1)) computes values, D₊(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

D̃ₓ(arg)

The forward difference of uₕ along the x direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\).

Alias for forward_star_difference(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along x is truncated to zero.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̃ₓ(op::LazyOp{D})

The symbolic averaged-spacing forward difference of op along the x direction.

Alias for D̃(op, Val(1)).

D̃ₓ!(vₕ, uₕ)

The forward difference of uₕ along the x direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\), written into vₕ.

The in-place form of D̃ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̃ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_star_difference!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̃ᵧ(arg)

The forward difference of uₕ along the y direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\).

Alias for forward_star_difference(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along y is truncated to zero.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̃ᵧ(op::LazyOp{D})

The symbolic averaged-spacing forward difference of op along the y direction.

Alias for D̃(op, Val(2)).

D̃ᵧ!(vₕ, uₕ)

The forward difference of uₕ along the y direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\), written into vₕ.

The in-place form of D̃ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̃ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_star_difference!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̃₂(arg)

The forward difference of uₕ along the z direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\).

Alias for forward_star_difference(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along z is truncated to zero.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̃₂(op::LazyOp{D})

The symbolic averaged-spacing forward difference of op along the z direction.

Alias for D̃(op, Val(3)).

D̃₂!(vₕ, uₕ)

The forward difference of uₕ along the z direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\), written into vₕ.

The in-place form of D̃₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̃₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_star_difference!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̃ₕ(arg)

The averaged-spacing forward difference of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, D̃ₕ(uₕ) is (forward_star_difference(uₕ, Val(1)), forward_star_difference(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for forward_star_difference.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

D̃ₕ(op::LazyOp{D})

The symbolic averaged-spacing forward difference of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

D̃(arg, d)

The forward difference of uₕ along the d direction over the averaged spacing, \(\frac{u_{i+1} - u_i}{(h_i + h_{i+1})/2}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one D̃ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for forward_star_difference(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̃(op::LazyOp{D}, ::Val{Dim})

The symbolic averaged-spacing forward difference of op along direction Dim, as a StarDifference node.

The entry point D̃ₓ and its siblings forward through, and the same function the space layer applies to a grid function: D̃(uₕ, Val(1)) computes values, D̃(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

Dcₓ(arg)

The centered difference of uₕ along the x direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\).

Alias for centered_difference(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along x are truncated to zero, so the mesh needs at least three points along x and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Dcₓ(op::LazyOp{D})

The symbolic centered difference of op along the x direction.

Alias for Dc(op, Val(1)).

Dcₓ!(vₕ, uₕ)

The centered difference of uₕ along the x direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\), written into vₕ.

The in-place form of Dcₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Dcₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_difference!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Dcᵧ(arg)

The centered difference of uₕ along the y direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\).

Alias for centered_difference(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along y are truncated to zero, so the mesh needs at least three points along y and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Dcᵧ(op::LazyOp{D})

The symbolic centered difference of op along the y direction.

Alias for Dc(op, Val(2)).

Dcᵧ!(vₕ, uₕ)

The centered difference of uₕ along the y direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\), written into vₕ.

The in-place form of Dcᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Dcᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_difference!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Dc₂(arg)

The centered difference of uₕ along the z direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\).

Alias for centered_difference(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along z are truncated to zero, so the mesh needs at least three points along z and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Dc₂(op::LazyOp{D})

The symbolic centered difference of op along the z direction.

Alias for Dc(op, Val(3)).

Dc₂!(vₕ, uₕ)

The centered difference of uₕ along the z direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\), written into vₕ.

The in-place form of Dc₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Dc₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_difference!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Dcₕ(arg)

The centered difference of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, Dcₕ(uₕ) is (centered_difference(uₕ, Val(1)), centered_difference(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for centered_difference.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

Dcₕ(op::LazyOp{D})

The symbolic centered difference of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

Dc(arg, d)

The centered difference of uₕ along the d direction, \(\frac{u_{i+1} - u_{i-1}}{h_i + h_{i+1}}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one Dcₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for centered_difference(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Dc(op::LazyOp{D}, ::Val{Dim})

The symbolic centered difference of op along direction Dim, as a CenteredDifference node.

The entry point Dcₓ and its siblings forward through, and the same function the space layer applies to a grid function: Dc(uₕ, Val(1)) computes values, Dc(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

D̽ₓ(arg)

The cross-weighted centered difference of uₕ along the x direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\).

Alias for cross_weighted_difference(arg, Val(1)). Second order on a non-uniform grid, where Dcₓ is first. arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. Unlike Dcₓ, the first and last points along x are not truncated: with no neighbour on the far side, each collapses to the one-sided difference the near side still gives, D₊ₓ at the first point and D₋ₓ at the last. The mesh still needs at least three points along x, and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̽ₓ(op::LazyOp{D})

The symbolic cross-weighted centered difference of op along the x direction.

Alias for D̽ₕ(op, Val(1)).

D̽ₓ!(vₕ, uₕ)

The cross-weighted centered difference of uₕ along the x direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\), written into vₕ.

The in-place form of D̽ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̽ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for cross_weighted_difference!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̽ᵧ(arg)

The cross-weighted centered difference of uₕ along the y direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\).

Alias for cross_weighted_difference(arg, Val(2)). Second order on a non-uniform grid, where Dcᵧ is first. arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. Unlike Dcᵧ, the first and last points along y are not truncated: with no neighbour on the far side, each collapses to the one-sided difference the near side still gives, D₊ᵧ at the first point and D₋ᵧ at the last. The mesh still needs at least three points along y, and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̽ᵧ(op::LazyOp{D})

The symbolic cross-weighted centered difference of op along the y direction.

Alias for D̽ₕ(op, Val(2)).

D̽ᵧ!(vₕ, uₕ)

The cross-weighted centered difference of uₕ along the y direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\), written into vₕ.

The in-place form of D̽ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̽ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for cross_weighted_difference!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̽₂(arg)

The cross-weighted centered difference of uₕ along the z direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\).

Alias for cross_weighted_difference(arg, Val(3)). Second order on a non-uniform grid, where Dc₂ is first. arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. Unlike Dc₂, the first and last points along z are not truncated: with no neighbour on the far side, each collapses to the one-sided difference the near side still gives, D₊₂ at the first point and D₋₂ at the last. The mesh still needs at least three points along z, and an ArgumentError is thrown when it has fewer.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̽₂(op::LazyOp{D})

The symbolic cross-weighted centered difference of op along the z direction.

Alias for D̽ₕ(op, Val(3)).

D̽₂!(vₕ, uₕ)

The cross-weighted centered difference of uₕ along the z direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\), written into vₕ.

The in-place form of D̽₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(D̽₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for cross_weighted_difference!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

D̽ₕ(arg, d)

The cross-weighted centered difference of uₕ along the d direction, the backward differences at \(x_{i+1}\) and \(x_i\) weighted by \(h_i\) and \(h_{i+1}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one D̽ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for cross_weighted_difference(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

D̽ₕ(arg)

The cross-weighted centered difference of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, D̽ₕ(uₕ) is (cross_weighted_difference(uₕ, Val(1)), cross_weighted_difference(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for cross_weighted_difference. The second-order, non-uniform-grid counterpart of ∇ₕ and ∇₊ₕ, built from D̽ₓ rather than from the one-sided differences.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

D̽ₕ(op::LazyOp{D}, ::Val{Dim})

The symbolic cross-weighted centered difference of op along direction Dim, as a CrossWeightedDifference node.

The entry point D̽ₓ and its siblings forward through, and the same function the space layer applies to a grid function: D̽ₕ(uₕ, Val(1)) computes values, D̽ₕ(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

D̽ₕ(op::LazyOp{D})

The symbolic cross-weighted centered difference of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

divₕ(u) -> Bramble._DivergenceTerms

The symbolic divergence of a composite trial or test function u with one component per spatial dimension: term i is \(D_{-,i}(u_i)\), with no averaging. It is the symbolic twin of the runtime divₕ over grid functions (operators/vector_calculus.jl, gpena/Bramble.jl#158), so inner₊(divₕ(u), divₕ(v)) assembles the runtime inner₊(divₕ(w), divₕ(w), Val(S)), and ∇ₕ ⋅ u inside a form is this operator.

The only supported use is inner₊(divₕ(u), divₕ(v)), which expands to \(\sum_{i,j} (D_{-,i}(u_i), D_{-,j}(v_j))_{\{1,\dots,D\}}\) through inner₊(left, right, Val(S)).

See also: divₘₕ, εₕ.

divₕ(uₕ) -> VectorElement
divₕ!(vₕ, uₕ) -> vₕ

Returns the discrete divergence of the vector field uₕ, built from the backward differences:

uₕ is an NTuple{D, VectorElement} – what ∇ₕ returns – or a grid function of a CompositeGridSpace with one leaf per spatial dimension. Its components must be grid functions of one mesh, or an ArgumentError is thrown.

The backward difference is truncated to zero on the first slice of each direction, exactly as D₋ₓ is, so the divergence there is the sum of the directions that still have a stencil.

divₕ! writes into a destination instead, and allocates nothing.

∇ₕ ⋅ uₕ is the same call written with ⋅ (LinearAlgebra.dot, exported from Bramble) in place of the function name: ∇ₕ ⋅ uₕ == divₕ(uₕ). It needs ⋅ in scope (using LinearAlgebra: ⋅ or Bramble's own re-export). ∇cₕ, ∇̽ₕ, ∇̃ₕ and ∇₊ₕ contract to divcₕ, div̽ₕ, diṽₕ and div₊ₕ the same way.

See also: div₊ₕ, curlₕ, Δₕ

divₕ!(vₕ::VectorElement, uₕ) -> VectorElement

The in-place form of divₕ: the discrete divergence of uₕ, written into vₕ.

Allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(divₕ!(vₕ, uₕ)).

vₕ is a grid function of the scalar space the components live on, and must not be one of them: every stencil reads a neighbour, and aliasing would read values already overwritten.

divₘₕ(u) -> Bramble._DivergenceTerms

The symbolic staggered divergence of a composite trial or test function u with one component per spatial dimension, placed at the cell centre every axis shares: term i is \(D_{-,i}(u_i)\) averaged onto that centre by every axis other than i.

It is form-only: it has no runtime twin, so no operator over grid functions computes it. Use divₕ where the form must match the runtime divergence.

The only supported use is inner₊(divₘₕ(u), divₘₕ(v)), which expands to \(\sum_{i,j} (\mathrm{div}_h^{(i)}(u), \mathrm{div}_h^{(j)}(v))_{\{1,\dots,D\}}\) through inner₊(left, right, Val(S)).

See also: divₕ, εₕ.

div₊ₕ(uₕ) -> VectorElement
div₊ₕ!(vₕ::VectorElement, uₕ) -> VectorElement

The forward-difference discrete divergence, \(\sum_d \textrm{D}_{+,x_d}(\textrm{u}_{h,d})\).

The forward twin of divₕ, standing to it as ∇₊ₕ stands to ∇ₕ, and truncated to zero on the last slice of each direction rather than the first.

∇₊ₕ ⋅ uₕ == div₊ₕ(uₕ).

div₊ₕ(uₕ) -> VectorElement
div₊ₕ!(vₕ::VectorElement, uₕ) -> VectorElement

The forward-difference discrete divergence, \(\sum_d \textrm{D}_{+,x_d}(\textrm{u}_{h,d})\).

The forward twin of divₕ, standing to it as ∇₊ₕ stands to ∇ₕ, and truncated to zero on the last slice of each direction rather than the first.

∇₊ₕ ⋅ uₕ == div₊ₕ(uₕ).

divcₕ(u::LazyOp{D}) -> LazyOp

The symbolic centered divergence of a trial or test function u with one component per spatial dimension,

Every term is collocated at the grid point, so the result is a plain operator sum usable wherever an operator is, e.g. innerₕ(p, divcₕ(v)). Shares its name with the runtime divcₕ over grid functions (operators/vector_calculus.jl).

See also: εcₕ, divₕ.

divcₕ(uₕ) -> VectorElement
divcₕ!(vₕ::VectorElement, uₕ) -> vₕ

Returns the centered discrete divergence of the vector field uₕ:

uₕ is spelled as for divₕ: an NTuple{D, VectorElement}, or a grid function of a CompositeGridSpace with one leaf per spatial dimension (in 1D, a scalar grid function), its components on one mesh. Each centered difference is zero on the first and last slice of its direction.

For fields vanishing on the boundary it is minus the adjoint of ∇cₕ, \((\textrm{div}_{c,h} \textrm{F}, \textrm{u})_h = -\sum_d (\textrm{F}_d, \textrm{Dc}_{x_d} \textrm{u})_h\), on any mesh.

divcₕ! writes into vₕ, which must not be one of the components, and allocates nothing.

∇cₕ ⋅ uₕ == divcₕ(uₕ).

See also: divₕ, curlcₕ, εcₕ

divcₕ(u::LazyOp{D}) -> LazyOp

The symbolic centered divergence of a trial or test function u with one component per spatial dimension,

Every term is collocated at the grid point, so the result is a plain operator sum usable wherever an operator is, e.g. innerₕ(p, divcₕ(v)). Shares its name with the runtime divcₕ over grid functions (operators/vector_calculus.jl).

See also: εcₕ, divₕ.

div̽ₕ(u::LazyOp{D}) -> LazyOp

The symbolic cross-weighted divergence of a trial or test function u with one component per spatial dimension,

Every term is co-located at the grid point, so the result is a plain operator sum usable wherever an operator is, e.g. innerₕ(p, div̽ₕ(v)). Shares its name with the runtime div̽ₕ over grid functions (operators/vector_calculus.jl).

See also: ε̽ₕ, divcₕ.

div̽ₕ(uₕ) -> VectorElement
div̽ₕ!(vₕ::VectorElement, uₕ) -> vₕ

Returns the cross-weighted discrete divergence of the vector field uₕ:

uₕ is spelled as for divₕ: an NTuple{D, VectorElement}, or a grid function of a CompositeGridSpace with one leaf per spatial dimension (in 1D, a scalar grid function), its components on one mesh. Each cross-weighted difference is second order on a non-uniform grid and is not truncated: on the first and last slice of its direction it is the one-sided difference the near side still defines, as for D̽ₓ.

div̽ₕ! writes into vₕ, which must not be one of the components, and allocates nothing.

∇̽ₕ ⋅ uₕ == div̽ₕ(uₕ).

See also: divcₕ, curl̽ₕ, ε̽ₕ, ∇̽ₕ

div̽ₕ(u::LazyOp{D}) -> LazyOp

The symbolic cross-weighted divergence of a trial or test function u with one component per spatial dimension,

Every term is co-located at the grid point, so the result is a plain operator sum usable wherever an operator is, e.g. innerₕ(p, div̽ₕ(v)). Shares its name with the runtime div̽ₕ over grid functions (operators/vector_calculus.jl).

See also: ε̽ₕ, divcₕ.

curlₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curlₕ!(vₕ, uₕ) -> vₕ

Returns the discrete curl of the vector field uₕ, built from the backward differences.

In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a backward difference. There is no 1D curl, and asking for one is an error rather than a zero.

curlₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination. curl₊ₕ is the forward twin.

∇ₕ × uₕ is the same call written with × (LinearAlgebra.cross) in place of the function name: ∇ₕ × uₕ == curlₕ(uₕ), needing × in scope. ∇cₕ, ∇̽ₕ and ∇̃ₕ contract to curlcₕ, curl̽ₕ and curl̃ₕ the same way.

See also: divₕ, ∇ₕ

curlₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curlₕ!(vₕ, uₕ) -> vₕ

Returns the discrete curl of the vector field uₕ, built from the backward differences.

In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a backward difference. There is no 1D curl, and asking for one is an error rather than a zero.

curlₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination. curl₊ₕ is the forward twin.

∇ₕ × uₕ is the same call written with × (LinearAlgebra.cross) in place of the function name: ∇ₕ × uₕ == curlₕ(uₕ), needing × in scope. ∇cₕ, ∇̽ₕ and ∇̃ₕ contract to curlcₕ, curl̽ₕ and curl̃ₕ the same way.

See also: divₕ, ∇ₕ

curl₊ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl₊ₕ!(vₕ, uₕ) -> vₕ

The forward-difference discrete curl, the twin of curlₕ.

∇₊ₕ × uₕ == curl₊ₕ(uₕ).

curl₊ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl₊ₕ!(vₕ, uₕ) -> vₕ

The forward-difference discrete curl, the twin of curlₕ.

∇₊ₕ × uₕ == curl₊ₕ(uₕ).

curlcₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curlcₕ!(vₕ, uₕ) -> vₕ

Returns the centered discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a centered difference. There is no 1D curl, and asking for one is an ArgumentError.

curlcₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇cₕ × uₕ == curlcₕ(uₕ).

See also: curlₕ, divcₕ, ∇cₕ

curlcₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curlcₕ!(vₕ, uₕ) -> vₕ

Returns the centered discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a centered difference. There is no 1D curl, and asking for one is an ArgumentError.

curlcₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇cₕ × uₕ == curlcₕ(uₕ).

See also: curlₕ, divcₕ, ∇cₕ

curl̽ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl̽ₕ!(vₕ, uₕ) -> vₕ

Returns the cross-weighted discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a cross-weighted centered difference. There is no 1D curl, and asking for one is an ArgumentError.

curl̽ₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇̽ₕ × uₕ == curl̽ₕ(uₕ).

See also: curlcₕ, div̽ₕ, ∇̽ₕ

curl̽ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl̽ₕ!(vₕ, uₕ) -> vₕ

Returns the cross-weighted discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a cross-weighted centered difference. There is no 1D curl, and asking for one is an ArgumentError.

curl̽ₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇̽ₕ × uₕ == curl̽ₕ(uₕ).

See also: curlcₕ, div̽ₕ, ∇̽ₕ

Δₕ(uₕ::VectorElement) -> VectorElement
Δₕ!(vₕ::VectorElement, uₕ::VectorElement) -> vₕ
Δₕ(u::LazyOp{D}) -> LazyOp{D}

Returns the conservative discrete Laplacian of the grid function uₕ, matrix-free:

which on a non-uniform mesh is the flux-difference form

per direction. This is the composition whose summation-by-parts identity with inner₊ holds, innerₕ(Δₕ(uₕ), vₕ) = -inner₊(∇ₕ(uₕ), ∇ₕ(vₕ)) for grid functions vanishing on the boundary, which is what makes it the discrete Laplacian rather than one of several plausible five-point stencils.

Evaluated in a single traversal per direction rather than as two nested operator calls, so Δₕ! needs no scratch grid function and allocates nothing. It agrees with the composition D̃ₓ(D₋ₓ(uₕ)) entry for entry, truncation at the two ends of each axis included.

On a composite element Δₕ is the Laplacian of each component, each on its own mesh.

In a form, Δₕ(u) of a trial or test function, or of any operator over one, builds the same operator as nodes: the sum over the D axes of one three-point second difference each, entry for entry D̃ₓ(D₋ₓ(u)) + D̃ᵧ(D₋ᵧ(u)) + …, so the identity above reads innerₕ(Δₕ(u), v) = -inner₊(∇ₕ(u), ∇ₕ(v)) in a bilinear form on functions vanishing on the boundary. One node per axis, not the nested pair: the pair evaluates its inner difference again at each outer tap.

See also: divₕ, ∇ₕ, D̃ₓ

Δₕ(v::GhostVector) -> Vector
Δₕ!(out::AbstractVector, v::GhostVector) -> out

The conservative discrete Laplacian of a GhostVector at the physical nodes, as a plain vector with no ghosts: the values of Δₕ(lift(Cₕ, u)) there, when v holds the degrees of freedom u and update_ghosts! has filled its ghosts. Along an axis whose facet carries ghosts, the flux across the facet reads the ghost; along one without, the stencil is truncated as on a plain space.

out follows the rule of the one-axis operators (D₋ₓ! on a GhostVector). Δₕ! allocates nothing on CpuSerial and CpuPolyester.

Examples

Ωₕ = mesh(domain(interval(0.0, 1.0) × interval(0.0, 2.0)), (5, 7), (false, false))
Cₕ = constrained(gridspace(Ωₕ; ghosts = :boundary),
                 u -> (:xmin => ∂ₙ(u) => 1.0, :xmax => u + ∂ₙ(u) => 0.0,
                       :ymin => ∂ₙ(u) => 0.0, :ymax => ∂ₙ(u) => 0.0))
v = update_ghosts!(GhostVector(Cₕ, rand(35)), Cₕ)
Δₕ(v)                           # 35 values, the Neumann and Robin data in the boundary rows

Δₕ(uₕ::VectorElement) -> VectorElement
Δₕ!(vₕ::VectorElement, uₕ::VectorElement) -> vₕ
Δₕ(u::LazyOp{D}) -> LazyOp{D}

Returns the conservative discrete Laplacian of the grid function uₕ, matrix-free:

which on a non-uniform mesh is the flux-difference form

per direction. This is the composition whose summation-by-parts identity with inner₊ holds, innerₕ(Δₕ(uₕ), vₕ) = -inner₊(∇ₕ(uₕ), ∇ₕ(vₕ)) for grid functions vanishing on the boundary, which is what makes it the discrete Laplacian rather than one of several plausible five-point stencils.

Evaluated in a single traversal per direction rather than as two nested operator calls, so Δₕ! needs no scratch grid function and allocates nothing. It agrees with the composition D̃ₓ(D₋ₓ(uₕ)) entry for entry, truncation at the two ends of each axis included.

On a composite element Δₕ is the Laplacian of each component, each on its own mesh.

In a form, Δₕ(u) of a trial or test function, or of any operator over one, builds the same operator as nodes: the sum over the D axes of one three-point second difference each, entry for entry D̃ₓ(D₋ₓ(u)) + D̃ᵧ(D₋ᵧ(u)) + …, so the identity above reads innerₕ(Δₕ(u), v) = -inner₊(∇ₕ(u), ∇ₕ(v)) in a bilinear form on functions vanishing on the boundary. One node per axis, not the nested pair: the pair evaluates its inner difference again at each outer tap.

See also: divₕ, ∇ₕ, D̃ₓ

Δₕ(v::GhostVector) -> Vector
Δₕ!(out::AbstractVector, v::GhostVector) -> out

The conservative discrete Laplacian of a GhostVector at the physical nodes, as a plain vector with no ghosts: the values of Δₕ(lift(Cₕ, u)) there, when v holds the degrees of freedom u and update_ghosts! has filled its ghosts. Along an axis whose facet carries ghosts, the flux across the facet reads the ghost; along one without, the stencil is truncated as on a plain space.

out follows the rule of the one-axis operators (D₋ₓ! on a GhostVector). Δₕ! allocates nothing on CpuSerial and CpuPolyester.

Examples

Ωₕ = mesh(domain(interval(0.0, 1.0) × interval(0.0, 2.0)), (5, 7), (false, false))
Cₕ = constrained(gridspace(Ωₕ; ghosts = :boundary),
                 u -> (:xmin => ∂ₙ(u) => 1.0, :xmax => u + ∂ₙ(u) => 0.0,
                       :ymin => ∂ₙ(u) => 0.0, :ymax => ∂ₙ(u) => 0.0))
v = update_ghosts!(GhostVector(Cₕ, rand(35)), Cₕ)
Δₕ(v)                           # 35 values, the Neumann and Robin data in the boundary rows

εₕ(u) -> Bramble._StrainTensor

The symbolic small-strain tensor \(\varepsilon(u) = \tfrac12(\nabla u + \nabla u^{T})\) of a composite trial or test function u with one component per spatial dimension.

u is whatever form's trial or test argument already is: u(i) addresses its i-th component exactly as it does everywhere else in the form layer (gpena/Bramble.jl#74). Every entry is placed the way the discrete energy form needs it, with no collocation choice exposed – see this section's header comment for the placement.

The only supported use is inner₊(εₕ(u), εₕ(v)), which expands to \(\sum_{i,j} (\varepsilon_{ij}(u), \varepsilon_{ij}(v))_{S_{ij}}\) with \(S_{ii} = \{i\}\) and \(S_{ij} = \{i,j\}\) for i != j, through inner₊(left, right, Val(S)).

See also: divₘₕ, ∇ₕ.

εₕ(uₕ) -> NTuple{D, NTuple{D, VectorElement}}

Returns the discrete strain tensor of the vector field uₕ,

entry by entry

uₕ is an NTuple{D, VectorElement} – what ∇ₕ returns – or a grid function of a CompositeGridSpace with one leaf per spatial dimension, exactly as divₕ takes it, its components on one mesh.

ε_ii sits on the face centre a backward difference along xᵢ alone reaches; ε_ij (i != j) sits on the edge centre the two averages bring the two halves of the shear term to. The result is a D-by-D nested tuple of grid functions, symmetric by construction: εₕ(uₕ)[i][j] and εₕ(uₕ)[j][i] are separate grid functions holding the same values.

εₕ! writes into a preallocated D-by-D nested tuple of destinations instead, and allocates nothing.

See also: ∇ₕ, divₕ

εₕ!(dest::NTuple{D, NTuple{D, VectorElement}}, uₕ) -> dest

The in-place form of εₕ: the discrete strain tensor of uₕ, written into dest.

Allocates nothing, where the allocating form allocates its D * D results. Returns dest, so it composes.

dest[i][j] and dest[j][i] end up holding the same values for i != j (εₕ is symmetric by construction); both are written, so either may be read. No destination may alias a component of uₕ or another destination.

εcₕ(u::LazyOp{D}) -> Bramble._CenteredStrainTensor

The symbolic centered small-strain tensor of a composite trial or test function u,

The only supported use is innerₕ(εcₕ(u), εcₕ(v)), which expands to \(\sum_{i,j} (\varepsilon^{ij}_{c,h}(u), \varepsilon^{ij}_{c,h}(v))_h\). Shares its name with the runtime εcₕ over grid functions.

See also: divcₕ, εₕ.

εcₕ(uₕ) -> NTuple{D, NTuple{D, VectorElement}}
εcₕ!(dest::NTuple{D, NTuple{D, VectorElement}}, uₕ) -> dest

Returns the centered discrete strain tensor of the vector field uₕ, entry by entry

Every centered difference sits on the grid point itself, so unlike εₕ no average relocates the shear terms. uₕ is spelled as for divcₕ. The result is symmetric by construction: dest[i][j] and dest[j][i] hold the same values.

εcₕ! writes into a preallocated D-by-D nested tuple and allocates nothing. No destination may alias a component of uₕ or another destination.

See also: εₕ, ∇cₕ, divcₕ

εcₕ(u::LazyOp{D}) -> Bramble._CenteredStrainTensor

The symbolic centered small-strain tensor of a composite trial or test function u,

The only supported use is innerₕ(εcₕ(u), εcₕ(v)), which expands to \(\sum_{i,j} (\varepsilon^{ij}_{c,h}(u), \varepsilon^{ij}_{c,h}(v))_h\). Shares its name with the runtime εcₕ over grid functions.

See also: divcₕ, εₕ.

ε̽ₕ(u::LazyOp{D}) -> Bramble._CenteredStrainTensor

The symbolic cross-weighted small-strain tensor of a composite trial or test function u,

The only supported use is innerₕ(ε̽ₕ(u), ε̽ₕ(v)), which expands to \(\sum_{i,j} (\overset{\times}{\varepsilon}^{ij}_h(u), \overset{\times}{\varepsilon}^{ij}_h(v))_h\). Shares its name with the runtime ε̽ₕ over grid functions.

See also: div̽ₕ, εcₕ.

ε̽ₕ(uₕ) -> NTuple{D, NTuple{D, VectorElement}}
ε̽ₕ!(dest::NTuple{D, NTuple{D, VectorElement}}, uₕ) -> dest

Returns the cross-weighted discrete strain tensor of the vector field uₕ, entry by entry

Every cross-weighted difference sits on the grid point itself, so, as for εcₕ, no average relocates the shear terms. uₕ is spelled as for div̽ₕ. The result is symmetric by construction: dest[i][j] and dest[j][i] hold the same values.

ε̽ₕ! writes into a preallocated D-by-D nested tuple and allocates nothing. No destination may alias a component of uₕ or another destination.

See also: εcₕ, ∇̽ₕ, div̽ₕ

ε̽ₕ(u::LazyOp{D}) -> Bramble._CenteredStrainTensor

The symbolic cross-weighted small-strain tensor of a composite trial or test function u,

The only supported use is innerₕ(ε̽ₕ(u), ε̽ₕ(v)), which expands to \(\sum_{i,j} (\overset{\times}{\varepsilon}^{ij}_h(u), \overset{\times}{\varepsilon}^{ij}_h(v))_h\). Shares its name with the runtime ε̽ₕ over grid functions.

See also: div̽ₕ, εcₕ.

∇cₕ(uₕ::VectorElement) -> VectorElement or NTuple{D, VectorElement}

Returns the centered discrete gradient of the grid function uₕ, one centered difference per direction:

The same function as Dcₕ, under the name the centered vector calculus family shares. In 1D it returns the bare grid function, above a D-tuple. Each difference is truncated to zero on the first and last slice of its direction.

∇cₕ! writes into a destination instead, and allocates nothing.

See also: divcₕ, curlcₕ, εcₕ, ∇ₕ

∇cₕ!(dest, uₕ::VectorElement) -> dest

The in-place form of ∇cₕ: the centered gradient of uₕ, written into dest – a grid function in 1D, a D-tuple of them above, the shape ∇cₕ returns.

Allocates nothing. No destination may alias uₕ or another destination.

∇̽ₕ(uₕ::VectorElement) -> VectorElement or NTuple{D, VectorElement}

Returns the cross-weighted discrete gradient of the grid function uₕ, one cross-weighted centered difference per direction:

The same function as D̽ₕ: the dispatch alias and the tuple-valued alias coincide for this family, so ∇̽ₕ is simply another name for it, under the ∇ notation the other vectorial gradients share. In 1D it returns the bare grid function, above a D-tuple. The first and last point along each direction have no truncated-boundary convention of their own and fall back to the one-sided difference the near side still defines, unlike ∇cₕ.

See also: D̽ₓ, ∇ₕ, ∇₊ₕ

∇̽ₕ!(dest, uₕ::VectorElement) -> dest

The in-place form of ∇̽ₕ: the cross-weighted gradient of uₕ, written into dest – a grid function in 1D, a D-tuple of them above, the shape ∇̽ₕ returns.

Allocates nothing. No destination may alias uₕ or another destination.

∇̃ₕ(uₕ::VectorElement) -> VectorElement or NTuple{D, VectorElement}

Returns the tilde discrete gradient of the grid function uₕ, one tilde forward difference per direction:

The same function as D̃ₕ, under the name the tilde vector calculus family shares. In 1D it returns the bare grid function, above a D-tuple. Each difference is truncated to zero on the last slice of its direction.

∇̃ₕ! writes into a destination instead, and allocates nothing.

See also: diṽₕ, curl̃ₕ, ∇ₕ

∇̃ₕ!(dest, uₕ::VectorElement) -> dest

The in-place form of ∇̃ₕ: the tilde gradient of uₕ, written into dest – a grid function in 1D, a D-tuple of them above, the shape ∇̃ₕ returns.

Allocates nothing. No destination may alias uₕ or another destination.

diṽₕ(uₕ) -> VectorElement
diṽₕ!(vₕ::VectorElement, uₕ) -> vₕ

Returns the tilde discrete divergence of the vector field uₕ:

uₕ is spelled as for divₕ: an NTuple{D, VectorElement}, or a grid function of a CompositeGridSpace with one leaf per spatial dimension (in 1D, a scalar grid function), its components on one mesh. Each tilde difference is zero on the last slice of its direction.

For fields vanishing on the boundary it pairs with the backward difference by summation by parts, \((\tilde{\textrm{div}}_h \textrm{F}, \textrm{v})_h = -\sum_d (\textrm{F}_d, \textrm{D}_{-,x_d} \textrm{v})_{+,d}\).

diṽₕ! writes into vₕ, which must not be one of the components, and allocates nothing.

∇̃ₕ ⋅ uₕ == diṽₕ(uₕ).

See also: divₕ, curl̃ₕ, ∇̃ₕ

diṽₕ(uₕ) -> VectorElement
diṽₕ!(vₕ::VectorElement, uₕ) -> vₕ

Returns the tilde discrete divergence of the vector field uₕ:

uₕ is spelled as for divₕ: an NTuple{D, VectorElement}, or a grid function of a CompositeGridSpace with one leaf per spatial dimension (in 1D, a scalar grid function), its components on one mesh. Each tilde difference is zero on the last slice of its direction.

For fields vanishing on the boundary it pairs with the backward difference by summation by parts, \((\tilde{\textrm{div}}_h \textrm{F}, \textrm{v})_h = -\sum_d (\textrm{F}_d, \textrm{D}_{-,x_d} \textrm{v})_{+,d}\).

diṽₕ! writes into vₕ, which must not be one of the components, and allocates nothing.

∇̃ₕ ⋅ uₕ == diṽₕ(uₕ).

See also: divₕ, curl̃ₕ, ∇̃ₕ

curl̃ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl̃ₕ!(vₕ, uₕ) -> vₕ

Returns the tilde discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a tilde forward difference. There is no 1D curl, and asking for one is an ArgumentError.

curl̃ₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇̃ₕ × uₕ == curl̃ₕ(uₕ).

See also: curlₕ, diṽₕ, ∇̃ₕ

curl̃ₕ(uₕ) -> VectorElement or NTuple{3, VectorElement}
curl̃ₕ!(vₕ, uₕ) -> vₕ

Returns the tilde discrete curl of the vector field uₕ. In 2D it is the scalar

and in 3D the three-component field \((\partial_y u_3 - \partial_z u_2,\; \partial_z u_1 - \partial_x u_3,\; \partial_x u_2 - \partial_y u_1)\), each derivative a tilde forward difference. There is no 1D curl, and asking for one is an ArgumentError.

curl̃ₕ! takes a destination – a grid function in 2D, a 3-tuple of them in 3D – and allocates nothing. No destination may alias a component of uₕ or another destination.

∇̃ₕ × uₕ == curl̃ₕ(uₕ).

See also: curlₕ, diṽₕ, ∇̃ₕ

ε₊ₕ(uₕ) -> NTuple{D, NTuple{D, VectorElement}}
ε₊ₕ!(dest::NTuple{D, NTuple{D, VectorElement}}, uₕ) -> dest

Returns the forward discrete strain tensor of the vector field uₕ, the forward twin of εₕ, entry by entry

uₕ is spelled as for divₕ. Every difference and average is truncated to zero on the last slice of its direction. The result is symmetric by construction: dest[i][j] and dest[j][i] hold the same values.

ε₊ₕ! writes into a preallocated D-by-D nested tuple and allocates nothing. No destination may alias a component of uₕ or another destination.

See also: εₕ, ∇₊ₕ, div₊ₕ

ε₊ₕ(uₕ) -> NTuple{D, NTuple{D, VectorElement}}
ε₊ₕ!(dest::NTuple{D, NTuple{D, VectorElement}}, uₕ) -> dest

Returns the forward discrete strain tensor of the vector field uₕ, the forward twin of εₕ, entry by entry

uₕ is spelled as for divₕ. Every difference and average is truncated to zero on the last slice of its direction. The result is symmetric by construction: dest[i][j] and dest[j][i] hold the same values.

ε₊ₕ! writes into a preallocated D-by-D nested tuple and allocates nothing. No destination may alias a component of uₕ or another destination.

See also: εₕ, ∇₊ₕ, div₊ₕ

jumpₓ(arg)

The jump across the interfaces along the x direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\).

Alias for jump(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along x has no forward neighbour and is treated as though it were zero, as in diff₊ₓ.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

jumpₓ(op::LazyOp{D})

The symbolic jump across the interfaces of op along the x direction.

Alias for jump(op, Val(1)).

jumpₓ!(vₕ, uₕ)

The jump across the interfaces along the x direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\), written into vₕ.

The in-place form of jumpₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(jumpₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for jump!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

jumpᵧ(arg)

The jump across the interfaces along the y direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\).

Alias for jump(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along y has no forward neighbour and is treated as though it were zero, as in diff₊ᵧ.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

jumpᵧ(op::LazyOp{D})

The symbolic jump across the interfaces of op along the y direction.

Alias for jump(op, Val(2)).

jumpᵧ!(vₕ, uₕ)

The jump across the interfaces along the y direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\), written into vₕ.

The in-place form of jumpᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(jumpᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for jump!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

jump₂(arg)

The jump across the interfaces along the z direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\).

Alias for jump(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along z has no forward neighbour and is treated as though it were zero, as in diff₊₂.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

jump₂(op::LazyOp{D})

The symbolic jump across the interfaces of op along the z direction.

Alias for jump(op, Val(3)).

jump₂!(vₕ, uₕ)

The jump across the interfaces along the z direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\), written into vₕ.

The in-place form of jump₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(jump₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for jump!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

jumpₕ(arg)

The jump of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, jumpₕ(uₕ) is (jump(uₕ, Val(1)), jump(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for jump.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

jumpₕ(op::LazyOp{D})

The symbolic jump across the interfaces of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

jump(arg, dim_val::Val)

The jump across the interfaces along the direction dim_val, \(u_{i+1} - u_i\).

arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Forwards to forward_difference, since a jump across an interface and an unscaled forward difference are the same quantity. The name records which of the two is meant.

jump(arg, d)

The jump across the interfaces along the d direction, \(\llbracket u \rrbracket = u_{i+1} - u_i\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one jumpₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for jump(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

jump(op::LazyOp{D}, ::Val{Dim})

The symbolic jump across the interfaces of op along direction Dim, as a JumpNode node.

The entry point jumpₓ and its siblings forward through, and the same function the space layer applies to a grid function: jump(uₕ, Val(1)) computes values, jump(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

Mₓ(arg)

The backward average along the x direction, \(\frac{u_{i-1} + u_{i}}{2}\).

Alias for backward_average(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mₓ(op::LazyOp{D})

The symbolic backward spatial average of op along the x direction.

Alias for Mₕ(op, Val(1)).

Mₓ!(vₕ, uₕ)

The backward average of uₕ along the x direction, \(\frac{u_{i-1} + u_{i}}{2}\), written into vₕ.

The in-place form of Mₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Mₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_average!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Mᵧ(arg)

The backward average along the y direction, \(\frac{u_{i-1} + u_{i}}{2}\).

Alias for backward_average(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mᵧ(op::LazyOp{D})

The symbolic backward spatial average of op along the y direction.

Alias for Mₕ(op, Val(2)).

Mᵧ!(vₕ, uₕ)

The backward average of uₕ along the y direction, \(\frac{u_{i-1} + u_{i}}{2}\), written into vₕ.

The in-place form of Mᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Mᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_average!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

M₂(arg)

The backward average along the z direction, \(\frac{u_{i-1} + u_{i}}{2}\).

Alias for backward_average(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

M₂(op::LazyOp{D})

The symbolic backward spatial average of op along the z direction.

Alias for Mₕ(op, Val(3)).

M₂!(vₕ, uₕ)

The backward average of uₕ along the z direction, \(\frac{u_{i-1} + u_{i}}{2}\), written into vₕ.

The in-place form of M₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(M₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_average!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Mₕ(arg, d)

The backward average along the d direction, \(\frac{u_{i-1} + u_{i}}{2}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one Mₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for backward_average(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mₕ(arg)

The backward average of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, Mₕ(uₕ) is (backward_average(uₕ, Val(1)), backward_average(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for backward_average.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

Mₕ(op::LazyOp{D}, ::Val{Dim})

The symbolic backward spatial average of op along direction Dim, as a BackwardAverage node.

The entry point Mₓ and its siblings forward through, and the same function the space layer applies to a grid function: Mₕ(uₕ, Val(1)) computes values, Mₕ(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

Mₕ(op::LazyOp{D})

The symbolic backward spatial average of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

Mcₓ(arg)

The centered average along the x direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\).

Alias for centered_average(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along x are truncated to zero. On a device-backed grid function it throws, as there is no device kernel yet.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mcₓ(op::LazyOp{D})

The symbolic centered spatial average of op along the x direction.

Alias for Mcₕ(op, Val(1)).

Mcₓ!(vₕ, uₕ)

The centered average of uₕ along the x direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\), written into vₕ.

The in-place form of Mcₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Mcₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_average!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Mcᵧ(arg)

The centered average along the y direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\).

Alias for centered_average(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along y are truncated to zero. On a device-backed grid function it throws, as there is no device kernel yet.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mcᵧ(op::LazyOp{D})

The symbolic centered spatial average of op along the y direction.

Alias for Mcₕ(op, Val(2)).

Mcᵧ!(vₕ, uₕ)

The centered average of uₕ along the y direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\), written into vₕ.

The in-place form of Mcᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Mcᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_average!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Mc₂(arg)

The centered average along the z direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\).

Alias for centered_average(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first and last points along z are truncated to zero. On a device-backed grid function it throws, as there is no device kernel yet.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mc₂(op::LazyOp{D})

The symbolic centered spatial average of op along the z direction.

Alias for Mcₕ(op, Val(3)).

Mc₂!(vₕ, uₕ)

The centered average of uₕ along the z direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\), written into vₕ.

The in-place form of Mc₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(Mc₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for centered_average!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

Mcₕ(arg, d)

The centered average along the d direction, \(\frac{u_{i-1} + 2 u_{i} + u_{i+1}}{4}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one Mcₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for centered_average(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

Mcₕ(arg)

The centered average of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, Mcₕ(uₕ) is (centered_average(uₕ, Val(1)), centered_average(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for centered_average.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

Mcₕ(op::LazyOp{D}, ::Val{Dim})

The symbolic centered spatial average of op along direction Dim, as a CenteredAverage node.

The entry point Mcₓ and its siblings forward through, and the same function the space layer applies to a grid function: Mcₕ(uₕ, Val(1)) computes values, Mcₕ(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

Mcₕ(op::LazyOp{D})

The symbolic centered spatial average of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

M₊ₓ(arg)

The forward average along the x direction, \(\frac{u_{i} + u_{i+1}}{2}\).

Alias for forward_average(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

M₊ₓ(op::LazyOp{D})

The symbolic forward spatial average of op along the x direction.

Alias for M₊ₕ(op, Val(1)).

M₊ₓ!(vₕ, uₕ)

The forward average of uₕ along the x direction, \(\frac{u_{i} + u_{i+1}}{2}\), written into vₕ.

The in-place form of M₊ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(M₊ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_average!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

M₊ᵧ(arg)

The forward average along the y direction, \(\frac{u_{i} + u_{i+1}}{2}\).

Alias for forward_average(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

M₊ᵧ(op::LazyOp{D})

The symbolic forward spatial average of op along the y direction.

Alias for M₊ₕ(op, Val(2)).

M₊ᵧ!(vₕ, uₕ)

The forward average of uₕ along the y direction, \(\frac{u_{i} + u_{i+1}}{2}\), written into vₕ.

The in-place form of M₊ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(M₊ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_average!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

M₊₂(arg)

The forward average along the z direction, \(\frac{u_{i} + u_{i+1}}{2}\).

Alias for forward_average(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

M₊₂(op::LazyOp{D})

The symbolic forward spatial average of op along the z direction.

Alias for M₊ₕ(op, Val(3)).

M₊₂!(vₕ, uₕ)

The forward average of uₕ along the z direction, \(\frac{u_{i} + u_{i+1}}{2}\), written into vₕ.

The in-place form of M₊₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(M₊₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_average!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

M₊ₕ(arg, d)

The forward average along the d direction, \(\frac{u_{i} + u_{i+1}}{2}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one M₊ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for forward_average(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

M₊ₕ(arg)

The forward average of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, M₊ₕ(uₕ) is (forward_average(uₕ, Val(1)), forward_average(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for forward_average.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

M₊ₕ(op::LazyOp{D}, ::Val{Dim})

The symbolic forward spatial average of op along direction Dim, as a ForwardAverage node.

The entry point M₊ₓ and its siblings forward through, and the same function the space layer applies to a grid function: M₊ₕ(uₕ, Val(1)) computes values, M₊ₕ(U, Val(1)) builds the node that will compute them during assembly.

Takes a Val and not an Int, unlike its space-layer namesake: Dim is a type parameter of the node, so a runtime direction would make the return type a Union.

M₊ₕ(op::LazyOp{D})

The symbolic forward spatial average of op along every coordinate, as a D-tuple of nodes. In one dimension there is one direction, so the node itself is returned rather than a one-element tuple.

S₊ₓ(arg)

The forward index shift along the x direction, \((S_+ u)_i = u_{i+1}\).

Alias for forward_shift(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along x has no forward neighbour and reads 0, so S₊ₓ(uₕ) - uₕ equals jumpₓ(uₕ) everywhere.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₊ₓ!(vₕ, uₕ)

The forward index shift along the x direction, \((S_+ u)_i = u_{i+1}\), written into vₕ.

The in-place form of S₊ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₊ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_shift!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₊ᵧ(arg)

The forward index shift along the y direction, \((S_+ u)_i = u_{i+1}\).

Alias for forward_shift(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along y has no forward neighbour and reads 0, so S₊ᵧ(uₕ) - uₕ equals jumpᵧ(uₕ) everywhere.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₊ᵧ!(vₕ, uₕ)

The forward index shift along the y direction, \((S_+ u)_i = u_{i+1}\), written into vₕ.

The in-place form of S₊ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₊ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_shift!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₊₂(arg)

The forward index shift along the z direction, \((S_+ u)_i = u_{i+1}\).

Alias for forward_shift(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The last point along z has no forward neighbour and reads 0, so S₊₂(uₕ) - uₕ equals jump₂(uₕ) everywhere.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₊₂!(vₕ, uₕ)

The forward index shift along the z direction, \((S_+ u)_i = u_{i+1}\), written into vₕ.

The in-place form of S₊₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₊₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for forward_shift!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₊ₕ(arg)

The forward index shift of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, S₊ₕ(uₕ) is (forward_shift(uₕ, Val(1)), forward_shift(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for forward_shift.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

S₊(arg, d)

The forward index shift along the d direction, \((S_+ u)_i = u_{i+1}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one S₊ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for forward_shift(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

forward_shift(arg, dim_val::Val) -> AbstractMatrix or VectorElement

The forward index shift along direction dim_val, \((S_+ u)_i = u_{i+1}\).

It relabels values one grid point along the direction and involves no spacing, so it is the same on uniform and non-uniform meshes. The last point along the direction has no forward neighbour and reads 0, the convention of jumpₓ (unlike D₊ₓ, which is 0 at that point); hence \(S_+ u - u\) is the jump \(u_{i+1} - u_i\) at every point, the last one included, and the matrix of forward_shift is the transpose of that of backward_shift.

Arguments

• arg: A mesh Ωₕ, a grid space Wₕ or a VectorElement uₕ, scalar or composite (componentwise on the latter), or a symbolic operand of a form (a LazyOp such as the trial function u or D₋ₓ(u)).

• dim_val: The direction, Val(1), Val(2) or Val(3). On a form operand the entry points S₊/S₋ take this Val form only; their Int and Symbol directions are for a mesh, a space or a grid function, since the direction is part of the node's type.

Returns

• For a mesh or a grid space, the npoints(Ωₕ) × npoints(Ωₕ) matrix shift(Ωₕ, dim_val, Val(1)), in the backend's matrix_type, with ones on the superdiagonal of that direction.

• For a VectorElement, a new VectorElement of the same space holding \(u_{i+1}\).

• For a LazyOp, the ShiftNode that assembles \(u_{i+1}\) inside a form.

Throws

• ArgumentError: dim_val is not between 1 and the mesh (or operand) dimension; or uₕ is device-backed or its space has a GpuPolicy (no device kernel yet, tracked on milestone v4.7.0).

Examples

using Bramble
using Bramble: forward_shift
Wₕ = gridspace(mesh(domain(interval(0.0, 1.0)), 5, true))
uₕ = Rₕ(Wₕ, x -> 4x)
parent(forward_shift(uₕ, Val(1)))

# output
5-element Vector{Float64}:
 1.0
 2.0
 3.0
 4.0
 0.0

See also: backward_shift, S₊ₕ, jump.

S₋ₓ(arg)

The backward index shift along the x direction, \((S_- u)_i = u_{i-1}\).

Alias for backward_shift(arg, Val(1)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first point along x has no backward neighbour and reads 0; the matrix is the transpose of S₊ₓ's.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₋ₓ!(vₕ, uₕ)

The backward index shift along the x direction, \((S_- u)_i = u_{i-1}\), written into vₕ.

The in-place form of S₋ₓ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₋ₓ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_shift!(vₕ, uₕ, Val(1)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₋ᵧ(arg)

The backward index shift along the y direction, \((S_- u)_i = u_{i-1}\).

Alias for backward_shift(arg, Val(2)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first point along y has no backward neighbour and reads 0; the matrix is the transpose of S₊ᵧ's.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₋ᵧ!(vₕ, uₕ)

The backward index shift along the y direction, \((S_- u)_i = u_{i-1}\), written into vₕ.

The in-place form of S₋ᵧ: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₋ᵧ!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_shift!(vₕ, uₕ, Val(2)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₋₂(arg)

The backward index shift along the z direction, \((S_- u)_i = u_{i-1}\).

Alias for backward_shift(arg, Val(3)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement. The first point along z has no backward neighbour and reads 0; the matrix is the transpose of S₊₂'s.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

S₋₂!(vₕ, uₕ)

The backward index shift along the z direction, \((S_- u)_i = u_{i-1}\), written into vₕ.

The in-place form of S₋₂: it allocates nothing, where the allocating form allocates its result. Returns vₕ, so it composes: normₕ(S₋₂!(vₕ, uₕ)).

vₕ and uₕ must be grid functions of the same space, and must not be the same object, as every stencil reads neighbours of the target coordinate; aliasing them would read values that have already been overwritten. Either violation throws an ArgumentError.

Alias for backward_shift!(vₕ, uₕ, Val(3)). Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter.

S₋ₕ(arg)

The backward index shift of arg along every coordinate, as a tuple with one entry per spatial dimension. On a one-dimensional mesh it returns that single entry rather than a one-tuple.

For a 2D space, S₋ₕ(uₕ) is (backward_shift(uₕ, Val(1)), backward_shift(uₕ, Val(2))). arg is a mesh, a grid space or a VectorElement, as for backward_shift.

Accepts a grid function of a scalar or of a composite grid space, componentwise on the latter: each entry of the tuple is then itself a composite grid function.

S₋(arg, d)

The backward index shift along the d direction, \((S_- u)_i = u_{i-1}\).

d names the direction three ways: a Val (Val(1)), an Int (1, 2, 3) or a Symbol (:x, :y, :z). The Val form is the one S₋ₓ and its siblings forward through; the other two select between literal Vals, one arm per direction the mesh has, so the direction still reaches the stencil engine as a compile-time constant and a loop over d allocates nothing beyond its results. An Int outside 1:dim(mesh), or a Symbol that is not :x/:y/:z, throws an ArgumentError.

Alias for backward_shift(arg, Val(d)). arg is a mesh, a grid space or a VectorElement: the first two give the operator as a sparse matrix, the third applies it and returns a VectorElement.

Accepts a grid function of a scalar or of a composite grid space. On a composite one the operator is applied to each component in turn, and the result is the composite grid function whose components are those results.

backward_shift(arg, dim_val::Val) -> AbstractMatrix or VectorElement

The backward index shift along direction dim_val, \((S_- u)_i = u_{i-1}\).

It involves no spacing. The first point along the direction has no backward neighbour and reads 0, so \(u - S_- u\) is the unscaled backward difference \(u_i - u_{i-1}\) at every point, the first one reading \(u_1\), and the matrix of backward_shift is the transpose of that of forward_shift.

Arguments

• arg: A mesh Ωₕ, a grid space Wₕ or a VectorElement uₕ, scalar or composite (componentwise on the latter), or a symbolic operand of a form (a LazyOp such as the trial function u or D₋ₓ(u)).

• dim_val: The direction, Val(1), Val(2) or Val(3). On a form operand the entry points S₊/S₋ take this Val form only; their Int and Symbol directions are for a mesh, a space or a grid function, since the direction is part of the node's type.

Returns

• For a mesh or a grid space, the npoints(Ωₕ) × npoints(Ωₕ) matrix shift(Ωₕ, dim_val, Val(-1)), in the backend's matrix_type, with ones on the subdiagonal of that direction.

• For a VectorElement, a new VectorElement of the same space holding \(u_{i-1}\).

• For a LazyOp, the ShiftNode that assembles \(u_{i-1}\) inside a form.

Throws

• ArgumentError: dim_val is not between 1 and the mesh (or operand) dimension; or uₕ is device-backed or its space has a GpuPolicy (no device kernel yet, tracked on milestone v4.7.0).

Examples

using Bramble
using Bramble: backward_shift
Wₕ = gridspace(mesh(domain(interval(0.0, 1.0)), 5, true))
uₕ = Rₕ(Wₕ, x -> 4x)
parent(backward_shift(uₕ, Val(1)))

# output
5-element Vector{Float64}:
 0.0
 0.0
 1.0
 2.0
 3.0

See also: forward_shift, S₋ₕ.

∂ₙ(u; K = nothing)

The outward normal derivative of u at the boundary facets, η_F Dc_d(u) on the facet F of normal axis d, with Dc_d the centred difference across the facet. It reads the ghost beyond the facet, so the space must have ghosts there: build it with gridspace(Ωₕ; ghosts = ...).

A node on several facets (a 2D corner) has one value per facet. Meaningful inside inner_Γ, on either side or both, where each facet's term carries that facet's weight and markers selects the facets (required; :boundary is all of them); so inner_Γ(∂ₙ(u), v; markers = (:xmin,)) gives a corner only its xmin term, and per-facet coefficients are sums over markers. With ∂ₙ on both sides, facet pairs with facet.

With a constant D × D matrix K, it is the conormal derivative η_F · (K Dc u), the centred difference along every axis. A K that varies in space is refused with an ArgumentError when ∂ₙ is called; a facet without ghosts, or a space without any, when form is. So is a nonzero K[d, e], e ≠ d, on a facet of axis d whose corners lack the ghosts of the two e facets: the tangential difference there reads them.

Examples

Ωₕ = mesh(domain(interval(0.0, 1.0) × interval(0.0, 1.0)), (9, 9), (true, true))
Wₕ = gridspace(Ωₕ; ghosts = :boundary)
a = form(Wₕ, Wₕ, (u, v) -> inner_Γ(∂ₙ(u), v; markers = (:xmin, :ymax)))
K = [2.0 0.5; 0.5 1.0]
b = form(Wₕ, Wₕ, (u, v) -> inner_Γ(∂ₙ(u; K), v; markers = :boundary))

See also: inner_Γ, η

∂ₙₙ(u)

The second normal derivative of u at the boundary facets: on the facet F of normal axis d, the second difference D̃_d D₋_d u along d alone (the per-axis term of Δₕ), the same on both sides since η_F² = 1. It reads the ghost beyond the facet, whose spacing is the first interior one, so the space must have ghosts there: build it with gridspace(Ωₕ; ghosts = ...).

A node on several facets (a 2D corner) has one value per facet, each reading only the ghost of its own facet. Meaningful inside inner_Γ, on either side or both, with markers selecting the facets as for ∂ₙ; a facet without ghosts, or a space without any, is refused with an ArgumentError when form is called.

Examples

Ωₕ = mesh(domain(interval(0.0, 1.0) × interval(0.0, 1.0)), (9, 9), (true, true))
Wₕ = gridspace(Ωₕ; ghosts = :boundary)
a = form(Wₕ, Wₕ, (u, v) -> inner_Γ(∂ₙₙ(u), v; markers = (:xmin,)))

See also: ∂ₙ, jumpₙ, inner_Γ

jumpₙ(w)

The inward jump of w at the boundary facets, w_{I − η_F e_d} − w_I at the node I of the facet F of normal axis d: the forward jump w_{I + e_d} − w_I on a minimum facet, the backward one w_{I − e_d} − w_I on a maximum facet. Both read only the facet node and its interior neighbour, so jumpₙ needs no ghosts of its own and works on any space. Its operand is evaluated as anywhere else: jumpₙ(Δₕ(u)) reads the ghosts of a ghost space, and on a plain space Δₕ is truncated at the boundary.

A node on several facets (a 2D corner) has one value per facet. Meaningful inside inner_Γ, on either side or both, with markers selecting the facets as for ∂ₙ, so per-facet coefficients are sums over markers.

Examples

Ωₕ = mesh(domain(interval(0.0, 1.0) × interval(0.0, 1.0)), (9, 9), (true, true))
Wₕ = gridspace(Ωₕ; ghosts = :boundary)
a = form(Wₕ, Wₕ, (u, v) -> inner_Γ(2.0 * jumpₙ(u), jumpₙ(v); markers = (:xmin,)))
b = form(Wₕ, Wₕ, (u, v) -> inner_Γ(jumpₙ(Δₕ(u)), v; markers = :boundary))

See also: ∂ₙ, ∂ₙₙ, inner_Γ