3. 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.

3.1. Information for all platforms

While NumBAT is developed on Linux, it can also be built natively on both MacOS and Windows. The Linux builds can also be run under virtual machines on MacOS and Windows if desired.

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

You can now skip forward to the section for your operating system: Linux, MacOS or Windows.

3.2. Installing on Linux

3.2.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.2.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.2.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.2.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. If you wish to be able to rebuild the documentation, we need some additional modules

    $ pip3 install sphinx nbsphinx sphinx_subfigure sphinxcontrib-bibtex setuptools pandoc ipython pygments

    You may also need to install the main pandoc package for your distribution.

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

  6. 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

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

  8. 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 and MacOS installs for further ideas.

  9. 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.

  10. 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

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

  12. 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.2.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.2.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.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. We are keen to increase our support of the MacOS build. Any comments on difficulties and solutions will be appreciated, so please don’t hesitate to get in touch using the directions at Seeking help with building NumBAT.

The following steps have worked for us:

  1. Open a terminal window on your desktop.

  2. Ensure you have the Xcode Command Line Tools installed. This is the basic package for command line development on MacOS. If you do not or are not sure, 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.

  3. Make a folder for your NumBAT work in a suitable location in your folder tree. Then clone the github repository:

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

This new NumBAT folder location is referred to as <NumBAT> in the following.

  1. If it is not already on your system, install the MacPorts package manager using the appropriate installer for your version of MacOS at that page.

  2. Install the Gmsh mesh generation tool. 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.

  3. Install a current gcc (we used gcc13):

    $ sudo /opt/local/bin/port install gcc-devel

  4. Install the Lapack and Blas linear algebra libraries:

    $ sudo /opt/local/bin/port install lapack

  5. Install the Arpack eigensolver:

    $ sudo /opt/local/bin/port install arpack

  6. Install the SuiteSparse matrix algebra suite:

    $ sudo /opt/local/bin/port install suitesparse

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

  8. Install python virtualenv package

    $ cd /Library/Frameworks/Python.framework/Versions/3.12/bin/
$ ./python3.12 -m pip install --upgrade pip
$ ./pip3 install virtualenv

  9. Create a NumBAT-specific python virtual environment in ~/nbpy3

    $ cd /Library/Frameworks/Python.framework/Versions/3.12/bin/
$ ./python3 -m virtualenv ~/nbpy3

  10. Activate the new python virtual environment (note the leading fullstop)

    $ . ~/nbpy3/bin/activate

  11. Install necessary python libraries

    $ pip3 install numpy matplotlib scipy psutil meson ninja

  12. Check that the python installs work.

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

  13. Install the NumBAT matplotlib style file:

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

  14. Move to the NumBAT fortran directory:

    $ cd backend/fortran

  15. Move to the <NumBAT>/backend/fortran/ directory and open the file meson.options in a text editor. Check the values of the options in the MacOS section and change any of the paths in the value fields as required.

  16. To start the build, enter:

    $ make mac

  17. 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 and MacOS installs for further ideas.

  18. 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.

  19. 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

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

  21. 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.3.1. Troubleshooting Linux and MacOS 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. In general, the GCC build is more tested and forgiving than the build with the Intel compilers and we recommend the GCC option. However, we do recommend using the Intel OneAPI math libraries as described above. This is the easiest way to get very high performance LAPACK and BLAS libraries with a well-designed directory tree.

  4. 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.

      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.

  5. 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.

3.4. Installing on Windows

There are two methods for installing NumBAT on Windows. You can build the entire system from scratch, as with the Linux and MacOS installs, or you can use a pre-built installer available from the github page.

For both methods, there are some common steps, including setting up the python environment and installing the open-source GMsh tool. These commons steps are described first.

3.4.1. Common installation steps for both methods

Python installers can be downloaded from the Python website.

3.4.1.1. Setting up the NumBAT Python environment

NumBAT is entirely driven from Python, either as scripts or Jupyter notebooks.

You can use an existing Python installation if you have a sufficiently recent version (>3.11.0) installed, or download a new Python installer. Note that NumBAT is a self-contained tree and will not add any files to your Python installation.

Note: if you are using the pre-built |NUMBAT| installer, for binary compatibility you *must* use Python version 3.13 and numpy version 2.2.

  1. If you do not have a suitable current Python, download and run the installer for a recent version from the Python website.

By default, this will install Python in the directory %HOMEPATH%\AppData\Local\Programs\Python\<PythonVer>, say %HOMEPATH%\AppData\Local\Programs\Python\Python312.

  1. Create a python virtual environment for working with NumBAT.

    You can use any name and location for your environment.

To specify a virtual environment tree called nbpy3, open a command prompt (or your favourite Windows terminal app) from the Start Menu and enter

