Merge pull request #256 from mpotse/develop

various bits of documentation
MmgTools · Mar 28, 2024 · a4a5ba3 · a4a5ba3
2 parents c51f5f4 + 47a6283
commit a4a5ba3
Show file tree

Hide file tree

Showing 6 changed files with 46 additions and 29 deletions.
diff --git a/src/common/libmmgtypes.h b/src/common/libmmgtypes.h
@@ -386,7 +386,7 @@ typedef MMG5_Quad * MMG5_pQuad;
  *
  * \brief Structure to store tetrahedra of an MMG mesh.
  *
- * \remark Numbering convention
+ * \remark The numbering conventions are illustrated below. Face i lies opposite to vertex i.
  * \verbatim
  *      Vertices                     Edges                       Faces           *
  *           3                          .                           .            *
@@ -410,8 +410,9 @@ typedef struct {
   MMG5_int ref; /*!< Reference of the tetrahedron */
   MMG5_int base;
   MMG5_int mark; /*!< Used for delaunay */
-  MMG5_int xt; /*!< Index of the surface \ref MMG5_xTetra associated to
-                 the tetrahedron*/
+  MMG5_int xt; /*!< Index of the surface \ref MMG5_xTetra associated to the
+                 tetrahedron (only for tetrahedra that are adjacent to
+                 surfaces) */
   MMG5_int flag;
   int16_t  tag;
 } MMG5_Tetra;

diff --git a/src/mmg2d/libmmg2d.h b/src/mmg2d/libmmg2d.h
@@ -449,9 +449,10 @@ LIBMMG2D_EXPORT int  MMG2D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  *
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
- * \param typEntity type of solutions entities (vertices, triangles...).
+ * \param typEntity type of solutions entities (vertices, triangles, ..., 
+ *        see \ref MMG5_entities for possible values).
  * \param np number of solutions.
- * \param typSol type of solution (scalar, vectorial...).
+ * \param typSol type of solution (scalar, vectorial, ..., see \ref MMG5_type for possible values).
  * \return 0 on failure, 1 otherwise.
  *
  * Initialize an array of solution field: set dimension, types and number of
@@ -479,7 +480,7 @@ LIBMMG2D_EXPORT int  MMG2D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * \param nsols number of solutions per entity
  * \param nentities number of entities
  * \param typSol    Array of size nsol listing the type of the solutions
- *                  (scalar, vectorial...).
+ *                  (scalar, vectorial, ..., see \ref MMG5_type for possible values).
  * \return 0 on failure, 1 otherwise.
  *
  * Initialize an array of solutions field defined at vertices: set dimension,
@@ -1059,9 +1060,11 @@ LIBMMG2D_EXPORT int  MMG2D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  *
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
- * \param typEntity pointer to the type of entities to which solutions are applied.
+ * \param typEntity pointer to the type of entities to which solutions are applied
+ *        (see \ref MMG5_entities for possible values).
  * \param np pointer to the number of solutions.
- * \param typSol pointer to the type of the solutions (scalar, vectorial...)
+ * \param typSol pointer to the type of the solutions
+ *               (scalar, vectorial, ..., see \ref MMG5_type for possible values)
  * \return 1.
  *
  * \remark Fortran interface:
@@ -1083,7 +1086,7 @@ LIBMMG2D_EXPORT int  MMG2D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * \param sol pointer to an array of sol structure.
  * \param nentities pointer to the number of entities.
  * \param typSol array of size MMG5_NSOL_MAX to store type of each solution
- * (scalar, vector..).
+ *        (scalar, vectorial, ..., see \ref MMG5_type for possible values).
  *
  * \return 1.
  *

