@c This file is part of the Neper software package.
@c Copyright (C) 2003-2015 Romain Quey
@c See the COPYING file in the top-level directory.

@node Meshing Module (-M)
@chapter Meshing Module (-M)

@MM{} is the module for meshing scalar and raster tessellations.  Two
meshing strategies are available. @dfn{Free (or unstructured) meshing}
creates a conforming mesh into tetrahedral elements (triangular in 2D,
line in 1D).  @dfn{Mapped meshing} generates a
non-conforming mesh into regular hexahedral elements (rectangular in 2D,
line in 1D).  Free meshing is carried out so that the elements have
sizes as close as possible to a desired target value, and show high
quality, that is, equilateral shapes.  The input file is a tessellation
file (@file{.tess}) or a raster tessellation file (@file{.tesr}), as
provided by @mT{}.  Standard, 1-scale tessellations and 2-scale
tessellations are supported.
Free meshing of raster tessellations
works for 1D and 2D tessellations only.
The output mesh can be written in various formats.

The target element size of the mesh can be specified through the element
@dfn{characteristic @w{length (@samp{cl})}}.  It stands for the length of a
1D element, the length of
the edge of a triangle or quadrilateral element (2D) and the length of
an edge of a tetrahedral or hexahedral element (3D). For convenience, a
@dfn{relative characteristic length (@code{rcl})} is also defined, whose
value is relative to the average cell size and provides a medium number
of elements.  It is also possible to specify a @code{cl} (or @code{rcl})
value on a per-cell basis, or to specify different values along the
three coordinate axes.

For free meshing,  mesh quality is ensured to the greatest extent
possible using several advanced capabilities,

@itemize
@item Optimized meshing rules.  The mesh properties are controlled by
size parameters (options @option{-cl}, @option{-rcl}, etc.) and a size
gradient parameter used for 1D meshing (option @option{-pl}).

@item Multimeshing.  Each tessellation face and volume is meshed
separately of the others, with several meshing algorithms, until a
target mesh quality is reached.  This is controlled by options
starting by @option{-meshqual}, and options @option{-mesh2dalgo} and
@option{-mesh3dalgo}.

@end itemize

Note that, in general, tessellation @emph{regularization} is also
necessary to ensure good-quality meshing, see @ref{Tessellation Module (-T)}.

Remeshing can also be applied to generate a new, good-quality
mesh from a mesh containing poor-quality elements.  The variables
defined on the old mesh can be transported on the new mesh (options
starting by @option{-transport}).

For mapped meshing, mesh cleaning options enable to remove
isolated elements or duplicate nodes, or to duplicate nodes subjected to
singularity behaviour (options @option{-clean}, @option{-dupnodemerge}
and @option{-singnodedup}).

Mesh partitioning enables to divide the mesh nodes and
elements into several sets while minimizing the interfaces between
them@footnote{Each partition being assigned to a processor in the finite
element calculation, the minimization of the interfaces between the
partitions is done in terms of the number of necessary communications
between processors.}, for parallel finite element calculations.
Partitioning can return any number of partitions, or more efficiently,
can be carried out according to a given parallel computer architecture
(option @option{-part}).

In the output mesh, the individual entities of the tessellations (the
vertices, edges, faces and polyhedra) can be described by element
sets (option @option{-dim}).  Node sets of the vertices, edges
and faces of the boundary of the tessellation are also provided for
prescribing the boundary conditions (option @option{-nset}).  The
surface element sets are also provided (option @option{-faset}).  The
mesh order can be 1 or 2 (option @option{-order}).
Statistical data can be obtained on the meshes (options starting by
@option{-stat}).

@page
Here is what a typical run of @mM{} looks like,
@sp 2

