\chapter{Extending Mesquite}  \label{sec:extensions}

% \section{Mesquite Programming Framework}
% 
% \subsection{Mesquite Repository} 
% 
% The CVS repository is currently located on the unix NFS at mcs.anl.gov, for example log on to
% 'shakey.mcs.anl.gov' and go to the directory '/home/mesquite/cvs'; the name of the CVS module is
% 'mesquite'.
% 
% Access to the mesquite repository requires an Argonne MCS account, which can be granted through Todd
% Munson, among others: tmunson@mcs.anl.gov .
% One way to use the cvs directory at argonne is through the ssh protocol, i.e. define the environment
% variable 'CVS\_RSH' to be 'ssh' and for example, checking out a working copy would require the
% following command, where :ext: will require CVS to consult the 'CVS\_RSH' variable: 
% \begin{verbatim}
% cvs -d :ext:username@shakey.mcs.anl.gov:/home/mesquite/cvs co mesquite
% \end{verbatim}
% 
% \subsection{Mesquite Makefile} 
% 
% The mesquite makefile is \emph{not} a recursive makefile, i.e. a makefile that tells sub-directories
% to execute their own makefile. Instead, it includes all variables from sub-directories into one main
% makefile located in the main mesquite/ directory and called GNUmakefile.
% 
% Here we describe simple procedures needed for code development.
% 
% \subsubsection{Adding a header file within an existing directory}
% 
% Since adding a header file (.hpp) does not require to compile an extra objet file, no action is
% needed in order for the makefile to use the header file. Just run 'gmake clean; gmake' in order for
% the makefile to rerun its symbolinc links section or altenatively, create a symbolic link manually from
% 'mesquite/includeLinks' to the new header file.
% 
% \subsubsection{Adding a file within an existing directory}
% 
% When adding a '.cpp' file to an existing directory,  one needs to notify the makefile that a new
% object file (.o) needs to be compiled. This is not done automatically in order to provide some
% versatility.
% 
% Simply edit the 'MakefileVariables.inc' file within the directory where your new .cpp file has been added. The first
% variable defines the current directory, let's call it CURRENTDIR. The second variable describes the
% sources in the present directory (let's call it CONTROLSRC): that's the variable you need to add
% your new file name to. For example, the MakefileVariables.inc file used to start with: 
% \begin{verbatim}
% CURRENTDIR = $(srcdir)/dir1
% 
% CURRENTSRC = $(CURRENTDIR)/file1.cpp \
%             $(CURRENTDIR)/file2.cpp
% \end{verbatim}
% and it now starts with:
% \begin{verbatim}
% CURRENTDIR = $(srcdir)/dir1
% 
% CURRENTSRC = $(CURRENTDIR)/file1.cpp \
%             $(CURRENTDIR)/file2.cpp \
%             $(CURRENTDIR)/file3.cpp
% \end{verbatim}
% That's it, you can now run gmake from the 'mesquite'directory 
% and it will pick up all dependencies and include your new file in
% the mesquite library.
% 
% \subsubsection{Adding a directory within the source tree}
% 
% To add a new directory to the source tree, you need two files 
% in the new directory: the 'MakefileVariables.inc' file and
%  the 'MakefileTargets.inc' file. For example, copy those files from 
%  the mesquite/src/Control directory and replace the string 'CONTROL' in 
% those two files by a string unique to your new directory (for example 
% 'CONTROLSRC' becomes 'NEWDIRSRC'). Make sure not to miss any querry/replace.
% 
% You can now define the new directory location and the new source files 
% names in the 'MakefileVariables.inc' file, as explained in the 
% previous section.
% 
% Finally, you need to add the new directory to the MODULENAMES variable in the main makefile
% mesquite/GNUmakefile, and you can run gmake. 
% 
% \subsubsection{Adding a new driver code}
% 
% To add a new driver code (e.g. mesquite/testSuite/test\_1/main.cpp), 
% copy to a new directory under 'mesquite/testSuite/' the
% 'mesquite/testSuite/test\_1/Makefile.inc' file and change 
% within that file the string TEST1 to a new unique string. 
% Now, add the new directory to the TESTNAMES variable within 
% 'mesquite/GNUmakefile'. 
% 
% To compile the new driver, go to the main 'mesquite/' directory and type:
% \begin{verbatim}
% gmake mesquite/yournewdir/main
% \end{verbatim}
% where main will be the executable name (note that this name can be 
% changed in the third variable in Makefile.inc).
% 
% 
% \subsection{Unit Test Suite Makefile}
% 
% The unit test suite, located in 'mesquite/testSuite/unit/' has its 
% own makefile. It is not as robust as the main mesquite makefile and can 
% be improved (it does not pick up all dependencies properly).
% 
% To compile the unit test suite, go into 'mesquite/testSuite/unit/' 
% and type 'gmake'. 
% 
% As you modify the test suite and mesquite in parallel, you might 
% need to use 'gmake clean; gmake' to pick up some dependencies ... 
% or you could improve the makefile. 
% 
% 
% \subsection{Directory Structure}
% 
% The base directory of the Mesquite project contains several
% sub-directories which are intended to help keep the project's
% files organized.  Some of the sub-directories themselves are
% also sub-divided.  Below are descriptions of the first level
% of sub-directories ({\it i.e.,} the directories contained in the
% base directory).
% \begin{enumerate}
% \item doc:  Contains a version of this document and a version of
% the developer's documentation generated with doxygen (TODO: acknowledge
% doxygen).
% \item include:  Contains the Mesquite header file, ``Mesquite.hpp.''
% \item includeLinks:  Contains soft links to the other header files
% used within Mesquite.  
% \item lib:  The location where the Mesquite library, ``libmesquite.a,'' is
% stored.
% \item meshFiles:  Contains example meshes that are used in some of
% the test cases.
% \item mswindow:  Contains the project file for compiling with Visual C++
% (TODO: VC++ trademark statement???).
% \item obj:  The directory where the object files are placed.
% \item src:  Contains the Mesquite source code and header files (except for
% Mesquite.hpp).
% \item testSuite:  Contains example driver codes which use Mesquite.  These
% test cases can only be ran when linked with the correct libraries (generally,
% AOMD or MDB).
% \end{enumerate}
% 
% \subsection{Code Testing Framework}
% 
% Another integral part of the Mesquite framework is the code testing
% infrastructure.  Several testing methodologies have been included
% within Mesquite. Unit testing is extensively used to facilitate
% development and ensure low-level robustness. Functional testing is
% used to ensure that user case scenarios run smoothly.
% 
% We use a broad definition for unit tests in Mesquite. Any test
% performed on a class without need for the entire Mesquite framework is
% considered a unit test. This encompasses simple assertions like
% checking the result of the multiplication of a matrix $A \in
% \Bbb{R}^{3 \times 3}$ by a vector $v \in \Bbb{R}^{3}$ to more complex
% assertions such as checking that a concrete \texttt{QualityImprover}
% correctly repositions a free vertex in a simple patch for a given
% objective function and quality metric.
% 
% Mesquite uses a readily available testing framework called CppUnit
% \cite{cppunit} --- essentially the well known jUnit testing framework
% ported to C++.  Using the unit testing methodology allows the
% developers to write far more robust code.
% 
% Applications using Mesquite may also find the testing framework useful
% when verifying their additions to the code. In particular,
% applications that prefer to implement Mesquite's mesh interface
% instead of using the TSTT mesh interface will want to
% check their implementation with the corresponding unit test collection
% available in Mesquite. In addition, analytic gradient and Hessian
% implementations can be checked against the numerical version provided
% by the {\tt QualityMetric} base class using readily available unit
% tests.
% 
% In addition to unit tests, the Mesquite test suite also includes
% a range of functional tests.  While these tests also use the
% CppUnit framework, they differ from unit tests in that 
% functional tests require the entire Mesquite framework.
% The functional tests are complete and often complex mesh
% optimization problems.  These tests are intended to ensure that
% the individual units of the Mesquite code work together correctly.
% Performing these tests not only helps
% validate the code but also allows developers to evaluate the
% effects of code modifications in terms of Mesquite's accuracy
% and efficiency on `real world' problems.

\section{Defining New Concrete Classes}

% \begin{verbatim}
% Explain that we only mention the truly polymorphic extensions. 
% Extensions that require not only an additional class, 
% but also other changes in the code (switches) are 
% not discussed int he user manual for now. This is a 
% reference manual issue. Give explicit examples of difficult things. 
% \end{verbatim}

The Mesquite architecture uses as much dynamic polymorphism in the
form of inheritance and virtual functions as is possible without
degrading performance.  This allows developers to add new
functionality to Mesquite by inheriting from the appropriate abstract
class and implementing its interface (i.e. its abstract virtual
functions).  We note that the mesh entities, defined by class {\tt
MsqMeshEntity}, are the only exception in our architecture.  Mesh
entities, i.e. triangles, tetrahedrons, quadrangles and hexahedrons,
are implemented in a single class, without the use of dynamic
polymorphism, to eliminate the performance impact of runtime
resolution.

\subsection{Adding a New Quality Metric} \label{sec:QualityMetricImpl}

The primary functionality associated with the {\tt QualityMetric}
class is the \texttt{evaluate\_element} or\texttt{evaluate\_vertex}  function which returns a single quality value
for a given mesh entity.

To implement a new quality metric, a user must inherit from the base
\texttt{QualityMetric} class and implement the `evaluate' function.
\texttt{ QualityMetric} provides a wide range of
functionality that allows the quality metrics to be defined in a
flexible way and therefore gives the user the ability to modify the
metric in a variety of ways.  For example, the condition number
quality metric for a quadrilateral or hexahedral element is computed
by evaluating the condition number at a number of sample points in the
element.  Mesquite allows the user to select which set of sample
points are used in this calculation ({\it e.g.}, the element's
vertices) and how these values are combined to form a single metric
value ({\it e.g.}, linear averaging).  Mesquite is currently being
extended to allow certain quality metrics to be referenced to a
non-isotropic element.

\subsection{Adding a New Objective Function}

\subsection{Adding a New Vertex Mover Algorithm}

A new vertex mover algorithm is defined by inheriting from the
\texttt{VertexMover} abstract class. The \texttt{VertexMover} class 
is an intermediate abstract classe, inheriting from the
\texttt{QualityImprover} class (see Figure \ref{fig:uml}),  which
essential functionality is to implement the \texttt{loop\_over\_mesh}
virtual function that shields the optimization algorithm developer
from the need to distinguish between local or global patches.  The
\texttt{VertexMover} base class also checks the outer termination
criterion to stop iterating over mesh subsets (see section
\ref{termination_section}) and updates the application mesh after
optimizing a patch.

The gathering of the mesh information from a \texttt{Mesh} into the patch is
carried out by the \texttt{PatchData} class, so that the
optimization algorithm receives the appropriate patch to improve
simply by inheriting from \texttt{QualityImprover}.  If needed, one can 
override the \texttt{set\_patch\_type} function to accept only specific
patch types.

% \subsection{Adding a New Topology Modifier Algorithm}



