State Machines in Python - Part 1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# State Machines in Python — Part 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing STMPY\n",
    "\n",
    "If you are running this notebook on Binder, STMPY should already be installed and you can jump to the next cell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you haven't installed stmpy, install it via the following command line commands:\n",
    "\n",
    "`python3 -m pip install --upgrade stmpy`\n",
    "\n",
    "Once you have done this  the command line, come back to this notebook and restart the kernel. (Grey menu bar at the top of this page, Kernel / Restart.) Then run the cell above again. Alternatively, you can also run the following cell which executes the command for you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python3 -m pip install --upgrade stmpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Checking the Installation\n",
    "\n",
    "Run the following cell by clicking `Shift` + `Enter`. It should output the current version of stmpy you have installed. If it prints `ModuleNotFoundError: No module named 'stmpy'` it means the Python interpreter does not have the STMPY library installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import stmpy\n",
    "\n",
    "print(\"STMPY Version installed: {}\".format(stmpy.__version__))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes, you have several Python interpreters on your machine. You can check on which one notebooks run with the code below. It will show you which Python interpreter is used. You should use the corresponding pip command to install the notebooks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "sys.executable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> If you have troubles getting notebooks with STMPY to run, take contact with us!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started - Step by Step\n",
    "\n",
    "*In the following we go through the setup of a single state machine, almost line by line so all details are covered. Make sure to execute every notebook cell with Python code in it, and make sure it executes correctly without error message. The next tutorials will present code in a more compact way. So if you feel confident in Python and think this goes to slow, there's hope. If you struggle a bit with Python, have an extra close look at the details.*\n",
    "\n",
    "Let's start with a simple state machine:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/ticktock.png\" style=\"max-width:100%;\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The state machine calls method `on_init()` when it starts, and goes into state `s_tick`. Then, it toggles back and forth to the `s_tock` state, controlled by timers. \n",
    "\n",
    "\n",
    "### Step 1: Python Class for Actions\n",
    "\n",
    "The actions in the transitions directly refer to Python methods `on_init()`, `on_tick()`, `on_tock()`. We declare them in a class `Tick`. This class works just as a warpper around these methods, and is a container for the variabes `ticks` and `tocks`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import clear_output\n",
    "\n",
    "\n",
    "class Tick:\n",
    "\n",
    "    def on_init(self):\n",
    "        clear_output(wait=True)\n",
    "        print('Init!')\n",
    "        # self.stm.diver.print_status()\n",
    "        self.ticks = 0\n",
    "        self.tocks = 0\n",
    "\n",
    "    def on_tick(self):\n",
    "        clear_output(wait=True)\n",
    "        print('Tiick! {}'.format(self.ticks))\n",
    "        print(self.stm.driver.print_status())\n",
    "        self.ticks = self.ticks + 1\n",
    "\n",
    "    def on_tock(self):\n",
    "        clear_output(wait=True)\n",
    "        print('Tooock! {}'.format(self.tocks))\n",
    "        print(self.stm.driver.print_status())\n",
    "        self.tocks = self.tocks + 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above you can see the three methods the state machine refers to. Within their body, they control simple counter variables `ticks` and `tocks`, but in principle you can do anything in these methods you like. \n",
    "\n",
    "We also need an instance of the Tick class for later:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tick = Tick()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Declaring Transitions and States\n",
    "\n",
    "**Transitions:** We declare the logic of the state machines by creating Python dictionaries for each of the transitions above. They declare source state, target state, trigger (unless its an initial transition), and effects. The effects declare a set of actions, separated by a `;`. Some of the actions refer to the methods defined in the class `Tick` from above, the others start timers directly. \n",
    "\n",
    "Note that the action `\"on_init; start_timer('tick', 300)\"` uses `'` to surround the string argument `tick` since it is declared within a Python string itself encalpsulated by `\"`. (The opposite, that means `'on_init; start_timer(\"tick\", 300)'` would also work.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# initial transition\n",
    "t0 = {\n",
    "    \"source\": \"initial\",\n",
    "    \"target\": \"s_tick\",\n",
    "    \"effect\": \"on_init; start_timer('tick', 300)\",\n",
    "}\n",
    "\n",
    "# transition s_tick ----> s_tock\n",
    "t1 = {\n",
    "    \"trigger\": \"tick\",\n",
    "    \"source\": \"s_tick\",\n",
    "    \"target\": \"s_tock\",\n",
    "    \"effect\": \"on_tick; start_timer('tock', 300)\",\n",
    "}\n",
    "\n",
    "# transition s_tock ----> s_tick\n",
    "t2 = {\n",
    "    \"trigger\": \"tock\",\n",
    "    \"source\": \"s_tock\",\n",
    "    \"target\": \"s_tick\",\n",
    "    \"effect\": \"on_tock; start_timer('tick', 300)\",\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, we don't have to declare anything special for the states, so they are only declared indirectly as values in the dictionary of the transitions. (In a later example we see how they can have entry and exit actions.)\n",
    "\n",
    "### Step 3: Creating the State Machine\n",
    "\n",
    "First, we need to import the Machine class. It contains code to execute the transitions and take care of all other stuff related to the state machine."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from stmpy import Machine"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We declare an instance for the machine, passing it the `tick` object from above and the transitions. It also gets a name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tick_tock_machine = Machine(transitions=[t0, t1, t2], obj=tick, name=\"tick_tock\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we need to do one more technical thing. Sometimes the Python class that implements our actions wants to send messages or manipulate timers, or get access to the STMPY API to do other things. For this, we use variable `stm` in the Tick class. We have to set the value of this variable now that we have created the corresponding machine. (For this example it is not necessary, but we want to introduce this step from the beginning.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tick.stm = tick_tock_machine"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Adding the State Machine to a Driver, and Start!\n",
    "\n",
    "The state machine is declared and ready, we only have to run it. State machines are not executed directly, but assigned to a **Driver**. One driver corresponds to one thread (or process) and can execute many state machines at the same time. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from stmpy import Driver\n",
    "\n",
    "driver = Driver()\n",
    "\n",
    "# add our state machine to the driver\n",
    "driver.add_machine(tick_tock_machine)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now the driver is declared. What's left is to start it. Since this machine is describing an endless loop, we limit the number of transitions the driver executes to 5. You will see that the notebook cell is active until the driver stops."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# start the driver, with limited number of transitions\n",
    "driver.start(max_transitions=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Execute all code cells above, step by step. The last one should start the state machine. You should now see that the state machine prints the following under the cell above:\n",
    "\n",
    "    Init!\n",
    "    Tick! 0\n",
    "    Tock! 0\n",
    "    Tick! 1\n",
    "    Tock! 1\n",
    "    \n",
    "You can also observe that the transitions are triggered by the timers, one every 1000 milliseconds."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Repetition\n",
    "\n",
    "- Transitions are declared as Python dictionaries.\n",
    "- Actions on transitions are declared in a special class for that state machine.\n",
    "- A `Machine` represents a state machine.\n",
    "- A `Driver` is needed to execute one (or several) state machines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "driver.stop()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "+------ Remaining steps: 023 ---------+\n",
    "| stm1: A     in state  s_01\n",
    "| timer t1: 245 seconds to go\n",
    "|       t2: idle\n",
    "| Queue head --> A (saved)\n",
    "|                B\n",
    "|                C\n",
    "|                ... (3 more)\n",
    "+---------------------------------------"
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}