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.
-
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
-
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*'
-
Update system packages. Make sure your system is up to date with sudo apt update and sudo apt upgrade.
-
(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.
-
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)
-
Reboot your system with sudo reboot to apply the changes.
-
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:
-
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.
-
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>
-
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
- 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
- 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
- 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.
If you don't have a GitHub profile yet, make one here.
👉 Check Git installation with: git –version
- 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:
- 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".
- (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"'
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.
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.
