Spaces

BufferType{T,VectorType}

Type alias for an ordered dictionary that maps integer keys to VectorBuffer instances.

This is the underlying storage container for GridSpaceBuffer, allowing efficient lookup and iteration over the buffer pool.

Type Parameters

• T: Element type of the vectors (e.g., Float64)
• VectorType: Type of the underlying vector container (e.g., Vector{Float64})

Example

buffer_dict = BufferType{Float64, Vector{Float64}}()
buffer_dict[1] = VectorBuffer(zeros(100), false)

See also: VectorBuffer, GridSpaceBuffer

struct GridSpaceBuffer{BT, VT, T}

Manages a pool of reusable VectorBuffers for a specific grid size and backend.

This structure is the core of the buffer management system. It holds an OrderedDict of VectorBuffers, allowing temporary vectors to be efficiently reused, thus minimizing memory allocation during iterative computations.

Fields

• buffer: an OrderedDict mapping an integer key to each VectorBuffer in the pool.

• backend: the computational backend associated with the buffers.

• npts: the size (npts) of the vectors managed by this buffer pool.

mutable struct VectorBuffer{T, VT<:AbstractArray{T, 1}} <: AbstractArray{T, 1}

A simple, mutable wrapper around a vector, designed to be part of a buffer pool to avoid repeated memory allocations during iterative computations.

The in_use flag acts as a simple locking mechanism to track whether the buffer's data is currently being used in a computation.

Fields

• vector: the underlying vector that holds the data.

• in_use: a boolean flag indicating if the buffer is currently locked (in use).

add_buffer!(space_buffer::GridSpaceBuffer)

Dynamically adds one new, available VectorBuffer to the pool. This is called when a request is made for a buffer but all existing ones are in use.

in_use(buffer::VectorBuffer)

Checks if the VectorBuffer is currently marked as in use (locked).

lock!(space_buffer::GridSpaceBuffer, i)

Locks the i-th buffer in the pool and returns the underlying vector for immediate use.

lock!(buffer::VectorBuffer)

Marks the VectorBuffer as currently in use (locks it).

nbuffers(space_buffer::GridSpaceBuffer)

Returns the total number of buffers (both locked and unlocked) currently in the pool.

simple_space_buffer(b::Backend, npts::Int; nbuffers::Int = 0)

Creates a GridSpaceBuffer pool, optionally pre-allocating a number of buffers. "Warming up" the pool by pre-allocating buffers can improve performance on the first few iterations.

unlock!(space_buffer::GridSpaceBuffer, i)

Unlocks the i-th buffer in the pool, marking it as available for reuse.

unlock!(buffer::VectorBuffer)

Marks the VectorBuffer as available (unlocks it).

vector(buffer::VectorBuffer)

Returns the underlying vector stored in the VectorBuffer.

vector_buffer(b::Backend, n::Int)

Creates a single VectorBuffer of size n, associated with a computational backend b. The buffer is initialized as unlocked (in_use = false).

vector_buffer(space_buffer::GridSpaceBuffer)

Retrieves an available vector from the buffer pool.

This is the main function for acquiring a temporary vector. It first searches for any unlocked buffer. If all existing buffers are locked, it transparently allocates a new one and adds it to the pool. The function returns the vector itself and its integer key, which must be used later to unlock! it. The buffer is marked as locked upon retrieval.

Coordinate axis labels used in documentation and error messages.

Corresponds to the x, y, and z spatial dimensions (1st, 2nd, and 3rd dimensions).

See also: _BRAMBLE_var2symbol

Subscript Unicode symbols for x, y, z coordinates used in operator notation.

These symbols are used to generate directional operator aliases via metaprogramming.

Examples

• D₊ₓ - forward difference in x-direction
• M₋ᵧ - backward average in y-direction
• jump₊₂ - forward jump in z-direction

See also: _BRAMBLE_var2label

AbstractSpaceType{N}

Abstract supertype for all function spaces defined on a mesh.

This is the top-level abstraction for a grid-based function space. The parameter N represents the number of components of the field (e.g., N=1 for a scalar field, N=3 for a 3D vector field).

ComponentStyle

Abstract type for compile-time dispatch on the number of field components in a function space.

The ComponentStyle hierarchy is used to specialize algorithms for scalar fields (single component) versus vector fields (multiple components). This pattern enables efficient code generation through Julia's multiple dispatch, avoiding runtime if/else checks.

Subtypes

• SingleComponent: For scalar fields (e.g., temperature, pressure)
• MultiComponent{D}: For vector fields with D components (e.g., velocity, displacement)

Usage

ComponentStyle(typeof(Wₕ))  # Returns SingleComponent() or MultiComponent{D}()

Example

Wₕ = gridspace(Ωₕ)  # Scalar space
ComponentStyle(typeof(Wₕ))  # Returns SingleComponent()

