Spaces

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.

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).

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.

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.

__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, [::InnerProductType], [i])

Returns the weights associated with the functionspace. A second argument can be supplied detailing the type of weights.

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. This allows passing both as a single callable object, pe(idx), which evaluates the function at the physical coordinates corresponding to the grid index idx.

Fields

• func

• mesh

__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).

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ₕ.

*(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ₕ.

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}$.