Object Oriented MicroMagnetic Framework (OOMMF)

Description	Badge
Build (this repo) on 'latest Ubuntu' (Github workflow)
Build (this repo) on Ubuntu 22.04 in Docker container
Build (this repo) on OSX (Github workflow)
Release on conda-forge
oommf/oommf Docker image on Dockerhub
License

Contents

• 1   OOMMF Git repository
  • 1.1   About
  • 1.2   Version
  • 1.3   Clone and build OOMMF from source
  • 1.4   Smoke test
  • 1.5   Extensions
  • 1.6   Docker
    • 1.6.1   Getting the Docker image
    • 1.6.2   Using the Docker container
    • 1.6.3   Environment variables in the image
    • 1.6.4   No graphical user interface
  • 1.7   Conda
  • 1.8   Support
  • 1.9   License
  • 1.10   How to cite
  • 1.11   Acknowledgements
• 2   Information for Developers
  • 2.1   Updating to new OOMMF releases, or including new extensions
  • 2.2   Github workflows

1   OOMMF Git repository

1.1   About

This is a repository of the OOMMF software. It holds the OOMMF source files as distributed by NIST available here in the oommf subdirectory of this repository.

The intention is to

1. provide the OOMMF distribution files in a git repository for those who prefer to pull them via git
2. include additional user-contributed OOMMF extensions, which have not made it into the official distribution from NIST into this git repository. Those can be seen from the Makefile-update-oommf. See also Extensions below.

Compilation of OOMMF (for example by running make build) is expected to work on Linux and OS X.

1.2   Version

The current version of OOMMF code in this repository is the beta release of OOMMF 2.0 (20b0-1 20220930 b0).

You can check which version you have, by inspecting the content of the oommf-version file.

The history of all OOMMF versions hosted in this directory is provided in versionlog.txt.

1.3   Clone and build OOMMF from source

If you want to build OOMMF from source, clone the repository:

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

and build it

cd oommf
make build

1.4   Smoke test

As a quick test of the compilation, you can compute standard problems 3 and 4 as a test of your build by running:

make test-all

1.5   Extensions

A number of OOMMF extensions are included:

We provide Dzyaloshinskii-Moriya interaction extensions for three different crystallographic classes:

1. Cnv - interfacial DMI (repository),
2. T(O) - bulk DMI (repository),
3. D2d - antiskyrmion DMI (repository)

and

4. the OOMMF Magnetoelastic Extension Module (repository) from Yu Yahagi.

and

5. a generalised Zhang-Li extension supporting current in arbitrary direction (Anv_SpinTEvolve_3d, repository, starting with this commit on 2023-07-14)

1.6   Docker

In the docker directory we provide Dockerfile and Makefile for building and running Docker images containg OOMMF. In addition, we also provide pre-built images at DockerHub under the oommf/oommf repository (available container images). More information about Docker as well as on how to install it on your system can be found here. This Docker image is also used by Ubermag.

1.6.1   Getting the Docker image

If you want to build an image yourself, navigate to the docker directory and run

make build

This command builds the image under the oommf/oommf:latest name. Otherwise, you can obtain the most recent image by pulling it from DockerHub oommf/oommf repository

docker pull oommf/oommf

1.6.2   Using the Docker container

To run a container, navigate to docker directory and run

make run

Or you can type the full command yourself:

docker run --rm -ti -v `pwd`:/io oommf/oommf:latest

Once inside the container, the oommf.tcl file is in /usr/local/oommf/oommf/oommf.tcl. For convenience, we provide a shell script oommf in the search path (in /usr/local/bin). This can be used, for example:

oommfuser@715477218aac:/io# oommf +version
<7> oommf.tcl 2.0a1  info:
oommf.tcl 2.0a1

You can also add oommf commands to the command line from the host, for example:

docker run --rm -ti -v `pwd`:/io oommf/oommf:latest oommf +version
<7> oommf.tcl 2.0a1  info:
oommf.tcl 2.0a1

How can I exchange files between the host and the container?

• The current working directory in the host is shared with the /io directory in the container.
• This can be used to exchange mif files and data files with the container environment. For example:
  • create the mif file on the host
  • then run docker to tell OOMMF to process the mif file and create data files in the process
  • then analyse data files on the host.

1.6.3   Environment variables in the image

During the build process of the container, we also set an environment variable OOMMFTCL to point to the /usr/local/oommf/oommf/oommf.tcl file. This is used by Ubermag, for example, to find the oommf.tcl file.

There is also the OOMMF_ROOT variable which points to the base directory of the OOMMF sources (that’s currently /usr/local/oommf/oommf). It can be used, for example, to execute an OOMMF example:

oommf boxsi +fg $OOMMF_ROOT/app/oxs/examples/stdprob3.mif -exitondone 1

1.6.4   No graphical user interface

Please note that OOMMF’s graphical user interface (GUI) in Docker container cannot be used (without further work), but it can be used to execute .mif files, through boxsi, for example:

