In the Modelica language, the annotation keyword is used to define graphics, documentation, menus and many other attributes that do not affect the behaviour of the system modelled. In this post I’m going to focus on the class annotations that let you store the simulation settings used to control the simulation of your experiment. Storing these settings in the class annotations makes it easy for other users of your models to use the same simulation setting without needing to set anything themselves.
Where Is The Class Annotation?
In case you’re new to Modelica and Dymola and wondering where to find the annotation in your models, here’s a quick guide. Feel free to skip ahead if you’re familiar with where annotations appear.
Collapsed annotations are collapsed within a green lower case letter icon in the text. Clicking on this icon will expand the annotation to show the entire code, as shown at the bottom of Figure 1.
Annotations are either:
- Component annotations linked to a specific item in a class (variables, components etc.). They are located at the end of the line declaring that item as highlighted in Figure 1.
- Class annotations are for the entire class, the icon is free-standing and usually located prior to the end line of the class; as shown in Figure 1.
Simulation Settings Annotations
In a Dymola model, the simulation settings in the class annotation allow you to define the settings you want to be used when your experiment is simulated whether this is you or another user.
The simulation settings annotations fall in to 4 groups in the class annotation, as illustrated in figure 2. These groups are (1) experiment, (2) experiment setup output, (3) experiment flags and (4) advanced experiment flags. In the next couple of sections I will go through the options available in each of these groups.
Experiment
annotation(experiment(annotationName = annotationValue));
The annotations that fall into the experiment group allow you to control the most general simulation settings. These annotations follow the syntax shown in the code above and the options are shown in the table below.
| Annotation Name | Annotation Value | Purpose |
| StartTime | Number | Start time of the simulation. |
| StopTime | Number | Stop time of the simulation. |
| __Dymola_NumberOfIntervals | Number | Number of results points to be stored. The total number of points stored is also dependent on the storing of results at event. Used as an alternative to Interval. |
| Interval | Number | Time interval between the results points to be stored. The total number of points stored is also dependent on the storing of results at event. Used as an alternative to __Dymola_NumberOfIntervals. |
| __Dymola_Algorithm | “Lsodar” “Dassl” “Radau” “Euler” “Rkfix2” “Rkfix3” “Rkfix4” “Esdirk23a” “Esdirk34a” “Esdirk45a” “Dopri45” “Dopri853” “Sdirk34hw” “Cerk23” “Cerk34” “Cerk45” “Cvode” | The integration algorithm used to solve the differential equations. For more details on the algorithms available see the Selecting the integration algorithm section of the Dymola User Manual Vol 1 [1]. |
| Tolerance | Number | Required accuracy. |
| __Dymola_fixedstepsize | Number | Time step used in combination with the selection of fixed step size algorithm. |
Experiment Setup Output
annotation(__Dymola_experimentSetupOutput(annotationName = annotationValue));
The annotations in the experiment setup output group allow you to control what is included in the simulation results stored. The syntax example for this annotation is shown above and the options available are shown below.
| Annotation Name | Annotation Value | Purpose |
| textual | true/false | Allows the results to be stored in textual rather than binary format. |
| doublePrecision | true/false | Results stored with double rather than single percision. |
| equidistant | true/false | Store results equidistantly as given by the experiment annotations. |
| events | true/false | Store variables before and after events. Note that the model is evaluated at each store point to get the correct values of all variables to store. So when this annotation is true, it adds extra evaluations which may cause very small changes in the result. If there are instabilities in the model, these small changes can have a more significant overall effect. |
| onlyStopTime | true/false | Stores the results at the stop time only. |
| states | true/false | State variables stored. |
| derivatives | true/false | Derivatives stored. |
| inputs | true/false | Public top level inputs stored. |
| outputs | true/false | Public top level outputs stored. |
| auxiliaries | true/false | Auxiliary variables stored. |
Experiment Flags
annotation(__Dymola_experimentFlags(annotationName = annotationValue));
The experiments flags annotations allow you to store settings for flags related to the experiment simulation, these annotations have equivalent flags that are set via the command line in Dymola. The syntax example for these annotations is shown in the code above, and the options shown in the table below.
| Annotation Name | Annotation Value | Purpose |
| Evaluate | true/false | Updates the global setting for evaluation of parameters at translation. There is a similar Evaluate components annotation which overrides the global setting, allowing more specific application of the setting. Corresponds to Evaluate in the command line. |
| OutputCPUtime | true/false | Stores two extra variables in the results. CPUtime gives the accumulated CPU time during the simulation. EventCounter increments for each event counting event iterations. Corresponds to OutputCPUtime in the command line. |
| OutputFlatModelica | true/false | Outputs all variable declarations and equations in a .mof file. Corresponds to OutputFlatModelica in the command line. |
Advanced Experiment Flags
annotation(__Dymola_experimentFlags(Advanced(annotationName = annotationValue)));
This group is a subset of the experiment flag annotations, where the equivalent flag for the command line starts with Advanced. The annotation syntax is shown above and the options are shown below.
| Annotation Name | Annotation Value | Purpose |
| EvaluateAlsoTop=false, | true/false | Evaluation of top level parameters at translation. Corresponds to Advanced.EvaluateAlsoTop in the command line. |
| GenerateVariableDependencies | true/false | Permits plotting of variable dependencies. If this is true, all the categories of variables are automatically stored. Corresponds to Advanced.GenerateVariableDependencies in the command line. |
| OutputModelicaCode | true/false | Outputs the translated Modelica code in a dsmodel.mof file. Corresponds to Advanced.OutputModelicaCode in the command line. |
| InlineMethod | 0 = Inline integration not used 1 = Explicit Euler 2 = Implicit Euler 3 = Trapezoidal Method 4 = Mixed Explicit/Implicit Euler 5 = Implicit Runge Kutta 6 = Explicit Runge Kutta 7 = Rosenbrock | Inline integration method used. If this is set to anything except 0, the __Dymola_Algorithm annotation should also be set to Euler. For more information on using fixed time step solvers and inline integration see this blog post. Corresponds to the Advanced.InlineMethod in the command line. |
| InlineOrder | 1-4 | Defines the order used for InlineMethod 5-7. Setting this to 1 for Implicit/Explicit Runge Kutta actually uses Implicit/Explicit Euler. Corresponds to Advanced.InlineOrder in the command line. |
| InlineFixedStep | Number | When using an implicit inline integration method, the code is optimised for this step size. The __Dymola_fixedstepsize annotations should also be set to match this. Corresponds to Advanced.InlineFixedStep in the command line. |
Note there is no equivalent to the command line flags Advanced.StoreProtectedVariables and
Advanced.StoreNonFiltered which can be stored in the class annotations of a model.
Creating Simulation Setting Annotations from a GUI
The class annotation of your model can be edited directly in the text to change the simulation settings stored. Alternatively the Simulation Setup dialog, shown in Figure 3, provides a GUI to edit these class annotations.
Selecting the Store in Model button at the bottom of the Simulation Setup dialog will allow you to create or edit the class annotation for options in the General, Translation and Output tabs of the GUI.
When the checkbox for Automatically store General and Inline integration settings is ticked, the class annotations for the changes to settings in the General tab and Inline integration group on the Realtime tab are updated whenever these are changed and OK’d in the Simulation Setup dialog.
FYI
Finally, did you know that you can access the class annotations of your model in the diagram as well as in the text? Figure 4 below shows you the steps to open the class annotation dialog.
All the annotations for the class are shown, including the simulation settings discussed in this post. Plus you can create, delete, edit, rename and reorder the annotations using either the right-click context menu or the buttons on the bottom left of the dialog.
References
I used Dymola 2020 and the VeSyMA 2019.1 library to create the images shown in this blog post. Other references are:
- Dassault Systèmes AB (2019), Dymola User Manual Volume 1,
Dymola 2020 - Modelica Association (2017), Modelica Language Specification, Version 3.4, available at
https://www.modelica.org/documents/ModelicaSpec34.pdf/view
Written by: Hannah Hammond-Scott – Modelica Project Leader
Please get in touch if you have any questions or have got a topic in mind that you would like us to write about. You can submit your questions / topics via: Tech Blog Questions / Topic Suggestion