GridapROMs.DofMaps

abstract type AbstractDofMap{D,Ti} <: AbstractArray{Ti,D} end

Type representing an indexing strategy for FE quantitites (e.g. FE vectors such as FE solutions and residuals, or FE sparse matrices such as FE Jacobians). Subtypes:

• InverseDofMap
• VectorDofMap
• TrivialSparseMatrixDofMap
• SparseMatrixDofMap

struct CartesianSparsity{A<:SparsityPattern,B<:AbstractVector,C<:AbstractVector} <: SparsityPattern
  sparsity::A
  bg_rows_to_act_rows::B
  bg_cols_to_act_cols::C
end

Fields:

• sparsity: the SparsityPattern of a matrix assembled on a (active) geometry which is either Cartesian, or it is defined from a (background) Cartesian geometry
• bg_rows_to_act_rows: a vector that maps a row of the Cartesian background geometry, to a row of the active geometry
• bg_cols_to_act_cols: a vector that maps a column of the Cartesian background geometry, to a column of the active geometry

struct DofMapArray{T,D,Ti,A<:AbstractArray{T},I<:AbstractArray{Ti,D}} <: AbstractArray{T,D}
  array::A
  dof_map::I
end

Subtype of AbstractArray whose entries stored in array are indexed according to the indexing strategy specified in dof_map

struct DofToCell{A} <: Map
  cellids::A
end

Inverse map of a standard connectivity structure: providing an input dof, returns a list of all the cells containing the dof

struct DofsToODofs{D,P,V} <: Map
  b::LagrangianDofBasis{P,V}
  odof_to_dof::Vector{Int32}
  node_and_comps_to_odof::Array{V,D}
  orders::NTuple{D,Int}
end

Map used to convert a DOF of a standard FESpace in Gridap to a DOF belonging to a space whose DOFs are lexicographically-ordered

struct InverseDofMap{D,Ti,I<:AbstractDofMap{D,Ti}} <: AbstractDofMap{D,Ti}
  dof_map::I
end

Inverse dof map of a given AbstractDofMap object dof_map

struct OIdsToIds{T,A<:AbstractVector{<:Integer}} <: AbstractVector{T}
  indices::Vector{T}
  terms::A
end

struct OReindex{T<:Integer} <: Map
  indices::Vector{T}
end

Map used to reindex according to the vector of integers indices

abstract type OrderedFESpace{S} <: SingleFieldFESpace end

Interface for FE spaces that feature a DOF reordering

struct Range1D{I<:AbstractVector,J<:AbstractVector} <: AbstractVector{Int}
  range::Range2D{I,J}
end

Represents a Range2D reshaped as a vector

struct Range2D{I<:AbstractVector,J<:AbstractVector} <: AbstractMatrix{Int}
  axis1::I
  axis2::J
  scale::Int
end

Creates the indices of a Kronecker product matrix from the indices of the two factors. The field axis1 refers to the first factor, field axis2 refers to the second factor. The field scale is by default equal to the number of entries of the first factor.

struct SparseMatrixDofMap{D,Ti,A<:SparsityPattern,B<:SparseDofMapStyle} <: AbstractDofMap{D,Ti}
  d_sparse_dofs_to_sparse_dofs::Array{Ti,D}
  d_sparse_dofs_to_full_dofs::Array{Ti,D}
  sparsity::A
  index_style::B
end

Index map used to select the nonzero entries of a sparse matrix of sparsity sparsity. The nonzero entries are sorted according to the field d_sparse_dofs_to_sparse_dofs by default. For more details, check the function get_d_sparse_dofs_to_full_dofs

struct SparsityCSC{Tv,Ti} <: SparsityPattern
  matrix::SparseMatrixCSC{Tv,Ti}
end

Sparsity pattern associated to a compressed sparse column matrix matrix

abstract type SparsityPattern end

Type used to represent the sparsity pattern of a sparse matrix, usually the Jacobian in a FE problem.

Subtypes:

• SparsityCSC
• CartesianSparsity
• TProductSparsity

struct TProductSparsity{A<:SparsityPattern,B<:SparsityPattern} <: SparsityPattern
  sparsity::A
  sparsities_1d::Vector{B}
end

Fields:

