2. Installing NumBAT¶

This chapter provides instructions on installing NumBAT on each platform. Please email michael.steel@mq.edu.au to let us know of any difficulties you encounter, or suggestions for improvements to the install procedure on any platform, but especially for MacOS or Windows.

2.1. Information for all platforms¶

While NumBAT is developed on Linux, it can also be built on MacOS X as a native command-line application, and under Windows using a virtual machine running Linux.

In all cases, the current source code for NumBAT is hosted here on Github. Please always download the latest release from the github page.

2.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).

2.2. Installing on Linux¶

NumBAT has been developed and tested on Ubuntu 23.04 with the following package versions: Python 3.11.4, Numpy 1.24.2, Arpack-NG, Suitesparse 7.1.0, and Gmsh 4.8.4. NumBAT also depends on the BLAS and LAPACK libraries. We strongly recommend linking NumBAT against optimised versions, such as the MKL library provided in the free Intel OneAPI library.

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.

The code depends critically on matrix-vector operations provided by Lapack and Blas libraries. We strongly recommend using an optimised library such as the Intel OneAPI library (for Intel CPUs) or the AMD Optimizing CPU Libraries (AOCL) for AMD CPUs. The steps below demonstrate the Intel OneAPI approach.

Before installing, ensure your system is up to date
```
$ sudo apt-get update
$ sudo apt-get upgrade
```
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 virtualenv nbpy3
```
Activate the new python virtual environment
```
$ source ~/nbpy3/bin/activate
```

Install necessary python libraries

$ pip3 install numpy matplotlib scipy psutils

Create a working directory for your NumBAT work and move into it.
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
```
Open the file <NumBAT>/backend/fortran/Makefile in a text editor and check the settings associated with the variables PLAT that control the preferred math library. The default setting is to use the Intel OneAPI library which is the recommended configuration.
Now at last, we can build NumBAT by running the following in the root <NumBAT> directory.
```
$ make build
```
If this completes without error, you are ready to proceed to the next chapter to begin using NumBAT.
If you hit a compile error you can’t resolve, please get in touch at michael.steel@mq.edu.au.

2.2.1. Other build configurations¶

The Fortran components (NumBAT source code and libraries) have been successfully compiled with Intel’s ifortran as well as GCC’s open-source gfortran. In this documentation we use gfortran, but this can be easily adjusted in |NUMBAT|/backend/fortran/Makefile

2.2.2. Other build configurations¶

The Fortran components (NumBAT source code and libraries) have been successfully compiled with Intel’s ifortran as well as GCC’s open-source gfortran. In this documentation we use gfortran, but this can be easily adjusted in NumBAT/backend/fortran/Makefile

2.2.3. 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/

2.3. Installing on MacOS¶

NumBAT can also be installed on MacOS, though this is currently somewhat experimental and has only been performed on certain versions of MacOS. Any comments on difficulties and solutions will be appreciated.

The following steps have worked for us:

Open a terminal window on your desktop.
Ensure you have the Xcode Command Line Tools installed. This is the basic package for command line development on MacOS. Enter the following command and then follow the prompts.

$ xcode-select –install

Note that there is a different version of the Xcode tools for each major release of MacOS. If you have upgraded your OS, say from Ventura to Sonoma, you must install the corresponding version of Xcode.

If the installer says Xcode is installed but an upgrade exists, you almost certainly want to apply that upgrade.

Make a folder for NumBAT studies and clone the github repository:

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

If it is not already on your system, install the MacPorts package manager at this page.
Install the Gmsh mesh generation tool at this page. Just the main Gmsh installer is fine. The SDK and other features are not required.

Note: After the installer has run, you must move the Gmsh application into your Applications folder by dragging the Gmsh icon into Applications.
Install a current gcc (we used gcc):
```
$ sudo port install gcc13
```
Install the Lapack and Blas linear algebra libraries:
```
$ sudo port install lapack
```
Install the Arpack eigensolver:
```
$ sudo port install arpack
```
Install the SuiteSparse matrix algebra suite:
```
$ sudo port install suitesparse
```
Install a current python (we used python 3.12):

Use the standard installer at https://www.python.org/downloads/macos/.

(Note that this will install everything in /Library/Frameworks and not override the System python in /System/Library/Frameworks.)
Install python virtualenv package

$ cd /Library/Frameworks/Python.framework/Versions/3.12/bin/ $ ./python3.12 -m pip install –upgrade pip $ ./pip3 install virtualenv
Create a NumBAT-specific python virtual environment in ~/nbpy3

$ cd /Library/Frameworks/Python.framework/Versions/3.12/bin/ $ ./python3 -m virtualenv ~/nbpy3
Activate the new python virtual environment (note the leading fullstop)
```
$ . ~/nbpy3/bin/activate
```

Install necessary python libraries

$ pip3 install numpy matplotlib scipy psutil

Check that the python installs work and create a matplotlib .config directory:

$ python3.12
$ import matplotlib
$ import numpy
$ import scipy
$ import psutil

Install the NumBAT matplotlib style file:

$ mkdir -pR $HOME/.matplotlib/stylelib/
$ cp <NumBAT>/backend/|NUMBAT|style.mplstyle $HOME/.matplotlib/stylelib

Move to the NumBAT fortran directory:
```
$ cd backend/fortran
```
Open the file Makefile in your preferred text editor and edit the lines at the top of the file so that:
- The line PLAT=MacOS is active and the others are commented out with a leading # symbol.
- The value of MYPYENV matches the folder of your python virtual environment set up above.
- The value of PYVERMAJMIN and SYSTEMPYINC are set appropriately.
Now at last, we can build NumBAT
```
$ make
```
If this completes without error, you are ready to proceed to the next chapter to begin using NumBAT.
If you hit a compile error you can’t resolve, please get in touch at michael.steel@mq.edu.au.

2.4. Installing on Windows¶

The easiest way to run NumBAT on Windows is usually by installing Ubuntu as a virtual machine using either Microsoft Hyper-V or Oracle Virtual Box.

Then NumBAT can be installed using exactly the same procedure as described above for standard Linux installations. It is also possible to build NumBAT using the Windows Subsystem for Linux, but dealing with installing the additional required packages may be quite painful.

There is also an outdated Docker package for Windows that could be updated to support the current version of NumBAT if there is demand. Let us know.

To build the pdf documentation you are currently reading, use
```
$ make docs
```

Note however most of the figures will only be available after you have run all the example problems in the tutorial lit_ex and JOSAB_tutorial directories. This can be done by running make in each of those directories. Be aware that some of these problems are quite large and may require some time to complete depending on your computer’s performance.

2.5. Building the documentation¶

You can rebuild the documentation you are currently reading by moving into the <NumBAT>/docs directory and running either make html or make latexpdf.

In each case, the output is placed in the <NumBAT>/docs/build directory.