Commit 3616b5f0 authored by Chris Cantwell's avatar Chris Cantwell

Merge branch 'feature/dev-guide-draft-mk' into 'master'

Feature/dev guide draft mk

See merge request !2
parents b1461b45 994712df
No preview for this file type
......@@ -64,6 +64,13 @@ publisher={John Wiley \& Sons}
year = 1997
}
@book{HGG,
title = "Spectral Methods for Time-Dependent Problems",
author = "Jan Hesthaven and Sigal Gottlieb and David Gottlieb",
publisher = "Cambridge University Press",
year = "2007"
}
@book{Demmel97,
author = "James W. Demmel",
title = "Applied Numerical Linear Algebra",
......@@ -72,6 +79,20 @@ publisher = "SIAM",
year = 1997
}
@book{Heath,
title = "Scientific Computing: An Introductory Survey",
author = "Michael T. Heath",
publisher = "McGraw-Hill Companies",
year = "2002"
}
@book{CockburnKS,
title = "Discontinuous Galerkin Methods: Theory, Computation and Applications",
author = "Bernardo Cockburn and George Karniadakis and Chi-Wang Shu",
publisher = "Springer-Verlag",
year = "2000"
}
@article{Pa84,
title={A spectral element method for fluid dynamics: laminar flow in a channel expansion},
author={Patera, Anthony T},
......@@ -156,7 +177,7 @@ publisher = "SIAM",
}
@article{WiFaVi14,
title={{PyFR}: An open source framework for solving advectiondiffusion type problems on streaming architectures using the flux reconstruction approach},
title={{PyFR}: An open source framework for solving advection-diffusion type problems on streaming architectures using the flux reconstruction approach},
author={Witherden, FR and Farrington, AM and Vincent, PE},
journal={Computer Physics Communications},
year={2014},
......@@ -354,6 +375,14 @@ polynomial interpolation in a simplex},
pages = {1707-1720},
}
@Article{TaylorW99,
author = {Taylor, M. and Wingate, B.A.},
title = {The Fekete collocation points for triangular spectral elements},
journal = {Journal on Numerical Analysis},
year = {1998},
}
@article{Duffy82,
author = "Duffy, M.G.",
title = "Quadrature over a pyramid or cube of integrands
......@@ -374,5 +403,33 @@ polynomial interpolation in a simplex},
year = "2014"
}
@article{KirbyS06,
author = "Robert M. Kirby and Spencer J. Sherwin",
title = "Aliasing Errors Due to Quadratic Non-Linearities On Triangular Spectral/hp Element Discretisations",
journal = "Journal of Engineering Mathematics",
volume = "56",
pages = "273-288",
year = "2006"
}
@book{BorisenkoTS,
author = "A.I. Borisenko and I.E. Tarapov and R.A. Silverman (Translator)",
title = "Vector and Tensor Analysis with Applications",
publisher = "Dover Books on Mathematics",
year = "2012"
}
@book{BStroustrup,
title={The C++ Programming Language (Fourth Edition)},
author={Bjarne Stroustrup},
year={2013},
publisher={Addison-Wesley Professional}
}
@book{SMeyers,
title={Effective C++: 55 Specific Ways to Improve Your Programs and Designs (Third Edition)},
author={Scott Meyers},
year={2005},
publisher={Addison-Wesley Professional}
}
......@@ -2,12 +2,30 @@
\DeclareOldFontCommand{\bf}{\normalfont\bfseries}{\mathbf}
\usepackage{makeidx}
\usepackage{hyperref}
\hypersetup{
colorlinks=true,
linkcolor=blue,
filecolor=magenta,
urlcolor=cyan,
}
\urlstyle{same}
\makeindex
\newcommand\nek{\emph{Nektar++}}
\newcommand\shp{spectral/$hp$}
\newcommand\Shp{Spectral/$hp$}
\newcommand{\GIT}{\textit{git}}
\def\code#1{\texttt{#1}}
\newcommand\hlink{\hyperlink}
\newcommand\htarget{\hypertarget}
\title{A Programmer's Guide to Nektar++}
\makeatletter\@addtoreset{chapter}{part}\makeatother%
\begin{document}
%\frontmatter
......@@ -25,7 +43,7 @@
\titlepage
\fi
\clearpage
%\clearpage
%\ifx\HCode\undefined
%\tableofcontents*
......@@ -35,16 +53,33 @@
%\input{test.tex}
\tableofcontents
\input{preface/preface.tex}
%
\input{introduction/introduction.tex}
%
%\input{prelims/prelims.tex}
\input{prelims/prelims.tex}
%
\part{Building-Blocks of Our Framework (Inside the Library)} \label{part:library}
\input{library/library-master.tex}
%%
\part{Solvers} \label{part:solvers}
\input{solvers/solvers-master.tex}
%%
\part{Utilities} \label{part:utilities}
\input{utilities/utilities-master.tex}
\bibliographystyle{plain}
\bibliography{developers-guide}
\printindex
\end{document}
This diff is collapsed.
%
\section{The Fundamental Algorithms within Collections}
\ No newline at end of file
\section{The Fundamental Algorithms within Collections}
As stated in the introduction, this section of this guide is structured in question-answer form. This is not meant to capture every possible
question asked of us on the {\nek} users list; however, this set of (ever-growing) questions are meant to capture the ``big ideas'' that developers
want to know about how Collections work and how they can be used.
In this section, we will through question and answer format try to cover the following basic algorithmic concepts that are found within
the Collections part of the library:
\begin{itemize}
\item xx
\end{itemize}
With the big ideas in place, let us now start into our questions.
\paragraph{Question:}
%
\section{The Fundamentals Behind Collections}
\ No newline at end of file
\section{The Fundamentals Behind Collections}
The concept of ``collections'' is that there are many operations that we (conceptually) accomplish on an element-by-element basis that can be aggregated together into a single operation. The
basic idea is that whenever you see a piece of code that consists of a loop in which, in the body of the loop, you are accomplishing the same operation (e.g. function evaluation) based upon
an input variable tied to the loop index -- you may be able to make the operation a ``collection''. For instance, consider if you were given the following snippet of code in Matlab notation:
\vspace{-5mm}
\begin{verbatim}
do j = 1:N,
y(j) = dot(a,x(:,j))
end
\end{verbatim}
\noindent where $y$ is a row vector of length $N$, $x$ is an $M \times N$ matrix and $a$ is a row vector of length $M$. Note that in this code snipped, the
vector $a$ remains constant; only the vector $x$ involved in the dot product is changing based upon the index (i.e. selecting a column of the array).
From linear algebra, you might recognize this as the way we accomplish the product of a row vector with a matrix -- we march through the matrix accomplishing
dot products. Although these two things are equivalent mathematically, they are not equivalent computationally {\em from the perspective of computational efficiency}. Most linear algebra operations within {\nek} are done using BLAS -- Basic Linear Algebra Subroutines -- a collection of specialized routines
for accomplishing Level 1 (single loop), Level 2 (double nested loop) and Level 3 (triple nested loop) operations. A dot product is an example of a Level 1
BLAS operation; A matrix-vector multiplication is an example of a Level 2 BLAS operation; and finally a matrix-matrix multiplication is an example of a Level 3
BLAS operation. The general rule of thumb is that as you move up the levels, the operations can be made more efficient (using various algorithmic
reorganization and memory layout strategies). Hence when you see a loop over Level 1 BLAS calls (like in the above piece of code), you should always
ask yourself if this could be transformed into a Level 2 BLAS call. Since the vector $a$ is not changing, this piece of code should be replaced with an
appropriate vector-matrix multiply.
As seen in StdRegions and LocalRegions, we often conceptually thing of many of our basic building block operations as being elemental. We have
elemental basis matrices, local stiffness matrices, etc. Although it is correct to implement operations as an iterator over elements in which you accomplish
an action like evaluation (done by taking a basis evaluation matrix times a coefficient vector), this operation can be made more efficient by ganging all these
elemental operations together into a {\em collection}.
As mentioned earlier, one of the caveats of this approach is that you must assume some level of consistency of the operation. For instance, in the case of physical evaluations, you must assume that a collection consists of elements that are all of the same time, have the same basis number and ordering, and are evaluated at the same set of points -- otherwise the operation cannot be expressed as a single (basis) matrix multiplied by a matrix whose columns consist of the modes
of all the elements who have joined the collective operation.
As will be seen in the data structure and algorithms sections of this discussion, these assumptions lead us to two fundamental types of collections: collections that live at the StdRegions level (i.e. collection operations that act on a group of elements as represented in reference space) and collections that live at the LocalRegions level (i.e. collection operations that act on a group of elements as represented in world space).
\ No newline at end of file
%
\section{The Fundamental Algorithms within LocalRegions}
\ No newline at end of file
\section{The Fundamental Algorithms within LocalRegions}
As stated in the introduction, this section of this guide is structured in question-answer form. This is not meant to capture every possible
question asked of us on the {\nek} users list; however, this set of (ever-growing) questions are meant to capture the ``big ideas'' that developers
want to know about how LocalRegions work and how they can be used.
In this section, we will through question and answer format try to cover the following basic algorithmic concepts that are found within
the LocalRegions part of the library:
\begin{itemize}
\item xx
\end{itemize}
With the big ideas in place, let us now start into our questions.
\paragraph{Question:}
%
\section{The Fundamental Data Structures within LocalRegions}
As mentioned earlier, in almost all object-oriented languages (which includes $C++$), there exists the concepts of {\em class attributes} and {\em object attributes}. For a summary of attributes and access patterns, please review Section \ref{sec:stdregions-datastructures}.
Within the LocalRegions directory of the library, there exists a class inheritance hierarchy designed to try to encourage re-use of core
algorithms (while simultaneously trying to minimize duplication of code). We present this class hierarchy in Figure \ref{localregions:localclasstree}.
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/expansiontree.pdf}
\caption{Figure local regions tree}
\caption{Class hierarchy derived from Expansion, the base class of the LocalRegions Directory.}
\label{localregions:localclasstree}
\end{figure}
\ No newline at end of file
\end{figure}
As is seen in Figure \ref{stdregions:localclasstree}, the LocalRegions hierarchy consists of three levels: the base level from which all
LocalRegion objects are derived is Expansion. This object is then specialized by dimension, yielding Expansion0D,
Expansion1D, Expansion2D and Expansion3D. The dimension-specific objects are then specialized based upon
shape.
The object attributes (variables) at various levels of the hierarchy can be understood in light of Figure \ref{stdregions:stdexpansion}.
At its core, an expansion is a means of representing a function over a world-space region evaluated at a collection of point positions.
The various data members hold information to allow all these basic building blocks to be specified. Many of the attributes are
inherited from StdRegions as they are not unique to LocalRegions; however, each LocalRegion Expansion is uniquely defined based
upon its geometric factors (which it stores via SpatialDomain information).
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/LocalExpansion.png}
\caption{Diagram to help understand the various data members (object attributes) contained within LocalRegions and how they connect with the mathematical representation presented earlier. Recall that a LocalRegion {\em is-a} StdRegion and {\em has-a} SpatialDomain.}
\label{localregions:localexpansion:stdexpansion}
\end{figure}
The various private, protected and public data members contained within LocalRegions are provided in the subsequent sections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Expansion}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Expansion\$D for various Dimensions}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Shape-Specific Expansions}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%
\section{The Fundamentals Behind LocalRegions}
\ No newline at end of file
\section{The Fundamentals Behind LocalRegions}
The idea behind local regions is strongly connected to that of standard regions, but from the top-down perspective. As an example: in standard regions, we only had to consider one type of triangle, the one that is straight-sided, right-angled, and whose principle horizontal and vertical sides where aligned with the coordinate axes. Of course, meshes of elements consist of elements that may are may not be right-angled, planar-sided, etc. The starting point for us is the question of how to build build basis functions that exist of a {\em world-space} element -- that is, an element whose vertex positions lie in the engineering (PDE) coordinate system of interest. Such an expansion is a local region. In {\nek}, each local region {\em is-a} standard region and {\em has-a} spatial domain data structure. The local region inherits common expansion methods from its standard region parent, and it uses its spatial domain information to specialize its operators to its local coordinate system.
%
\section{The Fundamental Algorithms within MultiRegions}
\ No newline at end of file
\section{The Fundamental Algorithms within MultiRegions}
As stated in the introduction, this section of this guide is structured in question-answer form. This is not meant to capture every possible
question asked of us on the {\nek} users list; however, this set of (ever-growing) questions are meant to capture the ``big ideas'' that developers
want to know about how MultiRegions work and how they can be used.
In this section, we will through question and answer format try to cover the following basic algorithmic concepts that are found within
the MultiRegions part of the library:
\begin{itemize}
\item xx
\end{itemize}
With the big ideas in place, let us now start into our questions.
\paragraph{Question:}
%
\section{The Fundamental Data Structures within MultiRegions}
As mentioned earlier, in almost all object-oriented languages (which includes $C++$), there exists the concepts of {\em class attributes} and {\em object attributes}. For a summary of attributes and access patterns, please review Section \ref{sec:stdregions-datastructures}.
Within the MultiRegions directory of the library, there exists a class inheritance hierarchy designed to try to encourage re-use of core
algorithms (while simultaneously trying to minimize duplication of code). We present this class hierarchy in Figure \ref{multiregions:multiregionstree}.
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/multiregiontree.pdf}
\caption{Figure 1}
\caption{Class hierarchy derived from ExpList, the base class of the MultiRegions Directory.}
\label{multiregions:multiregionstree}
\end{figure}
At its core, the items contained within MultiRegions are meant to represent sets of LocalRegions. In the most abstract sense, an
ExpList is merely a set of LocalRegion objects that may or may not have any relevance to each other. We then, as we do in
other parts of the library, specialize on the dimension of the objects these sets will contain. At the subsequent levels of the
hierarchy, we now involve information about we want to treat a collection of elements when evaluating them as a {\em field}.
We consider a {\em field} to be the representation of a function over a (sub--)domain. A domain consists of a collection of elements
that are {\em connected} (that is, they form a contiguous region in space). We think of the region of space as being tiled by elements
over which expansions are build. If we consider a MultiRegion field to be a collection of these expansions with no constraints on their
continuity, we arrive at the DisContField family of class definitions (which vary by dimension). For the currently available solvers within
{\nek}, this level of field is used for the solution of PDEs via the discontinuous Galerkin (dG) and Flux-Reconstruction (FR) methods.
If we consider a function as a collection of expansion in which we require continuity (in {\nek}, only $C^0$ continuity), then we employ
a further derived class called ContField (which again varies by dimension). For the currently available solvers
within {\nek}, this level of field is used for the solution of PDEs via the continuous Galerkin (cG) method.
Since many of the operations at the continuous field level do not rely upon the continuity of the field, we have structured the
continuous MultiRegion object as with an {\em is-a} relationship with the DisContFields.
The various private, protected and public data members contained within MultiRegions are provided in the subsequent sections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of ExpList}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of ExpList\$D for various Dimensions}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Discontinuous Field Expansions}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Continuous Field Expansions}
\paragraph{Private:}
\paragraph{Protected:}
%
\section{The Fundamental Algorithms within SpatialDomains}
\ No newline at end of file
\section{The Fundamental Algorithms within SpatialDomains}
As stated in the introduction, this section of this guide is structured in question-answer form. This is not meant to capture every possible
question asked of us on the {\nek} users list; however, this set of (ever-growing) questions are meant to capture the ``big ideas'' that developers
want to know about how SpatialDomains work and how they can be used.
In this section, we will through question and answer format try to cover the following basic algorithmic concepts that are found within
the SpatialDomains part of the library:
\begin{itemize}
\item xx
\end{itemize}
With the big ideas in place, let us now start into our questions.
\paragraph{Question:}
%
\section{The Fundamental Data Structures within SpatialDomains}
\label{sec:spatialdomains-datastructures}
As mentioned earlier, in almost all object-oriented languages (which includes $C++$), there exists the concepts of {\em class attributes} and {\em object attributes}. For a summary of attributes and access patterns, please review Section \ref{sec:stdregions-datastructures}.
Within the SpatialDomains directory of the library, there exists a class inheritance hierarchy designed to try to encourage re-use of core
algorithms (while simultaneously trying to minimize duplication of code). We present this class hierarchy in Figure \ref{spatialdomains:geomtree}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reference to World-Space Mapping}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Geometry}
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/geomtree.pdf}
\caption{Figure geometry tree}
\caption{Class hierarchy derived from Geometry, the base class of the SpatialDomains Directory.}
\label{spatialdomains:geomtree}
\end{figure}
At its core, the items contained within SpatialDomains are meant to represent the mapping of StdRegion information into world-space. The various attributes contained herein related to this geometric (mesh, curvature and mapping) information. The various private, protected and public data members contained within StdRegions are provided in the subsequent sections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Geometry}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Geometry\$D for various Dimensions}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables at the Level of Shape-Specific Geometry Information}
\paragraph{Private:}
\paragraph{Protected:}
\paragraph{Public:}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reference to World-Space Mapping}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Geometry}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{GeomFactors}
......
%
\section{The Fundamentals Behind SpatialDomains}
\label{sec:spatialdomains-fundamentals}
As mentioned in our discussions of the fundamentals of StdRegions (i.e. Section \ref{sec:stdregions-fundamentals}), one of the most
fundamental tools from calculus that we regularly employ is the idea of mapping from general domains to canonical domains. General
domains are the regions in world space over which we want to solve engineering problems, and thus want to be able to take derivatives and
compute integrals. But as we learned in calculus, it is often non-trivial to accomplish differentiation or integration over these regions. We resort
to the mapping arbitrary domains back to canonical domains over which we can define various operations. We introduced our canonical domains,
which we call standard regions, in Chapter \ref{chap:stdregions}. We refer to our world space regions as local regions, which we will present
in Chapter \ref{chap:localregions}. How these two are connected are via SpatialDomains.
As will be further discussed in Section \ref{sec:spatialdomains-datastructures}, there are two fundamental purposes served by SpatialDomains: (1) holding
basic geometric information (e.g. vertex values and curvature information) and (2) holding geometric factors information. The former information relates to
the geometric way we map standard regions to local regions. The latter information relates to how we use this map to allow us to accomplish
differentiation and integration of functions in world space via operations on standard regions with associated map (geometric) information. In this section,
we will highlight the important mathematical principles that are relevant to this section. We will first discuss the mapping itself: vertex and curvature information
and how it is used. We will then discuss how geometric factor information is computed. We break this down into two subsections following the convention of the
code. We will first discussed what is labeled in the code as {\em Regular}, and denotes mappings between elements of the same dimension
(i.e. standard region triangles to 2D triangles in world space). Although our notation will be slightly different, we will use \cite{KaSh05} as our guide; we
refer the interested reader there for a more in-depth discussion of these topics.
We will then discuss what is labeled in the code as {\em Deformed}, and denotes the mappings
between standard region elements and their world space variants in a higher embedded dimension (i.e. standard region triangles to triangles lying on a
surface embedded in a 3D space representing a manifold). Since the manifold work within {\nek} was introduced as an area of research, we will
use \cite{CantwellYKPS14} as our guide. The notation therein is slightly different than that of \cite{KaSh05} because of the necessity to use
broader coordinate system transformation principles (e.g. covariance and contravariance of vectors, etc.). We will abbreviate the detailed
mathematical derivations here, but encourage the interested reader to review \cite{CantwellYKPS14} and references therein as needed. For those
unfamiliar with covariant and contravariant spaces, we encourage the reader to review \cite{BorisenkoTS}.
\subsection{Vertex and Curvature Mapping Information}
When we load in a mesh into {\nek}, elements are often described in world space based upon their vertex positions. In traditional FEM formats, this can be as
simple as a list of d-dimensional vertex coordinates, followed by a list of element definitions: each row holding four integers (in the case of tetrahedra) denoting
the four vertices in the vertex list that comprise an element. {\nek} uses an HTML-based geometry file with a more rich definition of the basic geometric
information that just described; we encourage developers and users to review our User Guide(s) for the organization and conventions used within our geometry
files. For the purposes of this section, the important pieces of information are as follows. Let us assume that for each element, we have through our MeshGraph
data structure (described in the next section) access to the vertex positions of an element. In general, each vertex $\vec{v}_j$ is a n-tuple of dimension $d$ denoting
the dimension in which the points are specified in world space. For example, when considering a quadrilateral on the 2D plane, our vertex points each contain
two coordinates denotes the x-- and y--coordinates. As shown in Figure \ref{spatialdomains:planarmap}, we can express the mapping between a world space
quadrilateral and the standard region quadrilateral on $[-1,1]\times[-1,1]$ via a bi-linear mapping function $\chi(\vec{\xi})$.
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/planarmap.pdf}
\caption{Reference space to world space mapping of a 2D quadrilateral to a straight-sided (2D) quadrilateral in the plane via a bi-linear (i.e., $Q(1)$) mapping.}
\label{spatialdomains:planarmap}
\end{figure}
In the case of segments, this mapping function $\chi(\vec{\xi})$ is a function of one variable and is merely an affine mapping. In two dimensions, the
mapping of a straight-sided triangle is a linear mapping (i.e., P(1) in the language of traditional finite elements -- a total degree $k=1$ space) and
the mapping of a straight-sided quadrilateral is a bi-linear mapping (i.e, Q(1) in the language of traditional finite elements -- a degree $k=1$ map along each
coordinate direction combined through tensor-product). In three dimensions, the mapping of a planar-sided tetrahedron is also a linear mapping, the
mapping of a planar-sided hexahedron is a tri-linear mapping, and the prism and pyramid are mathematically somewhere in-between these two canonical
types as given in \cite{KaSh05}. The key point is that in the case of straight-sided (or planar-sided) elements, the mapping between reference space and
world space can be deduced solely based upon the vertex positions. Furthermore in these cases,
as denoted in Figure \ref{spatialdomains:planarmap}, the form of the mapping function is solely determined by type (shape) of the element. If
only planar-sided elements are used, pre-computation involving the mapping functions can be done so that when vertex value information is available,
all the data structures can be finalized.
As presented in \ref{KaSh05}, there are many components of {\nek} that capitalize on the geometric nature of the basis functions we use. We often
speak in terms of vertex modes, edge modes, face modes and internal modes -- i.e., the coefficients that provide the weighting of vertex basis functions,
edge basis functions, etc. It is beyond the scope of this developer guide to go into all the mathematical details of their definitions, etc. However, we do
want to point out a few common developer-level features that are important. In the case of straight-sided (planar-sided) elements, the aforementioned
mapping functions can be fully described by vertex basis functions. The real benefit of this approach (of connecting the mapping representation with a
geometric basis) is seen when moving to curved elements.
Consider Figure \ref{spatialdomains:curvemap} in which we modify the example given above to accommodate on curved edge. From the
mathematical perspective, we know that the inclusion of this (quadratic) edge will require our mapping function to now be in $Q(2)$. If we were
not to use the fact that our basis is geometric in nature, we would be forced to form a Vandermonde system for a set of coefficients used
to combine the tensor-product quadratic functions (nine basis functions in all), and use the five pieces of information available to us (the four
vertex values and the one point $\vec{c}_0$ that informs the curve on edge $1$. As shown in Figure \ref{spatialdomains:curvemap}, we would
expect that this updated (to accommodate a curved edge) mapping function to consist of the bi-linear mapping
function with an additional term $C_1(\xi_1,\xi_2)$ that encompasses the new curvature information.
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/curvemap.pdf}
\caption{Reference space to world space mapping of a 2D quadrilateral to a curve (2D) quadrilateral in the plane via a bi-quadratic (i.e., $Q(2)$) mapping.}
\label{spatialdomains:curvemap}
\end{figure}
The basis we use, following \cite{KaSh05}, allows us to precisely specify $C_1(\xi_1,\xi_2)$ using the edge basis function associated with edge $1$, and
to use the point value $\vec{c}_0$ to specify the coefficient to be used. In the figure, we assume that the form of the function is collocating, but in practice
it need not be so.
In practice, edge (and face) information can be given either as a set of point positions in world space that correspond to a particular point distribution
in the reference element (i.e., evenly-spaced points or GLL points) or modal information corresponding to the geometric basis we use internally. Our
geometric file formats assume the former -- that curve information is provided to us as physical values at specified positions from which we infer (calculate)
the modal values and store these values within SpatialDomain data structures.
Assuming we now have, for each element, a way of specifying the mapping function $\chi(\vec{\xi})$, we can now move to how we compute the geometric
factors for regular as well as for deformed mappings.
\subsection{Regular Mappings: Geometric Factors}
\subsection{Regular}
$$
\vec{x} = (x_j)^T,\, j=1,\ldots,D
$$
$$
\vec{\xi} = (\xi_j)^T,\, j=1,\ldots,D
$$
$$
\vec{x} = \chi(\vec{xi})
$$
$$
{\bf J} = \frac{\partial x_i}{\partial \xi_j}
......@@ -34,10 +115,12 @@ gmat and jac
note that gmat is a tensor defined at each point, and jac is the determinant of the jacobian.
\cite{CantwellYKPS14}
\subsection{Deformed}
\subsection{Deformed Mappings: Geometric Factors}
%
\section{The Fundamental Algorithms within StdRegions}
\ No newline at end of file
\section{The Fundamental Algorithms within StdRegions}
As stated in the introduction, this section of this guide is structured in question-answer form. This is not meant to capture every possible
question asked of us on the {\nek} users list; however, this set of (ever-growing) questions are meant to capture the ``big ideas'' that developers
want to know about how StdRegions work and how they can be used.
In this section, we will through question and answer format try to cover the following basic algorithmic concepts that are found within
the StdRegions part of the library:
\begin{itemize}
\item xx
\end{itemize}
With the big ideas in place, let us now start into our questions.
\paragraph{Question:}
\ No newline at end of file
%
\section{The Fundamental Data Structures within StdRegions}
\label{sec:stdregions-datastructures}
In almost all object-oriented languages (which includes $C++$), there exists the concepts of {\em class attributes} and {\em object attributes}. Class attributes are those attributes shared by all object instances (both immediate and derived objects) of a particular class definition, and object attributes (sometimes called data members) are those attributes whose values vary from object to object and hence help to characterize (or make unique) a particular object. In $C++$, object attributes are specified a header file containing class declarations; within a class declaration, attributes are grouped by their accessibility: {\em public} attributes, {\em protected} attributes and {\em private} attributes. A detailed discussion of the nuances of these
categories are beyond the scope of this guide; we refer the interested reader to the following books for further details: \cite{BStroustrup,SMeyers}.
For our purposes, the main thing to appreciate is that categories dictate access patters within the inheritance hierarchy and to the ``outside" world
(i.e. access from outside the object). We have summarized the relationships between the categories and their accessibility in Tables
\ref{table:publicinheritance}, \ref{table:protectedinheritance} and \ref{table:privateinheritance} \footnote{These tables are based upon information provided at http://www.programiz.com/cpp-programming/public-protected-private-inheritance, accessed 6 April 2018.}.
\begin{table}[ht]
\begin{center}
\caption{Accessibility in Public Inheritance}
\begin{tabular}{c c c c}
\hline\hline
Accessibility & private variables & protected variables & public variables \\
\hline
Accessibility from own class? & yes & yes & yes \\
Accessibility from derived class? & no & yes & yes\\
Accessibility from 2nd derived class? & no & yes & yes\\
\end{tabular}
\end{center}
\label{table:publicinheritance}
\end{table}
\begin{table}[ht]