Installation

All packages in Ubermag are available on both conda forge and PyPI. All packages can be installed independently using conda or pip. To simplify the installation for users doing micromagnetic simulations we provide a meta-package called ubermag. During installation of this packages all individual subpackages and additionally OOMMF are installed.

If you want to run simulations using mumax³ you have to install it manually and make sure that it can be found on the command line (i.e. adding it to the PATH variable).

To install any of the packages please follow the guidelines below and replace PACKAGE with one of the actual package names:

• ubermag (includes all packages listed below + OOMMF)

• discretisedfield

• micromagneticmodel

• micromagneticdata

• micromagnetictests

• oommfc

• ubermagtable

• ubermagdata

• ubermagutil

Standard installation – recommended

Installation environment

conda (recommended)

We recommend installation using conda package manager. If you do not already have it installed, download Anaconda Python 3.8+ for your operating system and follow the instructions to install it. After the installation is complete, in Terminal (Linux and MacOS) or in Anaconda Prompt (Windows), create a new environment and activate it.

Here, we show how to create and activate a new conda environment called ubermag_env. To use a different name, replace ubermag_env with your desired name.

$ conda create -n ubermag_env python=3.10
$ conda activate ubermag_env

pip + venv

If you do not want to use or cannot use conda you can also install ubermag via pip. You have to manually install Python and pip for your operating system.

First, we create a new virtual environment, here called ubermag_venv. To use a different name, replace ubermag_venv with your desired name. A new folder with the given environment name will be created in the current directory.

$ python3 -m venv ubermag_venv

To activate the environment on Windows, run:

$ ubermag_venv\Scripts\activate.bat

On Linux or MacOS, run:

$ source ubermag_venv/bin/activate

Installation

Now, you can install any PACKAGE by running the following command. We show the installation of the ubermag meta-package. To install individual packages, replace ubermag with the name of the package that you want to install.

conda (recommended)

$ conda install --channel conda-forge ubermag

pip + venv

$ pip install ubermag

If you want to use ubermag in a Jupyter notebook we provide a short summary of how to run Jupyter lab.

Installing a calculator

Ubermag can use different existing micromagnetic calculators (currently OOMMF and mumax³).

OOMMF

When you install ubermag using conda OOMMF will be automatically installed and ubermag (more precisely oommfc) knows how to find it. If you install ubermag using pip you have to install OOMMF manually and make sure that ubermag can find it. This also allows you to use a custom version of OOMMF. If you have no OOMMF installed but Docker is available ubermag will automatically attempt to download and use a Docker image that contains OOMMF.

For detailed instructions how to use a non-default OOMMF installation please refer to Controlling the default runner.

mumax³

Mumax³ does not directly come with ubermag and you have to install it manually (following the instructions on the mumax³ website). There are two different options how ubermag (more precisely mumax3c) can use your custom mumax³ installation.

• You can add the directory containing the mumax³ executable to your PATH variable. ubermag by default looks for an executable called mumax3 on PATH.

or

• You can change the name of the default executable in mumax3c when you import it as follows:

  Linux

  import mumax3c
  mumax3c.runner.mumax3_exe = '/full/path/to/mumax/executable'
  

  Windows

  import mumax3c
  mumax3c.runner.mumax3_exe = r'C:\full\path\to\mumax\executable.exe'
  

  A raw string is required to avoid that backslash + next character are interpreted as escape sequences in the Python string.

Testing

You can test the installation by running:

$ python -c "import ubermag; ubermag.test()"

Again, replace ubermag with the name of your package if you do not install the meta-package. If no errors are reported, the installation was successful.

Update

Every PACKAGE can be updated by running (if necessary replace ubermag with the name of your package):

conda (recommended)

$ conda update ubermag

pip + venv

$ pip install --upgrade ubermag

Advanced installation

To use ubermag for micromagnetic computations, you need to:

1. Install Ubermag.

2. Install a computational backend (such as OOMMF or mumax3).

3. Ensure Ubermag knows where to find the computational backend.

By installing Ubermag using conda, all three steps would be carried out automatically (for OOMMF). However, if for some reason you need more freedom in choosing the computational backend, please follow the steps explained subsequently for your operating system.

Windows

1. Before we install ubermag, we need to install Python3 Anaconda package manager. If you do not already have it installed, download Anaconda Python 3.8+ for your operating system and follow the instructions to install it.

2. Now we have everything required to install ubermag. Run in Command Prompt:

   $ pip install ubermag
   

