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:

  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:

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

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

    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.

    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.