{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "84445477",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "# Controlling the default runner\n",
    "In this tutorial we show how to globally controll the default runner. First we import `oommfc`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f384cdb0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import oommfc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "789382d8",
   "metadata": {},
   "source": [
    "`oommfc` has a special member `oommfc.runner` that provides information and control about the default runner and how it is chosen."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a59053aa",
   "metadata": {},
   "source": [
    "## Different runners\n",
    "\n",
    "There are three different runners that can be used:\n",
    "\n",
    "- Tcl runner: if we want to point ubermag to the particular `oommf.tcl` file\n",
    "- Exe runner: if we have OOMMF executable\n",
    "- Docker runner: if we want to run simulations inside Docker container\n",
    "\n",
    "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.\n",
    "\n",
    "**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.\n",
    "\n",
    "## The default runner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "f6729466",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: UNSET\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "246b8dc5",
   "metadata": {},
   "source": [
    "When we import `oommfc` the `OOMMF runner` is unset. The runner is chosen automatically when we first ask for ``oommfc.runner.runner``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "682473dd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner.runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e62dc12",
   "metadata": {},
   "source": [
    "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.\n",
    "\n",
    "A subsequent call to `oommfc.runner` shows the default runner."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "91414eda",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "93507e9a",
   "metadata": {},
   "source": [
    "We can also see, that the default runner is cached. This is controlled by:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "9291471b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner.cache_runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b0b1a64",
   "metadata": {},
   "source": [
    "## Defaults for the different runner types"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef957e9e",
   "metadata": {},
   "source": [
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "8d033198",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'OOMMFTCL'"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner.envvar"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "66b924aa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'oommf'"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner.oommf_exe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "74e4e5c3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'docker'"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner.docker_exe"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b4232ce",
   "metadata": {},
   "source": [
    "## Changing the default runner\n",
    "Our current runner is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "13f86b0b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df692e54",
   "metadata": {},
   "source": [
    "We can change the default runner by assigning an new `OOMMFRunner` object to `oommfc.runner.runner`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "d4ddc50b",
   "metadata": {
    "tags": [
     "raises-exception",
     "nbval-ignore-output"
    ]
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "couldn't read file \"/path/to/oommf_tcl\": no such file or directory\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running OOMMF (TclOOMMFRunner)[2023/10/18 12:33]... (0.0 s)\n",
      "Cannot find OOMMF.\n"
     ]
    },
    {
     "ename": "ValueError",
     "evalue": "runner=TclOOMMFRunner(/path/to/oommf_tcl) cannot be used.",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "Cell \u001b[0;32mIn[10], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[43moommfc\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrunner\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mrunner\u001b[49m \u001b[38;5;241m=\u001b[39m oommfc\u001b[38;5;241m.\u001b[39moommf\u001b[38;5;241m.\u001b[39mTclOOMMFRunner(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124m/path/to/oommf_tcl\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n",
      "File \u001b[0;32m~/repos/ubermag-devtools/repos/oommfc/oommfc/oommf/oommf.py:441\u001b[0m, in \u001b[0;36mRunner.runner\u001b[0;34m(self, runner)\u001b[0m\n\u001b[1;32m    438\u001b[0m \u001b[38;5;129m@runner\u001b[39m\u001b[38;5;241m.\u001b[39msetter\n\u001b[1;32m    439\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mrunner\u001b[39m(\u001b[38;5;28mself\u001b[39m, runner):\n\u001b[1;32m    440\u001b[0m     \u001b[38;5;28;01mif\u001b[39;00m runner\u001b[38;5;241m.\u001b[39mstatus \u001b[38;5;241m!=\u001b[39m \u001b[38;5;241m0\u001b[39m:\n\u001b[0;32m--> 441\u001b[0m         \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;132;01m{\u001b[39;00mrunner\u001b[38;5;132;01m=}\u001b[39;00m\u001b[38;5;124m cannot be used.\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m    442\u001b[0m     \u001b[38;5;28mself\u001b[39m\u001b[38;5;241m.\u001b[39m_runner \u001b[38;5;241m=\u001b[39m runner\n",
      "\u001b[0;31mValueError\u001b[0m: runner=TclOOMMFRunner(/path/to/oommf_tcl) cannot be used."
     ]
    }
   ],
   "source": [
    "oommfc.runner.runner = oommfc.oommf.TclOOMMFRunner(\"/path/to/oommf_tcl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f5ce4d13",
   "metadata": {},
   "source": [
    "In this example we (expectedly) get a `ValueError` because the path `/path/to/oommf_tcl` is invalid. The default runner has not been changed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "4c000fad",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5bea527b",
   "metadata": {},
   "source": [
    "## Going back to the default runner\n",
    "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:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "88cca55c",
   "metadata": {},
   "outputs": [],
   "source": [
    "oommfc.runner.autoselect_runner()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16879720",
   "metadata": {},
   "source": [
    "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: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "8c577eb3",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: ExeOOMMFRunner(/home/mlang/miniconda3/envs/ubermagdev310/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oommfc.runner"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}