Dymola and Modelica make the distribution and deployment of simulation models a relatively simple process. There is often some reservation by model developers concerning how much of a model they may want to reveal to the end users. There are various reasons the developer may want to conceal the model content, but it generally revolves around protection of their intellectual property.
Deployment of an entire Modelica library to a user base is common. This is usually done through generation of an ‘moe’ file which indicates that the Modelica library file is ‘encrypted’. Just because the file is ‘encrypted’ doesn’t mean that all of the code is (or isn’t) concealed. The level of code concealment is ultimately up to the model developer.
A code concealment mechanism is thus required in some way / shape / form. With code concealment, model developers can be assured that sensitive intellectual property (IP) is safe and secure when an encrypted Modelica library is released to a wider user base. Please note that what is described in this post is separate from model licensing, and pertains only to how the code is treated (by Dymola) in an encrypted Modelica library.
Two Standard Methods
Within the Dymola and Modelica ecosystem, there are two methods to affect model code protection and concealment:
- Modelica language annotations
- Dymola specific annotations
Annotations specific to Dymola pre-date the integration of similar annotations into the Modelica language standard. It is worth noting that Dymola and Modelica concealment annotations cannot be mixed in the same file. Adherence to one scheme over another is therefore recommended from the outset of library development.
Modelica Standard Annotations for Concealment
Modelica standard annotations, established in the Modelica language specification, can be easily accessed in Dymola through a specific Graphical User Interface (GUI).
By selecting one of these right click options, an annotation in the following style is added:
annotation (Protection(access=Access.packageText));Such an entry into a class is effective on all classes lower in the hierarchy than it, until another protection annotation is encountered. Protective actions corresponding to the menu are:
- Hide: Access.hide – Hide class from all view.
- Icon: Access.icon – Only icon annotation and publically declared connectors and variables can be accessed.
- Documentation: Access.documentation – Same as Access.icon, albeit with documentation annotation accessible too.
- Diagram: Access.diagram – Same as Access.documentation with added access to diagram annotation and any components with graphical annotation.
- Text for non-package: Access.nonPackageText – All options of Access.diagram, but all class elements can be accessed if class is not a package. Code cannot be duplicated.
- Full access for non-package; including documentation: Access.nonPackageDuplicate – Same as above option, with added caveat if class is not a package then it or any part can be copied.
- Text: Access.packageText – Same rights as Access.diagram, with ability to see, but not copy the source code.
- Full access: including duplication: Access.packageDuplicate – Same as Access.packageText, with added ability to copy the class and source text.
A few additional notes regarding these options:
By default, Dymola applies the Access.documentation option, without entering an annotation into the model text upon encryption. This shows up as the Default (no setting) entry from the GUI.
For more information on Modelica language protection annotations, please see the Dymola User Manual 2A page 171 or Modelica language specification page 273.
Dymola Specific Annotations for Concealment
Contrary to the Modelica concealment options, the Dymola specific protection options default to not revealing anything to the user. The model developer must manually enable the sharing of information in the encrypted library. Furthermore, there is no GUI associated with them, and thus they can only be implemented by adding the text into the class layers. As they are only applied post encryption, they can be present in the library and only take effect when the library undergoes encryption.
Another philosophical difference to the Modelica implementation is the concept of protecting whole packages, then granting individual classes exceptions where desired or required. There are specific annotations designed for use only on non-package classes which can be used to achieve this concept of affirmative unprotection.
Syntax for Dymola based annotations are similar to those of the Modelica approach, but with a Dymola specific entry and Boolean declaration of setting:
annotation(__Dymola_Protection(nestedAllowDuplicate = true));Behaviour of the Dymola annotations is best summarised for actions which affect All classes and Non-Packages.
Annotations affecting all classes:
- Duplicate:
allowDuplicate– Enables class source code to be duplicated. Note, no protection to the code can be applied post duplication. Default is false. - Diagram:
showDiagram– Enable diagram layer to be shown. Default is false, unless for tutorial and example packages. - Text:
showText– Enables text to be shown but not duplicated (unless specified separately). N.B. this can be circumvented. Default is false. - Documentation:
showDocumentation– Enables documentation to be viewed in the browser. If this is false, class is treated as protected from HTML generation. Cannot be exported to HTML without explicit permission. Default is true. - In package browser/choices all matching:
hideFromBrowser– Removes class from browser. Note reverse logic, setting this to true initiates a stronger protective action. Default is false. - License check:
Library– Designates package to be a library, therefore can be licensed as a standalone package of classes.
Some of the above only pertain to packages, therefore annotations affecting non-package classes (individual models, functions, blocks etc) are:
- Duplicate:
nestedAllowDuplicate– Enables class source code to be duplicated. Note, no protection to the code can be applied post duplication. Default is false. - Diagram:
nestedShowDiagram– Enable diagram layer to be shown. Default is false. - Text:
nestedShowText– Enables text to be shown but not duplicated (unless specified separately). N.B. this can be circumvented. Default is false. - Documentation:
nestedShowDocumentation– Enables documentation to be viewed in the browser. If this is false, class is treated as protected from HTML generation. Cannot be exported to HTML without explicit permission. Default is true.
Such annotations are designed to be used in classes within packages, often when the settings counteract a wider hierarchical setting. With these options, model developers have the option to protect most of their work and only allow certain specific elements to be unconcealed.
Further top level package settings can also be deployed. By default, all are false:
- Plotting of protected variables:
showVariables - Diagnostics with variable:
showDiagnostics - Statistics:
showStatistics - Flat Modelica:
showFlat
For more information on Modelica language protection annotations, please see the Dymola User Manual 2A page 173.
Closing Remarks
With two separate schemes of protection, Modelica libraries developed with Dymola can be protected in a relatively straightforward manner. By dictating how much of the code is concealed, any sensitive IP or data can be implemented in a model with less concern about trade secrets leaking into the hands of everyone in the user base. This is just one more reason that Dymola and Modelica are a great choice for not just commercial library developers but also groups who produce libraries of models with varying levels of distribution.
Nate Horn – Vice President
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.
