doc/user/finley.tex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Copyright (c) 2003-2018 by The University of Queensland
% http://www.uq.edu.au
%
% Primary Business: Queensland, Australia
% Licensed under the Apache License, version 2.0
% http://www.apache.org/licenses/LICENSE-2.0
%
% Development until 2012 by Earth Systems Science Computational Center (ESSCC)
% Development 2012-2013 by School of Earth Sciences
% Development from 2014 by Centre for Geoscience Computing (GeoComp)
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{The \finley Module}\label{chap:finley}
%\declaremodule{extension}{finley}
%\modulesynopsis{Solving linear, steady partial differential equations using finite elements}

The \finley library allows the creation of domains for solving
linear, steady partial differential
equations\index{partial differential equations} (PDEs) or systems
of PDEs using isoparametrical finite elements\index{FEM!isoparametrical}.
It supports unstructured 1D, 2D and 3D meshes.
The PDEs themselves are represented by the \LinearPDE class
of \escript.
\finley is parallelized under both \OPENMP and \MPI.
A more restricted form of this library ({\it dudley}) is described in 
Section~\ref{sec:dudley}.

\section{Formulation}
For a single PDE that has a solution with a single component the linear PDE is
defined in the following form:
\begin{equation}\label{FINLEY.SINGLE.1}
\begin{array}{cl} &
\displaystyle{
\int_{\Omega}
A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v_{,j} u+ C_{l} \cdot v u_{,l}+D \cdot vu \; d\Omega }  \\
+ & \displaystyle{\int_{\Gamma} d \cdot vu \; d{\Gamma} }
+  \displaystyle{\int_{\Gamma^{contact}} d^{contact} \cdot [v][u] \; d{\Gamma} } \\
= & \displaystyle{\int_{\Omega}  X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega }\\
+ & \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}}  +
\displaystyle{\int_{\Gamma^{contact}} y^{contact}\cdot [v] \; d{\Gamma}} \\
\end{array}
\end{equation}

\section{Meshes}
\label{FINLEY MESHES}

\begin{figure}
\centerline{\includegraphics{FinleyMesh}}
\caption{Subdivision of an Ellipse into triangles order 1 (\finleyelement{Tri3})}
\label{FINLEY FIG 0}
\end{figure}

To understand the usage of \finley one needs to have an understanding of how
the finite element meshes\index{FEM!mesh} are defined.
\fig{FINLEY FIG 0} shows an example of the subdivision of an ellipse into
so-called elements\index{FEM!elements}\index{element}.
In this case, triangles have been used but other forms of subdivisions can be
constructed, e.g. quadrilaterals or, in the three-dimensional case, into
tetrahedra and hexahedra. The idea of the finite element method is to
approximate the solution by a function which is a polynomial of a certain order
and is continuous across its boundary to neighbour elements.
In the example of \fig{FINLEY FIG 0} a linear polynomial is used on each
triangle. As one can see, the triangulation is quite a poor approximation of
the ellipse. It can be improved by introducing a midpoint on each element edge
then positioning those nodes located on an edge expected to describe the
boundary, onto the boundary.
In this case the triangle gets a curved edge which requires a parameterization
of the triangle using a quadratic polynomial.
For this case, the solution is also approximated by a piecewise quadratic
polynomial (which explains the name isoparametrical elements),
see \Refe{Zienc,NumHand} for more details.
\finley also supports macro elements\index{macro elements}.
For these elements a piecewise linear approximation is used on an element which
is further subdivided (in the case of \finley halved).
As such, these elements do not provide more than a further mesh refinement but
should be used in the case of incompressible flows, see \class{StokesProblemCartesian}.
For these problems a linear approximation of the pressure across the element is
used (use the \ReducedSolutionFS) while the refined element is used to
approximate velocity. So a macro element provides a continuous pressure
approximation together with a velocity approximation on a refined mesh.
This approach is necessary to make sure that the incompressible flow has a
unique solution.