• sparsity: a SparsityPattern of a matrix assembled on a Cartesian geometry of dimension D
• sparsities_1d: a vector of D 1D sparsity patterns

Structure used to represent a SparsityPattern of a matrix obtained by integrating a bilinear form on a triangulation that can be obtained as the tensor product of D 1D triangulations. For example, this can be done on a Cartesian mesh composed of D-cubes

const TrivialDofMap{Ti} = AbstractDofMap{1,Ti}

struct TrivialSparseMatrixDofMap{A<:SparsityPattern} <: TrivialDofMap{Int}
  sparsity::A
end

Index map used to select the nonzero entries of a sparse matrix of sparsity sparsity

struct VectorDofMap{D,I<:AbstractVector{<:Integer}} <: AbstractDofMap{D,Int32}
  size::Dims{D}
  bg_dof_to_act_dof::I
end

Dof map intended for the reindexing of FE vectors (e.g. FE solutions or residuals).

Fields:

• size: denotes the desired shape of the reindexed array
• bg_dof_to_act_dof: vector mapping a background DOF to an active DOF. A background DOF lives on a FESpace defined on a background Cartesian mesh; an active DOF lives on a FESpace defined on an active mesh, which must occupy a portion of the background mesh. When the active mesh coincides with the background one, bg_dof_to_act_dof represents simply an identity map. If not, this means there are inactive DOFs in the background FESpace, which bg_dof_to_act_dof is responsible of masking.

More in detail, if size = (n1,...,nD), we can think of this mapping as a function

n1 × ... × nD ⟶ {0,1,...,Nact}

where Nact is the number of active DOFs. The output of this map is an index according to which we reindex FE vectors. We follow the convention that, when indexed by zero, the FE vectors return a zero. This is acceptable, since the FE vector does not actually hold a value when indexed at an inactive DOF.

OrderedFEFunction(f::OrderedFESpace,fv,dv) -> FEFunction

Returns a FEFunction with correctly ordered values

add_ordered_entries!(combine::Function,A,vs,is::OIdsToIds,js::OIdsToIds)

Adds several ordered entries only for positive input indices. Returns A

change_dof_map(i::AbstractDofMap,args...) -> AbstractDofMap

Creates a new dof map from an old dof map i

fast_index(i,nfast::Integer) -> Any

Returns the fast index in a tensor product structure. Suppose we have two matrices A and B of sizes Ra × Ca and Rb × Rb. Their kronecker product AB = A ⊗ B, of size RaRb × CaCb, can be indexed as

AB[i,j] = A[slow_index(i,RbCb)] * B[fast_index(i,RbCb)],

where nfast == RbCb. In other words, this function converts an index belonging to AB to an index belonging to B

flatten(i::AbstractDofMap) -> TrivialDofMap

Flattens i, the output will be a dof map with ndims == 1

gather_ordered_free_and_dirichlet_values!(fv,dv,f::OrderedFESpace,cv) -> Nothing

Gathers correctly ordered free and dirichlet values

get_bg_dof_to_act_dof(f::FESpace,args...) -> AbstractVector{<:Integer}

Associates an active DOF to each background DOF of a FESpace f. This is done by computing the cumulative sum of the output of get_bg_dof_to_mask on f

get_bg_dof_to_mask(f::FESpace,args...) -> Vector{Bool}

Associates a boolean mask to each background DOF of a FESpace f. If the DOF is active, the mask is false. If the DOF is inactive (e.g., because it is constrained), the mask is true

get_cell_odof_ids(f::OrderedFESpace) -> AbstractArray

Fetches the ordered connectivity structure

get_d_sparse_dofs_to_full_dofs(Tu,Tv,a::TProductSparsity) -> AbstractArray{<:Integer,D}

Input:

• Tu, Tv: DOF types of a trial FESpace U and test FESpace V, respecively
• a: a TProductSparsity representing the sparsity of the matrix assembled from U and V

Output:

• a D-array d_sparse_dofs_to_full_dofs, which represents a map from Nnz_1 × … × Nnz_{D} to M⋅N, where Nnz_i represents the number of nonzero entries of the ith 1D sparsity contained in a, and M⋅N is the total length of the tensor product sparse matrix in a. For vector-valued FESpaces, an additional axis is added to d_sparse_dofs_to_full_dofs representing the number of components. In particular, the component axis has a length equal to num_components(Tu)⋅num_components(Tv)

