Merge pull request #167 from ModiaSim/Release0.12.0

Release0.12.0
ModiaSim · Jun 4, 2023 · a3f179f · a3f179f
2 parents 572ab57 + 0525c50
commit a3f179f
Show file tree

Hide file tree

Showing 20 changed files with 266 additions and 222 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 authors = ["Hilding Elmqvist <[email protected]>", "Martin Otter <[email protected]>"]
 name = "Modia"
 uuid = "cb905087-75eb-5f27-8515-1ce0ec8e839e"
-version = "0.11.0"
+version = "0.12.0"
 
 [deps]
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"

diff --git a/docs/src/Functions.md b/docs/src/Functions.md
@@ -60,15 +60,15 @@ showEvaluatedParameters
 CurrentModule = Modia
 ```
 
-The simulation result of a model `instantiatedModel` are provided as a *signal table*, 
+The simulation result of a model `instantiatedModel` are provided as a *signal table*,
 see [SignalTables.jl](https://github.com/ModiaSim/SignalTables.jl).
 
 Therefore, all [signal table functions](https://modiasim.github.io/SignalTables.jl/stable/Functions/OverviewOfFunctions.html)
 can be used on a simulated model
 
 To activate the defined plot package, use
 
-- [`@usingModiaPlot`](@ref) 
+- [`@usingModiaPlot`](@ref)
 
 Alternatively, `usingPlotPackage` (from Modia reexported macro of SignalTables) can be used,
 but then package `SignalTables` must be in your current environment.
@@ -87,11 +87,11 @@ FirstOrder = Model(
 )
 simulate!(firstOrder, stopTime=10)
 showInfo(firstOrder)    # list info about the result
-t = getValues(firstOrder, "time")  
+t = getValues(firstOrder, "time")
 y = getValues(firstOrder, "y")      # use any plot program: plot(t,y)
 
 # Write result on file
-writeSignalTable("firstOrder.json", firstOrder, indent=2, log=true) 
+writeSignalTable("firstOrder.json", firstOrder, indent=2, log=true)
 ```
 
 See the generated [json-file](../resources/fileio/firstOrder.json).

diff --git a/docs/src/Internal.md b/docs/src/Internal.md
@@ -1,69 +1,91 @@
 # Internal
 
 This chapter documents internal functions that are typically only
-for use of the developers of package Modia.
+for use of the developers of a model library or of Modia.
 
-## Code Generation
-
-This section provides functions to **generate Julia code** of the
-transformed equations.
+## Variables of built-in Components
 
 ```@meta
 CurrentModule = Modia
 ```
 
+The following functions are provided to define and access new variables
+in built-in components (seee for example model `InsulatedRod2` in `Modia/models/HeatTransfer.jl`).
+
+| Functions                                               | Description                                                                       |
+|:--------------------------------------------------------|:----------------------------------------------------------------------------------|
+| [`new_x_segmented_variable!`](@ref)                     | Generate new state variable (`x_segmented` and `der_x_segmented` variables)       |
+| [`new_w_segmented_variable!`](@ref)                     | Generate new local variable (`w_segmented` variable)                              | 
+| [`new_alias_segmented_variable!`](@ref)                 | Generate new alias variable                                                       |
+| [`new_z_segmented_variable!`](@ref)                     | Generate new zero crossing variables (`z_segmented` variables)                    |
+| [`get_x_startIndex_from_x_segmented_startIndex`](@ref)  | Return start index of `x_segmented` variable with respect to state vector `x`     |
+| [`copy_scalar_x_segmented_value_from_state`](@ref)      | Return value of scalar `x_segmented` variable from state vector `x`               |
+| [`copy_SVector3_x_segmented_value_from_state`](@ref)    | Return value of `SVector{3,FloatType}` x_segmented variable from state vector `x` |
+| [`copy_Vector_x_segmented_value_from_state`](@ref)      | Return value of `Vector{FloatType}` x_segmented variable from state vector `x`    |
+| [`copy_der_x_segmented_value_to_state`](@ref)           | Copy value of `der_x_segmented` variable to state derivative vector `der(x)`      |
+| [`copy_w_segmented_value_to_result`](@ref)              | Copy value of local variable (`w-segmented`) to result                            |
+
+
 ```@docs
-SimulationModel
-generate_getDerivatives!
-init!
-outputs!
-terminate!
-derivatives!
-DAEresidualsForODE!
-affectEvent!
-zeroCrossings!
-affectStateEvent!
-timeEventCondition!
-affectTimeEvent!
-addToResult!
-getFloatType
-measurementToString
+new_x_segmented_variable!
+new_w_segmented_variable!
+new_alias_segmented_variable!
+new_z_segmented_variable!
+get_x_startIndex_from_x_segmented_startIndex
+copy_scalar_x_segmented_value_from_state
+copy_SVector3_x_segmented_value_from_state
+copy_Vector_x_segmented_value_from_state
+copy_der_x_segmented_value_to_state
+copy_w_segmented_value_to_result
 ```
 
