GridapROMs.ParamDataStructures

module ParamDataStructures

Data structures for parametric PDEs: parameter spaces, realisations, parametric arrays, sparse matrices, and solution snapshots.

Parameter spaces and sampling

• ParamSpace / TransientParamSpace — domains over which parameters vary, with sampling strategies UniformSampling, NormalSampling, HaltonSampling, etc.
• Realisation / TransientRealisation — concrete parameter (and time) values drawn from a ParamSpace.
• ParamFunction / TransientParamFunction — functions parameterised over a ParamSpace.

Parametric arrays

• AbstractParamArray — abstract supertype; concrete subtypes are ConsecutiveParamArray (contiguous data layout, most efficient) and GenericParamArray.
• ParamSparseMatrix — sparse matrix with one entry per parameter.
• BlockParamArray — block-structured parametric array for multi-field problems.

Snapshots

• Snapshots — collection of FE solution vectors indexed by parameter (and optionally time).
• TransientSnapshots and its subtypes for time-dependent problems.
• select_snapshots — extract a subset of snapshots.

const ConsecutiveParamSparseMatrix{Tv,Ti} = Union{
  ConsecutiveParamSparseMatrixCSC{Tv,Ti},
  ConsecutiveParamSparseMatrixCSR{<:Any,Tv,Ti}}

Parameterised sparse matrices sharing the same sparsity pattern, whose nonzero values are stored contiguously

abstract type AbstractParamArray{T,N,A<:AbstractArray{T,N}} <: AbstractParamData{A,N} end

Type representing parametric abstract arrays of type A. Subtypes:

• ParamArray
• ParamSparseMatrix

const AbstractParamArray3D{T} = AbstractParamArray{T,3,<:AbstractArray{T,3}}

abstract type AbstractParamData{T,N} <: AbstractArray{T,N} end

Type representing generic parametric quantities. Subtypes:

• ParamNumber
• AbstractParamArray
• AbstractSnapshots

abstract type AbstractParamFunction{P<:Realisation} <: Function end

Representation of parametric functions with domain a parametric space. Subtypes:

• ParamFunction
• TransientParamFunction

const AbstractParamMatrix{T} = AbstractParamArray{T,2,<:AbstractMatrix{T}}

const AbstractParamVector{T} = AbstractParamArray{T,1,<:AbstractVector{T}}

abstract type AbstractRealisation end

Type representing parametric realisations, i.e. samples extracted from a given parameter space. Subtypes:

• Realisation
• TransientRealisation

abstract type AbstractSnapshots{T,N} <: AbstractParamData{T,N} end

Type representing N-dimensional arrays of snapshots. Subtypes must contain the following information:

• data: a (parametric) array
• realisation: a subtype of AbstractRealisation, representing the points in the parameter space used to compute the array data
• dof map: a subtype of AbstractDofMap, representing a reindexing strategy for the array data

Subtypes:

• Snapshots
• BlockSnapshots

const BlockConsecutiveParamArray{T,N,A<:Vector{<:ConsecutiveParamArray{T,N}},B} = BlockParamArray{T,N,A,B}

const BlockConsecutiveParamMatrix{T,A<:Matrix{<:ConsecutiveParamMatrix{T}},B} = BlockParamMatrix{T,A,B}

const BlockConsecutiveParamVector{T,A<:Vector{<:ConsecutiveParamVector{T}},B} = BlockParamVector{T,A,B}

struct BlockParamArray{T,N,A<:AbstractArray{<:AbstractParamArray{T,N},N},B<:NTuple{N,AbstractUnitRange{Int}}} <: ParamArray{T,N}
  data::A
  axes::B
end

Is to a ParamArray as a BlockArray is to a regular AbstractArray

const BlockParamMatrix{T,A,B} = BlockParamArray{T,2,A,B}

const BlockParamVector{T,A,B} = BlockParamArray{T,1,A,B}

struct BlockSnapshots{S<:Snapshots,N} <: AbstractSnapshots{S,N}
  array::Array{S,N}
end

Block container for Snapshots in a MultiField setting. Its param data is not stored separately; it is always derived from blocks(s) (mortared together), so that it stays consistent with the blocks under any operation (selecting, clustering, concatenating, ...) instead of needing to be kept in sync by hand alongside them.

struct ConsecutiveParamArray{T,N,M,A<:AbstractArray{T,M}} <: ParamArray{T,N}
  data::A
end

Parametric array with entries stored consecutively in memory. It is characterized by an inner size equal to size(data)[1:N], and parametric length equal to size(data,N+1), where data is an AbstractArray of dimension M = N+1

