mumax³

GPU-accelerated micromagnetism.

Paper on the design and verification of MuMax3: http://scitation.aip.org/content/aip/journal/adva/4/10/10.1063/1.4899186

Downloads and documentation

👉 Pre-compiled binaries, examples, and documentation are available on the mumax³ homepage.

Documentation of several tools, like mumax3-convert, is available here.

Contributing

Contributions are gratefully accepted. To contribute code, fork our GitHub repo and send a pull request.

Building from source

Consider downloading a pre-compiled mumax³ binary.

If you want to compile nevertheless, 4 essential components will be required to build mumax³: an NVIDIA driver, Go, CUDA and C.

If they are not yet present on your system: install them as detailed below.
If they are already installed: check if they work correctly by running the check for each component written below.

Click on the arrows below to expand the installation instructions:
_{^{These instructions were made for Windows 10 and Ubuntu 22.04 (but should be applicable to all Debian systems). Your mileage may vary.}}

Install an NVIDIA driver

Windows: Find a suitable driver here. Linux: Install the NVIDIA proprietary driver.

Troubleshooting Linux →click here←

If the following error occurs, proceed as follows:

batch
  nvidia-smi has failed because it couldn't communicate with the NVIDIA driver. Make sure that the latest NVIDIA driver is installed and running

1) Check for existing NVIDIA drivers.
Run dpkg -l | grep nvidia to see if any NVIDIA drivers are installed. If it shows some drivers, you might want to uninstall them before proceeding with the clean installation: sudo apt-get --purge remove '*nvidia*'
2) Update system packages. Make sure your system is up to date with sudo apt update and sudo apt upgrade.
3) (Optional but recommended:) Add the official NVIDIA PPA to ensure you have access to the latest NVIDIA drivers with sudo add-apt-repository ppa:graphics-drivers/ppa and sudo apt update.
4) Install the recommended driver. Ubuntu can automatically detect and recommend the right NVIDIA driver for your system with the command ubuntu-drivers devices. This will list the available drivers for your GPU and mark the recommended one.
To install the recommended NVIDIA driver, use sudo apt install nvidia-driver-<version> (replace <version> with the number of the recommended driver e.g., nvidia-driver-535)
5) Reboot your system with sudo reboot to apply the changes.

6) Verify the installation with nvidia-smi. This returns something like this, which shows you the driver version in the top center:

bash
      +-----------------------------------------------------------------------------------------+
      | NVIDIA-SMI 552.22                 Driver Version: 552.22         CUDA Version: 12.4     |
      |-----------------------------------------+------------------------+----------------------+
      | GPU  Name                     TCC/WDDM  | Bus-Id          Disp.A | Volatile Uncorr. ECC |
      | Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
      |                                         |                        |               MIG M. |
      |=========================================+========================+======================|
      |   0  NVIDIA GeForce RTX 3080 ...  WDDM  |   00000000:01:00.0 Off |                  N/A |
      | N/A   53C    P8              9W /  115W |     257MiB /   8192MiB |      0%      Default |
      |                                         |                        |                  N/A |
      +-----------------------------------------+------------------------+----------------------+

      +-----------------------------------------------------------------------------------------+
      | Processes:                                                                              |
      |  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
      |        ID   ID                                                               Usage      |
      |=========================================================================================|
      |    0   N/A  N/A     28420    C+G   ...Programs\Microsoft VS Code\Code.exe      N/A      |
      |    0   N/A  N/A     31888    C+G   ...les\Microsoft OneDrive\OneDrive.exe      N/A      |
      +-----------------------------------------------------------------------------------------+

WSL: Follow the instructions and troubleshooting for Linux above. If you encounter issues/errors during that process, see the troubleshooting section below:

Troubleshooting WSL →click here←

When using Windows Subsystem for Linux, your graphics card might not be recognized. If an error occurs after running the command:

1) If ubuntu-drivers devices throws the error Command 'ubuntu-drivers' not found: run the command sudo apt install ubuntu-drivers-common.
* ERROR:root:aplay command not found: run the command sudo apt install alsa-utils.
2) If sudo apt install nvidia-driver-<version> throws the error E: Unable to locate package nvidia-driver-<version>: run the commands

bash
        sudo apt install software-properties-gtk
        sudo add-apt-repository universe
        sudo add-apt-repository multiverse
        sudo apt update
        sudo apt install nvidia-driver-<version>

3) If nvidia-smi throws the error nvidia: command not found: the controller is probably not using the correct interface (sudo lshw -c display should show NVIDIA). To solve this, follow these steps. If a docker: permission denied error occurs: close and re-open WSL.

👉 Check NVIDIA driver installation with: nvidia-smi

Install CUDA - ⚠️Install in a directory without spaces⚠️

Windows: Download an installer from the CUDA website. ⚠️ To avoid common issues, the installation directory should not contain spaces. If possible, install in C:\cuda. Spaces should not cause issues when running deploy_windows.ps1, but this is not guaranteed.
Linux: Use sudo apt-get install nvidia-cuda-toolkit, or download an installer. Pick the default installation path. If this is not usr/local/cuda/, create a symlink to that path.
Match the version shown in your driver (see top right in nvidia-smi output). When prompted what to install: do not install the driver again, only the CUDA toolkit.
Add the CUDA bin and lib64 paths to your PATH and LD_LIBRARY_PATH by adding the following lines at the end of your shell profile file (usually .bashrc for Bash):

bash export PATH=/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

Apply the changes with source ~/.bashrc.

