Add example

examples/01_Simulation.ipynb

@@ -328,6 +328,49 @@
     "For most users running this in Jupyter notebook, the output will be truncated, but it gives an idea of what would be shown when selecting these options."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this example we specified events='impact' to indicate that simulation should stop when the specified event 'impact' is met. By default, the simulation will stop when the first of the specified events occur. If you dont specify any events, all model events will be included (in this case ['falling', 'impact']). This means that without specifying events, execution would have ended early, when the object starts falling, like below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = m.simulate_to_threshold(save_freq=0.5, dt=0.1)\n",
+    "print('Last timestep: ', results.times[-1])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that simulation stopped at around 3.8seconds, about when the object starts falling. \n",
+    "\n",
+    "Alternately, if we would like to execute until all events have occurred we can use the `event_strategy` argument, like below:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = m.simulate_to_threshold(save_freq=0.5, dt=0.1, event_strategy='all')\n",
+    "print('Last timestep: ', results.times[-1])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Not the simulation stopped at around 7.9 seconds, when the last of the events occured ('impact')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},