2-MultipleDispatch.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Preface: The most INSANE language composability showcase you will ever see 😮 😱 😲"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This workshop goes through Julia's core programming paradigm, **multiple dispatch**. It is arguably the reason Julia is able to overcome many difficulties plaguing other programming environments, and it is a prime reason of why Julia is a programming language most suitable for science.\n",
    "\n",
    "Let's activate the directory of the Julia Zero2Hero workshop as we will be using some external packages for this showcase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\u001b[32m\u001b[1m  Activating\u001b[22m\u001b[39m project at `c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop`\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[32m\u001b[1mStatus\u001b[22m\u001b[39m `C:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\Project.toml`\n",
      "  \u001b[90m[6e4b80f9] \u001b[39mBenchmarkTools v1.3.2\n",
      "  \u001b[90m[a134a8b2] \u001b[39mBlackBoxOptim v0.6.2\n",
      "  \u001b[90m[13f3f980] \u001b[39mCairoMakie v0.11.1\n",
      "  \u001b[90m[a93c6f00] \u001b[39mDataFrames v1.6.1\n",
      "  \u001b[90m[31c24e10] \u001b[39mDistributions v0.25.103\n",
      "  \u001b[90m[634d3b9d] \u001b[39mDrWatson v2.13.0\n",
      "  \u001b[90m[fa6b7ba4] \u001b[39mDualNumbers v0.6.8\n",
      "  \u001b[90m[61744808] \u001b[39mDynamicalSystems v3.2.3\n",
      "  \u001b[90m[0987c9cc] \u001b[39mMonteCarloMeasurements v1.1.6\n",
      "\u001b[32m⌃\u001b[39m \u001b[90m[1dea7af3] \u001b[39mOrdinaryDiffEq v6.59.2\n",
      "  \u001b[90m[1a8c2f83] \u001b[39mQuery v1.0.0\n",
      "  \u001b[90m[1e83bf80] \u001b[39mStaticArraysCore v1.4.2\n",
      "  \u001b[90m[0c5d862f] \u001b[39mSymbolics v5.10.0\n",
      "\u001b[91m→\u001b[39m \u001b[90m[1986cc42] \u001b[39mUnitful v1.19.0\n",
      "\u001b[36m\u001b[1mInfo\u001b[22m\u001b[39m Packages marked with \u001b[91m→\u001b[39m are not downloaded, use `instantiate` to download\n",
      "\u001b[36m\u001b[1mInfo\u001b[22m\u001b[39m Packages marked with \u001b[32m⌃\u001b[39m have new versions available and may be upgradable.\n"
     ]
    }
   ],
   "source": [
    "import Pkg\n",
    "Pkg.activate(@__DIR__)\n",
    "Pkg.status()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider the expression $f(x, y) = \\sin(xy)^2$, but in a context agnostic to what $x, y$ is. A Julia function for this is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "f (generic function with 1 method)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "f(x, y) = sin(x*y)^2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Julia, this function can be called with anything that supports the mathematical abstraction the function alludes to. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.4997597826618576e-32"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "f(1.0, π) # reals"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4×4 Matrix{Float64}:\n",
       " 0.201993  0.520487  0.158884  0.170447\n",
       " 0.163429  0.447944  0.136294  0.150966\n",
       " 0.148019  0.454487  0.137524  0.160479\n",
       " 0.247789  0.655772  0.199894  0.217503"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "f(rand(4,2), rand(2,4)) # matrices (sine of a matrix is well defined)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.00039994666951103004 + 0.003998933418663417ɛ"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using DualNumbers # numbers that carry a function derivative along them; used in automatic differentiation\n",
    "x = Dual(0.1, 0.5)\n",
    "y = Dual(0.2, 0)\n",
    "f(x, y) # returns a dual number (has numeric derivative)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.501648 ± 0.352 Particles{Float64, 2000}\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using MonteCarloMeasurements # numbers that actually represent a probability distribution\n",
    "using Distributions          # package offering probability distributions\n",
    "x = π ± 0.5 # normally distributed variable\n",
    "y = Particles(2000, Gumbel(π-0.5, 0.5)) # a different distribution\n",
    "z = f(x, y) # returns a probability distribution (monte carlo sampled particles)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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2y+99NJMvn2KEAhxEB1CO6S/qIxhSPqZHAAAwGU2b958xx13mKZ51llnLVu2rLKysqysbNGiRYcddlh3d3eivTao+fPnb9269cEHH6yoqAiHw5s2bTrrrLNEZOXKla+99lrvV5aVldXV1Y0ePTpxz16PO+6445xzzonFYtddd13P9g+tra2JxWBuuummiy++WETGjx//la98RUSKi4v71BCPx5csWSIiV199dWFhYc/jw4YNO/30003TXLVqVe/Xf/TRR2eeeebevXvXr19fXFz86U9/Oq3vl2sQCHEQq4zaYUj3WzI1CgAAPOvNN9+Mx+NHHHHE22+/PWfOnOOOO+6kk0669dZbf/GLX4jI1q1bDxw4MOhB3nvvvRdeeOGee+6ZOnVqQUHBjBkzli5dethhh4nI+++/3/uVb7/9tojMnDkzL++QRJOXl/fss88edthh27Zt+9WvfpV48NZbb62vr582bdpvfvObnldeeeWVIlJSUtLY2Nj7CKtWraqvr5eDM6K9zZo1S0Teeeed3g/ecsst4XB47dq1iWc9h0CIgwiEdhhSIGRqFAAAeNbu3btF5FOf+lRRUVHvx6+66qrFixcvXrw4nsYw1DnnnDNv3rzejxxzzDGnn366iDQ1NfV+fN26dSLy+c9/vv9BTjzxxMTqow888MCHH364bNmy5557rqCg4Lnnnhs1alTPyy677LLCwkLDMF599dXen/7888+LyEknnTRz5sw+R07sJLF27dqeRzo6Ov71r3/l5eVdfPHFM3pZv379oF+sS7DKKA5Kvz1lGBKJyLBhdlaTKwiEAABAD8cff7yIlJaWPvLIIzfffHNP427y5Mk333xzmgeZPXt2/wcPP/zw/g8m9nU4+uijkx7nRz/60WuvvfbOO+9cd911iVv+7r333jPPPLP3a4444ogLL7xwxYoVr7zySs/ugqFQKDGb2nutmh6J0/XeUqKzs/P73/9+/1f2ScVuRiDEQUNKI6EQgTAtBEIAAKCHG2+88dFHH21ra/vxj3/80EMPzZkz57zzzjv33HOPO+649A9y4oknpvnKxII0Rx55ZNJnfT7f008/fdppp23dulVEZs6ced999/V/2ZVXXrlixYrVq1e3tLSMHz9eRN54441AIODz+b73ve/1f33idIFAoLu7O7Hx4MSJE//85z+nWbM7MTKKg4Z0Axtb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gBqPPfbYV7/61Xg8ftbnd+7c+eCDD1577bVKqgL84PXXX7/hhhuKxeJdd931ox/9SHU5gKfK5fJXvvKVBx544KzPX3fddU8//fSGDRuUVAVUHYHQROPj49ddd93Q0FB9ff0tt9zygQ984MSJE0899VQ4HBaRxx9//Pbbb1ddI+CRPXv2vO9973McZ/HixX/1V3+1Y8eOZDL529/+9plnnhGRVatWHTlyZM2aNarLBBTIZDLXXXfdiRMnRIRACAN96Utf+v73vy8if/RHf/Tnf/7n69at++1vf/vkk0+KyHvf+96XX365ro6ldtABgdBEd9999/333y8iDz/88J133ln55PDw8PXXXz88PNzW1tbb29vU1KS0RsALlmVdd911HR0dK1eu3Lt371VXXXX6oV/84he7d+92HOfWW299+umnFRYJqPK5z33ukUceqXxMIIRpXnrppQ984AMi8tnPfvaRRx4JhUKVz3/ve9/78pe/LCKPPPLIHXfcobBCoFpYAG2cYrH4wx/+UERuu+2202lQRNrb2ys/7KPR6C9+8Qtl9QEeevXVVzs6OkTkG9/4xplpUEQ+9rGP3XXXXSLy3HPPFYtFNfUB6vzHf/zHI488snz58hUrVqiuBVCgsmn2mmuueeihh06nQRH50pe+VDlwobKQBNAAgdA4L7/8ciqVEpHPfe5zZz104403Ll26VESeffZZBZUBntu3b1/lg4997GPnPvrBD35QRIrFYmdnp6dlAaoNDAx88YtfFJEHH3zwkksuUV0O4LWxsbGXXnpJRO64447a2tqzHn300UefeOKJL3zhCwoqA1xAIDTOgQMHRKS2tvaGG24466H6+vrKK+DXXntNQWWA5yKRiIi0tLTMeDZAc3Nz5YNSqeRpWYBSlmXddtttU1NTn//85z/60Y+qLgdQ4De/+Y1t2yLyiU984txHr7322o9//OO7du3yvC7AFQRC41SOB2hvbz/9YvdM27ZtE5H+/v5yuex1ZYDn/umf/imVSo2MjMz46P/+7/+KSE1NzTve8Q5v6wJU+vu///tXX3316quv/va3v626FkCNysKQ1tbWtWvXisj4+PgLL7zw7LPPDg4Oqi4NqD4CoXEqr33b2tpmfHTdunUiUi6Xx8bGPC0LUKGxsXHJkiUzvjly4MCBH/zgByLyl3/5lyyZgzleeeWVf/zHf6yvr//3f//3xYsXqy4HUKOnp0dE1q5dOzo6etttt7W1td10000f+tCHLrvsstWrVz/00EOqCwSqiUBonEwmI2eshTvLokWLznwaYKYnn3zygx/8YC6XW7FixX333ae6HMAjiUTi9ttvtyzrvvvu27lzp+pyAGUSiYSI1NXVve997/vZz35WLpdXrFhReXNwbGzs85///Iw7z4GAIhAap3Je4vluzjn9+Xw+711NgG8cPXp0165du3fvTiQSy5Yte+6556688krVRQEe+cIXvjA0NPRnf/ZnX/va11TXAqhUeVv86NGjJ06c+PSnPz0wMDA+Pp5IJI4dO1a5i+KXv/zl6UtZgKAjEBqnMjdYKBRmfPR0Djw9VQgYYnJy8q//+q+vueaa5557TkRuueWWrq6ud7/73arrAjzy4IMP/uIXv1i+fPljjz125iH7gMk+/elPP/bYY5deemnlj5s3b37++ec3bdokIn/zN3+jtDSgagiExmlpaRGRZDI546OnP195GmCIZ599dvPmzd/97nfL5fL27dv/+7//+1e/+tX5ttoC+gmHw1/5yldE5Ec/+lF7e7vqcgDFTm+gPXfXQENDw1e/+lURGR0d5YwZ6IFAaJyNGzeKSDgcnvHR4eFhEVm8ePGqVas8LQtQ5wc/+MGHP/zhWCy2cuXKhx9++PDhwxwmDtOEw+FsNisin/zkJ5verre3V0R+/OMfV/74t3/7t6qLBVy3Zs0aEVm2bNnpucEzVY5klzcPIwWCbuaNZNDYli1bRGR8fDwajZ47AdLR0SEimzdvZr0QDPHEE098+ctfdhxn165dP/7xj3krBIY734YCy7IsyxKu5YQZNm/eLCLFYtFxnHNfEZ3+DMupoAcCoXFuvPHGygcvvPDCpz71qTMfyufze/bsEZGbbrpJQWWA57LZ7Be/+EXbtm+99dYnn3zyfIctAdrbunXriy++OONDt99+eyQS2bVrV+WkmQ0bNnhbGqDAn/zJn4hIJpPp7u6uvJN+pkOHDlU+2LFjh9eVAS7g1Y9xNm3atGPHjo6OjgceeOD2228/832vn/zkJ5U9hLt371ZXIOCdxx9/PJFINDQ0/PCHPyQNwmStra3vf//7Z3yocsZYW1vb+Z4A6Od973vfqlWrxsbGvvGNb/zyl78886FMJvPP//zPIrJ9+/alS5cqKhCoJl4Ameib3/zm7t279+3bd++99/7d3/1dbW2tiOzfv/+ee+4RkV27dnH9FAxR+TG/Zs2an//857M87VOf+hR30wOAOerq6u6555677777qaeeuvPOO7/97W9Xst+pU6fuuOOOwcHBUCj03e9+V3WZQHWEHMdRXQMU+OxnP/vYY4+JyPLly//v//2/x48fP3bsmIisW7fuwIED69atU10g4IWrrrrq1KlTF3zasWPHKvtJAANVvk3uuuuuH/3oR6prAbxTLpc/9KEP/c///I+I1NbWbt68OZvN9vX1VR79xje+ce4BpEBAccqooR566KF77723ubl5YmLi6aefrqTBm2++ee/evaRBGMKyrIGBAdVVAAD8qK6u7umnn/7qV7/a1NRkWVZXV1clDV5xxRW/+c1vSIPQCTOERkulUq+88kokEmltbd25c+eVV16puiIAAAAfSafTr7zySjQaXbly5TXXXHPZZZeprgioMgIhAAAAABiKJaMAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgKAIhAAAAABiKQAgAAAAAhiIQAgAAAIChCIQAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgKAIhAAAAABiKQAgAAAAAhiIQAgAAAIChCIQAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgqP8PwP4MPn2MiUwAAAAASUVORK5CYII=",
      "text/html": [
       "<img width=600 height=450 style='object-fit: contain;' src=\"data:image/png;base64, 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2y+99NJMvn2KEAhxEB1CO6S/qIxhSPqZHAAAwGU2b958xx13mKZ51llnLVu2rLKysqysbNGiRYcddlh3d3eivTao+fPnb9269cEHH6yoqAiHw5s2bTrrrLNEZOXKla+99lrvV5aVldXV1Y0ePTpxz16PO+6445xzzonFYtddd13P9g+tra2JxWBuuummiy++WETGjx//la98RUSKi4v71BCPx5csWSIiV199dWFhYc/jw4YNO/30003TXLVqVe/Xf/TRR2eeeebevXvXr19fXFz86U9/Oq3vl2sQCHEQq4zaYUj3WzI1CgAAPOvNN9+Mx+NHHHHE22+/PWfOnOOOO+6kk0669dZbf/GLX4jI1q1bDxw4MOhB3nvvvRdeeOGee+6ZOnVqQUHBjBkzli5dethhh4nI+++/3/uVb7/9tojMnDkzL++QRJOXl/fss88edthh27Zt+9WvfpV48NZbb62vr582bdpvfvObnldeeeWVIlJSUtLY2Nj7CKtWraqvr5eDM6K9zZo1S0Teeeed3g/ecsst4XB47dq1iWc9h0CIgwiEdhhSIGRqFAAAeNbu3btF5FOf+lRRUVHvx6+66qrFixcvXrw4nsYw1DnnnDNv3rzejxxzzDGnn366iDQ1NfV+fN26dSLy+c9/vv9BTjzxxMTqow888MCHH364bNmy5557rqCg4Lnnnhs1alTPyy677LLCwkLDMF599dXen/7888+LyEknnTRz5sw+R07sJLF27dqeRzo6Ov71r3/l5eVdfPHFM3pZv379oF+sS7DKKA5Kvz1lGBKJyLBhdlaTKwiEAABAD8cff7yIlJaWPvLIIzfffHNP427y5Mk333xzmgeZPXt2/wcPP/zw/g8m9nU4+uijkx7nRz/60WuvvfbOO+9cd911iVv+7r333jPPPLP3a4444ogLL7xwxYoVr7zySs/ugqFQKDGb2nutmh6J0/XeUqKzs/P73/9+/1f2ScVuRiDEQUNKI6EQgTAtBEIAAKCHG2+88dFHH21ra/vxj3/80EMPzZkz57zzzjv33HOPO+649A9y4oknpvnKxII0Rx55ZNJnfT7f008/fdppp23dulVEZs6ced999/V/2ZVXXrlixYrVq1e3tLSMHz9eRN54441AIODz+b73ve/1f33idIFAoLu7O7Hx4MSJE//85z+nWbM7MTKKg4Z0Axtb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gBqPPfbYV7/61Xg8ftbnd+7c+eCDD1577bVKqgL84PXXX7/hhhuKxeJdd931ox/9SHU5gKfK5fJXvvKVBx544KzPX3fddU8//fSGDRuUVAVUHYHQROPj49ddd93Q0FB9ff0tt9zygQ984MSJE0899VQ4HBaRxx9//Pbbb1ddI+CRPXv2vO9973McZ/HixX/1V3+1Y8eOZDL529/+9plnnhGRVatWHTlyZM2aNarLBBTIZDLXXXfdiRMnRIRACAN96Utf+v73vy8if/RHf/Tnf/7n69at++1vf/vkk0+KyHvf+96XX365ro6ldtABgdBEd9999/333y8iDz/88J133ln55PDw8PXXXz88PNzW1tbb29vU1KS0RsALlmVdd911HR0dK1eu3Lt371VXXXX6oV/84he7d+92HOfWW299+umnFRYJqPK5z33ukUceqXxMIIRpXnrppQ984AMi8tnPfvaRRx4JhUKVz3/ve9/78pe/LCKPPPLIHXfcobBCoFpYAG2cYrH4wx/+UERuu+2202lQRNrb2ys/7KPR6C9+8Qtl9QEeevXVVzs6OkTkG9/4xplpUEQ+9rGP3XXXXSLy3HPPFYtFNfUB6vzHf/zHI488snz58hUrVqiuBVCgsmn2mmuueeihh06nQRH50pe+VDlwobKQBNAAgdA4L7/8ciqVEpHPfe5zZz104403Ll26VESeffZZBZUBntu3b1/lg4997GPnPvrBD35QRIrFYmdnp6dlAaoNDAx88YtfFJEHH3zwkksuUV0O4LWxsbGXXnpJRO64447a2tqzHn300UefeOKJL3zhCwoqA1xAIDTOgQMHRKS2tvaGG24466H6+vrKK+DXXntNQWWA5yKRiIi0tLTMeDZAc3Nz5YNSqeRpWYBSlmXddtttU1NTn//85z/60Y+qLgdQ4De/+Y1t2yLyiU984txHr7322o9//OO7du3yvC7AFQRC41SOB2hvbz/9YvdM27ZtE5H+/v5yuex1ZYDn/umf/imVSo2MjMz46P/+7/+KSE1NzTve8Q5v6wJU+vu///tXX3316quv/va3v626FkCNysKQ1tbWtWvXisj4+PgLL7zw7LPPDg4Oqi4NqD4CoXEqr33b2tpmfHTdunUiUi6Xx8bGPC0LUKGxsXHJkiUzvjly4MCBH/zgByLyl3/5lyyZgzleeeWVf/zHf6yvr//3f//3xYsXqy4HUKOnp0dE1q5dOzo6etttt7W1td10000f+tCHLrvsstWrVz/00EOqCwSqiUBonEwmI2eshTvLokWLznwaYKYnn3zygx/8YC6XW7FixX333ae6HMAjiUTi9ttvtyzrvvvu27lzp+pyAGUSiYSI1NXVve997/vZz35WLpdXrFhReXNwbGzs85///Iw7z4GAIhAap3Je4vluzjn9+Xw+711NgG8cPXp0165du3fvTiQSy5Yte+6556688krVRQEe+cIXvjA0NPRnf/ZnX/va11TXAqhUeVv86NGjJ06c+PSnPz0wMDA+Pp5IJI4dO1a5i+KXv/zl6UtZgKAjEBqnMjdYKBRmfPR0Djw9VQgYYnJy8q//+q+vueaa5557TkRuueWWrq6ud7/73arrAjzy4IMP/uIXv1i+fPljjz125iH7gMk+/elPP/bYY5deemnlj5s3b37++ec3bdokIn/zN3+jtDSgagiExmlpaRGRZDI546OnP195GmCIZ599dvPmzd/97nfL5fL27dv/+7//+1e/+tX5ttoC+gmHw1/5yldE5Ec/+lF7e7vqcgDFTm+gPXfXQENDw1e/+lURGR0d5YwZ6IFAaJyNGzeKSDgcnvHR4eFhEVm8ePGqVas8LQtQ5wc/+MGHP/zhWCy2cuXKhx9++PDhwxwmDtOEw+FsNisin/zkJ5verre3V0R+/OMfV/74t3/7t6qLBVy3Zs0aEVm2bNnpucEzVY5klzcPIwWCbuaNZNDYli1bRGR8fDwajZ47AdLR0SEimzdvZr0QDPHEE098+ctfdhxn165dP/7xj3krBIY734YCy7IsyxKu5YQZNm/eLCLFYtFxnHNfEZ3+DMupoAcCoXFuvPHGygcvvPDCpz71qTMfyufze/bsEZGbbrpJQWWA57LZ7Be/+EXbtm+99dYnn3zyfIctAdrbunXriy++OONDt99+eyQS2bVrV+WkmQ0bNnhbGqDAn/zJn4hIJpPp7u6uvJN+pkOHDlU+2LFjh9eVAS7g1Y9xNm3atGPHjo6OjgceeOD2228/832vn/zkJ5U9hLt371ZXIOCdxx9/PJFINDQ0/PCHPyQNwmStra3vf//7Z3yocsZYW1vb+Z4A6Od973vfqlWrxsbGvvGNb/zyl78886FMJvPP//zPIrJ9+/alS5cqKhCoJl4Ameib3/zm7t279+3bd++99/7d3/1dbW2tiOzfv/+ee+4RkV27dnH9FAxR+TG/Zs2an//857M87VOf+hR30wOAOerq6u6555677777qaeeuvPOO7/97W9Xst+pU6fuuOOOwcHBUCj03e9+V3WZQHWEHMdRXQMU+OxnP/vYY4+JyPLly//v//2/x48fP3bsmIisW7fuwIED69atU10g4IWrrrrq1KlTF3zasWPHKvtJAANVvk3uuuuuH/3oR6prAbxTLpc/9KEP/c///I+I1NbWbt68OZvN9vX1VR79xje+ce4BpEBAccqooR566KF77723ubl5YmLi6aefrqTBm2++ee/evaRBGMKyrIGBAdVVAAD8qK6u7umnn/7qV7/a1NRkWVZXV1clDV5xxRW/+c1vSIPQCTOERkulUq+88kokEmltbd25c+eVV16puiIAAAAfSafTr7zySjQaXbly5TXXXHPZZZeprgioMgIhAAAAABiKJaMAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgKAIhAAAAABiKQAgAAAAAhiIQAgAAAIChCIQAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgKAIhAAAAABiKQAgAAAAAhiIQAgAAAIChCIQAAAAAYCgCIQAAAAAYikAIAAAAAIYiEAIAAACAoQiEAAAAAGAoAiEAAAAAGIpACAAAAACGIhACAAAAgKEIhAAAAABgqP8PwP4MPn2MiUwAAAAASUVORK5CYII=\"/>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# visualize it to make it clear that we are *effectively* performing\n",
    "# operations on probability distributions\n",
    "using CairoMakie\n",
    "fig, ax = density(x.particles; color = (\"black\", 0.5), label = \"x\")\n",
    "density!(y.particles; color = (\"blue\", 0.5), label = \"y\")\n",
    "density!(z.particles; color = (\"red\", 0.5), label = \"sin(xy)²\")\n",
    "axislegend()\n",
    "fig"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$$ \\begin{equation}\n",
       "2 y \\cos\\left( x y \\right) \\sin\\left( x y \\right)\n",
       "\\end{equation}\n",
       " $$"
      ],
      "text/plain": [
       "2y*cos(x*y)*sin(x*y)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using Symbolics # next-gen symbolic math library\n",
    "@variables x y # symbolic variables instead of real numbers\n",
    "expression = f(x, y) # returns a symbolic expression\n",
    "expand_derivatives(Differential(x)(expression)) # that can be used in symbolic algebra"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "_Huh, seems cool, but why does it matter...?_\n",
    "\n",
    "Well, think that you were using the `sin` function inside, well, let's say, a differential equation code. For example to solve the differential equation of the simple pendulum (in normalized units)\n",
    "$$\n",
    "\\begin{align}\n",
    "\\theta ' &= \\omega \\\\\n",
    "\\omega ' &= - \\sin(\\theta)\n",
    "\\end{align}\n",
    "$$\n",
    "we would write the simple code (unoptimized simplified example)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "retcode: Success\n",
       "Interpolation: 3rd order Hermite\n",
       "t: 2001-element Vector{Float64}:\n",
       "  0.0\n",
       "  0.01\n",
       "  0.02\n",
       "  0.03\n",
       "  0.04\n",
       "  0.05\n",
       "  0.060000000000000005\n",
       "  0.07\n",
       "  0.08\n",
       "  0.09\n",
       "  ⋮\n",
       " 19.920000000000314\n",
       " 19.930000000000316\n",
       " 19.940000000000317\n",
       " 19.95000000000032\n",
       " 19.96000000000032\n",
       " 19.970000000000322\n",
       " 19.980000000000324\n",
       " 19.990000000000325\n",
       " 20.0\n",
       "u: 2001-element Vector{Vector{Float64}}:\n",
       " [0.0, 1.0471975511965976]\n",
       " [0.010471975511965976, 1.0471975511965976]\n",
       " [0.020943951023931952, 1.0470928333554352]\n",
       " [0.031414879357486304, 1.0468834091566017]\n",
       " [0.04188371344905232, 1.0465693120324375]\n",
       " [0.05234940656937669, 1.046150597344396]\n",
       " [0.06281091254282066, 1.0456273423483986]\n",
       " [0.07326718596630465, 1.0449996461453193]\n",
       " [0.08371718242775784, 1.0442676296166633]\n",
       " [0.09415985872392447, 1.043431435345513]\n",
       " ⋮\n",
       " [-0.6752209213516657, 0.9208694250633547]\n",
       " [-0.6660122271010321, 0.9271201228264722]\n",
       " [-0.6567410258727674, 0.9332986763761494]\n",
       " [-0.6474080391090059, 0.9394040667397529]\n",
       " [-0.6380139984416083, 0.945435276310509]\n",
       " [-0.6285596456785032, 0.9513912893230593]\n",
       " [-0.6190457327852726, 0.9572710923361132]\n",
       " [-0.6094730218619115, 0.9630736747218571]\n",
       " [-0.5998422851150063, 0.9687980291615688]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using OrdinaryDiffEq # for solving ODEs\n",
    "pendulum(u, p, t) = [u[2], -sin(u[1])] # return the derivative given state, parameters, time\n",
    "u0 = [0, π/3] # initial condition for solving the ODE\n",
    "tspan = (0.0, 20.0) # timespan to solve in\n",
    "prob = ODEProblem(pendulum, u0, tspan)\n",
    "sol = solve(prob, Euler(); dt = 0.01)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What would happen if for the initial state we used a dual number (which would enable automatic differentiation to run through our differential equation solving)?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-element Vector{Vector{Dual128}}:\n",
       " [0.0 + 0.0ɛ, 1.0471975511965976 + 0.2ɛ]\n",
       " [0.010471975511965976 + 0.002ɛ, 1.0471975511965976 + 0.2ɛ]\n",
       " [0.020943951023931952 + 0.004ɛ, 1.0470928333554352 + 0.1999800010966127ɛ]\n",
       " [0.031414879357486304 + 0.005999800010966127ɛ, 1.0468834091566017 + 0.1999400098692737ɛ]\n",
       " [0.04188371344905232 + 0.007999200109658863ɛ, 1.0465693120324375 + 0.19988004147258182ɛ]\n",
       " [0.05234940656937669 + 0.009998000524384681ɛ, 1.046150597344396 + 0.199800119624031ɛ]\n",
       " [0.06281091254282065 + 0.011996001720624991ɛ, 1.0456273423483986 + 0.19970027658312506ɛ]\n",
       " [0.07326718596630463 + 0.013993004486456241ɛ, 1.0449996461453193 + 0.1995805531219053ɛ]\n",
       " [0.08371718242775783 + 0.015988810017675294ɛ, 1.0442676296166633 + 0.19944099848693514ɛ]\n",
       " [0.09415985872392446 + 0.017983220002544646ɛ, 1.043431435345513 + 0.19928167035279915ɛ]\n",
       " ⋮\n",
       " [-0.6752209213516684 - 0.8503582725709029ɛ, 0.9208694250633537 - 0.32113545402133725ɛ]\n",
       " [-0.6660122271010349 - 0.8535696271111163ɛ, 0.9271201228264712 - 0.31449782198630993ɛ]\n",
       " [-0.6567410258727702 - 0.8567146053309794ɛ, 0.9332986763761484 - 0.3077862741878133ɛ]\n",
       " [-0.6474080391090087 - 0.8597924680728576ɛ, 0.9394040667397519 - 0.3010012130426063ɛ]\n",
       " [-0.6380139984416111 - 0.8628024802032837ɛ, 0.945435276310508 - 0.2941430806380831ɛ]\n",
       " [-0.628559645678506 - 0.8657439110096645ɛ, 0.9513912893230583 - 0.2872123590945541ɛ]\n",
       " [-0.6190457327852754 - 0.8686160346006101ɛ, 0.9572710923361123 - 0.280209570895626ɛ]\n",
       " [-0.6094730218619143 - 0.8714181303095664ɛ, 0.9630736747218562 - 0.2731352791856272ɛ]\n",
       " [-0.599842285115009 - 0.8741494831013338ɛ, 0.968798029161568 - 0.26599008803328544ɛ]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "u0_dual = [Dual(0.0, 0.0), Dual(π/3, 0.2)]\n",
    "prob_dual = ODEProblem(pendulum, u0_dual, tspan)\n",
    "sol_dual = solve(prob_dual, Euler(); dt = 0.01)\n",
    "sol_dual.u # vector with the solution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What would happen if for the initial state we used an uncertain value distribution?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-element Vector{Vector{Particles{Float64, 2000}}}:\n",
       " [8.88e-19 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0105 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0209 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0314 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0419 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0523 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0628 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0733 ± 0.1, 1.05 ± 0.2]\n",
       " [0.0837 ± 0.1, 1.04 ± 0.2]\n",
       " [0.0942 ± 0.1, 1.04 ± 0.2]\n",
       " ⋮\n",
       " [-0.661 ± 0.6, 0.608 ± 0.52]\n",
       " [-0.655 ± 0.6, 0.613 ± 0.52]\n",
       " [-0.649 ± 0.61, 0.618 ± 0.52]\n",
       " [-0.643 ± 0.61, 0.623 ± 0.52]\n",
       " [-0.636 ± 0.61, 0.628 ± 0.51]\n",
       " [-0.63 ± 0.61, 0.633 ± 0.51]\n",
       " [-0.624 ± 0.62, 0.638 ± 0.51]\n",
       " [-0.617 ± 0.62, 0.643 ± 0.51]\n",
       " [-0.611 ± 0.62, 0.648 ± 0.51]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "u0_uncertain = [0 ± 0.1, π/3 ± 0.2]\n",
    "prob_uncertain = ODEProblem(pendulum, u0_uncertain, tspan)\n",
    "sol_uncertain = solve(prob_uncertain, Euler(); dt = 0.01)\n",
    "sol_uncertain.u # vector with the solution"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**_It just works._**\n",
    "\n",
    "Notice that I am not cheating here: there is **no glue code** between `OrdinaryDiffeq, DualNumbers, MonteCarloMeasurements`. These three packages are completely ignorant about each other! The language enables this interaction natively. In fact, this exact system is the basis for implementing neural ODEs in Julia, where part of the equations are Neural Networks!\n",
    "\n",
    "This incredible amount of power could not occur in e.g., Python, because it doesn't have one `sin` function. There is `pytorch.sin, numpy.sin, sympy.sin`. You would have to re-write your code three times for machine learning (autodiff), standard ODE solving, symbolic numerics, etc.\n",
    "\n",
    "Let's see how Julia makes all of this possible!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Types\n",
    "\n",
    "As eluded to in the previous lecture, all values in Julia have a specific Type. The Type system (i.e. the hierarchy of \"data identities\" anything in Julia has) is the the basis of multiple dispatch (next section). \n",
    "Julia's type system is dynamic but also allows to indicate that certain values are of specific type (i.e. static typing).\n",
    "\n",
    "**Quick important notice: \"Types\" are written in CamelCase by convention: `String`, `AbstractVector`, `Float64` while \"values\" and \"functions\" use lowercase `string`, `vector`, `float`.**\n",
    "\n",
    "## Type tree\n",
    "\n",
    "All values in Julia have a type that belongs to a single, fully connected type tree, all nodes of which are equally first-class as types. There is no distinction between native Julia types and user-created ones.\n",
    "\n",
    "The \"central\" node of this tree is `Any`, which literally means any possible value. The functions `subtypes` and `supertype` show the children or the parent of a node in this tree."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Type[]"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "subtypes(Float64) # this does not have subtypes, it is a \"leaf\" of the Type tree"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AbstractFloat"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "supertype(Float64)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that `subtypes/supertype` must take a Type as an input, not a value! E.g. `subtypes(5.0)` fails, as `5.0` is not a type, but it is instead an *instance* of the type `Float64`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Real"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "supertype(AbstractFloat)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Number"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "supertype(Real)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Any"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "supertype(Number)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We've reached the \"central\" node of the Type tree."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use the operator `<:` to check if something is a \"subtype of\" something else, for example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "true"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Float64 <: Number"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "false"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Float64 <: Int"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Abstract and concrete types\n",
    "\n",
    "Concrete types are anything that can be actually instantiated. Any value that exists in Julia code that is running always has a concrete type. On the other hand, abstract types exist only to establish hierarchical relations between the concrete types. At the moment we don't have a reason for hierarchical relations, but once we talk about Multiple Dispatch this reason will become apparent.\n",
    "\n",
    "In terms of mathematical reasoning, the distinction between abstract and concrete is simple: concrete types are leaves of the Type tree, while abstract types are anything else.\n",
    "\n",
    "Based on the above tree of the `Number` type, one can see that `Number, Real, AbstractFloat` are all abstract types, while `Float64, Float32` are concrete. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom types\n",
    "\n",
    "It is of course possible to create your own Types. This happens with the `struct` and `mutable struct` keywords like so"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct A\n",
    "    x\n",
    "    y\n",
    "end\n",
    "\n",
    "mutable struct B\n",
    "    x\n",
    "    y\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Types are instantiated by calling them as if they are functions, with arguments their fields (this is the \"default\" constructor, and one can make any arbitrary constructor they want)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A(1, 2)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "a = A(1, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "B(2, 3)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "b = B(2,3)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the *values* `a, b` are *instances* of the *Types* `A, B`. The difference between the two is that the `mutable` keyword establishes that any instance of type `B` can be mutated in place. This is not possible for `A`, and the only way to change its values is to make a new instance of `A` alltogether.\n",
    "\n",
    "Accessing the *fields* of the a Type is done by `a.fieldname`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 2)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "(a.x, b.x)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "b.x = 5 # possible because b (of type B) is mutable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "ename": "ErrorException",
     "evalue": "setfield!: immutable struct of type A cannot be changed",
     "output_type": "error",
     "traceback": [
      "setfield!: immutable struct of type A cannot be changed\n",
      "\n",
      "Stacktrace:\n",
      " [1] setproperty!(x::A, f::Symbol, v::Int64)\n",
      "   @ Base .\\Base.jl:38\n",
      " [2] top-level scope\n",
      "   @ c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:1"
     ]
    }
   ],
   "source": [
    "a.x = 5 # impossible"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the way we defined `A, B` here is **bad for performance**. The fields `x, y` can have any possible Type, as we added no restrictions to them. This means that once a function gets an instance of `A`, the compiler cannot optimize this function, as it is impossible to know by the type `A` what are the actual data structures involved. This is another form of Type instability that we discussed in the first session!\n",
    "\n",
    "To avoid this, use the type assertion operator `::` to enforce a Type to the fields of a `struct` definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct Agood\n",
    "    x::Float64\n",
    "    y::Float64\n",
    "    z::String\n",
    "end"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Agood(1.0, 1.0, \"best language evaaaah\")"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "julia = Agood(1, 1, \"best language evaaaah\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is means that `Agood` is **concretely typed**. (super-duper important by the way)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Abstract types\n",
    "\n",
    "As we specified no subtyping rule for `A, B`, they are by definition subtypes of the central node of the tree, `Any`. Abstract types are meaningful for subtyping relations.\n",
    "\n",
    "Abstract types are defined with the `abstract type` keyword"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "abstract type C end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the moment `C` is a subtype of `Any`. It is an abstract type so it is impossible to instantiate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "ename": "MethodError",
     "evalue": "MethodError: no constructors have been defined for C",
     "output_type": "error",
     "traceback": [
      "MethodError: no constructors have been defined for C\n",
      "\n",
      "Stacktrace:\n",
      " [1] top-level scope\n",
      "   @ c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:1"
     ]
    }
   ],
   "source": [
    "C(4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make `C` useful, we can create some subtypes of `C` using the subtyping operator `<:`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct D <: C\n",
    "    d::Number\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now `D` is a subtype of `C`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1-element Vector{Any}:\n",
       " D"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "subtypes(C)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just to be clear, the above definition of `D` is **also type-unstable**. Sure, it is better to specific that the field of `D` is some subtype of `Number`, but `Number` is still an abstract type!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parametric types\n",
    "\n",
    "Julia types can be parameterized based on other types, meaning that you can indeed make a field of a type to be \"anything that is a number\", and still be type stable!\n",
    "\n",
    "This is very useful for reducing code replication as well as leveraging multiple dispatch more. Type-parameterization means that when defining a `struct`, the fields of the struct could be of an arbitrary Type. Type-parameterization uses the curly brackets syntax. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct Alpha{T}\n",
    "    a::T\n",
    "    b::T\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here the type `Alpha` can be instantiated using the low level constructor `Alpha{Type}(val1, val2)`, which will convert automatically `val1, val2` to `Type`. For example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Alpha{Int64}(1, 1)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "a = Alpha{Int64}(1,1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The high level constructor `Alpha(val1, val2)` also exists, and will try to deduce what `Type` should be based on the arguments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Alpha{Int64}(5, 6)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Alpha(5, 6)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "ename": "MethodError",
     "evalue": "MethodError: no method matching Alpha(::String, ::Float64)\n\nClosest candidates are:\n  Alpha(::T, !Matched::T) where T\n   @ Main c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:2\n",
     "output_type": "error",
     "traceback": [
      "MethodError: no method matching Alpha(::String, ::Float64)\n",
      "\n",
      "Closest candidates are:\n",
      "  Alpha(::T, !Matched::T) where T\n",
      "   @ Main c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:2\n",
      "\n",
      "\n",
      "Stacktrace:\n",
      " [1] top-level scope\n",
      "   @ c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:1"
     ]
    }
   ],
   "source": [
    "Alpha(\"test\", 0.5)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since it is impossible to equivalently convert a string and a float to each other (as `1.0 != \"1\"`), one cannot instantiate `A` like this.\n",
    "\n",
    "Here is a second example with two type-parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct TwoPars{T, F}\n",
    "    a::T\n",
    "    b::F\n",
    "end"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "TwoPars{String, Float64}(\"string\", 0.5)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "TwoPars(\"string\", 0.5)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And a final example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct ManyPars{T <: Real, F <: Union{String, Real}}\n",
    "    a::T\n",
    "    b::F\n",
    "    c::Int\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, to instantiate `ManyPars`, `a` must be a subtype of reals, `b` could be a string or a real, while `c` has to be an integer."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Multiple dispatch\n",
    "Multiple dispatch is the core programming paradigm of Julia. This notebook presents simple examples that can teach you multiple dispatch. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What is Multiple Dispatch?\n",
    "\n",
    "Some handy definitions\n",
    "* **function**: the name of the \"function / process\" we are referring to.\n",
    "* **method**: what actually happens when we call the function with a specific combination of input arguments.\n",
    "\n",
    "*Dispatch* means that when a function call occurs, the language decides somehow which of the function *methods* have to be used. \n",
    "\n",
    "### No dispatch\n",
    "In no dispatch, as in e.g. C, there is nothing to be decided. The method and the function are one and the same. \n",
    "\n",
    "### Single dispatch\n",
    "In single dispatch, as in most object-oriented languages (like Python), it is possible for the same function name to have different methods:\n",
    "```\n",
    "array.set_size(args...)\n",
    "axis.set_size(args...)\n",
    "```\n",
    "where `array` could be an instance of something from `numpy` while `axis` could come from `matplotlib`. Here the language dispatches the function `set_size`, depending on the first argument, which is `array` or `axis`. It is important to note that in most object oriented languages, the **method is a property of the type**. \n",
    "\n",
    "### Multiple dispatch\n",
    "Here dispatch occurs based on the type of **every single function argument**, as in\n",
    "```\n",
    "set_size(a::Array, args...) = ...\n",
    "set_size(a::Axis, args...) = ...\n",
    "set_size(s, a::Array, args...) = ...\n",
    "set_size(a::Array, b::Vector) = ...\n",
    "set_size(a::Array, x::Real, y::Real, z::Real) = ...\n",
    "```\n",
    "etc. \n",
    "\n",
    "This means that multiple dispatch allows for exponentially more \"expressive power\", as one can use all arguments of the function to dispatch on.\n",
    "\n",
    "### How it works\n",
    "\n",
    "Keeping things simple, multiple dispatch follows one really basic rule: **the most specific method that is applicable to the input arguments is the one chosen!** \n",
    "\n",
    "Upon calling a function, Julia will try to find the method that is most specific across all arguments. This means that if a method is defined for both the abstract type combination, as well as the concrete type combination, Julia will always call the more concrete one. This rule also applies to e.g. parametric types, since `Vector{Float64}` is more specialized than `Vector` a method defined explicitly for `Vector{Float64}` is more specific. This rule also applies to unions, since `Float64` is more specialized than `Union{Float64, String}`.\n",
    "\n",
    "Two important points:\n",
    "\n",
    "1. **methods do not belong to the Types!**\n",
    "2. **new methods can be defined *after* the Types have been defined!**"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A simple example\n",
    "\n",
    "#### Defining some types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "abstract type Animal end # this is an abstract type. a supertype of the below\n",
    "\n",
    "struct Dog <: Animal   # this is a concrete type. a subtype of the above\n",
    "    name::String\n",
    "end\n",
    "\n",
    "struct Cat <: Animal\n",
    "    name::String\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's instantiate four animals"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Cat(\"Spotty\")"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "fido = Dog(\"Fido\")\n",
    "rex = Dog(\"Rex\")\n",
    "whiskers = Cat(\"Whiskers\")\n",
    "spotty = Cat(\"Spotty\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And finally, let's define some functions that take advantage of these `Animal` types, as well as multiple dispatch. Adding a method to a function is done by simply defining the function while also declaring the Types you add a method for:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "meets (generic function with 1 method)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "function encounter(a::Animal, b::Animal)\n",
    "    verb = meets(a, b)\n",
    "    println(\"$(a.name) meets $(b.name) and $verb\")\n",
    "end\n",
    "\n",
    "meets(a::Animal, b::Animal) = \"passes by\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Both of the above functions are defined on the abstract type level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Fido meets Rex and passes by\n",
      "Fido meets Spotty and passes by\n"
     ]
    }
   ],
   "source": [
    "encounter(fido, rex)\n",
    "encounter(fido, spotty)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now define more specific methods like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "meets (generic function with 5 methods)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "meets(a::Dog, b::Dog) = \"sniffs\"\n",
    "meets(a::Dog, b::Cat) = \"chases\"\n",
    "meets(a::Cat, b::Dog) = \"hisses\"\n",
    "meets(a::Cat, b::Cat) = \"slinks\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*(notice how the amount of methods of `meets` increased)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Fido meets Rex and sniffs\n",
      "Fido meets Whiskers and chases\n",
      "Whiskers meets Spotty and slinks\n",
      "Spotty meets Rex and hisses\n"
     ]
    }
   ],
   "source": [
    "encounter(fido, rex)\n",
    "encounter(fido, whiskers)\n",
    "encounter(whiskers, spotty)\n",
    "encounter(spotty, rex)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple extension of multiple dispatch\n",
    "What if we get a third animal? Like a rabbit? It is easy to extend the system"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Rabbit(\"Hops\")"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "struct Rabbit <: Animal\n",
    "    name::String\n",
    "end\n",
    "\n",
    "meets(a::Dog, b::Rabbit) = \"wiggles its tail\"\n",
    "meets(a::Rabbit, b::Cat) = \"hides\"\n",
    "\n",
    "hops = Rabbit(\"Hops\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Rex meets Hops and wiggles its tail\n",
      "Hops meets Whiskers and hides\n"
     ]
    }
   ],
   "source": [
    "encounter(rex, hops)\n",
    "encounter(hops, whiskers)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course, in the case where no specialized method exists, we get the default fallback we defined, as expected:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Whiskers meets Hops and passes by\n"
     ]
    }
   ],
   "source": [
    "encounter(whiskers, hops)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspecting dispatch\n",
    "\n",
    "To see how many methods a function has to it, and from which module they come, use `methods`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "# 7 methods for generic function <b>meets</b> from \u001b[35mMain\u001b[39m:<ul><li> meets(a::<b>Dog</b>, b::<b>Dog</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L1\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:1</a></li> <li> meets(a::<b>Dog</b>, b::<b>Cat</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L2\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:2</a></li> <li> meets(a::<b>Cat</b>, b::<b>Dog</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L3\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:3</a></li> <li> meets(a::<b>Cat</b>, b::<b>Cat</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L4\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:4</a></li> <li> meets(a::<b>Dog</b>, b::<b>Rabbit</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L5\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:5</a></li> <li> meets(a::<b>Rabbit</b>, b::<b>Cat</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L6\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:6</a></li> <li> meets(a::<b>Animal</b>, b::<b>Animal</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L6\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:6</a></li> </ul>"
      ],
      "text/plain": [
       "# 7 methods for generic function \"meets\" from \u001b[35mMain\u001b[39m:\n",
       " [1] meets(\u001b[90ma\u001b[39m::\u001b[1mDog\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mDog\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:1\u001b[24m\u001b[39m\n",
       " [2] meets(\u001b[90ma\u001b[39m::\u001b[1mDog\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mCat\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:2\u001b[24m\u001b[39m\n",
       " [3] meets(\u001b[90ma\u001b[39m::\u001b[1mCat\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mDog\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:3\u001b[24m\u001b[39m\n",
       " [4] meets(\u001b[90ma\u001b[39m::\u001b[1mCat\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mCat\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:4\u001b[24m\u001b[39m\n",
       " [5] meets(\u001b[90ma\u001b[39m::\u001b[1mDog\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mRabbit\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:5\u001b[24m\u001b[39m\n",
       " [6] meets(\u001b[90ma\u001b[39m::\u001b[1mRabbit\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mCat\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:6\u001b[24m\u001b[39m\n",
       " [7] meets(\u001b[90ma\u001b[39m::\u001b[1mAnimal\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mAnimal\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:6\u001b[24m\u001b[39m"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "methods(meets)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To see which method is called on a function call signature, use `@which`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "meets(a::<b>Cat</b>, b::<b>Dog</b>) in Main at <a href=\"https://github.com/Datseris/Zero2Hero-JuliaWorkshop/tree/1459bc1a1a72be14f14e659b9c74f22ef36ada84//2-MultipleDispatch.ipynb#L3\" target=\"_blank\">c:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\2-MultipleDispatch.ipynb:3</a>"
      ],
      "text/plain": [
       "meets(\u001b[90ma\u001b[39m::\u001b[1mCat\u001b[22m, \u001b[90mb\u001b[39m::\u001b[1mDog\u001b[22m)\n",
       "\u001b[90m     @\u001b[39m \u001b[90mMain\u001b[39m \u001b[90mc:\\Users\\gd419\\OneDrive - University of Exeter\\Teaching\\Zero2Hero-JuliaWorkshop\\\u001b[39m\u001b[90m\u001b[4m2-MultipleDispatch.ipynb:3\u001b[24m\u001b[39m"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@which meets(whiskers, rex)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*(in VSCode clicking that link would bring you to the source code where the method is defined; in Jupyter notebooks this feature doesn't work 🙁)*\n",
    "\n",
    "In Julia, all \"generic\" functions are of equal \"status\". The function `+` is in no way superior, or with more privileges, than the function `meets` we wrote up.\n",
    "\n",
    "It just has a bit more methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "+ (generic function with 719 methods)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "+"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extending existing functions/types"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I won't be going into Modules and namespaces here. But it is important to note that it would be possible for us to extend the `Animal` type as well as the `meets` function, *even if* they were coming from a different Module (e.g. a different Julia package).\n",
    "\n",
    "Extension is identical with creating a new method, however one has to specify the parent module as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [],
   "source": [
    "Base.:+(a::Animal, b::Animal) = println(\"$(a.name) and $(b.name) are animals\")\n",
    "Base.:+(a::Cat, b::Cat) = println(\"$(a.name) and $(b.name) cutie-cats, much cuter than doggos!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Rex and Whiskers are animals\n"
     ]
    }
   ],
   "source": [
    "rex + whiskers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Spotty and Whiskers cutie-cats, much cuter than doggos!"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "spotty + whiskers"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dispatch on parametric types\n",
    "\n",
    "\n",
    "Multiple dispatch can also be used on parametric types. Recall the definition of `Alpha`:\n",
    "```julia\n",
    "struct Alpha{T}\n",
    "    a::T\n",
    "    b::T\n",
    "end\n",
    "```\n",
    "For example if we define:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "foo (generic function with 3 methods)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "foo(a::Alpha) = \"generic function\"\n",
    "foo(a::Alpha{<:Number}) = \"specific to A with any number\"\n",
    "foo(a::Alpha{Float64}) = \"specific to A with 64-bit floats\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "then"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"generic function\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "foo(Alpha(\"string1\", \"string2\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"specific to A with any number\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "foo(Alpha(5, 6))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"specific to A with 64-bit floats\""
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "foo(Alpha(0.5, 0.6))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To learn more about the type system and multiple dispatch please read the official Julia documentation on [Types](https://pkg.julialang.org/docs/julia/THl1k/1.1.1/manual/types.html) and [Methods](https://pkg.julialang.org/docs/julia/THl1k/1.1.1/manual/methods.html). "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Generic algorithms\n",
    "\n",
    "How does one go about writing a generic algorithm through multiple dispatch? Well, it's simple really, just don't specify types unless you absolutely have to!\n",
    "\n",
    "## Some linear algebra algorithm\n",
    "Imagine the following simple algorithm, that performs some linear algebra computations involving inner products. `A` is supposed to be a matrix, while `vs` is supposed to be a vector of vectors, and the inner product `v ⋅ A ⋅ v` is performed for every vector."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "inner (generic function with 1 method)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using LinearAlgebra: dot\n",
    "\n",
    "function inner_sum(A, vs)\n",
    "    t = zero(eltype(A))\n",
    "    for v in vs\n",
    "        t += inner(v, A, v)\n",
    "    end\n",
    "    return t\n",
    "end\n",
    "\n",
    "inner(v, A, w) = dot(v, A*w)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "4.0471290624466025"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "a = rand(3,3)\n",
    "vs = [rand(3) for i in 1:5]\n",
    "inner_sum(a, vs)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The above code is **generic**: any `A, vs` that support the correct operations (here `*` and `dot`), will work fine.\n",
    "\n",
    "* Because Julia compiles all code based on the exact input types, `inner_sum` is also **arbitrarily efficient**. Given standard Julia matrices and vectors it uses BLAS. Given statically-sized arrays it uses super-efficient unrolled operations."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The \"OneHot\" vector\n",
    "\n",
    "In various fields that use linear algebra, like machine learning, a special vector datastracture is used often, called a \"OneHot\" vector. This vector has a 1 in a single entry, and 0 in all other entries. Having a dedicated structure for this vector is super efficient, because you only need to store 2 numbers to store it in memory, irrespectively of how large the vector is!\n",
    "\n",
    "Let's create this in Julia. To make our life easy, we will make this new Type a subtype of `AbstractVector`. This means that all functions that are defined on the abstract level for `AbstractVector` will work with our type as well (provided we implement all the necessary *methods*)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [],
   "source": [
    "struct OneHotVector <: AbstractVector{Bool}\n",
    "    len::Int\n",
    "    ind::Int\n",
    "end"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I \"know\" (by reading the documentation on the interface of `Array`) that the necessary methods I need to extend to make `OneHotVector` truly behave like any arbitrary Julia `vector` is (a) a `size` method and (b) a `getindex` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Extend size (so that it behaves like an array)\n",
    "Base.size(v::OneHotVector) = (v.len, )\n",
    "\n",
    "# Extend indexing (so that accessing a OneHotVector like v[5] works)\n",
    "Base.getindex(v::OneHotVector, i::Integer) = i == v.ind"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "10-element OneHotVector:\n",
       " 0\n",
       " 0\n",
       " 1\n",
       " 0\n",
       " 0\n",
       " 0\n",
       " 0\n",
       " 0\n",
       " 0\n",
       " 0"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "oh = OneHotVector(10, 3) # its already a \"true\" Julia vector!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Does our algorithm already work with such a vector?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.0558225871434948"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "vs = [OneHotVector(3, rand(1:3)) for _ in 1:5]\n",
    "\n",
    "inner_sum(a, vs)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "crazy stuff."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## OneHot inner product\n",
    "\n",
    "It is already great that the above algorithm works with the new `OneHotVector` type. The generic code that one writes with Julia is extensible with **minimal** effort.\n",
    "\n",
    "*But*, it currently uses the generic fallback `inner(w, A, v) = dot(w, A*v)`. This is inefficient! Let's break this down:\n",
    "\n",
    "1. `A*v` is a matrix-vector multiplication. It iterates every column of `A` and multiplies them by each entry of `v`.\n",
    "2. If the vector `v` has 0s everywhere and a 1 somewhere, then this operation in fact means `A[:, v.ind]`. I.e. we select the `v.ind`-th column of the matrix `A`.\n",
    "3. `dot(w, Av)` is also generic, it indexes into `w` and `Av` and does a pair-wise multiplication.\n",
    "4. Given the structure of `OneHotVector` we know that `inner(w, A, v)` is in fact just `A[w.ind, v.ind]`!\n",
    "\n",
    "Increasing the performance of our algorithm is **trivial**. Simply extend `inner` for `OneHotVector`. But first, some benchmarks...\n",
    "\n",
    "Here's how the performance of the algorithm would be without taking advantage of the internal structure of `OneHotVector`, and using it as if it was an full vector of 0s and 1s:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  5.650 μs (5 allocations: 4.38 KiB)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "2.8235095595788904"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "using BenchmarkTools\n",
    "\n",
    "L = 100\n",
    "a = rand(L, L)\n",
    "vs = [OneHotVector(L, rand(1:L)) for _ in 1:5]\n",
    "\n",
    "# timing before performance extension\n",
    "@btime inner_sum($a, $vs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now add the crucial extension:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "inner (generic function with 2 methods)"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "inner(w::OneHotVector, a, v::OneHotVector) = a[w.ind, v.ind]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and time again:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  5.100 ns (0 allocations: 0 bytes)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "2.8235095595788904"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# timing after performance extension\n",
    "@btime inner_sum($a, $vs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, isn't this crazy.\n",
    "\n",
    "**This matters a lot for academic code! It is often the case that you want to make a change in the algorithmic behavior of only a very small & very specific part of your algorithms. Multiple dispatch allows you to do just that - you don't have to re-write 100s of lines of code to just alter the behavior of 5.**"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Code re-use in Julia"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is an astonishing amount of code-reuse and cooperation among different packages of the Julia ecosystem, as we will see in the next lecture much more than any other science-used language has achieved so far (see [Stefan Karpinski's talk for more details on this](https://www.youtube.com/watch?v=kc9HwsxE1OY)).\n",
    "\n",
    "Naively one would think it is because of the ease of writing generic algorithms. This is in part true, but the reason Julia is the only language that truly succeeds in having all packages play nicely with each other (without each package actively writing glue code) is that you can re-use types from other people!\n",
    "\n",
    "In the following I'll compare the story of \"extending some else's type\" in Julia and in Python, and the difference will become apparent.\n",
    "\n",
    "Let's take as example the type `RGB`, which represents a color, and is defined in the Julia package `ColorTypes`. It is a simple type that bundles a value for red, green and blue, as well as defines some basic operations for the `RGB` type. For this example we can assume that `RGB` is defined as\n",
    "```julia\n",
    "struct RGB\n",
    "  r::Float64\n",
    "  g::Float64\n",
    "  b::Float64\n",
    "end\n",
    "```"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extending this type in Julia\n",
    "\n",
    "Now someone wants to **extend this existing type** `RGB`. For example, one might want to create a color vector space. \n",
    "\n",
    "How is this done in Julia? \n",
    "Simple! Extend the functionality of `RGB` by adding new methods that dispatch on `RGB`. \n",
    "\n",
    "For example, you could extend **existing functions**\n",
    "```julia\n",
    "module ExtensionsToRGB # creates a new module (new \"package\")\n",
    "using RGB\n",
    "\n",
    "Base.zero(::RGB) = RGB(0,0,0) # value of input doesnt matter\n",
    "Base.inv(c::RGB) = RGB(1 - c.r, 1 - c.g, 1 - c.b)\n",
    "\n",
    "end\n",
    "```\n",
    "etc., or **define new functions**\n",
    "```julia\n",
    "module ExtensionsToRGB # creates a new module (new \"package\")\n",
    "export dotc\n",
    "using RGB\n",
    "\n",
    "# dot product in color space: convert to grayscale and then normalize\n",
    "dotc(x::RGB, y::RGB) = 0.2*x.r*y.r + 0.771*x.g*y.g + 0.029*x.b*y.b\n",
    "\n",
    "end\n",
    "```\n",
    "\n",
    "All of this \"just works (TM)\" in Julia, even if the type `RGB` comes from a completely independent Julia package!\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Is this possible in OOP (Python)?\n",
    "In OOP the methods of a \"class\", are **defined literally textually within the class**. Therefore, if you wanted to extend this `RGB` in Python you would have two options:\n",
    "\n",
    "1. Edit the text file that defines the original class.\n",
    "2. Inherit the original class.\n",
    "\n",
    "### (1) Modifying the original class\n",
    "There are problems here:\n",
    "* You have to convince the author of the original package that your code is worthy to be included.\n",
    "* If everyone convinces the author about their method, the original class becomes huge and the source code becomes an unreadable mess.\n",
    "* The original developer has to maintain everyone else's whacka-doodle methods.\n",
    "* You can't change your mind about your extensions without potentially breaking everyone that uses the class `RGB`.\n",
    "\n",
    "### (2) Inheriting\n",
    "There are problems here as well:\n",
    "* If you inherit, you can't \"inherit the name\"; you have to create a new type `MyRGB` that inherits `RGB`.\n",
    "* Your extension will **not** actually apply to `RGB`, only to `MyRGB`. Therefore, anyone that already uses `RGB` cannot potentially benefit from your code.\n",
    "* This complexity increases quite fast; someone else makes `YourRGB` object, and then a third person tries to inherit from both `MyRGB` and `YourRGB` and makes an `OurRGB`, etc... Quickly becomes a hellhole!\n",
    "\n",
    "### Why Julia does better here\n",
    "Julia's multiple dispatch has none of the problems of (1) and (2). In addition, everyone that does not load the module `ExtensionsToRGB` is completely unaffected by whatever whacka-doodle shady business is happening there. On the other side, with the simple one liner `using ExtensionsToRGB`, you immediately gain access to all the extensions that have been done in that package. **And these extensions are valid for the single Julia type `RGB`**. No `MyRGB` nonsense!\n",
    "\n",
    "The reasons why this is so trivial in Julia is because:\n",
    "\n",
    "1. You can define _new types_ to which *existing operations* apply\n",
    "2. You can define _new operations_ which apply to *existing types*\n",
    "\n",
    "To go deeper into the concepts discussion in this section, you should have a look at this [blog post by Frames Catherine White](https://white.ucc.asn.au/2020/02/09/whycompositionaljulia.html) or this [talk by Stefan Karpinski](https://www.youtube.com/watch?v=kc9HwsxE1OY)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Multiple dispatch & scientific thought"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multiple dispatch makes developing scientific codebases extremely efficient (from the perspective of how much time a human has to spend), because it allows packages to access, utilize, modify, and extend other packages' code super easily as we have seen so far in this notebook. This partly explains the surge of powerful packages that exist in Julia despite the language recency.\n",
    "\n",
    "But I argue, there is one more fundamental reason multiple dispatch leads to incredibly efficient scientific programming, and further explains the package surge. It's because the way one rationalizes about code in multiple dispatch, is similar to the way one connects processes, objects, and ideas, in science. That is:\n",
    "\n",
    "**Multiple dispatch is the programming paradigm that most closely parallels scientific thought, because it detaches the processes (functions) from the objects (data types).**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: space simulations\n",
    "\n",
    "Imagine that you are working in space exploration. You have rockets, planets, asteroids. The process \"collide\" can occur between all three of these objects, yet fundamentally different in each case:\n",
    "\n",
    "1. when a rocket collides with an asteroid, the rocket explodes\n",
    "2. when an asteroid collides with a planet, the asteroid is disintegrated\n",
    "3. when a rocket collides with a planet, the rocket attempts to land on the planet\n",
    "4. when an asteroid collides with another asteroid they both disintegrate\n",
    "5. ...\n",
    "\n",
    "Implementing this scientific scenario in multiple dispatch directly parallels how we think about it. You extend the \"collide\" process for each combination. However, reasoning about this in an object-oriented framework is difficult, because the process \"collide\" must belong to one of the three objects. Yet, scientifically, this doesn't make any sense."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercises"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Type hierarchies\n",
    "\n",
    "Create a function `person_info(p)` that takes in any type of a \"person\" and prints their name and potentially some extra information. For a normal person, only the name is printed. If the person is a student, it should print their name *and* grade. If it is a group leader, then print their name and their group name. If the input to `person_info` is something other than a \"person\", it should error.\n",
    "\n",
    "Solve this exercise without using a single `if` statement; only multiple dispatch. These kind of problems seem to be \"natural\" to solve using `if` statements. However using multiple dispatch instead makes the code clearer, more easy to extend and (typically) more performant, because of how Julia compiles code.\n",
    "\n",
    "*Hint: given the rules of the exercise, you do not actually need abstract types to solve it. However, it is in general good practice to use them.*"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Indexing of a range type\n",
    "Create your own `Range` object, which is an efficient iterable container defined by a `(start, step, stop)`, which gives numeric values incremented by `step` starting from `start`, while *ensuring* that the result never exceeds `stop`. You only need to extend (add a new method) to the `Base.getindex(r::Range, i::Int)` function for this exercise. \n",
    "\n",
    "Test your range by initializing a range like `r = Range(0, 0.5, 1)`, and checking if `r[1], r[2], r[3]` give you indeed `0.0, 0.5, 1.0` as they should.\n",
    "\n",
    "This object can efficiently represent this range while storing only these 3 numbers, instead of all elements that theoretically belong to the range.\n",
    "\n",
    "*Hints:*\n",
    "1. As a first step, define your `Range` `struct`, preferably by making it a parametric type of 1 type-parameter (think about how many fields it should have).\n",
    "2. The Julia syntax `A[i]` is translated to `getindex(A, i)`. That's why you need to extend the `Base.getindex` function. Use the help functionality on `getindex` to learn more. \n",
    "3. Implement indexing for your Range type via extending `getindex`. Index `1` giving `start`. Be sure it errors for incorrect indices (where the value given by the range would exceed `stop`)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Iteration of a range type\n",
    "\n",
    "Continuing from the previous exercise, now make your `Range` object iterable by extending `Base.iterate(r::Range, state = 1)` as well as `Base.length(r::Range)`. It will then be possible to do `collect(range)` or `for a in range ...` or `[cos(r) for r in range]`.\n",
    "\n",
    "*Hints:*\n",
    "\n",
    "The [Julia documentation on the iteration API](https://pkg.julialang.org/docs/julia/THl1k/1.1.1/manual/interfaces.html#man-interface-iteration-1) shows that the Julia code block\n",
    "```julia\n",
    "for i in iter\n",
    "    # body\n",
    "end\n",
    "```\n",
    "\n",
    "is in fact internally translated into:\n",
    "```julia\n",
    "next = iterate(iter)\n",
    "while next !== nothing\n",
    "    (i, state) = next\n",
    "    # body\n",
    "    next = iterate(iter, state)\n",
    "end\n",
    "```\n",
    "\n",
    "1. To solve this exercise you need to define `Base.iterate(r::Range, state = 1)` which returns either the current element and the next iteration state (typically `i+1`) or `nothing` if there are no elements remaining to be iterated.\n",
    "2. Test `iterate` for your `Range` by using it in a `for` loop: `for r in myrange; @show r; end`.\n",
    "\n",
    "* **Bonus point** Did you write generic code? Try to see if your `Range` works with the package `Unitful`. This package provides types that combines numbers with physical units (like Newtons). Load this package with `using Unitful`. Does iterating a `Range(1u\"kg\", 0.1u\"kg\", 10u\"kg\")` work as expected? Make the necessary adjustments so that it does."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Advanced whackadoodle iterator\n",
    "\n",
    "Leveraging the experience of previous exercises, define an iterator object (and of course define `iterate` for it!) that has the following properties (**make an iterator struct, don't create a vector!**):\n",
    "\n",
    "* It iterates for `n` elements. The first element is always `rand()`.\n",
    "* At the odd steps of the iteration it returns the previous element divided by `rand()`.\n",
    "* At the even steps of the iteration it returns the previous element multiplied by `rand()`.\n",
    "\n",
    "Use this iterator object to efficiently study how its mean value and standard deviation behaves versus `n`, by using the functions `mean, std` (accessible after `using Statistics`). \n",
    "\n",
    "*Hint: if you implement this iterator correctly, then you should be able to give it directly to `mean`.*"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rational numbers\n",
    "\n",
    "Implement the type `RationalNumber <: Real`, similar to Julia's `Rational`, but without being a parametric type (i.e. both fields are just `Int`). Using the following function\n",
    "```julia\n",
    "function simplify(n::Integer, d::Integer)\n",
    "    g = gcd(n, d)\n",
    "    m = d < 0 ? -1 : 1\n",
    "    (m * n ÷ g, m * d ÷ g)\n",
    "end\n",
    "```\n",
    "define an **inner constructor**: a function `RationalNumber` inside the type-definition, which returns `new(simplify(n, d)...)`. `new` is a special keyword and stands for the type to be created. For example:\n",
    "```julia\n",
    "struct A\n",
    "    a::Float64\n",
    "    function A(a)\n",
    "        x = cos(a)\n",
    "        return new(x) # This creates an instance of A with the value x\n",
    "    end\n",
    "end\n",
    "```\n",
    "Inner constructors are used to perform specific tests or transformations necessary before instantiating a type. In this exercise the inner constructor simply ensures that if you try to define the rational number 5/10 you in fact create the equivalent (but simpler) 1/2.\n",
    "\n",
    "Then, implement the operations `+, -, *, /` between `RationalNumber`s, by extending e.g. `Base.:+(r1::RationalNumber, r2::RationalNumber)`.\n",
    "\n",
    "Test your code by ensuring that `RationalNumber(5, 10)` indeed has fields `(1, 2)`. Then test all operations with the rationals `1/2` and `1/3`.\n",
    "\n",
    "* **extra point**: Find out the minimum extension you need to make to your number type so that all trigonometric functions like `cos, tanh`, etc. work out of the box with it. (Hint: it is only one more method definition)"
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "kernelspec": {
   "display_name": "Julia 1.9.4",
   "language": "julia",
   "name": "julia-1.9"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.9.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}