$ %HOMEPATH%\AppData\Local\Programs\Python\Python312\python.exe -m venv nbpy3

  1. Activate the new python virtual environment

    $ %HOMEPATH%\npby3\Scripts\activate

  2. Install the necessary python tools and libraries

    $ pip3 install numpy==1.26.4 matplotlib scipy psutil ninja meson==1.4.1

Note that at last check, the most recent meson (1.5.0) is broken and we specify the earlier 1.4.1 version.

Similarly we specify a version of numpy from the 1.26 series as the new 2.0 version is not yet supported by some other packages we use.

  1. Finally, we will also need the Gnu make tool. This can be installed by typing

    $ winget install ezwinports.make

and then starting a new terminal (so that the PATH variable is updated to find make.exe.)

  1. Now you can proceed to install NumBAT using either Method 1, building fully from source, or Method 2, using the pre-built installer from the github page.

3.4.2. Installing NumBAT Method 1: full build from source

The Windows version of NumBAT is built using the native Windows toolchain including Visual Studio and the Intel Fortran compiler. Since a standard Windows installation, is not set up as a development environment, there are a number of steps and tools required, but it should go relatively smoothly.

3.4.2.1. Windows build tools

The following tools are all free but will use several GB of disk space.

  • Visual Studio:

    This is the primary Microsoft development environment.

    To install the free Community 2022 edition, download the main installer and follow the instructions.

  • 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.

  • Git

    This is a source control that we use to download NumBAT and some other tools.

    Download and run the latest Git for Windows release, accepting all defaults.

    Some users may prefer to use a graphical interface such as GitHub Desktop. This is fine too.

  • CMake

    This is a cross-platform build tool we will need for building some of the libraries.

    Download and run the latest release accepting all defaults.

3.4.2.2. NumBAT code and libraries

We can now build the supporting libraries, and then NumBAT itself.

  1. We will need the Gnu make tool. This can be installed by typing

    $ winget install ezwinports.make

    and then starting a new terminal (so that the PATH variable is updated to find make.exe.)

  2. Choose a location for the base directory for building NumBAT and supporting libraries, say c:\Users\<myname>\numbat, which we will refer to as <NumBAT_BASE>.

  3. Use the Start Menu to open the Intel OneAPI Command Prompt for Intel 64 for Visual Studio 2022. This is simply a Windows terminal with some Intel compiler environment variables pre-defined.

  4. In the terminal window, change to the <NumBAT_BASE> directory, then execute the following commands:

    $ mkdir nb_releases
$ mkdir usr_local
$ mkdir usr_local\include
$ mkdir usr_local\lib
$ mkdir usr_local\packages
$ cd usr_local\packages
$ git clone https://github.com/opencollab/arpack-ng.git arpack-ng
$ git clone https://github.com/jlblancoc/suitesparse-metis-for-windows.git suitesparse-metis
$ cd ..\..\nb_releases
$ git clone https://github.com/michaeljsteel/NumBAT.git nb_latest

  5. Download the Windows build of Gmsh and unzip the tree into usr_local\packages\gmsh. The Gmsh executable should now be at <NumBAT>\usr_local\packages\gmsh\gmsh.exe.

  6. Your <NumBAT_BASE> tree should now look like this:

    %HOME%
    |---numbat
        |---nb_releases
        |---usr_local
            |---include
            |---lib
            |---packages
3.4.2.2.1. Building SuiteSparse

This library performs sparse matrix algebra, used in the eigensolving routines of NumBAT.

  1. In the Intel command terminal, cd to <NumBAT_BASE>\usr_local\packages\suitesparse-metis.

  2. Enter the following command. It may take a minute or two to complete:

    $ cmake -D WITH_MKL=ON -B build .

    Make sure to include the fullstop after build.

  3. If that completes correctly, use Windows Explorer to open <NumBAT_BASE>\usr_local\packages\suitesparse-metis\build\SuiteSparseProject.sln with Visual Studio 2022.

  4. In the pull-down menu in the ribbon, select the Release build. Then from the Build menu, select the Build Solution item to commence the build. This will take a couple of minutes.

  5. Return to the command terminal and cd to <NumBAT_BASE>\usr_local. Then execute the following commands:

    $ copy packages\suitesparse-metis\build\lib\Release\*.dll lib
$ copy packages\suitesparse-metis\build\lib\Release\*.lib lib
$ copy packages\suitesparse-metis\SuiteSparse\AMD\Include\*.h include
$ copy packages\suitesparse-metis\SuiteSparse\UMFPACK\Include\*.h include
$ copy packages\suitesparse-metis\SuiteSparse\SuiteSparse_config\*.h include
3.4.2.2.2. Building Arpack-ng

