Commit b1461b45 authored by Chris Cantwell's avatar Chris Cantwell

Merge branch 'Current-Draft' into 'master'

Current draft

See merge request !1
parents 85a28cd6 06b2bdc1
SET(DEVGUIDESRC ${CMAKE_CURRENT_SOURCE_DIR})
SET(DEVGUIDE ${CMAKE_BINARY_DIR}/docs/developer-guide)
FILE(MAKE_DIRECTORY ${DEVGUIDE}/html)
FIND_PROGRAM(HTLATEX htlatex)
MARK_AS_ADVANCED(HTLATEX)
ADD_CUSTOM_TARGET(developer-guide-html
export TEXINPUTS=${CMAKE_SOURCE_DIR}//:${DEVGUIDESRC}//: &&
${HTLATEX} ${DEVGUIDESRC}/developers-guide.tex
"${DEVGUIDESRC}/styling.cfg,html,3,next,NoFonts"
WORKING_DIRECTORY ${DEVGUIDE}/html
)
# If tex4ht successful, create img dir and copy images across
FILE(GLOB_RECURSE imgfiles "img/*.png" "img/*.jpg" "*/img/*.png" "*/img/*.jpg")
ADD_CUSTOM_COMMAND(TARGET developer-guide-html
POST_BUILD COMMAND ${CMAKE_COMMAND} -E make_directory ${DEVGUIDE}/html/img)
FOREACH(img ${imgfiles})
ADD_CUSTOM_COMMAND(TARGET developer-guide-html
POST_BUILD COMMAND
${CMAKE_COMMAND} -E copy ${img} ${DEVGUIDE}/html/img)
ENDFOREACH()
FILE(GLOB_RECURSE pdffiles "*/img/*.pdf")
FIND_PROGRAM(CONVERT convert)
FOREACH(pdf ${pdffiles})
GET_FILENAME_COMPONENT(BASENAME ${pdf} NAME_WE)
ADD_CUSTOM_COMMAND(TARGET developer-guide-html
POST_BUILD COMMAND
${CONVERT} ${pdf} ${DEVGUIDE}/html/img/${BASENAME}.png)
ENDFOREACH()
FIND_PROGRAM(PDFLATEX pdflatex)
MARK_AS_ADVANCED(PDFLATEX)
FIND_PROGRAM(BIBTEX bibtex)
MARK_AS_ADVANCED(BIBTEX)
FIND_PROGRAM(MAKEINDEX makeindex)
MARK_AS_ADVANCED(MAKEINDEX)
ADD_CUSTOM_TARGET(developer-guide-pdf
export TEXINPUTS=${CMAKE_SOURCE_DIR}//: &&
${PDFLATEX} --output-directory ${DEVGUIDE} ${DEVGUIDESRC}/developers-guide.tex
COMMAND TEXMFOUTPUT=${DEVGUIDE} ${BIBTEX} ${DEVGUIDE}/developers-guide.aux
COMMAND TEXMFOUTPUT=${DEVGUIDE} ${MAKEINDEX} ${DEVGUIDE}/developers-guide.idx
COMMAND TEXINPUTS=${CMAKE_SOURCE_DIR}//:
${PDFLATEX} --output-directory ${DEVGUIDE} ${DEVGUIDESRC}/developers-guide.tex
COMMAND TEXINPUTS=${CMAKE_SOURCE_DIR}//:
${PDFLATEX} --output-directory ${DEVGUIDE} ${DEVGUIDESRC}/developers-guide.tex
WORKING_DIRECTORY ${DEVGUIDESRC}
)
This diff is collapsed.
\input{shared/devguide-preamble.tex}
\DeclareOldFontCommand{\bf}{\normalfont\bfseries}{\mathbf}
\newcommand\nek{\emph{Nektar++}}
\newcommand\shp{spectral/$hp$}
\newcommand\Shp{Spectral/$hp$}
\title{A Programmer's Guide to Nektar++}
\begin{document}
%\frontmatter
% Render pretty title page if not building HTML
\ifdefined\HCode
\begin{center}
\includegraphics[width=0.1\textwidth]{shared/img/icon-blue.png}
\end{center}
\maketitle
\begin{center}
\huge{Nektar++ Developer's Guide}
\end{center}
\else
\titlepage
\fi
\clearpage
%\ifx\HCode\undefined
%\tableofcontents*
%\fi
%
%\clearpage
%\input{test.tex}
\input{preface/preface.tex}
%
\input{introduction/introduction.tex}
%
%\input{prelims/prelims.tex}
%
\input{library/library-master.tex}
\bibliographystyle{plain}
\bibliography{developers-guide}
\end{document}
../library/StdRegions/img/afg002.pdf
\ No newline at end of file
../library/LibUtilities/img/basismemory.pdf
\ No newline at end of file
../library/LocalRegions/img/expansiontree.pdf
\ No newline at end of file
../library/SpatialDomains/img/geomtree.pdf
\ No newline at end of file
../library/MultiRegions/img/multiregiontree.pdf
\ No newline at end of file
../library/StdRegions/img/stdexpansiontree.pdf
\ No newline at end of file
../introduction/img/stdtolocal.pdf
\ No newline at end of file
../introduction/img/structure1.png
\ No newline at end of file
../introduction/img/structure2.png
\ No newline at end of file
This diff is collapsed.
%
\section{The Fundamental Algorithms within Collections}
\ No newline at end of file
%
\section{The Fundamental Data Structures within Collections}
\ No newline at end of file
%
\section{The Fundamentals Behind Collections}
\ No newline at end of file
%
\section{The Fundamental Algorithms within FieldUtils}
\ No newline at end of file
%
\section{The Fundamental Data Structures within FieldUtils}
\ No newline at end of file
%
\section{The Fundamentals Behind FieldUtils}
\ No newline at end of file
%
\section{The Fundamental Algorithms within GlobalMapping}
\ No newline at end of file
%
\section{The Fundamental Data Structures within GlobalMapping}
\ No newline at end of file
%
\section{The Fundamentals Behind GlobalMapping}
\ No newline at end of file
%
\section{BasicConst}
\lstinputlisting[language=C++, firstline=47, lastline=59]{../../library/LibUtilities/BasicConst/NektarUnivConsts.hpp}
\ No newline at end of file
%
\section{Foundations}
The two basic building blocks of all that is done in Nektar++ are the concepts of Points and of a Basis. The Point objects denote positions
in space, either on compact domains (normally $[-1,1]^d$ where $d$ is the dimension in a reference domain mapped to world-space)
or periodic domains (i.e. in the case of points used in Fourier expansions). The Basis objects denote functions (e.g. polynomials) evaluated
at a given set of points.
\subsection{Points}
\begin{itemize}
\item PointsKey
\item Points
\end{itemize}
\subsection{Basis}
\begin{itemize}
\item BasisKey
\item Basis
\end{itemize}
\begin{figure}[htb]
\centering
\includegraphics[width=4in]{img/basismemory.pdf}
\caption{Figure 1}
\label{foundations:basismemory}
\end{figure}
%
\section{Linear Algebra}
\ No newline at end of file
%
\section{Time Integration}
%
\section{The Fundamental Algorithms within LocalRegions}
\ No newline at end of file
%
\section{The Fundamental Data Structures within LocalRegions}
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/expansiontree.pdf}
\caption{Figure local regions tree}
\label{localregions:localclasstree}
\end{figure}
\ No newline at end of file
%
\section{The Fundamentals Behind LocalRegions}
\ No newline at end of file
%
\section{The Fundamental Algorithms within MultiRegions}
\ No newline at end of file
%
\section{The Fundamental Data Structures within MultiRegions}
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/multiregiontree.pdf}
\caption{Figure 1}
\label{multiregions:multiregionstree}
\end{figure}
%
\section{The Fundamentals Behind MultiRegions}
\ No newline at end of file
%
\section{The Fundamental Algorithms within SolverUtils}
\ No newline at end of file
%
\section{The Fundamental Data Structures within SolverUtils}
\ No newline at end of file
%
\section{The Fundamentals Behind SolverUtils}
\ No newline at end of file
%
\section{The Fundamental Algorithms within SpatialDomains}
\ No newline at end of file
%
\section{The Fundamental Data Structures within SpatialDomains}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reference to World-Space Mapping}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Geometry}
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/geomtree.pdf}
\caption{Figure geometry tree}
\label{spatialdomains:geomtree}
\end{figure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{GeomFactors}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{MeshGraph}
\ No newline at end of file
%
\section{The Fundamentals Behind SpatialDomains}
\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}
$$
$$
{\bf g} = {\bf J}^T{\bf J}
$$
$$
g = \det{\bf g}
$$
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}
%
\section{The Fundamental Algorithms within StdRegions}
\ No newline at end of file
%
\section{The Fundamental Data Structures within StdRegions}
\begin{figure}[htb]
\centering
\includegraphics[width=6in]{img/stdexpansiontree.pdf}
\caption{Figure 1}
\label{stdregions:stdexpansiontree}
\end{figure}
%
\section{The Fundamentals Behind StdRegions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reference Element Transformations That Facilitate Separability}
\begin{figure}[htb]
\centering
\includegraphics[width=4in]{img/afg002.pdf}
\caption{Duffy mapping between a right-sided triangle and a square domain.}
\label{stdregions:duffy}
\end{figure}
Duffy \cite{Duffy82}
Dubiner \cite{Dubiner91}
Ainsworth \cite{AinsworthAD11,Ainsworth14}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Reference Elements On Primative Geometric Types}
Hesthaven \cite{Hesthaven98}
Taylor \cite{TaylorWV00}
% Library Master File
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: LibUtilities}
In this chapter, we walk the reader through the different components of the LibUtilities Directory.
We have ordered them in alphabetical order by directory name, not by level of importance or
relevance to the code. Since all of these items are considered foundational to Nektar++, they
should all be considered equally important and relevant. Along the same lines -- since all of
these areas of the code represent the deepest members of the code hierarchy, these
items should rarely be modified.
%
\input{library/LibUtilities/basicconst.tex}
%
\input{library/LibUtilities/basicutils.tex}
%
\input{library/LibUtilities/communication.tex}
%
\input{library/LibUtilities/fft.tex}
%
\input{library/LibUtilities/foundations.tex}
%
\input{library/LibUtilities/interpreter.tex}
%
\input{library/LibUtilities/kernel.tex}
%
\input{library/LibUtilities/linearalgebra.tex}
%
\input{library/LibUtilities/memory.tex}
%
\input{library/LibUtilities/polylib.tex}
%
\input{library/LibUtilities/timeintegration.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: StdRegions}
In this chapter, we walk the reader through the different components of the StdRegions Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
StdRegions Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/StdRegions/stdreg-fundamentals.tex}
%
\input{library/StdRegions/stdreg-datastructures.tex}
%
\input{library/StdRegions/stdreg-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: SpatialDomains}
In this chapter, we walk the reader through the different components of the SpatialDomains Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
SpatialDomains Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
The SpatialDomains Directory and its corresponding class definitions serve two principal purposes:
\begin{enumerate}
\item To hold the elemental geometric information (i.e. vertex information, curve information and reference-to-world mapping information); and
\item To facility reading in and writing out geometry-related information.
\end{enumerate}
When designing Nektar++, developing a class hierarchy for StdRegions (those fundamental domains over which we define
integration and differentiation) and LocalRegions (i.e. elements in world-space) was fairly straightforward following \cite{KaSh05}.
For instance, a triangle in world-space {\em is-a} standard triangle. The first question that arose was where to store geometric
information, as information within the LocalRegions element or as information encapsulated from the element so that multiple Expansions could
all point to the same geometric information. The decision we made was to store geometric information -- that is, the vertex information
in world-space that defines an element and the edge and face curvature information -- in its own data structure that could be shared by
multiple Expansions (functions) over the same domain (element) in world-space. Hence SpatialDomains started as the directory
containing Geometry and GeomFactors class definitions to meet the first item listed above. A LocalRegion {\em is-a} StdRegion and {\em has-a}
SpatialDomain (i.e. Geometry and GeomFactors).
We then realized that in order to jump-start the process of constructing elements and combining them together into MultiRegions (collections of
elements that represent a (sub)-domain of interest), we needed devise a light-weight data structure into which we could load geometric information
from our geometry file and from which we could then construct Expansions (with their mappings, etc.). The light-weight data structure we
devised was MeshGraph, and it was meant to meet the second item listed above.
\input{library/SpatialDomains/spdomains-fundamentals.tex}
%
\input{library/SpatialDomains/spdomains-datastructures.tex}
%
\input{library/SpatialDomains/spdomains-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: LocalRegions}
In this chapter, we walk the reader through the different components of the LocalRegions Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
LocalRegions Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/LocalRegions/localreg-fundamentals.tex}
%
\input{library/LocalRegions/localreg-datastructures.tex}
%
\input{library/LocalRegions/localreg-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: MultiRegions}
In this chapter, we walk the reader through the different components of the MultiRegions Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
MultiRegions Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/MultiRegions/multireg-fundamentals.tex}
%
\input{library/MultiRegions/multireg-datastructures.tex}
%
\input{library/MultiRegions/multireg-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: Collections}
In this chapter, we walk the reader through the different components of the Collections Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
Collections Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/Collections/collections-fundamentals.tex}
%
\input{library/Collections/collections-datastructures.tex}
%
\input{library/Collections/collections-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: GlobalMapping}
In this chapter, we walk the reader through the different components of the GlobalMapping Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
GlobalMapping Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/GlobalMapping/globalmapping-fundamentals.tex}
%
\input{library/GlobalMapping/globalmapping-datastructures.tex}
%
\input{library/GlobalMapping/globalmapping-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: FieldUtils}
In this chapter, we walk the reader through the different components of the FieldUtils Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
FieldUtils Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/FieldUtils/fieldutils-fundamentals.tex}
%
\input{library/FieldUtils/fieldutils-datastructures.tex}
%
\input{library/FieldUtils/fieldutils-algorithms.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Inside the Library: SolverUtils}
In this chapter, we walk the reader through the different components of the SolverUtils Directory.
We begin with a discussion of the mathematical fundamentals, for which we use the book
by Karniadakis and Sherwin \cite{KaSh05} as our principle reference. We then provide
the reader with an overview of the primary data structures introduced within the
SolverUtils Directory (often done through C++ objects), and then present the major
algorithms -- expressed as either object methods or functions -- employed over these data structures.
\input{library/SolverUtils/solverutils-fundamentals.tex}
%
\input{library/SolverUtils/solverutils-datastructures.tex}
%
\input{library/SolverUtils/solverutils-algorithms.tex}
% Preface
\chapter{Preface}
Like with any software project, people want to know it origins: what motivated it, what and who drove it, and what
constrained it. \nek{} officially started as a project idea in 2004 in Salt Lake City, UT, USA and we registered
the first commit to SVN in 2006. The basic backstory is as follows: Mike Kirby (University of Utah) and Spencer
Sherwin (Imperial College London) had both studied under George Karniadakis. Though Mike and Spencer did
not overlap in terms of their studies (Spencer was a Princeton graduate while Mike was a Brown graduate), they
both worked on \emph{Nektar}, a \shp{} element code supervised by George. George's research group has
had a long history of involvement in various software projects, e.g. PRISM (which has continued its existence
under Hugh Blackburn) and \emph{Nektar}. Spencer and George initiated the \emph{Nektar} code with triangular (2D) and
tetrahedral (3D) \shp{} elements in the early 1990s, and the code grew and evolved with additions
by Igor Lomtev, Tim Warburton, Mike Kirby, etc., all under the PhD advisor direction of George. Spencer
graduated from Princeton under George's supervision in 1995 and went on to Imperial College London
as a faculty member; Mike graduated from Brown under George's supervision in 2002 and went on to the
University of Utah in 2002. In 2004, Mike and Spencer teamed up to re-write \emph{Nektar} in light of modern
C++ programming practices and in light of what had been learned in the decade or so since its foundation.
What were the observations that motivated \nek{}? The first observation was that \emph{Nektar}'s origin
was triangular and tetrahedral \shp{} elements as applied to incompressible fluid mechanics
problems (i.e. the incompressible Navier-Stokes equations). These ideas were extended to
the compressible Navier-Stokes by Lomtev and the two parallel paths joined and extended into
what is often called Hybrid \emph{Nektar} by Tim Warburton. Hybrid \emph{Nektar} (referred to as \emph{Nektar} from
here on out) used the C++ programming paradigm to facilitate hybrid elements: triangles and
quadrilaterals in 2D and tetrahedra, hexahedra, prisms and pyramids in 3D. In addition, Warburton
structured the code in a way to allow extensions to the Arbitrary Lagrangian Eulerian (ALE) formulation
within \emph{Nektar}, as well as various other features such as the \emph{Nektar} Magneto-Hydr