System Structure and Parameterization

For the simulation of complex systems, first a design of this system should be created. From a simulation perspective, each component has to be described with its inputs and outputs and its required parameters. This can be done using SSP by defining the wrapper of this component with an empty Component element comprising the connectors for the inputs and outputs and the component’s parameters.

The interaction of the components is defined by the connections. Connections can be made directly between components or via signal dictionaries. A signal dictionary is a collection of signals similar to a bus concept (e.g. like a CAN bus). During the design phase of a system, a signal dictionary can be a good way to predefine the available signal connections.

If the system has global parameters that shall be propagated to multiple components, the definition can also be made at system level. The mapping to the parameters of the components can be realized either using connections or through parameter bindings that can include parameter mappings.

The main result of the design of the complete simulation structure is the definition of all needed components and the used parameterization structure. Each component can be used as a design template for the implementation – including the wanted parameters. The system designer extracts each component into a separate SSP file as preparation for the implementation and sends it to the implementor.

The implementor of the component can import this SSP file as a template in his authoring tool and directly code the behavior using the defined input signals and the definition of the parameters to calculate the defined output signals.

After completion of the implementation, the component can be returned as a running entity in an SSP package file for insertion into the complete system structure by the integrator. The integrator can decide whether to merge the components from different sources into one file or use the components as references by using the appropriate mechanisms in SSP to just link to the original SSP files. The latter approach has the benefit that the components can be used “untouched” and any “warranty” given by the author of the component is not corrupted. Even traceability information can be retained this way.

A good system design can be used for various applications. The structure keeps the same for all these applications. The parameter settings are used to differentiate the applications. Therefore a good parametrization concept is important to facilitate this reuse. SSP supports the creation of a central parameterization structure for entire systems. The SSP parameter data model can be used to integrate parameters from various sources, including external parameter databases, which can export their parameter data as SSV data sets. Through the URI-based addressing mechanism, tools can support direct access to such databases from system structure descriptions.

After implementation of all components and provisioning of the parameter settings for a particular system everything is in place for running simulations. All these entities can be stored in one single SSP package, which can be imported by the executing system for running the simulation. Depending on the execution system, it might be necessary to define additional settings for the solver or other execution algorithms. The core SSP standard does not include these execution-specific settings, but layered standards will be defined to include those settings.

These complete instances of simulation systems can also be used as an archive for traceability purposes.

As an example, a system structure defined originally for software-in-the-loop testing can also be reused for hardware-in-the-loop testing. Where FMI enables the reuse of individual models across platforms, SSP enables the reuse of complete systems and subsystems, including their configurations, basic layouts, and parameters.

Data management tools can control the lifecycle of the SSP-based system structures. There is an increasing desire to reuse environment models to provide proven, consistent solutions for the validation of controller models in different projects and development stages (e.g., for virtual validation and HIL simulations).

Data management environments provide capabilities for managing model compositions, handling variants of systems and managing the parameter and signal interfaces of the different model systems.

The SSP approach enables the sharing of standardized system structure descriptions between data management, integration and configuration tools for SIL, MIL and HIL scenarios.

All XML-based file formats defined in the SSP standard allow optional ssc:Annotation elements to be inserted in all XML elements that represent entities of the underlying data model. This is achieved through the ssc:TAnnotations type defined in Section 4.2. Each ssc:Annotation element contains a required type attribute, which contains the namespace for that annotation, as defined in Section 2.1.3. The content of the ssc:Annotation element CAN be arbitrary XML data, and CAN make use of XML namespaces and XML schemas for combined validation where appropriate.

The System Structure Package (SSP) file format is a ZIP-based packaging format, and thus not XML-based. It offers a separate mechanism to include additional data and meta-data into the package format through the reserved extra/ ZIP entry prefix (i.e. top-level directory), as defined in Chapter 3. Files are placed inside sub-directories under that top-level directory using the namespace as defined in Section 2.1.3 as part of the sub-directory name. The content of files and further sub-directories placed in those sub-directories are unrestricted.

Both annotations and extra files extensions make use of a namespace mechanism based on reverse domain notation: The originator of a specification for additional data specifies a domain name under their control as the namespace for the additional data, in order to avoid conflicts due to name collisions. The namespace is used in reverse domain notation for the type attributes in the annotation mechanism and as part of the file entry prefix under extra/ in the extra files mechanism. All namespaces under both the org.modelica and org.ssp-standard domains are reserved for use in future layered standards (see below).

[ For example, extensions defined by the Modelica Association might make use of the org.modelica.ssp namespace. This could lead to annotations with a type attribute of org.modelica.ssp.something, and/or extra files under the extra/org.modelica.ssp.something sub-directory. ]

