Introduction

Description

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

Module -T generates polycrystals as tessellations. The tessellations can be (i) standard tessellations (Voronoi, etc.) or tessellations generated from cell properties (e.g. a size distribution), or (ii) multiscale tessellations, which are characterized by cell subdivision and are able to represent more complex microstructures. All capabilities available for standard tessellations are also available for multiscale tessellations. Tessellations with a very wide variety of cells morphologies can be generated, with the limitations that cells are convex. Once generated, the tessellations can be regularized by removing their smallest features (edges and faces), which then enables good-quality meshing. Periodicity conditions can be prescribed. Crystal orientations are provided for the cells. The output is a tessellation file written at a scalar (vectorial), .tess, or raster format, .tesr. Scalar tessellations can be meshed by module -M while raster tessellations can typically be used by FFT solvers.

Module -M meshes polycrystals described as tessellation files (.tess and 2D .tesr). Two meshing techniques are available: free (or unstructured) meshing, which generates triangular elements (in 2D) or tetrahedral elements (in 3D) that follow the grain shapes, and mapped (or structured) meshing, which generates regular square elements (in 2D) or regular cubic elements (in 3D) that do not necessarily follow the grain shapes. Free meshing into good-quality elements is ensured by optimized meshing rules, and multimeshing—a complementary use of several meshing algorithms. Remeshing is also available and is similar to meshing except that it takes a mesh as input. Cohesive elements can be inserted at interfaces. The output is a mesh file written at the .msh format, which can be readily be used as input by Neper’s companion program, FEPX, or other formats.

Module -S processes simulation results from FEPX. It translates the FEPX raw simulation results into a more friendly simulation directory .sim, and includes various post-processing capabilities to compute new results. The simulation directory can be used as such and loaded by module -V for result visualization.

Module -V generates publication-quality PNG images or VTK files of tessellations, meshes and simulation results. The results can be defined from internal data, data loaded from external files, or a simulation directory as generated by module -S. The output PNG images can be highly parameterized, with custom colors and transparency for the different entities, slices, etc., and is generated by ray tracing (using POV-Ray), while the output VTK file can be used for interactive visualization (e.g., using Paraview).

Neper strives 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, so that all treatments can be automated. Neper is multithreaded and operates on all threads by default.

Resources and Support

Several, complementary resources describing Neper are available:

Resources for FEPX can be accessed from https://fepx.info.

Installing Neper

Neper is written in (mostly ANSI) C and a little C++, and it can run on any Unix-like system. Neper is also known to run on macOS and on Microsoft Windows using the Windows subsystem for Linux (WSL), the Ubuntu app or similar solutions, although we do not test nor support this usage and multithreading must be turned off (which slows down execution significantly).

Note

Ubuntu users may be interested in the tutorial “Installing Neper on Ubuntu 22” from step-by-step installation instructions.

General Procedure

Compilation is performed via CMake (no root privileges needed):

  • Create a build directory, for instance as a subdirectory of Neper’s src directory:

    $ cd src
$ mkdir build

  • Run CMake from within the build directory, pointing to Neper’s src directory:

    $ cd build
$ cmake ..    (on Windows: cmake -DHAVE_OPENMP=OFF ..)

  • Build Neper:

    $ make

    Use option -j for a multithreaded compilation.

This generates the neper binary file. To make it available system-wide, run (as root):

$ make install

This procedure uses the default configuration options and should work out-of-the-box if the required dependencies are available in standard system locations.

Fine Configuration

The locations where files are installed, which dependencies are included, other dependency information and program configuration options can be specified, before installation, using CMake variables. This can be done using a terminal tool:

$ ccmake ..

or an interactive tool:

$ cmake-gui ..

or directly at the command line, using Cmake’s -D option:

$ cmake -D<VARIABLE1>=<VALUE1> -D<VARIABLE2>=<VALUE2> ..

