If you’ve been using Dymola for a while you will have come across annotations, as they accompany almost every model placed onto the diagram layer. Annotations can be used in any element definition, including parameters, instances, and the whole model. But they can be used to make your models a lot easier and intuitive to use. Getting a few parameter annotations under your belt and using them regularly can make day-to-day usability much easier. All of these will not affect the functionality, only how you can interact with the model in the parameter dialog box.
Annotations Basics
The first important step is to understand what an annotation is, where it is and what its syntax is.
Annotations are found at the end of element definitions, including parameters, instances and connections in the text layer. Usually, they are collapsed down to a green “a” unless opened. Opening can be done by right clicking on the text layer and choosing one of the choices from the “Expand” drop down list; clicking on the green “a”, or clicking on the arrow in the grey left hand edge of the text editor window which also works.
A lot of annotations are created automatically and do not need modification, especially when associated with models placed in the diagram layer. Annotations concerning placement can be modified in the text layer but are a lot easier to modify to look right in the diagram layer. When expanded they will look like the following:
annotation (Placement(transformation(extent={{84,-16},{116,16}})));
The syntax of an annotation must be correct or at best the annotation will not work, at worst it will create a model error. The capitalisation of any modification also needs to be correct, otherwise it will not work. The syntax is very similar to component modification, where the modification of certain elements is contained within its own set of standard brackets. Each modification is separated by a comma. In the example below, the Dialog element has three variables that are being modified; “enable”, “tab” and “group”. There is also a change made to the checkbox variable, located within the choices brackets.
annotation (choices(checkBox=true), Dialog(
enable=animation,
tab=”Animation”,
group=”Animate inertia matrix”));
Tabs and Groups
One of the most effective ways of improving usability is organising parameters into groups and tabs. This makes it a lot easier to find the parameters, and modify them. By default, parameters appear in the dialog box in the same order as they are defined in the text layer. If you’re extending from a component, then the parameters defined there will appear first. Below is the same model with and without tabs and groups. They both will work identically but finding the initialisation or animation parameters is a lot more difficult in the former model compared to the latter.
Groups and tabs are controlled within the Dialog group of variables and are defined with strings. Ensure that the D of Dialog is capitalised, and the t and g of tab and group are not. To have multiple parameters in the same tab/group the same dialog annotation is applied to all parameters in the same group. For example, every parameter to be found in the “if animation = true” group in the “Animation” tab must include modifiers for both the tab and the group, with the same spelling and capitalisation of the tab and group modifiers. An example is shown below:
annotation (Dialog(
tab=”Animation”,
group=”if animation = true”,
enable=animation));
Enabling/disabling parameters
It can be very useful to enable/disable the modification of a parameter, depending on the status of other parameters. For example, a parameter that controls an element of the animation is of no use when the animation is disabled. This is shown in the above example, where the parameter is enabled by the parameter “animation”.
The enable element is within the Dialog group of variables and is controlled by a Boolean. The Boolean must be controlled by other parameters, not a variable. The Boolean could also be a simple Boolean calculation, for example:
annotation (Dialog(enable=animation and animateSphere));
or
annotation (Dialog(enable=not controlType == VeSyMA.Types.VehicleControlType.Automatic
and not speedTime));
Both the cases above depend on parameters, but the second is a calculation based on parameters that are not Boolean.
Above is an example of parameters that are enabled/disabled. With animation enabled but animateSphere disabled, the animation parameters concerned with sphere animation are disabled but the animation parameters concerned with the cylinder are enabled.
Colour Selector
Colours of animations are defined using red green blue (RGB) values. Unless you are able to visualise RGB formulations in your mind’s eye, having a colour palate to be able to visually choose them is a lot easier. Within the Dialog group of variables is the colorSelector Boolean that can be enabled.
annotation (Dialog(colorSelector=true));
This enables the edit button to be a colour selector as shown below:
Boolean Checkbox
By default, the Booleans are controlled by a dropdown list of true and false. But switching to a checkbox is a much more efficient and easier way of controlling it.
This is controlled within the choices group of variables and is a Boolean variable. The annotation looks like this:
annotation (choices(checkBox=true));
Below is an example with and without the checkbox enabled for animation and animateSphere respectively.
Choices
A way to improve the control of what users are able to select as an option is to provide a drop down list of choices, whilst constraining the input to just those choices. This is done by creating a list within the choices group of variables. Each element of the list represents a separate choice, consisting of a value and description, started with “choice=” and separated with a comma. All the choices must match the type of the parameter defined.
The example below shows the syntax of a choice of a vector of axis:
annotation (choices(
choice={1,0,0} “{1,0,0} \”x axis\””,
choice={0,1,0} “{0,1,0} \”y axis\””,
choice={0,0,1} “{0,0,1} \”z axis\””,
choice={-1,0,0} “{-1,0,0} \”negative x axis\””,
choice={0,-1,0} “{0,-1,0} \”negative y axis\””,
choice={0,0,-1} “{0,0,-1} \”negative z axis\””));
The above annotation is of the type which can be configured to yield the following appearance in the dialog box, if the radio button option is selected:
Another use of annotations is to control the simulation settings, and is another great way to improve usability. A great blog post written by my colleague Hannah goes into detail about how to best use them, which you can read here:
Simulation Settings Stored in the Class Annotation
Written by: David Briant – Project Engineer
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
