ModelicaReference.Annotations

In this package annotations are described. Annotations are intended for storing extra information about a model, such as graphics, documentation or versioning. A Modelica tool is free to define and use other annotations, in addition to those defined here. The only requirement is that any tool shall save files with all annotations from this chapter and all vendor-specific annotations intact. To ensure this, annotations must be represented with constructs according to the Modelica grammar. The Modelica language specification defines the semantic meaning if a tool implements any of these annotations.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

Package Content

Name	Description
absoluteValue	absoluteValue
choices	choices
choicesAllMatching	choicesAllMatching
dateModified	dateModified
defaultComponentName	defaultComponentName
defaultComponentPrefixes	defaultComponentPrefixes
defaultConnectionStructurallyInconsistent	defaultConnectionStructurallyInconsistent
derivative	derivative
Dialog	Dialog
Documentation	Documentation
DocumentationClass	DocumentationClass
DynamicSelect	DynamicSelect
Evaluate	Evaluate
experiment	experiment
HideResult	HideResult
Inline	Inline
InlineAfterIndexReduction	InlineAfterIndexReduction
inverse	inverse
LateInline	LateInline
missingInnerMessage	missingInnerMessage
obsolete	obsolete
preferredView	preferredView
revisionId	revisionId
smoothOrder	smoothOrder
unassignedMessage	unassignedMessage
uses	uses
version	version
versionBuild	versionBuild
versionDate	versionDate

ModelicaReference.Annotations.absoluteValue

A simple type or component of a simple type may have the annotation absoluteValue. Note that this is only relevant for components of a few specific types.

If false, then the variable defines a relative quantity, and if true an absolute quantity.

Syntax

   annotation"(" absoluteValue "=" ( false | true ) ")

Description

When converting between units (in the user-interface for plotting and entering parameters), the offset must be ignored, for a variable defined with annotation absoluteValue = false.

Example usage

This annotation is used in the Modelica Standard Library for example in Modelica.Units.SI for the type definition TemperatureDifference.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.choices

Define graphical layout of choices in a parameter menu

Description

A declaration can have an annotation choices containing modifiers on choice, where each of them indicates a suitable redeclaration or modifications of the element. This is a hint for users of the model, and can also be used by the user interface to suggest reasonable redeclaration, where the string comments on the choice declaration can be used as textual explanations of the choices. The annotation is not restricted to replaceable elements but can also be applied to non-replaceable elements, enumeration types, and simple variables.

For a Boolean variable, a choices annotation may contain the definition checkBox = true, meaning to display a checkbox to input the values false or true in the graphical user interface.

Examples

replaceable model MyResistor=Resistor
  annotation(choices(
              choice(redeclare MyResistor=lib2.Resistor(a={2}) "..."),
              choice(redeclare MyResistor=lib2.Resistor2 "...")));

replaceable Resistor Load(R=2) constrainedby TwoPin
  annotation(choices(
              choice(redeclare lib2.Resistor Load(a={2}) "..."),
              choice(redeclare Capacitor Load(L=3) "...")));

replaceable FrictionFunction a(func=exp) constrainedby Friction
  annotation(choices(
             choice(redeclare ConstantFriction a(c=1) "..."),
             choice(redeclare TableFriction a(table="...") "..."),
             choice(redeclare FunctionFriction a(func=exp) "..."))));

type KindOfController=Integer(min=1,max=3)
   annotation(choices(
                choice=1 "P",
                choice=2 "PI",
                choice=3 "PID"));

model A
  KindOfController x;
end A;
A a(x=3 "PID");

It can also be applied to Boolean variables to define a check box:

  parameter Boolean useHeatPort=false annotation(choices(checkBox=true));

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.choicesAllMatching

Automatically display a list of matching choices in a graphical parameter menu.

Description

Choices menus of replaceable elements can be automatically constructed showing the names of all classes that are either directly or indirectly derived by inheritance from the constraining class of the declaration.

This can be recommended by having annotation choicesAllMatching = true; and disabled by having annotation choicesAllMatching = false;.