# Dispatch example
to_matrix(uₕ, ::SingleComponent) = # ... scalar implementation
to_matrix(uₕ, ::MultiComponent{D}) where D = # ... vector implementation

See also: SingleComponent, MultiComponent, to_matrix

InnerProductType

Abstract type for selecting which discrete inner product formula to use.

Different inner product types correspond to different weight distributions on the grid, used in various finite difference schemes and stability analyses. The choice of inner product affects energy estimates and numerical stability properties.

Subtypes

• Innerh: Standard $L^2$ inner product using cell measures (volumes)
• Innerplus: Modified inner product using staggered grid spacings

Background

In finite difference methods, different inner products arise naturally from:

• Summation-by-parts (SBP) operators
• Energy method stability analysis
• Discrete integration formulas

The standard inner product (Innerh) uses cell volumes as weights, while the modified inner products (Innerplus) use combinations of forward/backward spacings, appearing in discrete energy estimates for difference operators.

Usage

# Compute standard L² inner product
result = innerₕ(uₕ, vₕ)  # Uses Innerh() internally

# Compute modified inner product in x-direction
result = inner₊ₓ(uₕ, vₕ)  # Uses Innerplus() internally

See also: Innerh, Innerplus, innerₕ, inner₊ₓ

Innerh <: InnerProductType

Selector for the standard discrete $L^2$ inner product weighted by cell measures.

The weights are the volumes (1D: lengths, 2D: areas, 3D: volumes) of grid cells, denoted $|\square_k|$. This is the most common inner product for finite difference methods and corresponds to the trapezoid rule for integration on non-uniform grids.

Mathematical Form

For a 2D grid:

\[(u_h, v_h)_h = \sum_{i,j} |\square_{i,j}| u_h(x_i, y_j) v_h(x_i, y_j)\]

where $|\square_{i,j}|$ is the area of the cell centered at $(x_i, y_j)$.

Example

# Compute L² inner product
result = innerₕ(uₕ, vₕ)  # Uses Innerh() internally

# Compute L² norm
norm_value = normₕ(uₕ)  # Equivalent to sqrt(innerₕ(uₕ, uₕ))

See also: InnerProductType, Innerplus, innerₕ, normₕ

Innerplus <: InnerProductType

Selector for modified discrete $L^2$ inner products using staggered grid spacings.

These inner products use a combination of forward spacings $h_i$ and centered cell widths $h_{i+1/2}$, appearing naturally in energy estimates for finite difference operators. Different spatial directions may have different weight formulas.

The modified inner products are essential for:

• Proving discrete energy stability
• Analyzing discrete conservation properties
• Constructing stable finite difference schemes

Mathematical Form

For a 2D grid in the x-direction:

\[(u_h, v_h)_{+x} = \sum_{i,j} h_{x,i} h_{y,j+1/2} u_h(x_i, y_j) v_h(x_i, y_j)\]

Example

# These functions use Innerplus internally
result_x = inner₊ₓ(uₕ, vₕ)  # Modified inner product, x-direction
result_y = inner₊ᵧ(uₕ, vₕ)  # Modified inner product, y-direction

See also: InnerProductType, Innerh, inner₊ₓ, weights

struct MatrixElement{S, T, MT<:AbstractArray{T, 2}} <: AbstractArray{T, 2}

Represents a discrete linear operator (a matrix) that acts on a function space.

Similar to , this container bundles a raw matrix (data) with its parent space. This is used to represent discretization matrices from methods like finite differences (e.g., a differentiation or averaging matrix). Subtyping AbstractMatrix allows it to be used like a standard Julia matrix.

Fields

• data: the matrix data representing the linear operator.

• space: the parent function space to which this vector belongs.

MultiComponent{D} <: ComponentStyle

Indicates a function space for vector fields with D components per grid point.

This component style is used for vector-valued quantities such as velocity, displacement, or force fields, where each grid point stores D scalar values.

Type Parameter

• D::Int: Number of vector components (typically equal to spatial dimension)

Example

# Create a 2D vector space (e.g., for velocity field)
Wₕ = gridspace(Ωₕ)
Vₕ = CompositeGridSpace((Wₕ, Wₕ))  # 2-component vector space
ComponentStyle(typeof(Vₕ))  # Returns MultiComponent{2}()

uₕ = element(Vₕ)  # Vector has 2 * npoints(Ωₕ) entries

See also: ComponentStyle, SingleComponent, CompositeGridSpace

SingleComponent <: ComponentStyle

Indicates a function space for scalar fields (single component per grid point).

This is the component style for spaces representing scalar quantities such as temperature, pressure, or density, where each grid point has a single value.

Example

Wₕ = gridspace(Ωₕ)  # Creates a scalar grid space
ComponentStyle(typeof(Wₕ))  # Returns SingleComponent()