In all places where SSP file formats reference additional, potentially external, data, the reference not only caries a source specification (indicating where the data can be located, if it is not inlined), but also a MIME type attribute, specifying the file format of the data being referenced. The base standard specifies a minimum set of MIME types and related file formats (including specifically the SSP-defined file formats and FMI) that must be supported by implementations.

However implementations are free to support additional MIME types and file formats where sensible, and the exact semantics of support for additional file formats can be specified through layered standards, as described below.

In this fashion extension of SSP to support pre-existing, new or domain-specific file formats after the base standard has been finalized can be realized, as long as the file format can be semantically mapped to the SSP concepts already in place.

This optional element MUST contain definitions for all enumerations referenced in a file.

[ As a file-based interchange standard, the natural scope for units and enumerations is the file scope, so that files can be parsed and processed separately, without the need for cross-file references or scoped references with the possibilities of shadowing and ambiguities. Upon import tools are free to merge unit information across files or separate them between hierarchy layers as they see fit. ]

Each enumeration is defined through an Enumeration XML element:

The following XML child elements are specified for the Enumeration element:

This optional element MUST contain definitions for all units referenced in a file.

[ As a file-based interchange standard, the natural scope for units and enumerations is the file scope, so that files can be parsed and processed separately, without the need for cross-file references or scoped references with the possibilities of shadowing and ambiguities. Upon import tools are free to merge unit information across files or separate them between hierarchy layers as they see fit. ]

Each unit is defined through a Unit XML element:

The following XML child elements are specified for the Unit element:

The following XML child elements denote the data type of a connector or dictionary entry. [ Note that in the case of connectors the use of a type element itself is optional, in the case of dictionary entries it is required ].

The following XML child elements specify a transformation to be applied to a value prior to its use in a connection or parameter mapping:

The Dimension element is used to specify the dimensions of array connectors, signal dictionary entries, or parameter values.

The group GMetaData allows the specification of additional meta data for a given model element. Multiple (or no) MetaData elements may be present in a given model element.

The group GSignature allows the specification of digital signatures for a given model element. Multiple (or no) Signature elements may be present in a given model element.

This element contains information of a default simulation setup that is supplied with the system definition for informational purposes.

[ Note that in contrast to FMI 2.0/3.0 only start and stop time are specified here, since values like step size or tolerance depend on the specific solver or master algorithms employed and are hence not specified in this global element. Additional solver or master algorithm specific information can be supplied through the annotation mechanism, or using a future layered standard. ]

[ The handling of systems comprising components with differing units for the independent variable depends on the implementation. It should be noted that since FMI 2.0 the unit of the independent variable for FMUs is clearly specified: It defaults to seconds, however other units can be specified by explicitly defining the independent variable. This standard does not specify additional measures to deal with differing independent variable units, but leaves this to the implementation. ]

This optional element specifies the set of connectors of this model element, which represent the interface of the model element to the outside world. For components the set of connectors MUST match variables/ports of the underlying component implementation, e.g., for referenced FMI 2.0 FMUs, the name of a connector has to match the name attribute of the corresponding <ScalarVariable> element; for referenced FMUs that follow the OSI Sensor Model Packaging specification [OSMP150], the name of a connector of type Binary has to match the name attribute of the corresponding <osmp:osmp-binary-variable>. For FMI 3.0 FMUs, the connector name has to match either the name of the corresponding variable element, or one of its <Alias> elements.

Names of variable elements of an FMU might follow the “Variable Naming Conventions” specification as defined by the FMI standard. Hence, several variables might be grouped as a structure or an array. However, the name of a connector MUST match the name of a single variable.

Note that there is no requirement that connectors have to be present for all variables/ports of an underlying component implementation. At least those connectors MUST be present which are referenced in connections inside the SSD. [ Note that connectors do not have to be referenced in connections. Unreferenced connectors will yield the behavior that is specified for the underlying component variables/ports, e.g. an unconnected FMU input variable will remain at its default value during the whole simulation. The same is true for variables/ports that are not referenced through a connector at all. ]

The following XML attributes are specified for the Connector element:

The following XML child elements are specified for the Connector element:

The type of the Connector is identified by the presence of one of the XML child elements Real, Float64, Float32, Integer, Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Boolean, String, Enumeration, Binary, or Clock.

The dimensionality of the Connector is given by the presence of one or more Dimension elements.

The association of a connector to a clock is given by the presence of one or more Clock elements.

When Modelica models are represented in SSP, built-in input and output connectors shall be mapped as follows:

Modelica connectors of more advanced types are currently mapped in the following way:

