Using Submodels

Understanding submodels and how to use them
Submodels are groups of blocks contained within a single block. The behavior of a model containing submodel is mostly the same as an equivalent model where all blocks would be in the same layer.

Creating submodels

  1. 1.
    Given an existing model with various inter-connected blocks, select the blocks you wish to move into a submodel
  2. 2.
    Right-click on the canvas and then select “Create Submodel”
Select a few blocks to move into a new submodel
Right click and select “Create Submodel”
3. Enter the newly created Submodel by double-clicking on it
4. To go back to the main block diagram, you may hit the “↩️ Parent” button.
You may freely create as many layers of nested Submodels as you wish. When clicking the “↩️ Parent” button, you will be brought back one layer up. The “↩️ Parent” button will not be visible when editing the top-level model.

Submodel input and output ports

The block representing a submodel has as many input & output ports as its internal block diagram has “Inport” and “Outport” blocks respectively. You may add or remove input/output ports to a Submodel by entering it (double-click on it) and adding or removing blocks of types Inport or Outport.
Adding new I/O ports
  1. 1.
    Drag and drop an Inport or Outport block onto the canvas
Here, we are dragging an Outport block from the block library onto the canvas
2. Connect the port blocks
3. All Inport and Outport blocks get a corresponding port on the Submodel block
The new port called “Outport_1” may now be connected in the parent layer
You may remove I/O ports by removing their corresponding port block. This may lead to unconnected links that will show up as red lines. These unconnected links will often lead to model compilation failures, so you may need to reconnect or remove these links appropriately.

Submodel parameters

Just like the top-level model has optional model parameters, you may add new parameters at the submodel level, by first selecting a Submodel block and then clicking the + icon next to Submodel parameters in the right-side pane.
Parameters get propagated throughout nested layers of submodels, and all parameters defined in parent layers are visible to blocks within a submodel. Their names and expressions are visible in the right-side pane under Inherited parameters.
The syntax of model and submodel parameters follows a subset of Python where math and np(alias for numpy) modules are exposed. See Using Model Parameters for more information about parameters (submodel and model parameters follow the same syntax rules).
Parameter name conflicts and inheritance
If the name of a parameter in a Submodel conflicts with any parent Submodel parameter or an existing Model parameter, the value defined at the Submodel level will override the inherited value.
Using submodel parameters
The names defined as submodel parameters can be used by any blocks, just like model parameters. Example for a parameter-defined gain block:
Model parameters can be edited when no block is selected
Model parameters can be edited when no block is selected
Block parameters may be literals or refer to (sub)model parameters

Known limitations

Updated on 2022-03-28
As Collimator is still under heavy development, here is a non-comprehensive list of limitations specific to submodels:
  • Submodels may not have more than 7 input or output ports. Any extra Inport/Outport block within the submodel will not be reflected as an external port on the submodel block, and as a consequence can not be connected externally.
  • It is not currently possible to refer to existing parameters when defining a new parameter.
  • The exact behavior of submodel parameters is subject to change. We recommend using distinct names for each parameter to avoid unwanted conflicts, should the name inheritance rules change.
  • When creating submodels, it is possible that connecting links become somewhat entangled.
  • There is no option to “flatten” an existing submodel. This can be achieved by manually copy-pasting the blocks back to the parent model, and reconnecting the links.
  • Submodels do not have any special semantics and behave as if the blocks were all flattened out in the main model.