Selection of variables to be saved in the result file

December 7th, 2012 by Juan Gabriel Delgado Beltran

One of the most useful features of Dymola 2013 FD01 is a new annotation that enables the selection of a set of variables and / or parameters to be saved in the result file. Hence, the post-processing of simulations with large result files is improved, as users don’t have to “dig” in the variable browser or use the search filter to find a certain variable. The word variable might be used in this document to mean variables and / or parameters in a generic way.

General procedure:

In order to implement the selection of variables / parameters, proceed as follows:

1. Add an annotation to the model using the structure __Dymola_selections, specifying its corresponding fields.
2. Insert a name to identify the whole group of selected magnitudes by the attribute name from the constructor Selection.
3. In order to select a certain set of variables and / or parameters, a search criterion must be specified. The attribute name from MatchVariable implements this.
4. Set a name for the branch that stores a particular group of chosen variables with the attribute newName from MatchVariable.

If the same selection is going to be used with several models, just create an auxiliary one to implement the aforementioned annotation and extend from it when it should be used. The next figures 1 and 2 will clarify this:

Auxiliary model with the annotation

Figure 1. Auxiliary model with the annotation (some fields are indicated)

Working model

Figure 2. Working model (MyModel) with the extension from the auxiliary one (VariableSelection)

When simulating MyModel, the above annotation will select the variable “f” from every component and show the results in the variable browser. The selection can be identified with a tree structure whose trunk name is MySelection, whilst the chosen variables are in the branch Forces.

Another way to do this is using the auxiliary model to implement the variable selection and extend from the working model. Therefore, the model to run is the auxiliary one instead of the working one. This procedure has the problem that it forces to change the extension clause anytime that the working model changes.

Storage settings:

The selection of variables implemented by the aforementioned annotation is affected by the storage settings from the tab called “Output” in the Simulation Setup. These settings filter variables and parameters according to the criteria specified in the next figure:

Variable selection settings in the simulation setup

Figure 3. Variable selection settings in the Simulation Setup

Note that the size of the result file will be affected by these settings, as well as the availability of variables for the search. The access to the selected set of variables from the variable browser is therefore subject to the aforementioned settings.

Annotation attributes:

A general selection annotation consists of two main constructors or records (Selection and MatchVariable) with several fields.

The fields included in Selection are briefly explained next:

a) name (string) => sets the name of the group of variables selected to be displayed in the variable browser. Users can define whatever name they wish, regardless it has more than one word. The only requirement is that it has to be written between inverted commas.
b) match (MatchVariable) => defines the search criterion, that is, the requirement(s) that the variables and parameters will have to fulfil to be selected.
c) override (Boolean) => determines whether selections with the same name found on lower hierarchical levels of the working model should be overridden or merged.

MatchVariable, on its part, consists of the following fields:

a) name (string) => defines the matching pattern for the variables following this structure:

name = “*.VariableName”

The astersisk (*) means that the search criterion is carried out in all the components from the working model. Only the variables with a perfect match are selected. Therefore, a variable containing the string VariableName without a perfect match is not chosen. In order to select different variables, the matching pattern can be implemented for the same branch statement:

name = “*.(VariableName1|VariableName2)”

or, alternatively, the criterion can be declared through different matchings (even if they wil be shown in the same branch). This can be clarified by the below figures 4a and 4b.

Annotation for multiple selections (1)

Figure 4a. Annotation attributes for multiple selections (same branch; one matching statement)

Annotation for multiple selections (2)

b) newName (string) => name of the branch where a certain group of variables is going to be displayed in the variable browser. There are 2 main options:

newName = “%path%”

and the variable will be found in its corresponding directory in the variable browser.

newName = “BranchName.%path%”

Note that the annotation in fig. 4c implements 2 branches (Forces and Torques) in the trunk. These branches will be shown in the variable browser following the same order from the annotation.

Annotation for multiple selections (3)

Figure 4b. Annotation attributes for multiple selections (different branches)

c) className (string) => name of the class where the search has to be carried out (see below).
d) description (string) => if non-empty, broadens the search criterion as it defines a matching pattern to be fulfilled by the description of the variable under analysis.
e) tag[:] (string) => if non-empty, implements an additional search criterion. The analysed expressions should also match the inserted tag to be selected. A tag can be defined as it is shown in the figure below:

Tag annotations

Figure 5. Tag annotations

Advanced variables search:

As it has already been pointed out, it is possible to define the classes where the matching pattern will be performed by the attribute className. Normally, the search is carried out in all the components from the working model (using an asterisk in name), but sometimes users might be interested in targeting a specific component of the working model. This is particularly useful with big models. An example will illustrate how it works.

In fig. 6a, the variable “MyModel.dogClutch.f” is chosen because the search criterion uses an asterisk and, therefore, all the components are swept. However, if the attribute className is added and name is modified a bit, the aforementioned variable would be excluded from the search, besides all those that didn’t belong to the specified class (see fig. 6b):

Variable browser (1)

Figure 6a. View of the variable browser (className not used)

Variable browser (2)

Figure 6b. View of the variable browser (className used)


className Not defined “Modelica.Mechanics.Translational.Interfaces.Flange_b*”
name “*.f” “f”

Therefore, a variable is selected only from those components that contain the class indicated by the attribute className as long as name is modified accordingly (removing the asterisk).

In the analysed example (fig. 6b), users could access the variable f from the clutch through MyModel.MySelection.Forces.dogClutch or MyModel.dogClutch. The first option is faster in models with plenty of components and variables, especially if All variables; ignore selections in model is ticked.

User interface:

Once the simulation has been run, it is possible to get a list of all selections from the variable browser and indicate which one among these should be included in the “variables tree”. Follow these steps:

1. Go to the Variable browser in the Simulation page.
2. Click on Advanced in the lower part of the browser.
3. Click on Variable Selections. A list will pop up:

4. Deselect the list that you do not want to see in the variable browser.