This library performs an iterative algorithm for finding matrix eigensolutions.

  1. In the Intel command terminal, cd to <NumBAT_BASE>\usr_local\packages\arpack-ng.

  2. Enter the following command. It may take a minute or two to complete:

    $ cmake -B build -T "fortran=ifx" -D CMAKE_BUILD_TYPE=Release -D BUILD_SHARED_LIBS=OFF .

    Note the final fullstop!

  3. If that completes correctly, use Windows Explorer to open <NumBAT_BASE>\usr_local\packages\arpack-ng\build\arpack.sln with Visual Studio 2022.

  4. In the pull-down menu in the ribbon, select the Release build. Then from the Build menu select the Build solution option. This will take a few minutes.

  5. Return to the command terminal and cd to <NumBAT_BASE>\usr_local. Then execute the following commands:

    $ copy packages\arpack-ng\build\Release\* lib
$ copy packages\arpack-ng\ICB\*.h include
3.4.2.2.3. Building NumBAT

At long last, we are ready to build NumBAT itself.

  1. Your command prompt needs to have your NumBAT python environment activated.

    If you have opened a new prompt since setting up the python environment, enter

    $ %HOMEPATH%\npby3\Scripts\activate

  2. We need two additional python modules to run the build process

    $ pip3 install ninja meson==1.4.1

    Note that at last check, the most recent meson (1.5.0) is broken and we specify the earlier 1.4.1 version.

  3. In your command prmopt, move to your root <NumBAT_BASE> directory and then to the NumBAT folder itself:

    $ cd <NumBAT_BASE>
$ cd nb_releases\nb_latest

    From this point, we refer to the current directory as <NumBAT>.

    In other words, <NumBAT> = <NumBAT_BASE>\nb_releases\nb_latest.

  4. Setup the environment variables for the Intel compiler:

    $  "c:\Program Files (x86)\Intel\oneAPI\setvars.bat"

  5. Move to the <NumBAT>\backend\fortran directory and open the file meson.options in a text editor. Check the values of the options in the Windows section, particularly the value for windows_dir_nb_usrlocal and change any of the paths in the value fields as required.

  6. To initiate the build, enter

    $ make win

    This should take 2 to 3 minutes.

  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 a Windows installation for further ideas.

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

  9. Copy the .dlls built earlier to this directory:

    $ copy ..\..\..\..\usr_local\lib\*.dll .

  10. Also, copy the following Intel oneAPI .dlls to this directory:

    $ copy "c:\Program Files (x86)\Intel\oneAPI\mkl\latest\bin\mkl_rt.2.dll" .
$ copy "c:\Program Files (x86)\Intel\oneAPI\mkl\latest\bin\mkl_intel_thread.2.dll" .
$ copy "c:\Program Files (x86)\Intel\oneAPI\compiler\latest\bin\svml_dispmd.dll" .
$ copy "c:\Program Files (x86)\Intel\oneAPI\compiler\latest\bin\libmmd.dll" .
$ copy "c:\Program Files (x86)\Intel\oneAPI\compiler\latest\bin\libifcoremd.dll" .
$ copy "c:\Program Files (x86)\Intel\oneAPI\compiler\latest\bin\libifportMD.dll" .

  11. At this point, we are ready to test the installation with a short script that checks whether required applications and libraries can be found and loaded. Perform the following commands:

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

  12. If this program runs without error, congratulations! You are now ready to proceed to the next chapter to begin using NumBAT. If not, please see the suggestions at Troubleshooting a Windows installation. But before moving, please read the following section on creating a specalised NumBAT command terminal.

  13. 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.4.2.3. Creating a self-contained command terminal

If you plan to build the fortran code frequently, both the python and Intel oneAPI paths need to be set up in your terminal. Doing this manually requires typing:

$ %HOMEPATH%\npby3\Scripts\activate
$ c:\Program Files (x86)\Intel\oneAPI\setvars.bat

This quickly becomes tedious. To automatically activate your python environment and ensure all other necessary paths are correctly setup, it is helpful to create a dedicated launcher for the desktop that executes the required commands on first opening the terminal.

Here is a procedure for doing this

  1. Copy the launcher file numbat_cmd.bat to your NumBAT root directory:

    $ copy <NumBAT>\share\numbat_cmd.bat <NumBAT_BASE>

  2. Create a desktop shortcut to the Windows command terminal by using File Explorer to open the folder c:\Windows\System32, typing cmd.exe in the search box at top right, and then right-clicking Send to Desktop.

  3. Right click on the new shortcut and open its Properties dialog.

  4. Select the General tab and change the name field at the top to NumBAT Terminal.

  5. Select the Shortcut tab and change the Target field to %windir%\System32\cmd.exe "/K" %HOMEPATH%\numbat\numbat_cmd.bat

  6. Click the Change Icon button and select the NumBAT icon at <NumBAT>\docs\source\numbat.ico.

