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 22:02]
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 65: Line 65:
 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. 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 181: 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// (Ctrl+G), 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 201: Line 211:
 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. 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.
  
Line 213: Line 223:
   * [[model_presentation|Model Presentation]]   * [[model_presentation|Model Presentation]]
   * [[dinamica_console|Dinamica Console]]   * [[dinamica_console|Dinamica Console]]
 +  * [[ego_script#​submodels|EGO Script — Submodels]]