The installation directories are:

  • The binary directory (variable CMAKE_BUILD_DIRECTORY, default /usr/local);

  • The Bash completion script directory (variable CMAKE_BUILD_DIRECTORY_COMPLETION, default /usr/share on Linux and /usr/local/etc on macOS).

The dependencies which are (optionally) necessary at compilation time and must be (optionally) installed on your system before Neper is compiled are the following:

  • The GNU Scientific Library (GSL, mandatory, variable HAVE_GSL). 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 downloaded from the program website.

  • The OpenMP library (optional but highly-recommended, enabled by default, variable HAVE_OPENMP). It is likely to be available on your system or from your system package manager. [1]

  • The pthread library (mandatory). It is likely to be available on your system or from your system package manager.

Other dependencies are only needed at run-time (they are not necessary for compilation):

  • The Gmsh program (version 2.4.2 or higher, excluding version 2.5.1, mandatory for module -M). It is likely to be available from your system package manager. Alternatively, both binary and source-code versions can be downloaded from the program website (compiling from the source code significantly speeds up meshing). Gmsh must be available at the terminal as the command gmsh, or the path to its binary must be specified with option -gmsh (in module -M).

  • The POV-Ray program (version 3.7 or higher, mandatory for PNG output in Visualization Module (-V)). It is likely to be available on your system or from your system package manager (binary package). Alternatively, both binary and source-code versions can be downloaded the program website. POV-Ray must be available at the terminal as the command povray, or the path to its binary must be specified with option -povray (in module -V).

  • The Asymptote program and Tex Live (texlive-full on Ubuntu, for pole figure plots in Visualization Module (-V)). They are likely to be available from your system package manager. Alternatively, both binary and source-code versions can be downloaded from the program websites. Asymptote must be available at the terminal as the command asy, or the path to its binary must be specified with option -asy (in module -V).

    Attention

    Depending on your configuration and your use of Neper, it may be necessary to make the following changes in your /etc/ImageMagick-6/policy.xml file:

    • Comment out the following lines:

      <policy domain="coder" rights="none" pattern="PS" />
<policy domain="coder" rights="none" pattern="PS2" />
<policy domain="coder" rights="none" pattern="PS3" />
<policy domain="coder" rights="none" pattern="EPS" />
<policy domain="coder" rights="none" pattern="PDF" />
<policy domain="coder" rights="none" pattern="XPS" />

    • Increase the following limits (especially memory and disk):

      <policy domain="resource" name="memory" value="256MiB"/>
<policy domain="resource" name="map" value="512MiB"/>
<policy domain="resource" name="width" value="16KP"/>
<policy domain="resource" name="height" value="16KP"/>
<!-- <policy domain="resource" name="list-length" value="128"/> -->
<policy domain="resource" name="area" value="128MP"/>
<policy domain="resource" name="disk" value="1GiB"/>

Finally, other third-party libraries are directly included in the source code (see directory src/contrib) and are therefore not dependencies per se:

  • The NLopt library. If it is already available on your system, the system version will be used instead. To force the use of the built-in version, set FORCE_BUILTIN_NLOPT to ON (default OFF).

  • The libscotch library. If it is already available on your system, the system version will be used instead. To force the use of the built-in version, set FORCE_BUILTIN_LIBSCOTCH to ON (default OFF).

  • The tinycolormap library.

  • The nanoflann library.

  • The muparser library.

  • The openGJK library.

The program configuration variables concern the printing format of the real numbers, in the result files (.tess, .msh, etc.):

  • REAL_PRINT_FORMAT, default "%.12f" (12 decimal digits);

  • REAL_PRINT_FORMAT3, default "%15.12f" (12 decimal digits, 15 total digits);

  • REAL_PRINT_FORMAT5, default "%17.12f" (12 decimal digits, 17 total digits).

Testing Neper

Neper comes packaged with tests and reference outputs. To run the tests, execute the following from your build folder:

$ make test

or (equivalently):

