3.1. Installing on Linux

3.1.1. Install locations

There is no need to install NumBAT in a central location such as /usr/local/ or /opt/local/ though you may certainly choose to do so.

Here and throughout this documentation, we use the string <NumBAT> to indicate the root NumBAT install directory (e.g. /usr/local/NumBAT, /home/mike/NumBAT, /home/myuserid/research/NumBAT).

3.1.2. Requirements

NumBAT is developed and tested using relatively recent operating system, compiler and libraries. You should not need the very latest releases, but in general compilation will be smoother on an up-to-date system. In particular, we recommend using:

  • an OS release from 2023 or later (eg Ubuntu 24.04/24.10)

  • gcc compiler of version 13.0 or later

  • python 3.11 or later

NumBAT is currently developed and tested on Ubuntu 25.04 with the following package versions: Python 3.13, Numpy 2.0, Arpack-NG, Suitesparse 7.1.0, and Gmsh 4.8.4. NumBAT also depends on the BLAS linear algebra library. We strongly recommend linking NumBAT against an optimised version, such as the MKL library provided in the free Intel OneAPI library (for Intel CPUs) or the AMD Optimizing CPU Libraries (AOCL) for AMD CPUs. The steps below demonstrate the Intel OneAPI approach.

NumBAT has also been successfully installed by users on Debian and RedHat/Fedora, and with different versions of packages, but these installations have not been as thoroughly documented so may require user testing. In general, any relatively current Linux system should work without trouble.

NumBAT building and installation is easiest if you have root access, but it is not required. See the section below if you do not have root access (or the ability to run sudo) on your machine.

The following steps use package syntax for Ubuntu/Debian systems. For other Linux flavours, you may need to use different package manager syntax and/or slightly different package names.

3.1.3. Required libraries

  1. Before installing, ensure your system is up to date

    $ sudo apt-get update
$ sudo apt-get upgrade

  2. Install the required libraries using your distribution’s package manager.

    On Ubuntu, perform the following

    $ sudo apt-get install gcc gfortran make gmsh python3-venv python3-dev meson pkg-config ninja-build

$ sudo add-apt-repository universe

$ sudo apt-get install libarpack2-dev libparpack2-dev libatlas-base-dev libblas-dev liblapack-dev  libsuitesparse-dev

  3. If you wish to use the Intel OneAPI math libraries, you need both of the following:

    • Intel OneAPI Base Toolkit:

      This is the main Intel developer environment including C/C++ compiler and many high performance math libraries.

      Download and run the installer accepting all defaults.

    • Intel OneAPI HPC Toolkit

      This adds the Intel Fortran compiler amongst other HPC tools.

      Download and run the installer accepting all defaults.

  4. If you using the Intel OneAPI math libraries, you should add the library path /opt/intel/oneapi/<release>/lib to your LD_LIBRARY_PATH variable in one of your shell startup files (eg. ~/.bashrc). Replace <release> with the correct string 2024.1 or similar depending on your installed version of OneAPI.

3.1.4. Building NumBAT itself

  1. Create a python virtual environment for working with NumBAT. You can use any name and location for your tree. To specify a virtual environment tree called nbpy3 in your home directory, enter

    $ cd ~
$ python3 -m venv nbpy3

  2. Activate the new python virtual environment

    $ source ~/nbpy3/bin/activate

  3. Install necessary python libraries

    $ pip3 install numpy matplotlib scipy psutils

  4. Create a working directory for your NumBAT work and move into it. From now, we will refer to this location as <NumBAT>.

  5. To download the current version from the git repository and install any missing library dependencies, use

    $ git clone https://github.com/michaeljsteel/NumBAT.git
