feeLLGood – Installation

The source code of FeeLLGood is available on GitHub.

FeeLLGood is only distributed in source form, and depends on third-party libraries that are themselves only readily available in source form. In order to install it, you will need a fairly recent C++ toolchain, e.g. GCC 9 or newer.

Although FeeLLGood is meant to be portable, it has only been tested on Linux systems. The instructions that follow have been tested on fresh installs of Ubuntu (20.04 and 22.04), Debian (11 and 12) and Rocky Linux 9. Older versions of these distributions ship a GCC toolchain that is too old. You may need to make a few changes if you are using a different Linux flavor.

Installing the required libraries

FeeLLGood requires the libraries TBB, yaml-cpp, ANN, Duktape, ScalFMM, and Eigen. These libraries should be installed somewhere along the standard library search path.

Installing the required libraries in standard locations may not be possible if you do not have root access on the target system. In this case, you can install them anywhere, but you will then have to configure FeeLLGood’s build in order to find them. See the section Unprivileged install for details. Save for that specific section, this document assumes you are performing a regular install and you can invoke sudo to get root privileges.

This guide aims at providing definite instructions that can be successfully followed by blindly copying and pasting commands into the terminal. For definiteness, the following choices have been made: Eigen, TBB and yaml-cpp will be installed from a package of the Linux distribution and the other libraries from source. Eigen, TBB and yaml-cpp will end up in /usr/{include,lib}, while the others will be in /usr/local/{include,lib}. The source directories of the libraries and FeeLLGood will be installed under a common parent called src, under the current working directory, as in the following diagram:

.           ← initial working directory
└── src
    ├── ann_1.1.2
    ├── duktape-2.7.0  (on Rocky Linux only)
    ├── ScalFMM-V1.5.1
    └── FeeLLGood

We start by installing some Linux packages: unzip, the C++ compiler, make, cmake (needed by ScalFMM and FeeLLGood), git (needed by FeeLLGood) and the libraries Eigen, TBB, yaml-cpp and Duktape (needed by FeeLLGood). On Rocky Linux, Duktape will have to be installed from sources, as there is no package available in its standard repositories. Rocky Linux also requires installing wget (which is standard in Debian and Ubuntu) and a few extra commands to enable the installation of some other packages:

# On Ubuntu and Debian:
sudo apt-get update
sudo apt-get install unzip make cmake git g++ libeigen3-dev libtbb-dev libyaml-cpp-dev duktape-dev

# On Rocky Linux:
sudo dnf check-update
sudo dnf config-manager --set-enabled devel crb
sudo dnf install epel-release
sudo dnf install wget unzip make cmake git gcc-c++ eigen3-devel tbb-devel yaml-cpp-devel

Optionally, if you want to build the source documentation of ScalFMM or FeeLLGood, you will also need Doxygen and Graphviz:

# On Ubuntu and Debian:
sudo apt-get install doxygen graphviz

# On Rocky Linux:
sudo dnf install doxygen

Note that, on Rocky Linux, Graphviz is a dependency of Doxygen and does not need to be explicitly installed.

Then, create the src directory that will be the common parent of all the sources, and move into it:

mkdir src
cd src

Install MKL

This library is optional.

The Intel® Math Kernel Library (MKL), if available on the host system, can be used by feeLLGood to speed up some linear algebra computations. On Ubuntu and Debian, it can be installed as follows:

# These two lines are needed on Debian only:
sudo apt-get install software-properties-common
sudo apt-add-repository non-free

# Both on Ubuntu and on Debian:
sudo apt-get install libmkl-dev

Alternatively, MKL can be installed on most Linux systems by following the instructions provided by Intel. This option, however, comes with some caveats:

one has to install the package intel-oneapi-mkl-devel, even though Intel may suggest installing only intel-oneapi-mkl (dnf users beware!)
one has to properly set up the environment before building feeLLGood, which is done with the command
```
source /opt/intel/oneapi/setvars.sh
```
failing to do so would result in a cmake failure
this environment will also be needed for running feeLLGood, otherwise an “error while loading shared libraries” would result; at a minimum, LD_LIBRARY_PATH would have to be set.