-## Inquiries in Model
+## Inquiries in built-in Components
 
-The functions in this section can be called in the model code or in 
-functions that are called from the model code.
+The following functions are provided to inquire properties 
+in built-in components at the current state of the simulation
+(see for example model `InsulatedRod2` in `Modia/models/HeatTransfer.jl`).
 
 ```@docs
 isInitial
+isFirstInitialOfAllSegments
 isTerminal
+isTerminalOfAllSegments
 isEvent
 isFirstEventIteration
 isFirstEventIterationDirectlyAfterInitial
+isFullRestart
 isAfterSimulationStart
 isZeroCrossing
 storeResults
 getTime
 ```
 
-## Variable definitions in functions
+## Code Generation
 
-The following functions can be used to define states and algebraic variables inside functions:
+This section lists internal functions to **generate Julia code** of the
+transformed equations.
 
-```@docs
-new_x_segmented_variable!
-new_w_segmented_variable!
-new_alias_segmented_variable!
-new_z_segmented_variable!
-get_x_startIndex_from_x_segmented_startIndex
-get_scalar_x_segmented_value
-get_SVector3_x_segmented_value
-get_Vector_x_segmented_value!
-add_der_x_segmented_value!
-add_w_segmented_value!
+```@meta
+CurrentModule = Modia
 ```
 
+```@docs
+InstantiatedModel
+generate_getDerivatives!
+init!
+outputs!
+terminate!
+derivatives!
+DAEresidualsForODE!
+affectEvent!
+zeroCrossings!
+affectStateEvent!
+timeEventCondition!
+affectTimeEvent!
+addToResult!
+getFloatType
+measurementToString
+```
 
 
 

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,4 +1,4 @@
-activ# Modia Documentation
+# Modia Documentation
 
 [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).
 The basic type of the floating point variables is usually `Float64`, but can be set to any
@@ -42,6 +42,20 @@ functionalities of these packages.
 
 ## Release Notes
 
+### Version 0.12.0
+
+- Improved documentation of built-in component functions.
+
+**Non-backwards** compatible changes 
+
+- Renamed struct `SimulationModel` to `InstantiatedModel`.
+- Renamed function `get_scalar_x_segmented_value` to `copy_scalar_x_segmented_value_from_state`
+- Renamed function `get_SVector3_x_segmented_value` to `copy_SVector3_x_segmented_value_from_state`
+- Renamed function `get_Vector_x_segmented_value!` to `copy_Vector_x_segmented_value_from_state`
+- Renamed function `add_der_x_segmented_value!` to `copy_der_x_segmented_value_to_state`
+- Renamed function `add_w_segmented_value!` to `copy_w_segmented_value_to_result`
+
+
 ### Version 0.11.0
 
 - Require ModiaBase 0.11.1
@@ -140,7 +154,7 @@ These changes should usually not influence user models.
   show all parameters.
 
 - New functions to add states and algebraic variables from within functions that are not visible in the generated code
-  (see [Variable definitions in functions](@ref) and example `Modia/test/TestLinearSystems.jl`).
+  (see [Variables of built-in Components](@ref) and example `Modia/test/TestLinearSystems.jl`).
   This feature is used in the next version of
   Modia3D to allow (Modia3D) model changes after code generation and to get more light weight code.
 
@@ -471,7 +485,7 @@ Bug fixes
 - @reexport using Unitful
 - @reexport using DifferentialEquations
 - Cleanup of test files (besides ModiaLang, no other package needed in the environment to run the tests).
-- Change `SimulationModel{FloatType,ParType,EvaluatedParType,TimeType}` to `SimulationModel{FloatType,TimeType}`
+- Change `InstantiatedModel{FloatType,ParType,EvaluatedParType,TimeType}` to `InstantiatedModel{FloatType,TimeType}`
 
 
 #### Version 0.9.1

diff --git a/docs/src/tutorial/Modeling.md b/docs/src/tutorial/Modeling.md
@@ -528,7 +528,7 @@ testArray1 =  @instantiateModel(TestArray1, logCode=true)
 Note, the generated code is shown in the REPL if `logCode=true` is defined:
 
 ```julia
