Controlling the default runner

In this tutorial we show how to globally controll the default runner. First we import oommfc.

import oommfc

oommfc has a special member oommfc.runner that provides information and control about the default runner and how it is chosen.

Different runners

There are three different runners that can be used:

• Tcl runner: if we want to point ubermag to the particular oommf.tcl file

• Exe runner: if we have OOMMF executable

• Docker runner: if we want to run simulations inside Docker container

This is helpful if you want to change OOMMF installation you want to use. This is in particular helpful if you want to run OOMMF inside Docker, which allows us to run simulations on a “small linux machine”, which is automatically pulled from the cloud, simulations are run inside, and in the end it is destroyed automatically. This all happens in the background and requires no special assistance from the user. In order to use Docker, we need to have it installed on our machine - you can download it here: https://www.docker.com/products/docker-desktop. The first time we run the simulation, it is going to take some time for docker to pull an image from the cloud, but after that, the image will be known by docker, so there will be no delays for any further runs.

IMPORTANT: On Windows, it is not possible to run multiple OOMMF simulations in parallel when using the tcl or exe runner. Use the docker runner if you want to run multiple simulations simultaneously.

The default runner

oommfc.runner

OOMMF runner: UNSET
runner is cached: True

When we import oommfc the OOMMF runner is unset. The runner is chosen automatically when we first ask for oommfc.runner.runner.

oommfc.runner.runner

ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)

Now we have a default runner. The same does also happen in the background when creating a driver object and calling its drive method without explicitly passing a runner.

A subsequent call to oommfc.runner shows the default runner.

oommfc.runner

OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)
runner is cached: True

We can also see, that the default runner is cached. This is controlled by:

oommfc.runner.cache_runner

True

Defaults for the different runner types

The default values for the envvar OOMMFTCL, the executable oommf, and the docker executable can also be controlled via the runner object. They default to:

oommfc.runner.envvar

'OOMMFTCL'

oommfc.runner.oommf_exe

'oommf'

oommfc.runner.docker_exe

'docker'

Changing the default runner

Our current runner is:

oommfc.runner

OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)
runner is cached: True

We can change the default runner by assigning an new OOMMFRunner object to oommfc.runner.runner.

oommfc.runner.runner = oommfc.oommf.TclOOMMFRunner("/path/to/oommf_tcl")

couldn't read file "/path/to/oommf_tcl": no such file or directory

Running OOMMF (TclOOMMFRunner)[2023/10/18 12:33]... (0.0 s)
Cannot find OOMMF.

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[10], line 1
----> 1 oommfc.runner.runner = oommfc.oommf.TclOOMMFRunner("/path/to/oommf_tcl")

File ~/repos/ubermag-devtools/repos/oommfc/oommfc/oommf/oommf.py:441, in Runner.runner(self, runner)
    438 @runner.setter
    439 def runner(self, runner):
    440     if runner.status != 0:
--> 441         raise ValueError(f"{runner=} cannot be used.")
    442     self._runner = runner

ValueError: runner=TclOOMMFRunner(/path/to/oommf_tcl) cannot be used.

In this example we (expectedly) get a ValueError because the path /path/to/oommf_tcl is invalid. The default runner has not been changed:

oommfc.runner

OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)
runner is cached: True

Going back to the default runner

We can change the default runner as demonstrated in the previous paragraph. If we later on decide that we want to go back to the default runner choosen by oommfc, we can do so by calling:

oommfc.runner.autoselect_runner()

This call searches for the best available runner (it does not rely on caching) and overwrites the default obtained via oommfc.runner.runner. We still have the same runner, because we actually never sucessfully changed a runner in this tutorial:

oommfc.runner

OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)
runner is cached: True