The union of all elements defines the domain of the PDE.
Each element is defined by the nodes used to describe its shape.
In \fig{FINLEY FIG 0} the element, which has type \finleyelement{Tri3}, with
element reference number $19$\index{element!reference number} is defined by the
nodes with reference numbers $9$, $11$ and $0$\index{node!reference number}.
Notice that the order is counterclockwise.
The coefficients of the PDE are evaluated at integration nodes with each
individual element.
For quadrilateral elements a Gauss quadrature scheme is used.
In the case of triangular elements a modified form is applied.
The boundary of the domain is also subdivided into elements\index{element!face}.
In \fig{FINLEY FIG 0} line elements with two nodes are used.
The elements are also defined by their describing nodes, e.g. the face element
with reference number $20$, which has type \finleyelement{Line2}, is defined by
the nodes with the reference numbers $11$ and $0$.
Again the order is crucial, if moving from the first to second node the domain
has to lie on the left hand side (in the case of a two-dimensional surface
element the domain has to lie on the left hand side when moving
counterclockwise). If the gradient on the surface of the domain is to be
calculated rich face elements need to be used. Rich elements on a face are
identical to interior elements but with a modified order of nodes such that the
'first' face of the element aligns with the surface of the domain.
In \fig{FINLEY FIG 0} elements of the type \finleyelement{Tri3Face} are used.
The face element reference number $20$ as a rich face element is defined by the
nodes with reference numbers $11$, $0$ and $9$.
Notice that the face element $20$ is identical to the interior element $19$
except that, in this case, the order of the node is different to align the first
edge of the triangle (which is the edge starting with the first node) with the
boundary of the domain.

Be aware that face elements and elements in the interior of the domain must
match, i.e. a face element must be the face of an interior element or, in case
of a rich face element, it must be identical to an interior element.
If no face elements are specified \finley implicitly assumes homogeneous
natural boundary conditions\index{natural boundary conditions!homogeneous},
i.e. \var{d}=$0$ and \var{y}=$0$, on the entire boundary of the domain.
For inhomogeneous natural boundary conditions\index{natural boundary conditions!inhomogeneous},
the boundary must be described by face elements.

\begin{figure}
\centerline{\includegraphics{FinleyContact}}
\caption{Mesh around a contact region (\finleyelement{Rec4})}
\label{FINLEY FIG 01}
\end{figure}

If discontinuities of the PDE solution are considered, contact
elements\index{element!contact}\index{contact conditions} are introduced to
describe the contact region $\Gamma^{contact}$ even if $d^{contact}$ and
$y^{contact}$ are zero.
\fig{FINLEY FIG 01} shows a simple example of a mesh of rectangular elements
around a contact region $\Gamma^{contact}$\index{element!contact}.
The contact region is described by the elements $4$, $3$ and $6$.
Their element type is \finleyelement{Line2_Contact}.
The nodes $9$, $12$, $6$ and $5$ define contact element $4$, where the
coordinates of nodes $12$ and $5$ and nodes $4$ and $6$ are identical, with the
idea that nodes $12$ and $9$ are located above and nodes $5$ and $6$ below the
contact region.
Again, the order of the nodes within an element is crucial.
There is also the option of using rich elements if the gradient is to be
calculated on the contact region. Similarly to the rich face elements these
are constructed from two interior elements by reordering the nodes such that
the 'first' face of the element above and the 'first' face of the element below
the contact regions line up. The rich version of element $4$ is of type
\finleyelement{Rec4Face_Contact} and is defined by the nodes $9$, $12$, $16$,
$18$, $6$, $5$, $0$ and $2$.
\tab{FINLEY TAB 1} shows the interior element types and the corresponding
element types to be used on the face and contacts.
\fig{FINLEY.FIG:1}, \fig{FINLEY.FIG:2} and \fig{FINLEY.FIG:4} show the ordering
of the nodes within an element.

