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 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 DofsToODofs{D,P,V} <: Map
  b::LagrangianDofBasis{P,V}
  odof_to_dof::Vector{Int8}
  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,S} <: AbstractVector{T}
  indices::Vector{T}
  terms::Vector{S}
end

struct OReindex <: Map end

struct OrderedFESpace{S<:SingleFieldFESpace} <: SingleFieldFESpace
  space::S
  cell_odofs_ids::AbstractArray
  fe_odof_basis::CellDof
  dirichlet_odof_tag::Vector{Int8}
end

Interface for FE spaces whose DOFs are ordered lexycographically. Notes:

• There are two separate lexycographies for free and Dirichlet DOFs, as in standard Gridap FE spaces: positive ids correspond to free DOFs, negative ids correspond to Dirichlet DOFs
• The following lexycographical hierarchy is considered: x-axis, y-axis, z-axis, component axis (only for multi-valued problems)
• An exception of the ordering is given by the function scatterfreeanddirichletvalues, which returns the scattered (cell) values in the standard Gridap ordering, in order to prevent errors when comparing two FEFunctions defined on a standard FE space or an ordered FE space. This feature can be removed with some work in future versions

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} <: AbstractDofMap{D,Ti}
  d_sparse_dofs_to_sparse_dofs::Array{Ti,D}
  d_sparse_dofs_to_full_dofs::Array{Ti,D}
  sparsity::A
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
• 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.

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

compose_index(i1_to_i2,i2_to_i3) -> AbstractVector

Returns an index map i1_to_i3 representing the composition i1_to_i2 ∘ i2_to_i3

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

get_active_dof_to_bg_dof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace
  ) -> (AbstractVector,AbstractVector)

Same as get_dof_to_bg_dof, unless f is a FESpaceWithLinearConstraints, in which case it calls get_dof_to_bg_dof on the underlying, unconstrained space

get_bg_ddof_to_ddof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace) -> AbstractVector

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, defines an index mapping relating each Dirichlet dof of bg_f to a Dirichlet dof in f. In practice, it returns a map v of length bg_nddofs such that v[bg_ddof] = ddof if bg_ddof is located in the active portion, and v[bg_ddof] = 0 otherwise

get_bg_dof_to_active_dof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace
  ) -> (AbstractVector,AbstractVector)

Same as get_bg_dof_to_dof, unless f is a FESpaceWithLinearConstraints, in which case it calls get_bg_dof_to_dof on the underlying, unconstrained space

get_bg_dof_to_dof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace
  ) -> (AbstractVector,AbstractVector)

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, returns the results of get_bg_fdof_to_fdof and get_bg_ddof_to_ddof

get_bg_fdof_to_fdof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace) -> AbstractVector

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, defines an index mapping relating each free dof of bg_f to a free dof in f. In practice, it returns a map v of length bg_nfdofs such that v[bg_fdof] = fdof if bg_fdof is located in the active portion, and v[bg_fdof] = 0 otherwise

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_ddof_to_bg_ddof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace) -> AbstractVector

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, defines an index mapping relating each Dirichlet dof of f to a Dirichlet dof in bg_f. In practice, it returns a map v of length nddofs such that v[ddof] = bg_ddof

get_dof_eltype(f::FESpace) -> Type

Fetches the DOF eltype for a FESpace f

get_dof_map(space::FESpace) -> VectorDofMap

Returns the free 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_dof_map_with_diri(space::FESpace) -> VectorDofMap

Same as get_dof_map, but includes also Dirichlet dofs

get_dof_to_bg_dof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace
  ) -> (AbstractVector,AbstractVector)

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, returns the results of get_fdof_to_bg_fdof and get_ddof_to_bg_ddof

get_fdof_to_bg_fdof(bg_f::SingleFieldFESpace,f::SingleFieldFESpace) -> AbstractVector

Given a background FE space bg_f, e.g. defined on a background discrete model, and a FE space f defined on an active portion of such model, defines an index mapping relating each free dof of f to a free dof in bg_f. In practice, it returns a map v of length nfdofs such that v[fdof] = bg_fdof

get_group_to_ilabels(labels::AbstractVector) -> Table

Given a vector of natural numbers labels, returns a table of length maximum(labels) - minimum(labels), whose entries group the indices associated with equal entries of labels. An empty group is assigned whenever a label does not appear in labels Example:

julia> labels = [1,3,2,3,1,5,5]
7-element Vector{Int64}:
 1
 3
 2
 3
 1
 5
 5
julia> get_group_to_ilabels(labels)
5-element Table{Int32, Vector{Int32}, Vector{Int32}}:
 [1, 5]
 [3]
 [2, 4]
 []
 [6, 7]

get_group_to_labels(labels::AbstractVector) -> Table

Given a vector of natural numbers labels, returns a table of length maximum(labels) - minimum(labels), whose entries group equal entries of labels. An empty group is assigned whenever a label does not appear in labels Example:

julia> labels = [1,3,2,3,1,5,5]
7-element Vector{Int64}:
 1
 3
 2
 3
 1
 5
 5
julia> get_group_to_labels(labels)
5-element Table{Int32, Vector{Int32}, Vector{Int32}}:
 [1, 1]
 [2]
 [3, 3]
 []
 [5, 5]

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

group_ilabels(labels::AbstractVector) -> Table

Same as get_group_to_ilabels, but removes the empty groups corresponding to non-existing labels in labels Example:

julia> labels = [1,3,2,3,1,5,5]
7-element Vector{Int64}:
 1
 3
 2
 3
 1
 5
 5
julia> group_ilabels(labels)
4-element Table{Int32, Vector{Int32}, Vector{Int32}}:
 [1, 5]
 [3]
 [2, 4]
 [6, 7]

group_labels(labels::AbstractVector) -> Table

Same as get_group_to_labels, but removes the empty groups corresponding to non-existing labels in labels Example:

julia> labels = [1,3,2,3,1,5,5]
7-element Vector{Int64}:
 1
 3
 2
 3
 1
 5
 5
julia> group_labels(labels)
4-element Table{Int32, Vector{Int32}, Vector{Int32}}:
 [1, 1]
 [2]
 [3, 3]
 [5, 5]

inverse_table(a_to_b::Table) -> Table

Given the input table a_to_b, returns the inverse table b_to_a Example:

julia> a = Table([[1,2,3],[2,3,4]])
2-element Table{Int64, Vector{Int64}, Vector{Int32}}:
 [1, 2, 3]
 [2, 3, 4]
julia> inverse_table(a)
4-element Table{Int32, Vector{Int32}, Vector{Int32}}:
 [1]
 [1, 2]
 [1, 2]
 [2]

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

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)