@c typical_start
@verbatim
    $ neper -M n10-id1.tess

    ========================    N   e   p   e   r    =======================
    Info   : A software package for polycrystal generation and meshing.
    Info   : Version 2.0.0
    Info   : Built with: gsl libmatheval
    Info   : Loading initialization file `/foo/bar/.neperrc'...
    Info   : ---------------------------------------------------------------
    Info   : MODULE  -M loaded with arguments:
    Info   : [ini file] -gmsh /foo/bar/bin/gmsh
    Info   : [com line] n10-id1.tess
    Info   : ---------------------------------------------------------------
    Info   : Reading input data...
    Info   :   - Reading arguments...
    Info   : Loading input data...
    Info   :   - Loading tessellation...
    Info   :     [i] Parsing file `n10-id1.tess'...
    Info   :     [i] Parsed file `n10-id1.tess'.
    Info   : Meshing...
    Info   :   - Preparing... (cl = 0.2321) 100%
    Info   :   - 0D meshing... 100%
    Info   :   - 1D meshing... 100%
    Info   :   - 2D meshing... 100% (0.69|0.86/96%| 4%| 0%)
    Info   :     > Checking 2D mesh for pinching out...
    Info   :   - 3D meshing... 100% (0.89|0.91/100%| 0%| 0%)
    Info   :   - Searching nsets...
    Info   : Writing mesh results...
    Info   :   - Preparing mesh...
    Info   :   - Mesh properties:
    Info   :     > Node number:      289
    Info   :     > Elt  number:      996
    Info   :     > Mesh volume:    1.000
    Info   :   - Writing mesh...
    Info   :     [o] Writing file `n10-id1.msh'...
    Info   :     [o] Wrote file `n10-id1.msh'.
    Info   : Elapsed time: 8.414 secs.
    ========================================================================
@end verbatim
@c typical_end

@page
@section Arguments

@subsection Prerequisites

@req{-gmsh, path_name,
Specify the path of the Gmsh binary (for meshing into
triangle and tetrahedral elements).,
any, gmsh}

@subsection Input Data

In normal use, the input data is a tessellation file, a raster
tessellation file or a mesh file,

@inp{, file_name,
Name of the input file. It can be
a tessellation file (@file{.tess})@comma{}
a raster tessellation file (@file{.tesr}) or a mesh file for
remeshing (@file{.msh}).
To load several of them (namely@comma{} both a tessellation file and a mesh
file for remeshing)@comma{} combine them with @samp{@SEPNODEP}.
To overwrite the coordinates of the nodes of a mesh@comma{} use the
syntax @samp{@var{file_name}@SEPDEP{}@var{nodecoo_file_name}}@comma{} where
@file{@var{file_name}} is the name of the mesh file and
@file{@var{nodecoo_file_name}} is the name of the file containing the
coordinates of the nodes (see @ref{Position File}).
To load only a subregion of a raster tessellation@comma{} use the
syntax
@samp{@var{file_name}:crop(@var{xmin}|@var{xmax}|@var{ymin}|@var{ymax}|@var{zmin}|@var{zmax})}@comma{}
where
@samp{@var{xmin}}@comma{} @samp{@var{xmax}}@comma{}
@samp{@var{ymin}}@comma{} @samp{@var{ymax}}@comma{}
@samp{@var{zmin}} and @samp{@var{zmax}} are the minimum and maximum positions along
@var{x}@comma{} @var{y} and @var{z}@comma{} respectively.
For 2D raster tessellations@comma{} the @var{z} boundaries can be omitted.
For 1D raster tessellations@comma{} the @var{y} and @var{z} boundaries can be omitted.
To scale the number of points of a raster tessellation@comma{} use the syntax
@samp{@var{file_name}:scale(@var{factor})}@comma{}
where @code{@var{factor}} is the
scaling factor@comma{} or
@samp{@var{file_name}:scale(@var{factor_x}|@var{factor_y}|@var{factor_z})}@comma{}
where @code{@var{factor_x}}@comma{} @code{@var{factor_y}} and
@code{@var{factor_z}} are the
scaling factor along @var{x}@comma{} @var{y} and @var{z}@comma{}
respectively.
For 2D raster tessellations@comma{} the @var{z} factor can be omitted.
For 1D raster tessellations@comma{} the @var{y} and @var{z} factors can be omitted.
,
any, none}

It is also possible to load a result mesh from a file.
(Using @w{option @option{-o}} along with this capability
avoids overwriting the input data.)

@kindex -loadmesh
@inp{-loadmesh, file_name,
Load a mesh from a file (@file{.msh} format).
,
any, none}

Finally, it is possible to load a set of points (useful for statistics,
see option @option{-statpoint}),

@kindex -loadpoint
@inp{-loadpoint, file_name,
Load points from a file.
See @ref{Position File} for the file format.
Provide as argument the file name.
,
any, none}

@subsection Meshing Options

@opt{-elttype, char_string,
Type of elements@comma{} among tetrahedral (@samp{tet}) and hexahedral
(@samp{hex}). (The 2D counterparts@comma{} @samp{tri} and
@samp{quad}@comma{} can also be used and are equivalent.)
,
tet@comma{} hex, tet}

@opttwo{-cl, -rcl, -cl or -rcl, real,
Absolute or relative characteristic length of the elements.
@code{rcl} is defined relative to the average cell size.
The default @code{-rcl 1} leads to a mesh with about 100 elements per
cell in average (@w{64 in 2D}@comma{} @w{5 in 1D}).
For free meshing@comma{} it is also possible to get non-uniform
characteristic length distributions@comma{} as detailed in the following.
To define a characteristic length on a per-cell basis@comma{} the first way is to use the syntax
@code{@var{default_cl}@SEPNODEP{}@var{cell_expr1}@SEPDEP{}@var{cell_cl1}@SEPNODEP{}@var{cell_expr2}@SEPDEP{}@var{cell_cl2}...}@comma{}
where @code{@var{default_cl}} is the default characteristic length@comma{}
@code{@var{cell_expri}} is an expression defining the set of
@w{cells @var{i}} and @code{@var{cell_cli}} is the corresponding characteristic length.
@samp{@code{@var{cell_expri}}} can be any
expression based on variables provided in
@ref{Tessellation Keys} for tessellations@comma{} @ref{Raster
Tessellation Keys} for
raster tessellations and @ref{Mesh Keys} for meshes.
The expressions are processed one after the other. When processing
expression @code{@var{cell_expri}}@comma{} the matching cells
are assigned @code{@var{cell_cli}} as characteristic length.
A typical use is @samp{@code{-rcl
@var{val1}@SEPNODEP{}body==0@SEPDEP{}@var{val2}}} to get interior cells
meshed with @code{@var{rcl}=@var{val1}} and boundary cells
meshed with @code{@var{rcl}=@var{val2}}.
The second way is to load values from an external file using
the syntax @samp{@@@var{file_name}}@comma{} where @code{@var{file_name}}
is the name of the file containing the characteristic length values.
,
any, -rcl 1}

@opt{-dim, char_string,
Specify the meshing dimension. By default@comma{} it is equal to the
input data dimension (@w{@code{@samp{inputdim}}}). To get meshes of
several dimensions in output@comma{} provide the values combined @w{with
@samp{@SEPNODEP{}}}. Provide @code{@samp{all}} for all and
@code{@samp{none}} for none.  Note that the meshes of all dimensions are
systematically written into a @file{.msh} mesh file
unless
@samp{@SEPDEP{}msh} is appended to the option argument.
If a mesh dimension of 3 is required@comma{} but the input data is 2D@comma{}
the 3D mesh is obtained by extrusion of the 2D mesh.
,
0 to 3@comma{} all@comma{} none@comma{} inputdim, inputdim}

@opt{-order, integer,
Specify the mesh order.
1 means 2-node line elements@comma{} 3-node triangle elements@comma{}
4-node quadrangle elements@comma{} 4-node tetrahedral elements and
8-node hexahedral elements.
2 means 3-node line elements@comma{} 6-node triangle elements@comma{}
8-node quadrangle elements@comma{} 10-node tetrahedral elements and
20-node hexahedral elements.
,
1 or 2,1}

@optsec{-pl, real,
Progression factor for the element characteristic lengths. This value is
the maximum ratio between the lengths of two adjacent 1D elements.,
any >= 1, 2}

@optsec{-clratio, char_string,
Specify ratios between the @var{cl}-values along the different
coordinate axes. Provide the values combined with
@samp{@SEPDEP{}}. For example@comma{} @samp{2:1:1} leads to elements
twice as long in the x direction as in the y and z directions.
,
none, any}

@optsec{-clmin, real,
Minimum characteristic length of the elements.  Using this option is not recommended.,
any, none}
@c @optdevel{-meshface, expression,
@c Specify the faces to mesh. The argument can be: @samp{all} for
@c all@comma{} @samp{@@@var{file_name}} to load face numbers from a
@c file@comma{} or any expression based on the following arguments:
@c @var{cenx}@comma{} @var{ceny}@comma{} @var{cenz}@comma{}
@c @var{volume}@comma{}
@c @var{true}@comma{} @var{body}@comma{} and
@c @var{id}.,
@c any, all}
@c
@c @optdevel{-meshpoly, expression,
@c Specify the polyhedra to mesh. The argument can be: @samp{all} for
@c all@comma{} @samp{@@@var{file_name}} to load polyhedron numbers from a
@c file@comma{} or any expression based on the following arguments:
@c @var{cenx}@comma{} @var{ceny}@comma{} @var{cenz}@comma{}
@c @var{volume}@comma{}
@c @var{true}@comma{} @var{body}@comma{} and
@c @var{id}.,
@c any, all}

@sp 1
The following options define the multimeshing algorithm (for 2D and 3D
free meshings). @dfn{Multimeshing} consists in using several meshing
algorithms concurrently, for each face or polyhedron, until a minimum,
target mesh quality is reached. The mesh quality factor, @math{O},
accounts for both the element sizes and aspect ratios. It is given by
@tex
$
O = {O_{dis}}^\alpha \times {O_{size}}^{1-\alpha}
$,
@end tex
@ifinfo
@example
O = O_dis^alpha x O_size^(1-alpha),
@end example
@end ifinfo
where @math{O_{dis}} and @math{O_{size}} range from 0 (poor quality) to
1 (high quality) and @math{\alpha} is a factor equal to 0.8.  Therefore,
@math{O} also ranges from 0 (poor quality) to 1 (high quality).
See the Neper reference paper for further information.
The minimum quality value can be modified using option @option{-meshqualmin}.
The values of @math{O} and @math{O_{dis}} can be modified using options
@option{-meshqualexpr} and @option{-meshqualdisexpr}.
The value of the target mesh quality significantly influences meshing
speed and output mesh quality. While a value of 0 provides fastest
meshing, a value of 1 provides best-quality meshing. The
default value provides an effective balance.
@c
The meshing algorithms are taken from the Gmsh@footnote{@cite{Ch.@
Geuzaine and J.-F. Remacle, Gmsh: a three-dimensional finite element
mesh generator with built-in pre- and post-processing facilities,
International Journal for Numerical Methods in Engineering, 79,
1309--1331, 2009.}} and Netgen@footnote{@cite{J. Schoberl, Netgen, an
advancing front 2d/3d-mesh generator based on abstract rules.  Comput.
Visual.  Sci., 52, 1--41, 1997.}} libraries (options
@option{-mesh2dalgo} and @option{-mesh3dalgo}).

@opt{-meshqualmin, real,
Specify the minimum@comma{} target value of mesh quality@comma{}
@math{@var{O}}@comma{} as defined by option @option{-meshqualexpr}.,
0 to 1, 0.9}

@opt{-meshqualexpr, char_string,
Specify the expression of mesh quality@comma{} @math{@var{O}}@comma{}
as a function of @var{Odis} and @var{Osize}.,
any, Odis^0.8*Osize^0.2}

@optsec{-meshqualdisexpr, char_string,
Specify the expression of the mesh element distortion parameter@comma{}
@math{@var{Odis}}@comma{} as a function of the element distortion
parameter @var{dis} (see the Neper reference paper).,
any, dis^(exp((dis^0.1)/(dis^0.1-1)))}

@optsec{-mesh2dalgo, char_string,
Specify the 2D meshing algorithms (combine with @samp{@SEPNODEP}).
The available
values are @code{mead} (MeshAdapt)@comma{} @code{dela} (Delaunay) and
@code{fron} (Frontal).,
mead@comma{} dela@comma{} fron,
mead@SEPNODEP{}dela@SEPNODEP{}fron}

@optsec{-mesh3dalgo, char_string,
Specify the 3D meshing algorithms (combine with @samp{@SEPNODEP}).
Each algorithm has format
@samp{@var{mesh}@SEPDEP{}@var{opti}}@comma{} where
@code{@var{mesh}} and @code{@var{opti}} stand for the meshing and mesh
optimization algorithms. The available values of @code{@var{mesh}}
are currently limited to @code{netg}
(Netgen).  The available values of @code{@var{opti}} are @samp{gmsh}
(Gmsh)@comma{} @samp{netg} (Netgen) and @samp{gmne} (@w{Gmsh + Netgen}).
Use @samp{none} for none.
,
netg@SEPDEP{}none@comma{} netg@SEPDEP{}gmsh@comma{} netg@SEPDEP{}netg@comma{}
netg@SEPDEP{}gmne,
netg@SEPDEP{}gmsh@SEPNODEP{}netg@SEPDEP{}netg@SEPNODEP{}netg@SEPDEP{}gmne}

@c @optdevel{-mesh3dreport, logical,
@c Report statistical data on the 3D meshing.,
@c 0 or 1, 0}

@subsection Raster Tessellation Meshing Options

Raster tessellation meshing implies interface reconstruction, interface
mesh smoothing then remeshing. The following options enable to control
interface smoothing.

@iftex
@optsec{-tesrsmooth, char_string,
Method for smoothing the interface meshes reconstructed from raster tessellations.
Laplacian smoothing (@samp{laplacian}) is an iterative method that
consists in modifying the coordinates of a node
using the coordinates of the neighbouring nodes.
At iteration @var{i}@comma{} the position of a node@comma{}
@math{X_i}@comma{} is calculated from its previous position@comma{}
@math{X_{i-1}}@comma{} and the position of the barycentre of the
neighbouring nodes (weighted barycentre@comma{} considering the inverse of
the distance between the
node and the neighbour)@comma{} @math{X^n_{i-1}}@comma{} as follows:
@math{X_i=(1-A)@,X_{i-1} + A@,X^n_{i-1}}.
@math{A@in@left[0,@,1@right]} an
adjustable parameter (see option @option{-tesrsmoothfact}). The number
of iterations is set by option @option{-tesrsmoothitermax}.
There is no stop criterion@comma{} so @code{itermax} will always be
reached.,
laplacian or none, laplacian}
@end iftex

@ifinfo
@optsec{-tesrsmooth, char_string,
Method for smoothing the interface meshes reconstructed from raster tessellations.
A common algorithm is laplacian smoothing (@samp{laplacian}) consists
in modifying the coordinates of a node@comma{} @math{X}@comma{}
using the coordinates of the neighbouring nodes:
@math{X=(1-A)@,X_n + A@,X_n} where @math{X_n} is the barycentre of the
neighbouring nodes. @math{A}@comma{} which belongs to
@math{[0,\,1]}@comma{} is an
adjustable parameter (see option @option{-tesrsmoothfact}). Several
iterations are applied (see option @option{-tesrsmoothitermax}).
There is no stop criterion@comma{} so @code{itermax} will always be
reached.,
laplacian or none, laplacian}
@end ifinfo

@optsec{-tesrsmoothfact, real,
Factor used for the interface mesh smoothing (@math{A} in option
@option{-tesrsmooth}).,
0 to 1, 0.5}

@optsec{-tesrsmoothitermax, integer,
Number of iterations used for interface mesh smoothing.,
any >= 0, 5}

@subsection Mesh Cleaning Options

The following options are specific to mapped meshing of raster
tessellations containing voids.

@optsec{-clean, integer,
Clean the mesh so that it consists of a set of connected elements.
Provide as argument the level of cleaning.
A value of @code{1} indicates that two elements should be considered
connected to each other if they share at least a vertex.
A value of @code{2} indicates that two elements should be considered
connected to each other if they share at least a face.
Using this option@comma{} the elements (or bunches of elements) that
are not connected to the main skeleton are removed.
,
0 to 2,0}

@optsec{-singnodedup, logical,
Duplicate nodes which are the subject of singularity.  Such a node
belongs to several elements which share only a node or an
edge@comma{} which provides a singularity behaviour.
In Mechanics@comma{} it corresponds to imposing a common
displacement@comma{} while the point can carry no stress.
In Thermics@comma{} it corresponds to imposing a given temperature at a
particular location shared by two bodies@comma{} but not enabling heat
flux to operate at that location.
When this option is enabled@comma{}
such a node is duplicated@comma{} so that each body has its own node.
Option @option{-dupnodemerge} enables to merge back duplicate nodes.
,
0 or 1,0}

@optsec{-dupnodemerge, real,
Merge duplicate nodes. Provide as argument the distance between nodes
below which two nodes are merged. Note that Neper does not generate
meshes with duplicate nodes@comma{} except using option @option{-singnodedup}.
,
0, any>0}

@subsection Mesh Partitioning Options

Mesh partitioning is achieved using the libScotch
library@footnote{@cite{F.
Pellegrini, Scotch and libScotch 5.1 User's Guide, INRIA Bordeaux
Sud-Ouest, ENSEIRB & LaBRI, UMR CNRS 5800, 2008.}}.  The 
principle of mesh partitioning is to create partitions of same size
while minimizing the interfaces between them. This affects the same load
to all computation units and minimizes communications between them,
therefore minimizes the total computation time.  There are two
available strategies for mesh partitioning. The first one creates
partitions and arranges them independently of each other.  The other one
consists in optimizing the size and arrangment of the partitions based
on a given computer cluster architecture to minimize computation time
further. For those clusters that contain processors each with
several cores, the communication time between cores of a processor
is much lower than the communication time between cores of different
processors. To minimize the global communication time, partitions which
are processed by cores of the same processor can be grouped together.
Partitioning is applied to the higher-dimension mesh.  On top
of defining the partitions, it renumbers the nodes
and elements by increasing partition identifier and writes partitions
as element and node sets (@file{vtk}, @file{inp} and @file{geof}
formats).  This can be managed using option @option{-part}.

@opt{-part, integer or char_string,
Specify the number of partitions or a computer cluster architecture.
Using the first option@comma{} the number of partition can be any.
At the opposite@comma{} for a computer cluster architecture@comma{}
the total number of partitions must be a power of 2. An
architecture can be specified in two ways.  First@comma{} for clusters
that contain processors each with several cores@comma{} the number of
processors and the number of cores per processor can be combined using
the @samp{@SEPDEP{}} separator. A ratio of 10 is
considered between the computation time between cores located on
different processors and the one between cores of the same processor.
Second@comma{} the name of a file describing the cluster architecture at
the Scotch format can be provided.
,
any, none}

@optsec{-partbalancing, real,
Provide the rate of element partition balancing.
The partitioning algorithm applies to the nodes; the element partitions
are determined afterwards and can
be somewhat unbalanced.  This option enables to enforce balancing.
It is highly CPU-sensitive.,
0 to 1,0.5}

@optsec{-partmethod, char_string,
Specify the partitioning method. Provide the partitioning expression
in Scotch's jargon@comma{} or @samp{none} for none.,
any, see_the_source}

@subsection Field Transport Options

@opt{-transport, char_string@SEPDEP{}char_string@SEPDEP{}file_name@SEPNODEP{}...,
Use this option for transporting data from a parent mesh to a child mesh
(both 3D).
The parent mesh is the input mesh and the child mesh is the result mesh
(created by remeshing or loaded
with @option{-loadmesh}).
A transport entry must have format
@samp{@var{entity_type}@SEPDEP{}@var{data_type}@SEPDEP{}@var{file_name}}@comma{}
where
@samp{@var{entity_type}} must be @samp{elt}@comma{}
@samp{@var{data_type}} is the type of data@comma{} under format
@samp{integer@var{X}} or @samp{real@var{X}}@comma{} where @code{@var{X}} is the
dimension@comma{} and @code{@var{file_name}} is the name of the file
containing the parent data.  For several data transports@comma{} combine
the transport entries with @samp{@SEPNODEP}.,
any,none}

@subsection Output Options

@opt{-o, file_name,
Specify the output file name.,
any, none}

@opt{-format, char_string,
Specify the format of the output file(s). Mesh
formats are: the Gmsh @samp{msh}@comma{} the @w{VTK @samp{vtk}}@comma{}
the @w{Abaqus @samp{inp}}@comma{} the Zset/Z@'ebulon @samp{geof} and the
FEpX @samp{fepx} (for the FEpX legacy format@comma{} provide
@samp{fepx@SEPDEP{}legacy}). The tessellation file format
@samp{tess} is also available.
Combine arguments with @samp{@SEPNODEP}.,
anyone of the above list, msh}

@opt{-nset, char_string,
Specify the node sets to provide@comma{} among:
@code{faces}@comma{} @code{edges}@comma{} @code{vertices} for all
domain faces@comma{} edges and vertices@comma{}
and @code{facebodies} and @code{edgebodies} for all face and edge
bodies. Provide @code{all} for all and @code{none} for none.
To get the node sets corresponding to individual entities@comma{}
provide their labels. For a cuboidal domain@comma{} they are
@code{[x-z][0@comma{}1]} for the
domain faces@comma{} @code{[x-z][0@comma{}1][x-z][0@comma{}1]} for the
edges@comma{} and
@code{[x-z][0@comma{}1][x-z][0@comma{}1][x-z][0@comma{}1]} for the
vertices.
For a cylindrical domain@comma{} they are @code{z[0@comma{}1]} for the
@math{z} faces@comma{} and @code{f[1@comma{}2@comma{}...]} for the faces
on the circular part of the domain.
For other domains@comma{}
they are @code{f[1@comma{}2@comma{}...]} for the faces.
For cylindrical and other types of domains@comma{} the edge and
vertex labels are obtained from the face labels as for cuboidal domains.
For a 2D mesh (generated from a 2D tessellation)@comma{} the labels are
@code{[x-y][0,1]} for the edges and @code{[x-y][0,1][x-y][0,1]} for the
vertices.
For a 1D mesh (generated from a 1D tessellation)@comma{} the labels are
@code{x[0,1]} for the vertices.
Append @samp{body} to a label to get only the body nodes of
the set. Combine labels with @samp{@SEPNODEP}.
,
see above, faces in 3D@comma{} edges in 2D and vertices in 1D}

@opt{-faset, char_string,
Specify the domain surface meshes to provide. Use @samp{faces} for all
faces.  To get the fasets corresponding to individual
faces@comma{} provide their labels (see option @option{-nset}).
Combine them @w{with @samp{@SEPNODEP}}.
Provide @code{none} for none.
,
see above, none}

@subsection Post-Processing Options

The following options provide statistics on the nodes (@samp{nodes}),
0D elements (@samp{elt0d}) and element sets (@samp{elset0d}),
1D elements (@samp{elt1d}) and element sets (@samp{elset1d}),
2D elements (@samp{elt2d}) and element sets (@samp{elset2d}) and
3D elements (@samp{elt3d}) and element sets (@samp{elset3d}).
Also note that the @samp{@dfn{elt}} and
@samp{@dfn{elset}} labels can be used in place of @samp{elt@var{n}d} and
@samp{elset@var{n}d}, where @code{@var{n}} is the higher mesh dimension.  This
enables to use the same command whatever the higher mesh dimension is.

@post{-statnode, char_string,
Provide statistics on the nodes.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stnode}

@kindex -statelt
@kindex -statelset

@post{-statelt0d, char_string,
Provide statistics on the 0D elements.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelt0d}

@post{-statelt1d, char_string,
Provide statistics on the 1D elements.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelt1d}

@post{-statelt2d, char_string,
Provide statistics on the 2D elements.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelt2d}

@post{-statelt3d, char_string,
Provide statistics on the 3D elements.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelt3d}

@post{-statelset0d, char_string,
Provide statistics on the 0D element sets.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelset0d}

@post{-statelset1d, char_string,
Provide statistics on the 1D element sets.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelset1d}

@post{-statelset2d, char_string,
Provide statistics on the 2D element sets.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelset2d}

@post{-statelset3d, char_string,
Provide statistics on the 3D element sets.  Provide as argument
the keys as described in @ref{Mesh Keys} (combine with
@samp{@SEPNODEP}).
,
any, none,
.stelset3d}

@post{-statpoint, char_string,
Provide statistics on points.  The points must be loaded with option
@option{-loadpoint}. Provide as argument
the keys as described in @ref{Point Keys} (combine @w{with
@samp{@SEPNODEP}}).
,
any, none,
.stpoint}

@subsection Advanced Options

These advanced options set running conditions for the meshing libraries
(triangle and tetrahedral meshing),

@optsec{-mesh3dclconv, real,
Maximum difference between the characteristic length @code{cl}
and the average element length (for each polyhedron).  Neper tries its
best to get the average element size to match @code{cl}.  Use this
option to change the tolerance on the relative difference between the
two. This is a highly CPU-sensitive capability (increasing this value
can be efficient to speed up meshing).
,
any, 0.02}

@optsec{-mesh2dmaxtime, real,
Maximum processing time allowed to the meshing library for meshing a tessellation face
(in seconds).
,
any, 1000}

@optsec{-mesh2drmaxtime, real,
This option is similar to @option{-mesh2dmaxtime}@comma{} but the actual
maximum time is the product of the maximum processing time of
the previous meshings by the value provided in argument.
,
any, 100}

@optsec{-mesh2diter, integer,
Maximum 2D meshing attempts for a particular face (in case of
failure).
,
any, 3}

@optsec{-mesh3dmaxtime, real,
Maximum processing time allowed to the meshing library for meshing a tessellation
  volume
(in seconds).
,
any, 1000}

@optsec{-mesh3drmaxtime, real,
This option is similar to @option{-mesh3dmaxtime}@comma{} but the actual
maximum time is the product of the maximum processing time of
the previous meshings by the value provided in argument.
,
any, 100}

@optsec{-mesh3diter, integer,
Maximum 3D meshing attempts for a particular volume (in case of
failure).
,
any, 3}

@need 1000
@section Output Files

@subsection Mesh

The mesh can be written in the following formats,

@itemize
@item Gmsh format: file @file{.msh}

@item VTK format: file @file{.vtk}

@item Abaqus format: file @file{.inp}

@item Zset/Z@'ebulon format: file @file{.geof}

@item FEpX format: files @file{.mesh}, @file{.grain} and @file{.bcs}
(@file{.parms}, @file{.mesh}, @file{.surf}, @file{.opt} and @file{.bcs}
 in legacy mode)
@end itemize

@subsection Statistics

Statistics files are provided for nodes, elements, element sets and
points.
They are formatted with one entity per line.  Each line
contains the
data specified to the corresponding @option{-stat} option and described in
@ref{Mesh Keys}.

@itemize
  @item Node statistics file, @file{.stnode}.
  @item (Higher-dimension) element statistics file, @file{.stelt}.
  @item (Higher-dimension) element set statistics file, @file{.stelset}.
  @item 0D element statistics file, @file{.stelt0d}.
  @item 1D element statistics file, @file{.stelt1d}.
  @item 2D element statistics file, @file{.stelt2d}.
  @item 3D element statistics file, @file{.stelt3d}.
  @item 0D element set statistics file, @file{.stelset0d}.
  @item 1D element set statistics file, @file{.stelset1d}.
  @item 2D element set statistics file, @file{.stelset2d}.
  @item 3D element set statistics file, @file{.stelset3d}.
  @item Point statistics file, @file{.stpoint}.
@end itemize

@section Examples

Below are some examples of use of neper -M,

@enumerate
@c Example_beg
@item    Mesh tessellation @file{n100-id1.tess}.
@com{neper -M n100-id1.tess}
@item    Mesh 2D raster tessellation @file{n100-id1.tesr}.
@com{neper -M n100-id1.tesr}
@item    Mesh tessellation @file{n100-id1.tess} with a mesh size of rcl = 0.5 and in 2nd-order elements.
@com{neper -M n100-id1.tess -rcl 0.5 -order 2}
@item    Mesh tessellation @file{n100-id1.tess} with small elements for the
interior cells and bigger elements for the boundary cells.
@com{neper -M n100-id1.tess -rcl "0.2,body==0:0.5"}
@item    Remesh mesh @file{n150_def.msh} (comprising poor-quality
elements) into a clean, new mesh. Transport the scalar data of file
@file{n150_def.data} from the deformed mesh to the new mesh.
@com{neper -M n150.tess,n150_def.msh -transport elt@SEPDEP{}real1@SEPDEP{}n150_def.data}
@comx{-rcl 0.5 -o n150_new}
@item    Mesh tessellation @file{n100-id1.tess} and partition the mesh into 8 partitions.
@com{neper -M n100-id1.tess -part 8}
@item    Mesh tessellation @file{n100-id1.tess} into regular hexahedral
elements (non-conformal mesh).
@com{neper -M n100-id1.tess -elt hex}
@item    Mesh tessellation @file{n100-id1.tess} and get, for each
element, its radius ratio and its volume.
@com{neper -M n100-id1.tess -statelt rr,vol}
@c Example_end
@end enumerate