Examples

replaceable package Medium = Modelica.Media.Water.ConstantPropertyLiquidWater
                             constrainedby Modelica.Media.Interfaces.PartialMedium
                             annotation (choicesAllMatching=true);

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.dateModified

UTC date and time of the latest change to the package in the following format (with one space between date and time):
YYYY-MM-DD hh:mm:ssZ

Syntax

annotation"(" dateModified "=" STRING ")"

Description

“dateModified” is the UTC date and time (according to ISO 8601) of the last modification of the package. The intention is that a Modelica tool updates this annotation whenever the package or part of it was modified and is saved on persistent storage (like file or database system).

Examples

package Modelica
  annotation(version      = "3.0.1",
             versionDate  = "2008-04-10",
             dateModified = "2009-02-15 16:33:14Z",
             revisionId   = "c04e23a0d 2018-08-01 12:00:00 +0200");
  ...
  end Modelica;

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.defaultComponentName

Default name when dragging component

Syntax

   annotation"(" defaultComponentName "=" STRING ")"

Description

When creating a component of the given class, the recommended component name is the given string.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.defaultComponentPrefixes

Default prefixes when dragging component

Examples

annotation(defaultComponentPrefixes="inner",
           defaultComponentName="world")

Syntax

   annotation"(" defaultComponentPrefixes "=" STRING ")"

Description

The following prefixes may be included in the string prefixes: inner, outer, replaceable, constant, parameter, discrete. In combination with defaultComponentName it can be used to make it easy for users to create inner components matching the outer declarations.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.defaultConnectionStructurallyInconsistent

A model or block definition may contain the annotation defaultConnectionStructurallyInconsistent.

Syntax

   annotation"(" defaultConnectionStructurallyInconsistent "=" ( false | true ) ")

Description

If true, it is stated that a default connection will result in a structurally inconsistent model or block. A "default connection" is constructed by instantiating the respective model or block and for every input u providing an equation 0=f(u), and for every (potential,flow) pair of the form (v,i), providing an equation of the form 0=f(v,i).

Example usage

It is useful to check all models/blocks of a Modelica package in a simple way. One check is to default connect every model/block and to check whether the resulting class is structurally consistent (= a stronger requirement as "balanced").

It is rarely needed; but can be used for InverseBlockConstraints, in order to prevent a wrong error message. Additionally, when a user defined model is structurally inconsistent, a tool should try to pinpoint in which class the error is present. This annotation avoids then to show a wrong error message.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.derivative

Define derivative of function

Examples

function foo0 annotation(derivative=foo1); end foo0;
function foo1 annotation(derivative(order=2)=foo2); end foo1;
function foo2 end foo2;

Description

Derivatives of functions can be declared explicitly using the derivative annotation, whereas a function can be defined as a partial derivative of another function using the der-operator in a short function definition.

A function declaration can have an annotation derivative specifying the derivative function. This can influence simulation time and accuracy and can be applied to both functions written in Modelica and to external functions. A derivative annotation can state that it is only valid under certain restrictions on the input arguments. These restrictions are defined using the following optional attributes: order (only a restriction if order > 1, the default for order is 1), noDerivative, and zeroDerivative. The given derivative-function can only be used to compute the derivative of a function call if these restrictions are satisfied. There may be multiple restrictions on the derivative, in which case they must all be satisfied. The restrictions also imply that some derivatives of some inputs are excluded from the call of the derivative (since they are not necessary). A function may supply multiple derivative functions subject to different restrictions.

The inputs to the derivative function of order 1 are constructed as follows:

First are all inputs to the original function, and after all them we will in order append one derivative for each input containing reals.
The outputs are constructed by starting with an empty list and then in order appending one derivative for each output containing reals.
If the Modelica function call is a nth derivative (n>=1), i.e., this function call has been derived from an (n-1)th derivative, an annotation(order=n+1)=?, specifies the (n+1)th derivative, and the (n+1)th derivative call is constructed as follows:
The input arguments are appended with the (n+1)th derivative, which are constructed in order from the nth order derivatives.
The output arguments are similar to the output argument for the nth derivative, but each output is one higher in derivative order.

