This section goes through the process of getting, installing, and starting to run BOUT++.
The quickest way to get started is to use a pre-built binary. These take care of all dependencies, configuration and compilation. See section Docker image.
The remainder of this section will go through the following steps to manually install BOUT++. Only the basic functionality needed to use BOUT++ is described here; the next section (Advanced installation options) goes through more advanced options, configurations for particular machines, and how to fix some common problems.
Note: In this manual commands to run in a BASH shell will begin with ’$’, and commands specific to CSH with a ’%’.
Docker is a widely used container system, which packages together the operating system environment, libraries and other dependencies into an image. This image can be downloaded and run reproducibly on a wide range of hosts, including Windows, Linux and OS X. Here is the starting page for instructions on installing Docker.
The BOUT++ docker images are hosted on dockerhub for some releases and snapshots. Check the list of BOUT-next tags if you want a recent version of BOUT++ “next” (development) branch. First download the image:
$ sudo docker pull boutproject/boutproject/bout-next:9f4c663-petsc
$ sudo docker run --rm -it boutproject/bout-next:9f4c663-petsc
This should give a terminal in a “boutuser” home directory, in which there is “BOUT-next”, containing BOUT++ configured and compiled with NetCDF, SUNDIALS, PETSc and SLEPc. Python 3 is also installed, with ipython, NumPy, Scipy and Matplotlib libaries. To plot to screen an X11 display is needed. Alternatively a shared directory can be created to pass files between the docker image and host. The following commands both enable X11 and create a shared directory:
$ mkdir shared $ sudo docker run --rm -it \ -e DISPLAY -v $HOME/.Xauthority:/home/boutuser/.Xauthority --net=host \ -v $PWD/shared:/home/boutuser/bout-img-shared \ boutproject/bout-next:9f4c663-petsc
This should enable plotting from python, and files in the docker image put in “/home/boutuser/bout-img-shared” should be visible on the host in the “shared” directory.
If this is successful, then you can skip to section Running BOUT++.
BOUT++ is hosted publicly on github at https://github.com/boutproject/BOUT-dev. You can the latest stable version from https://github.com/boutproject/BOUT-dev/releases. If you want to develop BOUT++, you should use git to clone the repository. To obtain a copy of the latest version, run:
$ git clone https://github.com/boutproject/BOUT-dev.git
which will create a directory
BOUT-dev containing the code:
$ cd BOUT-dev
To get the latest changes later, go into the
BOUT-dev directory and run:
$ git pull
Development is done on the “next” branch, which you can checkout with:
$ git checkout next
The bare-minimum requirements for compiling and running BOUT++ are:
A C++ compiler that supports C++14
The NetCDF library (https://www.unidata.ucar.edu/downloads/netcdf)
The FFTW-3 library (http://www.fftw.org/)
is also strongly recommended. Fourier transforms are used for some
derivative methods, as well as the
ShiftedMetric parallel transform
which is used in the majority of BOUT++ tokamak simulations. Without
FFTW-3, these options will not be available.
If you use an Intel compiler, you must also make sure that you have a version of GCC that supports C++14 (GCC 5+).
On supercomputers, or in other environments that use a module system, you may need to load modules for both Intel and GCC.
On a cluster or supercomputer¶
If you are installing on a cluster or supercomputer then the MPI C++ compilers will
already be installed, and on Cray or IBM machines will probably be
On large facilities (e.g NERSC or Archer), the compilers and libraries
needed should already be installed, but you may need to load them to use them.
It is common to organise libraries using the
modules system, so try typing:
to get a list of available modules. Some instructions for specific machines can be found in Machine-specific installation. See your system’s documentation on modules and which ones to load. If you don’t know, or modules don’t work, you can still install libraries in your home directory by following the instructions below for FFTW and NetCDF.
Ubuntu / Debian¶
On Ubuntu or Debian distributions if you have administrator rights then you can install the basic dependencies with:
$ sudo apt-get install libmpich-dev libfftw3-dev libnetcdf-c++4-dev git make
To additionally build the Python interface, you need some Python packages:
$ sudo apt-get install python3 python3-distutils python3-pip python3-numpy python3-netcdf4 python3-scipy $ pip3 install --user Cython
Further, the encoding for python needs to be utf8 - it may be required
If you do not have administrator rights, so can’t install packages, then you need to install these libraries from source into your home directory. See Advanced installation options for details on installing some of these.
$ pacman -S openmpi fftw netcdf-cxx make gcc
On Fedora the required libraries can be installed by running:
$ sudo dnf build-dep bout++
This will install all the dependencies that are used to install BOUT++ for fedora. Feel free to install only a subset of the suggested packages. For example, only mpich or openmpi is required. To load an mpi implementation type:
$ module load mpi
After that the mpi library is loaded. Precompiled binaries are available for fedora as well. To get precompiled BOUT++ run:
$ # install the mpich version - openmpi is available as well $ sudo dnf install bout++-mpich-devel $ # get the python3 modules - python2 is available as well $ sudo dnf install python3-bout++
BOUT++ uses the CMake build system generator. You will need CMake >= 3.17.
It is possible to get the latest version of CMake using
$ pip install --user --upgrade cmake
$ conda install cmake
You may need to put
~/.local/bin in your
CMake supports out-of-source builds by default, which are A Good Idea. Basic configuration with CMake looks like:
$ cmake -S . -B build
which creates a new directory
build. You can call this directory
anything you like, and you also put it anywhere you like, you just
need to specify the path to the BOUT++ source directory with the
-S argument. This makes it very easy to keep two build directories
alongside one another, one with a debug build and one optimised, for
After configuring the build directory, you can then compile BOUT++ with:
# Build the library $ cmake --build build # Build the library with 8 threads $ cmake --build build -j 8 # Build the "blob2d" example $ cmake --build build --target blob2d
By default, CMake will use
makefiles, and so it is possible to
also build BOUT++ with
make from the build directory – note that
you must still run
cmake once first to configure BOUT++:
$ cmake . -B build $ cd build $ make
You might see some instructions in the documentation using
– they should be run from the
You can see what build options are available with:
$ cmake . -B build -LH ... // Enable backtrace BOUT_ENABLE_BACKTRACE:BOOL=ON // Output coloring BOUT_ENABLE_COLOR:BOOL=ON // Enable OpenMP support BOUT_ENABLE_OPENMP:BOOL=OFF // Enable support for PETSc time solvers and inversions BOUT_USE_PETSC:BOOL=OFF ...
CMake uses the
-D<variable>=<choice> syntax to control these
variables. You can set
<package>_ROOT to guide CMake in finding
the various optional third-party packages (except for PETSc/SLEPc,
_DIR). Note that some packages have funny
captialisation, for example
-LH to see the
form that each package expects.
CMake understands the usual environment variables for setting the compiler, compiler/linking flags, as well as having built-in options to control them and things like static vs shared libraries, etc. See the CMake documentation for more infomation.
A more complicated CMake configuration command might look like:
$ CC=mpicc CXX=mpic++ cmake . -B build \ -DBOUT_USE_PETSC=ON -DPETSC_DIR=/path/to/petsc/ \ -DBOUT_USE_SLEPC=ON -DSLEPC_DIR=/path/to/slepc/ \ -DBOUT_USE_SUNDIALS=ON -DSUNDIALS_ROOT=/path/to/sundials \ -DBOUT_USE_NETCDF=ON -DNetCDF_ROOT=/path/to/netcdf \ -DBOUT_ENABLE_OPENMP=ON \ -DBOUT_ENABLE_SIGFPE=OFF \ -DCMAKE_BUILD_TYPE=Debug \ -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/path/to/install/BOUT++
If you wish to change the configuration after having built
it’s wise to delete the
CMakeCache.txt file in the build
directory. The equivalent of
make distclean with CMake is to just
delete the entire build directory and reconfigure.
If you need to debug a CMake build, you can see the compile and link
commands which are being issued by adding
--verbose to the build
$ cmake --build build --verbose
Common CMake Options¶
The default build configuration options try to be sensible for new users and developers, but there are a few you probably want to set manually for production runs or for debugging:
CMAKE_BUILD_TYPE: The default is
RelWithDebInfo, which builds an optimised executable with debug symbols included. Change this to
Releaseto remove the debug symbols, or
Debugfor an unoptimised build, but better debug experience
CHECK: This sets the level of internal runtime checking done in the BOUT++ library, and ranges from 0 to 4 (inclusive). By default, this is 2, which aims to be a balance between useful checks and speed. Set this to 0 for faster production runs, and to 4 for more in-depth (and slower) checking.
BOUT_UPDATE_GIT_SUBMODULE: This is on by default, and ensures that the bundled git submodules are up-to-date. You should turn this off if you are using system versions, or if you run into problems updating the submodules.
NetCDF_ROOT: NetCDF is one of the few required, non-bundled dependencies. If CMake is having trouble finding netCDF, or the correct version, you should set this variable to the installed location of the netCDF C library.
BOUT_TESTS: These two options are particularly useful for developers of the BOUT++ library, and for new users. You can turn them off to save some time configuring the library. By default, these are on, but the examples and tests are not built unless you specifically ask for them, using the targets
If you don’t have some dependencies installed, CMake can be used to download, configure and compile them alongside BOUT++.
For NetCDF, use
For SUNDIALS, use
-DBOUT_DOWNLOAD_SUNDIALS=ON. If using
ccmake this option
may not appear initially. This automatically sets
configures SUNDIALS to use MPI.
BOUT++ bundles some dependencies, currently mpark.variant, fmt and
googletest. If you wish to
use an existing installation of
mpark.variant, you can set
-DBOUT_USE_SYSTEM_MPARK_VARIANT=ON, and supply the installation
mpark_variant_ROOT via the command line or environment
variable if it is installed in a non standard loction. Similarly for
respectively. To turn off both, you can set
The recommended way to use
googletest is to compile it at the same
time as your project, therefore there is no option to use an external
installation for that.
As of BOUT++ 5.0,
./configure is no longer supported and will
be removed in 6.0. Please switch to using CMake to build BOUT++.
To compile BOUT++, you first need to configure it.
Go into the
BOUT-dev directory and run:
If this finishes by printing a summary, and paths for IDL, Python, and
Octave, then the libraries are set up and you can skip to the next
section. If you see a message
ERROR: FFTW not found. Required by BOUT++” then make sure
FFTW-3 is installed (See the previous section on installing dependencies ).
If FFTW-3 is installed in a non-standard location, you can specify the
directory with the
–with-fftw= option e.g:
$ ./configure --with-fftw=$HOME/local
Configure should now find FFTW, and search for the NetCDF library. If
configure finishes successfully, then skip to the next section, but if
you see a message
NetCDF support disabled then configure couldn’t
find the NetCDF library. This will be followed by a message
ERROR: At least one file format must be supported. Check that you have
NetCDF installed (See the previous section on installing dependencies ).
Like the FFTW-3 library, if NetCDF is installed in a non-standard location then
you can specify the directory with the
--with-netcdf= option e.g.:
$ ./configure --with-fftw=$HOME/local --with-netcdf=$HOME/local
which should now finish successfully, printing a summary of the configuration:
Configuration summary PETSc support: no SLEPc support: no IDA support: yes CVODE support: yes ARKODE support: yes NetCDF support: yes Parallel-NetCDF support: no
If not, see Advanced installation options for some things you can try to resolve common problems.
Natural Language Support¶
BOUT++ has support for languages other than English, using GNU gettext. If you are planning on installing BOUT++ (see Installing BOUT++ (experimental)) then this should work automatically, but if you will be running BOUT++ from the directory you downloaded it into, then configure with the option:
This will enable BOUT++ to find the translations. When
finishes, the configuration summary should contain a line like:
configure: Natural language support: yes (path: /home/user/BOUT-dev/locale)
path is the directory containing the translations.
See Natural language support for details of how to switch language when running BOUT++ simulations.
Configuring analysis routines¶
The BOUT++ installation comes with a set of useful routines which can be used to prepare inputs and analyse outputs. Most of this code is now in Python, though IDL was used for many years. Python is useful In particular because the test suite scripts and examples use Python, so to run these you’ll need python configured.
When the configure script finishes, it prints out the paths you need to get IDL, Python, and Octave analysis routines working. If you just want to compile BOUT++ then you can skip to the next section, but make a note of what configure printed out.
$ pip install --user boutdata
$ conda install boutdata
$ pip install --user numpy scipy matplotlib sympy netCDF4 h5py future importlib-metadata
$ conda install numpy scipy matplotlib sympy netcdf4 h5py future importlib-metadata
They may also be available from your Linux system’s package manager.
To use the versions of
boutdata provided by BOUT++, the path to
tools/pylib should be added to the
PYTHONPATH environment variable. This is not
necessary if you have installed the
boutdata packages. Instructions
for doing this are printed at the end of the configure script, for example:
Make sure that the tools/pylib directory is in your PYTHONPATH e.g. by adding to your ~/.bashrc file export PYTHONPATH=/home/ben/BOUT/tools/pylib/:$PYTHONPATH
To test if this command has worked, try running:
$ python -c "import boutdata"
If this doesn’t produce any error messages then Python is configured correctly.
boutdata are provided by BOUT++ as submodules, so versions
compatible with the checked out version of BOUT++ are downloaded into the
externalpackages directory. These are the versions used by the tests run by
check even if you have installed
boutdata on your system.
If you want to use IDL to analyse
BOUT++ outputs, then the
IDL_PATH environment variable should include the
tools/idllib/ subdirectory included with BOUT++.
The required command (for Bash) is printed at the end of the BOUT++ configuration:
$ export IDL_PATH=...
After running that command, check that
idl can find the analysis routines by running:
$ idl IDL> .r collect IDL> help, /source
You should see the function
COLLECT in the
directory. If not, something is wrong with your
On some machines, modifying
IDL_PATH causes problems, in which case
you can try modifying the path inside IDL by running:
IDL> !path = !path + ":/path/to/BOUT-dev/tools/idllib"
where you should use the full path. You can get this by going to the
tools/idllib directory and typing
pwd. Once this is done
you should be able to use
collect and other routines.
Once BOUT++ has been configured, you can compile the bulk of the code by
going to the
BOUT-dev directory (same as
configure) and running:
(on OS-X, FreeBSD, and AIX this should be
gmake). This should print
----- Compiling BOUT++ ----- CXX = mpicxx CFLAGS = -O -DCHECK=2 -DSIGHANDLE \ -DREVISION=13571f760cec446d907e1bbeb1d7a3b1c6e0212a \ -DNCDF -DBOUT_HAS_PVODE CHECKSUM = ff3fb702b13acc092613cfce3869b875 INCLUDE = -I../include Compiling field.cxx Compiling field2d.cxx
At the end of this, you should see a file
libbout++.a in the
lib/ subdirectory of the BOUT++ distribution. If you get an error,
please create an issue on Github
Which machine you’re compiling on
The output from make, including full error message
make.configfile in the BOUT++ root directory
Running the test suite¶
BOUT++ comes with three sets of test suites: unit tests, integrated tests and method of manufactured solutions (MMS) tests. The easiest way to run all of them is to simply do:
$ make check
from the top-level directory. Alternatively, if you just want to run one them individually, you can do:
$ make check-unit-tests $ make check-integrated-tests $ make check-mms-tests
Note: The integrated test suite currently uses the
command to launch the runs, so won’t work on machines which use a job
submission system like PBS or SGE.
These tests should all pass, but if not please create an issue on Github containing:
Which machine you’re running on
make.configfile in the BOUT++ root directory
run.log.*files in the directory of the test which failed
If the tests pass, congratulations! You have now got a working installation of BOUT++. Unless you want to use some experimental features of BOUT++, skip to section [sec-running] to start running the code.
Installing BOUT++ (experimental)¶
Most BOUT++ users install and develop their own copies in their home directory, so do not need to install BOUT++ to a system directory. As of version 4.1 (August 2017), it is possible to install BOUT++ but this is not widely used and so should be considered experimental.
After configuring and compiling BOUT++ as above, BOUT++ can be installed
to system directories by running as superuser or
$ sudo make install
Do not do this unless you know what you’re doing!
This will install the following files under
/usr/local/bin/bout-configA script which can be used to query BOUT++ configuration and compile codes with BOUT++.
/usr/local/include/bout++/...header files for BOUT++
/usr/local/lib/libbout++.aThe main BOUT++ library
/usr/local/lib/libpvpre.a, the PVODE library
/usr/local/share/bout++/pylib/...Python analysis routines
/usr/local/share/bout++/idllib/...IDL analysis routines
makefileconfiguration, used to compile many BOUT++ examples
To install BOUT++ under a different directory, use the
flag e.g. to install in your home directory:
$ make install prefix=$HOME/local/
You can also specify this prefix when configuring, in the usual way (see ./configure):
$ ./configure --prefix=$HOME/local/ $ make $ make install
More control over where files are installed is possible by passing options to
configure, following the GNU conventions:
bout-configwill be installed ( default
--includedir=sets where the
bout++/*.hxxheader files wil be installed (default
--libdir=sets where the
libpvpre.alibraries are installed (default
make.configare installed (default
After installing, that you can run
$ bout-config --all
which should print out the list of configuration settings which
bout-config can provide.
If this doesn’t work, check that the directory containing
bout-config is in your
The python and IDL analysis scripts can be configured using
bout-config rather than manually setting paths as in
Configuring analysis routines. Add this line to your startup file
export PYTHONPATH=`bout-config --python`:$PYTHONPATH
note the back ticks around
bout-config --python not
quotes. Similarly for IDL:
export IDL_PATH=`bout-config --idl`:'<IDL_DEFAULT>':$IDL_PATH
More details on using bout-config are in the section on makefiles.