.svg?alt=media&token=5313f65a-1c30-4743-946c-ae118addf50f)
π©βπ«Groups and Submodels
Last updated
Last updated
In Collimator, Groups and Submodels help to better organize your models. If you have many blocks and you want to group some, or you want to make a reusable group of them, Groups and Submodels help you do this.
Groups do not have any functional impact on your model, they just help you organize the content of your model to improve readability and browsing. A Group visually consolidates several blocks into a single virtual block.
You can create groups in two ways:
The first way is to use the drop down menu in the left of the Model Editor toolbar, and select Create Group.
This will create an empty Group. You can double-click to enter this Group, and continue editing your model as usual. If you have 1 or more blocks selected when doing this, these blocks will be moved into the new Group, with appropriate connections and port blocks created as well.
The second way is by selecting 2 or more blocks, right-click the selection, and choose Create Group. The outcome is the same as with the first way of creating Groups.
If you select and copy/paste a Group, the new copy has no link to the old Group you copied. The contents inside the new Group are the same as those of the old Group you coped. Editing the contents of the new Group has no impact on the old Group and vice versa.
Blocks inside a Group have access the same parameters as the diagram where they are instantiated. A Group instantiated at the top level of a model, has the same parameter namespace as the model. A Group inside a Submodel (see below), has the same parameter namespace as the Submodel.
Submodels are like Groups, but there is a single source and one or more instances. Once you have created a Submodel, you can then instantiate it in as many places in your model as you like, with each instance referring to the source. Changing the source results in all the instances changing as well. If you copy/paste an instance, the new instance references the source in the same way as the old instance.
You can create Submodels in two ways.
The first way is to create them directly in the project dashboard:
Once created, you can open and edit it just like a model.
The second way is to convert a Group into a Submodel. Select and right-click a Group, then choose Convert to Submodel. You will have to give your new Submodel a name. The name must not match the name of any other Submodel in your project.
Beside the source/instance behavior, Submodels have some unique attributes that differentiate them from both Groups and Models:
Submodels cannot be simulated on their own. They must be instantiated at least once in a model, and then the model is simulated.
Submodels have their own parameter namespace. You can add parameters to a Submodel namespace in the right panel (see below).
Submodels may have their own initialization script (see below).
Submodels can have a discrete_step. Enabling and setting this attribute has the following effects:
All discrete blocks inside the scope of the Submodels will be assigned this discrete_step.
The port blocks that form the boundary between the Submodel and what is outside, will be overloaded with a Zero-Order-Hold operation.
When inside an instance of a Submodelβthat is, when you open a model and navigate to one of its submodel childrenβyou see this:
This means you are viewing the Submodel in read-only mode. To edit the Submodel, click the Edit button in the upper-right. This will take you to the Submodel source, you can make changes. When you are done, you can return to the read-only view by pressing your browsers back button.
Another way to edit Submodels is to open them directly from the project dashboard, just as you would for a Model.
In the same way that a 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 do not get propagated throughout nested layers of Submodels, meaning that parameters defined in parent layers are not visible to blocks within their children Submodels.
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:
When editing your Submodels, you can create or add an initialization script as shown below.
The script will run when loading the Model before simulation. Any variables created by your script can be referenced by blocks within your Submodel. Unlike Submodel parameters, though, the variables created in an initialization script are not editable at the Submodel instance level.
You can add/remove/rename ports of Groups and Submodels by adding/deleting/renaming the port blocks inside the Group or Submodel. Port blocks can be added like any other block, drag from library, double click and search, or copy/paste. At present, you cannot manually change the index of a port block.
