technical-notes/3-2-equality-hashes-and-pickling.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Technical note: Equality checking, hashing, pickling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This document lays out some of the details of equality checking in Python, its application in hashing, and the related issue of pickling/unpickling (where unpickling should produce an object that's equal to the original).\n",
    "\n",
    "The goal is to explain, outline, and decide the decisions Myokit's design makes in this regard."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Equality (`==`) vs `is`\n",
    "\n",
    "`==` checks if two objects \"should be considered equal\", e.g. `myokit.Number(1) == myokit.Number(1)` should return `True`.\n",
    "\n",
    "`is` checks if two variables point to the same object, e.g. `x is x` should return `True`, as should `y = x; x is y`. \n",
    "\n",
    "### `id()` and `is`\n",
    "\n",
    "- The line `x is y` is equivalent to `id(x) == id(y)`. \n",
    "- An object's id is unique **during its lifetime**. In the standard implementation, the value returned by id(x) is `&x`, the memory address of x.\n",
    "\n",
    "This means that:\n",
    "- If you store an objects id **but not the object**, and then want to check if you're seeing the same object again, you can't use `id(x) == stored_id`.\n",
    "- **However**, in most cases you would simply store the object. As long as you have a reference to the object, its id will stay in use, and so `x is stored_x` will always return the correct answer.\n",
    "\n",
    "### Literals\n",
    "\n",
    "A line like `Number(1) is Number(1)` creates two new objects, each with their own id, and so returns False.\n",
    "It gets a bit more complicated for literals, as Python tends to cache them: a line `1 is 1` retrieves two references to the same object (I think -- there might be further tricky details to make things fast) and so can return True.\n",
    "\n",
    "This seems to hold for low ints and floats, but not for strings and very long integers:\n",
    "```\n",
    ">>> id(1)\n",
    "140111174779120\n",
    ">>> id(1)\n",
    "140111174779120\n",
    ">>> id(1)\n",
    "140111174779120\n",
    "\n",
    ">>> id(-1.234e-5)\n",
    "140111173736976\n",
    ">>> id(-1.234e-5)\n",
    "140111173736976\n",
    ">>> id(-1.234e-5)\n",
    "140111173736976\n",
    "```\n",
    "\n",
    "```\n",
    ">>> id('Hello')\n",
    "140111173489136\n",
    ">>> id('Hello')\n",
    "140111173489328\n",
    ">>> id('Hello')\n",
    "140111173489136\n",
    "```\n",
    "```\n",
    ">>> id(12345678901234567890)\n",
    "140111173472384\n",
    ">>> id(12345678901234567890)\n",
    "140111173473296\n",
    ">>> id(12345678901234567890)\n",
    "140111173472288\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Equality in user-defined classes\n",
    "\n",
    "The `==` operator on objects calls the class's `__eq__` method.\n",
    "\n",
    "The default `__eq__` method returns `True if self is other else NotImplemented`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "NotImplemented\n"
     ]
    }
   ],
   "source": [
    "class A:\n",
    "    pass\n",
    "\n",
    "x = A()\n",
    "y = A()\n",
    "print(x.__eq__(x))\n",
    "print(x.__eq__(y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But `==` converts this to `False`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "print(x == x)\n",
    "print(x == y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is also a `__ne__` method that's used by `!=`. The default here inverses the result of `__eq__` (again dealing with `NotImplemented`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "NotImplemented\n"
     ]
    }
   ],
   "source": [
    "print(x.__ne__(x))\n",
    "print(x.__ne__(y))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "print(x == x)\n",
    "print(x == y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is usually no need to override `__ne__`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `==` operator in Myokit\n",
    "The following objects define an `__eq__` method in Myokit:\n",
    "\n",
    "- Unit\n",
    "- Quantity\n",
    "- Expression (Defined in `Name` and in the base class `Expression`)\n",
    "- Equation\n",
    "- ~Model~\n",
    "- Protocol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Units\n",
    "Two units are considered equal if their internal representation (7 exponents and 1 multiplier) are equal, as judged by `myokit.float.eq`.\n",
    "\n",
    "As a simple example, we create two numbers that are within 1 operation's floating point error from each other. Python shows these are not equal. But `myokit.float.eq` thinks they are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "WARNING:myokit:Using development version of Myokit (1.33.2.dev).\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "0.9999999999999999\n",
      "False\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "import myokit\n",
    "\n",
    "x = 1\n",
    "y = (1 / 1.234) * 1.234\n",
    "print(x)\n",
    "print(y)\n",
    "print(x == y)\n",
    "print(myokit.float.eq(x, y))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we create units with these numbers, we can see Myokit (1) using float.eq to judge equality, (2) using `float.cround` (which is even more tolerant) for display:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[m]\n",
      "[m]\n",
      "False\n"
     ]
    }
   ],
   "source": [
    "a = myokit.units.m * x\n",
    "b = myokit.units.m * y\n",
    "print(a)\n",
    "print(b)\n",
    "print(a == b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can go further still, and see how \"closeness\" is not applied in equality checking (but is used in displaying units):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n",
      "0.9999999999999998\n",
      "False\n",
      "False\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "x = 1\n",
    "y = (1 / 1.234)**2 * 1.234 * 1.234\n",
    "print(x)\n",
    "print(y)\n",
    "print(x == y)\n",
    "print(myokit.float.eq(x, y))\n",
    "print(myokit.float.close(x, y))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[m]\n",
      "[m]\n",
      "[m]\n",
      "[m (0.9999999999999998)]\n",
      "False\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "a = myokit.units.m * x\n",
    "b = myokit.units.m * y\n",
    "print(str(a))\n",
    "print(str(b))\n",
    "print(repr(a))\n",
    "print(repr(b))\n",
    "print(a == b)\n",
    "print(myokit.Unit.close(a, b))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more on float equality, see the previous notebook.\n",
    "\n",
    "**Note** Units currently have a global \"preferred representation\" property. This might become a per-object one in [#783](https://github.com/myokit/myokit/issues/783), in which case we'd need to decide if two units with a different preferred representation are equal (I'd say yes).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quantities\n",
    "\n",
    "Two `myokit.Quantity` objects are considered equal if their value is equal (according to Python's `==` operator for floats) and if their units are equal (again with `==`, so using `myokit.Unit.__eq__`).\n",
    "\n",
    "**Note**: Quantities might be merged with myokit.Number in [#798](https://github.com/myokit/myokit/issues/798).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Expressions\n",
    "\n",
    "For most expressions there is an obvious and desirable `==` implementation, e.g.:\n",
    "\n",
    "`myokit.Number(1) == myokit.Number(1)`,\n",
    "\n",
    "and\n",
    "\n",
    "`myokit.Plus(myokit.Number(1), myokit.Number(2)) == myokit.Plus(myokit.Number(1), myokit.Number(2))`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Names refer to variables\n",
    "\n",
    "The tricky part is _names_, which refer to a `myokit.Variable` object.\n",
    "\n",
    "(Another detail is that, for debugging purposes (and just for messing around), Name expressions' value can be any other type of object. This lets you re-use Myokit's expressions system for other things. It's not an official part of the API though...)\n",
    "\n",
    "The `myokit.Variable` class does not implement an `__eq__` operator. So if you load a model twice, a variable in the first model won't equal the \"same\" variable in the second:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "import myokit\n",
    "\n",
    "m1 = myokit.load_model('example')\n",
    "m2 = myokit.load_model('example')\n",
    "print(m1.code() == m2.code())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "i1 = m1.get('ina.INa')\n",
    "i2 = m2.get('ina.INa')\n",
    "print(i1 == i2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "even though the variables have the same code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(i1.code() == i2.code())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Should** variables implement an equality check so that `i1 == i2` in the above? It sounds reasonable, but there are several issues:\n",
    "\n",
    "- The main part of a variable is its defining equation. But checking if equations are equal would mean checking that the expressions are equal, which would involve checking the equality of several other variables, etc. This would make `==` an expensive - and potentially circular - operation.\n",
    "- Should two variables be equal if their parent's are not?\n",
    "\n",
    "**Decision**: Variables will not implement the `==` operator. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Expressions are immutable\n",
    "\n",
    "Making expressions immutable has a big advantage: it means we can cache the result of expensive tree operations.\n",
    "\n",
    "This meshes well with the idea of matching variables in names with `is`: the id of an object is immutable in its lifetime, and since a Name stores a reference to the object as well, that means the id of a name's value is immutable while the expression is alive.\n",
    "\n",
    "Note that variables themselves are not immutable: a reference to a variable called `a.b` can become a reference to `c.d` if the variable `a.b` is renamed. But because it is still the same variable object that is pointed to the reference itself has not changed. This does mean that the output from `.code()` cannot be cached."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Avoiding repeated tree recursion\n",
    "\n",
    "To avoid repeated tree recursion when checking if expression equality, we can create a string reprensentation of the expression on the first call, and re-use it in subsequent calls.\n",
    "This is implemented in the method `Expression._polish` (and more specifically the various implementations of helper method `Expression._polishb`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Equations\n",
    "\n",
    "Two equations are equal if their LHS and RHS expressions are equal with `==`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Models\n",
    "\n",
    "#### `__eq__` was added, but removed again\n",
    "\n",
    "An equality operator was added to `Model` in [#548](https://github.com/myokit/myokit/pull/548), and used to check that models could be pickled and unpickled.\n",
    "\n",
    "In this implementation, models are considered equal if they are the same object, or if\n",
    "\n",
    "- they have the same set of reserved unames (which are strings, so immutable and easy to compare), and\n",
    "- they have the same set of reserved uname prefixes (strings again), and\n",
    "- the output of their `code()` methods is the same. \n",
    "\n",
    "There are some pros and cons:\n",
    "\n",
    "- **pro** If you load the same model twice, the models are equal\n",
    "- **pro** Once you modify a model, it's no longer equal\n",
    "- **con** The unames are not something many/most users will remember about (pro: but that perhaps means they won't use them?)\n",
    "- **con** Because components and variables don't have a custom `__eq__` (see above), two models that are \"considered equal\" will consists of components and variables that are *not* considered equal. Similarly, the expressions in one model won't equal the expressions in another.\n",
    "\n",
    "Because this situation doesn't make sense, the `__eq__` implementation for models was removed again in [#849](https://github.com/myokit/myokit/pull/849)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Protocols\n",
    "\n",
    "Two protocols are considered equal if they contain the same events. This is checked by comparing their `.code()` output (which is in a canonicalised form)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hashing and equality\n",
    "\n",
    "Sets and dicts in Python are based on hash maps. To make objects useable as keys in a dict or items in a set, they need to implement a *hash function* that returns an **almost unique integer**. Look-ups in a set or dict start with a quick hash-based jump, followed by a \"proper\" check using `==`. As a result, the `__hash__` and `__eq__` methods of user-defined classes have [some restrictions](https://docs.python.org/3/reference/datamodel.html#object.__hash__):\n",
    "\n",
    "**Default implementations use `is`**.\n",
    "By default, `x.__eq__(y)` returns `x == y`, and `hash(x)` returns \"an appropriate value such that x == y implies both that x is y and hash(x) == hash(y)\". So if you leave hash and eq alone, your objects will be hashable, but with an \"is\" condition. In other words, `myokit.Number(1) in {myokit.Number(1)}` will return False because `id(myokit.Number(1)) != id(myokit.Number(1))`.\n",
    "\n",
    "**Overriding eq removes default hash**.\n",
    "If you override `__eq__` but not `__hash__`, Python will automatically set `YourClass.__hash__ = None`, rendering your object unhashable.\n",
    "\n",
    "**Overriding hash? Then do eq too**.\n",
    "If you override `__hash__`, you **must** also provide an appropriate `__eq__` function.\n",
    "\n",
    "**Hashes must be immutable**.\n",
    "The value returned by an object's `__hash__` must stay the same during its lifetime. So in general you should only implement `__hash__` for immutable objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hashing\n",
    "\n",
    "The following Myokit classes override `__hash__`:\n",
    "\n",
    "- Unit\n",
    "- Quantity\n",
    "- Expression (the base class)\n",
    "- Equation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Units\n",
    "\n",
    "Units are immutable.\n",
    "\n",
    "Units return a hash made from the unit's string representation -- without lookup of a preferred global notation (which itself would involve a call to hash, leading to cycles). Rounding is used, making these hashes only unique-ish."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quantities\n",
    "\n",
    "Quantities are immutable. They use the hash of their string representation (which is set at construction time)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Expressions\n",
    "\n",
    "Expression are immutable. Expressions use the hash of `Expression._polish()`, which is an immutable string that uses object ids instead of variable names (see above)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Equations\n",
    "\n",
    "Equations are immutable. An equation's hash is made up of the hashes of its LHS and RHS expressions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pickling\n",
    "\n",
    "The following objects in Myokit have extra functions related to pickling & unpickling:\n",
    "\n",
    "- Model\n",
    "- Protocol\n",
    "- Simulation & LegacySimulation\n",
    "- ~Expressions~"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Models\n",
    "\n",
    "Use `__reduce__` and `__setstate__` to (1) store the model code (including whatever the current state vector is) and then create a new model with `myokit.parse_model` and (2) store and restore the list of unames and uname prefixes (sets of strings, so easily pickled)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Protocols\n",
    "\n",
    "Use `__reduce__` to store protocol code and restore it with `myokit.parse_protocol`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Simulation and LegacySimulation\n",
    "\n",
    "Use `__reduce__` and `__setstate__` to (1) store the arguments needed to create a new sim, by calling its constructor (and recompiling), and (2) storing and re-setting the simulation state. Step 1 involves pickling a model and a protocol."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ~Expressions~\n",
    "\n",
    "Unpickling an expression containing names can not be done without the context of a model. To make this clear, the `__reduce__` method has been overridden to produce an exception that suggests the following strategy instead:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ina.gNa * ina.m^3 * ina.h * ina.j * (membrane.V - ina.ENa) <class 'myokit._expressions.Multiply'>\n",
      "ina.gNa * ina.m^3 * ina.h * ina.j * (membrane.V - ina.ENa) <class 'str'>\n",
      "ina.gNa * ina.m^3 * ina.h * ina.j * (membrane.V - ina.ENa) <class 'myokit._expressions.Multiply'>\n"
     ]
    }
   ],
   "source": [
    "import myokit\n",
    "import pickle\n",
    "\n",
    "# Load a model\n",
    "model = myokit.load_model('example')\n",
    "\n",
    "# Get an expression containing Names\n",
    "expression = model.get('ina.INa').rhs()\n",
    "print(expression, type(expression))\n",
    "\n",
    "# To serialise, get a string representation of the expression (no longer linked to a model)\n",
    "string = expression.code()\n",
    "\n",
    "pickled_string = pickle.dumps(string)\n",
    "unpickled_string = pickle.loads(pickled_string)\n",
    "\n",
    "print(unpickled_string, type(unpickled_string))\n",
    "\n",
    "# After unpickling, create a new expression from the string (using the model as \"context\")\n",
    "new_expression = myokit.parse_expression(unpickled_string, context=model)\n",
    "print(new_expression, type(new_expression))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is obviously a bit much for an error message:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Individual myokit Expressions can not be pickled. Please try e.g. pickling a full model, or pickling the output of `Expression.code()` and following unpickling with a call to `myokit.parse_expression(unpickled_code, context=a_model)` to recreate the Expression.\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    pickle.dumps(expression)\n",
    "except Exception as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "so this will have to do."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}