About Backward Compatibility

Migration or backward compatibility has to be considered in situations when you make changes to your physics interface design but still want users of this interface to use COMSOL Multiphysics model files created in the old version of the interface. If the migration is done properly, the old model file is corrected when opened, and the user can continue working with it without any problems. Otherwise, the user can get a series of error messages, complaining about invalid names and values, for example.

Another situation occurs if users have saved their models as model files for Java. The change you made in the interface can then break that model file for Java, so the user cannot execute it. It is possible to define migration for this as well, so generated files can execute although they contain Java code in an old syntax. This procedure is referred to as compatibility for the Model Object API. Generally, API migration is more complex to handle, and there are situations when you cannot avoid breaking old model files for Java.

There are settings that you can change without any need for migration. There are also settings that you cannot handle with migration at all — for example, if you change the list of supported space dimensions. The table below summarizes some common changes and whether you should consider migration for the change.

Change operation	Open Model Migration	API Migration
Change type	Yes	Yes
Rename input	Yes	Yes
Remove feature	No	Not possible
Remove input	No	Not possible
Remove input group	No	No
Change description	No	No
Change expression	No	No
Change icon	No	No
Change symbol	No	No
Remove supported space dimension	Not possible	Not possible
Add supported space dimension	No	No
Remove supported study types	Not possible	Not possible
Add supported study types	No	No

For the most common operations that do require migration, you automatically get the proper migration operation included under the last version. This only works if there is a version when you did the change. There can be occasions when you do not want to register a migration operation for every change you do. To turn off the automatic migration, click the Migration node and then clear the Add migration operations automatically check box in the Migration settings section.

The nodes for the migration operations appear in a Version under Building Blocks and under the following container nodes: Components, Properties, and Features.