Assemblers

This section describes the assemblers that are currently available and their abstract interface.

All assemblers must possess at minimum a DofManager.

The assemblers possess all the baggage to use the internal method sparse! in SparseArrays.jl. This method allows for a zero allocation instantiation of a SparseMatrixCSC type on the CPU. There are also methods available to ease in the conversion of CSC types and other sparse types such as CSR.

On the GPU, however, this type is first converted to an appropriate COO matrix type on the desired backend. There is unfortunately not a unified sparse matrix API in julia for GPUs, so we implement this functionality in package extensions. On CUDA, for example, the operational sequence to get a CuSparseMatrixCSC is to first sort the COO (row, col, val) triplets so they are ordered by row and then column. Then a CuSparseMatrixCOO type is created and converted to a CuSparseMatrixCSC type via CUDA.jl methods. An identical approach is taken for RocM types.

NOTE: This is one of the most actively developed areas of the package. Please use caution with any method beginning with a "_" as these are internal methods that will change without notice.

Matrices

FiniteElementContainers.assemble_matrix! — Method

assemble_matrix!(
    storage,
    pattern,
    dof,
    func::Function,
    Uu,
    p
)

Note this is hard coded to storing the assembled sparse matrix in the stiffness_storage field of assembler.

Matrix Action

FiniteElementContainers._assemble_block_matrix_action! — Method

_assemble_block_matrix_action!(
    backend::KernelAbstractions.Backend,
    field::FiniteElementContainers.AbstractField,
    conns::AbstractArray,
    nelem,
    coffset,
    b1,
    b2,
    func::Function,
    physics::AbstractPhysics,
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    X::FiniteElementContainers.AbstractField,
    t::Number,
    Δt::Number,
    U::FiniteElementContainers.AbstractField,
    U_old::FiniteElementContainers.AbstractField,
    V::FiniteElementContainers.AbstractField,
    state_old,
    state_new,
    props::AbstractArray,
    return_type
)

Assembly method for a block labelled as block_id. This is a GPU agnostic implementation using KernelAbstractions and Atomix for eliminating race conditions

TODO add state variables and physics properties

FiniteElementContainers._assemble_block_matrix_action! — Method

_assemble_block_matrix_action!(
    _::KernelAbstractions.CPU,
    field::FiniteElementContainers.AbstractField,
    conns::AbstractArray,
    nelem,
    coffset,
    b1,
    b2,
    func::Function,
    physics::AbstractPhysics,
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    X::FiniteElementContainers.AbstractField,
    t::Number,
    Δt::Number,
    U::FiniteElementContainers.AbstractField,
    U_old::FiniteElementContainers.AbstractField,
    V::FiniteElementContainers.AbstractField,
    state_old,
    state_new,
    props::AbstractArray,
    return_type
)

Assembly method for a block labelled as block_id. This is a CPU implementation with no threading.

TODO improve typing of fields to ensure they mathc up in terms of function spaces

FiniteElementContainers._assemble_block_matrix_free_action! — Method

_assemble_block_matrix_free_action!(
    backend::KernelAbstractions.Backend,
    field::FiniteElementContainers.AbstractField,
    conns::AbstractArray,
    nelem,
    coffset,
    b1,
    b2,
    func_action::Function,
    physics::AbstractPhysics,
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    X::FiniteElementContainers.AbstractField,
    t::Number,
    Δt::Number,
    U::FiniteElementContainers.AbstractField,
    U_old::FiniteElementContainers.AbstractField,
    V::FiniteElementContainers.AbstractField,
    state_old,
    state_new,
    props::AbstractArray,
    return_type
)

GPU dispatch for matrix-free action assembly.

FiniteElementContainers._assemble_block_matrix_free_action! — Method

_assemble_block_matrix_free_action!(
    _::KernelAbstractions.CPU,
    field::FiniteElementContainers.AbstractField,
    conns::AbstractArray,
    nelem,
    coffset,
    b1,
    b2,
    func_action::Function,
    physics::AbstractPhysics,
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    X::FiniteElementContainers.AbstractField,
    t::Number,
    Δt::Number,
    U::FiniteElementContainers.AbstractField,
    U_old::FiniteElementContainers.AbstractField,
    V::FiniteElementContainers.AbstractField,
    state_old,
    state_new,
    props::AbstractArray,
    return_type
)

CPU matrix-free action: accumulates Kq·vel per quadrature point into a vector, avoiding the full element stiffness matrix.

FiniteElementContainers._assemble_block_matrix_free_action_kernel! — Method

