Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mumax/3

GPU-accelerated micromagnetic simulator
https://github.com/mumax/3

cuda finite-difference-time-domain go micromagnetics scientific-computing

Last synced: 8 months ago
JSON representation

GPU-accelerated micromagnetic simulator

Awesome Lists containing this project

README 

          



# mumax³



**GPU-accelerated micromagnetism.**



Paper on the design and verification of MuMax3: 



## Downloads and documentation



👉 Pre-compiled binaries, examples, and documentation are available on the [mumax³ homepage](https://mumax.github.io).



Documentation of several tools, like `mumax3-convert`, is available [here](https://godoc.org/github.com/mumax/3/cmd).



## 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](https://mumax.github.io/download.html).



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](https://www.nvidia.com/en-us/drivers/).

* **Linux**: [Install the NVIDIA proprietary driver](https://www.nvidia.com/en-us/drivers/unix/). 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-` (replace `` 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-` throws the error `E: Unable to locate package nvidia-driver-`: 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- 

        ```



    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](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-compute). 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](https://developer.nvidia.com/cuda-downloads).

  * ⚠️ **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](https://developer.nvidia.com/cuda-downloads).

  * 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](https://go.dev/doc/install).

* 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//go`. See [this guide](https://www.wikihow.com/Change-the-PATH-Environment-Variable-on-Windows) 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](https://stackoverflow.com/a/46380601) lists the maximum supported `gcc` version for each CUDA version. If necessary, use `sudo apt-get install gcc-` instead, with the appropriate ``.

* **Windows:**

  * CUDA does not support the `gcc` compiler on Windows, so download and install [Visual Studio](https://visualstudio.microsoft.com/downloads/) 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](https://github.com/skeeto/w64devkit/releases).



👉 *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](https://github.com/join).



* **Windows:** [Download](https://git-scm.com/downloads) and install.

  

* **Linux:** `sudo apt install git`

* [Set up your username in Git](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git) and [setup an SSH key for your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).



👉 *Check Git installation with: `git –version`*



(Optional: install gnuplot for pretty graphs)



* **Windows:** [Download]((http://www.gnuplot.info/download.html)) 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](https://github.com/mumax/3/releases) 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:**



    ```bash

    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=` where `` is a less recent GCC. [Check the version compatibility here](https://stackoverflow.com/a/46380601). Alternatively, setting the `NVCC_CCBIN` environment variable achieves the same thing, allowing you to run `make` as usual.



  * ... **on Windows:**

    The `Makefile`s 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](https://mumax.github.io/download.html), 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



    ```bat

    ./deploy_windows.ps1 -CUDA_VERSIONS  -CUDA_CC 

    ```



    where e.g. `` is `12.6` and `` 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`:



    ```powershell

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