uₕ = element(Wₕ)  # Vector has npoints(Ωₕ) entries

See also: ComponentStyle, MultiComponent, ScalarGridSpace

struct VectorElement{S, T, VT<:AbstractArray{T, 1}} <: AbstractArray{T, 1}

Represents a grid function (a vector) that belongs to a specific function space.

This is a wrapper that bundles the raw numerical data (the vector data) with its parent space. The space provides the essential context, such as the underlying mesh and associated operators. By subtyping AbstractVector, a VectorElement can be used just like a regular Julia vector in most operations.

Fields

• data: the raw vector data containing the degrees of freedom.

• space: the parent function space to which this vector belongs.

eltype(Wₕ::AbstractSpaceType)

Returns the element type (e.g., Float64) of the data in the function space Wₕ. It also works if the argument is the type of the space.

average_matrix(Wₕ::AbstractSpaceType, i)

Returns the averaging matrix for the i-th dimension of the space Wₕ.

backend(Wₕ::Bramble.AbstractSpaceType) -> Any

Returns the computational backend associated with the space Wₕ.

backward_difference_matrix(Wₕ::AbstractSpaceType, i)

Returns the backward difference matrix for the i-th dimension of the space Wₕ.

has_average_matrix(Wₕ::AbstractSpaceType)

Checks if the averaging matrices have been computed and stored for Wₕ.

has_backward_difference_matrix(Wₕ::AbstractSpaceType)

Checks if the backward difference matrices have been computed and stored for Wₕ.

mesh_type(Wₕ::AbstractSpaceType)

Returns the type of the mesh associated with the function space Wₕ. Also works if the argument is the type of the space.

space(Wₕ::AbstractSpaceType)

Returns the function space Wₕ itself.

vector_buffer(Wₕ::AbstractSpaceType)

Returns the GridSpaceBuffer used for efficient memory management in the space Wₕ.

struct ScalarGridSpace{D, T, VT<:AbstractArray{T, 1}, MT<:AbstractArray{T, 2}, MType<:Bramble.AbstractMeshType{D}, BT<:Bramble.Backend{VT<:AbstractArray{T, 1}, MT<:AbstractArray{T, 2}}} <: Bramble.AbstractSpaceType{1}

Represents a function space for scalar fields defined on a mesh.

This structure is a cornerstone for numerical simulations, bundling a mesh with pre-computed weights for discrete inner products, lazy-initialized matrices for finite difference operators (like differentiation and averaging), and an efficient memory buffer for temporary vectors.

Fields

• mesh: the underlying mesh of the grid space.

• weights: a SpaceWeights object holding vectors for various discrete inner products.

• backward_difference_matrix: a tuple of matrices for the backward difference operator in each dimension.

• has_backward_difference_matrix: a flag indicating if the difference matrices have been computed and stored.

• average_matrix: a tuple of matrices for the averaging operator in each dimension.

• has_average_matrix: a flag indicating if the averaging matrices have been computed and stored.

• vector_buffer: a GridSpaceBuffer for efficient reuse of temporary vectors, minimizing memory allocations.

Discrete Inner Products

The weights object stores vectors for different discrete $L^2$ inner products on the space of grid functions. They are defined as follows:

- :innerₕ: The standard discrete $L^2$ inner product, weighted by the cell measure $|\square_k|$.

• 1D case:

\[(u_h, v_h)_h = \sum_{i=1}^{N_x} |\square_{i}| u_h(x_i) v_h(x_i)\]

• 2D case:

\[(u_h, v_h)_h = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y} |\square_{i,j}| u_h(x_i,y_j) v_h(x_i,y_j)\]

• 3D case:

\[(u_h, v_h)_h = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y}\sum_{l=1}^{N_z} |\square_{i,j,l}| u_h(x_i,y_j,z_l) v_h(x_i,y_j,z_l)\]

Here, $|\cdot|$ denotes the measure of the set (length, area, or volume). See cell_measure for details.

- :inner₊, :inner₊ₓ, :inner₊ᵧ, :inner₊₂: Modified discrete $L^2$ inner products, weighted by a mix of forward/backward spacings ($h_k$) and cell widths ($h_{k+1/2}$).

• 1D case (:inner₊):

\[(u_h, v_h)_+ = \sum_{i=1}^{N_x} h_{i} u_h(x_i) v_h(x_i)\]

• 2D case (:inner₊ₓ, :inner₊ᵧ):

\[(u_h, v_h)_{+x} = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y} h_{x,i} h_{y,j+1/2} u_h(x_i,y_j) v_h(x_i,y_j)\]

\[(u_h, v_h)_{+y} = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y} h_{x,i+1/2} h_{y,j} u_h(x_i,y_j) v_h(x_i,y_j)\]

• 3D case (:inner₊ₓ, :inner₊ᵧ, :inner₊₂):

