<!-- markdownlint-disable MD033 -->

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

<!-- [](https://travis-ci.org/mumax/3) -->

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 (≤12.9) 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:<br>_{^{These instructions were made for Windows 10 and Ubuntu 22.04 (but should be applicable to all Debian systems). Your mileage may vary.}}

<details><summary><b><i>Install an NVIDIA driver</i></b></summary>

• Windows: Find a suitable driver here.

• Linux: Install the NVIDIA proprietary driver. <!-- version 440.44 recommended --><details><summary>Troubleshooting Linux →click here←</summary> 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. <br> 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      |
      +-----------------------------------------------------------------------------------------+
  

  </details>

• WSL: Follow the instructions and troubleshooting for Linux above. If you encounter issues/errors during that process, see the troubleshooting section below: <details><summary>Troubleshooting WSL →click here←</summary> 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.

  </details>

👉 Check NVIDIA driver installation with: nvidia-smi

</details> <details><summary><b><i>Install CUDA</i></b> &leq;12.9</summary>

• Windows: Download an installer from the CUDA website.
  • ⚠️ To be on the safe side, it is recommended to install CUDA in a directory without spaces, like 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

</details> <details><summary><b><i>Install Go</i></b></summary>

• 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).<br>Check with go env GOPATH. <details><summary><i>Click here to set GOPATH manually if it does not exist.</i></summary>

  • 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=$GOPATH/bin:$PATH
    

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

    </details>

👉 Check Go installation with: go version

</details> <details><summary><b><i>Install a C compiler</i></b></summary>

• 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 "Desktop development with C++" workload. After installing, check if the path to cl.exe was added to your PATH environment variable (i.e., check whether where cl.exe returns an appropriate path like C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.29.30133\bin\HostX64\x64). If not, add it manually.
  • 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.

</details> <details><summary>(Optional: <b><i>install git</i></b> to contribute to