Installation

This chapter discusses BFORE installation in detail. If you just want to get up and running, have a look at the Quick Start chapter.

Pre-Requisites

To compile and run BFORE, you’ll need the following software components:

A modern (2003+) Fortran compiler
The BLAS linear algebra library
The LAPACK linear algebra library
The LAPACK95 Fortran 95 interface to LAPACK
The HDF5 data management library
The crlibm correctly rounded math library
The crmath Fortran 2003 interface to crlibm
The fypp Fortran preprocessor
The toml-f Fortran TOML parser

On Linux and MacOS platforms, all of these components are bundled together in the MESA Software Development Kit (SDK), which can be downloaded from the MESA SDK homepage. Using this SDK is strongly recommended.

Building BFORE

Download

Download the BFORE source code, and unpack it from the command line using the tar utility:

$ tar xf bfore-0.1.tar.gz

Set the BFORE_DIR environment variable with the path to the newly created source directory; this can be achieved, e.g., using the realpath command[1]:

$ export BFORE_DIR=$(realpath bfore-0.1)

Compile

Compile and install BFORE using the make utility:

$ make -j -C $BFORE_DIR

(the -j flags tells make to use multiple cores, speeding up the build).

Test

To check that BFORE has compiled correctly and gives reasonable results, you can run the unit tests via the command

$ make -C $BFORE_DIR utest

The initial output from the tests should look something like this:

 Checking mesh connectivity
   edge_next(edge_prev(e)) == e                                  ...passed
   edge_prev(edge_next(e)) == e                                  ...passed
   edge_next(edge_next(e)) == edge_prev(e)                       ...passed
   edge_prev(edge_prev(e)) == edge_next(e)                       ...passed
   edge_twin(e) == e                                             ...passed
   edge_face(face_edge(f)) == f                                  ...passed
   edge_face(face_edge(edge_face(e))) == edge_face(e)            ...passed
   edge_vert(vert_edge(v)) == v                                  ...passed
   edge_vert(vert_edge(edge_vert(e))) == edge_vert(e)            ...passed

Custom Builds

Custom builds of BFORE can be created by setting certain environment variables to the value yes. The following variables are currently supported:

EXTERNAL_FORUM: Link against an external ForUM library (default no). If set to yes, then you must ensure that the forum.pc package file can be found by the pkgconf utility (for instance, by setting the PKG_CONFIG_PATH environment variable)

EXTERNAL_MSG: Link against an external MSG library (default no). If set to yes, then you must ensure that the msg.pc package file can be found by the pkgconf utility (for instance, by setting the PKG_CONFIG_PATH environment variable)

DEBUG: Enable debugging mode (default no)

SHARED: Build shared libraries in addition to static ones (default yes)

OMP: Enable OpenMP parallelization (default yes)

FPE: Enable floating point exception checks (default yes)

UTESTS: Build unit tests (default yes)

If an environment variable is not set, then its default value is assumed. The default values can be altered by editing the file $BFORE_DIR/Makefile.

Git Access

Sometimes, you’ll want to try out new features in BFORE that haven’t yet made it into a formal release. In such cases, you can check out BFORE directly from the rhdtownsend/bfore git repository on GitHub:

$ git clone --recurse-submodules https://github.com/rhdtownsend/bfore.git

However, a word of caution: BFORE is under constant development, and features in the main (main) branch can change without warning.

footnote