no.ntnu.ihb.sspgen.ssp.SystemStructureDescription.xsd Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of dsl Show documentation
Show all versions of dsl Show documentation
A Kotlin DSL for generating SSP archives
This is the normative XML Schema 1.0 schema for the MAP SSP
SystemStructureDescription 1.0 format.
Version: 1.0
Copyright 2016 -- 2019 Modelica Association Project "SSP"
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Version of SSD format, 1.0 for this release.
This attribute gives the system structure a name, which can be used
for purposes of presenting the system structure to the user, e.g.
when selecting individual variant SSDs from an SSP.
This is the base type for all elements, currently consisting of components and systems.
The set of connectors of this element, which represent
the interface of the element to the outside world.
For components the set of connectors must match variable/ports
of the underlying component implementation, e.g. the referenced
FMU, by name.
Note that there is no requirement that connectors must
be present for all variables/ports of an underlying
component implementation. Only those connectors must
be present which are referenced in connections inside
the SSD.
This optional element defines the geometry information of the component.
(x1,y1) and (x2,y2) define the positions of the lower-left and upper-right
corners of the component in the coordinate system of the parent.
x1>x2 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 left rotation (x->y).
The coordinate system is oriented: 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 e.g. in an .fmu file (as disccused in the FMI group).
The optional attribute rotation defines the rotation (in degrees) of the icon.
The optional attribute FixedAspectRatio 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.
The set of parameter bindings for this element.
This attribute gives the element a name, which shall be unique
within the directly enclosing system. The name is used for
purposes of specifying the element's connectors in connections.
This attribute specifies the MIME type of the component, which defaults to
application/x-fmu-sharedlibrary to indicate an FMU. When referencing another
system structure definition file, the MIME type application/x-ssp-definition
is used, and the MIME type application/x-ssp-package is used for referenced
system structure packages (SSPs). No further types are currently defined.
This attribute indicates the source of the component as an URI
(cf. RFC 3986). For purposes of the resolution of relative URIs
the base URI is the URI of the SSD. Therefore for components
that are located alongside the SSD, relative URIs without scheme
and authority can and should be used to specify the component
sources. For components that are packaged inside an SSP that
contains this SSD, this is mandatory (in this way, the SSD URIs
remain valid after unpacking the SSP into the filesystem).
E.g. for an FMU called MyDemoFMU.fmu, that is located in the
resources directory of an SSP, the correct URI would be
"resources/MyDemoFMU.fmu".
When referencing another SSP, by default the default SSD of the
SSP (i.e. SystemStructure.ssd) is referenced. When a non-default
SSD should be selected, then the name of the non-default SSD must
be given through a fragment identifier, i.e. the URI
"resources/SubSSP.ssp#VariantB.ssd" would reference the VariantB.ssd
of SubSSP.ssp located in the resources directory relative to this SSD.
When the URI is a same-document URI with a fragment identifier, e.g.
"#other-system", then the fragment identifier should identify a
system element in this SSD document with an id attribute identical
to the fragment identifier. This mechanism can be used to instantiate
an embedded system definition multiple times through reference to
its definition element.
Note that implementations are only required to support relative URIs
as specified above, and that especially relative URIs that move beyond
the baseURI (e.g. go "up" a level via ..) are not required to be
supported by implementations, and are in fact often not supported for
security or other reasons. Implementations are also not required to
support any absolute URIs and any specific URI schemes (but are of
course allowed to support any and all kinds of URIs where useful).
When the referenced component is an FMU that contains multiple
implementations (e.g. Co-Simulation and Model Exchange), this optional
attribute can be used to determine which FMU implementation should be
employed. If the attribute is missing or uses the default value "any",
the importing tool is free to choose what kind of FMU implementation
to use. If the value is "CoSimulation" or "ModelExchange" the corresponding
FMU implementation must be used. It is an error if the specified type
of FMU implementation is not present in the FMU.
This element defines a signal dictionary, describing the signal dictionary
entries present in the signal dictionary.
The contents of the element can be used to provide a signal dictionary
inline, in which case the source attribute of the SignalDictionary element
must be empty.
The contents must be an ssb:SignalDictionary element, if the type attribute
of this element is application/x-ssp-signal-dictionary, or any other valid
XML content if the type attribute references another MIME type (in that case
there should be a layered specification that defines how embedding the content
works for that MIME type).
This attribute indicates the source of the signal dictionary as a URI
(cf. RFC 3986). For purposes of the resolution of relative URIs
the base URI is the URI of the SSD.
If the source attribute is missing, the signal dictionary is provided
inline as contents of the SignalDictionary element, which must be
empty otherwise.
For the default type application/x-ssp-signal-dictionary such inline
content must be an ssb:SignalDictionary element.
This attribute gives the signal dictionary a name, which shall be
unique within the directly enclosing system. The name is used for
purposes of specifying the signal dictionary referenced by a
signal dictionary reference. Name lookups occur in hierarchical
fashion, i.e. the name is first looked up in the system that
contains a signal dictionary reference. If that lookup yields
no match, the lookup is performed on the enclosing system, etc.,
until a match is found. It is an error if no matching signal
dictionary is found.
This attribute gives the name of the signal dictionary that is to
be referenced. Name lookups occur in hierarchical fashion, i.e.
the name is first looked up in the system that contains a signal
dictionary reference. If that lookup yields no match, the lookup
is performed on the enclosing system, etc., until a match is found.
It is an error if no matching signal dictionary is found.
This element describes a system, which can contain components and other systems as elements,
connectors as an interface to the outside world, and connections connecting the connectors
of itself and of its elements to another.
This element specifies a connection between two connectors,
either of the system or its directly contained elements.
Note that connections between connectors on a system are
allowed, so neither startElement nor endElement has to be
supplied.
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:
For component to component connections as well as for connections
between two connectors at the system level, currently the kind of
one connector must be output and of another connector must be
input, or for parameter connections the kind of one connector
must be calculatedParameter and the other must be parameter.
Information flows from the output/calculatedParameter to the
input/parameter connector.
For system to component connections the kinds of the connectors
must match, i.e. either both are input or both output or both
parameter or both calculatedParameter.
This optional element specifies a transformation that is to be
applied to the
source value prior to its conveyance to the target.
This optional element defines the geometry information of the
connection.
The start and end coordinates of the connection are derived
automatically
through the coordinates of the corresponding connectors. The
only relevant
geometry information provided by the connection geometry is a,
by default
empty, list of intermediate waypoint coordinates, which are to
be interpreted
as for the svg:polyline primitive, i.e. as waypoints for
straight line
segments, with the first and last points added automatically
based on the
translated coordinates of the start and end connectors.
Note that x and y coordinates are in the coordinate system of
the
enclosing system.
This attribute gives the name of the element that contains
the connector given as startConnector. If the attribute
is elided, then the startConnector names a connector on
this system.
This attribute gives the name of the connector that is
the start of the connection. If startElement is not
supplied this indicates a connector on this system,
otherwise the connector is to be found on the given
element.
This attribute gives the name of the element that contains
the connector given as endConnector. If the attribute
is elided, then the endConnector names a connector on
this system.
This attribute gives the name of the connector that is
the end of the connection. If endElement is not
supplied this indicates a connector on this system,
otherwise the connector is to be found on the given
element.
This attribute specifies whether automatic conversions between start
and end connector are performed using unit information potentially
available for both start and end definitions. If this attribute is
supplied and its value is true, then the environment will not
perform
any automatic unit conversions, otherwise automatic unit
conversions can be performed. This is also useful in conjunction
with
the optional linear transformation supplied via the
LinearTransformation
element: With suppressUnitConversion = true, the linear
transformation
is performed instead of any unit conversions, whereas otherwise the
linear transformation is performed in addition to any unit
conversions.
This optional 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.
This optional element contains the set of purely graphical elements
that are contained in the system, e.g. things 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 element defines a graphical note to be placed on the canvas of the
enclosing system. It is sized using the attributes so that the
coordinates
(x1,y1) and (x2,y2) define the positions of the lower-left and
upper-right
corners of the note in the coordinate system of the parent.
The note text is given by the text attribute. The presentation
expectation
is that the text is automatically sized ad wrapped in such a way that it
fits the note area. If this would lead to too small text, it might be
necessary to provide an interactive method (like expanding triangle, or
popup,
or other means) to show the remainder of the note text. Inside the text
attribute, newlines indicate paragraph breaks.
This element gives the type of the connector.
If a type is not supplied, the type is determined through
default mechanisms: For FMU components, the type of the
underlying variable would be used, for systems the types
of connected underlying connectors could be used if unambiguous.
If a type cannot be deduced unambinguously, the user should
be informed of this error. Equally, if the type of the connector
differs from the type of the underlying FMU variable this
constitutes an error.
This optional element gives the geometry information of the connector.
Note that x and y coordinates are in a special coordinate system, where
0,0 is the lower-left corner of the component/system, and 1,1 is the
upper-right corner of the component, regardless of aspect ratio.
For systems the placement of connectors for the inside and outside
view of the system is identical, the special coordinate system is just
translated to different actual coordinate systems, namely the one
determined by the ElementGeometry for the outside view, and the
one determined by SystemGeometry for the inside view.
This attribute gives the connector a name, which
shall be unique within the component or system and,
for components, must match the name of a relevant
variable/port in the underlying component implementation,
e.g. the referenced FMU.
Note that there is no requirement that connectors must
be present for all variables/ports of an underlying
component implementation. Only those connectors must
be present which are referenced in connections inside
the SSD.
This attribute specifies the kind of the given connector,
which indicates whether the connector is an input, an
output, both (inout), a parameter or a calculated parameter (i.e.
a parameter that is calculated by the component during initialization).
For components this must match the related kind of the underlying
component implementation, e.g. for referenced FMUs it must match the
combination of variability and causality.
For FMI 2.0 this means that the causality of the variable must
match the kind of the connector.
For FMI 1.0 this means that for connectors of kind input or output
the causality of the variable must be input or output and the
variability of the variable must be discrete or continuous (for
outputs also constant and parameter are allowable). For connectors
of kind parameter the causality must be input or internal and the
variablity must be parameter. For connectors of kind
calculatedParameter the causality must be output and the variablity
must be parameter.
For SignalDictionaryReferences, the kind of a given connector can
additionally be 'inout', which indicates that the semantics of the
connector are derived from the connections going to the connector.
This can be used for example to allow a connector to function as
both an input and output within the same SignaleDictionaryReference.
This provides a parameter binding for a component or system. For FMU components this
allows the parametrization of the FMU's parameters and start values of other variables
with a parameter source (e.g. a parameter file). Note that in this case the names
provided in the parameter source must match the names of the FMU variables, or must be
mapped to the names of the FMU variables through a ParameterMapping element, or are
ignored if no matching variable is found.
For systems the names in the parameter source must either match the hierarchical names
of parameters or other variables in the system, or must be mapped to those names through
a ParameterMapping element, or are ignored if no matching variable is found.
The hierarchical names of the parameters or other variables of a system are formed in the
following way: Any variables of the system exposed through connectors of the system have
the name of the connector as their name. For all elements of the system, the hierarchical
names of the variables of those elements are formed by prepending the element name and a
dot to the hierarchical names of the variables in that element. E.g. 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.
More than one ParameterBinding can be supplied, in which 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.
This means that variables eligible for parameterization are those with:
* either causality = "input" or a start value for FMI 1.0
* variability != "constant" and initial = "exact" or "approx" for FMI 2.0
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.
ParameterBindings 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).
This optional element can be used to provide parameter values inline
to the parameter binding, in which case the source attribute of the
ParameterBinding element must be empty.
The contents must be an ssv:ParameterSet element, if the type attribute
of the ParameterBinding element is application/x-ssp-parameter-set, or
any other valid XML content if the type attribute references another
MIME type (in that case there should be a layered specification that
defines how embedding the content works for that MIME type).
This element provides an optional parameter mapping, which specifies how
the parameter names and values provided in the parameter source are to be
mapped to the parameters of the component or system in question. If no
mapping is supplied, the parameter names of the parameter source are used
as is for name matching against the names of parameters in the component
or system and the values of the parameter source are not transformed further
before being applied.
The contents of the element can be used to provide a parameter mapping
inline, in which case the source attribute of the ParameterMapping element
must be empty.
The contents must be an ssm:ParameterMapping element, if the type attribute
of this element is application/x-ssp-parameter-mapping, or any other valid
XML content if the type attribute references another MIME type (in that case
there should be a layered specification that defines how embedding the content
works for that MIME type).
This attribute indicates the source of the parameter mapping as a URI
(cf. RFC 3986). For purposes of the resolution of relative URIs
the base URI is the URI of the SSD, if the sourcebase attribute
is not specified or is specified as SSD, and the URI of the
referenced component if the base attribute is specified as component.
This allows the specification of parameter mapping sources that reside
inside the component (e.g. an FMU) through relative URIs.
If the source attribute is missing, the parameter mapping is provided
inline as contents of the ParameterMapping element, which must be
empty otherwise.
Defines the base the source URI is resolved against: If the attribute
is missing or is specified as SSD, the source is resolved against the
URI of the SSD, if the attribute is specified as component the URI is
resolved against the (resolved) URI of the component source.
This attribute specifies the MIME type of the parameter source, which defaults
to application/x-ssp-parameter-set to indicate the SSP parameter set file format.
No further types are currently defined, but can of course be added at a later
date, e.g. for pre-existing parameter file formats, like CDF, etc.
This attribute indicates the source of the parameters as a URI
(cf. RFC 3986). For purposes of the resolution of relative URIs
the base URI is the URI of the SSD, if the sourcebase attribute
is not specified or is specified as SSD, and the URI of the
referenced component if the base attribute is specified as component.
This allows the specification of parameter sources that reside inside
the component (e.g. an FMU) through relative URIs.
Access to parameter sets over the SSP Parameter Repository Protocol
is mediated through URIs with the http or https scheme.
If the source attribute is missing, the parameter mapping is provided
inline as contents of a ParameterValues element, which must not be
present otherwise.
Defines the base the source URI is resolved against: If the attribute
is missing or is specified as SSD, the source is resolved against the
URI of the SSD, if the attribute is specified as component the URI is
resolved against the (resolved) URI of the component source.
Defines the optional prefix for name resolution and mapping purposes
for this binding. If this attribute is empty or not supplied no
prefix is used for name resolution and mapping, otherwise the specified
prefix is prepended to all names in the parameter source prior to
processing the normal name resolution or name mapping rules. This
allows the user to apply a parameter set normally intended for a component
(and thus containing bare parameter names) at a system level targeted to
one element of the system by supplying the name of the element plus a dot
as a prefix on the binding, thus causing all parameter names in the parameter
set to be treated as if they were specified with proper hierarchical names.
The attributes of this element, if present, specify reasonable default values
for running an experiment of the given system. Any tool is free to ignore this
information.
Default start time of simulation
Default stop time of simulation
© 2015 - 2025 Weber Informatics LLC | Privacy Policy