GitHub

Assembly

The assembler handles the insertion of the element matrices and element vectors into the system matrix and right hand side.

Custom matrix formats

While the CSC and CSR formats are the most common sparse matrix formats in practice, users might want to have optimized custom matrix formats for their specific use-case. The default assemblers Ferrite.CSCAssembler and Ferrite.CSRAssembler should be able to handle most cases in practice. To support a custom format users have to dispatch the following functions on their matrix type. There is the public interface

Ferrite.allocate_matrix — Function
allocate_matrix(::Type{SparseMatrixCSC{Tv, Ti}}, sp::SparsityPattern)

Allocate a sparse matrix of type SparseMatrixCSC{Tv, Ti} from the sparsity pattern sp.

source
allocate_matrix(::Type{Symmetric{Tv, SparseMatrixCSC{Tv, Ti}}}, sp::SparsityPattern)

Instantiate a sparse matrix of type Symmetric{Tv, SparseMatrixCSC{Tv, Ti}}, i.e. a LinearAlgebra.Symmetric-wrapped SparseMatrixCSC, from the sparsity pattern sp. The resulting matrix will only store entries above, and including, the diagonal.

source
allocate_matrix(sp::SparsityPattern)

Allocate a sparse matrix of type SparseMatrixCSC{Float64, Int} from the sparsity pattern sp.

This method is a shorthand for the equivalent allocate_matrix(SparseMatrixCSC{Float64, Int}, sp).

source
allocate_matrix(MatrixType, dh::DofHandler, args...; kwargs...)

Allocate a matrix of type MatrixType from the DofHandler dh.

This is a convenience method and is equivalent to:

