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.

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}
  touched::Array{Bool,N}
end

Block container for Snapshots of type S in a MultiField setting. This type is conceived similarly to ArrayBlock in Gridap

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 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} <: Snapshots{T,N,I,R}
  data::A
  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)

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.

struct ReshapedSnapshots{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

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.

Subtypes:

• SteadySnapshots
• TransientSnapshots

const SteadySnapshots{T,N,I,R<:Realisation} = Snapshots{T,N,I,R}

struct TensorialUniformSampling <: SamplingStyle end

Sampling according to a tensorial uniform distribution

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

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
• ModeTransientSnapshots

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

Stores a TransientSnapshots snaps alongside a parametric initial condition initial_data

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

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_final_time(r::GenericTransientRealisation) -> Real

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(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)

num_params(r::AbstractRealisation) -> Int

get_times(r::TransientRealisation) -> Int

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.

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

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

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

Returns the spatial size of the snapshots