Example: Given the declarations

 function foo0
   ...
   input Real x;
   input Boolean linear;
   input ...;
   output Real y;
   ...
   annotation(derivative=foo1);
 end foo0;

 function foo1
   ...
   input Real x;
   input Boolean linear;
   input ...;
   input Real der_x;
   ...
   output Real der_y;
   ...
   annotation(derivative(order=2)=foo2);
 end foo1;

 function foo2
   ...
   input Real x;
   input Boolean linear;
   input ...;
   input Real der_x;
   ...;
   input Real der_2_x;
   ...
   output Real der_2_y;
   ...

the equation

(...,y(t),...)=foo0(...,x(t),b,...);

implies that:

(...,d y(t)/dt,...)=foo1(...,x(t),b,..., ...,d x(t)/dt,...);
(...,d^2 y(t)/dt^2,...)=foo2(...,x(t),b,...,d x(t)/dt,..., ...,d^2 x(t)/dt^2,...);

An input or output to the function may be any simple type (Real, Boolean, Integer, String and enumeration types) or a record, provided the record does not contain both reals and non-reals predefined types. The function must have at least one input containing reals. The output list of the derivative function may not be empty.

zeroDerivative=input_var1
The derivative function is only valid if input_var1 is independent of the variables the function call is differentiated with respect to (i.e., that the derivative of input_var1 is "zero"). The derivative of input_var1 is excluded from the argument list of the derivative-function. Assume that function f takes a matrix and a scalar. Since the matrix argument is usually a parameter expression it is then useful to define the function as follows (the additional derivative = f_general_der is optional and can be used when the derivative of the matrix is non-zero).
```
function f "Simple table lookup"
  input Real x;
  input Real y[:, 2];
  output Real z;
  annotation(derivative(zeroDerivative=y) = f_der,
             derivative=f_general_der);
algorithm
  ...
end f;

function f_der "Derivative of simple table lookup"
  input Real x;
  input Real y[:, 2];
  input Real x_der;
  output Real z_der;
algorithm
  ...
end f_der;

function f_general_der "Derivative of table lookup taking into account varying tables"
  input Real x;
  input Real y[:, 2];
  input Real x_der;
  input Real y_der[:, 2];
  output Real z_der;
algorithm
  ...
end f_general_der;
```
noDerivative(input_var2 = f(input_var1, ...) )
The derivative function is only valid if the input argument input_var2 is computed as f(input_var1, ...). The derivative of input_var2 is excluded from the argument list of the derivative-function. Assume that function fg is defined as a composition f(x, g(x)). When differentiating f it is useful to give the derivative under the assumption that the second argument is defined in this way:
```
function fg
  input Real x;
  output Real z;
algorithm
   z := f(x, g(x));
end fg;

function f
  input Real x;
  input Real y;
  output Real z;
  annotation(derivative(noDerivative(y = g(x))) = f_der);
algorithm
  ...
end f;

function f_der
  input Real x;
  input Real x_der;
  input Real y;
  output Real z_der;
algorithm
  ...
end f_der;
```
This is useful if g represents the major computational effort of fg).

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.Dialog

Define graphical layout of the parameter menu.

Syntax

annotation(Dialog(enable = true,
                     tab = "General",
                   group = "Parameters",
      showStartAttribute = false,
           colorSelector = false,
              groupImage = "modelica://MyPackage/Resources/Images/image.png",
         connectorSizing = false));

Description

The annotations tab and group define the placement of the component or of variables in a dialog with optional tab and group specification. If enable = false, the input field may be disabled [and no input can be given]. If showStartAttribute = true the dialog should allow the user to set the start-value and the fixed attribute for the variable instead of the value-attribute [this is primarily intended for non-parameter values and avoids introducing a separate parameter for the start-value of the variable].

If colorSelector=true, it indicates that an rgb-value selector can be presented for a vector of three elements and generate values 0..255 (the annotation should be usable both for vectors of Integers and Reals).

