Submodels

Submodels are a way of reusing parts of a model to perform specific operations inside other models.

By using them, we can reduce the amount of work we have to put in when creating models that share similar functionalities. They are also an important tool for abstraction, hiding unnecessary details and making it easier to reason about the model concept and its implementation.

Conceptually, a submodel is a combination of functors exporting inputs and outputs to be bound externally, but, from the user point of view, a submodel is used just like any other ordinary functor.

Submodels are also first class citizens that can be transferred from one model to another. They can also be modified and updated at any time without breaking the model where they are being used. They can also depend on other submodels, as long as their definitions do not form a cycle.

Submodel Types

Basically, we have four different types of submodels in Dinamica EGO: system submodels, user submodels, local submodels, and store submodels. The different types of submodels are identified by different icon badges on the representation of the corresponding functors on the model.

The storage paths mentioned throughout this page (in the table below and in the “Where Submodels Are Stored” section) differ between Windows and Linux; both are listed where relevant.
Type	Badge/Decoration	Description
System Submodel	System submodels are submodels provided by Dinamica itself and cannot be changed by the user. System submodels can be used in models created by any user. On Windows, they are usually located at C:\Program Files\Dinamica EGO <version>\Submodels. On Linux, system submodels are stored inside the application itself, with no corresponding filesystem path.
User Submodel	User submodels are submodels created by each user and are available only for that specific user. User submodels can be used in models created only by that user. On Windows, they are usually located at C:\Users\<User>\Documents\Dinamica EGO <version>\Submodels. On Linux, they are usually located at /home/<User>/Dinamica EGO <version>/Submodels.
Local Submodel	Local submodels are submodels that are related to a specific model. They are bound to that model and cannot be used in a different model unless they are explicitly transferred to it.
Store Submodel	Store submodels are submodels downloaded by the user from the online Submodel Store. They are kept in a SQLite database. On Windows, it is typically located at C:\Users\<User>\AppData\Local\Dinamica EGO <version>\SubmodelDatabase.sqlite. On Linux, it is typically located at /home/<User>/.local/share/Dinamica EGO <version>/SubmodelDatabase.sqlite.

System and user submodels are presented in the “Submodels” tab while local submodels are presented in the “Local Submodels” tab of the Functor Library. Local submodels are only presented when their associated model is opened.

In practice, users can only create local submodels. These local submodels can later be promoted to user submodels, making them a definitive part of the user's tool set.

Where Submodels Are Stored

Local submodels are stored together with the model script. When using the EGO Script (.ego) or EGOML (.egoml) format, Dinamica creates a folder next to the script named after the script filename, with the extension replaced by _ego or _egoml and _Submodels appended. For example, a model named simulation model.egoml will have its local submodels stored in a subfolder called simulation model_egoml_Submodels, and the script files corresponding to each local submodel are located inside that folder. Using a unique submodel folder for each script guarantees that submodels from one script are completely independent from the submodels of any other script.

If a folder named “Submodels” exists in the same folder as the script, and the script-specific ..._Submodels folder described above is not found, Dinamica reads the local submodels from that generic “Submodels” folder instead — this folder is shared among all the scripts located in that folder. This is legacy behavior and may be removed in a future version.

The EGOMLX format works differently: it stores the local submodels and the script together in the same binary file, so no separate submodel folder is used.

User submodels are typically stored in the folder C:\Users\<User>\Documents\Dinamica EGO <version>\Submodels on Windows, or /home/<User>/Dinamica EGO <version>/Submodels on Linux.

Store submodels — those downloaded by the user from the online Submodel Store — are kept in a SQLite database. On Windows, it is typically located at C:\Users\<User>\AppData\Local\Dinamica EGO <version>\SubmodelDatabase.sqlite. On Linux, it is typically located at /home/<User>/.local/share/Dinamica EGO <version>/SubmodelDatabase.sqlite.

System submodels are provided by Dinamica itself: on Windows they are usually located at C:\Program Files\Dinamica EGO <version>\Submodels, while on Linux they are stored inside the application itself, with no corresponding filesystem path.

Changing the definition of user submodels may break existing models that use that definition, making those models useless unless the user manually updates each one of them. On the other hand, local submodels can be safely updated since their updates are propagated to all local submodels from the same model and to the main model itself.

Creating Local Submodels

Local submodels can be created by simply selecting the parts of a model that will be converted to a submodel and choosing the menu Edit => Create Submodel. The selection will be replaced by the new submodel and the visual representation of the new submodel will be available to be edited as a new tab on the script editor.

At any time, the user can make changes to the local submodel and apply those changes by clicking “Apply Changes / Edit Submodel Properties” on the model toolbar. See more information about updating a local submodel in the next sections.

