Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jose review #7

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Jose review #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79b72cb
Review.
chrisdembia Jan 23, 2019
d2d3994
Add review comments for JOSE submission.
chrisdembia Jan 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions paper/paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,21 +31,21 @@ StateMint includes a Mathematica package, a Python package, and a web interface

# Introduction

When deriving a system's state-space model—that is, the vector state (differential) equation and the vector output (algebraic) equation—one begins by forming scalar equations for each element describing its dynamics.
When deriving a system's state-space model—that is, the vector state (differential) equation and the vector output (algebraic) equation—one begins by forming scalar equations for each element **REVIEW: Not all systems are "element"-based. The reader may need more background here.** describing its dynamics.
The next step is to form a set of $N$ constraint equations that describe the topology of the system defined by the interconnection of the $N$ elements.
A set of $2N$ differential and algebraic equations and $2N$ unknown variables result.
If properly constructed (e.g. with the linear graph technique), $N$ of the unknown variables can be immediately eliminated through direct substitution.
A set of $2N$ differential and algebraic equations and $2N$ unknown variables result **REVIEW: Add a citation for why this is the case?**.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the case because each element has its elemental equation, along with a continuity or compatibility (a constraint) equation. Each element also has a through and across-variable associated with it. I have not seen this explicitly stated anywhere, but it can be derived from the linear graph methods. If you would like I could reference Rowell and Wormley here.

If properly constructed (e.g. with the linear graph technique **REVIEW: Not defined**), $N$ of the unknown variables can be immediately eliminated through direct substitution.
Finally, the set of equations can be reduced to a system of first-order differential equations in state and input variables and their time-derivatives, alone.
It is in these last two steps, especially the very last, that a student, manually reducing the set of equations, will often make some minor mistake.
This is typically of a "book keeping" variety that, if it teaches the student anything, it is not system dynamics.
It is in these last two steps, especially the last, that a student, manually reducing the set of equations, will often make some minor mistake.
This mistake is typically of a "book keeping" variety that, if it teaches the student anything, it is not system dynamics.
Instead, the student can be easily discouraged and confused about where they have made their mistake.
Fortunately, the software tools presented here will automate the algebraic reduction.
These will allow students to focus on understanding the process of dynamic system modeling.

Utilizing the advanced symbolic mathematics capabilities of Mathematica, a package was written to determine the dynamic system model.
However, this requires students to install and learn (at least) the basics of Mathematica.
To mitigate this problem, a web interface was designed to allow students to use this tool without any knowledge of programming by allowing equations to be input with notation similar to that of many scientific calculators.
To support this interface, a Python package was written with the same functionality as the Mathematica package and is deployed as an Amazon AWS Lambda function for use by the web interface.
Utilizing the advanced symbolic mathematics capabilities of Mathematica, we created a package that determines the dynamic system model.
However, this requires students to install and learn the basics of Mathematica.
To mitigate this problem, we designed a web interface to allow students to use this tool without any knowledge of programming by allowing equations to be input with notation similar to that of many scientific calculators.
To support this interface, we created a Python package with the same functionality as the Mathematica package and we deployed the package as an Amazon AWS Lambda function for use by the web interface.
This interface can be accessed by any device with an internet connection and a web browser.