\[(u_h, v_h)_{+x} = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y}\sum_{l=1}^{N_z} h_{x,i} h_{y,j+1/2} h_{z,l+1/2} u_h(x_i,y_j,z_l) v_h(x_i,y_j,z_l)\]

\[(u_h, v_h)_{+y} = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y}\sum_{l=1}^{N_z} h_{x,i+1/2} h_{y,j} h_{z,l+1/2} u_h(x_i,y_j,z_l) v_h(x_i,y_j,z_l)\]

\[(u_h, v_h)_{+z} = \sum_{i=1}^{N_x}\sum_{j=1}^{N_y}\sum_{l=1}^{N_z} h_{x,i+1/2} h_{y,j+1/2} h_{z,l} u_h(x_i,y_j,z_l) v_h(x_i,y_j,z_l)\]

struct SpaceWeights{D, VT<:(AbstractVector)}

A container that stores pre-computed weight vectors for various discrete inner products on a grid space.

This struct holds the diagonal elements (weights) needed to compute different types of inner products, such as those weighted by cell measures or staggered grid spacings. By pre-computing and storing these vectors, numerical simulations can avoid costly recalculations within iterative loops.

Fields

• innerh: weight vector for the standard discrete $L^2$ inner product (:innerₕ), based on cell measures ($|\square_k|$).

• innerplus: a tuple of weight vectors for modified, staggered inner products (:inner₊ₓ, :inner₊ᵧ, etc.), with one vector for each spatial dimension.

For a detailed explanation of the mathematical formulas corresponding to these weights, please refer to the documentation for ScalarGridSpace.

eltype(Wₕ::ScalarGridSpace)

Returns the element type of vectors in this space (e.g., Float64).

See also: backend

__innerplus_weights!(v, innerplus_per_component)

Builds the weights for the modified discrete $L^2$ inner product on the space of grid functions ScalarGridSpace. The result is stored in vector v.

_innerh_weights!(u, Ωₕ::AbstractMeshType)

Builds the weights for the standard discrete $L^2$ inner product, $inner_h(\cdot, \cdot)$, on the space of grid functions, following the order of the points provided by indices(Ωₕ). The values are stored in vector u.

_innerplus_mean_weights!(u::VT, Ωₕ, component::Int = 1) where VT

Builds a set of weights based on the half spacings, associated with the component-th direction, for the modified discrete $L^2$ inner product on the space of grid functions, following the order of the points. The values are stored in vector u. for each component.

_innerplus_weights!(u::VT, Ωₕ, component = 1) where VT

Builds a set of weights based on the spacings, associated with the component-th direction, for the modified discrete $L^2$ inner product on the space of grid functions, following the order of the points provided by indices(Ωₕ). The values are stored in vector u.

weights(Wₕ::ScalarGridSpace)
weights(Wₕ::ScalarGridSpace, ::InnerProductType)
weights(Wₕ::ScalarGridSpace, ::InnerProductType, i::Int)

Returns the pre-computed weight vectors for discrete inner products.

The weights are diagonal matrices (stored as vectors) used in computing discrete $L^2$ inner products. They represent cell measures or staggered grid spacings.

Methods

1. weights(Wₕ) - Returns the full SpaceWeights struct
2. weights(Wₕ, Innerh()) - Returns weights for standard $L^2$ inner product (cell volumes)
3. weights(Wₕ, Innerplus()) - Returns tuple of weights for modified inner products (all directions)
4. weights(Wₕ, Innerplus(), i) - Returns weights for modified inner product in direction i

Examples

Wₕ = gridspace(Ωₕ)

# Get all weights
w = weights(Wₕ)  # Returns SpaceWeights{D, VT}

# Get standard L² weights
w_h = weights(Wₕ, Innerh())  # Vector of cell volumes

# Get modified inner product weights for x-direction
w_plus_x = weights(Wₕ, Innerplus(), 1)  # Vector for x-direction

# Use in inner product
result = dot(uₕ.data, w_h, vₕ.data)  # Weighted inner product

See also: SpaceWeights, Innerh, Innerplus, innerₕ

mutable struct CompositeGridSpace{N, Spaces<:NTuple{N, Bramble.AbstractSpaceType}} <: Bramble.AbstractSpaceType{N}

A CompositeGridSpace represents a grid space that is formed by composing N individual sub-spaces.

Fields

• spaces

struct PointwiseEvaluator{F, M}

Helper struct to bundle a function with its mesh for pointwise evaluation.

This allows passing both a function and its mesh as a single callable object. When called with a grid index idx, it evaluates the function at the physical coordinates corresponding to that index.

Fields

• func: the function to evaluate at grid points

• mesh: the mesh providing the mapping from indices to physical coordinates

Callable Interface

A PointwiseEvaluator is callable:

pe = PointwiseEvaluator(f, Ωₕ)
value = pe(idx)  # Equivalent to f(point(Ωₕ, idx))

