Introduction

This page describes basic requirements for multi-dimensional array (MD array) template arguments in Intrepid. MD array is a fundamental concept for managing a wide range of numerical data arising in PDE-based simulations. An MD array is a collection of members of a given scalar data type that are identified through a multi-index. Therefore, allowing for an MD array template argument provides a convenient mechanism to share numerical data between Intrepid and user applications.

The scalar data type members of a multi-dimensional array are stored in a contiguous block of memory. Contiguous memory storage is not necessary to the concept of an array; however, in order to achieve the best performance from cache-based computer memory systems contiguity of member storage has proven to be essential.

Definitions

The following rules and definitions apply to all MD arrays used as template arguments in Intrepid.

A scalar value that is uniquely identified by a set of interegs {i0,i1,...,iN} is called a multi-indexed value;
The set of all multi-indexed values such that 0 <= ik < dim_k is called MD array;
The integer ik is the kth index of the MD array; the N-tuple {i0,...,iN} is the multi-index of the MD array;
The integer dim_k is the kth dimension of the MD array; the N-tuple {dim_0,...,dim_N} is the multi-dimension of the MD array
The integer N+1 is the rank of the MD array;
A map {i0,...,iN} -> {0,1,2,...} from the set of all multi-indices to the set of the natural numbers is called enumeration of the MD array;
The numerical position of an element indexed by {i0,...,iN}, established by the enumeration is called ordinal number of that element or simply ordinal.

Enumeration of all MD arrays passed as template arguments to Intrepid must follow the natural lexicographical order: the leftmost index i0 changes last and the rightmost index iN changes first. In summary, an MD array pased to Intrepid should comply with the following rules:

the indices are zero-based;
dimensions are counted from 0; e.g., a rank-4 array has dimensions {dim_0,dim_1,dim_2,dim_3}
the enumeration is induced by the natural lexicographical order;
the MD array is not strongly type on its dimensions and rank.

MD Array interface

An MD array type passed as a template argument to Intrepid is expected to implement the following minimal interface:

int rank() - returns number of dimensions
int dimension(dim_k) - returns the kth dimension (dimensions are dim0, dim1, etc.)
int size() - returns size, i.e., dim0*dim1*...*dim_k
const Scalar& operator(i,j,...,k) - const accessor using multi-index
Scalar& operator(i,j,...,k) - non-const accessor using multi-index
const Scalar& operator[i] - const accessor using the ordinal of the array element
Scalar& operator[i] - non-const accessor using the ordinal of the array element

MD Array notation and examples

In addition to the generic index and dimension notation ik and dim_k it is convenient to introduce data-specific notation for indices and dimensions of MD arrays that recur in PDE-based simulation codes.

 |-------------------------------------------------------------------------------------------------|
 |   Index type              | Dimension |  Description                                            |
 |---------------------------|-----------|---------------------------------------------------------|
 |   point                   |     P     |  number of points stored in an MD array                 |
 |   vertex                  |     V     |  number of nodes stored in an MD aray                |
 |   field                   |     F     |  number of fields stored in an MD array                 |
 |   basis field             |     B     |  number of basis fields stored in an MD array           |
 |   cell                    |     C     |  number of cells stored in an MD array                  |
 |   field coordinate        |     D     |  space dimension                                        |
 |   derivative ordinal      |     K     |  cardinality of the set of kth derivatives              |
 |-------------------------------------------------------------------------------------------------|

Remarks

The totality of all derivatives whose order equals k (OPERATOR_Dk in Intrepid) forms a multiset; see http://mathworld.wolfram.com/Multiset.html . In Intrepid this multiset is enumerated using the lexicographical order of the partial derivatives; see getDkEnumeration() for details.

This notation is used throughout Intrepid's documentation as a means to add further clarity to the specifications of MD array passed to and returned from Intrepid methods. The following is a list of typical MD arrays that arise in PDE-based simulation codes:

 |-------------------------------------------------------------------------------------------------|
 | Rank | Multi-dimension | Multi-index    | Description                                           |
 |-------------------------------------------------------------------------------------------------|
 |  1   | (P)             | (p)            | Scalar (rank 0) field evaluated at P points           |
 |  2   | (P,D)           | (p,d)          | Vector (rank 1) field evaluated at P points           |
 |  3   | (P,D,D)         | (p,d,d)        | Tensor (rank 2) field evaluated at P points           |           
 |-------------------------------------------------------------------------------------------------|
 |  2   | (P,F)           | (p,f)          | F scalar fields evaluated at P points                 |
 |  3   | (P,F,D)         | (p,f,d)        | F vector fields evaluated at P points                 |
 |  4   | (P,F,D,D)       | (p,f,d,d)      | F tensor fields evaluated at P points                 |
 |-------------------------------------------------------------------------------------------------|
 |  3   | (P,F,K)         | (p,f,k)        | kth deriv. of F scalar fields evaluated at P points   |       
 |  4   | (P,F,D,K)       | (p,f,d,k)      | kth deriv. of F vector fields evaluated at P points   |       
 |  5   | (P,F,D,D,K)     | (p,f,d,d,k)    | kth deriv. of F tensor fields evaluated at P points   |           
 |-------------------------------------------------------------------------------------------------|
 |  3   | (C,V,D)         | (c,v,d )       | Vertex coords. of C cells having V vertices each      |
 |  3   | (C,P,D)         | (c,p,d )       | Coords. of C*P points in C cells, P per cell          |
 |-------------------------------------------------------------------------------------------------|

MD Array implementaion in Intrepid

The FieldContainer class provides an implementation of an MD array type that is used throughout Intrepid. A FieldContainer object is templated on a Scalar type. Its rank and dimensions are runtime parameters, i.e., a FieldContainer is not strongly typed on rank and dimension.