# Web Interface
Expand All @@ -72,14 +72,14 @@ A detailed example of how to use the Python StateMint package is [included](http

# Mathematica Package

The Mathematica package `StateMint` can be installed as described in the [documentation](https://github.com/CameronDevine/StateMint/blob/master/mathematica/README.md). The central function of the package is `stateEquations`, which uses an algorithm similar to that of the Python package, above, to derive the state equations. It takes as arguments lists of elemental equations, constraint equations, primary variables, and input variables and returns the vector state equation, state variables, and the time-derivative of the state variables.
The Mathematica package `StateMint` can be installed as described in the [documentation](https://github.com/CameronDevine/StateMint/blob/master/mathematica/README.md). The central function of the package is `stateEquations`, which uses an algorithm similar **REVIEW: Not exactly the same? Why not?** to that of the Python package, above, to derive the state equations. It takes as arguments lists of elemental equations, constraint equations, primary variables, and input variables and returns the vector state equation, state variables, and the time-derivative of the state variables.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The functions available in Mathematica allow a simpler and more elegant package to be written.


The `outputEquations` function derives the output equations given output expressions in terms of primary and secondary variables (including inputs). The function accepts lists of input variables, state variables, elemental and constraint equations, and output expressions.

The functions `stateEquations` and `outputEquations` yield what are in general *nonlinear* state and output equations. Linear state and output equations are typically written in a standard vector form described by matrices `A`, `B`, `C`, and `D` (and sometimes `E` and `F`). The `linearizeState` function accepts lists of input variables, state variables, and the time-derivatives of the state vector (from `stateEquations`) and returns the `A`, `B`, and `E` matrices. Similarly, `linearizeOutput` returns the `C`, `D`, and `F` matrices.
The functions `stateEquations` and `outputEquations` yield what are in general *nonlinear* state and output equations. Linear state and output equations are typically written in a standard vector form described by matrices `A`, `B`, `C`, and `D` (and sometimes `E` and `F`) **REVIEW: Please provide a reference.**. The `linearizeState` function accepts lists of input variables, state variables, and the time-derivatives of the state vector (from `stateEquations`) and returns the `A`, `B`, and `E` matrices. Similarly, `linearizeOutput` returns the `C`, `D`, and `F` matrices.

A detailed example of how to use the Mathematica StateMint package is [included](https://github.com/CameronDevine/StateMint/blob/master/mathematica/Example.nb) in the StateMint repository.
This package is best used by those who are already familiar with Mathematica, or for more complex problems where Mathematica may perform better than SymPy.
This package is best used by those who are already familiar with Mathematica, or for more complex problems where Mathematica may perform better than SymPy **REVIEW: Do you have any evidence or citations for this claim?**.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do not have any evidence or citations for this claim.


# Acknowledgments

Expand Down
6 changes: 3 additions & 3 deletions python/Example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"source": [
"# StateMint\n",
"\n",
"There are two methods for using StateMint, one is to install the python package on your computer and to write python scripts solve and interact with the solution. The other is to use the web interface. This notebook will focus on how to interact with StateMint in a python script.\n",
"There are two methods for using StateMint, one is to install the python package on your computer and to write python scripts to solve and interact with the solution. The other is to use the web interface. This notebook will focus on how to interact with StateMint in a python script.\n",
"\n",
"Before we begin we need to import a few libraries, including `StateMint`."
]
Expand All @@ -30,7 +30,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Now that the required libraries have been imported we can start working on a problem. In this case we will be working on the problem set forth in the [tutorial](https://github.com/CameronDevine/StateMint/blob/tutorial/tutorial.md). This problem consists of a motor powering a pump through a flexible shaft. This pump pushes water through an enbow with a known resistance and out into the atmosphere. A diagram of the physical system can be seen below,"
"Now that the required libraries have been imported we can start working on a problem. In this case we will be working on the problem set forth in the [tutorial](https://github.com/CameronDevine/StateMint/blob/tutorial/tutorial.md). This problem consists of a motor powering a pump through a flexible shaft. This pump pushes water through an elbow with a known resistance and out into the atmosphere. A diagram of the physical system can be seen below,"
]
},
{
Expand Down Expand Up @@ -98,7 +98,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Now that the solution has been found, different parts of the equation can be viewed including the $A$ matrix,"
"Now that the solution has been found, different parts of the equation can be viewed, including the $A$ matrix,"
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion web/HTML/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ <h1 class="text-center">StateMint</h1>
<p class="text-center">
View some
<a style="color:rgb(60,104,255);" onclick="showExamples()"><strong>examples</strong></a>
or an in depth
or an in-depth
<a style="color:rgb(60,104,255);" data-toggle="modal" data-target="#tutorialRef" onclick="tutorial()"><strong>tutorial</strong></a>.
</p>
</section>
Expand Down
42 changes: 21 additions & 21 deletions web/HTML/tutorial/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This method of finding a differential equation of a dynamic system works with mu

### System Types

In each energy domain a through-variable, $v$, and an across-variable, $f$, is defined.
In each energy domain, a through-variable, $v$, and an across-variable, $f$, is defined.
A through-variable is a variable that generally has the same value at each element terminal.
It corresponds to a physical quantity that would be measured flowing through an element.
An across-variable is a variable that generally has a different value at each element terminal.
Expand All @@ -27,12 +27,12 @@ A list of common system types and their through-variables and across-variables c

### Elemental Equations

Within each energy domain there are multiple element types which can be used to model a system in that domain.
Across energy domains these elements can be grouped into three distinct types.
Within each energy domain, there are multiple element types which can be used to model a system in that domain.
Across energy domains, these elements can be grouped into three distinct types.

#### A Type Elements

A type elements are energy storage elements which relates the rate of change of the across-variable to the through-variable of the element.
A type elements are energy storage elements which relate the rate of change of the across-variable to the through-variable of the element.

| System Type | Element | Elemental Equation | Parameter
| ------------- | ------------------- | -------------------------- | ---------
Expand Down Expand Up @@ -103,37 +103,37 @@ The following elements can be modeled as gyrators,

Linear graph representations of systems use "nodes" and connecting "branches" to diagram a system.
Each node represents an independent across-variable value.
Branches are created for each element in the system.
In non electrical systems A type elements always connect to a ground node.
Branches are created for each element in the system. **REVIEW: Could you explain this idea more?**
In non-electrical systems, A type elements always connect to a ground node.
Arrows on branches point in the direction of decreasing across-variable.
Arrows on transformers and gyrators always point towards ground.
An example of a linear graph appears in the Example section of this tutorial.

### Normal Trees

In order to find the primary and secondary variables a normal tree can be constructed.
In order to find the primary and secondary variables **REVIEW: You have not yet defined primary and secondary variables**, a normal tree can be constructed.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are defined in the next section. It would be difficult to define these terms without first discussing the normal tree.

This normal tree should consist of $N-1$ branches from the linear graph where $N$ is the number of nodes in the linear graph.
If multiple ground nodes are present in the linear graph they should be counted as a single node.
Since the normal tree must be a tree structure no loops may be created when constructing the normal tree.
To construct the normal tree select branches in the following order.
If multiple ground nodes are present in the linear graph, they should be counted as a single node.
Since the normal tree must be a tree structure, no loops may be created when constructing the normal tree.
To construct the normal tree, select branches in the following order.

1. Across-variable sources
1. Across-variable sources **REVIEW: You have not defined source.**
2. A type elements
3. Transformers and Gyrators (minimizing the number of T type elements in the normal tree)
4. D type elements
5. T type elements

For transformers one branch must be selected, and for gyrators both or neither branches can be selected.
For transformers, one branch must be selected. For gyrators, both or neither branches can be selected.
The elements in the normal tree are termed normal tree branches, while the elements not in the normal tree are called normal tree links.

### Primary and Secondary Variables

Once the normal tree has been created it is trivial to determine the primary and secondary variables. These are defined as,
Once the normal tree has been created, it is trivial to determine the primary and secondary variables. Primary variables are defined as,

* Across-variables on normal tree branches and
* Through-variables on normal tree links.

For each element the secondary variable is the non primary variable. In other words the secondary variables are,
For each element, the secondary variable is the non-primary variable. In other words the secondary variables are,

* Across-variables on normal tree links
* Through-variables on normal tree branches
Expand All @@ -147,8 +147,8 @@ The state variables of the system are,

### Elemental Equations

We define $B$ as the number of branches in the linear graph and $S$ as the number of sources. **REVIEW: What is a source?**
$B-S$ elemental equations should be written with the primary variable on the left hand side.
Here $B$ is the number of branches in the linear graph and $S$ is the number of sources.

### Continuity Equations

Expand Down Expand Up @@ -191,7 +191,7 @@ Also adding both sides of the gyrator means that adding the torsional spring wou

![Normal Tree](tutorial/tutorial6.svg)

Next a the motor resistance is added.
Next, the motor resistance is added.

![Normal Tree](tutorial/tutorial7.svg)

Expand All @@ -215,7 +215,7 @@ $Q_R$

### Secondary Variables

Given the primary variables above the following are easily determined to be secondary variables.
Given the primary variables above, the following are easily determined to be secondary variables.

$i_s$,
$i_R$,
Expand All @@ -235,7 +235,7 @@ $\tau_k$

### Elemental Equations

Based on the list of elemental equations the following list of elemental equations can be generated.
Based on the list of elemental equations, the following list of elemental equations can be generated.

* $v_R=Ri_R$
* $v_L=Li_L'$
Expand All @@ -248,11 +248,11 @@ Based on the list of elemental equations the following list of elemental equatio

### Continuity Equations

To determine the continuity equations the following contours can be drawn.
To determine the continuity equations, the following contours can be drawn.

![Normal Tree](tutorial/tutorial9.svg)

Using these contours the equations below were constructed.
Using these contours, the equations below were constructed.

* $i_L=i_1$
* $i_R=i_1$
Expand All @@ -270,7 +270,7 @@ By adding each link into the normal tree the equations below were generated.

## Using the Software

Given these equations the state equation could be found by hand, or one of the following tools could be used.
Given these equations, the state equation could be found by hand, or by using one of the following tools.

### Web Interface

Expand Down