start_here.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building a model in Minnetonka"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import minnetonka as mn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A simple banking model, with savings, interest, and an interest rate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "with mn.model() as m:\n",
    "    mn.constant('Rate', 0.02)\n",
    "    mn.stock('Savings', lambda interest: interest, ('Interest',), 1000)\n",
    "    mn.variable('Interest', lambda savings, rate: savings * rate, 'Savings', 'Rate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's look at the initial amounts of **Savings** and **Interest**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variable values are accessed by indexing with an empty string, for reasons that will be made clear later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "20.0"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m['Interest']['']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance the model one year."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.step()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1020.0"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance it another year."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1040.4"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step()\n",
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance ten years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1268.2417945625452"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step(10)\n",
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Reset back to the beginning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.reset()\n",
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1020.0"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step()\n",
    "m['Savings']['']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Treatments and TIME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same model, but now with two treatments instead of the default (empty string) treatment. \n",
    "One treatment will be low interest, the other high interest. Also we will use a Python \n",
    "variables, so we can write **Savings** instead of **m['Savings']**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "with mn.model(treatments=['Low interest', 'High interest']) as m:\n",
    "    mn.constant('Rate', mn.PerTreatment({'Low interest': 0.01, 'High interest': 0.03}))\n",
    "    Savings = mn.stock('Savings', lambda interest: interest, ('Interest',), 1000)\n",
    "    mn.variable('Interest', lambda savings, rate: savings * rate, 'Savings', 'Rate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Initially **Savings** has the same amount in both treatments."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Variable amounts are accessed by indexing with the treatment name. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After a single year, **Savings** diverges."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1010.0"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step()\n",
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1030.0"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More divergence after a few more years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1051.0100501"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step(4)\n",
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1159.2740743"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Five years have passed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.TIME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After reset, TIME is 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.reset()\n",
    "m.TIME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Different timestep"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same model, but now with a time step that is less than one unit. The time unit remains a year, but the time step is a quarter. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also **Rate** and **Interest** are now Python variables, for easy access. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "with mn.model(treatments=['Low interest', 'High interest'], timestep=0.25) as m:\n",
    "    Rate = mn.constant('Rate', mn.PerTreatment({'Low interest': 0.01, 'High interest': 0.03}))\n",
    "    Savings = mn.stock('Savings', lambda interest: interest, ('Interest',), 1000)\n",
    "    Interest = mn.variable('Interest', lambda savings, rate: savings * rate, 'Savings', 'Rate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same at the start"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1000"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But step() now advances only a quarter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.25"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step()\n",
    "m.TIME"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1002.5"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1007.5"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that **Interest** is still defined on an annual basis, even though only 25% of the interest is applied each quarter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10.025"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Interest['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "30.224999999999998"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Interest['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance 20 time steps (5 years)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5.25"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step(20)\n",
    "m.TIME"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1053.8335170395887"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1169.8930233704716"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Same model, but a change outside the model logic."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Reset and advance two years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2.0"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.reset()\n",
    "m.step(8)\n",
    "m.TIME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The interest rate for the high interest treatment changes. This change is outside the logic of the model. Note that the change is only to the amount in a single treatment. The low interest treatment is unaffected."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In practice changes outside the logic of the model could be due to user intervention (as in this case), or could be due to real world integration, integration with other models, or integration with other software."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "Rate['High interest'] = 0.02"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Propagate the change through the rest of the model. As [explained in the documentation](https://bridgeland.github.io/minnetonka/index.html?highlight=recalculate#minnetonka.minnetonka.Model.recalculate), recalculation is only necessary when the amount of a variable (or constant or stock) is changed explicitly, outside of the model logic. The variables that depend on that changed variable will take amounts that do not reflect the changes, at least until the model is stepped. If that is not appropriate, a call to recalculate() will calculate new updated amounts for all those dependent variables."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.recalculate()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Interest** reflects the changed rate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "21.231976956365504"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Interest['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance 13 time steps (3.25 years), to the same time as before the reset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5.25"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.step(13)\n",
    "m.TIME"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After 5.25 years, **Savings** reflects the lowered rate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1132.711321538728"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The low interest treatment is unaffected by the change."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1053.8335170395887"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On reset, the high interest rate reverts to its model value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.03"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "m.reset()\n",
    "Rate['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Numpy arrays and other amounts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead of integers and floats, Minnetonka variables can take amounts that are any Python object, anything except a string. Let's try the same model with numpy arrays."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "initial_savings = np.array([1000, 2000, 3000, 4000])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Savings** takes an initial amount that is a numpy array. Note that the rest of the model is unchanged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [],
   "source": [
    "with mn.model(treatments=['Low interest', 'High interest'], timestep=0.25) as m:\n",
    "    Rate = mn.constant('Rate', mn.PerTreatment({'Low interest': 0.01, 'High interest': 0.03}))\n",
    "    Savings = mn.stock('Savings', lambda interest: interest, ('Interest',), initial_savings)\n",
    "    Interest = mn.variable('Interest', lambda savings, rate: savings * rate, 'Savings', 'Rate')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The amount of **Interest** is also a numpy array in this model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 30.,  60.,  90., 120.])"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Interest['High interest']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Advance 5 years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.step(20)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1051.20550328, 2102.41100656, 3153.61650984, 4204.82201313])"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['Low interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1161.1841423 , 2322.36828461, 3483.55242691, 4644.73656921])"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Savings['High interest']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "minnetonka_std_j",
   "language": "python",
   "name": "minnetonka_std_j"
  },
  "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}