{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "84445477",
   "metadata": {},
   "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": [
    "## 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(/opt/miniconda3/envs/ubermag-dev/bin/oommf)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "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(/opt/miniconda3/envs/ubermag-dev/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "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(/opt/miniconda3/envs/ubermag-dev/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "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": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running OOMMF (TclOOMMFRunner) [2021/08/12 10:53]... (0.0 s)\n",
      "OOMMF error:\n",
      "\tcommand: tclsh /path/to/oommf_tcl boxsi +fg macrospin.mif -exitondone 1\n",
      "\tstdout: \n",
      "\tstderr: couldn't read file \"/path/to/oommf_tcl\": no such file or directory\n",
      "\n",
      "\n",
      "\n",
      "Cannot find OOMMF.\n",
      "====================\n",
      "ValueError: new_runner=TclOOMMFRunner(/path/to/oommf_tcl) cannot be used.\n"
     ]
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "try:\n",
    "    oommfc.runner.runner = oommfc.oommf.TclOOMMFRunner('/path/to/oommf_tcl')\n",
    "except ValueError as e:\n",
    "    print('=' * 20)\n",
    "    print('ValueError:', e)"
   ]
  },
  {
   "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(/opt/miniconda3/envs/ubermag-dev/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "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": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OOMMF runner: ExeOOMMFRunner(/opt/miniconda3/envs/ubermag-dev/bin/oommf)\n",
       "runner is cached: True"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# NBVAL_IGNORE_OUTPUT\n",
    "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.8.10"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}