Installing¶
Conda¶
For macOS and Linux, precompiled binary packages are available via (mini)conda:
conda config --add channels conda-forge
conda install faunus
In addition to the faunus
executable, this installs a set of examples in share/faunus
,
as well as python bindings.
To update an existing installation, use
faunus --version # show version string
conda search faunus # show (new) revisions
conda upgrade faunus
Starting from version 2.1, we adhere to semantic versioning. Note: Updating to a newer version is often delayed, and if the version you’re after is not on Conda, consider an alternative method below.
Docker¶
We provide a Dockerfile
that builds the main branch in a Jupyter environment:
curl -s https://raw.githubusercontent.com/mlund/faunus/master/scripts/Dockerfile | docker build -t faunuslab -
docker run -it -p 8888:8888 faunuslab # open generated url in a browser
Once running, you may alias the Docker-side faunus command:
alias faunus='docker exec --interactive -u 1000 faunuslab faunus'
faunus < input.json # piping input to docker
Build from source code¶
Faunus is continuously tested on macOS/Linux, but compile on most unix operating systems, including the Windows Subsystem for Linus (WSL).
Requirements¶
- CMake 3.16+
- C++20 compiler (clang, g++, intel ixpc, …)
- Python 3.6+ with the following packages:
jinja2
,ruamel_yaml
oryaml
The following are optional:
jsonschema
(for validating input - highly recommended)pandoc
(for building manual)pypandoc
(for building manual)BeautifulSoup4
(for building manual)- Message Passing Interface (MPI)
Compiling¶
Download the latest release or the developer branch and build using cmake:
cd faunus
cmake . [OPTIONS]
make faunus
make usagetips # requires `pandoc`, `pypandoc`, `BeautifulSoup4`
Use make help
to see all build targets.
The following options are available:
CMake Option | Description |
---|---|
-DENABLE_MPI=OFF |
Enable MPI |
-DENABLE_OPENMP=ON |
Enable OpenMP support |
-DENABLE_TESTS=ON |
Enable unittesting |
-DENABLE_PYTHON=OFF |
Build python bindings (experimental) |
-DENABLE_FREESASA=ON |
Enable SASA routines (external download) |
-DENABLE_TBB=OFF |
Build with Intel Threading Building Blocks (experimental) |
-DENABLE_PCG=OFF |
Use PCG random number generator instead of C++'s Mersenne Twister |
-DBUILD_STATIC=OFF |
Build statically linked binaries |
-DCMAKE_BUILD_TYPE=Release |
Alternatives: Debug or RelWithDebInfo |
-DCMAKE_CXX_FLAGS_RELEASE="..." |
Compiler options for Release mode |
-DCMAKE_CXX_FLAGS_DEBUG="..." |
Compiler options for Debug mode |
-DCMAKE_INSTALL_PREFIX:PATH="..." |
Install location (default: /usr/local ) |
-DPython_EXECUTABLE="..." |
Full path to Python executable |
Compiling the Manual¶
Pandoc is required to build the HTML manual:
make manual_html
In addition to pandoc, a TeX Live installation containing XeLaTeX is required to build the PDF manual.
The manual is supposed to be typeset with
EB Garamond,
Garamond Math and
Fira Code
fonts thus they have to be available in your system. Alternatively, you can tweak the font options
in the header.md
file.
make manual
Selecting compilers and python¶
Should there be multiple compilers or python distributions, be specific:
export CC=/opt/bin/clang
export CXX=/opt/bin/clang++
cmake -DPython_EXECUTABLE=/opt/bin/python3 .
For solving rare python issues on macOS, the linked python library can be probed and, if needed, renamed:
otool -L pyfaunus.so
install_name_tool -change libpython3.8.dylib \
$HOME/miniconda/lib/libpython3.8.dylib pyfaunus.so
For further help with compiling with python bindings, see here.
Resetting the build system¶
To change the compiler or for another reason reset the build system, do:
make clean
rm -fR CMakeCache.txt CMakeFiles _deps
Intel Threading Building Blocks¶
If ENABLE_TBB=on
, TBB may be used for threaded simulations which may or may not be
advantageous, depending on the system.
By default, an unspecified and possibly outdated version of TBB will be downloaded and build.
Alternatively you can use an existing installation via TBB_DIR
:
cmake -DENABLE_TBB=on -DTBB_DIR={tbb-root}/lib/cmake/TBB
where {tbb-root}
is the installation directory of TBB, e.g. /usr/local
.
Development¶
The development of Faunus is done mainly in Jetbrain’s CLion
(free academic license) but any other IDE or merely a text editor can be used.
We recommend to use tools that respect the provided .clang-format
which will ease merging
changes into the codebase, see below.
Code Style¶
If you plan to contribute to Faunus it is recommended to activate the pre-commit hook for automatic styling of all changes:
cd faunus
./scripts/git-pre-commit-format install
This requires clang-format
which may also be directly used in IDEs
such as CLion. In the top-level directory of Faunus you will find
the style configuration file .clang-format
Also, adhere to the following naming conventions:
Style | Elements |
---|---|
CamelCase |
classes, namespaces |
camelBack |
functions |
snake_case |
variables |
Creating a conda package (development usage)¶
The basic steps for creating a conda package is outlined below, albeit
details depend on the build environment. See also the .travis.yml
configuration file in the main repository.
conda config --add channels conda-forge
conda install conda-build anaconda-client
cd scripts/
conda-build .
anaconda login
anaconda upload -u USER ... # see output from build step
Instead of uploading to anaconda.org, install a local copy directly after the build step above:
conda install -c USER faunus --use-local