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

@node Introduction
@chapter Introduction

@section The Neper Project

@subsection Description

Neper is a software package for polycrystal generation and meshing.  The
polycrystals can be 1D, 2D or 3D. Neper is built around three modules,

@itemize @bullet
@item @MT{} is the module for generating polycrystals, which is carried
out by tessellation
of a bounded domain of space. Several types of tessellations are available: Voronoi
tessellations, hardcore Voronoi tessellations, centroidal Voronoi
tessellations, Laguerre tessellations and regular tessellations.
The tessellated domain can be cubic, cylindrical or of any other convex
shape.
The tessellations can then be deformed for generating elongated cells.
Crystal orientations are provided for the grains.
@MT{} also enables to generate 2-scale polycrystals, which are
obtained by generating tessellations into the cells of a primary
tessellation.  Finally, @mT{} includes a ``regularization'' capability to remove the
small features of the tessellations, which then enables better-quality
meshing.
The output is a tessellation file at scalar or raster format.

@item @MM{} is the module for meshing polycrystals described as
tessellation files. Two capabilities are
available: meshing into tetrahedral elements that conform to the
tessellation morphology or meshing into regular hexahedral elements.
Tetrahedron meshing includes features that are necessary to get
good-quality meshes: optimized meshing rules and multimeshing (the
concurrent use of several meshing algorithms).  Remeshing is also
available to generate a new, good-quality mesh from a deformed mesh.
Tetrahedron meshing of raster tessellations works for 1D and 2D
tessellations only.

@item @MV{} is the visualization module. It enables to generate
publication-quality images of the tessellations and meshes. It is
also possible to visualize data on them using colours or displacements of
the nodes (for meshes) and to plot data on slices of the mesh.
The output is a PNG image file.

@end itemize

Neper aims to be an easy-to-use, efficient and robust tool.  All the
input data are prescribed non-interactively, using command lines and/or
ASCII files. This makes it possible to automate all treatments.

@subsection Resources

Several, complementary resources describing the Neper capabilities
are available,

@itemize
@item The Neper reference manual, which is the present document.  It describes all the Neper
capabilities. It is made of one chapter for each module, which describes
the available commands and result files and provides some examples.
The manual comes both as a PDF file and an info file.  Provided
that the info file is properly installed at your site, it can be
accessed by the command: @command{info neper}.

