Extendable matrices

The type hierarchy of extendable matrices in this package is as follows:

ExtendableSparse.AbstractExtendableSparseMatrixCSC <: SparseArrays.AbstractSparseMatrixCSC <: SparseArrays.AbstractSparseMatrix <: AbstractMatrix

The package defines two subtypes of ExtendableSparse.AbstractExtendableSparseMatrixCSC which are parametrized by types of extension matrices:

ExtendableSparse.GenericExtendableSparseMatrixCSC for single threaded assembly
ExtendableSparse.GenericMTExtendableSparseMatrixCSC for multithreaded assembly

User facing defaults are defined by type aliases:

const MTExtendableSparseMatrixCSC = GenericMTExtendableSparseMatrixCSC{SparseMatrixDILNKC}
const STExtendableSparseMatrixCSC = GenericExtendableSparseMatrixCSC{SparseMatrixLNK}
const ExtendableSparseMatrixCSC = STExtendableSparseMatrixCSC
const ExtendableSparseMatrix = ExtendableSparseMatrixCSC

Abstract type

ExtendableSparse.AbstractExtendableSparseMatrixCSC — Type

abstract type AbstractExtendableSparseMatrixCSC{Tv, Ti} <: AbstractSparseMatrixCSC{Tv, Ti} end

Abstract super type for extendable CSC matrices. It implements what is being discussed as the "AbstractSparseMatrixCSC interfacee"

Subtypes must implement:

SparseArrays.sparse: flush+return SparseMatrixCSC
Constructor from SparseMatrixCSC
rawupdateindex!
reset!: empty all internals, just keep size
flush!: (re)build SparseMatrixCSC, incorporate new entries

Subtypes of this type would contain a SparseMatrixCSC which is used in linear algebra operations. In addition they would contain data structures for efficiently adding new entries, like instances or vectors of instances of subtypes of AbstractSparseMatrixExtension.

Subtypes of AbstractExtendableSparseMatrixCSC

ExtendableSparse.GenericExtendableSparseMatrixCSC — Type

mutable struct GenericExtendableSparseMatrixCSC{Tm<:ExtendableSparse.AbstractSparseMatrixExtension, Tv, Ti<:Integer} <: ExtendableSparse.AbstractExtendableSparseMatrixCSC{Tv, Ti<:Integer}

Single threaded extendable sparse matrix parametrized by sparse matrix extension.

Fields:

cscmatrix: a SparseMatrixCSC containing existing matrix entries
xmatrix: instance of an AbstractSparseMatrixExtension which is used to collect new entries

ExtendableSparse.GenericMTExtendableSparseMatrixCSC — Type

mutable struct GenericMTExtendableSparseMatrixCSC{Tm<:ExtendableSparse.AbstractSparseMatrixExtension, Tv, Ti<:Integer} <: ExtendableSparse.AbstractExtendableSparseMatrixCSC{Tv, Ti<:Integer}

Extendable sparse matrix parametrized by sparse matrix extension allowing multithreaded assembly and parallel matrix-vector multiplication.

Fields:

cscmatrix: a SparseMatrixCSC containing existing matrix entries
xmatrices: vector of instances of AbstractSparseMatrixExtension used to collect new entries
colparts: vector describing colors of the partitions of the unknowns
partnodes: vector describing partition of the unknowns

It is assumed that the set of unknowns is partitioned, and the partitioning is colored in such a way that several partitions of the same color can be handled by different threads, both during matrix assembly (which in general would use a partition of e.g. finite elements compatible to the partitioning of the nodes) and during matrix-vector multiplication. This approach is compatible with the current choice of the standard Julia sparse ecosystem which prefers compressed colume storage (CSC) over compressed row storage (CSR).

Type aliases

ExtendableSparse.MTExtendableSparseMatrixCSC — Type

MTExtendableSparseMatrixCSC

Multithreaded extendable sparse matrix (Experimental).

Aliased to GenericMTExtendableSparseMatrixCSC with SparseMatrixDILNKC scalar matrix parameter.

ExtendableSparse.STExtendableSparseMatrixCSC — Type

STExtendableSparseMatrixCSC

Single threaded extendable sparse matrix (Experimental).

Aliased to GenericExtendableSparseMatrixCSC with SparseMatrixLNK scalar matrix parameter.

ExtendableSparse.ExtendableSparseMatrixCSC — Type

ExtendableSparseMatrixCSC

Aliased to STExtendableSparseMatrixCSC to ensure backward compatibility to ExtendableSparse v1.x.

ExtendableSparse.ExtendableSparseMatrix — Type

ExtendableSparseMatrix

Aliased to STExtendableSparseMatrixCSC to ensure backward compatibility to ExtendableSparse v1.x.

Required methods

SparseArrays.sparse — Function

sparse(
    mat::ExtendableSparse.SparseMatrixDict{Tv, Ti}
) -> SparseMatrixCSC

SparseArrays.sparse(A::AbstractExtendableSparseMatrixCSC)

Return SparseMatrixCSC which contains all matrix entries introduced so far.

