Overview

SystemML is an open XML file format for the exchange of any mathematical systems (in the engineering sense of a collection of interconnected processes). That is, a SystemML file specifies a collection of Processes knitted together into a computable integrated system by Links. SystemML is, thus, the common file format of SystemML-ready design clients and SystemML-ready execution clients (both "clients" with respect to SystemML).

A design client is a tool for constructing a system based on instructions from the user. An execution client is a tool for executing ("progressing") that system. Since they both talk the same language - SystemML - they can be built independently, and any execution client can execute a system designed by any design client. This allows Alice to pass a system to Bob as a SystemML file, safe in the knowledge that it fully specifies the system to be computed, even though Alice may not know what execution client or environment Bob will use to run the system, or what tools Bob might use to examine the system.

The SystemML file format specification does not specify anything about the processes that are included in SystemML documents, other than that they must be connectable in a particular way. The SystemML file, rather, specifies which processes to include, how they are connected, and carries parametrizations of those processes which are not meaningful without further information. To be able to read these parametrizations of individual processes, we must turn to the SystemML infrastructure.

File format

Extensions

Any of the specified tags described below may contain a tag <Client/>, which itself may contain one or more child tags holding client-specific information, under tags named for the client. For example, BRAHMS can store its own information under <Client><BRAHMS>...</BRAHMS></Client>. This information will be ignored by other Clients, which will more or less prevent inter-client information exchange. Implementation Configuration can be stored in this way in the Root System tag, for instance - see SystemML Version Control. Alternatively, graphical display information could be stored in each and every tag.

If such data becomes standardised, it may be imported into the standard, and a new tag defined that makes the information exchangeable between independent clients. No extensions should be made elsewhere, to avoid possible future conflicts.

System

A System is a container for other SystemML parts. The root tag of a SystemML document is the "root system", and is represented below. It can contain zero or more Subsystems, Processes, Links, or Exposes.

XML File or Snippet
<System Version="..." AuthTool="..." AuthToolVersion="..."> <Name>...</Name> <Title>...</Title> <System/> ... <Process/> ... <Link/> ... <Expose/> ... </System>
Version
The SystemML version in which this system is described. "AuthTool" and "AuthToolVersion" are the name and version of the tool that wrote this <System> tag.
Name
The name used to refer to this system within its context. NOTE that even though the root system is not referred to within the document, it must still be given a name in a valid SystemML System document (this name is needed to form Absolute Names). This name need not be meaningful, however.
Title
An optional field giving the descriptive title of the system.

A <Time/> tag will be added in future to support System Progression, specifying the time of the Execution Clock at which this System is represented.

Process

A Process represents a computable black-box component. It can be contained within any system.

XML File or Snippet
<Process> <Name>...</Name> <Class>...</Class> <State>...</State> <Time> <SampleRate>...</SampleRate> </Time> <Seed>...</Seed> </Process>
Name
The process name within the System, both for display and for reference.
Class
The SystemML class name of the process (that is, it must be the name of a node in the SystemML tree), also for display but primarily to tell the execution engine which process to instantiate.
State
This tag is unspecified by SystemML, and should contain the current State of the process in a form specified by the Component, and understood by any implementations of that Component.
SampleRate
Specifies the time resolution at which to run this process within this system. Non-integral sample rates must be specified as fractions (e.g. "10/3").
Seed
Specifies the seed for the Process, which can be used by the Process to initialise any pseudo-random generators it may use.

Link

A Link represents a connection piping an output of one process to an input of another. It can be contained within any system.

XML File or Snippet
<Link> <Name>...</Name> <Src>...</Src> <Dst>...</Dst> <Lag>...</Lag> </Link>
Name
The name of the Link, both for display and for reference.
Src
The output of a process that forms the source of this Link. It is usually specified as "ProcessName>>SetName>PortName", in which case the Link passes a single port. ">>SetName" can be omitted, in which case the default set is assumed. ">PortName" can be omitted, in which case all output ports in the specified set are piped to the Dst (and therefore Dst must be a set, not a port), and the Link passes a set instead of a port.
Dst
The input of a process that forms the destination of this Link. It is usually specified as "ProcessName>>SetName>PortName", in which case the Link passes a single port (and the Src must therefore be a port not a set). Often, ">PortName" will be omitted, in which case the port name is taken from the port name at Src. ">>SetName" can be omitted, in which case the default set is assumed. If a set is passed (Src references a set rather than a port), then Dst must not reference a port.
Lag
The delay of this Link (in sample periods for a discrete-time Link, or in seconds for a continuous-time Link).
Notes
  • A Link passing a port effectively defines that the specified input port exists in the specified input set of the specified process. A Link passing a set defines nothing - the set must already exist at the input of the specified process. In contrast, output ports of a system are defined implicitly in the specification of the process classes that are specified in the system - they are therefore created at run-time by the process implementation, which should comply with the specification. Therefore, connected inputs can be seen as being "offered" - there is no error if they are unrecognised by the process - whereas connected outputs can be seen as being "required" - if the process does not create them, the system is invalid.