It is also possible to select parts of a local submodel and create another local submodel using that selection. The new local submodel will be a dependency of the previous one, but the submodel creation process is basically the same.

If the selection is empty, an empty local submodel will be created. The process for updating an empty submodel is the same process used to update any local submodel.

Instantiating Local Submodels

Local submodels from a model are placed in a special tab on the Functor Library called “Local Submodels”. These local submodels are grouped by model name.

To instantiate a local submodel as part of a model, just expand the group on the “Local Submodels” tab corresponding to the current model and drag the submodel functor representation to the model presentation area.

It is worth noting that dragging the functor representation belonging to a different model will import the definition of the local submodel from that model.

Navigating Submodels

Navigating between the local submodels and the main model in a script editor can be done by clicking on the corresponding model/submodel tab on the model/submodel tabs or clicking on the submodel overview button above the model/submodel tabs.

Navigating between local submodels

Updating Local Submodels

At any time, the user can add or remove inputs and outputs or even change the combination of functors defining the submodel.

The functor action bar of all functors contained inside a submodel script exhibits additional options for “exporting functor inputs and outputs”. Exporting a new input or output can be performed following the steps below:

First, click on the functor whose inputs or outputs will be exported.

Select “export functor inputs and outputs” on the functor action bar and choose the inputs or outputs that will be exported. It is possible to define the input and output names and their corresponding descriptions. It is also possible to mark an exported input as advanced or optional. Optional inputs can also define an optional value that will be assigned to the port if no explicit value is provided.

Choose the “Submodel Options” submenu on the model toolbar and then click on “Apply Changes / Edit Submodel Properties”. That brings up the submodel editor dialog where you can define a new name, description and icon for the submodel or reorder its inputs and outputs (or even remove some of them). Clicking “Ok” propagates the changes to all parts of your model (and dependent submodels) where the submodel is used.

Below you can see two examples of updating the input and output ports of a local submodel:

Example 1 — exporting and updating ports using the functor action bar:

Example 2 — an additional approach to the same task:

Beware that connected inputs cannot be exported. They must be disconnected first.

It is also worth noting that it is possible to safely rename inputs and outputs. The connections to the port will be maintained when the changes are propagated.

Tip: Dinamica EGO comes with a set of icons from the Fat Cow Icon Set that can be used to customize the local submodels created by users. The icons come in size 16×16 and 32×32 pixels. The overall color of the chosen icon is automatically used to define the color of the functor representing the submodel on the graphical interface. The set of icons is usually installed in the folder IconSamples in your Dinamica EGO installation folder.

When updating a local submodel, the changes from all dependent local submodels will also be propagated. This means that updating a submodel always updates the whole chain of local submodels that use that submodel as part of their definition.

Removing ports from a local submodel is also similar to updating the exported ports. You can remove the ports using the “export functor inputs and outputs” option on the functor action bar and unchecking the corresponding port on the “Exported Ports” dialog, or using the “Apply Changes / Edit Submodel Properties” dialog.

Changing the order of the input or output ports can only be done by editing the port list on the “Apply Changes / Edit Submodel Properties” dialog.

Local Submodel Dependencies

Since local submodels can use other local submodels as part of their definitions, it is very convenient to know how the local submodel dependencies are organized. You can view that just by clicking on the graph icon at the bottom of the model toolbar.

On the dependency graph viewer, all local submodels are represented by their names and corresponding icons. An arrow pointing from a submodel A to a submodel B means that submodel A is used by submodel B. Multiple arrows mean that a local submodel is used more than once.

Copying (Importing) a Local Submodel Between Models

It is possible to copy local submodel definitions between models. Once the submodel is copied from one model to another, the submodels can be modified and updated independently.

You can copy a local submodel definition by dragging a local submodel from the Functor Library to the model presentation area. The process is similar to the instantiation of a regular functor.

It is also possible to copy the submodel definition by clicking on the “Import submodel definition” button on the functor library bar of the local submodel tab of the Functor Library. The definitions of system and user submodels can also be imported using the corresponding “Import submodel definition” button on the functor library bar of the submodel tab of the Functor Library.

Turning a Local Submodel into a User Submodel (Publishing)

Once your local submodel has been developed and fully tested, you can turn it into a user submodel.

To publish a local submodel into a user submodel, click on the “Publish Submodel” button on the “Submodel Options” drop-down menu located on the model toolbar.

Turning a local submodel into a user submodel makes reusing the submodel easier — the submodel will always be available to be used in your next models — but it has some drawbacks as well. You are fully responsible for the consequences of updating a user submodel. Beware that, unlike local submodels, your models will not carry a copy of a user submodel as part of their definition. So, if you change a user submodel in a way that breaks compatibility with the models using its definition, those models will not work anymore.

See Also

Functor Library

Model Toolbar

Model Presentation