systemcomposer.io.ModelBuilder

Model builder for System Composer architecture models

Description

Build System Composer™ models using a systemcomposer.io.ModelBuilder object. Build System Composer models with components and their position in an architecture hierarchy, ports and their mappings to components, connections among components through ports, and interfaces in architecture models and their mappings to ports.

Creation

builder = systemcomposer.io.ModelBuilder(profile)

Properties

Components — Component information

table

Component information, specified as a table containing this information:

• Hierarchical information of components

• Type of component (for example, Component, Reference Component, Variant Component, or Adapter)

• Stereotypes applied on a component

• Ability to set property values of a component

Ports — Ports information

table

Ports information, specified as a table. The table contains the information about ports, including their mappings to components and interfaces, and stereotypes applied on them.

Connections — Connections information

table

Connections information, specified as a table. The table contains information about the connections between the ports defined in Ports table as well as stereotypes applied on connections.

Interfaces — Interfaces information

table

Interfaces information, specified as a table. The table contains the definitions of various interfaces and their elements.

Examples

Import System Composer Architecture Using ModelBuilder Class

Import architecture specifications into System Composer™ using the systemcomposer.io.ModelBuilder utility class. These architecture specifications can be defined in an external source, such as an Excel® file.

In System Composer, an architecture is fully defined by four sets of information:

• Components and their position in the architecture hierarchy

• Ports and their mapping to components

• Connections among components through ports

• Interfaces in architecture models and their mapping to ports

This example uses the systemcomposer.io.ModelBuilder class to pass all of the above architecture information, including interface data definitions from an external source, and import a System Composer model.

In this example, architecture information of a small UAV system is defined in an Excel spreadsheet and is used to create a System Composer architecture model.

External Source Files

• Architecture.xlsx — This Excel file contains hierarchical information of the architecture model. This example maps the external source data to System Composer model elements. This information maps in column names to System Composer model elements.

     # Element    : Name of the element. Either can be component or port name.
     # Parent     : Name of the parent element.
     # Class      : Can be either component or port(Input/Output direction of the port).
     # Domain     : Mapped as component property. Property "Manufacturer" defined in the
                    profile UAVComponent under Stereotype PartDescriptor maps to Domain values
                    in excel source file.
     # Kind       : Mapped as component property. Property "ModelName" defined in the
                    profile UAVComponent under Stereotype PartDescriptor maps to Kind values
                    in excel source file.
     # InterfaceName : If class is of port type. InterfaceName maps to name of the interface
                       linked to port.
     # ConnectedTo : In case of port type, it specifies the connection to
                     other port defined in format "ComponentName::PortName".

• DataDefinitions.xlsx — This Excel file contains interface data definitions of the model. This example assumes this mapping between the data definitions in the Excel source file and interfaces hierarchy in System Composer.

     # Name        : Name of the interface or element.
     # Parent      : Name of the parent interface Name(Applicable only for elements) .
     # Datatype    : Datatype of element. Can be another interface in format
                     Bus: InterfaceName
     # Dimensions  : Dimensions of the element.
     # Units       : Unit property of the element.
     # Minimum     : Minimum value of the element.
     # Maximum     : Maximum value of the element.

Step 1. Instantiate the ModelBuilder Class

You can instantiate the ModelBuilder class with a profile name.

[stat,fa] = fileattrib(pwd);
if ~fa.UserWrite
    disp('This script must be run in a writable directory');
    return;
end

Specify the name of the model to build.

modelName = 'scExampleModelBuilder';

Specify the name of the profile.

profile = 'UAVComponent';

Specify the name of the source file to read architecture information.

architectureFileName = 'Architecture.xlsx';

Instantiate the ModelBuilder.

builder = systemcomposer.io.ModelBuilder(profile);

Step 2. Build Interface Data Definitions

Reading the information in the external source file DataDefinitions.xlsx to build the interface data model.

Create MATLAB® tables from the Excel source file.

opts = detectImportOptions('DataDefinitions.xlsx');
opts.DataRange = 'A2';

Force readtable to start reading from the second row.

definitionContents = readtable('DataDefinitions.xlsx',opts);

The systemcomposer.io.IdService class generates unique ID for a given key.

idService = systemcomposer.io.IdService();

for rowItr =1:numel(definitionContents(:,1))
    parentInterface = definitionContents.Parent{rowItr};
    if isempty(parentInterface)