julia sp = init_sparsity_pattern(dh) add_sparsity_entries!(sp, dh, args...; kwargs...) allocate_matrix(MatrixType, sp)`

Refer to allocate_matrix for supported matrix types, and to init_sparsity_pattern for details about supported arguments args and keyword arguments kwargs.

Note

If more than one sparse matrix is needed (e.g. a stiffness and a mass matrix) it is more efficient to explicitly create the sparsity pattern instead of using this method, i.e. use

sp = init_sparsity_pattern(dh)
add_sparsity_entries!(sp, dh)
K = allocate_matrix(sp)
M = allocate_matrix(sp)

instead of

K = allocate_matrix(dh)
M = allocate_matrix(dh)

Note that for some matrix types it is possible to copy the instantiated matrix (M = copy(K)) instead.

source
allocate_matrix(dh::DofHandler, args...; kwargs...)

Allocate a matrix of type SparseMatrixCSC{Float64, Int} from the DofHandler dh.

This method is a shorthand for the equivalent allocate_matrix(SparseMatrixCSC{Float64, Int}, dh, args...; kwargs...) – refer to that method for details.

source
allocate_matrix(::Type{BlockMatrix}, sp::BlockSparsityPattern)
allocate_matrix(::Type{BlockMatrix{T, Matrix{S}}}, sp::BlockSparsityPattern)

Instantiate a blocked sparse matrix from the blocked sparsity pattern sp.

The type of the returned matrix is a BlockMatrix with blocks of type S (defaults to SparseMatrixCSC{T, Int}).

Examples

# Create a sparse matrix with default block type
allocate_matrix(BlockMatrix, sparsity_pattern)

# Create a sparse matrix with blocks of type SparseMatrixCSC{Float32, Int}
allocate_matrix(BlockMatrix{Float32, Matrix{SparseMatrixCSC{Float32, Int}}}, sparsity_pattern)
Package extension

This functionality is only enabled when the package BlockArrays.jl is installed (pkg> add BlockArrays) and loaded (using BlockArrays) in the session.

source

the internal interface

Ferrite.zero_out_rows! — Function
zero_out_rows!(K::AbstractMatrix, ch::ConstraintHandler)

Set the values of all rows associated with constrained dofs to zero.

source
Ferrite.zero_out_columns! — Function
zero_out_columns!(K::AbstractMatrix, ch::ConstraintHandler)

Set the values of all columns associated with constrained dofs to zero.

source
Ferrite._condense! — Function
_condense!(K::AbstractSparseMatrix, f::AbstractVector, dofcoefficients::Vector{Union{Nothing, DofCoefficients{T}}}, dofmapping::Dict{Int, Int}, sym::Bool = false)

Condenses affine constraints K := C'KC and f := C'*f in-place, assuming the sparsity pattern is correct.

source

and the AbstractSparseMatrix interface for their custom matrix type. Optional dispatches to speed up operations might be

Ferrite.add_inhomogeneities! — Function
add_inhomogeneities!(f::AbstractVector, K::AbstractMatrix, ch::ConstraintHandler)

Compute "f -= K*inhomogeneities". By default this is a generic version via SpMSpV kernel.

source

Custom Assembler

In case the default assembler is insufficient, users can implement a custom assemblers. For this, they can create a custom type and dispatch the following functions.

Ferrite.start_assemble — Function
start_assemble(K::AbstractSparseMatrixCSC;            fillzero::Bool=true) -> CSCAssembler
start_assemble(K::AbstractSparseMatrixCSC, f::Vector; fillzero::Bool=true) -> CSCAssembler

Create a CSCAssembler from the matrix K and optional vector f.

start_assemble(K::Symmetric{AbstractSparseMatrixCSC};                 fillzero::Bool=true) -> SymmetricCSCAssembler
start_assemble(K::Symmetric{AbstractSparseMatrixCSC}, f::Vector=Td[]; fillzero::Bool=true) -> SymmetricCSCAssembler

Create a SymmetricCSCAssembler from the matrix K and optional vector f.

CSCAssembler and SymmetricCSCAssembler allocate workspace necessary for efficient matrix assembly. To assemble the contribution from an element, use assemble!.

The keyword argument fillzero can be set to false if K and f should not be zeroed out, but instead keep their current values.

Depending on the loaded extensions more assembly formats become available through this interface.

source
Ferrite.assemble! — Function
assemble!(a::COOAssembler, dofs, Ke)
assemble!(a::COOAssembler, dofs, Ke, fe)

Assembles the element matrix Ke and element vector fe into a.

source
assemble!(a::COOAssembler, rowdofs, coldofs, Ke)

Assembles the matrix Ke into a according to the dofs specified by rowdofs and coldofs.

source
assemble!(g, dofs, ge)

Assembles the element residual ge into the global residual vector g.

source
assemble!(A::AbstractAssembler, dofs::AbstractVector{Int}, Ke::AbstractMatrix)
assemble!(A::AbstractAssembler, dofs::AbstractVector{Int}, Ke::AbstractMatrix, fe::AbstractVector)

Assemble the element stiffness matrix Ke (and optional force vector fe) into the global stiffness (and force) in A, given the element degrees of freedom dofs.

This is equivalent to K[dofs, dofs] += Ke and f[dofs] += fe, where K is the global stiffness matrix and f the global force/residual vector, but more efficient.

source

For local elimination support the following functions might also need custom dispatches

Ferrite._condense_local! — Function
_condense_local!(local_matrix::AbstractMatrix, local_vector::AbstractVector,
                global_matrix#=::SparseMatrixCSC=#, global_vector#=::Vector=#,
                global_dofs::AbstractVector, dofmapping::Dict, dofcoefficients::Vector)

Condensation of affine constraints on element level. If possible this function only modifies the local arrays.

source

Type definitions

Ferrite.COOAssembler — Type
struct COOAssembler{Tv, Ti}

This assembler creates a COO (coordinate format) representation of a sparse matrix during assembly and converts it into a SparseMatrixCSC{Tv, Ti} on finalization.

source

Utility functions

Ferrite.matrix_handle — Function
matrix_handle(a::AbstractAssembler)
vector_handle(a::AbstractAssembler)

Return a reference to the underlying matrix/vector of the assembler used during assembly operations.

source
Ferrite.vector_handle — Function
matrix_handle(a::AbstractAssembler)
vector_handle(a::AbstractAssembler)

Return a reference to the underlying matrix/vector of the assembler used during assembly operations.

source
Ferrite._sortdofs_for_assembly! — Function
_sortdofs_for_assembly!(permutation::Vector{Int}, sorteddofs::Vector{Int}, dofs::AbstractVector)

Sorts the dofs into a separate buffer and returns it together with a permutation vector.

source
Ferrite.sortperm2! — Function
sortperm2!(data::AbstractVector, permutation::AbstractVector)

Sort the input vector inplace and compute the corresponding permutation.

source