3.4.3. Installing NumBAT Method 2: pre-built Windows installer

Note: The installer will allow you to run NumBAT problems and make changes to the code on the Python side only. You won’t be able to make changes to the Fortran finite element code. (For most people, this is completely fine.) The installer is not updated as frequently as the main source tree.

Note: the pre-built installer will only work with Python version 3.13. If you do not have this version installed, please follow the instructions for installing Python earlier in this section.

We will actually run two installers: one for the free GMsh mesh generation tool, and one for NumBAT itself.

  1. Choose a location for the base directory for building NumBAT and supporting libraries,

    say c:\Users\<myname>\numbat, which we will refer to as <NumBAT_BASE>.

  2. Use the Start Menu to open a Windows terminal.

  3. In the terminal window, change to the <NumBAT_BASE> directory, then execute the following commands:

    $ mkdir nb_releases
$ mkdir usr_local
$ mkdir usr_local\packages

  4. Download the Windows build of Gmsh and unzip the tree into usr_local\packages\gmsh. The Gmsh executable should now be at <NumBAT>\usr_local\packages\gmsh\gmsh.exe.

  5. Download the Windows installer for NumBAT from the NumBAT github page. The link to the installer can be found at the bottom of the Readme section and also under the Releases heading in the right-hand column of the page.

    Run the installer choosing an install directory in the <NumBAT_BASE>\nb_releases folder.

  6. In your Windows terminal, change directory to the newly installed NumBAT folder.

  7. Activate your python environment and then move to the NumBAT tutorials directory:

    $ %HOMEPATH%\npby3\Scripts\activate
$ cd tutorials

    Remember, you must activate a python environment that uses Python 3.13.

  8. You should now be able to run a NumBAT calculation:

    $ make tut01

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

    If not, please check the instructions above again, and if still stuck, please read the troubleshooting section to attempt to diagnose the problem. Then follow the instructions at Seeking help with building NumBAT to seek assistance.

3.4.4. Troubleshooting a Windows installation

  1. My build of NumBAT completes but the nb_install_tester.py program complains the NumBAT fortran nb_fortran.pyd dynamically linked library (DLL) can’t be loaded.

    This is usually due to another DLL required by NumBAT not being found, either because it is in an unexpected location or missing altogether. This can be a little painful to diagnose. The following procedure is relatively straightforward.

    1. Download the Dependencies tool available as a zip file install from github. This tool displays all the DLL dependencies of a given file and whether or not they have been located in the file system. Extract the zip file to a folder named dependencies in <NumBAT_BASE>\usr_local\packages.

    2. Now we can apply the tool to the NumBAT python dll.

    Start the DependenciesGui.exe tool:

    $ <NUMBAT_BASE>\usr_local\packages\dependencies\DependenciesGUI.exe

    Browse to your NumBAT folder and open backend\fortran\nb_fortran.pyd.

    Examine the output and note any red highlighted entries. These indicate required DLLs that have not been found. If one or more such lines appear, read through the install instructions again and ensure that any commands to copy DLLs to particular locations have been executed.

    1. Alternatively, you can try the command line version of this tool

      $ <NUMBAT_BASE>\usr_local\packages\dependencies\Dependencies.exe -depth 5 -modules nb_fortran.pyd

If you find a missing DLL by one of these methods, please let us know. It may suggest a problem with the pre-built installer or the documentation instructions.

3.4.5. Installing the Linux version via a Virtual Machine

Another way to run NumBAT on Windows or MacOS is by installing Ubuntu as a virtual machine using either Microsoft Hyper-V or Oracle Virtual Box, or a similar tool on MacOS.

Then NumBAT can be installed using exactly the same procedure as described above for standard Linux installations.

3.5. Building the documentation

If you should want to, 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.

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.

3.6. Seeking help with building NumBAT

If you are having trouble building NumBAT or are experiencing crashes, we will do our best to assist you.

Before writing for help (see contact details in Introduction to NumBAT), please do the following:

  1. Download the latest version of NumBAT from github and ensure the problem remains.

  2. If on Linux or MacOS, run the script ./backend/nb_runconfig_test.sh from the main NumBAT directory.

    This will create the file ./nb_buildconfig.txt in the main directory with useful details about your build configuration and environment.

    If on Windows, do the same using the file .\backend\nb_runconfig_test.bat instead.

  3. In your email, indicate the date on which you last downloaded NumBAT from github.

  4. Attach the nb_buildconfig.txt file.

  5. If the problem is a crash while running a NumBAT script, please attach the python script file and a description of how to observe the problem.

  6. If on Linux or MacOS, follow the instructions under Troubleshooting Linux and MacOS installs to generate a debugging trace with GDB and send a screen shot of the trace.