_assemble_block_matrix_free_action_kernel!(
    dev
) -> Union{KernelAbstractions.Kernel{KernelAbstractions.CPU, KernelAbstractions.NDIteration.DynamicSize, KernelAbstractions.NDIteration.DynamicSize, typeof(FiniteElementContainers.cpu__assemble_block_matrix_free_action_kernel!)}, KernelAbstractions.Kernel{Backend, KernelAbstractions.NDIteration.DynamicSize, KernelAbstractions.NDIteration.DynamicSize, typeof(FiniteElementContainers.gpu__assemble_block_matrix_free_action_kernel!)} where Backend<:KernelAbstractions.GPU}

GPU kernel for matrix-free action assembly. Accumulates Kq·vel into a vector per element, avoiding the 24×24 element matrix that causes register spilling on GPU.

FiniteElementContainers.assemble_matrix_action! — Method

assemble_matrix_action!(storage, dof, func, Uu, Vu, p)

FiniteElementContainers.assemble_matrix_action! — Method

assemble_matrix_action!(
    assembler,
    func::Function,
    Uu,
    Vu,
    p
)

FiniteElementContainers.assemble_matrix_free_action! — Method

assemble_matrix_free_action!(
    storage,
    dof,
    func_action,
    Uu,
    Vu,
    p
)

FiniteElementContainers.assemble_matrix_free_action! — Method

assemble_matrix_free_action!(
    assembler,
    func_action::Function,
    Uu,
    Vu,
    p
)

Matrix-free action assembly. func_action has signature funcaction(physics, interps, xel, t, Δt, uel, uelold, vel, stateoldq, statenewq, propsel) → SVector and returns the element-level product Kq·v_el directly, avoiding formation of the full element stiffness/mass matrix.

Matrix Action

FiniteElementContainers._assemble_block_vector_neumann_bc! — Method

_assemble_block_vector_neumann_bc!(
    backend::KernelAbstractions.Backend,
    field::FiniteElementContainers.AbstractField,
    U::FiniteElementContainers.AbstractField,
    X::FiniteElementContainers.AbstractField,
    conns,
    ref_fe,
    sides,
    vals,
    nelem
)

FiniteElementContainers._assemble_block_vector_neumann_bc! — Method

_assemble_block_vector_neumann_bc!(
    _::KernelAbstractions.CPU,
    field::FiniteElementContainers.AbstractField,
    U::FiniteElementContainers.AbstractField,
    X::FiniteElementContainers.AbstractField,
    conns,
    ref_fe,
    sides,
    vals,
    nelem
)

FiniteElementContainers.assemble_vector_neumann_bc! — Method

assemble_vector_neumann_bc!(storage, dof, Uu, p)

FiniteElementContainers.assemble_vector_neumann_bc! — Method

assemble_vector_neumann_bc!(assembler, Uu, p)

Scalar

FiniteElementContainers.assemble_quadrature_quantity! — Method

assemble_quadrature_quantity!(
    storage,
    pattern,
    dof,
    func::Function,
    Uu,
    p
)
assemble_quadrature_quantity!(
    storage,
    pattern,
    dof,
    func::Function,
    Uu,
    p,
    return_type
)

FiniteElementContainers.assemble_scalar! — Method

assemble_scalar!(assembler, func::Function, Uu, p)

Vector

FiniteElementContainers.assemble_vector! — Method

assemble_vector!(
    storage,
    pattern,
    dof,
    func::Function,
    Uu,
    p
)

FiniteElementContainers.assemble_vector! — Method

assemble_vector!(assembler, func::Function, Uu, p)

Abstract Interface

FiniteElementContainers.AbstractAssembler — Type

abstract type AbstractAssembler{Dof<:DofManager}

FiniteElementContainers._assemble_block! — Method

_assemble_block!(
    _::KernelAbstractions.CPU,
    field,
    conns::AbstractArray,
    nelem::Int64,
    coffset::Int64,
    block_start_index::Int64,
    block_el_level_size::Int64,
    func::Function,
    physics::AbstractPhysics,
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    X::FiniteElementContainers.AbstractField,
    t::Number,
    dt::Number,
    U::FiniteElementContainers.AbstractField,
    U_old::FiniteElementContainers.AbstractField,
    state_old,
    state_new,
    props::AbstractArray,
    return_type::FiniteElementContainers.AssembledReturnType
)

Assembly method for a block labelled as block_id. This is a CPU implementation with no threading.

TODO add state variables and physics properties

FiniteElementContainers._assemble_element! — Method

_assemble_element!(
    storage,
    K_el::StaticArraysCore.SMatrix,
    conns,
    el_id::Int64,
    block_start_index::Int64,
    block_el_level_size::Int64
)