\begin{table}
\centering
\begin{tabular}{l|llll}
\textbf{interior}&\textbf{face}&\textbf{rich face}&\textbf{contact}&\textbf{rich contact}\\
\hline
\finleyelement{Line2} & \finleyelement{Point1} & \finleyelement{Line2Face} & \finleyelement{Point1_Contact} & \finleyelement{Line2Face_Contact}\\
\finleyelement{Line3} & \finleyelement{Point1} & \finleyelement{Line3Face} & \finleyelement{Point1_Contact} & \finleyelement{Line3Face_Contact}\\
\finleyelement{Tri3} & \finleyelement{Line2} & \finleyelement{Tri3Face} & \finleyelement{Line2_Contact} & \finleyelement{Tri3Face_Contact}\\
\finleyelement{Tri6} & \finleyelement{Line3} & \finleyelement{Tri6Face} & \finleyelement{Line3_Contact} & \finleyelement{Tri6Face_Contact}\\
\finleyelement{Rec4} & \finleyelement{Line2} & \finleyelement{Rec4Face} & \finleyelement{Line2_Contact} & \finleyelement{Rec4Face_Contact}\\
\finleyelement{Rec8} & \finleyelement{Line3} & \finleyelement{Rec8Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec8Face_Contact}\\
\finleyelement{Rec9} & \finleyelement{Line3} & \finleyelement{Rec9Face} & \finleyelement{Line3_Contact} & \finleyelement{Rec9Face_Contact}\\
\finleyelement{Tet4} & \finleyelement{Tri6} & \finleyelement{Tet4Face} & \finleyelement{Tri6_Contact} & \finleyelement{Tet4Face_Contact}\\
\finleyelement{Tet10} & \finleyelement{Tri9} & \finleyelement{Tet10Face} & \finleyelement{Tri9_Contact} & \finleyelement{Tet10Face_Contact}\\
\finleyelement{Hex8} & \finleyelement{Rec4} & \finleyelement{Hex8Face} & \finleyelement{Rec4_Contact} & \finleyelement{Hex8Face_Contact}\\
\finleyelement{Hex20} & \finleyelement{Rec8} & \finleyelement{Hex20Face} & \finleyelement{Rec8_Contact} & \finleyelement{Hex20Face_Contact}\\
\finleyelement{Hex27} & \finleyelement{Rec9} & N/A & N/A & N/A\\
\finleyelement{Hex27Macro} & \finleyelement{Rec9Macro} & N/A & N/A & N/A\\
\finleyelement{Tet10Macro} & \finleyelement{Tri6Macro} & N/A & N/A & N/A\\
\finleyelement{Rec9Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
\finleyelement{Tri6Macro} & \finleyelement{Line3Macro} & N/A & N/A & N/A\\
\end{tabular}
\caption{Finley elements and corresponding elements to be used on domain faces
and contacts.
The rich types have to be used if the gradient of the function is to be
calculated on faces and contacts, respectively.}
\label{FINLEY TAB 1}
\end{table}

The native \finley file format is defined as follows.
Each node \var{i} has \var{dim} spatial coordinates \var{Node[i]}, a reference
number \var{Node_ref[i]}, a degree of freedom \var{Node_DOF[i]} and a tag
\var{Node_tag[i]}.
In most cases \var{Node_DOF[i]}=\var{Node_ref[i]} however, for periodic
boundary conditions, \var{Node_DOF[i]} is chosen differently, see example below.
The tag can be used to mark nodes sharing the same properties.
Element \var{i} is defined by the \var{Element_numNodes} nodes
\var{Element_Nodes[i]} which is a list of node reference numbers.
The order of these is crucial. Each element has a reference number
\var{Element_ref[i]} and a tag \var{Element_tag[i]}.
The tag can be used to mark elements sharing the same properties.
For instance elements above a contact region are marked with tag $2$ and
elements below a contact region are marked with tag $1$.
\var{Element_Type} and \var{Element_Num} give the element type and the number
of elements in the mesh.
Analogue notations are used for face and contact elements.
%The following \PYTHON script prints the mesh definition in the \finley file
%format:
%\begin{python}
%  print("%s\n"%mesh_name)
%  # node coordinates:
%  print("%dD-nodes %d\n"%(dim, numNodes))
%  for i in range(numNodes):
%     print("%d %d %d"%(Node_ref[i], Node_DOF[i], Node_tag[i]))
%     for j in range(dim): print(" %e"%Node[i][j])
%     print("\n")
%  # interior elements
%  print("%s %d\n"%(Element_Type, Element_Num))
%  for i in range(Element_Num):
%     print("%d %d"%(Element_ref[i], Element_tag[i]))
%     for j in range(Element_numNodes): print(" %d"%Element_Nodes[i][j])
%     print("\n")
%  # face elements
%  print("%s %d\n"%(FaceElement_Type, FaceElement_Num))
%  for i in range(FaceElement_Num):
%     print("%d %d"%(FaceElement_ref[i], FaceElement_tag[i]))
%     for j in range(FaceElement_numNodes): print(" %d"%FaceElement_Nodes[i][j])
%     print("\n")
%  # contact elements
%  print("%s %d\n"%(ContactElement_Type, ContactElement_Num))
%  for i in range(ContactElement_Num):
%     print("%d %d"%(ContactElement_ref[i], ContactElement_tag[i]))
%     for j in range(ContactElement_numNodes): 
%         print(" %d"%ContactElement_Nodes[i][j])
%     print("\n")
%  # point sources (not supported yet)
%  print("Point1 0")
%\end{python}

%The following example of a mesh file defines the mesh shown in \fig{FINLEY FIG 01}:
%\begin{verbatim}
%Example 1
%2D Nodes 16
%0   0 0 0.   0.
%2   2 0 0.33 0.
%3   3 0 0.66 0.
%7   4 0 1.   0.
%5   5 0 0.   0.5
%6   6 0 0.33 0.5
%8   8 0 0.66 0.5
%10 10 0 1.0  0.5
%12 12 0 0.   0.5
%9   9 0 0.33 0.5
%13 13 0 0.66 0.5
%15 15 0 1.0  0.5
%16 16 0 0.   1.0
%18 18 0 0.33 1.0
%19 19 0 0.66 1.0
%20 20 0 1.0  1.0
%Rec4 6
% 0 1  0  2  6  5
% 1 1  2  3  8  6
% 2 1  3  7 10  8
% 5 2 12  9 18 16
% 7 2 13 19 18  9
%10 2 20 19 13 15
%Line2 0
%Line2_Contact 3
% 4 0  9 12  6 5
% 3 0 13  9  8 6
% 6 0 15 13 10 8
%Point1 0
%\end{verbatim}
%Notice that the order in which the nodes and elements are given is arbitrary.
%In the case that rich contact elements are used the contact element section
%gets the form
%\begin{verbatim}
%Rec4Face_Contact 3
% 4 0  9 12 16 18  6  5  0  2
% 3 0 13  9 18 19  8  6  2  3
% 6 0 15 13 19 20 10  8  3  7
%\end{verbatim}
%Periodic boundary conditions\index{boundary conditions!periodic} can be
%introduced by altering \var{Node_DOF}.
%It allows identification of nodes even if they have different physical locations.
%For instance, to enforce periodic boundary conditions at the face $x_0=0$ and
%$x_0=1$ one identifies the degrees of freedom for nodes $0$, $5$, $12$ and $16$
%with the degrees of freedom for $7$, $10$, $15$ and $20$, respectively.
%The node section of the \finley mesh now reads:
%\begin{verbatim}
%2D Nodes 16
%0   0 0 0.   0.
%2   2 0 0.33 0.
%3   3 0 0.66 0.
%7   0 0 1.   0.
%5   5 0 0.   0.5
%6   6 0 0.33 0.5
%8   8 0 0.66 0.5
%10  5 0 1.0  0.5
%12 12 0 0.   0.5
%9   9 0 0.33 0.5
%13 13 0 0.66 0.5
%15 12 0 1.0  0.5
%16 16 0 0.   1.0
%18 18 0 0.33 1.0
%19 19 0 0.66 1.0
%20 16 0 1.0  1.0
%\end{verbatim}

\clearpage
\input{finleyelements}
\clearpage

\section{Macro Elements}
\label{SEC FINLEY MACRO}

\begin{figure}[th]
\begin{center}
\includegraphics{FinleyMacroLeg}\\
\subfigure[Triangle]{\label{FINLEY MACRO TRI}\includegraphics{FinleyMacroTri}}\quad
\subfigure[Quadrilateral]{\label{FINLEY MACRO REC}\includegraphics{FinleyMacroRec}}
\end{center}
\caption{Macro elements in \finley}
\end{figure}

\finley supports the usage of macro elements\index{macro elements} which can be
used to achieve LBB compliance when solving incompressible fluid flow problems.
LBB compliance is required to get a problem which has a unique solution for
pressure and velocity. For macro elements the pressure and velocity are
approximated by a polynomial of order 1 but the velocity approximation bases on
a refinement of the elements. The nodes of a triangle and quadrilateral element
are shown in Figures~\ref{FINLEY MACRO TRI} and~\ref{FINLEY MACRO REC},
respectively. In essence, the velocity uses the same nodes like a quadratic
polynomial approximation but replaces the quadratic polynomial by piecewise
linear polynomials. In fact, this is the way \finley defines the macro elements.
In particular \finley uses the same local ordering of the nodes for the macro
element as for the corresponding quadratic element. Another interpretation is
that one uses a linear approximation of the velocity together with a linear
approximation of the pressure but on elements created by combining elements to
macro elements. Notice that the macro elements still use quadratic
interpolation to represent the element and domain boundary.
However, if elements have linear boundaries a macro element approximation for
the velocity is equivalent to using a linear approximation on a mesh which is
created through a one-step global refinement.
Typically macro elements are only required to use when an incompressible fluid
flow problem is solved, e.g. the Stokes problem in \Sec{STOKES PROBLEM}.
Please see \Sec{FINLEY MESHES} for more details on the supported macro elements.

\section{Linear Solvers in \SolverOptions}
If available, Trilinos sovers are used by default, see Chapter \ref{TRILINOS}.
Table~\ref{TAB FINLEY SOLVER OPTIONS 1} and
%Table~\ref{TAB FINLEY SOLVER OPTIONS 2} 
show the solvers %and preconditioners
supported by \finley through the \PASO library.
%Currently direct solvers are not supported under \MPI.
\finley uses the iterative solvers \PCG for symmetric and \BiCGStab
for non-symmetric problems.
%If the direct solver is selected, which can be useful when solving very
%ill-posed equations, \finley uses the \MKL\footnote{If the stiffness matrix is
%non-regular \MKL may return without a proper error code. If you observe
%suspicious solutions when using \MKL, this may be caused by a non-invertible
%operator.} solver package. If \MKL is not available \UMFPACK is used.
%If \UMFPACK is not available a suitable iterative solver from \PASO is used.

\begin{table}
\centering
{\scriptsize
\begin{tabular}{l||c|c|c|c|c|c|c|c}
\member{setSolverMethod} & \member{DIRECT}& \member{PCG} & \member{GMRES} & \member{TFQMR} & \member{MINRES} & \member{PRES20} & \member{BICGSTAB} & lumping \\
\hline
 \hline
 \member{setReordering} & $\checkmark$ & & & & & &\\
 \hline  \member{setRestart} &  & & $\checkmark$ & & & $20$ & \\
 \hline\member{setTruncation} &  & & $\checkmark$ & & & $5$ & \\
   \hline\member{setIterMax} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
 \hline\member{setTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
 \hline\member{setAbsoluteTolerance} &  & $\checkmark$& $\checkmark$ & $\checkmark$& $\checkmark$& $\checkmark$ & $\checkmark$ \\
\hline\member{setReordering} & $\checkmark$ & & & & & & & \\
\end{tabular}
}
\caption{Solvers available for \finley and the \PASO package and the relevant
options in \class{SolverOptions}.
\MKL supports \member{MINIMUM_FILL_IN}\index{linear solver!minimum fill-in ordering}\index{minimum fill-in ordering}
and \member{NESTED_DISSECTION}\index{linear solver!nested dissection ordering}\index{nested dissection}
reordering.
Currently the \UMFPACK interface does not support any reordering.
\label{TAB FINLEY SOLVER OPTIONS 1}}
\end{table}

%\begin{table}
%\begin{center}
%{\scriptsize
%\begin{tabular}{l||c|c|c|c|c|c|c}
%\member{NO_PRECONDITIONER}&
%\member{AMG}&
%\member{JACOBI}&
%\member{GAUSS_SEIDEL}&
%\member{REC_ILU}&
%\member{RILU}&
%\member{ILU0}&
%\member{DIRECT}\\
%\hline
%status:& $\checkmark$ &$\checkmark$&$\checkmark$&$\checkmark$&later&$\checkmark$&later\\
%\hline
%\hline
%\member{setLevelMax}&$\checkmark$& & & & & &\\
%\hline
%\member{setCoarseningThreshold}&$\checkmark$& & & & & &\\
%\hline
%\member{setMinCoarseMatrixSize}&$\checkmark$& & & & & &\\
%\hline
%\member{setMinCoarseMatrixSparsity}&$\checkmark$& & & & & &\\
%\hline
%\member{setNumSweeps}& &$\checkmark$&$\checkmark$& & & &\\
%\hline
%\member{setNumPreSweeps}&$\checkmark$& & & & & &\\
%\hline
%\member{setNumPostSweeps}&$\checkmark$& & & & & &\\
%\hline
%\member{setDiagonalDominanceThreshold}&$\checkmark$& & & & & &\\
%\hline
%\member{setAMGInterpolation}&$\checkmark$& & & & & &\\
%\hline
%\member{setRelaxationFactor}& & & & &$\checkmark$& &\\
%\end{tabular}
%}
%\caption{Preconditioners available for \finley and the \PASO package and the
%relevant options in \class{SolverOptions}.
%\label{TAB FINLEY SOLVER OPTIONS 2}}
%\end{center}
%\end{table}

\section{Functions}
\begin{funcdesc}{ReadMesh}{fileName \optional{, \optional{integrationOrder=-1}, optimize=True}}
creates a \Domain object from the FEM mesh defined in file \var{fileName}.
The file must be in the \finley file format.
If \var{integrationOrder} is positive, a numerical integration scheme is chosen
which is accurate on each element up to a polynomial of degree
\var{integrationOrder}\index{integration order}.
Otherwise an appropriate integration order is chosen independently.
By default the labeling of mesh nodes and element distribution is optimized.
Set \var{optimize=False} to switch off relabeling and redistribution.
\end{funcdesc}

\begin{funcdesc}{ReadGmsh}{fileName, numDim, \optional{, \optional{integrationOrder=-1}, optimize=True\optional{, useMacroElements=False}}}
creates a \Domain object from the FEM mesh defined in file \var{fileName} for
a domain of dimension \var{numDim}.
The file must be in the \gmshextern file format.
If \var{integrationOrder} is positive, a numerical integration scheme is chosen
which is accurate on each element up to a polynomial of degree
\var{integrationOrder}\index{integration order}.
Otherwise an appropriate integration order is chosen independently.
By default the labeling of mesh nodes and element distribution is optimized.
Set \var{optimize=False} to switch off relabeling and redistribution.
If \var{useMacroElements} is set, second order elements are interpreted as
macro elements\index{macro elements}.
\end{funcdesc}

\begin{funcdesc}{MakeDomain}{design\optional{, integrationOrder=-1\optional{, optimizeLabeling=True\optional{, useMacroElements=False}}}}
creates a \finley \Domain from a \pycad \class{Design} object using \gmshextern.
The \class{Design} \var{design} defines the geometry.
If \var{integrationOrder} is positive, a numerical integration scheme is chosen
which is accurate on each element up to a polynomial of degree
\var{integrationOrder}\index{integration order}.
Otherwise an appropriate integration order is chosen independently.
Set \var{optimizeLabeling=False} to switch off relabeling and redistribution
(not recommended).
If \var{useMacroElements} is set, macro elements\index{macro elements} are used.
Currently \function{MakeDomain} does not support \MPI.
\end{funcdesc}

\begin{funcdesc}{load}{fileName}
recovers a \Domain object from a dump file \var{fileName} created by the
\function{dump} method of a \Domain object.
\end{funcdesc}

\begin{funcdesc}{Rectangle}{n0,n1,order=1,l0=1.,l1=1., integrationOrder=-1, \\
  periodic0=\False, periodic1=\False, useElementsOnFace=\False, optimize=\False}
generates a \Domain object representing a two-dimensional rectangle between
$(0,0)$ and $(l0,l1)$ with orthogonal edges.
The rectangle is filled with \var{n0} elements along the $x_0$-axis and
\var{n1} elements along the $x_1$-axis.
For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Rec4} and
\finleyelement{Rec8} are used, respectively.
In the case of \var{useElementsOnFace}=\False, \finleyelement{Line2} and
\finleyelement{Line3} are used to subdivide the edges of the rectangle, respectively.
If \var{order}=-1, \finleyelement{Rec8Macro} and \finleyelement{Line3Macro}\index{macro elements}
are used. This option should be used when solving incompressible fluid flow
problems, e.g. \class{StokesProblemCartesian}.
In the case of \var{useElementsOnFace}=\True (this option should be used if
gradients are calculated on domain faces), \finleyelement{Rec4Face} and
\finleyelement{Rec8Face} are used on the edges, respectively.
If \var{integrationOrder} is positive, a numerical integration scheme is chosen
which is accurate on each element up to a polynomial of degree
\var{integrationOrder}\index{integration order}.
Otherwise an appropriate integration order is chosen independently.
If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
along the $x_0$-direction are enforced.
That means for any solution of a PDE solved by \finley the values on the line
$x_0=0$ will be identical to the values on $x_0=\var{l0}$.
Correspondingly, \var{periodic1}=\True sets periodic boundary conditions in the
$x_1$-direction.
If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
computation and also ParMETIS will be used to improve the mesh partition if
running on multiple CPUs with \MPI.
\end{funcdesc}

\begin{funcdesc}{Brick}{n0,n1,n2,order=1,l0=1.,l1=1.,l2=1., integrationOrder=-1,
  periodic0=\False, periodic1=\False, \\ periodic2=\False, useElementsOnFace=\False,useFullElementOrder=\False, optimize=\False}
generates a \Domain object representing a three-dimensional brick between
$(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. The brick is filled with
\var{n0} elements along the $x_0$-axis,
\var{n1} elements along the $x_1$-axis and
\var{n2} elements along the $x_2$-axis.
For \var{order}=1 and \var{order}=2, elements of type \finleyelement{Hex8} and
\finleyelement{Hex20} are used, respectively.
In the case of \var{useElementsOnFace}=\False, \finleyelement{Rec4} and
\finleyelement{Rec8} are used to subdivide the faces of the brick, respectively.
In the case of \var{useElementsOnFace}=\True (this option should be used if
gradients are calculated on domain faces), \finleyelement{Hex8Face} and
\finleyelement{Hex20Face} are used on the brick faces, respectively.
If \var{order}=-1, \finleyelement{Hex20Macro} and \finleyelement{Rec8Macro}\index{macro elements}
are used. This option should be used when solving incompressible fluid flow
problems, e.g. \class{StokesProblemCartesian}.
If \var{integrationOrder} is positive, a numerical integration scheme is chosen
which is accurate on each element up to a polynomial of degree
\var{integrationOrder}\index{integration order}.
Otherwise an appropriate integration order is chosen independently.
If \var{periodic0}=\True, periodic boundary conditions\index{periodic boundary conditions}
along the $x_0$-direction are enforced.
That means for any solution of a PDE solved by \finley the values on the plane
$x_0=0$ will be identical to the values on $x_0=\var{l0}$.
Correspondingly, \var{periodic1}=\True and \var{periodic2}=\True sets periodic
boundary conditions in the $x_1$-direction and $x_2$-direction, respectively.
If \var{optimize}=\True mesh node relabeling will be attempted to reduce the
computation and also ParMETIS will be used to improve the mesh partition if
running on multiple CPUs with \MPI.
\end{funcdesc}

\begin{funcdesc}{GlueFaces}{meshList, tolerance=1.e-13}
generates a new \Domain object from the list \var{meshList} of \finley meshes.
Nodes in face elements whose difference of coordinates is less than
\var{tolerance} times the diameter of the domain are merged.
The corresponding face elements are removed from the mesh.
\function{GlueFaces} is not supported under \MPI with more than one rank.
\end{funcdesc}

\begin{funcdesc}{JoinFaces}{meshList, tolerance=1.e-13}
generates a new \Domain object from the list \var{meshList} of \finley meshes.
Face elements whose node coordinates differ by less than \var{tolerance} times
the diameter of the domain are combined to form a contact element\index{element!contact}.
The corresponding face elements are removed from the mesh.
\function{JoinFaces} is not supported under \MPI with more than one rank.
\end{funcdesc}

\section{\dudley}
\label{sec:dudley}
The {\it dudley} library is a restricted version of {\it finley}.
So in many ways it can be used as a ``drop-in'' replacement.
Dudley domains are simpler in that only triangular (2D), tetrahedral (3D) and line elements are supported.
Note, this also means that dudley does not support:
\begin{itemize}
\item dirac delta functions
\item contact elements
\item macro elements
\end{itemize}

Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision