#Prog:bamg
#NAME: @code{bamg} - bidimensional anisotropic mesh generator
#@cindex mesh
#@fiindex @file{.bamg} bamg mesh
#@toindex @code{bamg}
#SYNOPSIS:
#@example
#  bamg @var{options} -g @var{input}[.bamgcad] -o @var{ouput}[.bamg]
#@end example
#example:
#  Generate the mesh of a square @code{]1,1[^2} with a mesh size
#  @code{h=0.666} at all vertices. Enter the unix command:
#  @example
#    bamg -g toto.bamgcad -o toto.bamg
#  @end example
#  The geometry in defined in the @code{square.bamgcad} file:
#  @example
#	MeshVersionFormatted 0
#	Dimension 2
#	Vertices 4
#	-1 -1  1
#	 1 -1  2
#	 1  1  3
#	-1  1  4
#	Edges 4
#	1 2    1
#	2 3    2
#	3 4    3
#	4 1    4
#	hVertices
#	0.666 0.666 0.666 0.666
#  @end example
#  The file starts with vertices, coordinates and identifier.
#  Then come the boundary edges, using vertices identifiers and 
#  defining a boundary edge identifier.
#Outline:
# @noindent
# This software can
# @table @code
#  @item 1) create
#  	a mesh from a geometry
#  @item 2) adapt
#	a mesh from an existing background mesh using a metric or a solution file.
#  @item 3) metric build
#	just build a metric file, e.g. if you have an other mesher .
#  @item 3) quality improve
#	 of an existing mesh, by generating a new mesh.
#  @item 5) interpolate
#	a field from one mesh to another.
# @end table
#
#1) create:
#  Create a mesh from a geometry. Example:
#  @example
#    bamg -g toto.bamgcad -o toto.bamg
#  @end example
#  @table @code
#  @item -g @emph{filename}
#	the input file, specifying tghe geometry boundaries of the domain
#	to mesh (bamg file format @code{DB mesh}).
#  @item -o @emph{filename}
#	the output mesh file (bamg file format @code{DB mesh}).
# 	Some alternatives output file formats are supported with some @code{-oXY} options
#       where @code{XY} is one of the supported output file formats (see below).
#  @end table
#  In addition, optional parameter can be added to specify a metric
#  or the quality improvement.
#  All the options are described below.
#2) adapt:
#  Adapt a mesh from a background mesh using a metric or solution file. Example:
#  @example
#    bamg -b toto_bgd.bamg -Mbb toto_bgd_sol.bb -o toto_new.bamg
#  @end example
#  @table @code
#  @item -b @emph{filename}
#     	the input background mesh, where the file suffixe defines the format of the file:
#     	@code{.amdba}, @code{.am_fmt}, @code{.am}, @code{.ftq}, @code{.nopo}.
#	Otherwise the file is the bamg default @code{BD mesh} file format. 
#  @item  -Mbb @emph{filename}
#  @itemx -MBB @emph{filename}
#  @itemx -M @emph{filename}
#	The input metric file.
#       The @code{-Mbb} or @code{-MBB} specifies the solution file from which the
#	metric is automatically computed,
#	where the file is of type @code{bb} or @code{BB} (see file format below).
#	An alternative is to specify directly the metric
#	with the @code{-M} option (file format @code{Metric}).
#  @item -o @emph{filename}
#	the output mesh file (bamg file format @code{DB mesh}).
# 	Some alternatives output file formats are supported with some @code{-oXY} options
#       where @code{XY} is one of the supported output file formats (see below).
#  @end table
#  In addition, optional parameter can be added to control the metric generation
#  and the quality improvement.
#  All the options are described below.
#3) metric build:
#  Construct a metric file for an existing mesh and with a provided
#  solution. This option can be used without generating a new mesh,
#  e.g. if you have an other mesher.
#  @example
#    bamg -r toto_bgd.bamg -Mbb toto_bgd_sol.bb -oM toto_bgd.metric
#  @end example
#  @table @code
#  @item -r @emph{filename}
#	The input mesh file (bamg format @code{DB mesh}). 
#  @item  --Mbb @emph{filename}
#  @itemx --MBB @emph{filename}
#	The input provided solution,
#	where the file is of type @code{bb} or @code{BB} (see file format below).
#  @item -oM @emph{filename}
#	The output metric file, in file format @code{Metric} (see file format below).
#  @end table
#  In addition, optional parameter can be added to control the metric generation.
#  All the options are described below.
#4) quality improve:
#  Improve quality for an existing mesh and generate a new mesh.
#  @example
#    bamg -r toto_bgd.bamg -M toto_bgd.metric -o toto_new.bamg
#  @end example
#  @table @code
#  @item -r @emph{filename}
#	The input mesh file (bamg format @code{DB mesh}). 
#  @item -M @emph{filename}
#	The input metric file, in file format @code{Metric} (see file format below).
#  @item -o @emph{filename}
#	the output mesh file (bamg file format @code{DB mesh}).
# 	Some alternatives output file formats are supported with some @code{-oXY} options
#       where @code{XY} is one of the supported output file formats (see below).
#  @end table
#  In addition, optional parameter can be added to control the quality improvement.
#  All the options are described below.
#5) interpolate:
#  In the adaption process, a solution has been computed with the background mesh.
#  In order to transfer the solution of the problem under consideration on the new
#  generated mesh, an interpolation of old solution is necessary. This tranferred solution
#  may be a good initial guess for the solution on the new mesh. This interpolation is
#  carried out in a P1 Lagrange context.
#  @example
#    bamg -b toto_old.bamg -rbb toto_old.bb -r toto_new.bamg -obb toto_new.bb
#  @end example
#  @table @code
#  @item -b @emph{filename}
#	The destination input mesh file (bamg format @code{DB mesh}). 
#  @item -rbb @emph{filename}
#  @item -rBB @emph{filename}
#	The origin input solution, where the file is of type @code{bb} or @code{BB} (see file format below).
#  @item -r @emph{filename}
#	The origin input mesh file (bamg format @code{DB mesh}). 
#  @item -wbb @emph{filename}
#  @item -wBB @emph{filename}
#	The output solution,as reinterpolated on the destination mesh.
#  @end table
#creation options:
#  @table @code
#  @item -hmax @emph{float}
#	Set the value of the maximal edge size. 
#	Default value is the diameter of the domain to be meshed.
#  @item -hmin @emph{float}
#	Set the value of the minimal edge size. 
#	Default value is related to the size of the domain to be meshed
#	and the grid resolution used by the mesh generator (machine dependent).
#  @item -errg @emph{float}
#	Set the value of the relative error on geometry of the boundary.
#	Default value is 0.1.
#	In any case this value is geater than 1/sqrt(2).
#	Remark that mesh size created by this option can be smaller
#	than the @code{hmin} argument due to geometrical constraint.
#  @item -nbv @emph{int}
#	Set the maximal number of vertices of the generated mesh.
#	Default value is 50000.
#  @end table
#adaptation options:
#  These options are relevant when computing a metric from a scalar field
#  provided in a .bb file. Notice that, when providing a tensor metric in the .bb
#  file, the metric computation is not performed and these options are not relevent.
#  @table @code
#  @item -RelError
#		compute the metric with a relative error. This is the default.
#		In this case, the metric field is defined by
#  @end table
#  @example
#                          1           |H(x)|
#               M(x) = ---------- --------------------
#                      err*coef^2 max(CutOff,|eta(x)|)
#  @end example
#  @table @code
#		where @code{err}, @code{coef}, @code{CutOff} are adjustable
#               parameters defined below, @code{eta} is the solution field read
#               in the input file and @code{H} is its Hessian. Here @code{|eta|}
#               denotes the absolute value of the field @code{eta} and @code{|H|}
#               is the tensor field composed of the absolute values of the Hessian
#               eigenvalues and with the same eigenbasis as @code{H}.
#  @item -AbsError
#		compute the metric with an absolute error.
#		In this case, the metric is defined by
#  @end table
#  @example
#		@code{}          1            |H(x)|
#		M(x) = ---------- ---------------------
#               @code{}        err*coef^2 (sup(eta) - inf(eta))
#  @end example
#               where @code{sup(eta)} and @code{inf(eta)} denotes
#		the two extremal values of the input solution field @code{eta}.
#  @table @code
#  @item -coef @emph{float}
#		the multiplicative coefficient on the mesh size.
#		Default value is 1.0.
#  @item -err @emph{float}
#		the level of the @code{P1} interpolation error.
#		Default value is 0.01.
#		Recall that this error behaves as @code{O(h^2)} locally,
#               where @code{h} is the local mesh size.
#               Remark on the two previous formulae that a change by a factor 1/4
#               is equivalent to a change by a factor 1/2 on the mesh size.
#               So, either @code{coef} or @code{err} are specified in order to
#               generate a convergent mesh family.
#  @item -CutOff @emph{float}
#		the cut-off value used for the relative error criteria.
#		Default value is 1e-5.
#  @item -power @emph{float}
#	 	Set the power parameter of hessien to construct the metric.
#		Default value is 1.
#  @item -NbJacobi @emph{int}
#		Set the number of iterations in a smoothing procedure during the
#		metric construction. The 0 value implies no smoothing. 
#		Default value is 1.
#  @item -ratio @emph{float}
#		Set the ratio for a prescribed smoothing on the metric.
#		If ratio is 0 (default value) or less than 1.1,
#		no smoothing on the metric is done.
#		If ratio > 1.1 the speed of mesh size variation
#		is bounded by log(ratio).
#		Remark tht, as val is closer to 1, the number of vertices generated
#		increases. This may be useful to control the thickness of refined
#		regions near shocks or boundary layers.
#  @item -aniso
#  @itemx  -iso
#	The @code{-anio} enforces the metric to be anisotropic. This is the default.
#	Conversely, the metric may be of isotropic type with the @code{-iso} flag.
#  @item -anisomax @emph{float}
#	Set the bound of mesh anisotropy with respect to minimal 
#	mesh size in all direction so the maximal mesh size in all
#	direction is bounded by the ratio @code{anisomax}.
#	The default value is 1e6.
#       Remark that when @code{anisomax}=1, the generated mesh is isotropic.
#  @item -hminaniso @emph{float}
#	Set the value of @code{hmin} the minimal edge size and set the aniso mode.
#  @item -maxsubdiv @emph{float}
#	Change the metric such that the maximal subdivision of a background's
#	edge is bound by the @code{maxsubdiv} number.
#	The @code{maxsubdiv} number is alway limited by 10 and this is the default value.
#  @item  -KeepBackVertices 
#  @itemx -noKeepBackVertices
#	Try to Keep old vertices (default).
#	Otherwise, all vertices are created from scratch.
#  @item  -NoRescaling
#  @itemx -Rescaling
#      Don't rescale the solution between @code{[0,1]} before metric computation
#      Default is to rescale.
#  @end table
#quality improvement options:
#  @table @code
#  @item -NbSmooth @emph{int}
#	Set the number of iterations of the mesh smoothing procedure.
#	Default value is 3.
#  @item -omega @emph{float}
#	Set the relaxation parameter of the smoothing procedure,
#	Default value is 1.8.
#  @item  -splitpbedge
#  @itemx -nosplitpbedge
#	Sometimes, an internal edge can have its two vertices on the boundary.
#	This causes a triangle to have all its vertices on the boundary.
#	With the @code{-splitpbedge} option, this edge is splited in two, and this
#	situation is avoided.
#	By default, don't split.
#  @item -thetaquad @emph{float}
#	to create quad with 2 triangles 
#	Merge two triangles into a quadrilateral when the four angles of the
#	quadrilateral are in the range @code{[thetaquad, 180-thetaquad]}.
#  @item -2
# 	to create the mesh with a mesh size divided by two.
#  @item -2q
#	to split all triangles in three quadrilaterls, and to split all
#	quadrilaterals in four.
#  @end table
#output mesh format options:
#  @table @code
#  @item -o       @emph{filename}
#		 bamg DB mesh file format (default).
#  @item -oamdba  @emph{filename}
#		 amdba format.
#  @item -oftq    @emph{filename}
#		 ftq format.
#  @item -omsh    @emph{filename}
#		 msh format (freefem3 format).
#  @item -oam_fmt @emph{filename}
#		 am_fmt format.
#  @item -oam     @emph{filename}
#		 am format.
#  @item -onopo   @emph{filename}
#		 nopo format.
#  @end table
#others options:
#  @table @code
#  @item -thetamax @emph{float}
#	Set the angular limit for a corner in degre to be curved.
#       The angle is defined from two normals of two concecutives edges.
#	The default is 180 degree, i.e. no corners are curved.
#	This option is usefull when no geomtry are provided, e.g. remeshing from an
#	other mesh file format (@code{am_fmt}, @code{amdba}, @code{nopo}, etc).
#	This parameter is normaly specified in the geometry boundaries file (in BD file format)
#	by the @code{AngleOfCornerBound} optional section: when this file format is
#	used, this option has no effet.
#  @item -v @emph{int}
#	Set the level of printing (verbosity), which can be chosen between
#	0 and 10. Default value is 1.
#  @end table
#geometry file format (bamgcad):
#  The general structure allows to specify a mesh describing the geometry of the given domain.
#  The identification of the boundaries are used to define boundary conditions for
#  a partial derivative equation problem.
#  In this case, some of the above sections are not relevant.
#  First the required sections are:
#  @example
#    MeshVersionFormatted 0
#    Dimension 2
#    Vertices @emph{nv}
#    @{@emph{x_k} @emph{y_k} @emph{i_k}@} @emph{k}=1:@emph{nv}
#    Edges @emph{ne}
#    @{@emph{i_l} @emph{j_l} @emph{k_l}@} @emph{l}=1:@emph{ne}
#  @end example
#  Next, the optional sections:
#  @example
#    SubDomain @emph{nd}
#    @{2 @emph{ie_k} @emph{orient_k} @emph{id_k}@} @emph{k=1:nd}
#  @end example
#  A sub-domain, i.e. a bounded connex components of the plan
#  is defined using one edge identifier @emph{ie} along with
#  an orientation information @emph{orient}, indicating on which side
#  of this entity the sub-domain lies. This feature is usefull, e.g. when
#  dealing with a domain with holes.
#  The sub-domain number is @emph{id}.
#  If no sub-domain are defined, then we
#  suppose to mesh all the bounded connex component of the plan.
#  Remark: @code{SubDomainFromGeom} is equivalent to @code{SubDomain}.
#  @example
#    AngleOfCornerBound @emph{angle}
#  @end example
#  The @code{AngleOfCornerBound} specifies 
#  the angular limit for a corner in degre to be curved.
#  The angle is defined from two normals of two concecutives edges.
#  The default is 180 degree, i.e. no corners are curved.
#  When this angle is defined, some corners could be specified not to be curved by
"  the following list:
#  @example
#    Corners @emph{nc}
#    @{@emph{i_k}@} @emph{k}=1:@emph{nc}
#  @end example
#  The curved geometric representation of a boundary in two dimensions
#  uses the edges provided in the data structure so as to define some curves
#  of order three in the following way:
#  @table @code
#  @item *
#        an edge whose endpoints are corners and if no additional information are provided will
#        be represented by a straight segment,
#  @item *
#        an edge whose endpoints are corners but whose tangent is provided at one endpoint will
#        be represented by a curve of degree two,
#  @item *
#        an edge whose endpoints are corners but whose tangents are provided at these corners
#        will be represented by a curve of degree three,
#  @item *
#        an edge whose endpoints are not corners and with no additional information will be
#        represented by a curve of degree three. Indeed, we use in this case the adjacent edges
#        so as to evaluate the tangents at the edge endpoints.
#  @end table
#
#  In short, an edge defined by two informations will be approached by a straight line, three
#  information allow to obtain a curve of degree two and four data allow for a approximation
#  of degree three. The tangents are optionally specified by:
#  @example
#    TangentAtEdges @emph{nt}
#    @{@emph{ie}_k @emph{ive_k} @emph{xt} @emph{yt}@} @emph{k}=1:@emph{nt}
#  @end example
#  For the edge identifier @emph{ie}, the tangent at its @emph{ive} vertex (@emph{ive} takes value 1 or 2)
#  is specified by its components @emph{xt} and @emph{yt}.
#  Giving the tangent vector of an edge by means of the tangent vector at a point enables 
#  us to deal with the case where several edges (boundary lines) are emanating from a point.
#
#  The required vertices, are the vertices of the support that must be
#  present in the mesh as element vertices. Similarly, some edges
#  can be required:
#  @example
#    RequiredVertices @emph{nrv}
#    @{@emph{iv_k}@} @emph{k}=1:@emph{nrv}
#    RequiredEdges (@emph{nre}
#    @{@emph{ie_k}@} @emph{k}=1:@emph{nre}
#  @end example
future options:
#  The following features are planed for future work.
#  For periodic boundary conditions, the section @code{EquivalencedEdges}
#  indicates that two edges must be meshed the same way:
#  @example
#    EquivalencedEdges @emph{nee}
#    @{@emph{ie1_k} @emph{ie2_k}@} @emph{k}=1:@emph{nee}
#  @end example
#  Crack definition is the purpose of the @code{CrackedEdges} section.
#  We specify then that an edge is identical in terms of geometry to another edge:
#  @example
#    CrackedEdges @emph{nce}
#    @{@emph{ie1_k} @emph{ie2_k}@} @emph{k}=1:@emph{nce}
#  @end example
#credits:
#	Frederic Hecht <Frederic.Hecht@@inria.fr> is the author of bamg.
#	Pierre Saramito <Pierre.Saramito@@imag.fr> writes this unix man page.
#more reading:
#  The original site of the bamg mesh generator is @url{http://www.ann.jussieu.fr/hecht/ftp/bamg}.
#  Please read @url{http://www.ann.jussieu.fr/hecht/ftp/bamg/bamg.pdf} for
#  the detailled file formats and more advanced examples, e.g. a mesh
#  adaptation loop to minimize the P1 Lagrange interpolation error.
#End:
