home/modelica-guidelines/conversion-scripts.md

+### 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
+```Modelica
+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`](https://github.com/RWTH-EBC/AixLib/blob/master/AixLib/package.mo) appropriately like in the example below. Furthermore, you have to raise AixLib's version number (here from 0.5.1 to 0.5.2).
+```Modelica
+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
+The 3 possible commands are:
+
+```Modelica
+convertClass    ("oldClass", "newClass");
+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.
+
+You can find one advanced example in [ConvertAixLib_from_0.5.0_to_0.5.1.mos](https://github.com/RWTH-EBC/AixLib/blob/master/AixLib/Resources/Scripts/ConvertAixLib_from_0.5.0_to_0.5.1.mos):
+```Modelica
+convertModifiers("AixLib.Fluid.FixedResistances.HydraulicResistance", {"D"}, {"diameter=%D%"});
+```
+
+Hereby the old parameter name `D` will be renamed in all models to the new parameter name `diameter` for the model `AixLib.Fluid.FixedResistances.HydraulicResistance`. Furthermore, the old parameter values will be applied to the new parameter.
\ No newline at end of file