The annotation groupImage references an image using an Modelica URI, and the image is intended to be shown together with the parameter-group (only one image per group is supported). Disabling the input field will not disable the image.

The value of the connectorSizing annotation must be a literal false or true value [since if the value is an expression, the connectorSizing functionality is conditional and this will then lead easily to wrong models]. If connectorSizing = false, this annotation has no effect. If connectorSizing = true, the corresponding variable must be declared with the parameter prefix, must be a subtype of a scalar Integer and must have a literal default value of zero [since this annotation is designed for a parameter that is used as vector dimension and the dimension of the vector should be zero when the component is dragged or redeclared; furthermore, when a tool does not support the connectorSizing annotation, dragging will still result in a correct model]. If connectorSizing = true, a tool may set the parameter value in a modifier automatically, if used as dimension size of a vector of connectors. [The connectorSizing annotation is used in cases where connections to a vector of connectors shall be made and a new connection requires to resize the vector and to connect to the new index (unary connections). The annotation allows a tool to perform these two actions in many cases automatically. This is, e.g., very useful for state machines and for certain components of fluid libraries.]

Annotation "Dialog" is defined as:

record Dialog
  parameter String  tab                = "General";
  parameter String  group              = "Parameters";
  parameter String  groupImage         = "";
  parameter Boolean enable             = true;
  parameter Boolean showStartAttribute = false;
  parameter Boolean connectorSizing    = false;
  parameter Boolean colorSelector      = false;
  parameter Selector loadSelector;
  parameter Selector saveSelector;
end Dialog;

record Selector
  parameter String filter="";
  parameter String caption="";
end Selector;

Examples

A parameter dialog is a sequence of tabs with a sequence of groups inside them.

A Selector displays a file dialog to select a file: Parameter filter only shows files that fulfill the given pattern defined by "text1 (*.ext1);;text2 (*.ext2);" to show only files with file extension *.ext1 or *.ext2 and displaying a description text "text1" and "text2", respectively. Parameter caption is the text displayed in the dialog menu. Parameter loadSelector is used to select an existing file for reading, whereas parameter saveSelector is used to define a file for writing.

model DialogDemo
  parameter Boolean b = true "Boolean parameter";
  parameter Modelica.Units.SI.Length length "Real parameter with unit";
  parameter Integer nInports=0 annotation(Dialog(connectorSizing=true));
  parameter Real r1 "Real parameter in Group 1" annotation(Dialog(group="Group 1"));
  parameter Real r2 "Disabled Real parameter in group 1"
                     annotation(Dialog(group="Group 1", enable = not b));
  parameter Real r3 "Real parameter in Tab 1" annotation(Dialog(tab="Tab 1"));
  parameter Real r4 "Real parameter in Tab 1 and Group 2"
                     annotation(Dialog(tab="Tab 1", group="Group 2"));
  StepIn stepIn[nInports];
  ...
end DialogDemo;

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.Documentation

Annotations for documentation

Syntax

documentation_annotation:
   annotation"(" Documentation "(" "info" "=" STRING
                            ["," "revisions" "=" STRING ] ")" ")"

Description

The "Documentation" annotation can contain the "info" annotation giving a textual description, the "revisions" annotation giving a list of revisions and other annotations defined by a tool [The "revisions" documentation may be omitted in printed documentation]. How the tool interprets the information in "Documentation" is unspecified. Within a string of the "Documentation" annotation, the tags <HTML> and </HTML> or <html> and </html> define the start and end of content that is HTML encoded. Links to Modelica classes may be defined with the HTML link command using scheme "Modelica", e.g.,

    <a href="modelica://ExamplePackage.Tutorial">ExamplePackage.Tutorial</a>

Together with scheme "Modelica" the (URI) fragment specifiers #diagram, #info, #text, #icon may be used to reference different layers. Example:

   <a href="modelica://ExamplePackage.SimpleModel#info">SimpleModel</a>

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.DocumentationClass

Annotation for defining documentation classes

Syntax

documentation class_annotation:
   annotation"(" DocumentationClass "=" true ")"

