#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass extarticle
\begin_preamble
\newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}}
\newcommand{\fdo}[1]{\mathcal{D}_{#1}}
\newcommand{\sdo}[1]{D_{#1}}
\newcommand{\tdo}[1]{D_{#1}}
\newcommand{\fd}[2]{\fdo{#1} #2}
\newcommand{\sd}[2]{\sdo{#1} #2}
\newcommand{\td}[2]{\tdo{#1} #2}
\newcommand{\pdd}[2]{\frac{\partial^2 #1}{\partial #2^2}}
\newcommand{\pddd}[2]{\frac{\partial^3 #1}{\partial #2^3}}
\newcommand{\pmix}[3]{\frac{\partial^2 #1}{\partial #2 \partial #3}}
\newcommand{\pmixx}[4]{\frac{\partial^3 #1}{\partial #2 \partial #3 \partial #4}}
\newcommand{\funcd}[2]{\frac{\partial #1}{\partial #2}}
\newcommand{\spaced}[2]{{\cal D}^{#1} #2}
\newcommand{\totald}[2]{{D}^{#1} #2}

\newcommand{\abs}[1]{\left\vert{#1}\right\vert}
\newcommand{\od}[2]{\frac{d #1}{d #2}}
\newcommand{\odd}[2]{\frac{d^2 #1}{d #2^2}}
\newcommand{\R}{\mathbb{R}}

\usepackage{listings}
\usepackage[usenames,dvipsnames]{color}
\definecolor{lightgray}{RGB}{240,240,240}
\definecolor{bluegray}{RGB}{180,180,200}
\lstset{basicstyle={\sffamily\footnotesize},language={C++},tabsize=2,showstringspaces=false,frame=shadowbox,breaklines=true,mathescape=true,commentstyle={\itshape\textcolor{red}},lineskip=1pt,aboveskip=\bigskipamount,belowskip=\bigskipamount, rulesepcolor=\color{bluegray}}
\end_preamble
\use_default_options true
\begin_modules
theorems-ams
theorems-ams-extended
\end_modules
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman palatino
\font_sans default
\font_typewriter default
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize 12
\spacing single
\use_hyperref false
\papersize default
\use_geometry true
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 0
\branch answers
\selected 1
\filename_suffix 0
\color #5555ff
\end_branch
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 0.9in
\topmargin 0.75in
\rightmargin 0.9in
\bottommargin 0.75in
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Getting started with Sundance
\end_layout

\begin_layout Author
Kevin Long
\end_layout

\begin_layout Standard
In this document we show the support code common to many examples, and then
 walk through the development of a program to solve Laplace's equation.
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Section
Boilerplate code
\end_layout

\begin_layout Standard
A dull but essential first step is to show the skeleton C++ common to nearly
 every Sundance program:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

#include "Sundance.hpp"
\end_layout

\begin_layout Plain Layout

int main(int argc, void** argv) 
\end_layout

\begin_layout Plain Layout

{   
\end_layout

\begin_layout Plain Layout

	try     
\end_layout

\begin_layout Plain Layout

	{       
\end_layout

\begin_layout Plain Layout

		Sundance::init(argc, argv);
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

        /* code body goes here */     
\end_layout

\begin_layout Plain Layout

	}   
\end_layout

\begin_layout Plain Layout

	catch(exception& e)     
\end_layout

\begin_layout Plain Layout

	{        
\end_layout

\begin_layout Plain Layout

		Sundance::handleException(e);     
\end_layout

\begin_layout Plain Layout

	}   
\end_layout

\begin_layout Plain Layout

	Sundance::finalize(); 
\end_layout

\begin_layout Plain Layout

} 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
These lines control initialization and result gathering for profiling timers,
 initializing and finalizing MPI if MPI is being used, and other administrative
 tasks.
 The body of the code goes in place of the comment 
\family typewriter
code body goes here
\family default
.
 
\end_layout

\begin_layout Subsection
A minimalist example
\end_layout

\begin_layout Standard
An example of the boilerplate code plus a small amount of code body is in
 the source file 
\series bold
Skeleton.cpp
\series default
.
 This program simply does a few MPI calls to get the processor rank and
 the total number of processors, does a simple sanity check, and ends.
 Here's the code body.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* The main simulation code goes here.
 In this example, all we do     
\end_layout

\begin_layout Plain Layout

 * is to print some information about the processor ranks.
 */
\end_layout

\begin_layout Plain Layout

MPIComm comm = MPIComm::world();
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Print a header from the root processor only.
 Although this executes on      
\end_layout

\begin_layout Plain Layout

* all processors, anything written to the output stream Out::root()    
   
\end_layout

\begin_layout Plain Layout

* is ignored on all non-root processors (rank != 0).
       
\end_layout

\begin_layout Plain Layout

* After writing, synchronize to keep this message from getting jumbled 
     
\end_layout

\begin_layout Plain Layout

* together with the subsequent messages.
       */     
\end_layout

\begin_layout Plain Layout

Out::root() << "Example: getting started" << endl;     
\end_layout

\begin_layout Plain Layout

comm.synchronize();
\end_layout

\begin_layout Plain Layout

    
\end_layout

\begin_layout Plain Layout

/* Every processor now speaks up and identifies itself */     
\end_layout

\begin_layout Plain Layout

int myRank = comm.getRank();     
\end_layout

\begin_layout Plain Layout

int nProc = comm.getNProc();     
\end_layout

\begin_layout Plain Layout

Out::os() << "Processor " << myRank << " of " << nProc << " checking in"
 << endl;
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Test success or failure.
 Most examples you'll see will do this       
\end_layout

\begin_layout Plain Layout

* as part of the Trilinos regression testing system.
       
\end_layout

\begin_layout Plain Layout

* If you write a simulation code that won't become part of Trilinos,   
   
\end_layout

\begin_layout Plain Layout

* you often can bypass this step.
         
\end_layout

\begin_layout Plain Layout

* Here the test is a trival one: every processor's rank must be      
\end_layout

\begin_layout Plain Layout

* smaller than the total number of processors.
 If this fails,      
\end_layout

\begin_layout Plain Layout

* your MPI installation is probably broken!      
\end_layout

\begin_layout Plain Layout

* */     
\end_layout

\begin_layout Plain Layout

Sundance::passFailTest(myRank < nProc);
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Output from a run on four processors is shown.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Simulation built using Sundance version 2.4.0 (10 June 2012) 
\end_layout

\begin_layout Plain Layout

Sundance is copyright
\end_layout

\begin_layout Plain Layout

 (C) 2005-2012 Sandia National Laboratories 
\end_layout

\begin_layout Plain Layout

 (C) 2007-2012 Texas Tech University 
\end_layout

\begin_layout Plain Layout

and is licensed under the GNU Lesser General Public License, version 2.1
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

Example: getting started 
\end_layout

\begin_layout Plain Layout

p=0 | Processor 0 of 4 checking in 
\end_layout

\begin_layout Plain Layout

p=3 | Processor 3 of 4 checking in 
\end_layout

\begin_layout Plain Layout

p=1 | Processor 1 of 4 checking in 
\end_layout

\begin_layout Plain Layout

p=2 | Processor 2 of 4 checking in 
\end_layout

\begin_layout Plain Layout

test PASSED 
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Miscellaneous preliminaries
\end_layout

\begin_layout Standard
If you want to get on with solving differential equations, skip ahead to
 section 2.
 
\end_layout

\begin_layout Subsubsection
Reading parameters from command-line arguments
\end_layout

\begin_layout Standard
If you want to get on with solving differential equations, skip ahead to
 section 2.
\end_layout

\begin_layout Standard
Sometimes you'll want to set program options using command-line arguments.
 The Teuchos CommandLineProcessor system provides a number of utitilies
 for parsing command-line arguments; Sundance provides a simplified interface
 to that.
\end_layout

\begin_layout Standard
Example program: 
\series bold
CommandLineOptions.cpp
\series default
.
\end_layout

\begin_layout Standard
Here's the code body.
 
\emph on
Notice that the setting up of command-line option parsing must be done before
 the call to Sundance::init().
 
\emph default
This is one of the very few cases where code should precede the 
\family typewriter
init()
\family default
 call.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

// Declare variables whose values are to be read from the command line
\end_layout

\begin_layout Plain Layout

// Set default values
\end_layout

\begin_layout Plain Layout

int someInt = 137;     
\end_layout

\begin_layout Plain Layout

double someDouble = 3.14159;     
\end_layout

\begin_layout Plain Layout

string someString = "blue";     
\end_layout

\begin_layout Plain Layout

bool someBool = false;
\end_layout

\begin_layout Plain Layout

  
\end_layout

\begin_layout Plain Layout

// Register option names, variables, and help string with 
\end_layout

\begin_layout Plain Layout

// the command-line processor
\end_layout

\begin_layout Plain Layout

Sundance::setOption("integer", someInt, "An integer");     
\end_layout

\begin_layout Plain Layout

Sundance::setOption("alpha", someDouble, "A double");     
\end_layout

\begin_layout Plain Layout

Sundance::setOption("color", someString, "What is your favorite color?");
  
\end_layout

\begin_layout Plain Layout

Sundance::setOption("lie", "truth", someBool, "I am lying.");
\end_layout

\begin_layout Plain Layout

  
\end_layout

\begin_layout Plain Layout

// Now call init 
\end_layout

\begin_layout Plain Layout

Sundance::init(&argc, &argv);
\end_layout

\begin_layout Plain Layout

    
\end_layout

\begin_layout Plain Layout

Out::root() << "User input:" << endl;     
\end_layout

\begin_layout Plain Layout

Out::root() << "An integer: " << someInt << endl;     
\end_layout

\begin_layout Plain Layout

Out::root() << "A double-precision number: " << someDouble << endl;    
 
\end_layout

\begin_layout Plain Layout

Out::root() << "Favorite color: " << someString << endl;     
\end_layout

\begin_layout Plain Layout

Out::root() << "I am lying: " << someBool << endl;
\end_layout

\end_inset


\end_layout

\begin_layout Standard
With 
\family typewriter
./Sundance_CommandLineOptions.exe
\family default
 and no command-line arguments, the default values are used:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

User input: 
\end_layout

\begin_layout Plain Layout

An integer: 137 
\end_layout

\begin_layout Plain Layout

A double-precision number: 3.14159 
\end_layout

\begin_layout Plain Layout

Favorite color: blue 
\end_layout

\begin_layout Plain Layout

I am lying: 0 
\end_layout

\begin_layout Plain Layout

test PASSED 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
With the command line 
\family typewriter
./Sundance_CommandLineOptions.exe --color=red
\family default
, the string argument is set to red
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

User input: 
\end_layout

\begin_layout Plain Layout

An integer: 137 
\end_layout

\begin_layout Plain Layout

A double-precision number: 3.14159 
\end_layout

\begin_layout Plain Layout

Favorite color: red
\end_layout

\begin_layout Plain Layout

I am lying: 0 
\end_layout

\begin_layout Plain Layout

test PASSED 
\end_layout

\end_inset


\end_layout

\begin_layout Standard
A few further points about command-line parsing are:
\end_layout

\begin_layout Itemize
Command-line options should use the format 
\family typewriter
--name=value
\family default
 when values are given, or simply 
\family typewriter
--name
\family default
 when no value is needed.
 
\end_layout

\begin_layout Itemize
To see all command-line options and their default values, run your program
 with the 
\family typewriter
--help
\family default
 option.
\end_layout

\begin_layout Itemize
To access the lower-level command-line processor object, use the function
 
\family typewriter
Sundance::clp()
\family default
 which returns the command-line processor to be used during the call to
 
\family typewriter
init()
\family default
.
 See the Teuchos documentation for information about low-level command-line
 handling capabilities.
\end_layout

\begin_layout Subsubsection
Reading parameters from XML files
\end_layout

\begin_layout Standard
When you write an applications code you'll often want to read problem parameters
 from a data file.
 XML together with the Trilinos 
\family typewriter
ParameterList
\family default
 utility is a convenient way to do this.
 Even in toy example problems, most Trilinos solvers are initialized through
 
\family typewriter
ParameterList
\family default
 objects and it's convenient to read these from an XML file.
 
\end_layout

\begin_layout Standard
In the example program 
\series bold
XMLParameterList.cpp 
\series default
a 
\family typewriter
ParameterList
\family default
 is read from an XML file.
 The default filename is 
\family typewriter
paramExample.xml
\family default
 but an alternate filename can be given as a command line option 
\family typewriter
--xml-file=[filename]
\family default
.
\end_layout

\begin_layout Standard
Here's the contents of the XML file
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

<!-- An example parameter list in XML format -->
\end_layout

\begin_layout Plain Layout

<ParameterList>   
\end_layout

\begin_layout Plain Layout

	<ParameterList name="Widget">     
\end_layout

\begin_layout Plain Layout

		<Parameter name="Region"  type="int" value="1"/>     
\end_layout

\begin_layout Plain Layout

		<Parameter name="Material" type="string" value="Kryptonite"/>     
\end_layout

\begin_layout Plain Layout

		<Parameter name="Density"  type="double" value="3.14159"/>   
\end_layout

\begin_layout Plain Layout

	</ParameterList>    
\end_layout

\begin_layout Plain Layout

	<ParameterList name="Gizmo">
\end_layout

\begin_layout Plain Layout

		<Parameter name="Region"  type="int" value="2"/>     
\end_layout

\begin_layout Plain Layout

		<Parameter name="Material" type="string" value="Dilithium"/>     
\end_layout

\begin_layout Plain Layout

		<Parameter name="Density"  type="double" value="2.718"/>   
\end_layout

\begin_layout Plain Layout

	</ParameterList>    
\end_layout

\begin_layout Plain Layout

</ParameterList> 
\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
The body of the code is shown next.
 The 
\family typewriter
ParameterXMLFileReader
\family default
 object does the XML parsing, returning a 
\family typewriter
ParameterList
\family default
 object via the 
\family typewriter
getParameters()
\family default
 function.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Read the XML filename as a command-line option */     
\end_layout

\begin_layout Plain Layout

string xmlFilename = "paramExample.xml";     
\end_layout

\begin_layout Plain Layout

Sundance::setOption("xml-file", xmlFilename, "XML filename");   
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Initialize */     
\end_layout

\begin_layout Plain Layout

Sundance::init(&argc, &argv);
\end_layout

\begin_layout Plain Layout

    
\end_layout

\begin_layout Plain Layout

/* Read a parameter list from the XML file */     
\end_layout

\begin_layout Plain Layout

ParameterXMLFileReader reader(xmlFilename);     
\end_layout

\begin_layout Plain Layout

ParameterList params = reader.getParameters();
\end_layout

\begin_layout Plain Layout

    
\end_layout

\begin_layout Plain Layout

/* Get the parameters for the "Widget" sublist */     
\end_layout

\begin_layout Plain Layout

const ParameterList& widget = params.sublist("Widget");     
\end_layout

\begin_layout Plain Layout

Out::root() << "widget region label: " << widget.get<int>("Region") << endl;
     
\end_layout

\begin_layout Plain Layout

Out::root() << "widget material: " << widget.get<string>("Material") << endl;
     
\end_layout

\begin_layout Plain Layout

Out::root() << "widget density: " << widget.get<double>("Density") << endl;
\end_layout

\begin_layout Plain Layout

    
\end_layout

\begin_layout Plain Layout

/* Get the parameters for the "Gizmo" sublist */     
\end_layout

\begin_layout Plain Layout

const ParameterList& gizmo = params.sublist("Gizmo");     
\end_layout

\begin_layout Plain Layout

Out::root() << "gizmo region label: " << gizmo.get<int>("Region") << endl;
     
\end_layout

\begin_layout Plain Layout

Out::root() << "gizmo material: " << gizmo.get<string>("Material") << endl;
     
\end_layout

\begin_layout Plain Layout

Out::root() << "gizmo density: " << gizmo.get<double>("Density") << endl;
\end_layout

\end_inset


\end_layout

\begin_layout Standard
See the Teuchos documentation for more information on the use of parameter
 lists.
\end_layout

\begin_layout Subsubsection
Reading a solver from an XML file
\end_layout

\begin_layout Standard
One of the most common uses of XML and 
\family typewriter
ParameterList
\family default
 objects is to configure linear and nonlinear solvers.
 The 
\family typewriter
LinearSolverBuilder
\family default
 object can create a variety of linear solver types (including Amesos, Aztec,
 Belos, and Playa solvers) through a single function call to the static
 member 
\family typewriter
createMember()
\family default
, as shown in the next two code fragments.
 
\end_layout

\begin_layout Standard
The 
\family typewriter
createMember()
\family default
 function can be given an XML filename,
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

LinearSolver<double> solver = LinearSolverBuilder::createSolver("mySolver.xml");
\end_layout

\end_inset

or a parameter list,
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

ParameterList solverParams = bigList.sublist("LinearSolver");
\end_layout

\begin_layout Plain Layout

LinearSolver<double> solver = LinearSolverBuilder::createSolver(solverParams);
\end_layout

\end_inset


\end_layout

\begin_layout Section
Example: Laplace's equation on a 3D plate with a hole
\end_layout

\begin_layout Standard
With those preliminaries out of the way, let's solve a differential equation.
 Out first example will be to solve a linear boundary value problem in 3D:
 Laplace's equation
\begin_inset Formula 
\[
\nabla^{2}u=0
\]

\end_inset

on a thin square plate with a circular through-hole in the center.
 The geometry of this plate is shown in figures 1 and 2.
 For boundary conditions, we will specify Dirichlet conditions on one surface,
\begin_inset Formula 
\[
u=0\;\;\;\mbox{on the west edge of the plate}
\]

\end_inset

inhomogeneous Neumann conditions on the opposite surface,
\begin_inset Formula 
\[
\pd{u}{n}=1\;\;\;\mbox{on the east edge of the plate}
\]

\end_inset

and homogeneous Neumann conditions 
\begin_inset Formula 
\[
\pd{u}{n}=0
\]

\end_inset

on all other surfaces.
 
\end_layout

\begin_layout Subsection
Weak form
\end_layout

\begin_layout Standard
The Galerkin weak form of this problem is
\begin_inset Formula 
\[
\int_{\Omega}\nabla v\cdot\nabla u\, d\Omega-\int_{\mbox{east}}v\, dA=0\;\;\;\forall v\in H_{0}^{1}
\]

\end_inset

where 
\begin_inset Formula $H_{0}^{1}$
\end_inset

 is the subspace of 
\begin_inset Formula $H^{1}$
\end_inset

 such that 
\begin_inset Formula 
\[
u=0\;\;\mbox{on west}.
\]

\end_inset

In our program we'll represent this weak form in terms of symbolic expression
 objects called 
\family typewriter
Expr
\family default
s.
 As a basis for both the unknown function 
\begin_inset Formula $u$
\end_inset

 and the test function 
\begin_inset Formula $v$
\end_inset

, we will use the first-degree Lagrange functions on tetrahedral elements.
 On the surfaces where homogeneous Neumann BCs hold, the surface integral
 is zero, and the BCs are imposed weakly by simply omitting those integrals.
 The integrals will be computed using Gauss-Dunavant quadrature.
 
\end_layout

\begin_layout Standard
The resulting system of equations
\begin_inset Formula 
\[
K\mathbf{u=}\mathbf{b}
\]

\end_inset

is linear and must be solved with some linear solver algorithm.
 Sundance interfaces with linear solvers through the Playa 
\family typewriter
LinearSolver
\family default
 interface; most Trilinos solver libraries have an adapter letting them
 be used through Playa.
 
\end_layout

\begin_layout Standard
The solution vector is returned wrapped in an 
\family typewriter
Expr
\family default
 object of subtype 
\family typewriter
DiscreteFunction
\family default
.
 As such, it can be used in other symbolic expressions, for example, expressions
 that define post-processing steps such as flux calculations.
 Finally, it may be given to a 
\family typewriter
FieldWriter
\family default
 object that writes the solution to an output file in a format such as VTK
 or Exodus.
 
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename plateWithHoleMesh.png
	scale 25

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
3D view of meshed plate with hole
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename plateWithHoleGeom.png
	scale 30
	clip

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Schematic of labeled surfaces on the plate with hole
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Section
Programming Laplace's equation
\end_layout

\begin_layout Subsection
Overview of problem setup and solution
\end_layout

\begin_layout Standard
Before diving into code, let's take a coarse-grained look at the steps involved
 in setting up and solving a linear boundary value problem.
\end_layout

\begin_layout Enumerate
Do initialization steps
\end_layout

\begin_layout Enumerate
Create the objects that define the problem's geometry
\end_layout

\begin_layout Enumerate
Create the symbolic objects that will be used in the equation specification
\end_layout

\begin_layout Enumerate
Define the weak form and boundary conditions
\end_layout

\begin_layout Enumerate
Create a 
\begin_inset Quotes eld
\end_inset

problem
\begin_inset Quotes erd
\end_inset

 object that encapsulates the equations, boundary conditions, and geometry
 along with a specification of ordering of unknowns
\end_layout

\begin_layout Enumerate
Create a solver object
\end_layout

\begin_layout Enumerate
Solve the problem
\end_layout

\begin_layout Enumerate
Do postprocessing and/or visualization output
\end_layout

\begin_layout Enumerate
Do finalization steps
\end_layout

\begin_layout Standard
In more complex problems there may be loops over one or more of these steps;
 for example, a time integration will involve a loop over many solution
 steps, with visualization output being done at selected intervals.
 
\end_layout

\begin_layout Subsection
Getting a mesh
\end_layout

\begin_layout Standard
Sundance uses a 
\family typewriter
Mesh
\family default
 object to represent a discretization of the problem's geometric domain.
 There are many ways of getting a mesh; simple meshes might be built on
 the fly at runtime, more complex meshes will need to be build offline and
 read from a file.
 There are then numerous mesh file formats.
 To accomodate the diversity of mesh creation mechanisms, Sundance uses
 an abstract 
\family typewriter
MeshSource
\family default
 interface.
 Different mesh creation modes are represented as subtypes that implement
 this abstract interface.
 
\end_layout

\begin_layout Standard
Sundance is designed to work with different mesh underlying implementations,
 the choice of which is done by specifying a 
\family typewriter
MeshType
\family default
 object.
 
\end_layout

\begin_layout Standard
In this example we read a mesh that's been stored in the Exodus format.
 The file is named 
\family typewriter
plateWithHole.exo
\family default
.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

MeshType meshType = new BasicSimplicialMeshType(); 
\end_layout

\begin_layout Plain Layout

MeshSource meshReader = new ExodusMeshReader("plateWithHole", meshType);
 
\end_layout

\begin_layout Plain Layout

Mesh mesh = mesher.getMesh(); 
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Defining geometric subdomains
\end_layout

\begin_layout Standard
We'll need to specify subsets of the mesh on which equations or boundary
 conditions are defined.
 In many FEA codes this is done by explicit definition of element blocks,
 node sets, and side sets.
 Rather than working with sets explicitly at the user level, we instead
 work with 
\emph on
filtering rules
\emph default
 that produce sets of cells.
 These rules are represented by 
\family typewriter
CellFilter
\family default
 objects.
 You can think of a cell filter as an operator that acts on a mesh and returns
 a set of cells.
 
\end_layout

\begin_layout Standard
First we define a cell filter that identifies all cells of maximal dimension:
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Filter subtype MaximalCellFilter selects all cells having dimension equal
 to the spatial dimension of the mesh */
\end_layout

\begin_layout Plain Layout

CellFilter interior = new MaximalCellFilter();
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Next we define filters that identify the various boundary surfaces.
 In this example, boundary surfaces are specified by labels assigned to
 the mesh cells during the process of mesh generation.
 The 
\family typewriter
labeledSubset()
\family default
 member function finds those cells having a specified label.
 
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* DimensionalCellFilter selects all cells of a specified dimension.
 Here we select all 2D faces.
 Boundary conditions will be applied on certain subsets of these.
 */
\end_layout

\begin_layout Plain Layout

CellFilter edges = new DimensionalCellFilter(2);
\end_layout

\begin_layout Plain Layout

CellFilter south = edges.labeledSubset(1);     
\end_layout

\begin_layout Plain Layout

CellFilter east = edges.labeledSubset(2);     
\end_layout

\begin_layout Plain Layout

CellFilter north = edges.labeledSubset(3);     
\end_layout

\begin_layout Plain Layout

CellFilter west = edges.labeledSubset(4);     
\end_layout

\begin_layout Plain Layout

CellFilter hole = edges.labeledSubset(5);     
\end_layout

\begin_layout Plain Layout

CellFilter down = edges.labeledSubset(6);     
\end_layout

\begin_layout Plain Layout

CellFilter up = edges.labeledSubset(7);
\end_layout

\end_inset

See figure 2 for a schematic of the various boundary surfaces.
 In subsequent examples we will see other mechanisms for identifying cells.
\end_layout

\begin_layout Subsection
Defining symbolic expressions
\end_layout

\begin_layout Standard
An equation is built out of mathematical expressions.
 Expressions, represented by 
\family typewriter
Expr
\family default
 objects, can be combined using arithmetic operators, function composition,
 and differential operators.
 Expressions can be aggregated into lists.
 
\end_layout

\begin_layout Standard
An 
\family typewriter
Expr
\family default
 object is a RCH to an expression subtype.
 
\end_layout

\begin_layout Subsubsection
Test and unknown functions
\end_layout

\begin_layout Standard
Unknown and test functions are a vital part of every weak form.
 Each unknown or test function needs to have a basis function specified
 through choice of a 
\family typewriter
BasisFamily
\family default
 object.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Create an object representation of the first-degree Lagrange basis */
\end_layout

\begin_layout Plain Layout

BasisFamily basis = new Lagrange(1);
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The basis object is given as an argument to the test and unknown function
 constructors, as shown.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr u = new UnknownFunction(basis, "u");     
\end_layout

\begin_layout Plain Layout

Expr v = new TestFunction(basis, "v");
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The string arguments 
\family typewriter

\begin_inset Quotes eld
\end_inset

u
\begin_inset Quotes erd
\end_inset


\family default
 and 
\family typewriter

\begin_inset Quotes eld
\end_inset

v"
\family default
 are optional and are used only in labeling these functions in diagnostic
 output.
 Any label can be used.
 There is no need for the string's value to be identical to the name of
 the C++ variable.
\end_layout

\begin_layout Subsubsection
Differential operators
\end_layout

\begin_layout Standard
Differential operators are also represented as 
\family typewriter
Expr
\family default
 objects.
 The next code fragment shows the construction of partial derivative operators
 and their aggregation into a gradient operator.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Create differential operators and coordinate functions.
 Directions are 
\end_layout

\begin_layout Plain Layout

 * indexed starting from zero.
 The List() function can collect 
\end_layout

\begin_layout Plain Layout

 * expressions into a vector.
 */     
\end_layout

\begin_layout Plain Layout

Expr dx = new Derivative(0);    /* The operator $
\backslash
pd{}{x}$ */
\end_layout

\begin_layout Plain Layout

Expr dy = new Derivative(1);    /* The operator $
\backslash
pd{}{y}$ */  
\end_layout

\begin_layout Plain Layout

Expr dz = new Derivative(2);    /* The operator $
\backslash
pd{}{z}$ */  
\end_layout

\begin_layout Plain Layout

Expr grad = List(dx, dy, dz);   /* The operator $
\backslash
nabla$   */
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Equations and boundary conditions
\end_layout

\begin_layout Subsubsection
Numerical integration rules
\end_layout

\begin_layout Standard
Integrals appearing in weak forms and in postprocessing steps are done by
 quadrature.
 The family of quadrature rules to be used is specified by selection of
 a 
\family typewriter
QuadratureFamily
\family default
 object.
 Different terms can use different quadrature rules.
 Here we create two Gaussian quadrature objects, one of order 1 (for use
 in integrating 
\begin_inset Formula $\nabla v\cdot\nabla u$
\end_inset

) and one of order 2 (for use in integrating 
\begin_inset Formula $vu$
\end_inset

 on the boundary).
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* We need a quadrature rule for doing the integrations */     
\end_layout

\begin_layout Plain Layout

QuadratureFamily quad1 = new GaussianQuadrature(1);     
\end_layout

\begin_layout Plain Layout

QuadratureFamily quad2 = new GaussianQuadrature(2);     
\end_layout

\end_inset


\end_layout

\begin_layout Standard
These objects are called quadrature 
\emph on
families
\emph default
 rather than quadrature 
\emph on
rules
\emph default
 because they aren't just quadrature rules; rather, they can produce different
 quadrature rules for cells of different dimensions.
 For example, the Gaussian quadrature family will produce a Gauss-Legendre
 rule when used on a one-dimensional cell, or a 2D or 3D Gauss-Dunavant
 rule when used on a two-dimensional cell.
\end_layout

\begin_layout Subsubsection
Integrals
\end_layout

\begin_layout Standard
We now have everything needed to write the weak form: a domain of integration,
 an integrand, and a specification of quadrature.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Write the weak form */
\end_layout

\begin_layout Plain Layout

Expr eqn = Integral(interior, (grad*u)*(grad*v), quad1);
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Essential boundary conditions
\end_layout

\begin_layout Standard
Imposition of Dirichlet boundary conditions can be a tricky aspect of finite
 element methods.
 In this example, we use the most straightforward approach, which is to
 replace the rows associated with boundary nodes by the boundary condition.
 Division of these terms by 
\begin_inset Formula $h$
\end_inset

, the local cell diameter, is done so that the terms
\begin_inset Formula 
\[
\int_{\Omega}\nabla v\cdot\nabla u\, dV
\]

\end_inset

and
\begin_inset Formula 
\[
\int_{\mbox{west}}h^{-1}vu\, dA
\]

\end_inset

scale identically with 
\begin_inset Formula $h$
\end_inset

; this helps the conditioning of the resulting linear system of equations.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr h = new CellDiameterExpr();     
\end_layout

\begin_layout Plain Layout

Expr bc = EssentialBC(west, v*u/h, quad2);
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Creating and solving a linear problem
\end_layout

\begin_layout Standard
Everything is in place to build the linear problem object.
 Here's the constructor.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

LinearProblem prob(mesh, eqn, bc, v, u, vecType);
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Don't confuse the Sundance 
\family typewriter
LinearProblem
\family default
 object with the 
\family typewriter
LinearProblem
\family default
 objects in Epetra and Belos; it is quite different.
 The Sundance LP object is responsible for 
\emph on
building
\emph default
 a system of equations.
 The Epetra and Belos LP objects are encapsulations of a system of equations
 provided by a user.
 
\end_layout

\begin_layout Standard
Implementation note: LinearProblem is a lightweight user interface to a
 lower-level Assembler object that actually does the work of building matrices
 and vectors.
 Assembler is also used under the hood for the assembly of Jacobians and
 residuals for nonlinear problems and for the calculation of functional
 values and gradients.
 LinearProblem ensures that the Assembler is constructed properly, controls
 the call to Assembler for building the matrix and vector, invokes the linear
 solver and checks for convergence, and wraps the solution vector in a DiscreteF
unction object so that it can be used in symbolic specification of future
 problems.
\end_layout

\begin_layout Subsubsection
Getting a solver
\end_layout

\begin_layout Standard
The solver object can be created in a number of ways; most often it will
 be read from an XML file as described above.
\end_layout

\begin_layout Subsubsection
Doing the solve
\end_layout

\begin_layout Standard
Invocation of the solver is simple:
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr soln = prob.solve(solver);
\end_layout

\end_inset


\end_layout

\begin_layout Standard
The result, 
\family typewriter
soln
\family default
, is an expression with derived type 
\family typewriter
DiscreteFunction
\family default
.
 As an 
\family typewriter
Expr
\family default
, it can be used in further symbolic calculations; some simple examples
 are shown below in the section on postprocessing.
\end_layout

\begin_layout Standard
While this is the simplest way to invoke the solver, there are two issues
 with this syntax in complex problems in which multiple solves or error
 handling may be needed.
\end_layout

\begin_layout Itemize
If a problem occurs, the only feedback to the user is a thrown exception.
 
\end_layout

\begin_layout Itemize
A new discrete function object, 
\family typewriter
soln
\family default
, is created for every solve.
 While the price of allocation is relatively small, it is nonetheless an
 efficiency loss.
\end_layout

\begin_layout Standard
There is a version of the 
\family typewriter
solve()
\family default
 function that returns diagnostics and writes the solution into an existing
 discrete function.
 This alternate version is described in the more advanced documentation.
\end_layout

\begin_layout Subsection
Visualization output
\end_layout

\begin_layout Standard
To see the solution, use a 
\family typewriter
FieldWriter
\family default
 to send to file.
 In 2D or 3D, the file formats currently supported are VTK and Exodus.
 Here we write to a VTK file.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Write the results to a VTK file */
\end_layout

\begin_layout Plain Layout

FieldWriter w = new VTKWriter("PoissonDemo3D");     
\end_layout

\begin_layout Plain Layout

w.addMesh(mesh);     
\end_layout

\begin_layout Plain Layout

w.addField("soln", new ExprFieldWrapper(soln[0]));     
\end_layout

\begin_layout Plain Layout

w.write();
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Plain Layout
\noindent
\align center
\begin_inset Graphics
	filename plateWithHole3D.jpg
	scale 50
	clip

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Solution of Laplace's equation on the holed plate.
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Postprocessing
\end_layout

\begin_layout Standard
In real applications you'll want to do some computations to analyze the
 solution.
 This section gives several examples of postprocessing computations using
 the solution expression 
\family typewriter
soln
\family default
.
 
\end_layout

\begin_layout Subsubsection
Flux calculation and definite integrals
\end_layout

\begin_layout Standard
The first example is the computation of the flux
\begin_inset Formula 
\[
\int_{\partial\Omega}\mathbf{n}\cdot\nabla u\, dA.
\]

\end_inset

With no internal source, the flux should be zero to within 
\begin_inset Formula $O\left(h\right)$
\end_inset

; this provides a minimal validity check on the solution.We set up an expression
 for the flux, then call the 
\family typewriter
evaluateIntegral()
\family default
 function to compute it.
 
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr n = CellNormalExpr(3, "n");     
\end_layout

\begin_layout Plain Layout

CellFilter wholeBdry = east+west+north+south+up+down+hole;
\end_layout

\begin_layout Plain Layout

Expr fluxExpr = Integral(wholeBdry, (n*grad)*soln, quad2);      
\end_layout

\begin_layout Plain Layout

double flux = evaluateIntegral(mesh, fluxExpr);     
\end_layout

\begin_layout Plain Layout

Out::os() << "numerical flux = " << flux << endl;
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Moments and coordinate functions
\end_layout

\begin_layout Standard
In the next example, we compute the center-of-mass position of the body
 
\begin_inset Formula $\Omega$
\end_inset

,
\begin_inset Formula 
\[
x_{CM}=\frac{1}{V\left(\Omega\right)}\int_{\Omega}x\, d\Omega
\]

\end_inset

and similarly for 
\begin_inset Formula $y_{CM}$
\end_inset

 and 
\begin_inset Formula $z_{CM}$
\end_inset

.
\end_layout

\begin_layout Standard
Position-dependent functions can be written using coordinate expressions.While
 used only in a postprocessing step here, you'll often use coordinate functions
 when setting up position-dependent sources and boundary conditions.
 Here's the construction of the coordinate expressions,
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr x = new CoordExpr(0);     
\end_layout

\begin_layout Plain Layout

Expr y = new CoordExpr(1);     
\end_layout

\begin_layout Plain Layout

Expr z = new CoordExpr(2);
\end_layout

\end_inset

and their use in the integrals for the CM position.
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr volExpr = Integral(interior, 1.0, quad2);
\end_layout

\begin_layout Plain Layout

Expr xCMExpr = Integral(interior, x, quad2);     
\end_layout

\begin_layout Plain Layout

Expr yCMExpr = Integral(interior, y, quad2);     
\end_layout

\begin_layout Plain Layout

Expr zCMExpr = Integral(interior, z, quad2);    
\end_layout

\begin_layout Plain Layout

double vol = evaluateIntegral(mesh, volExpr);
\end_layout

\begin_layout Plain Layout

double xCM = evaluateIntegral(mesh, xCMExpr);     
\end_layout

\begin_layout Plain Layout

double yCM = evaluateIntegral(mesh, yCMExpr);     
\end_layout

\begin_layout Plain Layout

double zCM = evaluateIntegral(mesh, zCMExpr);     
\end_layout

\begin_layout Plain Layout

Out::os() << "centroid = (" << xCM << ", " << yCM << ", " << zCM << ")"
 << endl;
\end_layout

\end_inset

We next compute the first Fourier sine coefficient of the solution on the
 surface of the hole, 
\begin_inset Formula 
\[
A_{1}=\frac{\int_{\mbox{hole}}u\sin\phi\, d\Omega}{\int_{\mbox{hole}}\sin^{2}\phi\, d\Omega}.
\]

\end_inset


\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

/* Compute $
\backslash
sin
\backslash
phi$ from Cartesian coordinates $(x,y)$ */
\end_layout

\begin_layout Plain Layout

Expr r = sqrt(x*x + y*y);     
\end_layout

\begin_layout Plain Layout

Expr sinPhi = y/r;     
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Define expressions for the Fourier coefficients */
\end_layout

\begin_layout Plain Layout

Expr fourierSin1Expr = Integral(hole, sinPhi*soln, quad2); 
\end_layout

\begin_layout Plain Layout

Expr fourierDenomExpr = Integral(hole, sinPhi*sinPhi, quad2);
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Evaluate the integrals */    
\end_layout

\begin_layout Plain Layout

double fourierSin1 = evaluateIntegral(mesh, fourierSin1Expr);
\end_layout

\begin_layout Plain Layout

double fourierDenom = evaluateIntegral(mesh, fourierDenomExpr);
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

/* Write the results */  
\end_layout

\begin_layout Plain Layout

Out::os() << "fourier sin m=1 = " << fourierSin1/fourierDenom << endl;
\end_layout

\end_inset

As the final postprocessing example, we compute the 
\begin_inset Formula $L^{2}$
\end_inset

 norm of the solution 
\begin_inset Formula $u$
\end_inset

,
\begin_inset Formula 
\[
\left\Vert u\right\Vert _{2}=\sqrt{\int_{\Omega}u^{2}\, d\Omega}.
\]

\end_inset


\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

Expr L2NormExpr = Integral(interior, soln*soln, quad2);     
\end_layout

\begin_layout Plain Layout

double l2Norm_method1 = sqrt(evaluateIntegral(mesh, L2NormExpr));     
\end_layout

\begin_layout Plain Layout

Out::os() << "method #1: ||soln|| = " << l2Norm_method1 << endl;
\end_layout

\end_inset

Norm computation is a common enough operation that Sundance provides several
 built-in functions to compute various norms.
 For example, the previous computation can be carried out more compactly
 through the code
\end_layout

\begin_layout Standard
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

double l2Norm_method2 = L2Norm(mesh, interior, soln, quad);     
\end_layout

\begin_layout Plain Layout

Out::os() << "method #2: ||soln|| = " << l2Norm_method2 << endl;
\end_layout

\end_inset

Similar functions exist for the computation of the 
\begin_inset Formula $H^{1}$
\end_inset

 norm and 
\begin_inset Formula $H^{1}$
\end_inset

 seminorm.
\end_layout

\begin_layout Section
Exercises
\end_layout

\begin_layout Enumerate
Change the BC on the hole to 
\begin_inset Formula 
\[
\pd{u}{n}=x^{2}.
\]

\end_inset

In a postprocessing step, compute and compare the fluxes
\begin_inset Formula 
\[
Q_{\mbox{hole}}=\int_{\mbox{hole}}\mathbf{n}\cdot\nabla u\, dA
\]

\end_inset


\begin_inset Formula 
\[
Q_{\Omega\backslash\mbox{hole}}=\int_{\Omega\backslash\mbox{hole}}\mathbf{n}\cdot\nabla u\, dA.
\]

\end_inset

Verify that the net flux is zero.
\end_layout

\begin_layout Enumerate
Define an expression that will compute the average element diameter.
\end_layout

\begin_layout Enumerate
By running on a sequence of refined meshes, verify that the computations
 of the flux and of the first Fourier moment
\begin_inset Formula $A_{1}$
\end_inset

 are converging at the correct rates.
\end_layout

\end_body
\end_document