This abstraction is used internally by the restriction operator Rₕ to evaluate continuous functions at discrete grid points.

Example

# Define a function in physical coordinates
f(x) = sin(x[1]) * cos(x[2])

# Create evaluator
pe = PointwiseEvaluator(f, Ωₕ)

# Evaluate at grid point (i, j)
value = pe(CartesianIndex(i, j))  # Computes f([xᵢ, yⱼ])

See also: Rₕ, Rₕ!, point

(pe::PointwiseEvaluator)(idx)

Evaluate the function at the physical coordinates of grid index idx.

Arguments

• idx: Grid index (e.g., CartesianIndex(i, j))

Returns

The function value at the physical point corresponding to idx.

Example

pe = PointwiseEvaluator(f, Ωₕ)
value = pe(CartesianIndex(5, 10))  # Evaluates f at physical point (x₅, y₁₀)

__integrand1d(y, t, p)

Implements the integrand function needed in the calculation of the averaging operator avgₕ. In this function, y denotes the return values, t denotes the integration variable and p denotes the parameters (integrand function f, points x, spacing h and indices idxs).

For efficiency, each integral in avgₕ is rewritten as an integral over [0,1] following

\[\int_{a}^{b} f(x) dx = (b-a) \int_{0}^{1} f(a + t (b-a)) dt\]

__integrandnd(y, t, p)

Implements the integrand function needed in the calculation of avgₕ. In this function, y denotes the return values, t denotes the integration variable and p denotes the parameters (integrand function f, points x, measures meas and indices idxs).

For efficiency, each integral is calculated on $[0,1]^D$, where $D$ is the dimension of the integration domain. This is done through a similar change of variable as in __integrand1d(y, t, p).

_find_vec_in_broadcast(bc)

Internal helper to extract a VectorElement from a broadcast expression.

Recursively searches through the arguments of a broadcast expression tree to find a VectorElement instance. This is used by the broadcasting machinery to determine which function space should be used for the result.

Arguments

• bc: A broadcast expression, tuple of arguments, or individual value

Returns

• The first VectorElement found in the expression tree
• nothing if no VectorElement is found

Implementation Notes

Uses multiple dispatch to handle:

• Broadcasted objects: Extract and search arguments
• Tuples: Recursively search each element
• VectorElement: Return immediately (found!)
• Other types: Return nothing and continue searching

This enables broadcasts like uₕ .+ vₕ .* 2 to automatically preserve the space information.

func(pe::PointwiseEvaluator)

Returns the function stored in the PointwiseEvaluator.

space(uₕ::VectorElement)

Returns the grid space associated with VectorElement uₕ.

to_matrix(uₕ::VectorElement, [::ComponentStyle])

Reshapes the flat coefficient vector of uₕ into a multidimensional array that matches the logical layout of the grid points.

• For a SingleComponent space, this returns a D-dimensional array.
• For a MultiComponent space, it returns a tuple of D arrays, one for each component.

values!(uₕ::VectorElement, s)

Copies the values of s into the coefficients of VectorElement uₕ.

values(uₕ::VectorElement)

Returns the coefficients of the VectorElement uₕ.

VecOrMatElem{S,T}

Type alias for a union of VectorElement and MatrixElement.

This is used in function signatures that accept either vectors or matrices from the same function space, particularly in inner product calculations.

Type Parameters

• S: The space type (e.g., ScalarGridSpace{...})
• T: The element type (e.g., Float64)

Example

# This function accepts either VectorElement or MatrixElement
function my_inner_product(uₕ::VecOrMatElem, vₕ::VecOrMatElem)
	# ... implementation ...
end

See also: VectorElement, MatrixElement, innerₕ

*(Uₕ::MatrixElement, Vₕ::MatrixElement)

Returns a new MatrixElement given by multiplying the matrix of MatrixElement Uₕ by the matrix of MatrixElement Vₕ.

Base.:*(Uₕ::MatrixElement, vₕ::VectorElement)

Returns a new MatrixElement calculated by multiplying each coefficient of VectorElement vₕ with the corresponding column of Uₕ.

*(Uₕ::MatrixElement, α::Number)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of Uₕ * α.

Base.:*(uₕ::VectorElement, Vₕ::MatrixElement)

Returns a new MatrixElement calculated by multiplying each coefficient of VectorElement uₕ with the corresponding row of Vₕ.

*(α::Number, Uₕ::MatrixElement)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of α * Uₕ.

+(Uₕ::MatrixElement, Vₕ::MatrixElement)

Returns a new MatrixElement given by adding the matrix of MatrixElement Uₕ to the matrix of MatrixElement Vₕ.

+(Uₕ::MatrixElement, α::Number)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of Uₕ + α.

+(α::Number, Uₕ::MatrixElement)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of α + Uₕ.