$ ctest

This runs the tests in Normal mode (Minimal on macOS), for which the produced output files are compared to reference ones. The (packaged) reference output files are generated on Ubuntu 20.04, using compiler GCC 9.3.0, (built-in) NLopt 2.6.1, (built-in) libscotch 6.0, Gmsh 4.9.4 and POV-Ray 3.7.0. It is expected that different versions may result in minor (insignificant) changes to the output, though this will generally result in failed tests. If this happens, change the testing mode to Minimal. The testing mode is controlled by variable BUILD_TESTING_MODE, which may be changed as described in Fine Configuration.

  • The Normal mode checks if the program completes without error and if the produced output is the same as a set of reference output. It is the default mode on Linux.

  • The Minimal mode only checks if the program completes without error. This mode may be useful when installing on a machine which has program or library versions different from the ones with which the reference output was generated. It is the default mode on macOS.

  • The Writing mode overwrites the reference outputs with the generated output. This mode may be useful when installing on a machine which has program or library versions different from the ones with which the reference output was generated and the user needs a reference output before making changes to the source code.

Getting Started

The neper binary must be run in a terminal, followed by a list of arguments:

$ neper <arguments>

Neper returns messages in the terminal and results in ASCII (optionally binary) files.

The list of arguments describes the problem to solve. There are several general-purpose, self-explanatory arguments:

$ neper --help
$ neper --version
$ neper --license

The following of this section provides information on how to call Neper’s modules, properly format option arguments and set up an initialization file.

Modules

To call a module, run:

$ neper <module_name> <module_arguments>

where the module name can be -T, -M, -S or -V, and the module arguments can include both required input data and options. Input data (when not a file name) and options start by -. Options can be provided in arbitrary order and are always followed by a single argument. String completion is available for all options, so they may be abbreviated as long as the abbreviation is not ambiguous. For instance, in module -T, option -regularization can be abbreviated to -reg. Autocomplete is also available and will complete an option name (or provide possibilities for the option name) when hitting the Tab key. For instance, -reg<tab> completes to -regularization, and neper -T -n 1 -d shows -domain -dim.