@item The Neper homepage, @url{http://neper.sourceforge.net}.  It is
where the Neper distribution can be downloaded from. The page also
provides an introduction to Neper.

@item The Neper reference paper,
``@cite{R.@ Quey, P.R.@ Dawson and F.@ Barbe, Large-scale 3D random
polycrystals for the finite element method: Generation, meshing and
remeshing, Comput.@ Methods Appl.@ Mech.@ Engrg., vol.@ 200, pp.@
1729-1745, 2011.}''. It
provides details on the algorithms.  It can be downloaded
from the Neper homepage or by following this link:
@url{http://neper.sourceforge.net/docs/neper-reference-paper.pdf}.

@end itemize

@section Installing Neper

Neper is written in (mostly ANSI) C and a very little C++. It can run on
any Unix-like system.  Neper can be compiled using CMake, a standard
open-source build system.  The main steps are as follows,

@itemize
@item Create a @file{build} directory, for example as a subdirectory of
Neper's @file{src} directory,

@com{mkdir build}

@item Run CMake from within the @file{build} directory, pointing to Neper's
@file{src} directory,

@com{cd build}
@com{cmake ..}

@item To build and install Neper, then simply type,

@com{make}
@com{make install (as root)}

@end itemize

This will use the default configuration options and should work out of
the box on condition that the required libraries are available and
installed in standard system locations.  A finer configuration can be
achieved before building Neper, as described in the following.

Neper has mandatory as well as optional dependencies.  Some dependencies
are managed at compilation time,

@itemize

@item the GSL library (mandatory)

It is likely to be available on your system or from your system package
manager (binary and development packages).  Alternatively, the
source code version can be obtained from the GSL homepage,
@uref{http://www.gnu.org/software/gsl}.

@item the libmatheval library (optional, @emph{included} by default)

It is likely to be available on your system or from your system package
manager (binary and development packages).
Alternatively, the source code version can be obtained from the
libmatheval homepage, @uref{http://www.gnu.org/software/libmatheval}.

@item the libScotch library (optional, @emph{not included} by default)

@MM{} includes mesh partitioning, which requires the
libScotch library (version @code{5.1.12} or later).  It can be
downloaded from the Scotch homepage,
@url{www.labri.fr/perso/pelegrin/scotch}.

@item the pthread library (needed only with Scotch version >= 6.0.0,
@emph{not included} by default)

libScotch version 6.0.0 or later requires the pthread library.
It is likely to be available on your system or from your system package
manager.
@end itemize

Optional dependencies can be toggled on / off using CMake's GUI
(@command{cmake-gui}) or @command{ccmake}, by setting variables
@code{HAVE_@var{LIBRARYNAME}} to ON or OFF, respectively.  The commands
would be,

@com{cmake-gui ..}

or,

@com{ccmake ..}

The additional variables @samp{HAVE_DEBUGGING}, @samp{HAVE_PROFILING}
and @samp{HAVE_OPTIMIZATION} are for development and should not be
changed from their default values for production use (@samp{OFF},
@samp{OFF} and @samp{ON}, respectively); warnings are printed
at Neper execution otherwise.

The following dependencies are only needed at run time,
@c
@itemize

@item the Gmsh program (mandatory for module -M)

This version on Neper is intended to work with Gmsh (version
@code{2.4.2} or later), which can be
downloaded from @url{http://www.geuz.org/gmsh}.  A working Gmsh
installation must be available on your system.  (Compiling Gmsh from the
source code provides faster meshing.)

@item the POV-Ray program (mandatory for module -V)

Module -V uses POV-Ray to produce publication-quality images of the
tessellations and meshes.  POV-Ray can be downloaded from
@url{http://www.povray.org}.  POV-Ray must be available in the terminal
through the command: @command{povray}.

@end itemize

Finally, the Neper installation can be tested out by running a series of
tests, as follows,
@com{neper --test}

For a proper Neper installation, all tests
should pass.  (The command actually is an alias for @samp{@command{neper
-D all -runmode fast}}, see @ref{Developer's Guide} for details.)

@c Moreover, the documentation can be installed as an @file{info} file.  On
@c most systems, this can be achieved simply by copying the file
@c @file{neper.info} into an info directory (usually @file{/usr/info},
@c @file{/usr/local/info} or @file{/usr/doc/info}).

@section Getting Started

Using Neper consists in running the command @file{neper} in a terminal,
with a list of arguments,

@com{neper @var{list_of_arguments}}

The arguments define the problem for Neper to solve.  Neper then returns
output in ASCII files, together with some messages in the terminal.
Neper includes some general-purpose self-explanatory commands,

@com{neper --help}
@com{neper --version}
@com{neper --license}

@subsection Calling a Module

A typical Neper invocation consists in calling a module and providing it
with a number of arguments,

@com{neper @var{module_name} @var{module_arguments}}

The module names are @option{-T}, @option{-M} and @option{-V}.
The module arguments can include both required input
data and options.  Input data (when not a file name) and options
start @w{by @samp{-}}.  The options can be
given in arbitrary order and are to be
specified as follows: @samp{@var{option_name option_argument}}.
Any option takes one and only one argument.  The options
can be written both in British English and in American English, even if
only the British English versions are provided in this manual.  String
completion is available for all options, so they may be abbreviated as
long as the abbreviation is not ambiguous. For example, in module
@code{-T}, option @option{-regularization} can be abbreviated to
@option{-reg}.
Logical options can be selected or disabled by providing as argument the
@w{value @samp{1}} @w{or @samp{0}}, respectively.
For option arguments that are integer or real numbers, mathematical or
logical expressions can be used if libmatheval is available
(for the list and format of mathematical and logical expressions,
see @ref{Mathematical and Logical Expressions}).
For example, in @mT{}, option
@option{@w{-rcl 0.5}} can also be written as @option{@w{-rcl 1/2}} or
@option{-rcl "cos(pi/3)"}.  Options are tagged by importance level in
the reference manual: @w{`[Option]'} or @w{`[Secondary option]'}.
Prerequisites are tagged @w{`[Prerequisite]'}, input data are tagged
@w{`[Input Data]'} and post-processing options are tagged
@w{`[Post-processing]'}.
@MV{} has some exceptions with respect to the previous rules: the
argument cannot be given in arbitrary order, string completion is not
available and option @option{-loop} takes several arguments.

@subsection Initialization File

When Neper is started, it reads commands from an initialization file,
@file{$HOME/.neperrc}, if that file exists.  Another initialization file
can be specified using option @option{--rcfile}, which must be done
@emph{before} calling a module,

@com{neper --rcfile @var{my_file} @var{module_name module_arguments}}

To disable the reading of an initialization file, use option
@option{--rcfile} with
@samp{@code{none}} as value of @code{@var{my_file}}.

When a module of Neper is called,
Neper looks for the occurrence of @samp{neper @var{module_name}} in the
initialization file, then reads all arguments until the subsequent occurrence
of @samp{neper} (which should denote the beginning of another module
option field) or the end of the file.  Moreover, any comments can be
written using @samp{neper comments}.  The arguments may be any
legal arguments, but are typically limited to frequently-used options.

@c @medskip
An example of initialization file is provided below,

@c @cartouche
@example
@c @group
neper comments ------------------------------------------------------
This is my initialization file (~/.neperrc).
neper -T -reg 1
neper -M -gmsh my_gmsh_path
neper comments ------------------------------------------------------
@c @end group
@end example
@c @end cartouche

@c @medskip
If the initialization file is not found, or if @samp{neper
@var{module_name}} is not found in the file, Neper will only consider
the command line arguments.  Also note that if an argument is
initialized several times (for example, both in the initialization file
and at the command line), the last specified value is retained.

@need 4000
@subsection Conventions

@subsubsection Manual

The Neper documentation is maintained as a Texinfo manual.  Here are
the writing conventions used in the document,

@enumerate
@item A command that can be typed in a terminal is printed like
@command{this}, or, in the case of a major command, like
@com{this}
@item a program (or command) option is printed like @option{this};
@item The name of a variable is printed like @code{this};
@item A meta-syntactic variable (i.e.@: something that stands for another piece of text) is printed like @var{this};
@item Literal examples are printed like @samp{this};
@item File names are printed like @file{this}.
@end enumerate

@c Some abbreviations are used consistently for options:
@c
@c @multitable @columnfractions 0.5 0.5
@c @item
@c @multitable @columnfractions 0.2 0.6
@c @item tess  @tab tessellation
@c @item geo   @tab geometry
@c @item stat  @tab statistics
@c @item poly  @tab polyhedron@comma{} polyhedra
@c @item ver   @tab vertex@comma{} vertices
@c @item dim   @tab dimension
@c @item cl    @tab characteristic length
@c @item min   @tab minimum
@c @item max   @tab maximum
@c @end multitable
@c
@c @tab
@c @multitable @columnfractions 0.3 0.6
@c @item algo  @tab algorithm
@c @item part  @tab partition
@c @item arch  @tab architecture
@c @item surf  @tab surface
@c @item stat  @tab statistics
@c @item iter  @tab iteration
@c @item nset  @tab node set
@c @item elset @tab @w{element set}
@c @end multitable
@c
@c @end multitable

@subsubsection Argument Separators

Some options may take several values, which can be combined using
separators, as specified in the option descriptions
(see @ref{Tessellation Module (-T)}, @ref{Meshing Module (-M)} and
@ref{Visualization Module (-V)}).  There actually are two separators,

@enumerate
@item The @samp{@SEPNODEP} separator is used to provide several
arguments with no dependency between each other, that is, whose
corresponding actions can be processed independently.  For instance, in
module -T, the @option{-format} option can take argument
@w{@samp{tess@SEPNODEP ply}} to get the tessellation both in Neper's
tessellation @w{format @file{.tess}} and in @w{Ply format @file{.ply}}.

@item The @samp{@SEPDEP} separator is used to combine several arguments
that show dependency between each other, that is, whose corresponding
actions cannot be processed independently. For instance, in module -M,
the meshing option @option{-mesh3dalgo} takes
as argument a combination of a meshing algorithm, @samp{@var{mesh}}, and
a meshing optimization algorithm, @samp{@var{opti}}, under the form
@samp{@var{mesh}@SEPDEP{}@var{opti}}.  Optimization is applied after
meshing, hence the dependency.

@end enumerate

In @mT{}, the @samp{::} super-separator is used for 2-scale tessellation
generation.
