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:
Figure 1. Auxiliary model with the annotation (some fields are indicated)
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:
- If Protected variables is ticked, all the protected variables included in the Store settings will be saved in the results file. Otherwise, these variables will not be displayed even if they take part in the set of selected variables.
- If All variables; ignore selections in model is not ticked, only the variables included in the annotation will be shown, among those filtered by the Store settings. If it is, all the variables will be displayed, regardless the selection carried out.
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.
Figure 4a. Annotation attributes for multiple selections (same branch; one matching statement)
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:
- If the user does not wish to set any particular name for the branch, simply write
newName = “%path%”
and the variable will be found in its corresponding directory in the variable browser.
- To set a certain name for the branch, the syntax used is
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.
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:
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):
Figure 6a. View of the variable browser (className not used)
Figure 6b. View of the variable browser (className used)
| ATTRIBUTE | BEFORE (a) | AFTER (b) |
| 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:
- Parameters and States is the predefined selection corresponding to a conventional simulation (bearing in mind the storing settings).
- MySelection is the name of the group of variables selected.
4. Deselect the list that you do not want to see in the variable browser.