Migration to Newer Library Versions

Here at Claytex we typically release new versions of our Modelica libraries twice a year inline with the Dymola releases; allowing us to regularly provide our users with new features, enhancements and bug fixes. The changes between versions of our libraries may include changes of names, parameterisation or locations. If a user tried to use the newer library without updating their models to be compatible, there would very likely be errors in their models. To help our users migrate to newer versions of our libraries, we provide conversion scripts. In this blog post I will talk about migration of your libraries to newer versions of our libraries using conversion scripts. It turns out this isn’t as intuitive as one may think.

What Does a Conversion Script Look Like?

Conversion scripts are normally located in the Scripts folder within a library installation. They are Modelica script files that can be opened in any text editor or the inbuilt Dymola script editor.

As you can see in the example above, a conversion script contains commands describing changes between versions of libraries which allow Dymola to update a user’s models to be compatible with the newer version.

We regularly use these commands in our conversion scripts:

• convertClass( ) – Changes the reference path of models that have been renamed or moved in extend clauses and type declarations.
• convertElement( ) – Updates references to connectors, parameters and variables in equations, connections and modifiers.
• convertModifier( ) – Converts parameter bindings in modifiers or removes them entirely.

Within the top level annotations in our libraries we use conversion annotations like the one below. These annotations tell Dymola which conversion script is required when migrating between library versions.

How Does Dymola Know What Library Versions are Compatible?

Your library should contain uses annotations, like those beneath, that tell Dymola what other libraries are used and the compatible versions of these libraries.

Uses annotation can be seen at the bottom of any documentation layer within a library, even if the text layer is hidden.

Migration of Your Libraries

When you want to migrate your own models and libraries to use newer versions of our libraries you should:

1. Take a look at the release notes for the new libraries.
   • This will give you a heads up of the changes you can expect in your models.
   • The notes will also point out any updates required that we couldn’t implement automatically through the conversion scripts and what you should do.
2. Ensure your libraries are saved and backed up.
   • We suggest using version controls tools to do this. For the benefits of using version control, take a look at this blog post.
3. Open Dymola.
4. Open the newer versions of the libraries your models are dependent on, as listed in the uses annotations.
5. Run the conversion scripts for all the libraries changing version. (I agree… this isn’t intuitive.)
   • The scripts are in the library’s Scripts folder.
   • They are run like any other script in Dymola.
6. Open your library or model to be migrated.
   • Any conversion updates made to your models will appear in the Syntax log.
7. A conversion dialog box will appear, like that shown in figure 4.
   • This dialog box lists the conversion scripts for all the libraries with newer versions open than the version number in the uses annotations in your library or model.
   • It has an option to update the version number of your library.
   • It has an option to generate a conversion script containing conversion commands for users of your library resulting from this migration.
   • It has an option to create a backup of your original library.
8. Once you have set the options you desire in the dialog, click OK.
   • More conversion updates may appear in the Syntax log.
   • The uses annotations in your library should be updated to the newer version numbers.
9. Check the uses annotations in your library to be sure that the versions of other libraries have been updated to the newer version numbers.
10. Perform a check of your models in Dymola to identify any errors that need to be fixed.
11. Save your migrated library.
12. Perform testing of your library and models to verify that any changes to the simulation results are acceptable.
    • I mentioned in a previous post on Effective Modelica Library Development that we use an inhouse regression test tool to simulate all our experiments and compare the results to accepted reference data. This means we can easily spot difference in the results due to changes made to our models. We use our regression test tool to check our experiments after we migrate our libraries to use newer versions of other libraries. Similarly our Multi-Run tool could help you perform this testing.

Keeping Your Libraries Up-to-date

We recommended updating to newer versions of our libraries and Dymola as soon as possible to take advantage of the improvements to the libraries and Dymola. This also minimises the amount of conversion changes required simultaneously, as you will only be migrating a single version increment at a time.

Hopefully this blog post will support you in keeping your libraries up-to-date and make the process of converting your libraries to use newer versions of our libraries more clear.

There is more information on the conversion commands and how migration of your libraries works in the Migration appendix of the Dymola User Manual.

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.