Download and install ANN

FeeLLGood uses the ANN library for building a kdtree and for finding nodes fast. It is needed when recentering the whole magnetization distribution on the nodes.

Download and install ANN 1.1.2 as follows:

wget https://www.cs.umd.edu/~mount/ANN/Files/1.1.2/ann_1.1.2.tar.gz
tar xzf ann_1.1.2.tar.gz
cd ann_1.1.2/
sed -i 's/CFLAGS =.* -O3/& -std=c++98/' Make-config
make linux-g++
sudo cp lib/libANN.a /usr/local/lib/
sudo cp include/ANN/ANN.h /usr/local/include/
cd ..

On Rocky Linux, download and install Duktape

FeeLLGood lets the user use analytical expressions for defining the initial magnetization configuration, and a time-dependent applied field. It uses Duktape for parsing these expressions.

On Debian and Ubuntu, Duktape is available in the apt repositories. On Rocky Linux, it has to be installed from sources:

wget -nv https://duktape.org/duktape-2.7.0.tar.xz
tar -xJf duktape-2.7.0.tar.xz
cd duktape-2.7.0/src
gcc -O2 -c duktape.c
ar rcs libduktape.a duktape.o
sudo cp libduktape.a /usr/local/lib/
sudo cp duktape.h duk_config.h /usr/local/include/
cd ../..

Download, patch and install ScalFMM

FeeLLGood uses ScalFMM 1.5 for computing the demagnetizing field, through a fast multipole algorithm that evaluates the scalar potential from the surface and volume magnetic charges.

Warning: There are a few small bugs in ScalFMM that can affect FeeLLGood. These bugs have to be patched before invoking cmake.

Download, patch and install ScalFMM as follows:

scalfmm_sha1=22b9e4f6cf4ea721d71198a71e3f5d2c5ae5e7cc
wget https://gitlab.inria.fr/solverstack/ScalFMM/-/archive/$scalfmm_sha1/ScalFMM-$scalfmm_sha1.tar.gz
tar xzf ScalFMM-$scalfmm_sha1.tar.gz
cd ScalFMM-$scalfmm_sha1/
sed -i 's/memcpy/if (nbParticles != 0) memcpy/' Src/Components/FBasicParticleContainer.hpp
sed -i 's/OPENMP_CXX_FOUND/OPENMP_FOUND OR OPENMP_CXX_FOUND/' CMakeLists.txt
cd Build
cmake ..
make
sudo make install
cd ../..

On some computers, you may encounter some problems while compiling ScalFMM, see here to solve some possible situations.

Installing FeeLLGood

Once the required libraries are installed, clone the FeeLLGood’s git repository and build it from there:

git clone https://github.com/feellgood/FeeLLGood.git
cd FeeLLGood/
cmake .
make

Some explanations of the compiler options and what may be modified or not can be found here.

The make command above creates an executable named feellgood in the current working directory. If you want to install it, you can type:

sudo make install

This will copy the executable, together with some scripts from the tools directory, to /usr/local/bin. It will also copy the contents of the python-modules directory to /usr/local/lib/python3.X/YYYY-packages/feellgood, where 3.X is your Python version and YYYY is dist or site, depending on your Linux distribution. The installed directory tree will have the following structure:

/usr/local
├── bin
│   ├── feellgood                 ← feeLLGood executable
│   └── ...                       ← a few Python scripts from tools/
└── lib
    └── python3.*                 ← named with your Python version number
        └── site-packages         ← or "dist-packages", if that directory exists
            └── feellgood         ← Python "feellgood" package
                ├── __init__.py   ← empty, needed to make a Python package
                └── *.py          ← some Python modules

If you want to install things elsewhere, you can manually copy the feellgood executable, and any scripts from tools/ you may want to use, to any directory in your $PATH. You may also copy the python-modules directory anywhere in your Python's sys.path, but make sure to rename it feellgood, as the provided scripts and examples use the idiom from feellgood.… import ….