diff --git a/src/mmg3d/boulep_3d.c b/src/mmg3d/boulep_3d.c
@@ -39,6 +39,9 @@
 extern MMG5_Info  info;
 
 /**
+ * \brief Given a vertex and a tetrahedron, find all tetrahedra in the ball of
+ * this vertex.
+ *
  * \param mesh pointer to the mesh structure.
  * \param start index of the starting tetrahedra.
  * \param ip local index of the point in the tetrahedra \a start.
@@ -47,8 +50,8 @@ extern MMG5_Info  info;
  * \return 0 if fail and the number of the tetra in the ball otherwise.
  *
  * Fill the volumic ball (i.e. filled with tetrahedra) of point \a ip in tetra
- * \a start. Results are stored under the form \f$4*kel + jel\f$, kel = number
- * of the tetra, jel = local index of p within kel.
+ * \a start. Results are stored in the form \f$4*kel + jel\f$, kel = number
+ * of tetrahedra, jel = local index of p within kel.
  *
  */
 int MMG5_boulevolp (MMG5_pMesh mesh, MMG5_int start, int ip, int64_t * list){

diff --git a/src/mmg3d/libmmg3d.h b/src/mmg3d/libmmg3d.h
@@ -355,9 +355,12 @@ LIBMMG3D_EXPORT int  MMG3D_Set_inputParamName(MMG5_pMesh mesh, const char* fpara
  * \brief Initialize a solution field.
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
- * \param typEntity type of solutions entities (vertices, triangles...).
+ * \param typEntity type of entities on which the solution is defined (vertices, triangles, ...).
+ *        See \ref MMG5_entities for the defined entity types. Currently only \ref MMG5_Vertex
+ *        is supported.
  * \param np number of solutions.
- * \param typSol type of solution (scalar, vectorial...).
+ * \param typSol type of solution (scalar, vectorial, ...,
+ *        see \ref MMG5_type for possible values).
  * \return 0 if failed, 1 otherwise.
  *
  * Initialize a solution field: set dimension, types and number of data.
@@ -382,7 +385,7 @@ LIBMMG3D_EXPORT int  MMG3D_Set_inputParamName(MMG5_pMesh mesh, const char* fpara
  * \param nsols number of solutions per entity
  * \param nentities number of vertices
  * \param typSol Array of size nsols listing the type of the solutions
- *                  (scalar, vectorial...).
+ *                 (scalar, vectorial, ..., see \ref MMG5_type for possible values).
  * \return 0 if failed, 1 otherwise.
  *
  * Initialize a solution field defined at vertices: set dimension,
@@ -1327,7 +1330,7 @@ LIBMMG3D_EXPORT int  MMG3D_Set_inputParamName(MMG5_pMesh mesh, const char* fpara
  * \param mesh pointer to the mesh structure.
  *
  * To mark as ended a mesh given without using the API functions (for example,
- * mesh given by mesh->point[i] = 0 ...). This function performs veritications,
+ * mesh given by mesh->point[i] = 0 ...). This function performs verifications,
  * e.g. to make sure that all tetrahedra are consistently oriented.
  *
  * \remark Fortran interface:
@@ -1526,10 +1529,10 @@ LIBMMG3D_EXPORT int  MMG3D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
  * \param typEntity pointer to the type of entities to which solutions
- * are applied.
+ *        are applied (see \ref MMG5_entities for possible values)
  * \param np pointer to the number of solutions.
- * \param typSol pointer to the type of the solutions (scalar, vectorial,
- * ...)
+ * \param typSol pointer to the type of the solutions
+ *        (scalar, vectorial, ..., see \ref MMG5_type for possible values)
  * \return 1.
  *
  * \remark Fortran interface:
@@ -1552,7 +1555,7 @@ LIBMMG3D_EXPORT int  MMG3D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * \param nsols pointer to the number of solutions per entity.
  * \param nentities pointer to the number of solutions.
  * \param typSol array of size MMG5_NSOLS_MAX to store type of each solution
- * (scalar, vector..).
+ *        (scalar, vectorial, ..., see \ref MMG5_type for possible values).
  *
  * \return 1.
  *
@@ -2006,11 +2009,16 @@ LIBMMG3D_EXPORT int  MMG3D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * \brief Get the quality measure of a single tetrahedron in the mesh.
  *
  * \param mesh pointer to the mesh structure.
- * \param met pointer to the metric structure.
- * \param k index of the tetra for which we want to get the quality.
- * \return the computed quality or 0. if fail.
+ * \param met pointer to the metric structure (may be NULL for an isotropic metric).
+ * \param k index of the tetrahedron for which we want to get the quality (from 1 to
+ *        the number of tetrahedra included)
+ * \return the computed quality or 0 in case of failure.
  *
- * Get quality of tetra \a k.
+ * This function returns the quality measure of tetrahedron \a k. Quality values
+ * range from 0 (degenerate) to 1 (best attainable). The function returns 0
+ * if the tetrahedron is flat or has a negative volume, and also if \a k is out
+ * of range. In the latter case it will also print a diagnostic message to
+ * standard output.
  *
  * \remark Fortran interface:
  * >   SUBROUTINE MMG3D_GET_TETRAHEDRONQUALITY(mesh,met,k,retval)\n
@@ -2020,7 +2028,7 @@ LIBMMG3D_EXPORT int  MMG3D_Set_lsBaseReference(MMG5_pMesh mesh, MMG5_pSol sol,MM
  * >   END SUBROUTINE\n
  *
  */
-  LIBMMG3D_EXPORT double MMG3D_Get_tetrahedronQuality(MMG5_pMesh mesh,MMG5_pSol met, MMG5_int k);
+  LIBMMG3D_EXPORT double MMG3D_Get_tetrahedronQuality(MMG5_pMesh mesh, MMG5_pSol met, MMG5_int k);
 
 /**
  * \brief Get the next element of a scalar solution structure defined at vertices.

diff --git a/src/mmg3d/mmg3d2.c b/src/mmg3d/mmg3d2.c
@@ -305,10 +305,10 @@ double MMG3D_vfrac(MMG5_pMesh mesh,MMG5_pSol sol,MMG5_int k,int pm) {
  *
  * Reset mesh->info.isoref vertex and tetra references to 0.
  *
- * \warning to improve: for now, entities linked to the old ls (corners,required
+ * \warning to improve: for now, entities linked to the old ls (corners, required
  * points, normals/tangents, triangles and edges) are deleted in loadMesh. It
- * would be better to analyze wich entities must be keeped and which one must be
- * deleted depending on the split/nosplit infos.
+ * would be better to analyze wich entities must be kept and which ones must be
+ * deleted depending on the split/nosplit info.
  */
 int MMG3D_resetRef_ls(MMG5_pMesh mesh) {
   MMG5_pTetra     pt;
@@ -714,7 +714,7 @@ int MMG3D_snpval_ls(MMG5_pMesh mesh,MMG5_pSol sol) {
     if ( !MG_VOK(p0) ) continue;
     if ( fabs(sol->m[k]) < MMG5_EPS ) {
       if ( mesh->info.ddebug )
-        fprintf(stderr,"  ## Warning: %s: snapping value %" MMG5_PRId "; "
+        fprintf(stderr,"  ## Warning: %s: snapping value at vertex %" MMG5_PRId "; "
                 "previous value: %E.\n",__func__,k,fabs(sol->m[k]));
 
       tmp[k] = ( fabs(sol->m[k]) < MMG5_EPSD ) ?

diff --git a/src/mmgs/libmmgs.h b/src/mmgs/libmmgs.h
@@ -300,7 +300,8 @@ LIBMMGS_EXPORT int  MMGS_Set_inputParamName(MMG5_pMesh mesh, const char* fparami
  *
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
- * \param typEntity types of solution entities (vertices, triangles...).
+ * \param typEntity types of solution entities (vertices, triangles, ...
+ *        see \ref MMG5_entities for possible values).
  * \param np number of solutions.
  * \param typSol type of solution (scalar, vectorial, ..., see \ref MMG5_type for possible values)
  * \return 0 on failure, 1 otherwise.
@@ -1131,6 +1132,7 @@ LIBMMGS_EXPORT int  MMGS_Get_meshSize(MMG5_pMesh mesh, MMG5_int* np, MMG5_int* n
  * \param mesh pointer to the mesh structure.
  * \param sol pointer to the sol structure.
  * \param typEntity pointer to the type of entities to which solutions are applied.
+ *        (see \ref MMG5_entities for possible values)
  * \param np pointer to the number of elements in the solution.
  * \param typSol pointer to the type of the solution (\ref MMG5_Scalar, \ref MMG5_Vector,
  *    \ref MMG5_Tensor, \ref MMG5_Notype)