const ConsecutiveParamMatrix{T,A<:AbstractArray{T,3}} = ConsecutiveParamArray{T,2,3,A}

struct ConsecutiveParamSparseMatrixCSC{Tv,Ti<:Integer,A<:AbstractMatrix{Tv}} <: ParamSparseMatrixCSC{Tv,Ti}
  m::Int64
  n::Int64
  colptr::Vector{Ti}
  rowval::Vector{Ti}
  data::A
end

Represents a vector of sparse matrices in CSC format, with entries stored consecutively in memory. For sake of coherence, an instance of ConsecutiveParamSparseMatrixCSC inherits from AbstractMatrix{<:SparseMatrixCSC{Tv,Ti} rather than AbstractVector{<:SparseMatrixCSC{Tv,Ti}, but should conceptually be thought as an AbstractVector{<:SparseMatrixCSC{Tv,Ti}.

struct ConsecutiveParamSparseMatrixCSR{Bi,Tv,Ti<:Integer,A<:AbstractMatrix{Tv}} <: ParamSparseMatrixCSR{Bi,Tv,Ti}
  m::Int64
  n::Int64
  rowptr::Vector{Ti}
  colval::Vector{Ti}
  data::A
end

Represents a vector of sparse matrices in CSR format, with entries stored consecutively in memory. For sake of coherence, an instance of ConsecutiveParamSparseMatrixCSR inherits from AbstractMatrix{<:SparseMatrixCSR{Bi,Tv,Ti} rather than AbstractVector{<:SparseMatrixCSR{Bi,Tv,Ti}, but should conceptually be thought as an AbstractVector{<:SparseMatrixCSR{Bi,Tv,Ti}.

const ConsecutiveParamVector{T,A<:AbstractArray{T,2}} = ConsecutiveParamArray{T,1,2,A}

struct FetchParam <: Map
  index::Int
end

Map extracting the index-th parameter from a parameterised cell array

struct GenericParamBlock{A} <: ParamBlock{A}
  data::Vector{A}
end

Most standard implementation of a ParamBlock

struct GenericParamMatrix{Tv,Ti} <: ParamArray{Tv,2}
  data::Vector{Tv}
  ptrs::Vector{Ti}
  nrows::Vector{Ti}
end

Parametric matrix with entries stored non-consecutively in memory

struct GenericParamSparseMatrixCSC{Tv,Ti<:Integer} <: ParamSparseMatrixCSC{Tv,Ti}
  m::Int64
  n::Int64
  colptr::Vector{Ti}
  rowval::Vector{Ti}
  data::Vector{Tv}
  ptrs::Vector{Ti}
end

Represents a vector of sparse matrices in CSC format, with entries stored non-consecutively in memory. For sake of coherence, an instance of GenericParamSparseMatrixCSC inherits from AbstractMatrix{<:SparseMatrixCSC{Tv,Ti} rather than AbstractVector{<:SparseMatrixCSC{Tv,Ti}, but should conceptually be thought as an AbstractVector{<:SparseMatrixCSC{Tv,Ti}.

struct GenericParamSparseMatrixCSR{Bi,Tv,Ti<:Integer} <: ParamSparseMatrixCSR{Bi,Tv,Ti}
  m::Int64
  n::Int64
  rowptr::Vector{Ti}
  colval::Vector{Ti}
  data::Vector{Tv}
  ptrs::Vector{Ti}
end

Represents a vector of sparse matrices in CSR format, with entries stored non-consecutively in memory. For sake of coherence, an instance of GenericParamSparseMatrixCSR inherits from AbstractMatrix{<:SparseMatrixCSR{Bi,Tv,Ti} rather than AbstractVector{<:SparseMatrixCSR{Bi,Tv,Ti}, but should conceptually be thought as an AbstractVector{<:SparseMatrixCSR{Bi,Tv,Ti}.

struct GenericParamVector{Tv,Ti} <: ParamArray{Tv,1}
  data::Vector{Tv}
  ptrs::Vector{Ti}
end

Parametric vector with entries stored non-consecutively in memory

struct GenericSnapshots{T,N,I,R,A,B} <: Snapshots{T,N,I,R}
  data::A
  param_data::B
  dof_map::I
  realisation::R
end

Most standard implementation of a Snapshots

struct GenericTransientRealisation{P,T,A} <: TransientRealisation{P,T}
  params::P
  times::A
  t0::T
end

Most standard implementation of a TransientRealisation.

struct HaltonSampling <: SamplingStyle
  start::Int
end

Sampling according to a Halton sequence

Halton is a sequence, not a distribution, hence this sampling strategy repeats realisations since the draws are not randomized; to draw different parameters, one needs to provide a starting point in the sequence (start = 1 by default)

struct LatinHypercubeSampling <: SamplingStyle end

Sampling according to a Latin HyperCube distribution

struct NormalSampling <: SamplingStyle end

Sampling according to a normal distribution

abstract type ParamArray{T,N} <: AbstractParamArray{T,N,Array{T,N}} end

Type representing parametric arrays of type A. Subtypes:

• TrivialParamArray
• ConsecutiveParamArray
• GenericParamVector
• GenericParamMatrix
• BlockParamArray

Also acts as a constructor according to the following rules:

• ParamArray(A::AbstractArray{<:Number}) -> ParamNumber
• ParamArray(A::AbstractArray{<:Number},plength::Int) -> TrivialParamArray
• ParamArray(A::AbstractVector{<:AbstractArray}) -> ParamArray
• ParamArray(A::AbstractVector{<:AbstractSparseMatrix}) -> ParamSparseMatrix
• ParamArray(A::AbstractArray{<:ParamArray}) -> BlockParamArray

abstract type ParamBlock{A} end

Type representing cell-wise quantities defined during the integration routine. They are primarily used when lazily evaluating parametric quantities on the mesh. The implementation of the lazy interface mimics that of ArrayBlock in Gridap. Subtypes: -GenericParamBlock -TrivialParamBlock

struct ParamFunction{F,P} <: AbstractParamFunction{P}
  fun::F
  params::P
end

Representation of parametric functions with domain a parametric space. Given a function f : Ω₁ × ... × Ωₙ × D, where D is a ParamSpace, the evaluation of f in μ ∈ D returns the restriction of f to Ω₁ × ... × Ωₙ

const ParamMatrix{T} = ParamArray{T,2}

struct ParamNumber{T<:Number,A<:AbstractVector{T}} <: AbstractParamData{T,1}
  data::A
end

Used as a wrapper for non-array structures, e.g. factorizations or numbers

struct ParamSpace{P<:AbstractVector{<:AbstractVector},S<:SamplingStyle} <: AbstractSet{Realisation}
  param_domain::P
  sampling_style::S
end

Fields:

• param_domain: domain of definition of the parameters
• sampling_style: distribution on param_domain according to which we can sample the parameters (by default it is set to HaltonSampling)

ParamSpace(domain::Tuple;sampling=:halton) -> ParamSpace
ParamSpace(domain::AbstractVector{<:AbstractVector};sampling=:halton) -> ParamSpace

Parameter space with bounds domain, given either as a tuple (min₁,max₁,min₂,max₂,...) whose entries share the same type, or as a vector of intervals [[min₁,max₁],...]. sampling (:halton, :uniform, :normal, :latin_hypercube, :tensorial_uniform) sets the default distribution of realisation

abstract type ParamSparseMatrix{Tv,Ti,A<:AbstractSparseMatrix{Tv,Ti}
  } <: AbstractParamArray{Tv,2,A} end

Type representing parametric abstract sparse matrices of type A. Subtypes:

• ParamSparseMatrixCSC
• ParamSparseMatrixCSR

abstract type ParamSparseMatrixCSC{Tv,Ti} <: ParamSparseMatrix{Tv,Ti,SparseMatrixCSC{Tv,Ti}} end

Type representing parametric sparse matrices in CSC format. Subtypes:

• ConsecutiveParamSparseMatrixCSC
• GenericParamSparseMatrixCSC

abstract type ParamSparseMatrixCSR{Bi,Tv,Ti} <: ParamSparseMatrix{Tv,Ti,SparseMatrixCSR{Bi,Tv,Ti}} end

Type representing parametric sparse matrices in CSR format. Subtypes:

• ConsecutiveParamSparseMatrixCSR
• GenericParamSparseMatrixCSR

const ParamVector{T} = ParamArray{T,1}

struct ParamVectorWithEntryInserted{T,A} <: ParamVector{T}
  a::A
  index::Int
  value::Vector{T}
end

struct ParamVectorWithEntryRemoved{T,A} <: ParamVector{T}
  a::A
  index::Int
end

struct Realisation{P<:AbstractVector} <: AbstractRealisation
  params::P
end

Represents standard parametric realisations, i.e. samples extracted from a given parameter space. The field params is most commonly a vector of vectors. When the parameters are scalars, they still need to be defined as vectors of vectors of unit length. In other words, we treat the case in which params is a vector of numbers as the case in which params is a vector of one vector.

abstract type SamplingStyle end

Subtypes:

• UniformSampling
• NormalSampling
• HaltonSampling
• LatinHypercubeSampling
• UniformTensorialSampling

abstract type Snapshots{T,N,I,R} <: AbstractSnapshots{T,N} end

Type representing a collection of parametric abstract arrays of eltype T, that are associated with a realisation of type R. Unlike AbstractParamArray, which are arrays of arrays, subtypes of Snapshots are arrays of numbers.

const SparseSnapshots{T,N,I<:AbstractSparseDofMap,R} = Snapshots{T,N,I,R}

Snapshots of sparse matrices (e.g. Jacobians), storing their nonzero entries

struct TensorialUniformSampling <: SamplingStyle end

Sampling according to a tensorial uniform distribution

const TransientBlockSnapshots{S<:TransientSnapshots,N} = BlockSnapshots{S,N}

const TransientGenericSnapshots{T,N,I,R<:TransientRealisation,A,B} = GenericSnapshots{T,N,I,R,A,B}

struct TransientParamFunction{F,P,T} <: AbstractParamFunction{P}
  fun::F
  params::P
  times::T
end

Representation of parametric functions with domain a transient parametric space. Given a function f : Ω₁ × ... × Ωₙ × D × [t₁,t₂], where [t₁,t₂] is a temporal domain and D is a ParamSpace, or equivalently f : Ω₁ × ... × Ωₙ × D × [t₁,t₂], where D is a TransientParamSpace, the evaluation of f in (μ,t) ∈ D × [t₁,t₂] returns the restriction of f to Ω₁ × ... × Ωₙ

struct TransientParamSpace{P<:ParamSpace,T} <: AbstractSet{TransientRealisation}
  parametric_space::P
  temporal_domain::T
end

Fields:

• parametric_space: underlying parameter space
• temporal_domain: underlying temporal space

It represents, in essence, the set of tuples (p,t) in parametric_space × temporal_domain

TransientParamSpace(domain,times::AbstractVector{<:Real};sampling=:halton) -> TransientParamSpace

Space of parameters with bounds domain (see ParamSpace), and time grid times (e.g. t0:dt:tf). Only the parameters are sampled

abstract type TransientRealisation{P<:Realisation,T<:Real} <: AbstractRealisation end

Represents temporal parametric realisations, i.e. samples extracted from a given parameter space for every time step in a temporal range. The most obvious application of this type are transient PDEs, where an initial condition is given. Following this convention, the initial time instant is kept separate from the other time steps.

struct TransientRealisationAt{P,T} <: TransientRealisation{P,T}
  params::P
  t::Base.RefValue{T}
end

Represents a GenericTransientRealisation{P,T} at a certain time instant t. To avoid making it a mutable struct, the time instant t is stored as a Base.RefValue{T}.

const TransientSnapshots{T,N,I,R<:TransientRealisation} = Snapshots{T,N,I,R}

Transient specialization of a Snapshots

Subtypes:

• TransientSnapshotsWithIC

struct TransientSnapshotsWithIC{T,N,I,R,A,B<:TransientSnapshots{T,N,I,R}} <: TransientSnapshots{T,N,I,R}
  initial_param_data::A
  snaps::B
end

Stores a TransientSnapshots snaps alongside a parametric initial condition initial_param_data

const TransientSparseSnapshots{T,N,I<:AbstractSparseDofMap,R<:TransientRealisation} = TransientSnapshots{T,N,I,R}

Transient version of SparseSnapshots

struct TrivialParamArray{T<:Number,N,A<:AbstractArray{T,N}} <: ParamArray{T,N}
  data::A
  plength::Int
end

Wrapper for a non-parametric array data that we wish assumed a parametric length

struct TrivialParamBlock{A} <: ParamBlock{A}
  data::A
  plength::Int
end

Wrapper for a non-paramentric quantity data that we wish assumed a parametric length plength

struct UniformSampling <: SamplingStyle end

Sampling according to a uniform distribution

GenericParamArray(A::AbstractArray{<:AbstractArray}) -> AbstractParamArray

Parameterised array whose entries are the arrays in A, one per parameter. Unlike a ConsecutiveParamArray, the entries can have different sizes

change_mode(a::AbstractMatrix,np::Integer) -> AbstractMatrix

Converts the space-mode unfolding a of transient snapshots with np parameters into their time-mode unfolding (time steps × (space DOFs, parameters))

eltype2(a) -> Type

Returns the eltype of eltype(a), i.e. it extracts the eltype of a parametric entry of a

find_param_length(a...) -> Int

Returns the parametric length of all parametric quantities. An error is thrown if there are no parametric quantities or if at least two quantities have different parametric length

get_all_data(A::ParamArray) -> AbstractArray{<:Any}

Returns all the entries stored in A, assuming A stores its entries consecutively

get_at_time(r::GenericTransientRealisation,time) -> TransientRealisationAt

Returns a TransientRealisationAt from a GenericTransientRealisation at a time instant specified by time

get_at_timestep(r::GenericTransientRealisation,timestep::Int) -> TransientRealisationAt

Restriction of r to its timestep-th time; timestep = 0 is the initial time

get_final_time(r::GenericTransientRealisation) -> Real

get_initial_param_data(s::TransientSnapshots) -> AbstractParamArray

Initial conditions of the transient snapshots s

get_initial_time(r::GenericTransientRealisation) -> Real

get_param_data(a) -> Any

Returns the parametric data of a, usually in the form of a AbstractVector or a NTuple

get_param_entry!(v::AbstractVector,A::AbstractParamArray,i...) -> AbstractVector

In-place version of get_param_entry

get_param_entry(A::AbstractParamArray{T},i...) where T -> Vector{eltype(T)}

Returns a vector of the entries of A at index i, for every parameter. The length of the output is equals to param_length(A)

get_params(r::AbstractRealisation) -> Realisation

get_realisation(s::AbstractSnapshots) -> AbstractRealisation

Returns the realisations associated to the snapshots s

get_times(r::TransientRealisation) -> Any

inneraxes(A::AbstractParamArray) -> Tuple{Vararg{Base.OneTo}}

Returns the axes of A for a single parameter

innerlength(A) -> Int

Returns the length of A for a single parameter. The total entries of A is equals to param_length(A)*innerlength(A)

lazy_param_getindex(a,index::Int) -> AbstractArray

Lazily extracts the index-th parameter from the parameterised cell array a

lazy_testitem(a) -> AbstractArray

Same as lazy_param_getindex(a,1)

local_parameterise(a,plength::Integer) -> GenericParamBlock

Cell-wise parameterisation of a: a block storing plength independent copies of a (or the entries of a, if it is already a collection of plength arrays)

num_params(r::AbstractRealisation) -> Int

num_space_dofs(s::Snapshots) -> Integer

Total number of spatial DOFs of s, i.e. prod(space_dofs(s))

get_times(r::TransientRealisation) -> Int

param_cat(a::AbstractVector) -> Any

Concatenates along the parameter dimension a vector of realisations, parameterised arrays or snapshots

param_eachindex(a,i::Integer) -> Any

Returns the parametric range of a 1:param_length(a)

param_getindex(a,i::Integer) -> Any

Returns the parametric entry of a at the index i ∈ {1,...,param_length(a)}

param_length(a) -> Int

Returns the parametric length of a

param_setindex!(a,v,i::Integer) -> Any

Sets the parametric entry of a to v at the index i ∈ {1,...,param_length(a)}

parameterise(a,plength::Integer) -> Any

Returns a quantity with parametric length plength from a. When a already possesses a parametric length, i.e. it is a parametrized quantity, it returns a

parameterise(f::Function,r::Realisation) -> ParamFunction
parameterise(f::Function,r::TransientRealisation) -> TransientParamFunction

Method that parameterises an input quantity by a realisation r

realisation(p::ParamSpace;nparams=1,sampling=get_sampling_style(p),kwargs...) -> Realisation
realisation(p::TransientParamSpace;nparams=1,sampling=get_sampling_style(p),kwargs...) -> TransientRealisation

Extraction of a set of nparams parameters from a given parametric space, by default according to the sampling strategy specified in p.

select_all_data(data::AbstractArray,prange) -> AbstractArray

Restriction of the snapshot data data to the parameters of index prange

select_param_data(data::AbstractParamArray,prange) -> AbstractParamArray

Restriction of the parameterised snapshot data data to the parameters of index prange

select_snapshots(s::AbstractSnapshots,pindex) -> AbstractSnapshots

Restriction of s to the parameters of index pindex

select_times(s::TransientSnapshots,tindex) -> TransientSnapshots

Restriction of s to the time steps of index tindex

shift!(r::TransientRealisation,δ::Real) -> Nothing

In-place uniform shifting by a constant δ of the temporal domain in the realisation r

space_dofs(s::Snapshots{T,N}) where {T,N} -> NTuple{N-1,Integer}

Returns the spatial size of the snapshots