Build the source documentation

This is not required, or even useful, for using FeeLLGood. However, if you want to understand the FeeLLGood sources, this documentation may help making sense of the program internals.

Assuming you have installed Doxygen and Graphviz, you can generate the source documentation by typing:

doxygen

Then, open the file html/index.html in your browser.

The source documentation of the latest version of FeeLLGood is also available online: FeeLLGood internals.

Unprivileged install

It is possible to install FeeLLGood without root privileges. For doing so, you will have to first install the required libraries in a directory you have write access to, then configure FeeLLGood’s build to search for those libraries in the right place. This second step is done by adding the appropriate include_directories and link_directories commands to CMakeLists.txt.

The example script below performs such an unprivileged install. It assumes wget, unzip, g++, make, cmake, git, eigen, tbb and yaml-cpp are already installed. It creates the following directory structure:

$install_prefix          ← root of the installation
├── bin
│   ├── feellgood        ← FeeLLGood executable
│   └── ...              ← FeeLLGood Python scripts + ScalFMM tools
├── include              ← library headers
├── lib
│   ├── python3.*                 ← named with your Python version number
│   │   └── site-packages         ← or "dist-packages", if that directory exists
│   │       └── feellgood         ← Python "feellgood" package
│   │           ├── __init__.py   ← empty, needed to make a Python package
│   │           └── *.py          ← some Python modules
│   └── ...                       ← library archives
└── src                  ← sources
    ├── ScalFMM-V1.5.1
    ├── ann_1.1.2
    ├── duktape-2.7.0
    └── FeeLLGood

The variable install_prefix defines the root of the installation. It is set in the script to the current working directory, but you can change it to your liking.

Here is the script:

#!/bin/bash

# Root of the installation.
# This can be changed to any directory you have write access to.
install_prefix=$PWD

# Set up the directory structure.
mkdir -p $install_prefix/{include,lib,src}
cd $install_prefix/src

# Install ANN.
wget -nv https://www.cs.umd.edu/~mount/ANN/Files/1.1.2/ann_1.1.2.tar.gz
tar xzf ann_1.1.2.tar.gz
cd ann_1.1.2/
sed -i 's/CFLAGS =.* -O3/& -std=c++98/' Make-config
make linux-g++
cp lib/libANN.a $install_prefix/lib/
cp include/ANN/ANN.h $install_prefix/include/
cd ..

# Install Duktape.
wget -nv https://duktape.org/duktape-2.7.0.tar.xz
tar -xJf duktape-2.7.0.tar.xz
cd duktape-2.7.0/src
gcc -O2 -c duktape.c
ar rcs libduktape.a duktape.o
sudo cp libduktape.a $install_prefix/lib/
sudo cp duktape.h duk_config.h $install_prefix/include/
cd ../..

# Patch, build and install ScalFMM.
scalfmm_sha1=22b9e4f6cf4ea721d71198a71e3f5d2c5ae5e7cc
wget -nv https://gitlab.inria.fr/solverstack/ScalFMM/-/archive/$scalfmm_sha1/ScalFMM-$scalfmm_sha1.tar.gz
tar xzf ScalFMM-$scalfmm_sha1.tar.gz
cd ScalFMM-$scalfmm_sha1/
sed -i 's/memcpy/if (nbParticles != 0) memcpy/' Src/Components/FBasicParticleContainer.hpp
sed -i 's/OPENMP_CXX_FOUND/OPENMP_FOUND OR OPENMP_CXX_FOUND/' CMakeLists.txt
cd Build
cmake .. -DCMAKE_INSTALL_PREFIX=$install_prefix
make
make install
cd ../..

# Patch, build and install FeeLLGood.
git clone https://github.com/feellgood/FeeLLGood.git
cd FeeLLGood/
ed -s CMakeLists.txt <<EOF
/ADD_EXECUTABLE/i
include_directories($install_prefix/include)
link_directories($install_prefix/lib)
.
wq
EOF
cmake . -DCMAKE_INSTALL_PREFIX=$install_prefix
make
make install