Data

This tag is likely to be added in the future to support System Progression (storing complete System State at non-zero time). Some number of Data tags will be necessary to fully specify the contents of Data objects that are in transit across a Link at the specified time.

Expose

All connectable parts of a Subsystem "system" (sets and ports) can be referenced from the parent system by "drilling down" into the Subsystem explicitly, e.g. "system/process>port". Whilst this is effective, there may be a case for hiding the internals of a Subsystem, in which case we do not want the parent system poking Links down into it. To allow this, any connectable in a Subsystem can be made visible directly in the parent system, by "Expose"ing it. This allows connection to processes within a system from outside the system, without knowing its internal arrangement. An Expose can be contained within any system. An Expose can be viewed as placing a connectable (Set or Port) on the System itself (usually only Processes have connectables), that is internally connected to one (or more, in the case of an input) connectables inside the system.

XML File or Snippet
<Expose> <Name>...</Name> <What>...</What> <As>...</As> </Expose>
Name
The name of the expose for display, and the name of the expose for reference (it will not be referenced within the system). An expose has no functional effect in the root tag, but note that that root tag may at some point be included in a larger system, so an expose still makes sense there.
What
The name of the thing that is exposed. This can be any identifier that can be the Src or Dst of a Link tag (a Set, or a Port, but not a Process). "As" must take a form that suits the exposed object. If the exposed item is an input (Set or Port), more than one What tag may be included.
As
The name that the exposed thing is given in the parent system, for reference in a Link or in a further Expose. It must have an appropriate form for the object that is exposed.

Examples

Expose examples in the form "What ==> As". These are assumed to be found in a Subsystem "S2" within a parent system "S1", that itself has a Subsystem "S3". Objects are exposed exposed as Sets or Ports of the exposing system (in this case, "S1/S2"). Since the Subsystem cannot know what it will be called when dropped into the parent system, it cannot explicitly specify this in an Expose tag, so the parser must infer it instead.

P>>G ==> H
Exposes S1/S2/P>>G (an output set) as S1/S2>>H (the parser infers that the set is exposed on "S2", and that "H" is an output set name since an output set is being exposed).
P>> ==> H
Exposes S1/S2/P>> (the default output set) as S1/S2>>H (the parser infers that the set is exposed on "S2", and that "H" is an output set name since an output set is being exposed).
P>>G>A ==> B
Exposes S1/S2/P>>G>A (an output port on set G) as S1/S2>>>B (an output port on the default set; the parser infers that "B" is the output port name since a port is being exposed).
P>>G>A ==> H>B
Exposes S1/S2/P>>G>A (an output port on set G) as S1/S2>>H>B (an output port on set H).
S3/P>A ==> H>B
Exposes S1/S2/S3/P>A (an output port on the default set) as S1/S2>>H>B (an output port on set H).
P<A ==> H>B
Exposes S1/S2/P<A (an input port on the default set of P) as S1/S2>>H>B (an output port on set H) PARSE ERROR!
P<A ==> H<B
Exposes S1/S2/P<A (an input port on the default set of P) as S1/S2<<H<B (an input port on set H); ok, no parse error now.
Notes
  • The last example above illustrates why "Name" cannot do double duty as "As" - "H<B" is an illegal value for a "Name" field.
  • GOTCHA Since exposure exposes only that which is explcitly specified, exposing an input Port does not expose the implicit link destination that is the Process. Without exposure, you could link "P>A" to "Q", and "Q" would be offered an input Port called "A". If "S/Q" is inside a Subsystem, and we expose its input port "S/Q<B" as "S<A", then we might think we could link "P>A" to "S" and achieve the same connectivity. However, exposing "S/Q<B" has only exposed that port, not the implicit destination for links "S/Q". So the Subsystem does not know where the link is targeted. Therefore, we must link explicitly to the port ("P>A" ==> "S<A").

System (Subsystem)

A "Subsystem" (also a system) is a container and has exactly the same status as the root system.

XML File or Snippet
<?xml ... ?> <System Version="..."><!-- root system --> <Name>...</Name> <System Version="..."><!-- Subsystem --> <Name>...</Name> <System/> ... <Process/> ... <Link/> ... <Expose/> ... </System> </System>

Example

Here is a complete example of a SystemML document, generated by brahms_test nested under BRAHMS.