Skip to content

Commit 009b497

Browse files
authored
Merge pull request #152 from alhirzel/improvements-modeling-documentation
Some work on tutorial
2 parents 8268e1d + 40c1b34 commit 009b497

File tree

1 file changed

+32
-17
lines changed

1 file changed

+32
-17
lines changed

docs/src/tutorial/Modeling.md

Lines changed: 32 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,25 +25,31 @@ LowPassFilter = Model(
2525
equations = :[T * der(x) + x = u],
2626
)
2727
```
28-
The symbols `input` and `output` refer to predefined variable constructors to define the input and output variables. If an equation has just a unique variable in the left hand side, `y`, the right hand side can be given as a quoted expression in a Var-constructor `Var(:x)` after the `output` constructor combined with the merge operator, `|`, see below.
28+
29+
The symbols `input` and `output` refer to predefined variable constructors to define the input and output variables.
30+
If an equation has just a unique variable in the left hand side, `y`, the right hand side can be given as a quoted expression in a Var-constructor `Var(:x)` after the `output` constructor combined with the merge operator, `|`, see below.
2931

3032
## 2.2 Merging models
3133

32-
It is possible to combine models by merging. If we want to change the model to become a highpass filter, an alternative output equation
34+
It is possible to combine models by merging.
35+
If we want to change the model to become a high-pass filter, an alternative output equation
3336

3437
```math
3538
y = -x + u
3639
```
3740

38-
is defined in an anonymous model `Model( y = :(-x + u) )`. This anonymous model is merged with `LowPassFilter` using the merge operator `|`:
41+
is defined in an anonymous model `Model( y = :(-x + u) )`.
42+
This anonymous model is merged with `LowPassFilter` using the merge operator `|`:
3943

4044
```julia
4145
HighPassFilter = LowPassFilter | Model( y = Var(:(-x + u) ) )
4246
```
4347

4448
The merging implies that the `output` property of `y` is kept, but the binding expression is changed from `:x` to `:(-x + u)`.
4549

46-
In general, recursive merging is desired and Modia provides a `mergeModels` function for that (see appendix [A.3 MergeModels algorithm](@ref)). This function is invoked as a binary operator `|` (also used for merge in Python). Note, that the order of the arguments/operands are important.
50+
In general, recursive merging is desired and Modia provides a `mergeModels` function for that (see appendix [A.3 MergeModels algorithm](@ref)).
51+
This function is invoked as a binary operator `|` (also used for merge in Python).
52+
Note, that the order of the arguments/operands are important.
4753

4854
Generalizing the block to have two outputs for both low and high pass filtering would be done as follows:
4955

@@ -108,7 +114,9 @@ LowAndHighPassFilter = Model(
108114

109115
## 2.3 Functions and tables
110116

111-
In order to test an input/output block as defined in the previous section, an input needs to be defined. This can be made by adding an equation for `u`. Assume we want `u` to be sinousoidial with an increasing frequency:
117+
In order to test an input/output block as defined in the previous section, an input needs to be defined.
118+
This can be made by adding an equation for `u`.
119+
Assume we want `u` to be sinusoidal with an increasing frequency:
112120

113121
```julia
114122
TestLowAndHighPassFilter = LowAndHighPassFilter | Model(
@@ -117,7 +125,14 @@ TestLowAndHighPassFilter = LowAndHighPassFilter | Model(
117125
)
118126
```
119127

120-
`time` is a reserved name for the independent variable. It has unit `s` for seconds. The Julia package [Unitful](https://painterqubits.github.io/Unitful.jl/stable/) provides a means for defining units and managing unit inference. It need not be explicitly defined, because its symbols are exported by `using Modia`. Definition of units is done with a string macro `u"..."`. In this case, the input signal was given unit Volt. The state x must then also have consistent unit, that is Volt. If the model equations contain systems of simultaneous equations, then approximate guess values, optionally with units, must be given `start`: `i = Var(start=0.0u"A")`.
128+
`time` is a reserved name for the independent variable.
129+
It has unit `s` for seconds.
130+
The Julia package [Unitful](https://painterqubits.github.io/Unitful.jl/stable/) provides a means for defining units and managing unit inference.
131+
It need not be explicitly defined, because its symbols are exported by `using Modia`.
132+
Definition of units is done with a string macro `u"..."`.
133+
In this case, the input signal was given unit Volt.
134+
The state `x` must then also have consistent unit, that is Volt.
135+
If the model equations contain systems of simultaneous equations, then approximate guess values, optionally with units, must be given `start`: `i = Var(start=0.0u"A")`.
121136

122137
The input signal can also be defined by interpolation in a table:
123138

@@ -128,7 +143,7 @@ table = CubicSplineInterpolation(0:0.5:2.0, [0.0, 0.7, 2.0, 1.8, 1.2])
128143
TestLowAndHighPassFilter2 = TestLowAndHighPassFilter | Map(u = :(table(time*u"1/s")*u"V"))
129144
```
130145

131-
It is possible to call Julia functions that have more as one return argument:
146+
It is possible to call Julia functions that have more than one return argument:
132147

133148
```julia
134149
function ref(time)
@@ -146,7 +161,7 @@ TestMultiReturningFunction1 = Model(
146161
```
147162

148163
The returned arguments are typically numbers or arrays (see below).
149-
It is also possible to return an instance of a struct and, say,
164+
It is also possible to return an instance of a `struct` and, say,
150165
pass this instance as input to another function call.
151166

152167
It is currently not supported that a function call modifies one of its arguments,
@@ -168,7 +183,7 @@ Hierarchical models are obtained if the values themselves are `Models`, i.e. dic
168183
A model with two filters can, for example, be defined as follows:
169184

170185
```julia
171-
TwoFilters = (
186+
TwoFilters = Model(
172187
high = HighPassFilter,
173188
low = LowPassFilter,
174189
)
@@ -179,7 +194,7 @@ Note, that the previous definitions of `HighPassFilter` and `LowPassFilter` was
179194
A band pass filter is a series connection of a high pass filter and a low pass filter and can be described as:
180195

181196
```julia
182-
BandPassFilter = (
197+
BandPassFilter = Model(
183198
u = input,
184199
y = output,
185200
high = HighPassFilter | Map(T=0.5, x=Var(init=0.1u"V")),
@@ -257,7 +272,7 @@ Various physical components sometimes share common properties.
257272
One mechanism to handle this is to use inheritance.
258273
In Modia, **merging** is used.
259274

260-
Electrical components such as resistors, capacitors and inductors are categorized as oneports which have two pins.
275+
Electrical components such as resistors, capacitors and inductors are categorized as `OnePort`s which have two `Pin`s.
261276
Common properties are: constraint on currents at the pins and definitions of voltage over the component and current through the component.
262277

263278
```julia
@@ -343,7 +358,7 @@ Having the above electrical component models, enables defining a filter
343358
by instantiating components, setting parameters and defining connections.
344359

345360
```julia
346-
Filter = (
361+
Filter = Model(
347362
R = Resistor | Map(R=0.5u"Ω"),
348363
C = Capacitor | Map(C=2.0u"F"),
349364
V = ConstantVoltage | Map(V=10.0u"V"),
@@ -397,7 +412,7 @@ TwoFilters = Model( f1 = Filter | Map( r = 10.0, c = 2.0), f2 = Filter )
397412

398413
### 2.5.7 Re-declarations
399414

400-
It is possible to reuse a particular model topology by redeclaring the models of particular components.
415+
It is possible to reuse a particular model topology by re-declaring the models of particular components.
401416
For example, changing the filter `f1` to a voltage divider by changing `C` from a Capacitor to a Resistor.
402417
A predefined definition `redeclare` is used for this purpose.
403418

@@ -470,7 +485,7 @@ SecondOrder = Model(
470485
Variables `sys.u` and `sys.y` are vectors with one element each.
471486

472487
Note, `[0; w^2]` is a vector in Julia and not a column matrix.
473-
In order that `B` is defined as column matrix, the Julia 1.7 feature is used to append two semikolons, that is,
488+
In order that `B` is defined as column matrix, the Julia 1.7 feature is used to append two semicolons, that is,
474489
`[0; w^2;;]`
475490

476491
Array equations remain array equations during symbolic transformation and in the generated code,
@@ -497,8 +512,8 @@ equations = :[
497512
]
498513
```
499514

500-
When the init or start value of an array variable is defined as a [StaticArrays](https://github.com/JuliaArrays/StaticArrays.jl) array,
501-
then the value of this array remains to be a StaticArrays variable also in the generated code.
515+
When the `init` or `start` value of an array variable is defined as a [StaticArrays.jl `StaticArray`](https://github.com/JuliaArrays/StaticArrays.jl),
516+
then the type of this array variable will be `StaticArray` in the generated code.
502517
The benefit is that array operations are more efficient:
503518

504519
```julia
@@ -537,7 +552,7 @@ plot(testArray2, "v", figure=5)
537552
538553
## 2.7 Model libraries
539554
540-
Modia provides a small set of pre-defined model components in directory `Modia.modelsPath`:
555+
Modia provides a small set of predefined model components in directory `Modia.modelsPath`:
541556
542557
- `AllModels.jl` - Include all model libraries
543558
- `Blocks.jl` - Input/output control blocks

0 commit comments

Comments
 (0)