[ Note that the current opaque mapping of more advanced types to Binary connectors is a temporary solution, and a more detailed mapping may be provided in future versions of the standard supporting more complex data types. ]

This optional XML element defines the geometry information of the model element, where (x1,y1) and (x2,y2) define the positions of the lower-left and upper-right corners of the model element in the coordinate system of its parent system. If x1>x2 this indicates horizontal flipping, y1>y2 indicates vertical flipping.

The optional attribute rotation (in degrees) defines an additional rotation (applied after flipping), where positive numbers indicate a counter clockwise rotation.

[Sometimes such a counter clockwise orientation is also called a left rotation (x→y), with the coordinate system orientation: x → right, y → up)]

The optional attribute iconSource defines an icon URI with the same semantics as for the source attribute of the Component element. If defined, this icon overrides any icon that may be defined in an .fmu file (as defined in the relevant FMI standards). It is RECOMMENDED that implementations that support graphical presentation support at least PNG and SVG file formats for the icon.

The optional attribute iconRotation defines the rotation (in degrees) of the icon. The optional attribute iconFixedAspectRatio defines whether the icon shall be fit into the extent defined by (x1,y1), (x2,y2) and iconRotation with fixed aspect ratio. The optional attribute iconFlip defines whether any flipping indicated by (x1,y1), (x2,y2) shall be applied to the icon graphics, too.

[If no explicit icon is given, the icon used by the tool to represent the system should be rotated accordingly.]

[ Graphical example for an ElementGeometry: ]

