Skip to content

Commit 84d0c31

Browse files
MartinOtterMartinOtter
committed
Docu adapted and improved.
1 parent 22ffbc2 commit 84d0c31

File tree

14 files changed

+295
-241
lines changed

14 files changed

+295
-241
lines changed

‎README.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ The [Modia Tutorial](https://modiasim.github.io/Modia.jl/stable/tutorial/Getting
77
The [Modia3D Tutorial](https://modiasim.github.io/Modia3D.jl/stable/tutorial/GettingStarted.html) provides an introduction to use 3D components in Modia.
88
Modia is part of [ModiaSim](https://modiasim.github.io/docs/).
99

10-
[Modia](https://github.com/ModiaSim/Modia.jl) is an environment in form of a Julia package to model and simulate physical systems (electrical, mechanical, thermo-dynamical, etc.) described by differential and algebraic equations. A user defines a model on a high level with model components (like a mechanical body, an electrical resistance, or a pipe) that are physically connected together. A model component is constructed by **`expression = expression` equations** or by Julia structs/functions, such as the pre-defined Modia 3D-mechanical components. The defined model is symbolically processed (for example, equations might be analytically differentiated) with algorithms from package [ModiaBase.jl](https://github.com/ModiaSim/ModiaBase.jl). From the transformed model a Julia function is generated that is used to simulate the model with integrators from [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl).
10+
[Modia](https://github.com/ModiaSim/Modia.jl) is an environment in form of a Julia package to model and simulate physical systems (electrical, mechanical, thermo-dynamical, etc.) described by differential and algebraic equations. A user defines a model on a high level with model components (like a mechanical body, an electrical resistance, or a pipe) that are physically connected together. A model component is constructed by **`expression = expression` equations** or by Julia structs/functions, such as the pre-defined [Modia3D] (https://github.com/ModiaSim/Modia3D.jl) multibody components. The defined model is symbolically processed (for example, equations might be analytically differentiated) with algorithms from package [ModiaBase.jl](https://github.com/ModiaSim/ModiaBase.jl). From the transformed model a Julia function is generated that is used to simulate the model with integrators from [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl).
1111
The basic type of the floating point variables is usually `Float64`, but can be set to any
12-
type `FloatType<:AbstractFloat` via `@instantiateModel(..., FloatType = xxx)`, for example
12+
type `FloatType <: AbstractFloat` via `@instantiateModel(..., FloatType = xxx)`, for example
1313
it can be set to `Float32, DoubleFloat, Measurement{Float64}, StaticParticles{Float64,100}`.
1414

1515
## Installation
@@ -24,16 +24,22 @@ Furthermore, one or more of the following packages should be installed in order
2424
to be able to generate plots:
2525

2626
```julia
27-
julia> ]add ModiaPlot_PyPlot # if plotting with PyPlot desired
28-
add ModiaPlot_GLMakie # if plotting with GLMakie desired
29-
add ModiaPlot_WGLMakie # if plotting with WGLMakie desired
30-
add ModiaPlot_CairoMakie # if plotting with CairoMakie desired
27+
julia> ]add SignalTablesInterface_PyPlot # if plotting with PyPlot desired
28+
29+
# currently under registration
30+
add SignalTablesInterface_GLMakie # if plotting with GLMakie desired
31+
add SignalTablesInterface_WGLMakie # if plotting with WGLMakie desired
32+
add SignalTablesInterface_CairoMakie # if plotting with CairoMakie desired
3133
```
3234

35+
or call `t = getValues(instantiatedModel, "time"), y = getValues(instantiatedModel, "y")` to retrieve
36+
the results in form of vectors and arrays and use any desired plot package for plotting, e.g., `plot(t,y)`.
37+
3338
Note, Modia reexports the following definitions
3439

3540
- `using Unitful`
3641
- `using DifferentialEquations`
42+
- `using SignalTables`
3743
- and exports functions `CVODE_BDF` and `IDA` of [Sundials.jl](https://github.com/SciML/Sundials.jl).
3844

3945
As a result, it is usually sufficient to have `using Modia` in a model to utilize the relevant

‎docs/src/Functions.md‎

Lines changed: 35 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -54,79 +54,62 @@ showEvaluatedParameters
5454
```
5555

5656

57-
## Results
57+
## Results and Plotting
5858

5959
```@meta
6060
CurrentModule = Modia
6161
```
6262

63-
The simulation result of a model `instantiatedModel` are provided as *signal table*
64-
(see [SignalTables.jl]()).
65-
Therefore, all functions[SignalTables.jl functions] can be used.
66-
These functions
67-
[ModiaResult](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html) and
68-
exports them, so the functions can be accessed without prefixing them with `Modia`.
63+
The simulation result of a model `instantiatedModel` are provided as a *signal table*,
64+
see [SignalTables.jl](https://github.com/ModiaSim/SignalTables.jl).
6965

70-
The following functions are provided to access **Modia results**
71-
(use `ìnstantiatedModel` as argument `result`, e.g. `printResultInfo(instantiatedModel)`):
66+
Therefore, all [signal table functions](https://modiasim.github.io/SignalTables.jl/stable/Functions/OverviewOfFunctions.html)
67+
can be used on a simulated model, for example:
7268

73-
| Functions | Description |
74-
|:---------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------|
75-
| [`printResultInfo` ](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.printResultInfo) | Print info of the result on stdout. |
76-
| [`resultInfo`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.resultInfo) | Return info about the result as [DataFrame](https://github.com/JuliaData/DataFrames.jl) table |
77-
| [`rawSignal`](https://modiasim.github.io/ModiaResult.jl/stable/AbstractInterface.html#ModiaResult.rawSignal) | Return raw signal data given the signal name. |
78-
| [`getPlotSignal`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.getPlotSignal) | Return signal data prepared for a plot package. |
79-
| [`signalNames`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.signalNames) | Return all signal names. |
80-
| [`timeSignalName`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.timeSignalName) | Return the name of the time signal. |
81-
| [`hasOneTimeSignal`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.hasOneTimeSignal) | Return true if one time signal present. |
82-
| [`hasSignal`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.hasSignal) | Return true if a signal name is known. |
83-
| [`getLastValue`](@ref) | Return last available value of variable name |
84-
| [`defaultHeading`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.defaultHeading`) | Return default heading of a result. |
85-
86-
87-
## Plotting
88-
89-
```@meta
90-
CurrentModule = Modia
9169
```
70+
using Modia
9271
93-
The simulation result of a model `instantiatedModel` supports the functions of
94-
[ModiaResult](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html) and
95-
exports them, so the functions can be accessed without prefixing them with `Modia`.
96-
97-
The following functions are provided to **define/inquire the current plot package**:
72+
FirstOrder = Model(
73+
T = 0.2u"s",
74+
x = Var(init=0.3),
75+
equations = :[u = sin(time/u"s")
76+
T * der(x) + x = u
77+
y = 2*x]
78+
)
79+
simulate!(firstOrder, stopTime=10)
80+
showInfo(firstOrder) # list info about the result
81+
t = getValues(firstOrder, "time")
82+
y = getValues(firstOrder, "y") # use any plot program: plot(t,y)
83+
84+
# Write result on file
85+
writeSignalTable("firstOrder.json", firstOrder, indent=2, log=true)
86+
```
9887

99-
| Functions | Description |
100-
|:-------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------|
101-
| [`@usingModiaPlot`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.@usingModiaPlot) | Expands into `using ModiaPlot_<PlotPackageName>` |
102-
| [`usePlotPackage`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.usePlotPackage) | Define the plot package to be used. |
103-
| [`usePreviousPlotPackage`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.usePreviousPlotPackage) | Define the previously defined plot package to be used. |
104-
| [`currentPlotPackage`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaResult.currentPlotPackage) | Return name defined with `usePlotPackage` |
88+
See the generated [json-file](../resources/fileio/firstOrder.json).
10589

106-
The following functions are available after
90+
For plotting, a plot package must be installed, e.g.,
10791

108-
1. `ENV["MODIA_PLOT"] = XXX` (e.g. in startup.jl file) or
109-
`usePlotPackage(XXX)` has been executed (XXX = "PyPlot", "GLMakie", "WGLMakie", "CairoMakie", "NoPlot" or "SilentNoPlot") and
110-
2. `@usingModiaPlot` has been called,
92+
```julia
93+
julia> ]add SignalTablesInterface_PyPlot # if plotting with PyPlot desired
94+
add SignalTablesInterface_GLMakie # if plotting with GLMakie desired
95+
add SignalTablesInterface_WGLMakie # if plotting with WGLMakie desired
96+
add SignalTablesInterface_CairoMakie # if plotting with CairoMakie desired
97+
```
11198

112-
to **plot with the currently defined plot package**
113-
(use `ìnstantiatedModel` as argument `result`, e.g. `plot(instantiatedModel, ...)`):
99+
In a model, the desired plot package is defined with:
114100

115-
| Functions | Description |
116-
|:----------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------|
117-
| [`plot`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaPlot_PyPlot.plot) | Plot simulation results in multiple diagrams/figures. |
118-
| [`saveFigure`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaPlot_PyPlot.saveFigure) | Save figure in different formats on file. |
119-
| [`closeFigure`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaPlot_PyPlot.closeFigure) | Close one figure |
120-
| [`closeAllFigures`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaPlot_PyPlot.closeAllFigures) | Close all figures |
121-
| [`showFigure`](https://modiasim.github.io/ModiaResult.jl/stable/Functions.html#ModiaPlot_PyPlot.showFigure) | Show figure in window (only GLMakie, WGLMakie) |
101+
```julia
102+
using Modia
103+
usePlotPackage("PyPlot") # or ENV["SignalTablesPlotPackage"] = "PyPlot"
104+
```
122105

123106
A Modia variable `a.b.c` is identified by a String key `"a.b.c"`.
124107
The legends/labels of the plots are automatically constructed by the
125108
names and units of the variables. Example:
126109

127110
```julia
128111
using Modia
129-
@usingModiaPlot
112+
@usingPlotPackage # execute `using SignalTablesInterface_XXX`
130113

131114
instantiatedModel = @instantiateModel(...)
132115
simulate!(instantiatedModel, ...)

‎docs/src/Internal.md‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,24 @@ SimulationModel
1717
generate_getDerivatives!
1818
init!
1919
outputs!
20+
terminate!
21+
derivatives!
22+
DAEresidualsForODE!
23+
affectEvent!
24+
zeroCrossings!
25+
affectStateEvent!
26+
timeEventCondition!
27+
affectTimeEvent!
2028
addToResult!
2129
getFloatType
22-
baseType
2330
measurementToString
2431
```
2532

2633
## Inquiries in Model
2734

35+
The functions in this section can be called in the model code or in
36+
functions that are called from the model code.
37+
2838
```@docs
2939
isInitial
3040
isTerminal
@@ -34,4 +44,36 @@ isFirstEventIterationDirectlyAfterInitial
3444
isAfterSimulationStart
3545
isZeroCrossing
3646
storeResults
47+
getTime
48+
```
49+
50+
## Variable definitions in functions
51+
52+
The following functions can be used to define states and algebraic variables inside functions:
53+
54+
```@docs
55+
new_x_segmented_variable!
56+
new_w_segmented_variable!
57+
new_alias_segmented_variable!
58+
new_z_segmented_variable!
59+
get_x_startIndex_from_x_segmented_startIndex
60+
get_scalar_x_segmented_value
61+
get_SVector3_x_segmented_value
62+
get_Vector_x_segmented_value!
63+
add_der_x_segmented_value!
64+
add_w_segmented_value!
3765
```
66+
67+
68+
69+
70+
71+
72+
73+
74+
75+
76+
77+
78+
79+

0 commit comments

Comments
 (0)