get_dof_eltype(f::FESpace) -> Type

Fetches the DOF eltype for a FESpace f

get_dof_map(space::FESpace) -> VectorDofMap

Returns the active dofs sorted by coordinate order, for every dimension. If space is a D-dimensional, scalar FESpace, the output index map will be a subtype of AbstractDofMap{<:Integer,D}. If space is a D-dimensional, vector-valued FESpace, the output index map will be a subtype of AbstractDofMap{D+1}.

get_internal_dof_map(space::FESpace) -> VectorDofMap

Returns the internal dofs sorted by coordinate order, for every dimension. If space is a D-dimensional, scalar FESpace, the output index map will be a subtype of AbstractDofMap{<:Integer,D}. If space is a D-dimensional, vector-valued FESpace, the output index map will be a subtype of AbstractDofMap{D+1}.

get_polynomial_order(f::FESpace) -> Integer

Retrieves the polynomial order of f

get_polynomial_orders(fs::FESpace) -> Integer

Retrieves the polynomial order of fs for every dimension

get_sparse_dof_map(trial::FESpace,test::FESpace,args...) -> AbstractDofMap

Returns the index maps related to Jacobiansin a FE problem. The default output is a TrivialSparseMatrixDofMap; when the trial and test spaces are of type TProductFESpace, a SparseMatrixDofMap is returned.

get_sparsity(U::FESpace,V::FESpace,trian=_get_common_domain(U,V)) -> SparsityPattern

Builds a SparsityPattern from two FESpaces U and V, via integration on a triangulation trian

invert(i::AbstractDofMap) -> InverseDofMap

Retruns an InverseDofMap object out of an existing dof map i

range_1d(i::AbstractVector,j::AbstractVector,args...) -> AbstractVector{Int}

Vectorization operation of a Range2D object

range_2d(i::AbstractVector,j::AbstractVector,scale=length(i)) -> Range2D

Constructor of a Range2D object

recast(v::AbstractVector,a::AbstractSparseMatrix) -> AbstractSparseMatrix

Returns a sparse matrix with values equal to v, and sparsity pattern equal to that of a

recast_indices(fids::AbstractArray,a::AbstractSparseMatrix) -> AbstractArray

Input:

• a sparse matrix a of size (M,N) and a number of nonzero entries Nnz
• an array of indices sids with values ∈ {1,...,Nnz} (sparse indices)

Output:

• an array of indices fids with values ∈ {1,...,MN} (full indices), whose

entries are associated to those of sids. Zero entries are preserved

recast_split_indices(fids::AbstractArray,a::AbstractSparseMatrix) -> (AbstractArray,AbstractArray)

Input:

• a sparse matrix a of size (M,N) and a number of nonzero entries Nnz
• an array of indices sids with values ∈ {1,...,Nnz} (sparse indices)

Output:

• an array rows of indices frows with values ∈ {1,...,M} (full rows), whose

entries are associated to those of sids. Zero entries are preserved

• an array rows of indices fcols with values ∈ {1,...,N} (full cols), whose

entries are associated to those of sids. Zero entries are preserved

scatter_ordered_free_and_dirichlet_values(f::OrderedFESpace,fv,dv) -> AbstractArray

Scatters correctly ordered free and dirichlet values

slow_index(i,nfast::Integer) -> Any

Returns the slow index in a tensor product structure. Suppose we have two matrices A and B of sizes Ra × Ca and Rb × Rb. Their kronecker product AB = A ⊗ B, of size RaRb × CaCb, can be indexed as

AB[i,j] = A[slow_index(i,RbCb)]B[fast_index(i,RbCb)],

where nfast == RbCb. In other words, this function converts an index belonging to AB to an index belonging to A

sparsify_indices(sids::AbstractArray,a::AbstractSparseMatrix) -> AbstractArray

Input:

• a sparse matrix a of size (M,N) and a number of nonzero entries Nnz
• an array of indices fids with values ∈ {1,...,MN} (full indices)

Output:

• an array of indices sids with values ∈ {1,...,Nnz} (sparse indices), whose

entries are associated to those of fids. Zero entries are preserved

vectorize(i::AbstractDofMap) -> AbstractVector

Reshapes i as a vector, and removes the masked dofs in i (if any)