sparse(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC
) -> SparseMatrixCSC

sparse(
    ext::ExtendableSparse.GenericExtendableSparseMatrixCSC
) -> SparseMatrixCSC

ExtendableSparse.rawupdateindex! — Function

rawupdateindex!(
    lnk::ExtendableSparse.SparseMatrixLNK{Tv, Ti},
    op,
    v,
    i,
    j
) -> ExtendableSparse.SparseMatrixLNK{Tv, Ti} where {Tv, Ti}

Update element of the matrix with operation op. It assumes that op(0,0)==0. If v is zero a new entry is created nevertheless.

rawupdateindex!(
    lnk::ExtendableSparse.SparseMatrixDILNKC{Tv, Ti},
    op,
    v,
    i,
    j
) -> ExtendableSparse.SparseMatrixDILNKC

Update element of the matrix with operation op. It assumes that op(0,0)==0. If v is zero a new entry is created nevertheless.

rawupdateindex!(
    m::ExtendableSparse.SparseMatrixDict{Tv, Ti},
    op,
    v,
    i,
    j
) -> Any

rawupdateindex!(A::AbstractExtendableSparseMatrixCSC,op,v,i,j,part = 1)

Add or update entry of A: A[i,j]=op(A[i,j],v) without checking if a zero is inserted. The optional parameter part denotes the partition.

rawupdateindex!(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC,
    op,
    v,
    i,
    j
) -> Any
rawupdateindex!(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC,
    op,
    v,
    i,
    j,
    tid
) -> Any

rawupdateindex!(
    ext::ExtendableSparse.GenericExtendableSparseMatrixCSC,
    op,
    v,
    i,
    j
) -> Any
rawupdateindex!(
    ext::ExtendableSparse.GenericExtendableSparseMatrixCSC,
    op,
    v,
    i,
    j,
    part
) -> Any

ExtendableSparse.flush! — Function

flush!(csc::SparseMatrixCSC) -> SparseMatrixCSC

Trivial flush! method for allowing to run the code with both ExtendableSparseMatrix and SparseMatrixCSC.

flush!(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC{Tm, Tv, Ti}
) -> ExtendableSparse.GenericMTExtendableSparseMatrixCSC{Tm, Tv, Ti} where {Tm, Tv, Ti}