Specialization of of _assemble_element! for SparseMatrixAssembler.

FiniteElementContainers._cell_interpolants — Method

_cell_interpolants(
    ref_fe::ReferenceFiniteElements.ReferenceFE,
    q::Int64
) -> Any

FiniteElementContainers._element_level_fields — Method

_element_level_fields(
    U::H1Field{T, D, NF},
    ref_fe,
    conns,
    e
) -> Any

FiniteElementContainers._element_level_fields_flat — Method

_element_level_fields_flat(
    U::H1Field{T, D, NF},
    ref_fe,
    conns,
    e
) -> Any

FiniteElementContainers._element_level_properties — Method

_element_level_properties(
    props::AbstractArray,
    _::Int64
) -> StaticArraysCore.SVector

FiniteElementContainers._element_level_properties — Method

_element_level_properties(
    props::StaticArraysCore.SArray{Tuple{NP}, T, 1, NP},
    _::Int64
) -> StaticArraysCore.SVector

FiniteElementContainers._element_scratch — Method

_element_scratch(
    _::FiniteElementContainers.AssembledScalar,
    ref_fe,
    U
) -> Any

FiniteElementContainers._element_scratch — Method

_element_scratch(
    _::FiniteElementContainers.AssembledStruct,
    ref_fe,
    U
)

FiniteElementContainers._element_scratch — Method

_element_scratch(
    _::FiniteElementContainers.AssembledMatrix,
    ref_fe,
    U::H1Field{T, D, NF}
) -> Any

FiniteElementContainers._element_scratch — Method

_element_scratch(
    _::FiniteElementContainers.AssembledVector,
    ref_fe,
    U::H1Field{T, D, NF}
) -> Any

FiniteElementContainers._element_scratch_matrix — Method

_element_scratch_matrix(ref_fe, U::H1Field{T, D, NF}) -> Any

FiniteElementContainers._element_scratch_vector — Method

_element_scratch_vector(ref_fe, U::H1Field{T, D, NF}) -> Any

FiniteElementContainers._quadrature_level_state — Method

_quadrature_level_state(
    state::AbstractArray{<:Number, 3},
    q::Int64,
    e::Int64
) -> Any

FiniteElementContainers.hessian — Method

hessian(
    asm::FiniteElementContainers.AbstractAssembler
) -> SparseArrays.SparseMatrixCSC{Float64, Int64}

FiniteElementContainers.hvp — Method

hvp(
    asm::FiniteElementContainers.AbstractAssembler,
    v
) -> Any

FiniteElementContainers.mass — Method

mass(
    assembler::FiniteElementContainers.AbstractAssembler
) -> SparseArrays.SparseMatrixCSC{Float64, Int64}

FiniteElementContainers.residual — Method

residual(
    asm::FiniteElementContainers.AbstractAssembler;
    use_sparse_vector
) -> Any

assumes assemble_vector! has already been called

FiniteElementContainers.stiffness — Method

stiffness(
    assembler::FiniteElementContainers.AbstractAssembler
) -> SparseArrays.SparseMatrixCSC{Float64, Int64}

KernelAbstractions.get_backend — Method

get_backend(
    asm::FiniteElementContainers.AbstractAssembler
) -> Any

SparseMatrixAssembler

FiniteElementContainers.SparseMatrixAssembler — Type

struct SparseMatrixAssembler{Condensed, NumArrDims, IV<:AbstractVector{Int64}, RV<:AbstractVector{Float64}, Var<:FiniteElementContainers.AbstractFunction, FieldStorage<:FiniteElementContainers.AbstractField{Float64, NumArrDims, RV<:AbstractVector{Float64}}, QuadratureStorage<:NamedTuple} <: FiniteElementContainers.AbstractAssembler{DofManager{Condensed, Int64, IV<:AbstractVector{Int64}, Var<:FiniteElementContainers.AbstractFunction}}

General sparse matrix assembler that can handle first or second order problems in time.

FiniteElementContainers.SparseMatrixAssembler — Method

SparseMatrixAssembler(
    dof::DofManager
) -> SparseMatrixAssembler{_A, _B, Vector{Int64}, Vector{Float64}, Var, _C, QuadratureStorage} where {_A, _B, Var<:FiniteElementContainers.AbstractFunction, _C<:FiniteElementContainers.AbstractField{Float64, _B, Vector{Float64}}, QuadratureStorage<:(NamedTuple{_A, Tuple{Vararg{Matrix{Float64}, N}}} where {_A, N})}

Construct a SparseMatrixAssembler for a specific field type, e.g. H1Field. Can be used to create block arrays for mixed FEM problems.

SparsityPattern