root@715477218aac:/io# oommf boxsi

1.7   Conda

We also made recipes for building Conda OOMMF package and they are available here. Information on how to install Conda on your system as well as how to use it can be found here. Installing oommf package using conda can be done by running

conda install -c conda-forge oommf

1.8   Support

For support on OOMMF itself, please refer to OOMMF’s web page. However, if you have any difficulties or problems in using any of the features we provide in this repository, you are welcome to raise an issue in our ubermag/help repository.

1.9   License

The License for the OOMMF code can be found here. If you use any of the following extensions (which do not come with the OOMMF code from NIST at the moment), please refer to the licenses in the corresponding repositories (Cnv, T(O), D2d, and magnetoelastic).

1.10   How to cite

• Information on how to cite the usage of OOMMF can be found here.

• If you want to acknowledge the packaging of OOMMF as a git repository, a Docker container, a conda-forge package or the use of Ubermag, please cite this paper:

  M. Beg, M. Lang and H. Fangohr, “Ubermag: Towards more effective micromagnetic workflows,” in IEEE Transactions on Magnetics, DOI: 10.1109/TMAG.2021.3078896 (2021)

  BibTeX snippet:

  @article{beg2021,
    author = {Beg, Marijan and Lang, Martin and Fangohr, Hans},
    journal = {IEEE Transactions on Magnetics},
    title = {Ubermag: Towards more effective micromagnetic workflows},
    year = {2021},
    volume = {},
    number = {},
    pages = {1-1},
    doi = {10.1109/TMAG.2021.3078896}
  }
  

• If you use any of the DMI extensions in your research, please refer to the “How to cite” section in the corresponding repositories for the particular crystallographic class (Cnv, T(O), or D2d).

1.11   Acknowledgements

The repository which holds the OOMMF source code was developed as a part of OpenDreamKit – Horizon 2020 European Research Infrastructure project (676541) and the EPSRC Programme grant on Skyrmionics (EP/N032128/1). Further thanks go to the University of Southampton and the Max Planck Institute for the Structure and Dynamics of Matter.

2   Information for Developers

This repository is providing a git repository of OOMMF source files and additional extensions (see above for details).

2.1   Updating to new OOMMF releases, or including new extensions

If a new OOMMF release (from NIST) should be included here, one should use the targets in the Makefile-update-oommf makefile (see comments in makefile). They will (in summary):

1. Using make -f Makefile-update-oommf fetch-oommf fetch new OOMMF sources from NIST. The Makefile will update the versionlog.txt and oommf-version files so that these reflect the new version automatically.
2. Using make -f Makefile-update-oommf fetch-all-extensions fetch extensions. The script clone-log-and-extract-src.py is used to copy the relevant files from each extension into the right place with the OOMMF directory structure (oommf/app/oxs/local/) into a dedicated subdirectory. The script will also add a NAME.log and NAME-HEAD.zip file for each extensions with name NAME into the relevant subdirectory. These files contain additional information about the extension (to provide better provenance and reproducibility).

The Makefile will need manual updating (for example new version number, ...) before being used in steps 1 and 2.

A recommendation is to:

• iterate through steps 1 and 2 until everything works automatically. You can use make -f Makefile-update-oommf clean to remove all downloaded and extracted files before starting over.
• then run make build to build the new OOMMF and make test-all to run standard problem 3 and 4 as a smoke test. Iterate 1 and 2 until the tests pass.

3. At that point, the modifications to Makefile-update-oommf should be committed to the repository (other modifications of scripts as well if any were necessary).
4. Remove all generated files (such as *.o) using make -f Makefile-update-oommf clean, remove all modifications using git checkout ., and repeat steps 1 and 2 (so that we only have those files in the directories that we like to commit to this repository as part of the new released).

Once this is done, one can

5. commit all of the retrieved (and newly created zip and log) files to this repository
6. make a new release for this repository (for example using Github GUI)
7. if desired, push a new docker image to docker hub (see docker/Makefile). Note that the current docker/Dockerfile uses the OOMMF version on the master branch of this repository: if a new OOMMF version is added through a pull request, this needs to be merged before the Dockerhub image is built.
8. if desired, update other packaging systems providing OOMMF, for example conda-forge, and spack (package.py)

This README will need updating (where specific version numbers are mentioned).

Even though steps 1 and 2 above only need to be exercised where there is a new OOMMF-version (or new extensions to include), we have a github workflow to run through the targets in this Makefile-update-oommf makefile periodically.

2.2   Github workflows

• Compile OOMMF on latest Ubuntu on Github’s systems:

• Compile OOMMF on Ubuntu 22:04 (in Docker container): This uses the Dockerfile to define the environment, in which the compilation is then executed via the Makefile.

• Compile OOMMF on latest OSX on Github's systems:

• Replay OOMMF upgrade procedure (see above):

• Building Dockerhub image used by Ubermag:

  This uses the docker/Dockerfile: compilation of OOMMF is carried out as part of the Dockerfile.