Description

Only allowed as class annotation on any kind of class and implies that this class and all classes within it are treated as having the annotation preferredView="info". If the annotation preferredView is explicitly set for a class, it has precedence over a DocumentationClass annotation.

[A tool may display such classes in special ways. For example, the description texts of the classes might be displayed instead of the class names, and if no icon is defined, a special information default icon may be displayed in the package browser.]

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.DynamicSelect

Define schematic animation of diagram layer

Examples

The level of a tank is animated by a rectangle expanding in vertical direction and its color depending on a variable overflow:

annotation(
  Icon(graphics={Rectangle(
    extent=DynamicSelect({{0,0},{20,20}},{{0,0},{20,level}}),
    fillColor=DynamicSelect({0,0,255},
                            if overflow then {255,0,0} else {0,0,255}))}
);

Description

Any value (coordinates, color, text, etc.) in graphical annotations can be dependent on class variables using the DynamicSelect expression. DynamicSelect has the syntax of a function call with two arguments, where the first argument specifies the value of the editing state and the second argument the value of the non-editing state. The first argument must be a literal expression and this value is used for the annotation when editing and/or browsing the diagram layer. The second argument may contain references to variables to enable a dynamic behavior and the actual value is used for the annotation for schematic animation of the diagram layer, e.g., after a simulation.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.Evaluate

Annotation for code generation (evaluate parameter value)

Syntax

   annotation"(" Evaluate "=" ( false | true ) ")

Description

The annotation Evaluate can occur in the component declaration, its type declaration, or a base-class of the type-declaration. In the case of multiple conflicting annotations it is handled similarly to modifiers (e.g., an Evaluate-annotation on the component declaration takes precedence). The annotation Evaluate only has effect for a component declared with the prefix parameter.

If Evaluate = true, the model developer proposes to utilize the value for the symbolic processing. In that case, it is not possible to change the parameter value after symbolic pre-processing.

If Evaluate = false, the model developer proposes to not utilize the value of the corresponding parameter for the symbolic processing.

Evaluate is for example used for axis of rotation parameters in the Modelica.Mechanics.MultiBody library in order to improve the efficiency of the generated code

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.experiment

Define default experiment parameters

Examples

annotation(experiment(StartTime=0, StopTime=5, Tolerance=1e-6))

Syntax

experiment_annotation:
   annotation"(" "experiment" "(" [experimentOption] {, experimentOption}] ")"

experimentOption:
   StartTime  "=" ["+" | "-"] UNSIGNED_NUMBER |
   StopTime   "=" ["+" | "-"] UNSIGNED_NUMBER |
   Interval   "=" UNSIGNED_NUMBER
   Tolerance  "=" UNSIGNED_NUMBER

Description

The experiment annotation defines the default start time (StartTime) in [s], the default stop time (StopTime) in [s], the suitable time resolution for the result grid (Interval) in [s], and the default relative integration tolerance (Tolerance) for simulation experiments to be carried out with the model or block at hand.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.HideResult

Annotation for code generation (hide result)

Syntax

   annotation"(" HideResult "=" ( false | true ) ")

Description

HideResult = true defines that the model developer proposes to not show the simulator results of the corresponding component [e.g., it will not be possible to plot this variable].

HideResult = false defines that the developer proposes to show the corresponding component [if a variable is declared in a protected section, a tool might not include it in a simulation result. By setting HideResult = false, the modeler would like to have the variable in the simulation result, even if in the protected section].

HideResult is for example used in the connectors of the Modelica.StateGraph library to not show variables to the modeler that are of no interest to him and would confuse him.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.Inline

Annotation for code generation (inline function body)

Syntax

   annotation"(" Inline "=" ( false | true ) ")

Description

Has only an effect within a function declaration.

If "Inline = true", the model developer proposes to inline the function. This means, that the body of the function is included at all places where the function is called.

If "Inline = false", the model developer proposes to not inline the function.

Example usage

