Simulation Settings Stored In The Class Annotation

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.

Component And Class Annotation Text
Figure 1: Component and Class Annotations

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.

Simulation Settings In The Class Annotation
Figure 2: Simulation settings in the class annotation

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 NameAnnotation ValuePurpose
StartTimeNumberStart time of the simulation.
StopTimeNumberStop time of the simulation.
__Dymola_NumberOfIntervalsNumberNumber 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.
IntervalNumberTime 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].
ToleranceNumberRequired accuracy.
__Dymola_fixedstepsizeNumberTime 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 NameAnnotation ValuePurpose
textualtrue/falseAllows 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 NameAnnotation Value Purpose
Evaluatetrue/falseUpdates 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 NameAnnotation ValuePurpose
EvaluateAlsoTop=false,true/falseEvaluation 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.
InlineMethod0 = 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.
InlineOrder1-4Defines 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.
InlineFixedStepNumberWhen 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.

Simulation Setup GUI
Figure 3 : Simulation Setup Dialog To Edit Simulation Settings

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.

Figure 4: Opening the Class Annotations 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:

  1. Dassault Systèmes AB (2019), Dymola User Manual Volume 1,
    Dymola 2020
  2. 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

CONTACT US

Got a question? Just fill in this form and send it to us and we'll get back to you shortly.

Sending

© Copyright 2010-2019 Claytex Services Ltd All Rights Reserved. | Designed by CMA Marketing

Log in with your credentials

Forgot your details?