Installation

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 neither test nor support this usage and multithreading must be turned off (which slows down execution significantly).

When installed, Neper consists of the neper binary, which can be called from the command line, and data files, which are used by the binary. At runtime, neper looks for its data files in $NEPER_DATA_DIR, ../share/neper relative to the directory of the neper binary (so that an installed binary uses its own data files), $HOME/.local/share/neper and <prefix>/share/neper, successively, where <prefix> is the installation prefix (/usr/local by default, see below). The data directory is printed by neper --data.

Neper can be installed using conda, which is the simplest method (see Conda Package), or compiled from its source code (see Building from Source).

Conda Package

Neper is available as a conda package from conda-forge, for Linux and macOS. No compilation and no administrator rights are needed.

If conda is not available on your system (command conda), install it first, using Miniforge:

$ curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
$ bash Miniforge3-$(uname)-$(uname -m).sh

Accept the license and the default installation directory ($HOME/miniforge3), and answer yes to the last question, about initializing conda, so that conda is available in new terminals. Then, open a new terminal (or run source ~/.bashrc, for Bash). The terminal prompt then starts with (base), which is the default conda environment. The installer file can be removed.

Then, install Neper in a new environment (named neper here) and activate it:

$ conda create -n neper -c conda-forge neper
$ conda activate neper

This also installs the required programs and libraries: Gmsh, POV-Ray, etc. Asymptote and ImageMagick, which are needed only for some outputs of Visualization Module (-V) (see Fine Configuration), are not installed.

Neper can then be run as neper in the activated environment, and updated by:

$ conda update -n neper -c conda-forge neper

Neper and FEPX can also be installed together, in the same environment (named neperfepx here), to generate meshes with Neper, simulate them with FEPX and post-process the results with Neper:

$ conda create -n neperfepx -c conda-forge neper fepx
$ conda activate neperfepx

Building from Source

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 Neper available system-wide, run (using sudo for administration privileges):

$ sudo make install

To make Neper available locally to the user, run:

$ make userinstall

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

Attention

Since version 4.11, either make install or make userinstall must be run for proper installation. Copying the neper binary to ~/bin for a local installation is no longer sufficient.

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 directory is CMAKE_INSTALL_PREFIX, which defaults to /usr/local for make install and $HOME/.local for make userinstall.

Other compilation options are CMAKE_BUILD_TYPE and ENABLE_PROFILING, which should not be used for production.

The dependencies that are needed at compilation time, and must therefore be installed on your system before Neper is compiled, are the following:

• 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.

• The Gmsh library (version 4.9 or higher, mandatory). It is used for meshing (module -M). It is likely to be available from your system package manager (package libgmsh-dev on Debian and Ubuntu); alternatively, it is provided by the Gmsh SDK, or it can be built from the Gmsh source code. If it is not installed in a standard location, its installation directory can be specified using CMAKE_PREFIX_PATH.

  To build the Gmsh library from the Gmsh source code, Gmsh must be configured with -DENABLE_BUILD_DYNAMIC=1 (which builds the shared library, libgmsh.so, in addition to the Gmsh program), and then installed with make install (which installs the library and its header files, including gmshc.h, used by Neper):

  $ cd gmsh-<version>-source
  $ mkdir build
  $ cd build
  $ cmake -DENABLE_BUILD_DYNAMIC=1 ..
  $ make
  $ make install
  

  To install Gmsh in a non-standard location, add -DCMAKE_INSTALL_PREFIX=<directory> to the cmake command, pass -DCMAKE_PREFIX_PATH=<directory> when configuring Neper, and make the library available at run time (for example, by adding its library directory to LD_LIBRARY_PATH).

Other dependencies are only needed at runtime (they are not necessary for compilation):

• 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 from 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 -asymptote (in module -V).

• The ImageMagick program (mandatory for PNG output of orientation spaces in Visualization Module (-V), -space rodrigues). It is likely to be available on your system or from your system package manager. ImageMagick must be available at the terminal as the command convert.

  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 GNU Scientific Library (GSL). 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_GSL to ON (default OFF).

  Note

  The built-in GSL version is 2.7.1 (subset).

• 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 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) 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 the 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.

Orilib Program

Neper’s library of orientation functions, Orilib, also comes as a program, orilib, which makes it possible to run its functions from the command line, for example to convert orientations between descriptors or to compute disorientations. It is built and installed together with neper (it can also be built alone, using make orilib). Its functions are also available in Python (see Orilib).

The program can be run in three ways:

• orilib starts an interactive session, in which a command is typed, then its input data (as requested), and so on, until quit is typed. listall lists the commands, signatures lists their inputs and outputs (with their types) and help prints help;

• orilib <command> runs a single command, reading its input data from the standard input and writing its output to the standard output (with no other information), which makes it convenient for scripting, for example:

  $ echo 0 30 0 | orilib ol_e_q
   0.965925826  0.258819045  0.000000000  0.000000000
  

• orilib loop <command> runs a command repeatedly, on all the input data.

The real output values are written with 9 decimals, and their format can be changed using environment variable ORILIB_FORMAT, e.g. ORILIB_FORMAT=%.17g for full precision.

The commands are named after the Orilib functions, which follow the pattern ol_, where the descriptors are abbreviated as e (Euler angles, Bunge convention), g (rotation matrix), q (quaternion), m (Miller indices), rtheta (rotation axis / angle pair), R (Rodrigues vector) and homochoric (homochoric vector), and angles are in degrees (or in radians with the _rad suffix). The main families of commands are:

Commands	Description
ol_e_g, ol_q_R, etc.	conversions between orientation descriptors
ol_g_g_g, ol_q_inverse, etc.	combination and inversion of rotations
ol_q_crysym, ol_q_qcrysym, etc.	crystallographically related and preferred orientations
ol_q_q_misori, ol_q_q_disori, etc.	misorientations and disorientations (angles or rotations)
ol_q_refsym, etc.	symmetries with respect to the sample (orthotropic, etc.)
ol_q_pf_stprojxy, etc.	pole figure and inverse pole figure projections
ol_nb_e, ol_nb_max_rtheta, etc.	generation of orientations from random numbers
ol_label_q, ol_q_des, etc.	orientations given as labels or descriptor names

The complete list of commands is provided in Orilib Commands (it can also be printed using orilib listall).

Python Interface

The Python interface is the neper Python package, provided in the python directory of the distribution. It requires Python 3.8 or higher and Neper itself (installed as described above), and is installed using pip, from the top-level directory of the distribution:

$ pip install ./python

This also installs NumPy, if needed. See Python Interface for details.

[1]

On macOS, install llvm and libomp via Homebrew.