-(Uₕ::MatrixElement, Vₕ::MatrixElement)

Returns a new MatrixElement given by subtracting the matrix of MatrixElement Vₕ to the matrix of MatrixElement Uₕ.

-(Uₕ::MatrixElement, α::Number)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of Uₕ - α.

-(α::Number, Uₕ::MatrixElement)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of α - Uₕ.

/(Uₕ::MatrixElement, α::Number)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of Uₕ / α.

/(α::Number, Uₕ::MatrixElement)

Returns a new MatrixElement with coefficients given by the elementwise evaluation of α / Uₕ.

Base.copyto!(Uₕ::MatrixElement, Vₕ::MatrixElement)

Copies the coefficients of MatrixElement Vₕ into MatrixElement Uₕ.

eltype(Uₕ::MatrixElement{S,T})

Returns the element type of a MatrixElement, T. CAn be applied to the type of the MatrixElement.

Base.similar(Uₕ::MatrixElement)

Returns a similar MatrixElement to Uₕ.

elements(Wₕ::AbstractSpaceType, [A::AbstractMatrix])

Returns a MatrixElement from a given AbstractSpaceType, initialized with the identity matrix. If matrix A is provided, it is used instead.

space(Uₕ::MatrixElement)

Returns the space associated with the MatrixElement Uₕ.

⊗(A, B)

Kronecker product operator (alias for kron).

Computes the Kronecker product (tensor product) of matrices A and B. This operator is used extensively in constructing multidimensional shift operators.

Example

I₂ = Eye(2)
I₃ = Eye(3)
result = I₂ ⊗ I₃  # 6×6 identity matrix

See also: shift

_Eye(::Type{MType}, npts, ::Val{i})

Internal helper to create identity or shifted diagonal matrices.

Creates either an identity matrix (i=0) or a matrix with ones on the i-th diagonal. The Val{i} allows compile-time specialization for the diagonal offset.

Arguments

• MType: Matrix type to construct
• npts::Int: Size of the square matrix
• ::Val{i}: Diagonal offset (0 = main diagonal, 1 = superdiagonal, -1 = subdiagonal)

Returns

• For i=0: Identity matrix of size npts × npts
• For i≠0: Matrix with ones on the i-th diagonal, zeros elsewhere

Example

_Eye(Matrix{Float64}, 5, Val(0))   # 5×5 identity
_Eye(Matrix{Float64}, 5, Val(1))   # 5×5 with ones on superdiagonal
_Eye(Matrix{Float64}, 5, Val(-1))  # 5×5 with ones on subdiagonal

See also: shift

shift(Ωₕ, ::Val{SHIFT_DIM}, ::Val{i})

Creates a shift operator on a D-dimensional mesh.

• SHIFT_DIM: The dimension along which to apply the shift (e.g., 1 for x, 2 for y).
• i: The shift amount (e.g., -1 for a backward shift).

backward_derivative_weights!(v::AbstractVector, Ωₕ::AbstractMeshType, diff_dim::Val)

Computes the geometric weights for the backward finite difference operator and stores them in-place in vector v.

backward_difference(arg, dim_val::Val)

Constructs the unscaled backward difference operator, representing the operation $u_{i} - u_{i-1}$.

backward_difference_dim!(out, in, [h], dims, diff_dim)

Low-level, in-place function to compute the unscaled backward difference of vector in along dimension diff_dim, storing the result in out. This function computes $u_{i} - u_{i-1}$.

backward_finite_difference(arg, dim_val::Val)

Constructs the backward finite difference operator, which approximates the first derivative using the formula $\frac{u_{i} - u_{i-1}}{h_i}$.

forward_derivative_weights!(v::AbstractVector, Ωₕ::AbstractMeshType, diff_dim::Val)

Computes the geometric weights for the forward finite difference operator and stores them in-place in vector v.

forward_difference(arg, dim_val::Val)

Constructs the unscaled forward difference operator, representing the operation $u_{i+1} - u_i$.

forward_difference_dim!(out, in, [h], dims, diff_dim)

Low-level, in-place function to compute the unscaled forward difference of vector in along dimension diff_dim, storing the result in out. This function computes $u_{i+1} - u_i$.

forward_finite_difference(arg, dim_val::Val)

Constructs the forward finite difference operator, which approximates the first derivative using the formula $\frac{u_{i+1} - u_i}{h_i}$.

backward_jump(arg, dim_val::Val)

Constructs or applies the backward jump operator, representing the operation $u_{i} - u_{i-1}$.

backward_jump_dim!(out, in, dims, jump_dim)

Low-level, in-place function to compute the backward jump of vector in along dimension jump_dim, storing the result in out. This function computes $u_{i} - u_{i-1}$.

forward_jump(arg, dim_val::Val)

Constructs or applies the forward jump operator, representing the operation $u_{i+1} - u_i$.