3. To install OOMMF as a computational backend, first, you need to install tcl on your machine. To do this, download the .exe file from this link, appropriate for your operating system (32-bit or 64-bit). After the download is complete, run the downloaded file and follow the instructions to complete the installation.

4. Download the .zip file for the latest OOMMF version which is appropriate for your Windows OS (32-bit or 64-bit) from this link. After the download is complete, unzip (extract) it. Locate among the the unzipped files oommf.tcl and remember its location - we are going to need it in step 3.

   Note: Some OOMMF extensions are only available in the conda package, not the official release from the NIST website.

5. In order to help Ubermag find where oommf.tcl is, we need to set the value of environment variable OOMMFTCL. To do this, in Control Panel, select System -> Advanced system settings (tab Advanced) -> Environment variables. In User variables select New... and type OOMMFTCL for Variable name and C:\path\you\remembered\from\step2\oommf.tcl to Variable value.

MacOS

1. Before we install ubermag, we need to install Python3 Anaconda package manager. If you do not already have it installed, download Anaconda Python 3.8+ for your operating system and follow the instructions to install it.

2. Now we have everything required to install ubermag. Therefore, run in terminal:

   $ pip install ubermag
   

3. To compile OOMMF on MacOS, make sure you have XCode (from AppStore) and Git installed.

4. Clone the repository by typing

   $ git clone https://github.com/fangohr/oommf.git
   

5. To compile OOMMF, change the directory (cd oommf) and run:

   $ make build
   

   This command, apart from building OOMMF, will download and compile Dzyaloshinkii-Moriya extensions for different crystalographic classes. For more information, please refer to the OOMMF repository.

6. Finally, we have to set the environment variable OOMMFTCL, so that Ubermag knows where to find OOMMF. Consequently, in your home directory, add the path to oommf.tcl file to the end of the .bash_profile file. More specifically, the line at the end of your file should look like:

   export OOMMFTCL="/path/to/your/compiled/oommf.tcl"
   

   Please note that after editing .bash_profile file, you need to refresh your environment variables (source ~/.bashrc) or reopen the Terminal window.

Linux (Ubuntu)

1. To install Ubermag, we first have to make sure you have pip installed. Please note that this command requires root privileges (sudo).

   $ apt-get install python3-pip
   

   (Alternatively, you can use Anaconda Python3 distribution. If you do not already have it installed, download Anaconda Python 3.8+ for your operating system and follow the instructions to install it.)

2. Now, we can install ubermag

   $ python3 -m pip install ubermag
   

3. You can compile OOMMF on your machine by firstly installing the required packages. Please note that this command requires root privileges (sudo).

   $ apt-get install git tcl-dev tk-dev
   

4. Clone the repository:

   $ git clone https://github.com/fangohr/oommf.git
   

   (If you do not have git, you can install it using apt-get install git.)

5. To compile OOMMF, change the directory (cd oommf) and run:

   $ make build
   

   This command, apart from building OOMMF, will download and compile Dzyaloshinkii-Moriya extensions as well. For more information, please refer to the OOMMF reporsitory.

6. Finally, we have to set the environment variable OOMMFTCL, so that previously installed Ubermag knows where to find OOMMF. Consequently, in your home directory, add the path to oommf.tcl file to the end of the .bashrc file. More specifically, the line at the emd of your file should look like:

   export OOMMFTCL="/path/to/your/oommf.tcl"
   

   Please note that after editing .bash_profile file, you need to refresh your environment variables (source ~/.bashrc) or reopen the Terminal window.

Check the installation

To check if Ubermag can communicate with your installed OOMMF, you can use these commands in a Python prompt on any operating system:

import oommfc
oommfc.runner.runner.status

or from the command line:

python3 -c "import oommfc; oommfc.runner.runner.status"

This will attempt to run a small simulation using OOMMF.

How does Ubermag find OOMMF?

oommfc checks for OOMMF in the following steps until the first method is successful:

1. Is the OOMMFTCL variable set? If so, use this value to try to find OOMMF there.

2. Is OOMMF in the directory it should be in if both oommf and ubermag were installed using conda.

3. If docker is available and the docker deamon is running, then OOMMF is used in the Docker container. (The required docker image will be downloaded if necessary.)

Development installation

The above-explained installation methods are not suitable for the development of the ubermag package collection. Detailed guidelines and additional helper scripts to clone and install all packages in a way that is feasible for package development are given in our devtools repository. The information given there is only intended for people developing Ubermag or planning to contribute. For normal users we recommend following the steps under Standard installation – recommended.