Installation

Get librascal

It is strongly recommended to clone librascal from its repository in GitHub.

git clone https://github.com/lab-cosmo/librascal.git

The installation of the library for python use can be done simply with:

pip install .

assuming that python 3.5 (or higher) and gcc or clang are available.

Dependencies

Before installing librascal, please make sure you have at least the following packages installed:

Package	Required version
gcc (g++)	4.9 or higher
clang	4.0 or higher
cmake	2.8 or higher
python	3.6 or higher
numpy	1.13 or higher
scipy	1.4.0 or higher
ASE	3.18 or higher

Other necessary packages (such as Eigen and pybind11) are downloaded automatically when compiling Rascal.

The following packages are required for some optional features:

Feature	Package	Required version
Feature compression	skcosmo	0.1.0 or later
Rotational algebra (Clebsch-Gordan coeffs.)	sympy	1.4 or later
Building documentation	pandoc	(latest)
	sphinx	2.1.2 or later
	breathe	4.14.1 or later
	nbsphinx	0.8.1 or later

Compiling

To compile the code it is necessary to have CMake 3.0 and a C++ compiler supporting C++14. During the configuration, it will automatically try to download the external libraries on which it depends:

• Eigen

• pybind11

• Boost (only the unit test framework library)

• Python3

And the following libraries to build the documentation:

• Doxygen

• Sphinx

• Breathe

Beware, Python3 is mandatory. The code won’t work with a Python version older than 3.

You can then use pip to install all python packages required for the usage and development of rascal:

pip install -r requirements.txt

To configure and compile the code with the default options, on *nix systems (Windows is not supported):

mkdir build
cd build
cmake ..
make

Customizing the build

The library supports several alternative builds that have additional dependencies. Note that the ncurses GUI for cmake (ccmake) is quite helpful to customize the build options.

Tests

Librascal source code is extensively tested (both c++ and python). The BOOST unit_test_framework is required to build the tests (see BOOST.md for further details on how to install the boost library). To build and run the tests:

cd build
cmake -DBUILD_TESTS=ON ..
make
ctest -V

You can also run the tests with Valgrind (a memory-error checker) by passing -DRASCAL_TESTS_USE_VALGRIND=ON to cmake.

In addition to testing the behaviour of the code, the test suite also check for formatting compliance with clang-format 8.0 or higher and black packages (these dependencies are optional). To install these dependencies on Ubuntu:

sudo apt-get install clang-format-8
pip3 install black

Build Type

Several build types are available Release (default), Debug and RelWithDebInfo. To build an alternative mode

cd build
cmake -DCMAKE_BUILD_TYPE=Debug
..
make

Or

cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo  \\
   CMAKE_C_FLAGS_RELWITHDEBUBINFO="-03 -g -DNDEBUG" ..
make

Documentation

The documentation relies on the sphinx (with nbsphinx and breathe extensions), doxygen, pandoc, and graphviz packages. To install them on ubuntu:

pip3 install sphinx sphinx_rtd_theme breathe nbsphinx
sudo apt-get install pandoc doxygen graphviz

Then to build the documentation run:

cd build
cmake -DBUILD_DOC=ON ..
make doc

and open build/docs/html/index.html in a browser.

Bindings

Librascal relies on the pybind11 library to automate the generation of the python bindings which are built by default. Nevertheless, to build only the c++ library:

cd build
cmake -DBUILD_BINDINGS=OFF ..
make

Installing rascal

To install the python library with c++ bindings:

pip install .

Helpers for Developers

Deepclean

To remove all the cmake files/folders except for the external library (enable glob and remove):

shopt -s extglob
rm -fr -- !(external|third-party)

Automatic code formatting

To help developers conform their contribution to the coding convention, the formatting of new functionalities can be automated using clang-format (for the c++ files) and black (for the python files). The .clang-format and .pycodestyle files define common settings to be used.

To enable these functionalities (optional) you can install these tools with:

sudo apt-get install clang-format
pip install black

The automatic formatting of the c++ and python files can be triggered by:

cd build
cmake ..
make pretty-cpp
make pretty-python

Please use these tools with caution as they can potentially introduce unwanted changes to the code. If code needs to be specifically excluded from auto formatting, e.g. a matrix which should be human-readable, code comments tells the formatters to ignore lines:

• C++

  // clang-format off
  SOME CODE TO IGNORE
  // clang-format on
  

• python

  SOME LINE TO IGNORE # noqa
  

  where noqa stands for no quality assurance.

Jupyter notebooks

If you are contributing any code in IPython/Jupyter notebooks, please install the nbstripout extension (available e.g. on github and PyPI). After installing, activate it for this project by running:

nbstripout --install --attributes .gitattributes

from the top-level repository directory. Please note that that nbstripout will not strip output from cells with the metadata fields keep_output or init_cell set to True, so use these fields judiciously. You can ignore these settings with the following command:

git config filter.nbstripout.extrakeys '\
   cell.metadata.keep_output cell.metadata.init_cell'

(The keys metadata.kernel_spec.name and metadata.kernel_spec.display_name may also be useful to reduce diff noise.)

Nonetheless, it is highly discouraged to contribute code in the form of notebooks; even with filters like nbstripout they’re a hassle to use in version control. Use them only for tutorials or stable examples that are either meant to be run interactively or are meant to be processed by sphinx (nbsphinx) for inclusion in the tutorials page.

Miscellaneous Information

• Common cmake flags:

  • -DCMAKE_CXX_COMPILER

  • -DCMAKE_C_COMPILER

  • -DCMAKE_BUILD_TYPE

  • -DBUILD_BINDINGS

  • -DINSTALL_PATH

  • -DBUILD_DOC

  • -DBUILD_TESTS

• Special flags:

  • -DBUILD_BINDINGS:

    • ON (default) -> build python binding

    • OFF -> does not build python binding

  • -DINSTALL_PATH:

    • empty (default) -> does not install in a custom folder

    • custom string -> root path for the installation

To build librascal as a docker environment:

sudo docker build -t test -f ./docker/install_env.dockerfile  .
sudo docker run -it -v /path/to/repo/:/home/user/  test

Run Rascal

In order to run Rascal, you need to import the library into a Python code:

import rascal
from rascal.representations import *

Advanced options

It is possible to link Rascal with other scientific calculation packages, like LAMMPS, ASE, i-PI, and n2p2. These interfaces are still a work in progress.