# Introduction to OOMMF Python project

## OOMMF - the Object Oriented MicroMagnetic Framework¶

The Object Oriented MicroMagnetic Framework - widely known just as "OOMMF" - has been the most widely used open source micromagnetic modelling and simulation suite for over a decade; some evidence of this is visible in the list of papers that use and cite OOMMF [1].

Micromagnetism is the study of magnetisation at the micro and nanometre length scales, and is important for applications such as magnetic data storage and magnetic sensor devices, including recent research areas of spintronic and skyrmionics.

Micromagnetics uses (time dependent non-linear partial integro-) differential equations which generally have to be solved numerically. As the relevant physics involves multiple time and length scales, the computational problem is accordingly difficult.

## OOMMF User interface¶

The core of the OOMMF code is written in C++. Users can drive the simulation package through a Graphical User Interface (GUI) or through provision of Tcl files that define a simulation run. Within these files, the user can provide (Tcl) functions with agreed names that define complicated input parameters such as the initial magnetisation vector field. These functions will be called and evaluated by OOMMF at run time, for example to set the initial vector field.

CLOC provides the following breakdown of the OOMMF code (commit f792fbc48789b6e26acdeead7be114aab33e559d on https://github.com/fangohr/oommf), representing OOMMF version 1.2.a6):

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C++                            184          16926          24430         121062
Tcl/Tk                         242           5614          18367          50758
HTML                            76           2622           2309          22628
C/C++ Header                   174           4738           9801          18689
Perl                             7            674             96           1990
CSS                              1              5              5             20
C                                1              4             20             19
-------------------------------------------------------------------------------
SUM:                           685          30583          55028         215166
-------------------------------------------------------------------------------

## OpenDreamKit project¶

The Horizon 2020 research project OpenDreamKit - funded by the European Union - is bringing together developments in computational mathematics and computational workflow software and tools to make scientific Open Source research tools more efficient to use and develop further.

One research activity is the exploration of the Jupyter Notebook as an environment in which micromagnetic simulations can be set up, run, explored and analysed. The authors expect this to provide significant effectivity improvements to enable better science:

• a productivity improvement over the current use of OOMMF through bash scripts and subsequent separate workflow steps to analyse the data
• provide better reproducibility of computational exploration as all steps are contained in the same document
• faster (i.e. automatic) and complete documentation of such studies

As a first step towards this, we need to allow to execute micromagnetic simulation commands inside the notebook. While a member of the OpenDreamKit team has produced a TcL kernel for the Jupyter notebook [2], we believe that the vast majority of users will benefit more from a Python based interface to OOMMF.

Python has become a very widely used language in computational science and engineering that is recognised by scientists and engineers as easy to learn [3], allowing the use of in-built and a growing number of third-party scientific libraries. Increasingly, Python is also used for High Performance Computing - a recent HPC newsletter [4] reports that 6% of the codes they experienced as being Python based.

[2] Ryan Pepper, Thomas Kluyver, Hans Fangohr: Tcl kernel for Jupyter Notebook (2016)
[3] Hans Fangohr, A Comparison of C, Matlab and Python as Teaching Languages in Engineering Lecture Notes on Computational Science 3039, 1210-1217 (2004) pdf
[4] Newsletter June 2016 of Centre of Excellence for Performance Optimisation and Productivity (POP CoE) https://pop-coe.eu/news/newsletter/pop-newsletter-1-issue-june-2016 (2016)

## Python interface¶

There is a number of technical possibilities to provide a Python interface to OOMMF; including wrapping up of the C++ source code in some way (SWIG, Boost, Cython, ...) so that it can be interfaced and driven from a Python programme.

However, we have chosen a different interaction model to drive the OOMMF simulation package from Python. Our approach consists of providing a Python based (domain specific) language that allows to describe the micromagnetic model and the system that should be simulated. Users define the physics of the problem they want to simulate within this Python-based language. This includes the geometry of the system to compute, the material parameters and the discretisation of space (we restrict ourselves to a finite difference discretisation of space, which is the computational model that OOMMF provides).

When the user has completed defining the simulation problem, and needs to compute, for example, how the magnetisation changes as a function of time, the Python class generates a (Tcl-based) configuration file for OOMMF, calls the OOMMF executable (via the operating system), and extracts the computed data from the output file, before returning the output data to the user in a Python data structure.

We have chosen this design as the best solution to our requirements:

• by not attempting to drive the C++ code directly from Python, we do not need to re-implement parts of the substantial Tcl code base (see table above)
• by not interfacing directly to the C++ code, we do not need to interact with the complex platform and compiler specific build system of OOMMF, and the resulting variety in the C++ files.
• As we only interact with the OOMMF simulation through configuration files, we couple the Python layer and the OOMMF code as loosely as possible: the OOMMF simulation executable can be build using a different compiler than the one we are using for any interfacing; providing robustness across multiple operating systems and versions.

We note that a disadvantage of this approach is that some computation will have to be repeated: imagine that the user who drives OOMMF through the Python interface wants to set the magnetisation to some configuration, and then (i) compute the Demagnetisation field and store it, and then (ii) compute the exchange field and store it. Using the outlined configuration-file based interface to OOMMF, we will have to write two configuration files and call OOMMF twice to compute the required data. In particular, we will have to re-compute the demagnetisation tensor in the second call, even though it has been computed in the first call already. If we had chosen for a direct connection to the C++ routines, this might be avoidable (although at substantial costs to realise and maintain this). Time will tell in how far this affects users.

## The OOMMF calculator¶

The first step of the project is to develop a Pyton based interface for OOMMF, and the code under development is available at http://github.com/joommf/oommfc, together with documentation at http://oommfc.readthedocs.io . This part of the project is called the OOMMF Calculator, as it uses OOMMF as a "calculator" to solve the actual micromagnetic calculation, and to "drive" the system through phase space (see Figure below). This functionality is embedded in a micromagnetic description language which is embedded in Python.

Some of the details of this work are described in our preprint [5] and over time the documenation of the OOMMFC package will become more detailed. A good starting point are the micromagnetic standard problem examples in the manual, for example standard problem 3. At the bottom of this post, we show parts of the code computing the standard problem 3, demonstrating how the simulation description embedded in Python allows us to combine the micromagnetic calculator with tools from the scientific python stack, such as a root finding method from scipy.optimize.bisect to find the crossing of two lines, where for each step two different micromagnetic simulations have to be executed.

[5] Marijan Beg, Ryan A. Pepper, Hans Fangohr: User interfaces for computational science: a domain specific language for OOMMF embedded in Python https://arxiv.org/abs/1609.07432 (2016)

Figure: A schematic representation of our micromagnetic model. The system object is completely defined with: (i) mesh, (ii) Hamiltonian, (iii) dynamics equation, and (iv) magnetisation configuration. The driver is “driving” (moving) the system through phase space by changing its magnetisation.

## Outlook¶

In subsequent steps, we will develop micromagnetic data analysis tools embedded in the Jupyter Notebook, executable online hosted tutorials, and seek feedback from the community about the possibly improvements. The combination of Jupyter and OOMMF leads to the project title JOOMMF, and more details will be available at http://joommf.github.io

Figure: Parts of the standard problem 3 demonstration.