Conversion Scripts

Conversion Scripts

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.

Introduction

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.

So, when renaming such a model, 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.

The content must look like

convertClass("AixLib.Fluid.HeatExchangers.HeaterCooler_T", "AixLib.Fluid.HeatExchangers.Heater_T");

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.

All commands suitable for conversion scripts

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

Summary:
The 4 possible commands are:

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 manuals.

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"});