Conversion Scripts

IMPORTANT: Read chapter "Migrating to newer libraries" in "Dymola User Manual Volume 2" for detailed information!

Why and when are conversion scripts necessary?

If you change the name of a model or the name of a model's parameter in AixLib, you have to create a conversion script. This is necessary to automatically change the paths or parameter mapping of the AixLib models that you are using in any other library. You must add the conversion script to the conversion() list and increase AixLib's version number in the annotation() of AixLib's package.mo file.

Please note that Dymola offers the possibility to create conversion scripts automatically. We recommend to use this! This ensures that no conversion commands are missing. Only the new library is used for conversion. All inheritances of the old library are lost. Therefore, in case of a renamed connector in the base class, a conversion must be performed for all models that extend from this base class in the old library. This functionality was improved with the latest release of Dymola (2022x). Some additional information how to configure this can be found in this stackoverflow thread.

Writing a conversion script

For instance, a model in AixLib is renamed from AixLib.Fluid.HeatExchangers.HeaterCooler_T to AixLib.Fluid.HeatExchangers.Heater_T, then in another model the path to this model remains AixLib.Fluid.HeatExchangers.HeaterCooler_T. Thus, a conversion script should be created in ./AixLib/Resources/Scripts and should be named like ConvertAixLib_from_<x.y.z>_to_<x.y.z+1>.mos, where <x.y.z> denotes the version number still with the old model path and z+1 with the new model path.

Now append the list of conversion scripts in the main package.mo file of AixLib appropriately like in the example below. Furthermore, you have to raise AixLib's version number (here from 0.5.1 to 0.5.2).

annotation(..., version = "0.5.2", conversion(from(
   version="0.3.2",script="modelica://AixLib/Resources/Scripts/ConvertAixLib_from_0.3.2_to_0.4.mos",
   version="0.5.0",script="modelica://AixLib/Resources/Scripts/ConvertAixLib_from_0.5.0_to_0.5.1.mos", 
   version="0.5.1",script="modelica://AixLib/Resources/Scripts/ConvertAixLib_from_0.5.1_to_0.5.2.mos")),...

If now another library is opened, while the AixLib is already loaded, AixLib's conversion script(s) is/are automatically executed depending on the AixLib version in the uses() annotation of the other library's package.mo file.

Create a conversion script with Dymola function

If you are thinking about renaming a class or variable, please consider Dymola's automatic scripting. This is activated by the flags

Advanced.ActiveSmartRenameClass=3;
Advanced.ActiveSmartRename=3;

or via the menu with selecting "Renaming class and renaming component: Yes, also conversion scripts" in the package browser (Edit/ Options/ Package Browser).

IMPORTANT: Convert commands are only written if the renaming is done by using the GUI (Shift + Ctrl + N).

Commands suitable for conversion scripts

This commands can be used to write a conversion script:

convertClass("oldClass", "newClass");
convertClassIf("OldClassName","para","val","NewClassName");
convertElement("oldClass", "oldElement", "newElement");
convertModifiers("oldClass", oldParameterBindings, newParameterBindings);

There are many options to create enhanced scripts, e.g. using curled brackets for array notation. For challenging conversions have a look at Dymola's User Manual Volume 2.

If possible, ConvertElement should be preferred to ConvertModifiers. You can find an example in ConvertAixLib_from_0.3.2_to_0.4.mos:

convertElement("AixLib.Controls.Continuous.PITemp", "RangeSwitch", "rangeSwitch");

Hereby the old parameter name RangeSwitch will be renamed in all models to the new parameter name rangeSwitch for the model AixLib.Controls.Continuous.PITemp. Furthermore, the old parameter values will be applied to the new parameter.

In case of deleted or changed default values ConvertModifiers is used. You can find an example of a deleted and a changed default value in a newer AixLib version in ConvertAixLib_from_0.7.10_to_0.7.11.mos:

convertModifiers("AixLib.Utilities.HeatTransfer.HeatConv_outside", fill("",0), {"A=16", "calcMethodHConv=1"});

Further information

This Claytex Technical Blog article also contains helpful information.