In the case of interfaces, add the interface name to the model builder.

        interfaceName = definitionContents.Name{rowItr};

Get the unique interface ID.

getID(container,key) generates or returns (if key is already present) same value for input key within the container.

        interfaceID = idService.getID('interfaces',interfaceName);

Use builder.addInterface to add the interface to the data dictionary.

        builder.addInterface(interfaceName,interfaceID);   
    else

In the case of an element, read the element properties and add the element to the parent interface.

        elementName  = definitionContents.Name{rowItr};
        interfaceID = idService.getID('interfaces',parentInterface);

The ElementID is unique within a interface. Append E at the start of an ID for uniformity. The generated ID for an input element is unique within parent interface name as a container.

        elemID = idService.getID(parentInterface,elementName,'E');

Set the data type, dimensions, units, minimum, and maximum properties of the element.

        datatype = definitionContents.DataType{rowItr};
        dimensions = string(definitionContents.Dimensions(rowItr));
        units = definitionContents.Units(rowItr);

Make sure that input to builder utility function is always a string.

        if ~ischar(units)
            units = '';
        end
        minimum = definitionContents.Minimum{rowItr};
        maximum = definitionContents.Maximum{rowItr};

Use builder.addElementInInterface to add an element with properties in the interface.

        builder.addElementInInterface(elementName,elemID,interfaceID,datatype,dimensions,...
            units,'real',maximum,minimum);
    end
end

Step 3. Build Architecture Specifications

Architecture specifications are created by MATLAB tables from the Excel source file.

excelContents = readtable(architectureFileName);

Iterate over each row in the table.

for rowItr =1:numel(excelContents(:,1))

Read each row of the Excel file and columns.

    class = excelContents.Class(rowItr);
    Parent = excelContents.Parent(rowItr);
    Name = excelContents.Element{rowItr};

Populate the contents of the table.

    if strcmp(class,'component')
        ID = idService.getID('comp',Name);

The Root ID is by default set as zero.

        if strcmp(Parent,'scExampleSmallUAV')
            parentID = "0";
        else
            parentID = idService.getID('comp',Parent);
        end

Use builder.addComponent to add a component.

        builder.addComponent(Name,ID,parentID);

Read the property values.

        kind = excelContents.Kind{rowItr};
        domain = excelContents.Domain{rowItr};

Use builder.setComponentProperty to set stereotype and property values.

        builder.setComponentProperty(ID,'StereotypeName','UAVComponent.PartDescriptor',...
            'ModelName',kind,'Manufacturer',domain);
    else

In this example, concatenation of the port name and parent component name is used as key to generate unique IDs for ports.

        portID = idService.getID('port',strcat(Name,Parent));

For ports on root architecture, the compID is assumed as 0.

        if strcmp(Parent,'scExampleSmallUAV')
            compID = "0";
        else
            compID = idService.getID('comp',Parent);
        end

Use builder.addPort to add a port.

        builder.addPort(Name,class,portID,compID );

The InterfaceName specifies the name of the interface linked to the port.

        interfaceName = excelContents.InterfaceName{rowItr};

Get the interface ID.

getID will return the same IDs already generated while adding interface in Step 2.

        interfaceID = idService.getID('interfaces',interfaceName);

Use builder.addInterfaceToPort to map interface to port.

        builder.addInterfaceToPort(interfaceID,portID);        

Read the ConnectedTo information to build connections between components.

        connectedTo = excelContents.ConnectedTo{rowItr};

ConnectedTo is in the format:

(DestinationComponentName::DestinationPortName)

For this example, consider the current port as source of the connection.

        if ~isempty(connectedTo)
            connID = idService.getID('connection',connectedTo);
            splits = split(connectedTo,'::');

Get the port ID of the connected port.

In this example, port ID is generated by concatenating the port name and the parent component name. If the port ID is already generated, the getID function returns the same ID for the input key.

            connectedPortID = idService.getID('port',strcat(splits(2),splits(1))); 

Populate the connection table.

            sourcePortID = portID;
            destPortID = connectedPortID;

Use builder.addConnection to add connections.

            builder.addConnection(connectedTo,connID,sourcePortID,destPortID);
        end 
    end
end

Step 3. Import Model from Populated Tables with builder.build Function

