Experiments Format

This document specifies the Experiments Format, a simple XML-based file format that allows the description of experiment setups for simulation models, including parameters, stimuli, and reference results. This format is intended to be referenced from layered standards such as FMI-LS-REF.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (regardless of formatting and capitalization).

This document is licensed under the Attribution-ShareAlike 4.0 International license. The code is released under the 2-Clause BSD License. The licenses text can be found in the LICENSE.txt file that accompanies this distribution.

1. Introduction

1.1. Intent of This Document

This document specifies the Experiments Format (ma-hs-experiments), a simple XML-based file format for describing experiment setups for simulation models. The format allows tools to exchange experiment definitions including start and stop time, solver settings, parameter sets, stimuli, and reference results.

1.2. How to Read This Document

In key parts of this document, non-normative examples are used to help understand the format.

Conventions used in this document:

Non-normative text is given like this:

Especially examples are defined in this style.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (regardless of formatting and capitalization).

2. Experiments Format

Files using this format shall use the MIME type application/x-ma-hs-experiments, and a file type suffix of .exp.

An experiments file is a valid XML file that conforms to the schema defined in maHarmonizedSpecificationExperiments.xsd. The root element is <Experiments> with the following attributes:

Table 1. Experiments Attributes.
Attribute	Presence	Description
`name`	Required	Name of the set of experiments.
`description`	Optional	Brief description of the set of experiments that is suitable for display to users, e.g. indicating the purpose of the set of experiments.

Beside these attributes the root element <Experiments> contains the following elements:

Table 2. `<Experiments>` element details.
Element	Description
`<Experiment>`	Each element describes one experiment setup.
`<Annotations>`	Optional annotations as defined in the FMI standard.

An example of an experiments file is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<Experiments
    name="Smoke Tests"
    description="Simple set of smoke tests to validate the integration of an FMU into a simulation engine."
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../schema/maHarmonizedSpecificationExperiments.xsd">
    <Experiment name="Test1" description="Baseline steady-state test"
        startTime="0.0" stopTime="10.0" stepSize="0.001" tolerance="0.004">
        <Stimuli source="test1-in.csv"/>
        <References source="test1-ref.csv"/>
    </Experiment>
    <Experiment name="Test2" description="Baseline dynamic test" startTime="0.0" stopTime="15.0" stepSize="0.010">
        <Parameters source="dynamic-params.ssv"/>
        <Stimuli source="test2-in.csv"/>
        <References source="test2-ref.hdf5" type="application/hdf5"/>
    </Experiment>
</Experiments>

2.1. Experiment

Each experiment setup is described by an <Experiment> element.

The <Experiment> element contains the following attributes:

Table 3. Experiment Attributes.
Attribute	Presence	Description
`name`	Required	Name of the experiment.
`description`	Optional	Brief description of the experiment that is suitable for display to users.
`startTime`	Optional	Start time of the experiment setup.
`stopTime`	Optional	Stop time of the experiment setup.
`tolerance`	Optional	Tolerance for the experiment setup.
`stepSize`	Optional	Step size for the experiment setup.

The <Experiment> element contains the following child elements:

Table 4. `<Experiment>` element details.
Element	Description
`<Parameters>`	Parameters for the experiment setup.
`<Stimuli>`	Reference stimuli for the experiment setup.
`<References>`	Reference results for the experiment setup.
`<Annotations>`	Optional annotations as defined in the FMI standard.

2.2. Parameters

The <Parameters> element references a parameter file for the experiment. It contains the following attributes:

Table 5. Parameters Attributes.
Attribute	Presence	Description
`type`	Optional	MIME type of the parameter data source. Defaults to `application/x-ssp-parameter-set` to indicate the SSV file format as specified in the SSP standard.
`source`	Required	Source of the parameter file as a URI. Any relative URIs are to be interpreted relative to the location of the experiments file.

2.3. Stimuli and References

The <Stimuli> element references a time series data file containing input stimuli for the experiment. The <References> element references a time series data file containing reference (expected) results for the experiment. Both elements have the same structure.

Table 6. Time Series Data Attributes.
Attribute	Presence	Description
`type`	Optional	MIME type of the time series data source. Defaults to `text/csv`. Other supported types include `application/hdf5` for HDF5 files.
`source`	Required	Source of the time series data as a URI. Any relative URIs are to be interpreted relative to the location of the experiments file.

References

[RFC2119] RFC 2119. https://tools.ietf.org/html/rfc2119
[SSP20] System Structure and Parameterization 2.0. https://ssp-standard.org/docs/2.0/
[LICENSE] MA License text. https://raw.githubusercontent.com/modelica/fmi-standard/master/LICENSE.txt