Annotations¶

Declaration Annotations¶

A declaration annotation comes at the end of a declaration, right before the ;. Here is a simple declaration that includes an annotation:

parameter Real length "Rod length" annotation ...

Note that the annotation comes after the descriptive string and before the ;. Also, the ... is simply a place holder for the Annotation Data, which will be discussed shortly.

Statement and Equation Annotations¶

It is also possible to associate annotations with equations, for example:

T = T0 "Specify initial value for T" annotation ...

In declarations and equations, the annotation is always at the very end and comes immediately before the ;.

Inheritance Annotations¶

We briefly discussed the extends keyword when we talked about Modifications and Avoiding Repetition. It is possible to associate an annotation with an extends clause as follows:

extends QuiescentModelWithInheritance(gamma=0.3, delta=0.01) annotation ...

As we’ve observed in each previous case, the annotation immediately precedes the ;.

Model Annotations¶

A model annotation associates annotation data directly with the model definition itself. This is exactly the kind of annotation we saw when describing Experimental Conditions, e.g.,

model FirstOrderExperiment "Defining experimental conditions"
  Real x "State variable";
initial equation
  x = 2 "Used before simulation to compute initial values";
equation
  der(x) = 1-x "Drives value of x toward 1.0";
  annotation ...
end FirstOrderExperiment;

Note how, unlike all the previous annotation locations we’ve described, this annotation isn’t really “attached” to anything. This indicates that it is annotating the model itself.

General Syntax¶

The syntax of an annotation is the same syntax used for Modifications. This means the annotation will include either an assignment to a variable in the annotation, e.g.,

annotation ...

or it will include a modification to something inside a variable in the annotation, e.g.,

annotation ...

User Annotations¶

Annotations were designed to allow model developers to attach arbitrary data to their models. For example, if a user wanted to associate a part number with a given model definition, they might introduce a model annotation like this:

annotation ...

A general principle of annotation data is that if a tool reads in a model, it must preserve the annotation information when it writes it back out. The tool does not (and, in general, will not) have to understand the data. But the data must be preserved.

Multiple Annotations¶

Imagine a user wanted to specify both a part number and an experiment annotation. Then they might end up with an annotation like this one:

annotation ...

Note how these two pieces of information can exist side by side. One way to think about annotations is to visualize them as a tree like this:

• PartNumber="FF78-E4B879"
• experiment
  • StartTime=0
  • StopTime=8

Namespaces¶

This introduces another principle of annotations which is that it should be possible to have more than one as long as the names are different. For this reason, choosing names is very important and they should be chosen to avoid potential conflicts with other names. For example, a better approach for including the part number would be to enclose it in a variable that is more likely to be unique to your company or application, e.g.,:

annotation ...

In this case, the variable XogenyIndustries can be used to carve out a “namespace” for a specific organization or purpose. If another organization came along and wanted to associate a different part number with the same model, they could do that by establishing their own separate hierarchy in the annotation, e.g.,:

annotation ...

Occasionally, Modelica tool vendors include their own special annotations (e.g., in the Modelica Standard Library). By convention, tool vendors use names that are prefixed by two underscores, e.g.,

annotation ...

Interpretation¶

Remember that annotation data is arbitrary. This allows arbitrary data to be associated with the model. The meaning of that data is, in general, not defined in the Modelica specification. As we will see shortly, there are a few “standard” annotations (they will be described throughout this book) and they are documented in the specification. But when users add annotations beyond the standard annotations it is assumed that they have some way (using some Modelica tool, compiler or other Modelica aware technology) of extracting and interpreting their annotation data.

The bottom line is that while you can inject (non-standard) annotation data into the model, tools are only required to preserve it and not to interpret it.

Documentation¶

It is very common to document Modelica annotations as if they had Record Definitions associated with them. We’ll see several examples of this technique in our next topic. Using this approach to document expected annotation data are strongly encouraged. In fact, this technique is so popular and useful that there are proposals to actually make it part of the language itself in the future.

Documentation¶

Type: Model Annotation

The Documentation annotation in Modelica allows raw text or HTML to be associated with a model as documentation. This documentation is composed of two components. The first is information about the model and the second is revision history information. The structure of the Documentation annotation is described by the following record definition:

record Documentation
  String info "Documentation in text or HTML format";
  String revision "Revision information in text or HTML format";
end Documentation;

When embedding HTML inside an annotation, the HTML code must be surrounded by <html> tags, e.g.,

model MyWidget
  // ... declarations
  annotation ...
  // .. equations
end MyWidget;

Here the model MyWidget contains HTML documentation. The documentation is wrapped by <html> tags and all quotes used to define attributes are escaped by " to avoid accidentally terminating the info string.

experiment¶

Type: Model Annotation

The experiment annotation is used to specify information about how a given model should be simulated. The annotation data can be represented in record form as:

record experiment
  Real StartTime "Time at which the simulation should start";
  Real StopTime "Time at which the simulation should stop";
  Real Interval(min=0) "Time interval between results";
  Real Tolerance(min=0) "Solver tolerance to use";
end experiment;

Evaluate¶

Type: Declaration Annotation (applies to parameters)

The Evaluate annotation indicates to a Modelica compiler that the value of a given parameter can be transformed into a constant at compile time. In other words, it indicates that the user does not require the ability to change the value of the parameter from one simulation to the next.

The motivation behind having such an annotation is that it allows the Modelica compiler to assume many things about the parameter during model compilation that it otherwise couldn’t. These assumptions might restrict the system of equations in such a way that the underlying systems of equations are easier to solve than in the general case where the parameter could take on a range of values.

The Evaluate annotation is simply a Boolean variable (true indicating that the parameter value can be transformed into a constant). It is used in an annotation as follows:

parameter Real x annotation ...

HideResult¶

Type: Declaration Annotation

The HideResult annotation is used to indicate that the solution for a given variable is not of interest to the analyst. By setting the value of HideResult to true, the model developer is indicating to the Modelica compiler that it need not store the annotated variable in any simulation results that are produced. This can save both simulation time and disk space because it avoids writing out data that will never be viewed.

The HideResult annotation would be used as follows:

Real z "Uninteresting variable" annotation ...