forward_jump_dim!(out, in, dims, jump_dim)

Low-level, in-place function to compute the forward jump of vector in along dimension jump_dim, storing the result in out. This function computes $u_{i+1} - u_i$.

backward_average(arg, dim_val::Val)

Constructs or applies the backward averaging operator, representing the operation $\frac{u_{i-1} + u_{i}}{2}$.

backward_average_dim!(out, in, dims, average_dim)

Low-level, in-place function to compute the backward average of vector in along dimension average_dim, storing the result in out. This function computes $\frac{u_{i-1} + u_{i}}{2}$.

forward_average(arg, dim_val::Val)

Constructs or applies the forward averaging operator, representing the operation $\frac{u_{i} + u_{i+1}}{2}$.

forward_average_dim!(out, in, dims, average_dim)

Low-level, in-place function to compute the forward average of vector in along dimension average_dim, storing the result in out. This function computes $\frac{u_{i} + u_{i+1}}{2}$.

AddOperator{OP1,OP2,S} <: OperatorType

Represents the sum or difference of two operators: op₁ ± op₂.

This operator type enables algebraic manipulation of operator expressions, storing the operation as op₁ + scalar*op₂ where scalar ∈ {-1, 1}.

Fields

• space::S: The grid space on which the operators act
• operator1::OP1: The first operator
• operator2::OP2: The second operator
• scalar::Int: Sign indicator (+1 for addition, -1 for subtraction)

Constructor

Created automatically through + and - operations:

op_sum = op₁ + op₂
op_diff = op₁ - op₂

Properties

• Both operators must have the same codomain type
• first(op) returns the first operator
• second(op) returns the second operator
• scalar(op) returns +1 or -1

Algebraic simplification

• op + ZeroOperator returns op
• ZeroOperator + op returns op
• op - ZeroOperator returns op
• ZeroOperator - op returns -1 * op

GradientOperator{S} <: OperatorType

Represents the discrete gradient operator ∇ₕ acting on grid space elements.

The gradient operator computes spatial derivatives using backward difference matrices. For multi-dimensional problems, it produces a vector of partial derivatives.

Fields

• space::S: The grid space on which the operator acts

Constructor

GradientOperator(space)

Type Alias

ScaledGradientOperator{S,V} = ScaledOperator{GradientOperator{S},S,V}

Properties

• scalar(∇) returns one
• codomaintype(∇) returns the element type of the space
• Works with inner₊ for proper integration

Examples

Wh = gridspace(mesh)
∇ = GradientOperator(Wh)
uₕ = element(Wh)

# Use in bilinear form for Laplacian
a(u, v) = inner₊(∇₋ₕ(u), ∇₋ₕ(v))

IdentityOperator

Represents the identity operator I that maps each element to itself.

The identity operator is the neutral element for operator composition and serves as the base case for many operator algebraic simplifications.

Fields

• space::S: The grid space on which the operator acts

Constructor

IdentityOperator(space)

Properties

• scalar(I) returns one (multiplicative identity)
• α * I creates a ScaledOperator with coefficient α
• I * α is equivalent to α * I

Examples

Wh = gridspace(mesh)
I = IdentityOperator(Wh)
op = 3.5 * I         # Scaled identity
uₕ = element(Wh)
result = innerₕ(uₕ, I)  # Identity in inner product

OperatorType

Abstract base type for all operators acting on finite element spaces.

Operators represent linear transformations on grid space elements, supporting:

• Scalar multiplication
• Addition and subtraction
• Composition
• Inner product operations

Subtypes

• ScalarOperatorType: Operators with scalar codomain
• VectorOperatorType: Operators with vector codomain

Interface

All operator types must implement:

• space(op): Return the underlying grid space
• show(io, op): Display representation

ScalarOperatorType <: OperatorType

Abstract type for operators with scalar-valued codomain.

ScaledGradientOperator{S,V}

Type alias for a scaled gradient operator α * ∇ₕ.

ScaledOperator(S::AbstractSpaceType, α, op = IdentityOperator(S))

Construct a scaled operator α * op with algebraic simplification.

Arguments

• S::AbstractSpaceType: The grid space
• α: Scalar coefficient (Number or VectorElement)
• op: Operator to scale (defaults to IdentityOperator(S))

Returns

• op if α == 1 (identity property)
• ZeroOperator(S) if α == 0 (annihilation property)
• ScaledOperator{...} otherwise

Examples

op1 = ScaledOperator(Wh, 2.5)           # 2.5 * I
op2 = ScaledOperator(Wh, 1, D₋ₓ)        # D₋ₓ (unchanged)
op3 = ScaledOperator(Wh, 0, any_op)     # ZeroOperator

ScaledOperator{OP,S,V} <: OperatorType

Represents a scaled operator α * Op, where α is a scalar coefficient.

