adapt(4rheolef) 						    rheolef-6.1 						   adapt(4rheolef)

NAME

       adapt - mesh adaptation

SYNOPSYS

	geo adapt (const field& phi);
	geo adapt (const field& phi, const adapt_option_type& opts);

DESCRIPTION

	The function adapt implements the mesh adaptation procedure,
	based on the gmsh (isotropic) or bamg (anisotropic) mesh generators.
	The bamg mesh generator is the default in two dimension.
	For dimension one or three, gmsh is the only generator supported yet.
	In the two dimensional case, the gmsh correspond to the opts.generator="gmsh".

	The strategy based on a metric determined from the Hessian of
	a scalar governing field, denoted as phi, and that is supplied by the user.
	Let us denote by H=Hessian(phi) the Hessian tensor of the field phi.
	Then, |H| denote the tensor that has the same eigenvector as H,
	but with absolute value of its eigenvalues:

	 |H| = Q*diag(|lambda_i|)*Qt

	The metric M is determined from |H|.
	Recall that an isotropic metric is such that M(x)=hloc(x)^(-2)*Id
	where hloc(x) is the element size field and Id is the
	identity d*d matrix, and d=1,2,3 is the physical space dimension.

GMSH ISOTROPIC METRIC

		   max_(i=0..d-1)(|lambda_i(x)|)*Id
	 M(x) = -----------------------------------------
		err*hcoef^2*(sup_y(phi(y))-inf_y(phi(y)))

	Notice that the denominator involves a global (absolute) normalization
	sup_y(phi(y))-inf_y(phi(y)) of the governing field phi
	and the two parameters opts.err, the target error,
	and opts.hcoef, a secondary normalization parameter (defaults to 1).

BAMG ANISOTROPIC METRIC

	There are two approach for the normalization of the metric.
	The first one involves a global (absolute) normalization:

				|H(x))|
	 M(x) = -----------------------------------------
		err*hcoef^2*(sup_y(phi(y))-inf_y(phi(y)))

	The first one involves a local (relative) normalization:

				|H(x))|
	 M(x) = -----------------------------------------
		err*hcoef^2*(|phi(x)|, cutoff*max_y|phi(y)|)

	Notice that the denominator involves a local value phi(x).
	The parameter is provided by the optional variable opts.cutoff;
	its default value is 1e-7.
	The default strategy is the local normalization.
	The global normalization can be enforced by setting
	opts.additional="-AbsError".

	When choosing global or local normalization ?

	When the governing field phi is bounded,
	i.e. when err*hcoef^2*(sup_y(phi(y))-inf_y(phi(y)))
	will converge versus mesh refinement to a bounded value,
	the global normalization defines a metric that is mesh-independent
	and thus the adaptation loop will converge.

	Otherwise, when phi presents singularities, with unbounded
	values (such as corner singularity, i.e. presents peacks when represented
	in elevation view), then the mesh adaptation procedure
	is more difficult. The global normalization
	divides by quantities that can be very large  and the mesh adaptation
	can diverges when focusing on the singularities.
	In that case, the local normalization is preferable.
	Moreover, the focus on singularities can also be controled
	by setting opts.hmin not too small.

	The local normalization has been choosen as the default since it is
	more robust. When your field phi does not present singularities,
	then you can swith to the global numbering that leads to a best
	equirepartition of the error over the domain.

IMPLEMENTATION

       struct adapt_option_type {
	   typedef std::vector<int>::size_type size_type;
	   std::string generator;
	   bool isotropic;
	   Float err;
	   Float errg;
	   Float hcoef;
	   Float hmin;
	   Float hmax;
	   Float ratio;
	   Float cutoff;
	   size_type n_vertices_max;
	   size_type n_smooth_metric;
	   bool splitpbedge;
	   Float thetaquad;
	   Float anisomax;
	   bool clean;
	   std::string additional;
	   bool double_precision;
	   Float anglecorner;  // angle below which bamg considers 2 consecutive edge to be part of
			       // the same spline
	   adapt_option_type() :
	       generator(""),
	       isotropic(true), err(1e-2), errg(1e-1), hcoef(1), hmin(0.0001), hmax(0.3), ratio(0), cutoff(1e-7),
	       n_vertices_max(50000), n_smooth_metric(1),
	       splitpbedge(false), thetaquad(std::numeric_limits<Float>::max()),
	       anisomax(1e6), clean(false), additional("-RelError"), double_precision(false),
	       anglecorner(0)
	    {}
       };
       template <class T, class M>
       geo_basic<T,M>
       adapt (
	 const field_basic<T,M>& phi,
	 const adapt_option_type& options = adapt_option_type());

rheolef-6.1							    rheolef-6.1 						   adapt(4rheolef)