-function getDerivatives(_x, _m::Modia.SimulationModel{_FloatType,_TimeType} ...
+function getDerivatives(_x, _m::Modia.InstantiatedModel{_FloatType,_TimeType} ...
     ...
     v::ModiaBase.SVector{3,_FloatType} = ModiaBase.SVector{3,_FloatType}(_x[1:3])
     var"der(v)" = -v

diff --git a/docs/src/tutorial/Simulation.md b/docs/src/tutorial/Simulation.md
@@ -24,7 +24,7 @@ modelInstance = @instantiateModel(model; FloatType = Float64, aliasReduction=tru
 
 The macro performs structural and symbolic transformations, generates a function for
 calculation of derivatives suitable for use with [DifferentialEquations.jl](https://github.com/SciML/DifferentialEquations.jl)
-and returns [`SimulationModel`](@ref) that can be used in other functions,
+and returns [`InstantiatedModel`](@ref) that can be used in other functions,
 for example to simulate or plot results. Explanation of the arguments:
 
 * `model`: model (declarations and equations)

diff --git a/examples/Pendulum.jl b/examples/Pendulum.jl
@@ -41,7 +41,7 @@ println("\n... Numerically linearize at stopTime = 10 with Float64 and Double64:
 
 #= DoubleFloats is not necessarily defined in the environment
 using Modia.DoubleFloats
-pendulum3 = SimulationModel{Measurement{Double64}}(pendulum2)
+pendulum3 = InstantiatedModel{Measurement{Double64}}(pendulum2)
 (A_10_Double64, x_10_Double64) = linearize!(pendulum3, stopTime=10) 
 =#
 

diff --git a/models/HeatTransfer/InsulatedRod2.jl b/models/HeatTransfer/InsulatedRod2.jl
@@ -84,7 +84,7 @@ end
 
 
 # Called once before initialization of a new simulation segment
-function initSegment_InsulatedRod2!(instantiatedModel::SimulationModel{FloatType,TimeType}, path::String, ID,
+function initSegment_InsulatedRod2!(instantiatedModel::InstantiatedModel{FloatType,TimeType}, path::String, ID,
                                     parameters::AbstractDict; log=false)::Nothing where {FloatType,TimeType}
     obj::InsulatedRodStruct{FloatType} = Modia.get_instantiatedSubmodel(instantiatedModel, ID)
 
@@ -99,9 +99,9 @@ end
 
 
 # Open an initialized InsulatedRod2 model and return a reference to it
-function openInsulatedRod!(instantiatedModel::SimulationModel{FloatType,TimeType}, ID)::InsulatedRodStruct{FloatType} where {FloatType,TimeType}
+function openInsulatedRod!(instantiatedModel::InstantiatedModel{FloatType,TimeType}, ID)::InsulatedRodStruct{FloatType} where {FloatType,TimeType}
     obj::InsulatedRodStruct{FloatType} = Modia.get_instantiatedSubmodel(instantiatedModel, ID)
-    Modia.get_Vector_x_segmented_value!(instantiatedModel, obj.T_startIndex, obj.T)
+    Modia.copy_Vector_x_segmented_value_from_state(instantiatedModel, obj.T_startIndex, obj.T)
     return obj
 end
 
@@ -127,6 +127,6 @@ function computeInsulatedRodDerivatives!(instantiatedModel, obj::InsulatedRodStr
     for i in 1:length(T)
         obj.der_T[i] = k*(T_grad1(T,Ta,i) - T_grad2(T,Tb,i))
     end
-    Modia.add_der_x_segmented_value!(instantiatedModel, obj.T_startIndex, obj.der_T)
+    Modia.copy_der_x_segmented_value_to_state(instantiatedModel, obj.T_startIndex, obj.der_T)
     return true
 end