[model,importReport] = builder.build(modelName);

Clean up artifacts.

cleanUp

Copyright 2020 The MathWorks, Inc.

More About

Definitions

Term	Definition	Application	More Information
architecture	A System Composer architecture represents a system of components and how they interface with each other structurally and behaviorally.	Different types of architectures describe different aspects of systems. You can use views to visualize a subset of components in an architecture. You can define parameters on the architecture level using the Parameter Editor.	Compose Architectures Visually Author Parameters in System Composer Using Parameter Editor
root	A root is at the top of an architecture hierarchy. A root architecture has a boundary defined by its architecture ports that surround the system of interest.	The root architecture has a system boundary surrounding your architecture model. You can add architecture ports that define interfaces across the boundary.	Compose Architectures Visually
model	A System Composer model is the file that contains architectural information, such as components, ports, connectors, interfaces, and behaviors.	Perform operations on a model: Extract root-level architecture. Apply profiles. Link interface data dictionaries. Generate instances from model architecture. A System Composer model is stored as an SLX file.	Create Architecture Model with Interfaces and Requirement Links
component	A component is a replaceable part of a system that fulfills a clear function in the context of an architecture. A component defines an architectural element, such as a function, another system, hardware, software, or other conceptual entity. A component can also be a subsystem or subfunction.	Represented as a block, a component is a part of an architecture model that can be separated into reusable artifacts. Transfer information between components with: Port interfaces using the Interface Editor Parameters using the Parameter Editor	Compose Architectures Visually
port	A port is a node on a component or architecture that represents a point of interaction with its environment. A port permits the flow of information to and from other components or systems.	Component ports are interaction points on the component to other components. Architecture ports are ports on the boundary of the system, whether the boundary is within a component or the overall architecture model. The root architecture has a boundary defined by its ports.	Compose Architectures Visually
connector	Connectors are lines that provide connections between ports. Connectors describe how information flows between components or architectures.	A connector allows two components to interact without defining the nature of the interaction. Set an interface on a port to define how the components interact.	Compose Architectures Visually

Algorithms

Components	Description
addComponent(compName,ID,ParentID)	Add component with name and ID as a child of component with ID as ParentID. In case of root, ParentID is 0.
setComponentProperty(ID,varargin)	Set stereotype on component with ID. Key value pair of property name and value defined in the stereotype can be passed as input. In this example builder.setComponentProperty(ID,'StereotypeName',... 'UAVComponent.PartDescriptor','ModelName',kind,'Manufacturer',domain) ModelName and Manufacturer are properties under stereotype PartDescriptor.

Ports	Description
addPort(portName,direction,ID,compID)	Add port with name and ID with direction (either Input or Output) to component with ID as compID.
setPropertyOnPort(ID,varargin)	Set stereotype on port with ID. Key value pair of the property name and the value defined in the stereotype can be passed as input.

Connections	Description
addConnection(connName,ID,sourcePortID,destPortID)	Add connection with name and ID between ports with sourcePortID (direction: Output) and destPortID (direction: Input) defined in the ports table.
setPropertyOnConnection(ID,varargin)	Set stereotype on connection with ID. Key value pair of the property name and the value defined in the stereotype can be passed as input.

Interfaces	Description
addInterface(interfaceName,ID)	Add interface with name and ID to a data dictionary.
addElementInInterface(elementName,ID,interfaceID,datatype,dimensions,units,complexity,Maximum,Minimum)	Add element with name and ID under an interface with ID as interfaceID. Data types, dimensions, units, complexity, and maximum and minimum are properties of an element. These properties are specified as strings.
addAnonymousInterface(ID,datatype,dimensions,units,complexity, Maximum,Minimum)	Add anonymous interface with ID and element properties like data type, dimensions, units, complexity, maximum, and minimum. Data type of an owned interface cannot be another interface name. Owned interfaces do not have elements like other interfaces.

Interfaces and Ports	Description
addInterfaceToPort(interfaceID,portID)	Link an interface with ID specified as InterfaceID to a port with ID specified as PortID.

Models	Description
build(modelName)	Build model with model name passed as input.

Logging and Reporting	Description
getImportErrorLog	Get ErrorLogs generated while importing the model. Called after the build function.
getImportReport	Get a report of the import. Called after the build function.

Version History

Introduced in R2019b