\chapter{Constraining Mesh to a Geometric Domain}
\label{sec:geom}

Vertex positions may be constrained to a geometric domain by providing Mesquite
with an optional instance of the \texttt{Mesquite::MeshDomain} interface.  This
interface provides two fundamental capabilities: mesh-geometry classification,
and interrogation of local geometric properties.  The methods defined in the 
\texttt{Mesquite::MeshDomain} interface combine both queries into single
operation.  Queries are passed a mesh entity handle (see Section \ref{sec:MeshData}),
and are expected to interrogate the geometric domain that the specified mesh
entity is classified to.

If Mesquite is used to optimize the mesh of a B-Rep solid model (the data model used by all modern CAD systems), then the domain is composed of geometric vertices,
curves, surfaces, and volumes.  Curves are bounded by end vertices, surfaces are
bounded by loops (closed chains) of curves, and volumes are bounded by groups of
surfaces.  Mesquite expects each surface element (triangle, quadrilateral, etc.)
to be associated with a 2D domain (surface).  Vertices may be associated with
a geometric entity that either contains adjacent mesh elements or bounds the
geometric entity containing the adjacent elements. Mesquite does not use 
geometric volumes.  A query for the closest location on the domain for a vertex 
or element whose classification is a geometric volume should simply return the 
input position.  

It is possible to define an optimization problem such that mesh classification
data need not be provided in a \texttt{Mesquite::MeshDomain} implementation. 
This is done by optimizing the mesh associated with each simple geometric
component of the domain separately, with the boundary vertices flagged as fixed.
The following pseudo-code illustrates such an approach for a B-Rep type geometric
domain:
\begin{verbatim}
for each geometric vertex
 mark associated vertex as fixed
end-for
for each curve
 do any application-specific optimization of curve node placement
 mark associated mesh vertices as fixed
end-for
for each surface
 define Mesquite::MeshDomain for surface geometry
 invoke Mesquite to optimize surface mesh
 mark all associated mesh vertices as fixed
end-for
for each volume
 invoke Mesquite to optimize volume mesh w/o Mesquite::MeshDomain
end-for
\end{verbatim}


\section{The ITAPS iGeom and iRel Interfaces} \label{sec:ITAPS}

Mesquite can access mesh domain data through the \emph{iGeom} and \emph{iRel} interface defined by the ITAPS Work Group.  These interfaces provide APIs for accessing B-Rep geometric data and associating mesh with geometry (classification), respectively.  Mesquite provides the \texttt{Mesquite::MsqIGeom} class (\texttt{MsqIGeom.hpp}) as an adaptor for interfacing with appications that present the \emph{iGeom} and \emph{iRel} interfaces.  The use of the \emph{iRel} interface is optional.  If all the mesh vertices are constrained to a single geometric surface, it is sufficient to provide only an iGeom instance to \texttt{Mesquite::MsqIGeom}.  If vertices are constrained to different geometric entities, then the \emph{iRel} interface must be provided to \texttt{Mesquite::MsqIGeom} so Mesquite can determine which iMesh entity a given vertex is constrained to lie in.


\section{Simple Geometric Domains} \label{sec:MsqGeom}

Mesquite provides several implementations of the
\texttt{Mesquite::MeshDomain} interface for simple geometric primitives. All MeshDomains in Mesquite are geometric surfaces upon which meshes consisting of triangles and/or quadrilaterals can exist. Mesquite does not have any implementations of 3D geometric regions. The domains available in Mesquite include:
\begin{itemize}
\item \texttt{PlanarDomain}: An unbounded planar surface.
\item \texttt{XYPlanarDomain}: An unbounded planar surface that exists in the XY-plane.
\item \texttt{SphericalDomain}: A closed spherical surface.
\item \texttt{CylinderDomain}: An unbounded cylindrical surface.
\item \texttt{BoundedCylinderDomain}: A bounded cylindrical surface.
\item \texttt{ConicDomain}: An unbounded cone with a circular cross-section.
\item \texttt{XYRectangle}: An bounded rectangular domain in the XY-Plane.
\end{itemize}

The \texttt{PlanarDomain} is often used to map $\mathbb{R}^{2}$ optimization
problems to $\mathbb{R}^{3}$.  The others are used primarily for testing
purposes.  

\medskip
\noindent Notes about Domains:
\begin{itemize}
\item The \texttt{BoundedCylinderDomain} provides some simplistic mesh-geometry classification capabilities.  The others do not provide any classification functionality.  Creating a bounded Cylinder is a two-step process. First, a cylinder is created via the constructor by specifying a radius, a vector defining the direction of the axis, and a point through which the axis passes.  Second, the bounding part is specified by calling one of the two overloaded methods "create\_curve()".  Both versions accept a distance from the axis where the circular curve to act at the bounding box will be placed along with vertices to be considered bound to the curve.  The vertices are specified by either a list or a mesh depending on which version of the method is used.
\item The \texttt{ConicDomain} is not bounded at the apex.  It extends infinitely in  both directions.
\item The \texttt{XYPlanarDomain} is the only MeshDomain type that can be used with FeasibleNewton optimization.  FeasibleNewton also operates on volume meshes. 
\item The \texttt{XYRectangle} domain is a simple 2D domain used for free-smooth testing. The specified rectangle can be in the XY, YZ, or ZX plane.   The constructor takes as input a point (x,y,z), a height and width, and a plane.  A corresponding bounding box is then created in the specified plane. The method "setup(iMesquite::Mesh* mesh, Mesquite::MsqError\& err)" can then be used to determine if a particular mesh lies completely in the defined bounded rectangle. If any of the vertices of the mesh lie outside the rectangle a non-zero err value will be returned.
\end{itemize}
   
\section{Associating a Mesh with a Domain} \label{sec:MeshDomainAssoc}
The \texttt{MeshDomainAssoc} class is used to associate a \texttt{Mesh} class instance with a \texttt{MeshDomain} class instance.   When the constructor for the \texttt{MeshDomainAssoc} class is called, a check is performed to determine if the characteristics of the mesh are compatible with the associated domain.  

  The constructor for the \texttt{MeshDomainAssoc} class:

\begin{lstlisting}
   MeshDomainAssoc( Mesquite::Mesh* mesh, 
                    Mesquite::MeshDomain* domain, 
                    bool full_compatibility_check=false,
                    bool proceed=false,
                    bool skip_compatibility_check=false )
\end{lstlisting}

\begin{verbatim}
where:

   - 'mesh' is the mesh instance being associated.
   - 'domain' is the domain being associated.
   - 'full_compatibility_check' controls how many vertices will be 
     checked for compatibility with the associated domain.  When false 
     (the default), only the first vertex of the mesh is checked for
     compatibility.  When true, all vertices of the mesh are checked.
   - 'proceed' controls what Mesquite will do if the compatibility
     check fails.  When false (the default), mesquite terminates
     execution.  When true, execution continues.
   - 'skip_compatibility_check' when true, does not perform the
      compatibility check.  When false (the default), the check is 
      performed.
\end{verbatim}

Only the first two parameters are required when calling the constructor.  All other parameters only need to be specified when something other than the default behavior is desired.

The MeshDomainAssoc class is designed to work with planar surface (2D) meshes only.  When using volume (3D) meshes that require a MeshDomainAssoc instance to be created in order to call a function or method, the domain parameter in the constructor should be specified as a NULL. 

 In a given program, many different instances of the \texttt{MeshDomainAssoc} class can be created; one for each combination of a specific mesh, domain, and different values for the optional parameters.

An example of how \texttt{MeshDomainAssoc} is used can be found in the paraboloid\_domain\_test located in the testSuite directory.