The scalar is stored as a FunctionWrapper for efficient evaluation and type stability. Scaled operators support nested composition and algebraic simplification.

Fields

• space::S: The grid space on which the operator acts
• scalar::V: Function wrapper containing the scalar coefficient
• operator::OP: The underlying operator being scaled

Constructor

ScaledOperator(space, α, operator)

Properties

• scalar(op) evaluates and returns the scalar coefficient
• parent_operator(op) returns the underlying operator
• codomaintype(op) returns the codomain type of the scalar

Algebraic simplification

• ScaledOperator(S, 0, op) returns ZeroOperator(S)
• ScaledOperator(S, 1, op) returns op unchanged
• α * (β * op) combines to (α*β) * op

Examples

I = IdentityOperator(Wh)
op1 = ScaledOperator(Wh, 2.5, I)    # 2.5 * I
op2 = 3 * op1                         # (3 * 2.5) * I = 7.5 * I

ScaledOperator(S::AbstractSpaceType, α, op::ZeroOperator)

Scaling a zero operator always returns the zero operator (absorbing property).

VectorOperator{S,CompType} <: OperatorType

Represents a vector-valued operator as a tuple of component operators.

This allows construction of operators acting on product spaces S × S × ... × S, where each component space has its own operator.

Fields

• space::S: The underlying grid space
• component_operators::CompType: Tuple of operators for each component

VectorOperatorType <: OperatorType

Abstract type for operators with vector-valued codomain.

ZeroOperator{S} <: OperatorType

Represents the zero operator 0 that maps all elements to zero.

This operator absorbs all scalar multiplication and addition operations, providing algebraic simplification in operator expressions.

Fields

• space::S: The grid space on which the operator acts

Constructor

ZeroOperator(space)

Properties

• scalar(op) returns zero
• α * ZeroOperator returns ZeroOperator for any α
• op + ZeroOperator returns op for any operator op

*(α, op::OperatorType) -> OperatorType

Scale an operator by a scalar or vector coefficient α.

Arguments

• α: Scalar (Number) or vector (VectorElement) coefficient
• op: Operator to scale

Returns

• ZeroOperator if α == 0
• op unchanged if α == 1
• ScaledOperator{...} containing the scaled operator

Examples

I = IdentityOperator(Wh)
op = 2.5 * I      # Scaled identity
op = uₕ * I       # Element-wise scaling

first(op::AddOperator)

Return the first operator in the sum/difference.

_process_scalar(f::FunctionWrapper) -> String

Convert a scalar function wrapper to its string representation for display purposes.

Used by operator show methods to format scalar coefficients in expressions.

_scalar2wrapper(::Type{T}, α) -> FunctionWrapper

Convert a scalar value α to a FunctionWrapper with return type T.

This enables efficient storage and evaluation of scalar coefficients in operators. Handles numbers, tuples, and VectorElement types.

Arguments

• T: Target return type
• α: Scalar value to wrap (Number, Tuple, or VectorElement)

Returns

• FunctionWrapper{T,Tuple{}}: Zero-argument function wrapper returning the scalar

inner₊!(vₕ::AbstractVector, uₕ::VectorElement, l::GradientOperator)

In-place version of gradient inner product.

Accumulates the result into vₕ, summing contributions from all spatial dimensions.

inner₊!(vₕ::AbstractVector, uₕ::VectorElement, ::IdentityOperator)

In-place version: vₕ .+= w₊ .* uₕ.values

inner₊!(vₕ::AbstractVector, uₕ::VectorElement, l::ScaledOperator)

In-place version: vₕ .+= w₊ .* α .* uₕ.values

Uses fused multiply-add for efficiency.

inner₊!(vₕ::AbstractVector, uₕ::NTuple{D,VectorElement}, l::GradientOperator)

In-place version for tuple of vector elements.

Each component uₕ[i] contributes to the result through its corresponding dimension's difference matrix and weights.

innerₕ!(vₕ::AbstractVector, uₕ::VectorElement, ::IdentityOperator)

In-place version: vₕ .+= wₕ .* uₕ.values

innerₕ!(vₕ::AbstractVector, uₕ::VectorElement, l::ScaledOperator)

In-place version: vₕ .+= wₕ .* α .* uₕ.values

parent_operator(op::ScaledOperator)

Return the underlying operator being scaled.

scalar(op::AddOperator)

Return the sign of the second operator (+1 for addition, -1 for subtraction).

scalar(op::IdentityOperator)

Return the scalar representation of the identity operator (one).

scalar(op::ScaledOperator)

Evaluate and return the scalar coefficient of the scaled operator.

scalar(op::ZeroOperator)

Return the scalar representation of the zero operator (zero of the space element type).

second(op::AddOperator)

Return the second operator in the sum/difference.

space(op::OperatorType) -> AbstractSpaceType

Return the grid space on which the operator op acts.