Documentation fixes and moved to FMI.jl (#49)

* doc fixes * doc fixes * doc fixes --------- Co-authored-by: ThummeTo <[email protected]>
ThummeTo · Nov 6, 2023 · c2342ae · c2342ae · ThummeTo · Nov 6, 2023
1 parent ec36fc8
commit c2342ae
Show file tree

Hide file tree

Showing 8 changed files with 156 additions and 93 deletions.
diff --git a/src/FMI2/cconst.jl b/src/FMI2/cconst.jl
@@ -20,6 +20,13 @@ const fmi2Real = Creal      # defined in FMICore.jl, dependent on the Julia arch
 const fmi2Integer = Cint
 const fmi2Byte = Char
 const fmi2ValueReference = Cuint
+
+"""
+fmi2FMUstate is a pointer to a data structure in the FMU that saves the internal FMU state of the actual or
+a previous time instant. This allows to restart a simulation from a previous FMU state.
+
+Source: FMI2.0.3 Spec [p.17]; See also section 2.1.8
+"""
 const fmi2FMUstate = Ptr{Cvoid}
 const fmi2Component = Ptr{Cvoid}
 const fmi2ComponentEnvironment = Ptr{Cvoid}
@@ -29,29 +36,31 @@ export fmi2Char, fmi2String, fmi2Boolean, fmi2Real, fmi2Integer, fmi2Byte, fmi2V
 fmi2ValueReferenceFormat = Union{Nothing, String, AbstractArray{String,1}, fmi2ValueReference, AbstractArray{fmi2ValueReference,1}, Int64, AbstractArray{Int64,1}, Symbol} 
 export fmi2ValueReferenceFormat
 
+const fmi2Status = Cuint
+const fmi2StatusOK      = Cuint(0)
+const fmi2StatusWarning = Cuint(1)
+const fmi2StatusDiscard = Cuint(2)
+const fmi2StatusError   = Cuint(3)
+const fmi2StatusFatal   = Cuint(4)
+const fmi2StatusPending = Cuint(5)
+
 """
 Source: FMISpec2.0.2[p.18]: 2.1.3 Status Returned by Functions
 
 Status returned by functions. The status has the following meaning:
-fmi2OK – all well
-fmi2Warning – things are not quite right, but the computation can continue. Function “logger” was called in the model (see below), and it is expected that this function has shown the prepared information message to the user.
-fmi2Discard – this return status is only possible if explicitly defined for the corresponding function
+- fmi2OK – all well
+- fmi2Warning – things are not quite right, but the computation can continue. Function “logger” was called in the model (see below), and it is expected that this function has shown the prepared information message to the user.
+- fmi2Discard – this return status is only possible if explicitly defined for the corresponding function
 (ModelExchange: fmi2SetReal, fmi2SetInteger, fmi2SetBoolean, fmi2SetString, fmi2SetContinuousStates, fmi2GetReal, fmi2GetDerivatives, fmi2GetContinuousStates, fmi2GetEventIndicators;
 CoSimulation: fmi2SetReal, fmi2SetInteger, fmi2SetBoolean, fmi2SetString, fmi2DoStep, fmiGetXXXStatus):
 For “model exchange”: It is recommended to perform a smaller step size and evaluate the model equations again, for example because an iterative solver in the model did not converge or because a function is outside of its domain (for example sqrt(<negative number>)). If this is not possible, the simulation has to be terminated.
 For “co-simulation”: fmi2Discard is returned also if the slave is not able to return the required status information. The master has to decide if the simulation run can be continued. In both cases, function “logger” was called in the FMU (see below) and it is expected that this function has shown the prepared information message to the user if the FMU was called in debug mode (loggingOn = fmi2True). Otherwise, “logger” should not show a message.
-fmi2Error – the FMU encountered an error. The simulation cannot be continued with this FMU instance. If one of the functions returns fmi2Error, it can be tried to restart the simulation from a formerly stored FMU state by calling fmi2SetFMUstate.
+- fmi2Error – the FMU encountered an error. The simulation cannot be continued with this FMU instance. If one of the functions returns fmi2Error, it can be tried to restart the simulation from a formerly stored FMU state by calling fmi2SetFMUstate.
 This can be done if the capability flag canGetAndSetFMUstate is true and fmi2GetFMUstate was called before in non-erroneous state. If not, the simulation cannot be continued and fmi2FreeInstance or fmi2Reset must be called afterwards.4 Further processing is possible after this call; especially other FMU instances are not affected. Function “logger” was called in the FMU (see below), and it is expected that this function has shown the prepared information message to the user.
-fmi2Fatal – the model computations are irreparably corrupted for all FMU instances. [For example, due to a run-time exception such as access violation or integer division by zero during the execution of an fmi function]. Function “logger” was called in the FMU (see below), and it is expected that this function has shown the prepared information message to the user. It is not possible to call any other function for any of the FMU instances.
-fmi2Pending – this status is returned only from the co-simulation interface, if the slave executes the function in an asynchronous way. That means the slave starts to compute but returns immediately. The master has to call fmi2GetStatus(..., fmi2DoStepStatus) to determine if the slave has finished the computation. Can be returned only by fmi2DoStep and by fmi2GetStatus (see section 4.2.3).
+- fmi2Fatal – the model computations are irreparably corrupted for all FMU instances. [For example, due to a run-time exception such as access violation or integer division by zero during the execution of an fmi function]. Function “logger” was called in the FMU (see below), and it is expected that this function has shown the prepared information message to the user. It is not possible to call any other function for any of the FMU instances.
+- fmi2Pending – this status is returned only from the co-simulation interface, if the slave executes the function in an asynchronous way. That means the slave starts to compute but returns immediately. The master has to call fmi2GetStatus(..., fmi2DoStepStatus) to determine if the slave has finished the computation. Can be returned only by fmi2DoStep and by fmi2GetStatus (see section 4.2.3).
 """
-const fmi2Status = Cuint
-const fmi2StatusOK      = Cuint(0)
-const fmi2StatusWarning = Cuint(1)
-const fmi2StatusDiscard = Cuint(2)
-const fmi2StatusError   = Cuint(3)
-const fmi2StatusFatal   = Cuint(4)
-const fmi2StatusPending = Cuint(5)
+fmi2Status, fmi2StatusOK, fmi2StatusWarning, fmi2StatusDiscard, fmi2StatusError, fmi2StatusFatal, fmi2StatusPending
 export fmi2Status, fmi2StatusOK, fmi2StatusWarning, fmi2StatusDiscard, fmi2StatusError, fmi2StatusFatal, fmi2StatusPending
 
 """
@@ -117,14 +126,15 @@ const fmi2InitialApprox     = Cuint(1)
 const fmi2InitialCalculated = Cuint(2)
 export fmi2Initial, fmi2InitialExact, fmi2InitialApprox, fmi2InitialCalculated
 
+const fmi2True = fmi2Boolean(true)
+const fmi2False = fmi2Boolean(false)
 """
 Source: FMISpec2.0.2[p.16]: 2.1.2 Platform Dependent Definitions
 
 To simplify porting, no C types are used in the function interfaces, but the alias types are defined in this section.
 All definitions in this section are provided in the header file “fmi2TypesPlatform.h”.
 """
-const fmi2True = fmi2Boolean(true)
-const fmi2False = fmi2Boolean(false)
+fmi2True, fmi2False
 export fmi2True, fmi2False
 
 """
@@ -153,7 +163,14 @@ export fmi2StatusKind, fmi2StatusKindDoStepStatus, fmi2StatusKindPendingStatus,
 
 # Custom helper, not part of the FMI-Spec. 
 """
-ToDo.
+Types of dependency:
+
+- `fmi2DependencyKindDependent`: no particular structure, f(v)
+- `fmi2DependencyKindConstant`: constant factor, c*v (for Real valued variables only)
+- `fmi2DependencyKindFixed`: tunable factor, p*v (for Real valued variables only)
+- `fmi2DependencyKindDependent`: discrete factor, d*v (for Real valued variables only)
+
+Source: FMI2.0.3 Spec for fmi2VariableDependency [p.60] 
 """
 const fmi2DependencyKind            = Cuint
 const fmi2DependencyKindDependent   = Cuint(0)

diff --git a/src/FMI2/convert.jl b/src/FMI2/convert.jl
@@ -4,10 +4,10 @@
 #
 
 """
-    
-    fmi2StatusToString(status)
 
-Converts a fmi2Status/Integer `status` to String.
+    fmi2StatusToString(status::Union{fmi2Status, Integer})
+
+Converts `fmi2Status` `status` into a String ("OK", "Warning", "Discard", "Error", "Fatal", "Pending").
 """
 function fmi2StatusToString(status::Union{fmi2Status, Integer})
     if status == fmi2StatusOK
@@ -54,10 +54,10 @@ end
 export fmi2StatusToString
 
 """
-    
-    fmi2CausalityToString(c)
 
-Converts a fmi2Causality `c` to String.
+    fmi2CausalityToString(c::fmi2Causality)
+
+Converts [`fmi2Causality`](@ref) `c` to the corresponding String ("parameter", "calculatedParameter", "input", "output", "local", "independent").
 """
 function fmi2CausalityToString(c::fmi2Causality)
     if c == fmi2CausalityParameter
@@ -79,10 +79,10 @@ end
 export fmi2CausalityToString
 
 """
-    
-    fmi2StringToCausality(s)
 
-Converts a String `s` to fmi2Causality.
+    fmi2StringToCausality(s::AbstractString)
+
+Converts `s` ("parameter", "calculatedParameter", "input", "output", "local", "independent") to the corresponding [`fmi2Causality`](@ref).
 """
 function fmi2StringToCausality(s::AbstractString)
     if s == "parameter"
@@ -104,10 +104,10 @@ end
 export fmi2StringToCausality
 
 """
-    
-    fmi2VariabilityToString(c)
 
-Converts a fmi2Variablitiy `c` to fmi2Variability.
+    fmi2VariabilityToString(c::fmi2Variability)
+
+Converts [`fmi2Variability`](@ref) `c` to the corresponding String ("constant", "fixed", "tunable", "discrete", "continuous").
 """
 function fmi2VariabilityToString(c::fmi2Variability)
     if c == fmi2VariabilityConstant
@@ -127,10 +127,10 @@ end
 export fmi2VariabilityToString
 
 """
-    
-    fmi2StringToVariability(s)
 
-Converts a String `s` to fmi2Variablitiy.
+    fmi2StringToVariability(s::AbstractString)
+
+Converts `s` ("constant", "fixed", "tunable", "discrete", "continuous") to the corresponding [`fmi2Variability`](@ref).
 """
 function fmi2StringToVariability(s::AbstractString)
     if s == "constant"
@@ -150,10 +150,10 @@ end
 export fmi2StringToVariability
 
 """
-    
-    fmi2InitialToString(c)
 
-Converts a  fmi2Initial `c` to String.
+    fmi2InitialToString(c::fmi2Initial)
+
+Converts [`fmi2Initial`](@ref) `c` to the corresponding String ("approx", "exact", "calculated").
 """
 function fmi2InitialToString(c::fmi2Initial)
     if c == fmi2InitialApprox
@@ -169,10 +169,10 @@ end
 export fmi2InitialToString
 
 """
-    
-    fmi2StringToInitial(s)
 
-Converts a String `s` to fmi2Initial.
+    fmi2StringToInitial(s::AbstractString)
+
+Converts `s` ("approx", "exact", "calculated") to the corresponding [`fmi2Initial`](@ref).
 """
 function fmi2StringToInitial(s::AbstractString)
     if s == "approx"
@@ -188,10 +188,10 @@ end
 export fmi2StringToInitial
 
 """
-    
-    fmi2DependencyKindToString(dk)
 
-Converts a fmi2DependencyKind `dk` to String.
+    fmi2DependencyKindToString(c::fmi2DependencyKind)
+
+Converts [`fmi2DependencyKind`](@ref) `c` to the corresponding String ("dependent", "constant", "fixed", "tunable", "discrete")
 """
 function fmi2DependencyKindToString(dk::fmi2DependencyKind)
     if dk == fmi2DependencyKindDependent
@@ -211,10 +211,10 @@ end
 export fmi2DependencyKindToString
 
 """
-    
-    fmi2StringToDependencyKind(s)
 
-Converts a String `s` to fmi2DependencyKind.
+    fmi2StringToDependencyKind(s::AbstractString)
+
+Converts `s` ("dependent", "constant", "fixed", "tunable", "discrete") to the corresponding [`fmi2DependencyKind`](@ref)
 """
 function fmi2StringToDependencyKind(s::AbstractString)
     if s == "dependent"

diff --git a/src/FMI2/ctype.jl b/src/FMI2/ctype.jl
@@ -62,7 +62,9 @@ end
 export fmi2Annotation
 
 """ 
-ToDo 
+Mutable Struct representing existance and kind of dependencies of an Unknown on Known Variables in Continuous-Time and Event Mode (ME) and at Communication Points (CS)
+
+See also FMI2.0.3 Spec fmi2VariableDependency [p.60]
 """
 mutable struct fmi2VariableDependency
     # mandatory 

diff --git a/src/FMI2/struct.jl b/src/FMI2/struct.jl
@@ -42,7 +42,7 @@ Overload the Base.show() function for custom printing of the FMU2.
 Base.show(io::IO, e::FMU2Event) = print(io, e.indicator == 0 ? "Time-Event @ $(round(e.t; digits=4))s" : "State-Event #$(e.indicator) @ $(round(e.t; digits=4))s")
 
 """ 
-ToDo 
+The mutable struct representing a specific Solution of a FMI2 FMU.
 """
 mutable struct FMU2Solution{C} <: FMUSolution where {C}
     component::C # FMU2Component
@@ -206,7 +206,12 @@ function Base.show(io::IO, sol::FMU2Solution)
 end
 
 """
-ToDo.
+Source: FMISpec 2.0.3 [p.16f]
+
+This is a pointer to a data structure in the simulation environment that calls the FMU. Using this
+pointer, data from the modelDescription.xml file [(for example, mapping of valueReferences to
+variable names)] can be transferred between the simulation environment and the logger function
+(see [FMISpec 2.0.3] section 2.1.5).
 """
 mutable struct FMU2ComponentEnvironment
     logStatusOK::Bool