👉 Check CUDA installation with: nvcc --version*

Install Go

Download and install from the Go website. The GOPATH environment variable should have been set automatically (note: the folder it points to probably doesn’t exist yet).
Check with go env GOPATH.

Click here to set GOPATH manually if it does not exist.

On Windows: %USERPROFILE%/go is often used, e.g. C:/Users/<name>/go. See this guide if you are unfamiliar with environment variables. On Linux: ~/go is often used. Open or create the ~/.bashrc file and add the following lines.

bash
    export GOPATH=$HOME/go
    export PATH=$PATH:$GOPATH/bin

After editing the file, apply the changes by running source ~/.bashrc.

👉 Check Go installation with: go version

Install a C compiler

Linux: sudo apt-get install gcc ⚠️ each CUDA version has a maximum supported gcc version. This StackOverflow answer lists the maximum supported gcc version for each CUDA version. If necessary, use sudo apt-get install gcc-<min_version> instead, with the appropriate <min_version>.
Windows: CUDA does not support the gcc compiler on Windows, so download and install Visual Studio with the C/C++ extension pack. After installing, check if the path to cl.exe was added to your PATH environment variable. If not, add it manually, e.g. C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.29.30133\bin\HostX64\x64.
To compile Go, on the other hand, gcc is needed. Usually this is included in the Go installation, but if not it can be downloaded and installed from w64devkit.

👉 Check C installation with: gcc --version on Linux and where.exe cl.exe on Windows.*

(Optional: install git to contribute to mumax³)

_{^{If you don’t have a GitHub profile yet, make one here.}}

Windows: Download and install.
Linux: sudo apt install git
Set up your username in Git and setup an SSH key for your GitHub account.

👉 Check Git installation with: git –version*

(Optional: install gnuplot for pretty graphs)

Windows: Download) and install. Linux: sudo apt-get install gnuplot

👉 Check gnuplot installation with: gnuplot -V

With these tools installed, you can build mumax³ yourself.

Within your GOPATH folder, create the subfolders src/github.com/mumax.
Clone the GitHub repository by running git clone https://github.com/mumax/3.git in that newly created mumax folder.
- If you don’t have git, you can manually fetch the source here and unzip it into $GOPATH/src/github.com/mumax/3.
Initialize a Go module by moving to the newly created folder with cd 3/ and running go mod init github.com/mumax/3, followed by go mod tidy.
Query the compute capability of your GPU using the command nvidia-smi --query-gpu=compute_cap --format=csv. Based on this, set the environment variable CUDA_CC: if your compute capability is e.g., 8.9, then set the value CUDA_CC=89.
You can now compile mumax³ …
- … on Linux:
```
make realclean
make
```
  Your binary is now at $GOPATH/bin/mumax3.
  
  Note: each CUDA version has a maximum supported GCC version. If your default GCC compiler is too recent, you can use a different GCC compiler by instead running make NVCC_CCBIN=<path_to_gcc> where <path_to_gcc> is a less recent GCC. Check the version compatibility here. Alternatively, setting the NVCC_CCBIN environment variable achieves the same thing, allowing you to run make as usual.
- … on Windows:
  The Makefiles may experience issues with whitespaces. Instead, we recommend to use the deploy/deploy_windows.ps1 script: this generates the Windows executables for the mumax³ download page, but can also be used to build a single mumax³ executable for yourself by making the following adjustments:
  1) Change the $VS2022 variable to point to your Visual Studio executable. If you wish to compile for CUDA versions below v11.6, also set $VS2017. Example: if where.exe cl.exe returns foo\bar\cl.exe, then set $VS2022 = "foo\bar".
  2) (Not strictly necessary, but check this anyway) Throughout the file there are several switch ( $CUDA_VERSION ) blocks. If these do not address your installed CUDA version, add your version. Consult nearby comments when in doubt.
  
  Now you can compile mumax³ by opening Powershell in the /deploy directory and running
```
./deploy_windows.ps1 -CUDA_VERSIONS <your_cuda_version> -CUDA_CC <your_compute_capability>
```
  where e.g. <your_cuda_version> is 12.6 and <your_compute_capability> is 86, if you have installed CUDA v12.6 and your GPU’s compute capability is 8.6.
  
  Your executable will be created in the deploy/build directory.
Check installation with: which mumax3 on Linux or where.exe mumax3.exe on Windows, followed by mumax3 -test.
Troubleshooting: cuda.h or curand.h not found: →click here←

This usually means that the CGO_CFLAGS and CGO_LDFLAGS environment variables are not found or point to the wrong path. To fix this, either define them in the script you are using to build mumax³, or define them in the terminal before running the script.
- On Windows: say your CUDA is installed in %CUDA_PATH% (e.g. C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.1), then run these two lines in Powershell before running deploy_windows.ps1:
```
$env:CGO_CFLAGS = '-I "%CUDA_PATH%\include"'
$env:CGO_LDFLAGS = '-L "%CUDA_PATH%\lib\x64"'
```
Troubleshooting: mumax3.exe is not generated: →click here←

If, during the build process of mumax³, everything runs smoothly until you get the error that the mumax3.exe executable can not be found, try setting the CGO_ENABLED environment variable to 1 in your build script.

Troubleshooting: vcvars64.bat not found or could not initialise VC environment: →click here←

CUDA requires Visual Studio to compile, which tries to set various environment variables.
If Visual Studio fails to do so automatically, you can open a new shell, manually run the vcvars64.bat file there (the error message should contain the path to this Batch file), and then compile mumax using that shell.