You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/SciML/ColPrac)
9
+
[](https://github.com/SciML/ColPrac)
Copy file name to clipboardExpand all lines: docs/src/API/linear_analysis.md
+39-17Lines changed: 39 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -1,40 +1,48 @@
1
1
# Linear Analysis
2
2
3
3
!!! danger "Experimental"
4
-
The interface described here is currently experimental and at any time subject to breaking changes not respecting semantic versioning.
4
+
5
+
The interface described here is currently experimental and at any time subject to breaking changes not respecting semantic versioning.
5
6
6
7
Linear analysis refers to the process of linearizing a nonlinear model and analysing the resulting linear dynamical system. To facilitate linear analysis, ModelingToolkitStandardLibrary provides the concept of an [`AnalysisPoint`](@ref), which can be inserted in-between two causal blocks (such as those from the `Blocks` sub module). Once a model containing analysis points is built, several operations are available:
7
8
8
-
-[`get_sensitivity`](@ref) get the [sensitivity function (wiki)](https://en.wikipedia.org/wiki/Sensitivity_(control_systems)), $S(s)$, as defined in the field of control theory.
9
-
-[`get_comp_sensitivity`](@ref) get the complementary sensitivity function $T(s) : S(s)+T(s)=1$.
10
-
-[`get_looptransfer`](@ref) get the (open) loop-transfer function where the loop starts and ends in the analysis point. For a typical simple feedback connection with a plant $P(s)$ and a controller $C(s)$, the loop-transfer function at the plant output is $P(s)C(s)$.
11
-
-[`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearized system.
12
-
-[`open_loop`](@ref) return a new (nonlinear) system where the loop has been broken in the analysis point, i.e., the connection the analysis point usually implies has been removed.
9
+
-[`get_sensitivity`](@ref) get the [sensitivity function (wiki)](https://en.wikipedia.org/wiki/Sensitivity_(control_systems)), $S(s)$, as defined in the field of control theory.
10
+
-[`get_comp_sensitivity`](@ref) get the complementary sensitivity function $T(s) : S(s)+T(s)=1$.
11
+
-[`get_looptransfer`](@ref) get the (open) loop-transfer function where the loop starts and ends in the analysis point. For a typical simple feedback connection with a plant $P(s)$ and a controller $C(s)$, the loop-transfer function at the plant output is $P(s)C(s)$.
12
+
-[`linearize`](@ref) can be called with two analysis points denoting the input and output of the linearized system.
13
+
-[`open_loop`](@ref) return a new (nonlinear) system where the loop has been broken in the analysis point, i.e., the connection the analysis point usually implies has been removed.
13
14
14
15
An analysis point can be created explicitly using the constructor [`AnalysisPoint`](@ref), or automatically when connecting two causal components using `connect`:
Analysis points are *causal*, i.e., they imply a directionality for the flow of information. The order of the connections in the connect statement is thus important, i.e., `connect(out, :name, in)` is different from `connect(in, :name, out)`.
21
22
23
+
Analysis points are *causal*, i.e., they imply a directionality for the flow of information. The order of the connections in the connect statement is thus important, i.e., `connect(out, :name, in)` is different from `connect(in, :name, out)`.
24
+
22
25
The directionality of an analysis point can be thought of as an arrow in a block diagram, where the name of the analysis point applies to the arrow itself.
26
+
23
27
```
24
28
┌─────┐ ┌─────┐
25
29
│ │ name │ │
26
30
│ out├────────►│in │
27
31
│ │ │ │
28
32
└─────┘ └─────┘
29
33
```
34
+
30
35
This is signified by the name being the middle argument to `connect`.
31
36
32
37
Of the above mentioned functions, all except for [`open_loop`](@ref) return the output of [`ModelingToolkit.linearize`](@ref), which is
38
+
33
39
```julia
34
40
matrices, simplified_sys =linearize(...)
35
41
# matrices = (; A, B, C, D)
36
42
```
43
+
37
44
i.e., `matrices` is a named tuple containing the matrices of a linear state-space system on the form
45
+
38
46
```math
39
47
\begin{aligned}
40
48
\dot x &= Ax + Bu\\
@@ -43,29 +51,31 @@ y &= Cx + Du
43
51
```
44
52
45
53
## Example
54
+
46
55
The following example builds a simple closed-loop system with a plant $P$ and a controller $C$. Two analysis points are inserted, one before and one after $P$. We then derive a number of sensitivity functions and show the corresponding code using the package ControlSystemBase.jl
47
56
48
57
```@example LINEAR_ANALYSIS
49
58
using ModelingToolkitStandardLibrary.Blocks, ModelingToolkit
50
-
@named P = FirstOrder(k=1, T=1) # A first-order system with pole in -1
59
+
@named P = FirstOrder(k = 1, T = 1) # A first-order system with pole in -1
51
60
@named C = Gain(-1) # A P controller
52
61
t = ModelingToolkit.get_iv(P)
53
-
eqs = [
54
-
connect(P.output, :plant_output, C.input) # Connect with an automatically created analysis point called :plant_output
55
-
connect(C.output, :plant_input, P.input) # Connect with an automatically created analysis point called :plant_input
this particular transfer function should be equivalent to the linear system `P(s)S(s)`, i.e., equivalent to
112
+
99
113
```@example LINEAR_ANALYSIS_CS
100
114
feedback(P, C)
101
115
```
102
116
103
117
### Obtaining transfer functions
118
+
104
119
A statespace system from [ControlSystemsBase](https://juliacontrol.github.io/ControlSystems.jl/stable/man/creating_systems/) can be converted to a transfer function using the function `tf`:
120
+
105
121
```@example LINEAR_ANALYSIS_CS
106
122
tf(S)
107
123
```
108
124
109
125
## Gain and phase margins
126
+
110
127
Further linear analysis can be performed using the [analysis methods from ControlSystemsBase](https://juliacontrol.github.io/ControlSystems.jl/stable/lib/analysis/). For example, calculating the gain and phase margins of a system can be done using
128
+
111
129
```@example LINEAR_ANALYSIS_CS
112
130
margin(P)
113
131
```
114
-
(they are infinite for this system). A Nyquist plot can be produced using
132
+
133
+
(they are infinite for this system). A Nyquist plot can be produced using
0 commit comments