$ cd NumBAT

  6. Move to the backend\fortran directory.

    1. To build with the gcc compilers, run:

      $ make gcc

    2. To build with the Intel compilers, edit the file nb-linuxintel-native-file.ini adjusting the variables to point the correct location of the Intel compilers. Then run:

      $ make intel

  7. If all is well, this will run to completion. If you encounter errors, please check that all the instructions above have been followed accurately. If you are still stuck, see Troubleshooting Linux installs for further ideas.

  8. If you hit a compile error you can’t resolve, please see the instructions at Seeking help with building NumBAT on how to seek help.

  9. Once the build has apparently succeeded, it is time to test the installation with a short script that tests whether required applications and libraries can be found and loaded. Perform the following commands:

    $ cd <NumBAT>/backend
$ python ./nb_install_tester.py

  10. If this program runs without error, congratulations! You are now ready to proceed to the next chapter to begin using NumBAT

  11. Once again, if you run into trouble, please don’t hesitate to get in touch for help using the instructions at Seeking help with building NumBAT. Please do send all the requested information, as it usually allows us to solve your problem faster.

3.1.5. Using the Intel Fortran compiler

The default compiler for Linux is GCC’s gfortran.

It is also possible to build NumBAT with the ifx compiler from Intel’s free OneAPI HPC toolkit. You may find some modest performance improvements.

To use the Intel compiler,

  1. If you have not already done so, install the Intel OneAPI Base and HPC Toolkits as described above.

  2. Adjust your LD_LIBRARY_PATH variable in your ~/.bashrc or equivalent to include /opt/intel/oneapi/<release>/lib. (Replace <release> with the correct string 2024.1 or similar depending on your installed version of OneAPI.)

  3. In <NumBAT>/backend/fortran, repeat all the earlier instructions for the standard GCC build but rather than plain make gcc, please use:

    $ make intel

3.1.6. Installing without root access

Compiling and installing NumBAT itself does not rely on having root access to your machine. However, installing the supporting libraries such as SuiteSparse and Arpack is certainly simpler if you have root or the assistance of your system admin.

If this is not possible, you can certainly proceed by building and installing all the required libraries into your own tree within your home directory. It may be helpful to create a tree like the following so that the relevant paths mirror those of a system install

$HOME/
 |---my_sys/
      |---usr/
           |---include/
           |---lib/
           |---bin/

3.1.7. Troubleshooting Linux installs

Performing a full build of NumBAT and all its libraries from scratch is a non-trivial task and it’s possible you will hit a few stumbles. Here are a few traps to watch out for:

  1. Please ensure to use relatively recent libraries for all the Python components. This includes using

    • Python: 3.11 or later

    • matplotlib: 3.9.0 or later

    • scipy: 1.13.0 or later

    • numpy: 2.0 or later

  2. Be sure to follow the instructions above about setting up the virtual environment for NumBAT excusively. This will help prevent incompatible Python modules being added over time.

  3. If you encounter an error about “missing symbols” in the NumBAT fortran module, there are usually two possibilities:

    • A shared library (a file ending in .so) is not being loaded correctly because it can’t be found in the standard search path. To detect this, run ldd nb_fortran.so in the backend/fortran directory and look for any lines containing not found. (On MacOS, use otools -L nb_fortran.so instead of ldd.)

      You may need to add the directory containing the relevant libraries to your LD_LIBRARY_PATH in your shell setup files (eg. ~/.bashrc or equivalent).

    • You may have actually encountered a bug in the NumBAT build process. Contact us for assistance as described in the introduction.

  4. If NumBAT crashes during execution with a Segmentation fault, you have quite possibly found a bug that should be reported to us. Useful information about a crash can be obtained from the GNU debugger gdb as follows:

    1. Make sure that core dumps are enabled on your system. This article provides an excellent guide on how to do so.

    2. Ensure that gdb is installed.

    3. Rerun the script that causes the crash. You should now have a core dump in the directory determined in step 1.

    4. Execute gdb as follows:

      $ gdb <path_to_numbat_python_env>  <path_to_core file>

    5. In gdb, enter bt for backtrace and try to identify the point in the code at which the crash has occurred.