# Modelica🔗

Modelica is the modeling language that Modelon Impact use to describe a models behavior. The behavior is specified by mathematical equations. Modelica is a free language designed from the start for modeling and simulation.

### Why use Modelica?🔗

• Equation based modeling let you focus on the physics and the compiler will take care of the implementation details
• Free non-proprietary language actively designed by the Modelica association.
• Multi-domain modeling
• Object-oriented makes it possible to create modular code that can be reused and is easier to maintain
• Hierarchical modeling let you create a model that replicates the structure of the actual physical system of interest
• Open text format that can be inspected and version controlled
• Native external function interface to C and Fortran code
• Hybrid modeling, mix continuous and discrete equations and algorithms
• Built-in Unit support

### Background🔗

The Modelica design effort was initiated by Hilding Elmqvist and started in September 1996.

Today the Modelica language has evolved and is used all over the world by many of the largest industrial companies.

### Examples🔗

Below is the Modelica code for a lumped heat capacitor model.

model HeatCapacitor "Lumped thermal element storing heat"
parameter Modelica.SIunits.HeatCapacity C
"Heat capacity of element (= cp*m)";
Modelica.SIunits.Temperature T(start=293.15, displayUnit="degC")
"Temperature of element";
Interfaces.HeatPort_a port annotation (Placement(transformation(
origin={0,-100},
extent={ {-10,-10},{10,10} },
rotation=90)));
equation
T = port.T;
C*der(T) = port.Q_flow;
annotation(...);
end HeatCapacitor;


When executing the code, the annotation expands into addition code and parameters relevant to the model.

### Compilation🔗

To simulate a Modelica model, it needs first to be compiled. During the compilation process, all equations are symbolically sorted to an executable sequence. The result is C-code that can be simulated.

Modelon Impact use the Optimica Compiler Toolkit to compile the Modelica code.

### Structural parameters🔗

A structural parameter is a parameter that canâ€™t be changed without a recompilation.

Following use-cases require recompilation:

1. Structural change of the C-code

• Example: parameter Real[n] volumeSegments, n is structural as it change the size of volumeSegments
2. Conditionally declared components

• Example: HeatExchanger hex if enableHex, enableHex is structural as it decide if component hex is instantiated or not
3. Dependent parameters

• Example: parameter Real area=length*length, area is structural as compiler assumes that overwriting a parameter with a default value that depends on other parameters could mean that we overwrite a model assumption
4. Parameter that due to compiler optimization is compiled into a constant

• Example 1: parameter Real a=1 annotation(Evaluate=true);, model developer guide compiler to compile into a constant

• Example 2 c:=If b > 2 then 1 else 3, b is a structural parameter if compiler simplify the expression for a given value of b

5. Parameter that set a min or max attribute

• Example: parameter Real a(min=b)=1, b is a structural parameter, due to the FMI specification 2 say that min and max should be a literal

## Vendor specific annotations🔗

### What is a vendor specific annotation?🔗

Vendor specific annotations are annotations that are specific to and used by a particular Modelica tool vendor. They typically extend existing Modelica annotations in some way that is helpful for the tool in question. Modelon vendor specific annotations typically include possibilities to control look and feel and behavior of stickies.

### Modelon vendor specific annotations🔗

#### canConnectTo🔗

The canConnectTo annotation is a Modelon vendor-specific connector annotation. It adds additional restrictions, on top of the Modelica specified type compatibility, what a connector can connect to.

  annotation(__Modelon(canConnectTo={classA, classB}));


This annotation make it possible for Modelon Impact to better support "soft library design patterns" that relies on connector icons to indicate what should be connected or not.

Limitation: Compilation is not affected by this annotation, only the GUI connector logic.

#### DialogExtensions🔗

The DialogExtensions annotation is a Modelon vendor-specific annotation that contains extensions to the conventional Modelica specification dialog annotation. It is a container for other annotations listed below and is defined as

  annotation(__Modelon(DialogExtensions(...)));


#### hide🔗

The hide annotation is a DialogExtensions annotation which controls whether or not a variable is shown in a sticky by default (when collapsed). The sticky can always be expanded to show all variables including those that have a hide annotation evaluating to true.

The hide annotation is defined as

  annotation(__Modelon(DialogExtensions(hide = <BooleanExpression> )));

The boolean condition can be a literal, a reference or an expression which gives the author freedom to configure what's shown in stickies relative to other parameters and variables.

  parameter Real a annotation(__Modelon(DialogExtensions(hide = true)));
parameter Real b annotation(__Modelon(DialogExtensions(hide = some_parameter)));
parameter Real c annotation(__Modelon(DialogExtensions(hide = some_parameter and not some_other_parameter > some_value)));


#### hideInEditingState / hideInNonEditingState🔗

The annotations hideInEditingState and hideInNonEditingState are similar to the hide annotation but apply depending on if the tool is in an editing state or in a non-editing state, respectively. In Impact 'Model mode' and 'Experiment mode' are considered to be editing states and 'Result mode' is considered to be a non editing state.

These annotations can be used to optimize sticky space by only showing the relevant subset of a sticky by default in each mode, so typically input and parameters in model and experiment mode and calculated variables in result mode.

#### Example🔗

Consider a user defined tank model, similar to Modelica.Fluid.Vessels.OpenTank, which has the component view sticky shown in the image below

The sticky contains both parameters and calculated values. Let's assume that we would want to show the three parameters when editing the model or creating an experiment and conversely only show the two variables when looking at results. We could then include an annotation for each of these parameters and variables as shown below.

import SI = Modelica.SIunits;

/* Shown in non-editing state */
SI.Height level  annotation(__Modelon(DialogExtensions(hideInEditingState = true)));
SI.Volume V annotation(__Modelon(DialogExtensions(hideInEditingState = true)));

/* Shown in editing state */
parameter SI.Height height annotation(__Modelon(DialogExtensions(hideInNonEditingState = true)));
parameter SI.Area crossArea annotation(__Modelon(DialogExtensions(hideInNonEditingState = true)));
parameter SI.Height level_start annotation(__Modelon(DialogExtensions(hideInNonEditingState = true)), Dialog(tab = "Initialization"));

This would mean that the tank stickies would only show the parameters in model mode and experiment mode, like shown below.

the user could press on the little blue expander button to see the full content of the stickies and in result mode the stickies would instead show the calculated values as shown below

This could be configured with any kind of expression including other parameters. Let's say for example that the user would like the possibility of deciding whether the editing mode-dependent annotations should have effect or always show everything. To achieve that she could change the condition to depend on a new parameter hideDependingOnMode, effectively acting as a persisted expander button, as shown below

import SI = Modelica.SIunits;

parameter Boolean hideContentDependingOnMode = false;

/* Shown in non-editing state */
SI.Height level  annotation(__Modelon(DialogExtensions(hideInEditingState = hideContentDependingOnMode)));
SI.Volume V annotation(__Modelon(DialogExtensions(hideInEditingState = hideContentDependingOnMode)));

/* Shown in editing state */
parameter SI.Height height annotation(__Modelon(DialogExtensions(hideInNonEditingState = hideContentDependingOnMode)));
parameter SI.Area crossArea  annotation(__Modelon(DialogExtensions(hideInNonEditingState = hideContentDependingOnMode)));
parameter SI.Height level_start  annotation(__Modelon(DialogExtensions(hideInNonEditingState = hideContentDependingOnMode)), Dialog(tab = "Initialization"));
`

Adding the parameter hideContentDependingOnMode to the Tank component view sticky will show the following in model mode

and toggling it would thus collapse parts of the sticky depending on mode.