Params Example

examples/01_Simulation.ipynb

@@ -1137,6 +1137,109 @@
     "## Parameters"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "All the previous sections used a model with default settings. This is hardly ever the case. A model will have to be configured to represent the actual system. For example, the BatteryCircuit default parameters are for a 18650 battery tested in NASA's SHARP lab. If you're using the model for a system other than that one battery, you will need to update the parameters.\n",
+    "\n",
+    "The parameters available are specific to the system in question. See 3. Included Models for a more detailed description of these. For example, for the BatteryCircuit model, parameters include battery capacity, internal resistance, and other electrical characteristics.\n",
+    "\n",
+    "In this section we will adjust the parameters for the ThrownObject Model, observing how that changes system behavior."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from progpy.models import ThrownObject\n",
+    "m = ThrownObject()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Parameters can be accessed using the `parameters` attribute. For a ThrownObject, here are the parameters:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(m.parameters)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Ignoring process and measurement noise for now (that will be described in the next section) and the lumped_parameter (which will be described in 4. Creating new prognostic models), the parameters of interest here are described below:\n",
+    "\n",
+    "* **thrower_height**: The height of the thrower in meters, and therefore the initial height of the thrown object\n",
+    "* **throwing_speed**: The speed at which the ball is thrown vertically (in m/s)\n",
+    "* **g**: Acceleration due to gravity (m/s^2)\n",
+    "* **rho**: Air density (affects drag)\n",
+    "* **A**: Cross-sectional area of the object (affects drag)\n",
+    "* **m**: Mass of the object (affects drag)\n",
+    "* **cd**: Coefficient of drag of the object (affects drag)\n",
+    "\n",
+    "Let's try simulating the path of the object with different throwing speeds."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results1 = m.simulate_to_threshold(threshold_keys='impact', dt=0.1, save_freq=0.1)\n",
+    "fig = results1.outputs.plot(title='default')\n",
+    "\n",
+    "m.parameters['throwing_speed'] = 10\n",
+    "results2 = m.simulate_to_threshold(threshold_keys='impact', dt=0.1, save_freq=0.1)\n",
+    "fig = results2.outputs.plot(title='slow')\n",
+    "\n",
+    "m.parameters['throwing_speed'] = 80\n",
+    "results3 = m.simulate_to_threshold(threshold_keys='impact', dt=0.1, save_freq=0.1)\n",
+    "fig = results3.outputs.plot(title='fast')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also set parameters as keyword arguments when instantiating the model, like below. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m_e = ThrownObject(g=-9.81)  # Earth gravity\n",
+    "results_earth = m_e.simulate_to_threshold(threshold_keys='impact', dt=0.1, save_freq=0.1)\n",
+    "fig = results_earth.outputs.plot(title='Earth')\n",
+    "\n",
+    "m_j = ThrownObject(g=-24.79)  # Jupiter gravity\n",
+    "results_jupiter = m_j.simulate_to_threshold(threshold_keys='impact', dt=0.1, save_freq=0.1)\n",
+    "fig = results_jupiter.outputs.plot(title='Jupiter')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Model parameters are used to configure a model to accurately describe the system of interest.\n",
+    "\n",
+    "For a simple system like the ThrownObject, model parameters are simple and measurable. For most systems, there are many parameters that are difficult to estimate. For these, parameter estimation comes into play. See 2. Parameter Estimation for more details"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},