Skip to content

Expandable Connectors

Introduction​🔗

Certain use cases require a different approach to the standard connectors in Modelica. The requirement of a Modelica connector being balanced can make it challenging to change the signals being carried by the connector, for example to use different model configurations in a template based architecture if all the possible signals aren't known when building the architecture. There can also be a need to simply group signals together into a predefined heirarchy to improve readability of the model and to ensure compatibilty with external interfaces (e.g. when the model is exported as an FMU).

Composite and expandable connectors can be used for such use cases. Both connectors serve similar purposes. The difference between them being that expandable connectors provide a way to define connections without specifying all the variables involved in the connection.

This tutorial explains the concept of composite and expandable connectors in Modelica, how to define and use them in Impact.

Preparations for the Tutorial🔗

The example model package used in this tutorial can be checked out in the form of an Impact project by clicking here.

The models in the example package are built using components from the Modelica Standard Library (MSL 4.x.x). This tutorial is aimed at intermediate to experienced Modelica users and requires the use of the code view.

An example model🔗

ExpandableConnectors.TestMotor shows a model which uses causal signals to exchange information between two component models, one being the plant and the other being the controller. The plant model in this case is a simplified representation of an electric motor while the controller takes the target speed as input and uses the measured speed and current as part of feedback control. The individual signals need to be connected between the controller and the plant models.

Composite connector🔗

To simplify the connections, group the variables into a new connector. If the signals are known beforehand, i.e. the interface is well defined, a composite connector can be used. A logical way to group the connectors is to have one connector for the controller component which simply contains the real output voltage and speed_measured, current_measured inputs. A corresponding connector for the plant would contain the real input voltage and the speed_measured, current_measured outputs.

Composite connectors for Controller and Plant🔗

Right click on ExpandableConnectors.Components.Interfaces and select New model. Enter the Name as controllerConnector and Class specialization as Connector:

Switch to the code view and add the speed_measured, current_measured and voltage_ref variables by adding the following code:

    .Modelica.Blocks.Interfaces.RealInput speed_measured;
    .Modelica.Blocks.Interfaces.RealInput current_measured;
    .Modelica.Blocks.Interfaces.RealOutput voltage_ref;
The code view for controllerConnector should look like the following:

A composite connector contains instances of other connectors, not pure variables. In this case, the RealInput and RealOutput components are indeed connectors. This can be verified for example by looking at the code layer of Modelica.Blocks.Interfaces.RealInput.

Duplicate controllerConnector and name it plantConnector. Switch to the code view and edit voltage_ref to be RealInput and speed_measured, current_measured to be RealOutput so the code looks like the following:

Using composite connectors🔗

Create a new model ControllerWithCompositeConnector in the ExpandableConnectors.Components package. Drag in the following components: - ExpandableConnectors.Components.Controller - Modelica.Blocks.Interfaces.RealInput - ExpandableConnectors.Components.Interfaces.controllerConnector

Rename the RealInput to speed_target and and connect it to controller.speed_target.

If we try to connect controller.voltage to controllerConnector, a dialog is presented with the list of available variables, making it straightforward to select the correct one.

Connect controller.speed_measured and controller.current_measured to the corresponding variables in the connector. Your diagram layer should look like this:

In the same way, create ExpandableConnectors.Components.PlantWithExpandableConnector component using: - ExpandableConnectors.Components.Plant - ExpandableConnectors.Components.Interfaces.plantConnector

The diagram layer should look like:

Now you will create an experiment using these two components. Duplicate ExpandableConnectors.TestMotor and rename it to ExpandableConnectors.TestMotorUsingCompositeConnector. Delete the plant and controller components and drag in ExpandableConnectors.Components.PlantWithCompositeConnector and ExpandableConnectors.Components.ControllerWithCompositeConnector.

Connect: - sine.y to controllerWithCompositeConnector.speed_target - controllerWithCompositeConnector.controllerConnector to plantWithCompositeConnector.plantConnector

Simulating this model, the results can be compared to our original model to ensure that they are indeed the same.

Expandable connector🔗

The main concept of an expandable connector is that sub-connectors can be defined by connecting to it, even if these connectors are not there in the connector definition.

An expandable connector defines the minimum set of variables that should appear on the connector. This means additional variables can be added to the connector without changing the connector definition.

Expandable connector for Controller and Plant🔗

We can create a new model called motorControlBus in the ExpandableConnectors.Components.Interfaces package. Select expandable connector as the Class specialization.

This time we will use the same connector for both plant and controller components. We can leave this connector definition empty and add the variables when we make our component models using motorControlBus,

Using expandable connectors🔗

Build a controller model: - Duplicate ExpandableConnectors.Components.ControllerWithCompositeConnector and rename it to ControllerWithExpandableConnector. - Delete the existing controllerConnector component and drag in ExpandableConnectors.Components.Interfaces.motorControlBus