Inline = true is for example used in Modelica.Mechanics.MultiBody.Frames and in functions of Modelica.Media to have no overhead for function calls such as resolving a vector in a different coordinate system and at the same time the function can be analytically differentiated, e.g., for index reduction needed for mechanical systems.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.InlineAfterIndexReduction

Annotation for code generation

Syntax

   annotation"(" InlineAfterIndexReduction "=" ( false | true ) ")

Description

Has only an effect within a function declaration. If true, the model developer proposes to inline the function after the function is differentiated for index reduction, and before any other symbolic transformations are performed.

This annotation cannot be combined with annotations Inline and LateInline!

Example usage

InlineAfterIndexReduction = true is for example used in Modelica.Mechanics.Rotational.Components.AngleToTorqueAdaptor to define that an input signal is the derivative of another input signal.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.inverse

Every function with one output argument may have one or more "inverse" annotations to define inverses of this function.

Syntax

function f1
  input A1 u1;
  ...
  input T1 uk;
  ...
  input Am um = am;
  ...
  input An un;
  output T2 y;
  annotation(inverse(uk = f2(..., y, ....), ui = f3(..., y, ...), ...));
algorithm
  ...
end f1;

Description

The meaning is that function "f2" is one inverse to function "f1" where the previous output "y" is now an input and the previous input "uk" is now an output. More than one inverse can be defined within the same inverse annotation. Several inverses are separated by commas. (The inverse requires that for all valid values of the input arguments of f2(...,y, ...) and uk being calculated as uk := f2(..., y, ...) implies the equality y = f1(..., uk, ...,) up to a certain precision.)

Function "f1" can have any number and types of arguments with and without default value. The restriction is that the number of unknown variables in the output argument of both "f1" and "f2" must be the same and that "f2" must have exactly the same arguments as "f1" (with the same defaults, if an argument um has a default), but the order of the arguments may be permuted.

Examples

function h_pTX
  input Real p    "pressure";
  input Real T    "temperature";
  input Real X[:] "mass fractions";
  output Real h   "specific enthalpy";
  annotation(inverse(T = T_phX(p,h,X)));
algorithm
  ...
end h_pTX;

function T_phX
  input Real  p    "pressure";
  input Real  h    "specific enthalpy";
  input Real  X[:] "mass fractions";
  output Real T    "temperature";
algorithm
  ...
end T_phX;

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.LateInline

Annotation for code generation (inline function body after symbolic processing)

Syntax

   annotation"(" LateInline "=" ( false | true ) ")

Description

Has only an effect within a function declaration.

If "LateInline = true", the model developer proposes to inline the function after all symbolic transformations have been performed, but before common subexpression elimination takes place.

If "LateInline = false", the model developer proposes to not inline the function after symbolic transformations have been performed.

Example usage

This annotation is for example used in Modelica.Media.Water.IF97_Utilities.T_props_ph to provide in combination with common subexpression elimination the automatic caching of function calls. Furthermore, it is used in order that a tool is able to propagate specific enthalpy over connectors in the Modelica.Fluid library.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.missingInnerMessage

Diagnostic message, if inner declaration is missing

Examples

model World
  annotation(defaultComponentName     = "world",
             defaultComponentPrefixes = "inner replaceable",
             missingInnerMessage      = "The World object is missing");
  ...
end World;

Syntax

   annotation"(" missingInnerMessage "=" STRING ")"

Description

When an outer component of the class does not have a corresponding inner component, the string message may be used as a diagnostic message. However, the inner component is automatically added - if unique - regardless of this annotation.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.obsolete

A class may have the following annotation:

    annotation(obsolete = "message");

Syntax

   annotation"(" obsolete "=" STRING ")"

Description

It indicates that the class ideally should not be used anymore and gives a message indicating the recommended action.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.preferredView

Define default view when selecting class

Syntax

preferred view_annotation:
   annotation"(" preferredView "=" ("info" | "diagram" | "text") ")"

Description

The preferredView annotation defines the default view when selecting the class. info means info layer, i.e., the documentation of the class, diagram means diagram layer and text means the Modelica text layer.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.revisionId

