GitHub

Sparsity pattern and sparse matrices

This is the reference documentation for sparsity patterns and sparse matrix instantiation. See the topic section on Sparsity pattern and sparse matrices.

Sparsity patterns

AbstractSparsityPattern

The following applies to all subtypes of AbstractSparsityPattern:

Ferrite.init_sparsity_pattern — Function
init_sparsity_pattern(dh::DofHandler; nnz_per_row::Int)

Initialize an empty SparsityPattern with ndofs(dh) rows and ndofs(dh) columns.

Keyword arguments

  • nnz_per_row: memory optimization hint for the number of non-zero entries per row that will be added to the pattern.
source
Ferrite.add_sparsity_entries! — Function
add_sparsity_entries!(
    sp::AbstractSparsityPattern,
    dh::DofHandler,
    ch::Union{ConstraintHandler, Nothing} = nothing;
    topology = nothing,
    keep_constrained::Bool = true,
    coupling = nothing,
    interface_coupling = nothing,
)

Convenience method for doing the common task of calling add_cell_entries!, add_interface_entries!, and add_constraint_entries!, depending on what arguments are passed:

  • add_cell_entries! is always called
  • add_interface_entries! is called if topology is provided (i.e. not nothing)
  • add_constraint_entries! is called if the ConstraintHandler is provided

For more details about arguments and keyword arguments, see the respective functions.

source
Ferrite.add_cell_entries! — Function
add_cell_entries!(
    sp::AbstractSparsityPattern,
    dh::DofHandler,
    ch::Union{ConstraintHandler, Nothing} = nothing;
    keep_constrained::Bool = true,
    coupling::Union{AbstractMatrix{Bool}, Nothing}, = nothing
)

Add entries to the sparsity pattern sp corresponding to DoF couplings within the cells as described by the DofHandler dh.

Keyword arguments

  • keep_constrained: whether or not entries for constrained DoFs should be kept (keep_constrained = true) or eliminated (keep_constrained = false) from the sparsity pattern. keep_constrained = false requires passing the ConstraintHandler ch.
  • coupling: the coupling between fields/components within each cell. By default (coupling = nothing) it is assumed that all DoFs in each cell couple with each other.
source
Ferrite.add_interface_entries! — Function
add_interface_entries!(
    sp::SparsityPattern, dh::DofHandler, ch::Union{ConstraintHandler, Nothing};
    topology::ExclusiveTopology, keep_constrained::Bool = true,
    interface_coupling::AbstractMatrix{Bool},
)

Add entries to the sparsity pattern sp corresponding to DoF couplings on the interface between cells as described by the DofHandler dh.

Keyword arguments

  • topology: the topology corresponding to the grid.
  • keep_constrained: whether or not entries for constrained DoFs should be kept (keep_constrained = true) or eliminated (keep_constrained = false) from the sparsity pattern. keep_constrained = false requires passing the ConstraintHandler ch.
  • interface_coupling: the coupling between fields/components across the interface.
source
Ferrite.add_constraint_entries! — Function
add_constraint_entries!(
    sp::AbstractSparsityPattern, ch::ConstraintHandler;
    keep_constrained::Bool = true,
)

Add all entries resulting from constraints in the ConstraintHandler ch to the sparsity pattern. Note that, since this operation depends on existing entries in the pattern, this function must be called as the last step when creating the sparsity pattern.

Keyword arguments

  • keep_constrained: whether or not entries for constrained DoFs should be kept (keep_constrained = true) or eliminated (keep_constrained = false) from the sparsity pattern.
source
Ferrite.add_entry! — Function
add_entry!(sp::AbstractSparsityPattern, row::Int, col::Int)

Add an entry to the sparsity pattern sp at row row and column col.

source

SparsityPattern

Ferrite.SparsityPattern — Method
SparsityPattern(nrows::Int, ncols::Int; nnz_per_row::Int = 8)

Create an empty SparsityPattern with nrows rows and ncols columns. nnz_per_row is used as a memory hint for the number of non zero entries per row.

SparsityPattern is the default sparsity pattern type for the standard DofHandler and is therefore commonly constructed using init_sparsity_pattern instead of with this constructor.

Examples

# Create a sparsity pattern for an 100 x 100 matrix, hinting at 10 entries per row
sparsity_pattern = SparsityPattern(100, 100; nnz_per_row = 10)

Methods

The following methods apply to SparsityPattern (see their respective documentation for more details):

source
Ferrite.SparsityPattern — Type
struct SparsityPattern <: AbstractSparsityPattern

Data structure representing non-zero entries in the eventual sparse matrix.

See the constructor SparsityPattern(::Int, ::Int) for the user-facing documentation.

Struct fields

  • nrows::Int: number of rows
  • ncols::Int: number of column
  • rows::Vector{Vector{Int}}: vector of length nrows, where rows[i] is a sorted vector of column indices for non zero entries in row i.
Internal struct

The specific implementation of this struct, such as struct fields, type layout and type parameters, are internal and should not be relied upon.

source

BlockSparsityPattern

Package extension

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

Ferrite.BlockSparsityPattern — Method
BlockSparsityPattern(block_sizes::Vector{Int})

Create an empty BlockSparsityPattern with row and column block sizes given by block_sizes.

Examples

# Create a block sparsity pattern with block size 10 x 5
sparsity_pattern = BlockSparsityPattern([10, 5])

Methods

The following methods apply to BlockSparsityPattern (see their respective documentation for more details):

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
Ferrite.BlockSparsityPattern — Type
struct BlockSparsityPattern <: AbstractSparsityPattern

Data structure representing non-zero entries for an eventual blocked sparse matrix.

See the constructor BlockSparsityPattern(::Vector{Int}) for the user-facing documentation.

Struct fields

  • nrows::Int: number of rows
  • ncols::Int: number of column
  • block_sizes::Vector{Int}: row and column block sizes
  • blocks::Matrix{SparsityPattern}: matrix of size length(block_sizes) × length(block_sizes) where blocks[i, j] is a SparsityPattern corresponding to block (i, j).
Internal struct

The specific implementation of this struct, such as struct fields, type layout and type parameters, are internal and should not be relied upon.

source
Ferrite.allocate_matrix — Method
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(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(::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
Ferrite.allocate_matrix — Method
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

Sparse matrices

Creating matrix from SparsityPattern

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

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

source
Ferrite.allocate_matrix — Method
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

Creating matrix from DofHandler

Ferrite.allocate_matrix — Method
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