Orchestra

RT-LAB Orchestra is an add-on that extends RT-LAB’s connectivity capabilities to heterogeneous co-simulations.

Heterogeneous co-simulations consist of simulations written in different programming languages, or generated by various simulation tools. Although Simulink provides some connectivity capabilities through the use of S-functions, the main advantage of using RT-LAB Orchestra is flexibility: co-simulation components can be developed and tested by different teams, then integrated to form a cohesive co-simulation system.

When using the RT-LAB Orchestra, RT-LAB is referred to as the Framework, and simulation components that exchange data with this Framework are referred to as External Components, also known as Clients. RT-LAB Orchestra provides a real-time, user-configurable communication layer that sits on top of the RT-LAB Framework.

In this context, RT-LAB becomes a backbone that provides a transport layer between simulation components.

Currently supported External Components are:

• C code applications

• standard (non-RT-LAB and RT-LAB) Simulink models

• standalone Dymola models

As a software application, RT-LAB Orchestra consists of the following entities:

• a configuration file used to specify the simulation data exchange between the Framework and External Components; the communication layer depends on the content of this configuration file

• a library of Simulink blocks, the rtlab_orchestra Simulink library, that provides interfaces between the Framework and External Components

• a C code application programming interface, the Orchestra RT-API, which is used by External Components to exchange simulation data with the Framework. Calls to the RT-API are embedded in an External Component where the data exchange takes place

Each of these entities is further described below.

Configuring the RT-LAB Orchestra Communication Layer

The RT-LAB Orchestra Data Description File

You configure the RT-LAB Orchestra communication layer by specifying the simulation data to be exchanged in an eXtended Markup Language (XML) file called a Data Description File (DDF). A DDF is decomposed into a 4-level hierarchy. Each level is further described in subsequent sections. The figure below shows the structure of a sample DDF.

Open

The Orchestra Root Element

The <orchestra> element is at the top of a DDF. All the XML elements comprised between the opening and closing <orchestra> tags are part of the same co-simulation. Syntactically valid XML elements that are not explicitly required to configure RT-LAB Orchestra are ignored. Also, note that all XML tags and attributes in a DDF are in lower case.

Domain Elements

The next level down from the top element contains a list of <domain> elements. An RT-LAB Orchestra domain is a container for named data items exchanged between co-simulation components, also referred to in this context as domain participants. A domain is defined by the name attribute of its element. A domain name has to be unique inside the root element.

A <domain> element contains several Quality Of Services (QoS) attributes that define the connection policies followed by domain participants:

In the DDF, this attribute is controlled by the <hasStates> element. Note that some connection policies are not compatible: a connection with states has to be synchronous, and a synchronous connection doesn’t allow multiple publishers to the same domain. Incompatible connection policies are treated as errors by RT-LAB Orchestra.

In addition, the type of connection to a domain is specified using the <connection> element. Supported types are local and remote. For a local connection, the processes associated with the RT-LAB framework and the External Component are located on the same machine and they communicate through a shared memory segment.

For a remote connection, the processes associated with the RT-LAB framework and the External Component are located on different machines and they communicate through a reflective memory segment.

When specifying a remote connection, it is also necessary to provide information about the type of communication card that is used to connect an External Component to the Framework, as well as the PCI index (a positive integer) corresponding to where the card is inserted. This is done by using <card> element and <pciindex> elements respectively.

Data Sets

Each domain is required to contain both a Publish and a Subscribe set, possibly empty.

• The Publish set contains the list of data items written by the RT-LAB Framework to the communication layer, and therefore read by external domain participants.

• The Subscribe set contains the list of data items read from the communication layer by the RT-LAB Framework, and therefore published by an external component.

• It is important to note that the XML is generated from the framework view. 

• The Client can publish data that is described in the 'Subscribe set' or subscribe to data that are described in the 'Publish set'.

Data Items

Data items are the actual signals exchanged within a co-simulation. Data items are identified by a name attribute in a DDF. Item names have to be unique within a given domain.

Data items are further defined by a type and a length. The type corresponds to native types in the C programming language (such as double or int). The C-code char type is denoted by byte. The <length> element is used to represent data items that consist of arrays of native types. For example, a data item defined with the C-code int[4] corresponds to the DDF elements <type>int</type> and <length>4</length>

For documentation purposes, you can insert an optional <description> XML element inside an <item> element.

You can also assign a default value to data items in the Subscribe set. Valid formats for default values correspond to acceptable definitions for a C code double (e.g.: 1.2, +1e2, .E-2 etc.).

Note that it is an error to assign a default value to a data item that is part of the Publish set of a domain; this is because an Orchestra framework publishes all the data items of a Publish set at every time step, therefore default values would be overwritten before they can be read by a subscriber External Component.

Constraints on Element Names

The following constraints apply to domain and data item names:

• the names are case-sensitive,

• leading and trailing spaces are stripped, and the resulting stripped names are limited to 64 characters,

• the names have to consist of at least one non-space character.

• the names cannot contain a comma (,) or a pound sign (#).

The RT-LAB Orchestra CSV File

CSV stands for Comma Separated Values, a file format that is compatible with MS Excel. An Orchestra CSV file consists of a header followed by a body made up of rows of data.

The CSV Header

The header consists of 2 distinct and required elements, namely a Domain Descriptor and a Column List.

The Domain Descriptor provides a description of a DDF domain in the format of a pair of attribute/value pairs separated by :, namely following the format: domain attribute1=value1:attribute2=value2 etc.

The table below shows the list of defined attributes and the corresponding valid values.