Important

  • An argument must not contain any spaces.

  • When an argument contains shell metacharacters ((, ), ?, <, etc.), it must be enclosed in either single (') or double (") quotes to be read in properly. (Only double quotes enable variable substitution by the shell).

Logical options can be enabled or disabled by providing argument values of 1 or 0, respectively. Integer or real arguments can be written as numeral values or Mathematical and Logical Expressions. For instance, in module -T, option -rcl 0.5 can also be written as -rcl 1/2 or -rcl "cos(pi/3)". For some options, different values can be specified to different entities by loading them from an external Data File (or similar), using file(<file_name>). For the more complex case of a multiscale tessellation, a Multiscale Cell File can also be used, and loaded using msfile(<file_name>).

Module -V shows some exceptions with respect to these rules: the argument can only be listed in arbitrary order before their corresponding -print call, string completion is not available for custom input options, and option -loop takes several arguments.

Argument Separators

Some options may take several argument values, which can be combined using separators:

  • The , separator is used to combine uncorrelated arguments, i.e. arguments of the same type, which can be processed independently from each other, in any order. This is for example the case of output file formats.

  • The : separator is used to combine correlated arguments, i.e. arguments of different types, which cannot be processed independently from each other and must be processed in order. This is for example the case of the values of a variable in different directions.

  • The :: separator is used in module -T (and a little in module -M) to assign argument values to the different scales of a multiscale tessellation. It is a super-separator that takes precedence over the , and : standard separators.

Initialization File

When Neper is run, it starts by reading commands from an initialization file, $HOME/.neperrc, if that file exists. Another initialization file can be specified with option --rcfile, before calling a module:

$ neper --rcfile <my_rc_file> <module_name> <module_arguments>

The reading of an initialization file can be disabled using option --rcfile none.

When a Neper module is called, Neper looks for the occurrence of neper <module_name> in the initialization file and then reads all arguments until the next occurrence of neper (which should denote the beginning of another module option field) or the end of the file. The arguments may be any legal arguments but are typically limited to frequently-used options. Moreover, any field of comments can be preceded by neper comments.

Here is the example of an initialization file, featuring its syntax (parts beginning with ## do not belong to the file):

neper comments -------------------------------------  ## comment
This is my initialization file.                       ## comment
                                                      ## comment
        It is pretty incomplete though...             ## comment
                                                      ## comment
neper -T -reg 1                                       ## -T option
neper -M -gmsh my_gmsh_path                           ## -M option
     -order 2                                         ## -M option
                                                      ## comment
neper comments                                        ## comment
        Remember to add what I do not remember!       ## comment
neper -V -povray my_povray_path                       ## -V option
neper comments -------------------------------------  ## comment

If the initialization file is not found, or if neper <module_name> is not found inside it, Neper will consider only the command line arguments. Also, if an argument is initialized several times (for instance, both in the initialization file and at the command line), only the last specified value is used.

Running Conditions

Neper runs on all threads by default. The actual number of threads to use can be set at run stage, using the OMP_NUM_THREADS environment variable, as in

$ export OMP_NUM_THREADS=8

The environment variable is unset by default.

Conventions Used in This Manual

  • A command entered at the terminal is shown like this:

    $ command

    The first character on the line is the terminal prompt, and should not be typed. The dollar sign, $, is used as the standard prompt in this manual, although some systems may use a different character.

  • A program (or command) option is printed like this;

  • An option argument is printed like <this>;

  • The name of a variable, or a meta-syntactic variable, is printed like <this>;

  • A series of values are enclosed in curly brackets ({ and }) and separated by ,, as in {1,3};

  • A range of integer values or letters are enclosed in curly brackets ({ and }) and separated by -, as in {1-3};

  • Mutually exclusive values are enclosed in curly brackets ({ and }) and separated by |, as in {possibility1|possibility2};

  • Optional arguments are enclosed in square brackets ([ and ]);

  • Different possibilities for an integer number, in a variable name, file name, etc. are printed using the # symbol (e.g., one (or all) of <var1>, <var2>, etc. is printed <var#>);

  • An arbitrary piece of text, composed or zero or more characters, is printed using the * symbol (as in the Shell language);

  • Literal examples are printed like

    this

  • File names are printed like this.

Just like the $ sign, the <, >, [, ], {, }, etc. signs are used only for formatting and should not be typed.

Options that are only of secondary importance or for fine tuning are tagged (Secondary option).

Some options, such as -datacellcol, -datafacecol, etc., differ only by the fact that they apply to different entities and are documented together, as -data{cell,...,face,...}col.

Some abbreviations are used consistently for options and contribute to Neper’s jargon:

Abbreviation

Meaning

algo

algorithm

arch

architecture

aspratio

aspect ratio

cl

characteristic length

col

color or column

conv

convergence

coo

coordinate

crysym

crystal symmetry

csys

coordinate system

diameq

equivalent diameter

dim

dimension

dir

directory or direction

dis

distribution or distortion

dof

degree of freedom

dup

duplicate(d)

elset

element set

elt

element

expr

expression

fact

factor

faset

element face set

geo

geometry

id

identifier

ini

initial

inf

infinity

inter

interpolation

iter

iteration

max

maximum

min

minimum

morpho

morphology

nb

number

neigh

neighbor

nset

node set

opti

optimization

ori

orientation

part

partition

poly

polyhedron

pov

POV-Ray file

qual

quality

rad

radius

rcl

relative characteristic length

res

resolution

rmax

relative maximum

sing

singular

stat

statistics

surf

surface

tesr

raster tessellation

tess

scalar tessellation

tmp

temporary

trs

transparency

val

value

var

variable

ver

vertex