Compared to the composite connector, trying to connect controller.voltage to motorControlBus connector, a different dialog box is shown with an option called new_element. Selecting this option enables the addition of a signal which is not present in the connector definition.

Add voltage_ref, speed_measured and current_measured signals by connecting each of those to the connector and entering the new_element option. Your diagram layer should look like the following:

In the same way create PlantWithExpandableConnector: - Duplicate ExpandableConnectors.Components.PlantWithCompositeConnector and rename it to PlantWithExpandableConnector. - Delete the existing plantConnector component and drag in ExpandableConnectors.Components.Interfaces.motorControlBus

Trying to connect plant.voltage to motorControlBus, we get the same dialog again with the new_element option and the correct variables with the same names used in ControllerWithExpandableConnector need to be added. Add voltage_ref, speed_measured and current_measured signals by connecting each of those to the connector to end up with a diagram layer like this:

Now you will create an experiment using these two components. Duplicate ExpandableConnectors.TestMotor and rename it to ExpandableConnectors.TestMotorUsingCompositeConnector. Delete the plant and controller components and drag in ExpandableConnectors.Components.PlantWithExpandableConnector and ExpandableConnectors.Components.ControllerWithExpandableConnector.

Connect: - sine.y to ControllerWithExpandableConnector.speed_target - controllerWithExpandableConnector.motorControlBus to plantWithExpandableConnector.motorControlBus

Simulate this model, and compare the results against the original model and the composite connector variant to ensure they are the same.

Summary🔗

Some important differences between a composite and an expandable connector are highlighted below: - The variables in a composite connector need to be defined in the connector before being used in a component model. New variables can be added to an expandable connector without changing the connector definition.
- Since only the new_element option is shown for an empty connector even when signals have been added to the same connector in a different model, it is possible to add the wrong signal (e.g. because of a typo). Since only the defined variables are shown instead for a composite connector, there is a reduced possibility of adding the wrong signal. - Debugging missing signals can be more complicated in the case of an expandable connector as balance check cannot be done either for the component or the system model and the system model needs to be translated to see any errors. Running a balance check on the PlantWithExpandableConnector component shows this:

  • Since a composite connector needs to be balanced, debugging missing signals can be potentially simpler. For example, deleting one of the controller to controllerConnector connections in the ControllerWithCompositeConnector component and running the balance check shows this error which is an immediate indication of something being wrong:

Common use cases🔗

The following table lists some common use cases where expandable or composite connectors can be used.

Use case Custom connector required Expandable or Composite
Add new connections to an existing expandable connector in one of the Modelon libraries (e.g. add a new signal to an expandable control bus connector) No These connectors are expandable by default, no additional action is required from the user apart from using the new_element option in the diagram layer
Create hierarchical connectors (e.g. outputs.x.y) Yes Both expandable and composite connectors can be used, with the composite connector having the advantage of reducing the chances of modeling errors related to connecting to the wrong variable
Group multiple connectors to allow making a single connection with all of them Yes Composite if all the connectors are known, expandable
A connector representing a data bus connection with multiple signals Yes (if existing library connector cannot be used) Expandable connector to enable addition of more signals in the future. Currently known signals (minimum set) can be defined while keeping the connector expandable
Make connections where the content of the connectors can be changed (e.g. via parameters in components that are connected) Yes Since the signals present in the connector cannot be predefined, an expandable connector should be used.
Make connections in a model template, where the content of the connections are defined once the template is populated with specific components Yes Since the signals present in the connector cannot be predefined, an expandable connector should be used
A physical connector with multiple physical elements (e.g. an electrical plug with multiple pins) Yes Composite connector to since the physical connectors typically carry flow and potential variables and need to be balanced

Advanced concepts🔗

Some concepts which are not covered in this article but are relevant when working with connectors in Modelica:

  • Instead of creating two composite connector variants with different causality, a single connector can be created using Modelon.Blocks.Interfaces.RealConnector instead of the RealInput and RealOutput blocks. The causality of signals can be defined using different methods.
  • An expandable connector does not necessarily need to be empty. Since it defines the minimum set of variables, it can contain the known variables which need to be present in the model. Like mentioned under the common use cases, this provides the advantage of the correct variables being shown in the connect dialog while providing the possibility of adding new variables using the new_element option.
  • Since an expandable or composite connector can contain other connectors, they can be used to represent physical acausal connectors between components as well, e.g.:
  • Modelica.Mechanics.MultiBody.Interfaces.FlangeWithBearing: Composite connector containing rotational flange and multibody frame connector
  • An alternative to expandable connectors is using replaceable connectors (composite connectors that have explicitly defined content).