Variables

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:

Variable typesDescription
RealScalarScalar variable with Float64 value
RealSVector{Size}Variable with SVector{Size,Float64} value
RealSVector3Variable with SVector{3,Float64} value
RealVariable{VType, EType}Variable with value/element type VType/EType

All of them have the following attributes:

Variable attributesDescription
value::VTypeValue of the variable (scale, vector, matrix, ...)
info::AbstractStringDescription text
causality::ModiaMath.CausalityCausality of variable
variability::ModiaMath.VariabilityVariability of variable
start::ETypeStart value of variable
fixed::Boolfixed = true: value=start after initialization
analysis::VariableAnalysisTypeAnalysis for which the variable is used
min::ETypeMinimum value of value and of start
max::ETypeMaximum value of value and of start
nominal::ETypeNominal value of value (used to improve numerics)
flow::Bool= true if variable is a flow variable
numericyType::ModiaMath.NumericTypeDefines how variable is used by the integrator
integral= the integral variable or nothing
unit::StringUnit of value and of start

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

Main developer

Martin Otter, DLR - Institute of System Dynamics and Control

source
@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`.

source
@enum Causality Parameter CalculatedParameter Input Output Local Independent

Causality of variable (only used when connecting models)

source
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.

source
@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:

\[\begin{align} z &= f_z(x, t) \\ 0 &= f_d(\dot{x}, x, t, z_i > 0) \\ 0 &= f_c(x, t, z_i > 0) \\ J &= \left[ \frac{\partial f_d}{\partial \dot{x}}; \frac{\partial f_c}{\partial x} \right] \; \text{is regular} \end{align}\]

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:

@enum valueMapping/Description
XD_EXPCopied from x into variable; der(v) is computed by model
XD_IMPCopied from x into variable; der(v) copied from derx
XACopied from x into variable; derx is ignored (algebraic variable)
DER_XD_EXPComputed by model; automatic: residue = der(v) - derx
DER_XD_IMPCopied from derx into variable (= der(v); v has type XD_IMP
LAMBDACopied from derx into variable; index-1 algebraic variable
MUECopied from derx; stabilizing variable to reduced index to index 1
FD_IMPIs copied from variable to residue; part of $f_d$ equations
FCIs copied from variable to residue; part of $f_c$ equations
WRComputed by model; stored in result; used to compute residues
WCComputed by model; stored in result; only available at communication points
TIMECopied from t into variable; independent variable time
source
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.

source
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.

source
v = RealScalar(..)

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

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

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

source
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.

source
@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).

source
@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.

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

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

source
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.

source
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).

source
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.

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

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

source

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.

source

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.

source

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.

source

table = ModiaMath.get_xTable(vars::ModelVariables)

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

source
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)
source
ModiaMath.instanceName(component::ModiaMath.AbstractComponentWithVariables)

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

source

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.

source
@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).

source