Adapt docs to new ModiaLang version (0.11.2).

Author: MartinOtter

docs/src/index.md

@@ -45,11 +45,27 @@ julia> ]add Measurements, MonteCarloMeasurements, Distributions
 
 ### Version 0.6.1
 
+Non-backwards compatible changes
+
+- Equations can only be defined with key `equations` and no other key. 
+
+- Parameter values in the code are now type cast to the type of the parameter value from the 
+  `@instantiatedModel(..)` call. The benefit is that access of parameter values in the code is type stable
+  and operations with the parameter value are more efficient and at run-time no memory is allocated.
+  Existing models can no longer be simulated, if parameter values provided via `simulate!(.., merge=xx)` are not
+  type compatible to their definition. For example, an error is thrown if the @instantedModel(..) uses a Float64 value and the
+  `simulate!(.., merge=xx)` uses a `Measurement{Float64}` value for the same parameter
+
+Other changes:
+
 - See release notes of [ModiaLang](https://github.com/ModiaSim/ModiaLang.jl/releases/tag/v0.11.0) and 
   of [Modia3D](https://github.com/ModiaSim/Modia3D.jl/releases/tag/v0.9.0).
+
 - Project.toml and Manifest.toml updated due to new versions of Modia3D and ModiaLang
+
 - docu: fix some typing and formatting
 
+
 ### Version 0.6.0
 
 - Modia is restricted to Julia 1.7

docs/src/tutorial/Appendix.md

@@ -16,6 +16,8 @@ in column 2 and 3. These constants can be used as shortcuts:
 | flow       | flow      | Var(flow = true)      | If true, flow variable                             |
 | init       | --        | --                    | Initial value of ODE state (defines unit and size) |
 | start      | --        | --                    | Start value of variable (defines unit and size)    |
+| hideResult | --        | --                    | If true, the variable is not stored in the result  |
+
 
 Example:
 
@@ -99,24 +101,30 @@ Such a merge semantic allows for unification of parameter modifications and inhe
 The basics of the `mergeModels` algorithm and the merge operator `|` are defined as follows (without logging):
 
 ```julia
-function mergeModels(m1::OrderedDict, m2::OrderedDict, env=Symbol())
+function mergeModels(m1::AbstractDict, m2::AbstractDict, env=Symbol())
     result = deepcopy(m1)
     for (k,v) in m2)
-        if typeof(v) <: OrderedDict
+        if typeof(v) <: AbstractDict
             if k in keys(result) && ! (:_redeclare in keys(v))
-                result[k] = mergeModels(result[k], v, k)
+                if typeof(result[k]) <: AbstractDict
+                    result[k] = mergeModels(result[k], v, k)
+                end
             else
                 result[k] = v
             end
         elseif v === nothing
             delete!(result, k)
+        elseif k in keys(result) && k == :equations
+            equa = copy(result[k])
+            push!(equa.args, v.args...)
+            result[k] = equa
         else
             result[k] = v
         end
     end
     return result
 end
 
-|(m::OrderedDict, n::OrderedDict) =  mergeModels(m, n)
+|(m::AbstractDict, n::AbstractDict) =  mergeModels(m, n)
 
 ```

docs/src/tutorial/GettingStarted.md

@@ -9,17 +9,17 @@ T \cdot \frac{dx}{dt} + x = 1; \;\;\; x(t_0) = 0.2
 can be defined, simulated and plotted with the following commands:
 
 ```julia
-using Modia       # reexports exported symbols from 
+using Modia       # reexports exported symbols from
                   # DifferentialEquations and from Unitful
-@usingModiaPlot   # Use plot package defined with 
+@usingModiaPlot   # Use plot package defined with
                   # ENV["MODIA_PLOT"] or usePlotPackage(..)
 
 
 # Define model
 SimpleModel = Model(
     T = 0.4,
     x = Var(init=0.2),
-    equation = :[T * der(x) + x = 1],
+    equations = :[T * der(x) + x = 1],
 )
 
 # Transform to ODE form
@@ -37,7 +37,7 @@ plot(simpleModel, ("x", "der(x)"))
 
 A model is defined with a constructor `Model` taking a comma separated list of name/value pairs.
 The model consists of a definition of a parameter `T` with default value 0.2.
-Constructor `Var` with an `init` key is used to define the initial condition `0.2` of the state `x`, and one equation. Equations can have a Julia expression on both sides of the equal sign and are given as a *quoted* array expression `:[ ]` assigned to a unique identifier such as `equation`.
+Constructor `Var` with an `init` key is used to define the initial condition `0.2` of the state `x`, and one equation. Equations can have a Julia expression on both sides of the equal sign and are given as a *quoted* array expression `:[ ]` assigned to key `equations`.
 
 The macro `@instantiateModel(..)` symbolically processes the model, in particular solves the equation
 for the derivative `der(x)`, so the following equation will be used by the integrator:
@@ -51,18 +51,18 @@ returns an instance containing all the information needed for the next steps.
 
 The first [`simulate!`](@ref) function performs one simulation with the Modia default integrator
 `Sundials.CVODE_BDF()`. The second `simulate!` call defines the integrator as second argument.
-Integrator `Tsit5` is an [adaptive Runge-Kutta method of order 5/4 from Tsitouras](https://www.sciencedirect.com/science/article/pii/S0898122111004706). There are > 100 ODE integrators provided. For details, see [here](https://docs.sciml.ai/stable/solvers/ode_solve/). The simulation result is stored inside `simpleModel`.
+Integrator `Tsit5` is an [adaptive Runge-Kutta method of order 5/4 from Tsitouras](https://www.sciencedirect.com/science/article/pii/S0898122111004706). There are > 100 ODE integrators provided. For details, see [here](https://diffeq.sciml.ai/stable/solvers/ode_solve/). The simulation result is stored inside `simpleModel`.
 
 Function call `plot(..)` produces a line plot. Variables to be plotted
 are defined as tuples or arrays of variable names. Tuples are displayed in one diagram. A Vector or
-matrix of tuples or strings are displayed as vector or matrix of diagrams. 
-When `ENV["MODIA_PLOT"] = "GLMakie"` is set, then command `plot(..)` produces the following image 
+matrix of tuples or strings are displayed as vector or matrix of diagrams.
+When `ENV["MODIA_PLOT"] = "GLMakie"` is set, then command `plot(..)` produces the following image
 
 ![SimpleModel Plot](../../resources/images/SimpleModel_GLMakie.png)
 
 When `ENV["MODIA_PLOT"] = "PyPlot"` is set, the following image is produced:
 
 ![SimpleModel Plot](../../resources/images/SimpleModel_PyPlot.png)
 
-Note, the tool bar of PyPlot provides various interactive commands, for example to zoom into the 
+Note, the tool bar of PyPlot provides various interactive commands, for example to zoom into the
 plot or to store the plot in different formats on file (for example in `png` or `svg` format).

docs/src/tutorial/Modeling.md

@@ -22,7 +22,7 @@ LowPassFilter = Model(
     u = input,
     y = output | Var(:x),
     x = Var(init=0),
-    equation = :[T * der(x) + x = u],
+    equations = :[T * der(x) + x = u],
 )
 ```
 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.
@@ -128,28 +128,39 @@ table = CubicSplineInterpolation(0:0.5:2.0, [0.0, 0.7, 2.0, 1.8, 1.2])
 TestLowAndHighPassFilter2 = TestLowAndHighPassFilter | Map(u = :(table(time*u"1/s")*u"V"))
 ```
 
-A function cannot return more as one variable and a function cannot modify
-one of its arguments:
+It is possible to call Julia functions that have more as one return argument:
 
-```
-equations = :[
-    (y1, y1) = fc1(u1,u2)      # Error: Two return arguments
-    fc2!(u,y)                  # Error: Not known that fc2! computes y
-    println("This is a test")  # Fine
-]
+```julia
+function ref(time)
+    y1 = sin(time)
+    y2 = cos(time)
+    return (y1,y2)
+end
+
+TestMultiReturningFunction1 = Model(
+    equations = :[
+        (y1,y2) = ref(time)
+        y3 = y1+y2
+    ]
+)
 ```
 
-The first issue can be fixed by rewriting the function call:
+The returned arguments are typically numbers or arrays (see below).
+It is also possible to return an instance of a struct and, say,
+pass this instance as input to another function call.
+
+However, it is currently not supported that a function call modifies one of its arguments,
+or that a function call returns no argument at all:
 
 ```
 equations = :[
-    v  = fc1(u1,u2)
-    y1 = v[1]
-    y2 = v[2]
+    fc!(u,y)                   # Error: Not known that fc! computes y
+    println("This is a test")  # Error: One equation is introduced but no unknown
 ]
 ```
 
 
+
 ## 2.4 Hierarchical modeling
 
 So far, the composition of models has resulted in dictionaries of key/value pairs with values being numeric values or quoted expressions.
@@ -262,13 +273,13 @@ OnePort = Model(
 Having such a `OnePort` definition makes it convenient to define electrical component models by merging `OnePort` with specific parameter definitions with default values and equations:
 
 ```julia
-Resistor = OnePort | Model( R = 1.0u"Ω", equation = :[ R*i = v ], )
+Resistor = OnePort | Model( R = 1.0u"Ω", equations = :[ R*i = v ], )
 
-Capacitor = OnePort | Model( C = 1.0u"F", v=Map(init=0.0u"V"), equation = :[ C*der(v) = i ] )
+Capacitor = OnePort | Model( C = 1.0u"F", v=Map(init=0.0u"V"), equations = :[ C*der(v) = i ] )
 
-Inductor = OnePort | Model( L = 1.0u"H", i=Map(init=0.0u"A"), equation = :[ L*der(i) = v ] )
+Inductor = OnePort | Model( L = 1.0u"H", i=Map(init=0.0u"A"), equations = :[ L*der(i) = v ] )
 
-ConstantVoltage = OnePort | Model( V = 1.0u"V", equation = :[ v = V ] )
+ConstantVoltage = OnePort | Model( V = 1.0u"V", equations = :[ v = V ] )
 ```
 
 The merged `Resistor` is shown below:
@@ -288,6 +299,9 @@ Resistor = Model(
 ),
 ```
 
+Note, there is a special merge-rule that the vectors of keys `equations` are appended.
+
+
 ### 2.5.4 Connections
 
 Connections are described as an array of tuples listing the connectors that are connected:
@@ -439,15 +453,13 @@ StateSpace = Model(
 and used as:
 
 ```julia
-col(args...) = hvcat(1, args...)  # Construct a column matrix from a vector
-
 SecondOrder = Model(
     w = 20.0,
     D =  0.1,
     k =  2.0,
     sys = StateSpace | Map(A = :([  0        1;
                                  -w^2  -2*D*w]),
-                           B = :(col([0; w^2])),
+                           B = :([0; w^2;;]),    # Julia 1.7: Trailing ";;" defines a column matrix
                            C = :([k 0]),
                            D = :(zeros(1,1)),
                            x = Var(init = zeros(2)) ),
@@ -457,8 +469,9 @@ SecondOrder = Model(
 
 Variables `sys.u` and `sys.y` are vectors with one element each.
 
-Note, `[0; w^2]` is a vector in Julia and not a column matrix (see the discussion [here](https://discourse.julialang.org/t/construct-a-2-d-column-array/30617)).
-In order that `B` is defined as column matrix, the function `col(..)` is used.
+Note, `[0; w^2]` is a vector in Julia and not a column matrix.
+In order that `B` is defined as column matrix, the Julia 1.7 feature is used to append two semikolons, that is,
+`[0; w^2;;]`
 
 Array equations remain array equations during symbolic transformation and in the generated code,
 so the code is both compact and efficient.
@@ -484,6 +497,44 @@ equations = :[
 ]
 ```
 
+When the init or start value of an array variable is defined as a [StaticArrays](https://github.com/JuliaArrays/StaticArrays.jl) array,
+then the value of this array remains to be a StaticArrays variable also in the generated code.
+The benefit is that array operations are more efficient:
+
+```julia
+using StaticArrays
+TestArray1 = Model
+    v = Var(init=SVector{3,Float64}(1.0, 2.0, 3.0)),
+    equations = :[der(v) = -v]
+)
+testArray1 =  @instantiateModel(TestArray1, logCode=true)
+```
+
+Note, the generated code is shown in the REPL if `logCode=true` is defined:
+
+```julia
+function getDerivatives(_x, _m::ModiaLang.SimulationModel{_FloatType,_TimeType} ...
+    ...
+    v::ModiaBase.SVector{3,_FloatType} = ModiaBase.SVector{3,_FloatType}(_x[1:3])
+    var"der(v)" = -v
+    ...
+```
+
+The sizes of StaticArrays variables cannot be changed, after `@instantiatedModel` was called.
+However, the sizes of standard array variables can be changed with keyword argument `merge` in `simulate!`
+(so no re-generation and re-compilation of the code is needed):
+
+```julia
+TestArray2 = Model(
+    v = Var(init=[1.0, 2.0, 3.0]),   # length(v) = 3
+    equations = :[der(v) = -v]
+)
+testArray2 = @instantiateModel(TestArray2)
+simulate!(testArray2, stopTime=2.0, merge=Map(v = [4.0, 3.0, 2.0, 1.0]))   # length(v) = 4
+plot(testArray2, "v", figure=5)
+```
+
+
 ## 2.7 Model libraries
 
 Modia provides a small set of pre-defined model components in directory `Modia.modelsPath`:
@@ -496,15 +547,16 @@ Modia provides a small set of pre-defined model components in directory `Modia.m
 - `Translational.jl` - 1D translational, mechanical component models
 - [PathPlanning](@ref) - Defining reference trajectories and access them.
 
-These models are included in package `Modia`, but are not exported, so must be access with `Modia.xxx`.
-
-The circuit of section [2.5.5 Connected models](@ref) can be for example constructed with these libraries in the following way:
+The desired libraries must be explicitly included with the help of utility
+path variable `Modia.modelsPath`. For example, the circuit of section [2.5.5 Connected models](@ref)
+is constructed with these libraries in the following way:
 
 ```julia
 using Modia
-using DifferentialEquations
 @usingModiaPlot
 
+include("$(Modia.modelsPath)/Electric.jl")
+
 FilterCircuit = Model(
     R = Modia.Resistor  | Map(R=0.5u"Ω"),
     C = Modia.Capacitor | Map(C=2.0u"F", v=Var(init=0.1u"V")),