[The next examples show the effects of attributes of the ElementGeometry on the visual representation of a reference element:

*Non-transformed reference* (icon fills rectangle, left 2 inputs, right 1 output)

Coordinate systems:

Red: ConnectorGeometry
Blue: ElementGeometry

*Example 1: No flip* (x1<x2, y1<y2), rotation=0
iconRotation=0, iconFixedAspectRatio=true, iconFlip=IGNORED (relevant only if element is flipped)

*Example 2: No flip* (x1<x2, y1<y2), rotation=0
iconRotation=0, iconFixedAspectRatio=false, iconFlip=IGNORED

_
_

*Example 3: No flip* (x1<x2, y1<y2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=true, iconFlip=IGNORED

*Example 4: No flip* (x1<x2, y1<y2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=false, iconFlip=IGNORED

_
_

*Example 5: No flip* (x1<x2, y1<y2), rotation=ϕ
iconRotation=0, iconFixedAspectRatio=true, iconFlip=IGNORED

*Example 6: No flip* (x1<x2, y1<y2), rotation=ϕ
iconRotation=0, iconFixedAspectRatio=false, iconFlip=IGNORED

_
_

*Example 7: Horizontal flip* (x1>x2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=true, iconFlip=true

*Example 8: Horizontal flip* (x1>x2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=false, iconFlip=false

*Example 9: Horizontal flip* (x1>x2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=true, iconFlip=false

_
_

*Example 10: Vertical flip* (y1>y2), rotation=0
iconRotation=0, iconFixedAspectRatio=true, iconFlip=false

*Example 11: Horizontal and vertical flip* (x1>x2, y1>y2), rotation=0
iconRotation=0, iconFixedAspectRatio=true, iconFlip=false

*Example 12: Horizontal and vertical flip* (x1>x2, y1>y2)*, *rotation=0
iconRotation=0, iconFixedAspectRatio=true, iconFlip=true

_
_

*Example 13: Horizontal and vertical flip* (x1>x2, y1>y2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=true, iconFlip=true

*Example 14: Horizontal and vertical flip* (x1>x2, y1>y2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=false, iconFlip=true

*Example 15: Horizontal and vertical flip* (x1>x2, y1>y2), rotation=ϕ
iconRotation=ϕ, iconFixedAspectRatio=true, iconFlip=false

]

The ParameterBindings element provides the parameter bindings for a component or system, where each binding is specified in a ParameterBinding element. A parameter binding applies a set of parameter values (a parameter set), supplied by a parameter source (for example a parameter file) to parametrize a component or system.

For FMU components this allows the parametrization of the FMU’s parameters, structural parameters, and start values of other variables. For systems this allows the parametrization of complete (sub-)hierarchies of sub-systems and components using a hierarchical naming scheme.

When no parameter mapping is specified as part of the binding, then all the parameter values provided by the parameter source are applied using their original names. If a parameter matching this name is found in the system, the parameter value is applied. Otherwise that parameter value is ignored.

When a parameter mapping is specified as part of the binding, then only the mapped parameter values are applied, using their mapped-to names. Non-mapped parameter values are not applied in this case.

For FMU components parameter values are applied to FMU variables based on the variables’ names in the FMU, i.e. it is not required (but allowed) that those variables are referenced in connectors in the system description.

For systems parameter values are applied using the hierarchical names of parameters or other variables in the system.

The hierarchical names of the parameters or other variables of a system are formed in the following way:

[ For example for a system A containing a system B which contains an exposed parameter named SP1 and an element C with a parameter P2, the hierarchical names of the parameters in system A are B.SP1 and B.C.P2 respectively. The hierarchical name of those parameters inside system B are SP1 and C.P2 respectively, and the hierarchical name of P2 inside element C is just P2.

Therefore a parameter binding on element C shall reference the parameter P2 using its local name P2, not the hierarchical name C.P2, which would be valid for a parameter binding on system B. ]

Note that the hierarchical names of parameters or other variables do not have to be unique: If two or more variables end up with the same hierarchical name (due to so-called punning), then any parameter values being applied to that name MUST be applied to all of them. If this is not wanted, then it is up to the generating implementation to ensure that no punning occurs, through proper choice of system and element names.

[ For example, for a system A containing a system B with component C and variable D, and system A also containing a component called B.C and variable D, both variables will have the hierarchical name A.B.C.D. If this is not wanted, then proper care should be taken in naming component B.C and system B/component C in non-conflicting ways. The standard allows such punning, because the ability to have a . in the name of systems or components allows for example the replacement of a monolithic component with a system of components, or vice-versa, while keeping parameter names identical. ]

More than one ParameterBinding can be supplied. In this case all of the parameters found will be used to parametrize the component, with parameter values in ParameterBinding sources appearing at a succeeding position in the element order taking priority over prior sources at the same hierarchy level, should a parameter be included in more than one ParameterBinding source.

When ParameterBinding sources on multiple levels of the hierarchy supply values for the same parameter, bindings at a higher hierarchy level take precedence over lower levels, i.e. bindings at a system level take precedence over bindings at a sub-system or component level.

Parameter bindings for FMU components can be used to set any initial values in the FMU which are legal to change. It is assumed that the parameterization is applied prior to initializing for FMI 1.0, or before entering initialization mode for FMI 2.0/3.0. For structural parameters it is assumed that the parameterization is applied in configuration mode for FMI 3.0.

This means that variables eligible for parameterization are those with:

All kinds of system connectors can be parameterized. In case the system level connectors are connected to FMU components, the parameterization MUST be compatible with the variable in the connected FMU.

Parameter bindings that apply to a component that references another SSD/SSP are handled as if the top-level system of the SSD/SSP was present in the enclosing system instead of the component with one special case: Any parameter bindings in the component are treated as if they were present in the top-level system of the SSP/SSD after all parameter bindings of the system. Therefore they take priority over any of the existing parameter bindings (for parameters with identical names).

The following XML child elements are specified for the ParameterBinding element:

This optional element contains one or more components, signal dictionary references or systems that are the internal content of the given system.

The following XML child elements are specified for the Elements element:

This optional element provides the connections between connectors of the system, connectors of its elements and inbetween those connectors.

This element specifies a connection between two connectors, either of the system or its directly contained elements. Note that only connections between certain kinds of connectors are allowed, as specified in Section 5.3.2.1. Note also that the terms start and end in the attribute names of the connector, like startElement or endConnector, do not denote directionality of the data flow implied by the connector. That is determined by the combination of the semantics of the actual connectors (variables/ports) connected and their kind attributes.

Signal dictionaries can be seen as a description of a collection of signals. Such collections can also be seen as a “signal bus” (like a CAN-bus in embedded systems). One can use a signal dictionary as a specification of how a collection of signals shall look like with definition of signal names and their units during a design phase. When a large number of signals have to be handled, signal dictionaries can help to keep a system description clearly represented.

Another benefit of signal dictionaries is the possibility to define a mapping between two or more signal dictionaries that may differ by names or units, which is a common case when components are integrated into a system that come from different sources without a common design or architecture.

This optional element provides the set of defined signal dictionaries for the system.

A signal dictionary is a collection of signals which can be accessed in different systems at different levels of the hierarchy through signal dictionary references referencing the signal dictionary.

This element defines the extent of the system canvas. (x1,y1) and (x2,y2) define the lower-left and upper-right corner, respectively. Different from ElementGeometry, where x1 > x2 and y1 > y2 indicate flipping, x1 < x2 and y1 < y2 MUST hold here.

If undefined, the system canvas extent defaults to the bounding box of all ElementGeometry elements of the child elements of the system.

When displaying the content of a sub-system together with the enclosing parent system, the transformation of co-coordinates inside the sub-system to co-ordinates in the parent system is defined by the transformation from SystemGeometry.\{x1,y1,x2,y2} to ElementGeometry.\{x1',y1',x2',y2'}, where ElementGeometry.z' is the respective coordinate of the sub-system when instantiated in the parent system after rotation.

When importing or exporting systems, the nominal unit of the coordinates is 1 mm for all axis. The nominal unit is intended to ensure similar visual sizing and appearances when combining systems from different implementations.

[ The visual appearance of a length of 1 should be (roughly) 1 mm. Importing and exporting tools that support a graphical representation might use different coordinate systems. This common unit for coordinates is defined to allow a seamless integration of SSPs from different sources. Without such a common unit, an SSP exported in one tool might appear huge or tiny in the other tool. Hence, the exporting tool has to scale from its own coordinate system when exporting and the importing tool has to scale to its own coordinate system when importing an SSP. ]

[ Graphical example for a SystemGeometry: ]

[ Graphical example showing the interplay of SystemGeometry, ElementGeometry, ConnectorGeometry, and ConnectionGeometry: ]

[ Example how the given Geometries can be used to transform coordinates to show elements on different hierarchy levels in a single graphic:

Subsystem A is an element with an ElementGeometry (x1_Ae, y1_Ae, x2_Ae, y2_Ae) and a SystemGeometry (x1_As, y1_As, x2_As, y2_As).

B is an element in subystem A with an ElementGeometry coordinates (x1_Be, y1_Be, x2_Be, y2_Be).

To plot the element B in the system where A is located, use the following coordinate transformation:

x1_Be → (x1_Ae + (x1_Be - x1_As) * (x2_Ae - x1_Ae) / (x2_As - x1_As))

y1_Be → (y1_Ae + (y1_Be - y1_As) * (y2_Ae - y1_Ae) / (y2_As - y1_As))

x2_Be → (x1_Ae + (x2_Be - x1_As) * (x2_Ae - x1_Ae) / (x2_As - x1_As))

y2_Be → (y1_Ae + (y2_Be - y1_As) * (y2_Ae - y1_Ae) / (y2_As - y1_As)) ]

This optional element contains the set of purely graphical elements that are contained in the system, like notes, which have no semantic impact on the system but aid in presentation of the system in graphical user interfaces.

Currently the only graphical element defined is the Note element, which allows for simple textual notes to be placed into the system diagram, but in the future more elements might be added as needed for exchange of graphical information.

This type specifies a parameter that represents an IEEE754 double precision floating point number, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents an IEEE754 double precision floating point number, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents an IEEE754 single precision floating point number, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 32-bit signed integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 8-bit signed integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 8-bit unsigned integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 16-bit signed integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 16-bit unsigned integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 32-bit signed integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 32-bit unsigned integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 64-bit signed integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a 64-bit unsigned integer, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a Boolean value, or an array of such values.

For array parameters, values are specified as a space-separated list of values in row-major order, as specified in FMI.

This type specifies a parameter that represents a zero-terminated UTF-8 encoded string, or an array of such values.

The value of the parameter can alternatively be specified using one or more Value child elements:

It is an error if both value attribute and Value child elements are present.

For scalar parameters, or array parameters with a single element, either way of specifying the singular value can be used.

For array parameters with more than one element, values MUST be specified as child elements, with each element providing one element value in row-major order, as specified in FMI.

This type specifies a parameter that represents an enumeration value, or an array of such values, as specified by an enumeration definition.

The value of the parameter can alternatively be specified using one or more Value child elements:

It is an error if both value attribute and Value child elements are present.

For scalar parameters, or array parameters with a single element, either way of specifying the singular value can be used.

For array parameters with more than one element, values MUST be specified as child elements, with each element providing one element value in row-major order, as specified in FMI.

This type specifies a parameter that represents a length-terminated binary data type, or an array of such values.

The value of the parameter can alternatively be specified using one or more Value child elements:

It is an error if both value attribute and Value child elements are present.

For scalar parameters, or array parameters with a single element, either way of specifying the singular value can be used.

For array parameters with more than one element, values MUST be specified as child elements, with each element providing one element value in row-major order, as specified in FMI.

This element specifies a single mapping between a parameter in the source and a parameter of the system or component being parametrized. Through its optional GTransformationChoice element a transformation can be specified that is to be applied to the parameter value prior to its application to its target parameter.

The following XML child elements are specified for the MappingEntry element:

A dictionary entry defines a single signal in the signal dictionary.

The following XML child elements are specified for the DictionaryEntry element: