Variables

module ModiaMath.Variables

Provide variable types for simulation models.

This module provides functions to declare simulation Variables as special structs that have a value and associated attributes. Furthermore, there are functions to copy the integrator interface variables (x, derx, residue) to the appropriate Variables and vice versa. Therefore, the modeler does not have to care about, how the values of the variables are mapped to the integrator interface. Typically, a model is constructed with macro @component using RealXXX variable declarations. Example:

  using ModiaMath
  using StaticArrays

  @component Pendulum(;L=1.0, m=1.0, d=0.1, g=9.81) begin
     phi = RealScalar(start=pi/2, unit="rad"    , fixed=true,               numericType=ModiaMath.XD_EXP)
     w   = RealScalar(start=0.0 , unit="rad/s"  , fixed=true, integral=phi, numericType=ModiaMath.XD_EXP)
     a   = RealScalar(            unit="rad/s^2",             integral=w  , numericType=ModiaMath.DER_XD_EXP) 
     r   = RealSVector{2}(        unit="m"      ,                           numericType=ModiaMath.WC)
  end;

The following variable types are currently supported:

All of them have the following attributes:

The following functions are provided to perform the actual copy-operations and/or to inquire information about the variables in the model

• ModiaMath.copy_start_to_x!
• ModiaMath.copy_x_and_derx_to_variables!
• ModiaMath.copy_variables_to_residue!
• ModiaMath.print_ModelVariables
• ModiaMath.get_xTable
• ModiaMath.get_copyToVariableTable
• ModiaMath.get_copyToResidueTable
• ModiaMath.get_copyToResultTable

Main developer

Martin Otter, DLR - Institute of System Dynamics and Control

@enum AnalysisType KinematicAnalysis QuasiStaticAnalysis DynamicAnalysis

Type of analyis that is actually carried out. The AnalysisType is set by the user of the simulation model. Variables are declared in the model with VariableAnalysisType. Variables with [VariableAnalysisType](@ref) <= AnalysisTypeare removed from the analysis and do not show up in the result. For example, an *acceleration* would be declared asOnlyDynamicAnalysisand then this variable would not show up in the result, ifAnalysisType = KinematicAnalysisorQuasiStaticAnalysis`.

@enum Causality Parameter CalculatedParameter Input Output Local Independent

Causality of variable (only used when connecting models)

vars = ModiaMath.ModelVariables(model::ModiaMath.AbstractComponentWithVariables; 
                                analysis::AnalysisType = ModiaMath.DynamicAnalysis)

Return a struct that contains all the variables in model in a form so that fast copying from the integrator interface to the variables can be performed, and vice versa.

@enum NumericType XD_EXP XD_IMP ..

Defines how a variable is used in the integrator interface. The goal is to describe an implicit index-1 DAE:

The integrator interface to the model is

getModelResidues(m::AbstractSimulationModel, t::Float64, x::Vector{Float64},  
                 derx::Vector{Float64}, r::Vector{Float64}

In the following table it is shown how NumericType values of variables are mapped to this integrator interface:

v = RealSVector{Size}(..)

Generate a variable of type RealVariable{SVector{Size,Float64},Float64} where the values have type StaticArrays.SVector{Size,Float64}. The argument list is described in module Variables.

v = RealSVector3(..)

Generate a variable of type RealVariable{SVector{3,Float64},Float64} where the values have type StaticArrays.SVector{3,Float64}. The argument list is described in module Variables.

v = RealScalar(..)

Generate a variable of type RealVariable{Float64,Float64} to define scalar, Float64, real variables. The argument list is described in module Variables.

v = RealVariable{ValueType,ElementType}(...)

Generate a new variable with v.value::ValueType, v.nominal::ElementType. The argument list is described in module Variables.

sm = ModiaMath.SimulationModel(model::ModiaMath.AbstractComponentWithVariables;
                               startTime = 0.0, stopTime = 1.0, tolerance = 1e-4,
                               interval = (stopTime-startTime)/500.0)

Return a simulationModel sm struct that can be simulated with ModiaMath.simulate!. The given model is typically constructed with the @component macro. As keyword arguments, default values for startTime, stopTime, tolerance, interval can be given.

@enum Variability Constant Fixed Tunable Discrete Continuous

Currently not used. Will be used in the future to store only the minimum information in the result (store value only, when it can potentially change).

@enum VariableAnalysisType AllAnalysis QuasiStaticAndDynamicAnalysis 
                           OnlyDynamicAnalysis NotUsedInAnalysis

Type of analysis that can be carried out with the variable (e.g. a force would be defined as QuasiStaticAndDynamicAnalysis, an acceleration would be defined as OnlyDynamicAnalysis and a position variable would be defined as AllAnalysis.

Variables with VariableAnalysisType <=AnalysisType are removed from the analysis and do not show up in the result. For example, an acceleration would be declared as OnlyDynamicAnalysis and then this variable would not show up in the result, if AnalysisType = KinematicAnalysis or QuasiStaticAnalysis.

name = ModiaMath.componentName(
           component::ModiaMath.AbstractComponentWithVariables)

Return name of component (without the leading path) as Symbol.

copy_start_to_x!(vars::ModelVariables, x::Vector{Float64}, x_fixed::Vector{Bool}, x_nominal::Vector{Float64})

Copy start, fixed and nominalvalues of variables vars to x, x_fixed, and x_nominal vectors.

copy_variables_to_residue!(vars::ModelVariables, x::Vector{Float64},
                           derx::Vector{Float64}, residue::Vector{Float64})

Copy variables vars to residue vector and include the inherent residue equations of XD_EXP variables (residue = der(v) - derx).

copy_x_and_derx_to_variables!(time::Float64, x::Vector{Float64}, 
                              derx::Vector{Float64}, vars::ModelVariables)

Copy xand derxof the integrator interface to the model variables vars.

name = ModiaMath.fullName(component::ModiaMath.AbstractComponentWithVariables)

Return full path name of component (including root name) as Symbol.

table = ModiaMath.get_copyToResidueTable(vars::ModelVariables)

Function returns a DataFrames tables of all the variables in vars that are copied from variables to the residue vector.

table = ModiaMath.get_copyToResultTable(vars::ModelVariables)

Function returns a DataFrames tables of all the variables in vars that are copied from variables to the result.

table = ModiaMath.get_copyToVariableTable(vars::ModelVariables)

Function returns a DataFrames tables of all the variables in vars that are copied from x/derx to the variables.

table = ModiaMath.get_xTable(vars::ModelVariables)

Function returns a DataFrames tables of all the variables stored in x-vector in vars.

initComponent!(within::ModiaMath.AbstractComponentWithVariables, component, name)

Initialize component with name (of String or Symbol type) for component within. If component::ModiaMath.AbstractComponentWithVariables the within object and name are stored in component._internal.

Additionally, and for all other types of component the following statement is executed:

   setfield!(within, Symbol(name), component)

ModiaMath.instanceName(component::ModiaMath.AbstractComponentWithVariables)

Return instance name of component (= full name but without root name) as Symbol.

table = print_ModelVariables(obj)

Print all the variables in obj in form of DataFrames tables. obj can be of type ModiaMath.ModelVariables or ModiaMath.SimulationModel.

@component ComponentName(arguments) begin ... end

Macro to generate a mutable struct ComponentName. An instance of this struct can be used as simulationModel in constructor ModiaMath.SimulationModel and can then be simulated with ModiaMath.simulate!.

The arguments must be keyword arguments and are used as keyword arguments for the generated constructor function ComponentName. The code inbegin ... endis basically the body of the generated constructor function. All left-hand-side (scalar or vector) symbols present betweenbegin ... end, as well as all keyword-argumentsargumentsare declared as fields in structComponentName`.

Examples

using ModiaMath

@component Pendulum(;L=1.0, m=1.0, d=0.1, g=9.81, phi0_deg=90.0) begin
   @assert(L > 0.0)
   @assert(m > 0.0)
   @assert(d >= 0.0)
  
   phi = RealScalar(..)
   w   = RealScalar(..)
   a   = RealScalar(..) 
   r   = RealSVector{2}(..)
end

pendulum = Pendulum(L=1.8)

The symbols L, m, d, g, phi0_deg, phi, w, a, r are used as fields in pendulum (so pendulum.L = 1.8).