flush!(
    ext::ExtendableSparse.GenericExtendableSparseMatrixCSC{Tm, Tv, Ti}
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC{Tm, Tv, Ti} where {Tm, Tv, Ti}

ExtendableSparse.reset! — Function

reset!(
    m::ExtendableSparse.SparseMatrixDict{Tv, Ti}
) -> Dict{Pair{_A, _B}} where {_A, _B}

reset!(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC{Tm, Tv, Ti},
    p::Integer
) -> ExtendableSparse.GenericMTExtendableSparseMatrixCSC{Tm, Tv, Ti} where {Tm, Tv, Ti}

reset!(
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC
) -> ExtendableSparse.GenericMTExtendableSparseMatrixCSC

reset!(
    ext::ExtendableSparse.GenericExtendableSparseMatrixCSC{Tm, Tv, Ti}
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC{Tm, Tv, Ti} where {Tm, Tv, Ti}

AbstractSparseMatrixCSC interface

See SparseArrways#395 for a discussion.

SparseArrays.nnz — Function

nnz(lnk::ExtendableSparse.SparseMatrixLNK) -> Integer

Return number of nonzero entries.

nnz(lnk::ExtendableSparse.SparseMatrixDILNKC) -> Integer

Return number of nonzero entries.

nnz(m::ExtendableSparse.SparseMatrixDict) -> Int64

SparseArrays.nnz(ext::AbstractExtendableSparseMatrixCSC)

flush! and return number of nonzeros in ext.cscmatrix.

SparseArrays.nonzeros — Function

SparseArrays.nonzeros(ext::AbstractExtendableSparseMatrixCSC) = nonzeros(sparse(ext))

flush! and return nonzeros in ext.cscmatrix.

SparseArrays.rowvals — Function

SparseArrays.rowvals(ext::AbstractExtendableSparseMatrixCSC)

flush! and return rowvals in ext.cscmatrix.

SparseArrays.findnz — Function

SparseArrays.findnz(ext::AbstractExtendableSparseMatrixCSC)

flush! and return findnz(ext.cscmatrix).

SparseArrays.dropzeros! — Function

dropzeros!(
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> SparseMatrixCSC

SparseArrays.getcolptr — Function

SparseArrays.getcolptr(ext::AbstractExtendableSparseMatrixCSC)

flush! and return colptr of in ext.cscmatrix.

SparseArrays.SparseMatrixCSC — Type

SparseMatrixCSC(
    lnk::ExtendableSparse.SparseMatrixLNK
) -> SparseMatrixCSC

Constructor from SparseMatrixLNK.

SparseMatrixCSC(
    lnk::ExtendableSparse.SparseMatrixDILNKC
) -> SparseMatrixCSC{Float64, Int64}

Constructor from SparseMatrixDILNKC.

SparseArrays.SparseMatrixCSC(A::AbstractExtendableSparseMatrixCSC)

Create SparseMatrixCSC from ExtendableSparseMatrix

Base.size — Function

size(
    lnk::ExtendableSparse.SparseMatrixLNK
) -> Tuple{Integer, Integer}

Return tuple containing size of the matrix.

size(
    lnk::ExtendableSparse.SparseMatrixDILNKC
) -> Tuple{Integer, Integer}

Return tuple containing size of the matrix.

size(
    m::ExtendableSparse.SparseMatrixDict
) -> Tuple{Any, Any}

Base.size(ext::AbstractExtendableSparseMatrixCSC)

Return size of matrix.

Base.eltype — Function

Base.eltype(::AbstractExtendableSparseMatrixCSC{Tv, Ti})

Return element type.

Base.show — Function

Base.show(::IO, ::MIME"text/plain", ext::AbstractExtendableSparseMatrixCSC)

flush! and use the show method of SparseMatrixCSC to show the content.

Linear Algebra

Base.:\ — Function

 Base.:\(::AbstractExtendableSparseMatrixCSC, b)

\ for ExtendableSparse. It calls the LU factorization form Sparspak.jl, unless GPL components are allowed in the Julia sysimage and the floating point type of the matrix is Float64 or Complex64. In that case, Julias standard `` is called, which is realized via UMFPACK.

 Base.:\(Symmetric(::AbstractExtendableSparseMatrixCSC), b)

\ for Symmetric{ExtendableSparse}

 Base.:\(Hermitian(::AbstractExtendableSparseMatrixCSC), b)

\ for Hermitian{ExtendableSparse}

LinearAlgebra.ldiv! — Function

ldiv!(
    r::AbstractArray,
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    x::AbstractArray
) -> SparseMatrixCSC

flush! and ldiv! with ext.cscmatrix

LinearAlgebra.mul! — Function

mul!(
    r::AbstractVecOrMat,
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    x::AbstractVecOrMat
)

flush! and multiply with ext.cscmatrix

mul!(
    r::AbstractVecOrMat,
    ext::ExtendableSparse.GenericMTExtendableSparseMatrixCSC,
    x::AbstractVecOrMat
)

LinearAlgebra.norm — Function

norm(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> Any
norm(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    p::Real
) -> Any

flush! and calculate norm from cscmatrix

LinearAlgebra.opnorm — Function

opnorm(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> Any
opnorm(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    p::Real
) -> Any

flush! and calculate opnorm from cscmatrix

LinearAlgebra.cond — Function

cond(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> Any
cond(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    p::Real
) -> Any

flush! and calculate cond from cscmatrix

LinearAlgebra.issymmetric — Function

issymmetric(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> Bool

flush! and check for symmetry of cscmatrix

Algebraic operations

Base.:+ — Function

+(
    lnk::ExtendableSparse.SparseMatrixLNK{Tv, Ti<:Integer},
    csc::SparseMatrixCSC
) -> SparseMatrixCSC

Add SparseMatrixCSC matrix and SparseMatrixLNK lnk, returning a SparseMatrixCSC

+(
    dictmatrix::ExtendableSparse.SparseMatrixDict{Tv, Ti},
    cscmatrix::SparseMatrixCSC{Tv, Ti}
) -> SparseMatrixCSC{Tv, Ti} where {Tv, Ti}

+(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    B::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC

+(
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    csc::SparseMatrixCSC
) -> SparseMatrixCSC

Base.:- — Function

-(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    B::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC

-(
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    csc::SparseMatrixCSC
) -> SparseMatrixCSC

-(
    csc::SparseMatrixCSC,
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> SparseMatrixCSC

Base.:* — Function

*(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    B::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC

*(
    d::Diagonal,
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC

*(
    ext::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    d::Diagonal
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC

Handling of homogeneous Dirichlet BC

ExtendableSparse.mark_dirichlet — Function

mark_dirichlet(A; penalty=1.0e20)

Return boolean vector marking Dirichlet nodes, known by A[i,i]>=penalty

mark_dirichlet(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC;
    penalty
) -> Vector{Bool}

ExtendableSparse.eliminate_dirichlet! — Function

eliminate_dirichlet!(A,dirichlet_marker)

Eliminate dirichlet nodes in matrix by setting

    A[:,i]=0; A[i,:]=0; A[i,i]=1

for a node i marked as Dirichlet.

Returns A.

eliminate_dirichlet!(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    dirichlet
) -> ExtendableSparse.AbstractExtendableSparseMatrixCSC

ExtendableSparse.eliminate_dirichlet — Function

eliminate_dirichlet(A,dirichlet_marker)

Create a copy B of A sharing the sparsity pattern. Eliminate dirichlet nodes in B by setting

    B[:,i]=0; B[i,:]=0; B[i,i]=1

for a node i marked as Dirichlet.

Returns B.

eliminate_dirichlet(
    A::ExtendableSparse.AbstractExtendableSparseMatrixCSC,
    dirichlet
) -> ExtendableSparse.GenericExtendableSparseMatrixCSC