Skip to content

Commit

Permalink
Merge branch 'dev' into examples/load_profiles
Browse files Browse the repository at this point in the history
  • Loading branch information
@teubert
teubert authored Sep 13, 2023
2 parents c33e168 + 0c23145 commit fd7bd42
Show file tree
Hide file tree
Showing 5 changed files with 336 additions and 86 deletions.
165 changes: 86 additions & 79 deletions examples/linear_model.ipynb → examples/04_New Models.ipynb
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,51 @@
{
"cells": [
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"# Welcome to ProgPy's Linear Model Example"
"# 4. Defining new Physics-Based Prognostic Models"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"The goal of this notebook is to instruct users on how to use ProgPy Model LinearModel.\n",
"\n",
"This example shows the use of the LinearModel class, a subclass of PrognosticsModel for models that can be described as a linear time series, which can be defined by the following equations:\n",
"All of the past sections describe how to use an existing model. In this section we will describe how to create a new model. This section specifically describes creating a new physics-based model. For training and creating data-driven models see 5. Data-driven Models."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Linear Models"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The easiest model to build is a linear model. Linear models are defined as a linear time series, which can be defined by the following equations:\n",
"\n",
"\n",
"\n",
"#### _<b>The State Equation<b>_:\n",
"**The State Equation**:\n",
"$$\n",
"\\frac{dx}{dt} = Ax + Bu + E\n",
"$$\n",
"\n",
"#### _<b>The Output Equation<b>_:\n",
"**The Output Equation**:\n",
"$$\n",
"z = Cx + D\n",
"$$\n",
"\n",
"#### _<b>The Event State Equation<b>_:\n",
"**The Event State Equation**:\n",
"$$\n",
"es = Fx + G\n",
"$$\n",
"\n",
"$x$ is `state`, $u$ is `input`, $z$ is `output`, and $es$ is `event state`"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"$x$ is `state`, $u$ is `input`, $z$ is `output`, and $es$ is `event state`\n",
"\n",
"Linear Models are defined by creating a new model class that inherits from progpy's LinearModel class and defines the following properties:\n",
"* $A$: 2-D np.array[float], dimensions: n_states x n_states. <font color = 'teal'>The state transition matrix. It dictates how the current state affects the change in state dx/dt.</font>\n",
"* $B$: 2-D np.array[float], optional (zeros by default), dimensions: n_states x n_inputs. <font color = 'teal'>The input matrix. It dictates how the input affects the change in state dx/dt.</font>\n",
Expand All @@ -57,32 +61,31 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"We will now utilize our LinearModel to model the classical physics problem throwing an object into the air! We can create a subclass of LinearModel which will be used to simulate an object thrown, which we will call the ThrownObject Class.\n",
"We will now utilize our LinearModel to model the classical physics problem throwing an object into the air. This is a common example model, the non-linear version of which (`progpy.examples.ThrownObject`) has been used frequently throughout the examples. This version of ThrownObject will behave nearly identically to the non-linear ThrownObject, except it will not have the non-linear effects of air resistance.\n",
"\n",
"We can create a subclass of LinearModel which will be used to simulate an object thrown, which we will call the ThrownObject Class.\n",
"\n",
"First, some definitions for our Model!\n",
"First, some definitions for our Model:\n",
"\n",
"#### __Events__: (2)\n",
"**Events**: (2)\n",
"* `falling: The object is falling`\n",
"* `impact: The object has hit the ground`\n",
"\n",
"#### __Inputs/Loading__: (0)\n",
"**Inputs/Loading**: (0)\n",
"* `None`\n",
"\n",
"#### __States__: (2)\n",
"**States**: (2)\n",
"* `x: Position in space (m)`\n",
"* `v: Velocity in space (m/s)`\n",
"\n",
"#### __Outputs/Measurements__: (1)\n",
"**Outputs/Measurements**: (1)\n",
"* `x: Position in space (m)`"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
Expand All @@ -95,7 +98,6 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
Expand All @@ -115,34 +117,21 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we'll define some features of a ThrownObject LinearModel. Recall that all LinearModels follow a set of core equations and require some specific properties (see above). In the next step, we'll define our inputs, states, outputs, and events, along with the $A$, $C$, $E$, and $F$ values."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we'll define some features of a ThrownObject LinearModel. Recall that all LinearModels follow a set of core equations and require some specific properties (see above). In the next step, we'll define our inputs, states, outputs, and events, along with the $A$, $C$, $E$, and $F$ values.\n",
"\n",
"First, let's consider state transition. For an object thrown into the air without air resistance, velocity would decrease literally by __-9.81__ \n",
"$\\dfrac{m}{s^2}$ due to the effect of gravity, as described below:\n",
"\n",
" $$\\frac{dv}{dt} = -9.81$$\n",
"\n",
" Position change is defined by velocity (v), as described below:\n",
" \n",
" $$\\frac{dx}{dt} = v$$"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Note: For the above equation x is position not state. Combining these equations to the model $\\frac{dx}{dt}$ equation defined earlier yields the A and E matrix defined below. Note that there is no B defined because this model does not have an inputs."
" $$\\frac{dx}{dt} = v$$\n",
"\n",
" Note: For the above equation x is position not state. Combining these equations with the model $\\frac{dx}{dt}$ equation defined above yields the A and E matrix defined below. Note that there is no B defined because this model does not have any inputs."
]
},
{
Expand All @@ -164,7 +153,6 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
Expand All @@ -187,19 +175,12 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"In the following cells, we'll define some class functions necessary to perform prognostics on the model."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"The `initialize()` function sets the initial system state. Since we have defined the `x`and `v` values for our ThrownObject model to represent position and velocity in space, our initial values would be the thrower_height, and throwing_speed parameters, respectively."
"In the following cells, we'll define some class functions necessary to perform prognostics on the model.\n",
"\n",
"The `initialize()` function sets the initial system state. Since we have defined the `x` and `v` values for our ThrownObject model to represent position and velocity in space, our initial values would be the thrower_height and throwing_speed parameters, respectively."
]
},
{
Expand All @@ -217,7 +198,6 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
Expand All @@ -241,7 +221,6 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
Expand All @@ -264,13 +243,10 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"With these functions created, we can now run our ThrownObject Model!\n",
"\n",
"In this example, we will initialize our ThrownObject as `m`, and we'll use the `simulate_to_threshold()` function to simulate the movement of the thrown object in air. For more information, see the [Simulation](https://nasa.github.io/progpy/prog_models_guide.html#simulation) documentation."
"With these functions created, we can now use the `simulate_to_threshold()` function to simulate the movement of the thrown object in air. For more information, see 1. Simulation."
]
},
{
Expand All @@ -280,58 +256,89 @@
"outputs": [],
"source": [
"m = ThrownObject()\n",
"save = m.simulate_to_threshold(print = True, save_freq=1, threshold_keys='impact', dt=0.1)"
"save = m.simulate_to_threshold(print=True, save_freq=1, threshold_keys='impact', dt=0.1)"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"__Note__: Because our model takes in no inputs, we have no need to actually define a future loading function! As a result, we are simply passing in an empty Input Container. However, for most models, there would be inputs, thus a need for a future loading function. For more information on future loading functions and when to use them, please refer to the ProgPy [Future Loading](https://nasa.github.io/progpy/prog_models_guide.html#future-loading) Documentation."
"__Note__: Because our model takes in no inputs, we have no need to define a future loading function. However, for most models, there would be inputs, and thus a need for a future loading function. For more information on future loading functions and when to use them, please refer to the future loading section in 1. Simulation.\n",
"\n",
"Let's take a look at the outputs of this model"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"fig = save.outputs.plot(title='generated model')"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"We'll also demonstrate how this looks plotted on a graph."
"Notice that that plot resembles a parabola, which represents the position of the ball through space as time progresses!"
]
},
{
"cell_type": "code",
"execution_count": null,
"cell_type": "markdown",
"metadata": {},
"outputs": [],
"source": [
"import matplotlib.pyplot as plt\n",
"save.outputs.plot(title='generated model')\n",
"plt.show()"
"For more information on Linear Models, see the [Linear Model](https://nasa.github.io/progpy/api_ref/prog_models/LinearModel.html) Documentation."
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"Notice that that plot resembles a parabola, which represents the position of the ball through space as time progresses!"
"## New State Tranisition Models"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"#### Conclusion\n",
"\n",
"In this example, we will initialize our ThrownObject as `m` and use the `simulate_to_threshold()` function to simulate the movement of the thrown object in air. For more information, see the [Linear Model](https://nasa.github.io/progpy/api_ref/prog_models/LinearModel.html) Documentation."
"## Direct Models"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Derived Parameters"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
"source": [
"## Matrix Models"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## State Limits"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Custom Events"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Conclusions"
]
}
],
"metadata": {
Expand Down
Loading

0 comments on commit fd7bd42

Please sign in to comment.