@c This file is part of the Neper software package.
@c Copyright (C) 2003-2018 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).
@dfn{Mapped (or structured) meshing} generates a
non-conforming mesh into regular hexahedral elements (quadrangular in
2D). Free meshing is carried out so that the elements have
sizes as close as possible to the 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 tessellations, multiscale tessellations and
periodic (or semi-periodic) tessellations are supported.
Free meshing of raster tessellations works for 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 triangular or quadrangular 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 @code{cl} (or @code{rcl})
values 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 3.0.0
    Info   : Built with: gsl nlopt muparser
    Info   : <http://neper.sourceforge.net>
    Info   : Copyright (C) 2003-2018, and GNU GPL'd, by Romain Quey.
    Info   : Comments and bug reports: <neper-users@lists.sourceforge.net>.
    Info   : Loading initialization file `/home/rquey/.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.72|0.87/83%|11%| 6%)
    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:      287
    Info   :     > Elt  number:     1006
    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.537 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}

@req{-tmp, path_name,
Specify the path of the temporary directory (used by Gmsh).,
any, "."}

@subsection Input Data

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

@inp{, file_name,
Specify the 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.
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.
,
any, none}

It is also possible to load a result mesh from a file (use @w{option @option{-o}} not to overwrite the file).  If the file contains meshes of dimensions lower than the tessellation's dimension, these meshes are used and only higher-dimension meshes are generated.

@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.  These points are used
only for statistics, in 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,
Specify the 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,
Specify the 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}).
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
always 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.
With @samp{@option{-format geof}}@comma{} use @samp{@code{1,inputdim}}
to get the 1D mesh written as lisets (for visualization).
,
0 to 3@comma{} all@comma{} none@comma{} inputdim, inputdim}

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

@optsec{-pl, real,
Specify the 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 the 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}

@optnrc{-clmin, real,
Specify the minimum characteristic length of the elements.,
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 more 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. A value of 0 provides the fastest
meshing while a value of 1 provides the 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}

@optsec{-interface, char_string,
Specify the type of interface meshing. Provide @samp{continuous} for a
continuous mesh at interfaces@comma{} with shared nodes between
neighbour element sets (which are associated to the tessellation cells).  Provide
@samp{discontinuous} for a discontinuous mesh at interfaces@comma{} with
distinct nodes for the neighbour element sets.  Provide @samp{cohesive} for
cohesive elements at interfaces@comma{} joining the neigbour element
sets.
See option @option{-faset} for the output format.
,
see above, continuous}

@optsec{-mesh2dpinchfix, logical,
Apply 2D-mesh pinches correction after 2D meshing.  Disable only if you really know what you are doing.,
0 or 1, 1}

@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
modifies 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]} is 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,
Specify the 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,
Specify the factor used for the interface mesh smoothing (@math{A} in option
@option{-tesrsmooth}).,
0 to 1, 0.5}

@optsec{-tesrsmoothitermax, integer,
Specify the 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 options
@option{-singnodedup} or @option{-interface}.
,
0, any>0}

@subsection Transformation Options

@opt{-scale, real:real:real,
Scale the mesh by given factors in the x@comma{} y and z directions
once it is generated.
In 2D@comma{} the @var{z} value can be omitted.
,
any, none}

@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, while the second 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 made of
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 made of 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,
Specify 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@comma{} but getting a full balancing is highly CPU-demanding.,
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{}...,
Transport data from a parent mesh to a child mesh.
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{node} or @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}. Nodal data are transported
by interpolation using the shape functions (2D only).  Element data are transported by
considering the parent element which the centroid of the new element belongs
to.,
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}). For @samp{msh}@comma{} append
@samp{@SEPDEP{}@var{format}} to specify the format@comma{}
which can be @samp{ascii} or @samp{binary} (default @samp{ascii}).
The tessellation file format @samp{tess} is also available.
Combine arguments with @samp{@SEPNODEP}.,
see above, 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.
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 and edges in 2D}

@opt{-faset, char_string,
Specify the element surface meshes (edge meshes in 2D) to provide. Use
@samp{faces} for all domain faces.  To get the meshes of individual
faces@comma{} provide their labels (see option @option{-nset}).  For
internal mesh faces (edges in 2D) as created by @samp{@option{-interface
discontinuous}}@comma{} provide @samp{internal}.
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,
Specify the 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,
Specify the maximum processing time allowed to the meshing library for meshing a tessellation face
(in seconds).
,
any, 1000}

@optsec{-mesh2drmaxtime, real,
Specify a factor used to determine the maximum processing time allowed
to the meshing library for meshing a tessellation face.  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,
Specify the maximum number of 2D meshing attempts for a particular face
(in case of failure).
,
any, 3}

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

@optsec{-mesh3drmaxtime, real,
Specify a factor used to determine the maximum processing time allowed
to the meshing library for meshing a tessellation polyhedron.  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,
Specify the maximum number of 3D meshing attempts for a particular
polyhedron (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 Periodicity

@itemize
@item File @file{.per}. For each slave node, the file provides (one slave
      node per line): the node id, the master node id and the shift
      vector of the slave.
@end itemize

@subsection Interfaces

@itemize
@item File @file{.intl}. For each 2D interface, the file provide (one 2D
    interface per line): the labels of the two element sets of the interface.
@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 divide 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
