diff --git a/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h b/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h new file mode 100644 index 00000000000..63b75dad08d --- /dev/null +++ b/Mesh_2/doc/Mesh_2/CGAL/lloyd_optimize_mesh_2.h @@ -0,0 +1,99 @@ +namespace CGAL { + +/*! +\ingroup PkgMesh_2Functions + +The function `lloyd_optimize_mesh_2()` is a mesh optimization process +based on the minimization of a global energy function. + +In `lloyd_optimize_mesh_2()`, the minimized global energy may be interpreted +as the \f$ L^1\f$-norm of the error achieved +when the function \f$ x^2\f$ is interpolated on the mesh domain +using a piecewise linear function which is linear +in each cell of the Voronoi diagram of the mesh vertices. + +The optimizer `lloyd_optimize_mesh_2()` works in iterative steps. +At each iteration, mesh vertices are moved into +positions that bring to zero the energy gradient +and the Delaunay triangulation is updated. +Vertices on the mesh boundaries are not moved. + +\pre `time_limit` \f$ \geq\f$ 0 and 0 \f$ \leq\f$ `convergence` \f$ \leq\f$ 1 and 0 \f$ \leq\f$ `freeze_bound` \f$ \leq\f$ 1 + +\tparam CDT is required to be or derive from +`CGAL::Constrained_Delaunay_triangulation_2`. +The argument `cdt`, passed by reference, provides the initial mesh +and is modified by the algorithm to represent the final optimized mesh. + +The function has several optional parameters which are named parameters +(we use the Boost.Parameter library). +Therefore, when calling the function, the parameters can be provided in any order +provided that the names of the parameters are used +(see example at the bottom of this page). + +\cgalHeading{Named Parameters} + +- `parameters::time_limit` +is used to set up, in seconds, +a CPU time limit after which the optimization process is stopped. This time is +measured using `Timer`. +The default value is 0 and means that there is no time limit. + +- `parameters::%max_iteration_number` sets a limit on the +number of performed iterations. The default value of 0 means that there is +no limit on the number of performed iterations. + +- `parameters::%convergence` is a stopping criterion based on convergence: +the optimization process is stopped, when at the last iteration, +the displacement of any vertex is less than a given fraction of the +length of the shortest edge incident to that vertex. +The parameter `convergence` gives the threshold ratio. + +- `parameters::freeze_bound` is designed to reduce running time of each +optimization iteration. Any vertex that has a displacement less than a given +fraction of the length of its shortest incident edge, is frozen (i.e.\ is +not relocated). The parameter `freeze_bound` gives the threshold ratio. +The default value is 0.001. If it is set to 0, freezing of vertices is disabled. + + +\return +The function `lloyd_optimize_mesh_2()` returns a value of type `CGAL::Mesh_optimization_return_code` +which is: +