Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
submodels [2026/07/10 21:16]
hermann 		submodels [2026/07/12 06:38] (current)
hermann
Line 15: Line 15:
 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. 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.
  
-> **Note:** 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.+> **Note:** The storage paths mentioned throughout this page (in the table below and in the [[#​where_submodels_are_stored|Where Submodels Are Stored]] section) differ between **Windows** and **Linux**; both are listed where relevant.
  
 [{{:​submodels:​submodel_with_badge.png|Functor icon is decorated by badge representing local submodel}}] [{{:​submodels:​submodel_with_badge.png|Functor icon is decorated by badge representing local submodel}}]
Line 63: Line 63:
 ===== Creating Local Submodels ===== ===== 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 //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.+Local submodels can be created by simply selecting the parts of a model that will be converted to a submodel and choosing //Edit// → //Create Submodel// ​(K). 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.+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 the [[#​updating_local_submodels|Updating Local Submodels]] section below for more information.
  
 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. 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.
Line 72: Line 72:
  
 {{youtube>​YvoteWC_lnI?​size=853x480&​rel=0|Creating local submodels }} {{youtube>​YvoteWC_lnI?​size=853x480&​rel=0|Creating local submodels }}
 +
 +==== Creating a Submodel Directly as a Script ====
 +
 +A submodel does not have to be created through the GUI: any ''​.ego''​ file that declares the right set of ''​@submodel.*''​ properties (name, description,​ group, and its input/​output port declarations) is a valid submodel. See [[ego_script#​submodels|Submodels]] in the EGO Script reference for the full property syntax.
 +
 +Whether a hand-written submodel script becomes a local or a user submodel is determined entirely by where the file is placed, following the same [[#​where_submodels_are_stored|storage locations]] used for submodels created through the GUI — the ''​@submodel.name''​ property, not the filename, is what identifies the submodel.
  
 ===== Instantiating Local Submodels ===== ===== Instantiating Local Submodels =====
Line 79: Line 85:
 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|model presentation]] area. 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|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.+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 — see [[#​copying_importing_a_local_submodel_between_models|Copying (Importing) a Local Submodel Between Models]] below.
  
 [{{:​submodels:​instatiating_local_submodel.gif|Instantiating functor corresponding to local submodel}}] [{{:​submodels:​instatiating_local_submodel.gif|Instantiating functor corresponding to local submodel}}]
Line 103: Line 109:
 Select //export functor inputs and outputs// on the [[model_presentation#​functor_action_bar|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. Select //export functor inputs and outputs// on the [[model_presentation#​functor_action_bar|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 //Submodel Options// on the model toolbar and then click //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.+> **Note:** Any port from the integer family of types can be declared a light enum, which presents it in the GUI as a labeled dropdown instead of a free-form numeric field, via the //Make port available as an enum value// control. This is not specific to submodels — it can be set on any carrier functor of an integer value type in any model, provided the carrier has an editor. When such a carrier'​s port is exported as a submodel input, its light enum configuration carries over into the submodel'​s interface. 
 + 
 +Choose //Submodel Options// on the model toolbar and then click //Apply Changes / Edit Submodel Properties//​. That brings up the submodel editor dialog where you can define a new name, description, documentation URL, 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. 
 + 
 +The submodel editor dialog also lets you set the submodel'​s **group**, which controls where it appears in the [[functor_library|Functor Library]]. A group name can contain subgroups by separating them with a colon (''":"''​);​ for example, ''"​Elevation Graph:​Tools:​Debug"''​ places the submodel in a //Debug// subgroup, itself inside a //Tools// subgroup, inside an //Elevation Graph// group. This is specific to submodels: an ordinary functor'​s placement in the Library is fixed by its own definition and cannot be changed by the user, but a submodel'​s group — and therefore whether it appears in a subgroup — is under the control of whoever creates or edits it.
  
 Below you can see two examples of updating the input and output ports of a local submodel: Below you can see two examples of updating the input and output ports of a local submodel:
Line 126: Line 136:
 {{youtube>​zx6moYBS3YU?​size=853x480&​rel=0|Removing ports and changing port order }} {{youtube>​zx6moYBS3YU?​size=853x480&​rel=0|Removing ports and changing port order }}
  
-===== Local Submodel Dependencies =====+===== 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.+Since submodels can use other submodels as part of their definitions,​ it is very convenient to know how those dependencies are organized. ​The dependency viewer is not limited to local submodels — it shows the local, user, store, and system submodels a model uses, and how they depend on each other. 
 + 
 +You can open it by clicking the graph icon at the bottom of the model toolbar, or by choosing //​Submodels//​ → //Show Model Dependencies//​ (Ctrl+U).
  
 [{{:​submodels:​local_submodel_dependencies.png|Local submodel dependency viewer}}] [{{:​submodels:​local_submodel_dependencies.png|Local submodel dependency viewer}}]
  
-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.+On the dependency graph viewer, ​every submodel involved is represented by its name and corresponding ​icon. 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 submodel is used more than once. Clicking on any local submodel shown in the visualization navigates to it. 
 + 
 +Clicking the //Remove Unused// button removes all local submodels defined by the current model that are not being used, either as part of the model'​s own definition or by any of its other local submodels.
  
 ===== Copying (Importing) a Local Submodel Between Models ===== ===== Copying (Importing) a Local Submodel Between Models =====
Line 143: Line 157:
  
 It is also possible to copy the submodel definition by clicking the //Import submodel definition//​ button on the [[functor_library#​functor_library_bar|functor library bar]] of the local submodel tab of the [[functor_library|Functor Library]]. The definitions of system and user submodels can also be imported using the corresponding //Import submodel definition//​ button on the [[functor_library#​functor_library_bar|functor library bar]] of the submodel tab of the [[functor_library|Functor Library]]. It is also possible to copy the submodel definition by clicking the //Import submodel definition//​ button on the [[functor_library#​functor_library_bar|functor library bar]] of the local submodel tab of the [[functor_library|Functor Library]]. The definitions of system and user submodels can also be imported using the corresponding //Import submodel definition//​ button on the [[functor_library#​functor_library_bar|functor library bar]] of the submodel tab of the [[functor_library|Functor Library]].
 +
 +Submodels already used in the model can also be imported through the //​Submodels//​ menu: //​Submodels//​ → //Import Selected Submodel// (Ctrl+G) imports the definition of the currently selected submodel instance, while //​Submodels//​ → //Import All Submodels// imports the definitions of every system, store, and user submodel used directly or indirectly by the model.
  
 ===== Turning a Local Submodel into a User Submodel (Publishing) ===== ===== Turning a Local Submodel into a User Submodel (Publishing) =====
Line 175: Line 191:
 ==== Checking for Updates ==== ==== Checking for Updates ====
  
-To check whether an installed store submodel has a newer, compatible update available, choose //​Submodels//​ → //Submodel Manager//, then use the //Check for Updates// option.+To check whether an installed store submodel has a newer, compatible update available ​(see [[#​versioning_and_compatibility|Versioning and Compatibility]] above), choose //​Submodels//​ → //Submodel Manager// ​(Ctrl+G), then use the //Check for Updates// option.
  
 ===== Deleting Submodels ===== ===== Deleting Submodels =====
Line 183: Line 199:
 To delete a local submodel, select it among the local submodels of the model and choose //Remove Submodel// on the //Submodel Options// menu. If the submodel is still being used — either by the main model script or by another local submodel — Dinamica reports this, shows where it is being used, and the removal fails. To delete a local submodel, select it among the local submodels of the model and choose //Remove Submodel// on the //Submodel Options// menu. If the submodel is still being used — either by the main model script or by another local submodel — Dinamica reports this, shows where it is being used, and the removal fails.
  
-> **Tip:** Before attempting to remove a local submodel, it is a good idea to check the [[#local_submodel_dependencies|dependency viewer]] (//​Submodels//​ → //Show Model Dependencies//​) to confirm the submodel is not being used elsewhere.+> **Tip:** Before attempting to remove a local submodel, it is a good idea to check the [[#submodel_dependencies|dependency viewer]] (//​Submodels//​ → //Show Model Dependencies//​) to confirm the submodel is not being used elsewhere.
  
 ==== Deleting a User or Store Submodel ==== ==== Deleting a User or Store Submodel ====
Line 193: Line 209:
 ===== Submodel Expansion and Execution ===== ===== Submodel Expansion and Execution =====
  
-Before executing a model, Dinamica EGO can expand all submodels used in it, replacing each submodel instance with its internal functor definition. This removes data copy constraints caused by submodel usage.+Before executing a model, Dinamica EGO can expand all submodels used in it, replacing each submodel instance with its internal functor definition. This expansion does not modify the model the user is working on — it is applied to a copy of the model that is submitted for execution, leaving the original model and its submodel instances untouched. This removes data copy constraints caused by submodel usage.
  
-  * This behavior is controlled by the //Expand submodels before executing a model// option, found under //Tools// → //Options// | //​Advanced//​. On the command line, it can be disabled using the ''​-disable-submodel-expansions''​ flag of the Dinamica Console.+  * This behavior is controlled by the //Expand submodels before executing a model// option, found under //Tools// → //Options// | //​Advanced//​. On the command line, it can be disabled using the ''​-disable-submodel-expansions''​ flag of the [[dinamica_console|Dinamica Console]].
   * When submodel expansion is enabled, the //Remove all unnecessary intermediate carrier functors before executing a model// option (same Options panel; ''​-remove-redundant-carriers''​ on the command line) can additionally be enabled to remove unnecessary intermediate carrier functors introduced by the expansion. Use with caution: removal can prevent the content of some output ports from being inspected and, in rare cases, may change model semantics.   * When submodel expansion is enabled, the //Remove all unnecessary intermediate carrier functors before executing a model// option (same Options panel; ''​-remove-redundant-carriers''​ on the command line) can additionally be enabled to remove unnecessary intermediate carrier functors introduced by the expansion. Use with caution: removal can prevent the content of some output ports from being inspected and, in rare cases, may change model semantics.
 +
 +It is also possible to manually expand submodels as part of editing the model itself, replacing a submodel instance — local, user, store, or system — with its internal definition. This can be done for the currently selected submodel via //​Submodels//​ → //Expand Selected Submodel// (Ctrl+E), or for every submodel used directly or indirectly by the model via //​Submodels//​ → //Expand All Submodels//​. Unlike the automatic expansion that happens before execution, these options do change the model being edited by the user — the expanded functors permanently replace the submodel instance in the model.
  
 ---- ----
Line 205: Line 223:
   * [[model_presentation|Model Presentation]]   * [[model_presentation|Model Presentation]]
   * [[dinamica_console|Dinamica Console]]   * [[dinamica_console|Dinamica Console]]
 +  * [[ego_script#​submodels|EGO Script — Submodels]]