Revision identifier of the version management system used to manage this library. It marks the latest submitted change to any file belonging to the package.

Syntax

annotation"(" revisionId "=" STRING ")"

Description

“revisionId” is a tool specific revision identifier possibly generated by a source code management system (e.g., Subversion or Git). This information allows to exactly identify the library source code in the source code management system.

Examples

package Modelica
  annotation(version      = "3.2.3",
             versionDate  = "2018-08-01",
             dateModified = "2018-12-12 07:40:19Z",
             revisionId   = "c04e23a0d 2018-08-01 12:00:00 +0200");
  ...
  end Modelica;

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.smoothOrder

Define differentiability of function body

Syntax

   annotation"(" smoothOrder "=" UNSIGNED_INTEGER ")"
   annotation"(" smoothOrder "(" normallyConstant=NAME ["," normallyConstant=NAME] ")"
                             "=" UNSIGNED_NUMBER ")"

Description

This annotation has only an effect within a function declaration.

smoothOrder defines the number of differentiations of the function, in order that all of the differentiated outputs are continuous provided all input arguments and their derivatives up to order smoothOrder are continuous.

This means that the function is at least C^smoothOrder. smoothOrder = 1 means that the function can be differentiated at least once in order that all output arguments are still continuous, provided the input arguments are continuous. If a tool needs the derivative of a function, e.g., for index reduction or to compute an analytic Jacobian, the function can be differentiated analytically at most smoothOrder times.

The optional argument normallyConstant of smoothOrder defines that the function argument NAME is usually constant.

Examples

This annotation is used by many functions of the Modelica.Fluid library, such as Modelica.Fluid.Dissipation.PressureLoss.StraightPipe.dp_laminar_DP, since geometric arguments to these functions are usually constant.

function SpecialPolynomial
  input  Real u;
  output Real y;
algorithm
   y = if u > 0 then u^2 else 0;
  annotation(smoothOrder = 1);
end SpecialPolynomial;

model TestSpecialPolynomial
   Real y;
   Real yd;
   Real ydd;
equation
   y   = SpecialPolynomial(sin(time));
   yd  = der(y);     // fine, SpecialPolynomial is analytically differentiated once
   ydd = der(yd);    // error, SpecialPolynomial cannot be differentiated twice
end TestSpecialPolynomial;

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.unassignedMessage

Error message, if variable is not assigned

Examples

connector Frame "Frame of a mechanical system"
    ...
  flow Modelica.Units.SI.Force f[3] annotation(unassignedMessage =
"All Forces cannot be uniquely calculated. The reason could be that the
mechanism contains a planar loop or that joints constrain the same motion.
For planar loops, use in one revolute joint per loop the option
PlanarCutJoint=true in the Advanced menu.
");
end Frame;

Syntax

   annotation"(" unassignedMessage "=" STRING ")"

Description

When the variable to which this annotation is attached in the declaration cannot be computed due to the structure of the equations, the string message can be used as a diagnostic message. When using BLT partitioning, this means if a variable "a" or one of its aliases "b = a", "b = -a", cannot be assigned, the message is displayed. This annotation is used to provide library specific error messages.

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.uses

Defines that classes within this top-level class uses a specific version of another top-level class

Examples

model A
  annotation(version="1.0",
     uses(Modelica(version="1.5")));
  ...
end A;

model B
  annotation(uses(Modelica(version="2.1 Beta 1")));
  ...
end B;

Description

uses(IDENT (version = VERSION-NUMBER) )
Defines that classes within this top-level class uses version VERSION-NUMBER of classes within the top-level class IDENT. The annotations uses and conversion may contain several different sub-entries.

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.version

Define version information of package

Examples

package Modelica
  annotation(version="2.1",
             conversion(noneFromVersion="2.1 Beta 1",
                        from(version="1.5",
                             script="convertFromModelica1_5.mos")));
  ...
end Modelica;

model A
  annotation(version="1.0",
     uses(Modelica(version="1.5")));
  ...
end A;

model B
  annotation(uses(Modelica(version="2.1 Beta 1")));
  ...
end B;

In this example the model A uses an older version of the Modelica library and can be upgraded using the given script, and model B uses an older version of the Modelica library but no changes are required when upgrading.

Description

Version numbers are of the forms:

Main release versions:

""" UNSIGNED_INTEGER { "." UNSIGNED_INTEGER } """

Example: "2.1"

Pre-release versions:

""" UNSIGNED_INTEGER { "." UNSIGNED_INTEGER } " " {S-CHAR} """

Example: "2.1 Beta 1"

Un-ordered versions:
```
 """ NON-DIGIT {S-CHAR} """ 
```
Example: "Test 1"

The main release versions are ordered using the hierarchical numerical names, and follow the corresponding pre-release versions. The pre-release versions of the same main release version are internally ordered alphabetically.

In a top-level class, the version number and the dependency to earlier versions of this class are defined using one or more of the following annotations:

version = CURRENT-VERSION-NUMBER
Defines the version number of the model or package. All classes within this top-level class have this version number.
conversion ( noneFromVersion = VERSION-NUMBER)
Defines that user models using the VERSION-NUMBER can be upgraded to the CURRENT-VERSION-NUMBER of the current class without any changes.
conversion ( from (version = VERSION-NUMBER, [to = VERSION_NUMBER ","] script = "?" ) )
Defines that user models using the VERSION-NUMBER or any of the given VERSION-NUMBER can be upgraded to the given VERSION-NUMBER (if the to-tag is missing this is the CURRENT-VERSION-NUMBER) of the current class by applying the given conversion rules. The to-tag is added for clarity and optionally allows a tool to convert in multiple steps.
uses(IDENT (version = VERSION-NUMBER) )
Defines that classes within this top-level class uses version VERSION-NUMBER of classes within the top-level class IDENT. The annotations uses and conversion may contain several different sub-entries.

A top-level class, IDENT, with version VERSION-NUMBER can be stored in one of the following ways in a directory given in the MODELICAPATH:

The file IDENT ".mo"
Example: Modelica.mo
The file IDENT " " VERSION-NUMBER ".mo"
Example: Modelica 2.1.mo
The directory IDENT
Example: Modelica
The directory IDENT " " VERSION-NUMBER
Example: Modelica 2.1

This allows a tool to access multiple versions of the same package.

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.versionBuild

Defines the optional build number of the library.

This is a deprecated annotation. It should no longer be used, since it will be removed in one of the next Modelica releases. Use instead Semantic Versioning which provides a better mechanism for maintaining releases and bug-fixes in a well defined way.

Syntax

annotation"(" versionBuild "=" INTEGER ")"

Description

“versionBuild” is the optional build number of the library. When a new version is released “versionBuild” should be omitted or “versionBuild = 1”. There might be bug fixes to the library that do not justify a new library version. Such maintenance changes are called a “build” release of the library. For every new maintenance change, the “versionBuild” number is increased. A “versionBuild” number A that is higher as “versionBuild” number B, is a newer release of the library. There are no conversions between the same versions with different build numbers.

Examples

package Modelica
  annotation(version      = "3.0.1",
             versionDate  = "2008-04-10",
             versionBuild = 4,
             dateModified = "2009-02-15 16:33:14Z",
             revisionId   = "c04e23a0d 2018-08-01 12:00:00 +0200");
  ...
  end Modelica;

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

ModelicaReference.Annotations.versionDate

UTC date of first version build (in format: YYYY-MM-DD).

Syntax

annotation"(" versionDate "=" STRING ")"

Description

“versionDate” is the date in UTC format (according to ISO 8601) when the library was released.

Examples

package Modelica
  annotation(version      = "3.0.1",
             versionDate  = "2008-04-10",
             dateModified = "2009-02-15 16:33:14Z",
             revisionId   = "c04e23a0d 2018-08-01 12:00:00 +0200");
  ...
  end Modelica;

Related annotations

Extends from ModelicaReference.Icons.Information (Icon for general information packages).

Automatically generated Thu Oct 1 16:08:42 2020.