Layered Standard References

Based on FMI 2.0 and FMI 3.0, this layered standard defines how to provide additional related files inside an FMU with role information.

[Note: Although the document refers to versions 2.0 and 3.0 of the FMI standard, everything described in this document also applies to all subsequent minor versions. For further information on compatibility, see section Versioning and Layered Standards in the FMI 3.0 specification.]

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 layered standard FMI-LS-REF, which allows the inclusion of related files into an FMU. This includes parameter sets, additional experiments, as well as other relevant files to the FMU, like the model sources, requirements, or specifications.

1.2. How to Read This Document

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

Conventions used in this document:

Non-normative text is given in square brackets in italic font: [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. Common Concepts

This layered standard provides the capability to include additional related files, in an FMU, in a structured way. These files are described in the layered standard manifest file, which is part of the FMU archive.

This supports the following use cases:

Inclusion of requirements, specifications, model sources, and other related files that are helpful in understanding and correctly using the FMU in a recognizable way.
The ability to provide multiple parameter sets with an FMU as part of the FMU archive.
Inclusion of additional experiments that provide sufficient information to enable smoke test validation of an FMU in a new simulation environment.

2.1. Layered Standard Manifest File

All information about the related files included with the FMU are contained in the layered standard manifest file. Table 1 shows the attributes of the fmiReferences root element of fmi-ls-manifest.xml.

Table 1. Manifest Attributes.
Attribute	Namespace	Value	Description
`fmi-ls-name`	`http://fmi-standard.org/fmi-ls-manifest`	`org.fmi-standard.fmi-ls-ref`	Name of the layered standard in reverse domain name notation.
`fmi-ls-version`	`http://fmi-standard.org/fmi-ls-manifest`	`1.0.0-rc.1`	Version of the layered standard. This layered standard uses semantic versioning, as defined in [PW13].
`fmi-ls-description`	`http://fmi-standard.org/fmi-ls-manifest`	`Layered Standard providing related files for an FMU.`	String with a brief description of the layered standard that is suitable for display to users.

Beside these attributes the root element fmiReferences contains the following elements:

Table 2. `fmiReferences` element details.
Element	Description
`<Related>`	Each element describes one additional related file present in the FMU archive.

An example of a manifest file for this layered standard is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<fmiReferences
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../schema/fmi3LayeredStandardReferenceManifest.xsd"
	xmlns:fmi-ls="http://fmi-standard.org/fmi-ls-manifest"
	fmi-ls:fmi-ls-name="org.fmi-standard.fmi-ls-ref"
	fmi-ls:fmi-ls-version="1.0.0-rc.1"
	fmi-ls:fmi-ls-description="Layered Standard providing related files for an FMU.">
	
	<Related type="text/modelica" source="modelica/mymodel.mo" role="model" description="Modelica Model Source"/>
	<Related type="application/x-ssp-parameter-set" source="baseline-params.ssv" role="parameter" description="Baseline Model Parameters"/>
	<Related type="application/x-ssp-parameter-set" source="midend-params.ssv" role="parameter" description="Midend Model Parameters"/>
	<Related type="application/x-ssp-parameter-set" source="highend-params.ssv" role="parameter" description="Highend Model Parameters"/>
	<Related type="application/x-ssp-parameter-set" source="dynamic-params.ssv" role="parameter" description="Dynamic Model Parameters"/>
	<Related type="application/x-ma-ls-experiments" source="smoke-tests.exp" role="experiment" description="Smoke Tests of FMU"/>
</fmiReferences>

2.2. Related Files

Any related files that are not part of the basic FMU, but are helpful in understanding and correctly using the FMU, are described by a <Related> element in the layered standard manifest file.

The <Related> element contains the following attributes:

Table 3. Related Attributes.
Attribute	Description
`type`	MIME type of the related file.
`source`	Source of the related file as a URI.
`role`	Role of the related file, e.g., `model`, `requirement`, `specification`, `parameter`, `experiment`, etc.
`description`	Brief description of the related file that is suitable for display to users.

The role attribute is used to indicate the purpose of the related file. Its value must be one of the following:

Table 4. Role Values.
Role	Description
`document`	Document file, e.g., a documentation file, or any other document related to the FMU that does not fit into the other categories.
`requirement`	Requirement file, e.g., a requirements specification document.
`specification`	Specification file, e.g., a design specification document that describes the FMU design.
`model`	Model source file, e.g., a Modelica model, that was used to create the FMU.
`parameter`	Parameter file, e.g., a parameter set in SSV format. See below for rules of application.
`system`	System file, e.g., a system description file that describes the system in which the FMU is used.
`testcase`	Test case file, e.g., a set of test cases that are used as part of the overall simulation task.
`experiment`	Experiment file, e.g., an experiment setup in the EXP format described in Appendix A, that can be used to perform basic validation (i.e. a smoke test) of the FMU in a simulation environment.
`result`	Result file, e.g., a result file that contains the results of an experiment or simulation run.
`method`	Method file, e.g., a method description file that describes the method used to create the FMU.
`rationale`	Rationale file, e.g., a rationale document that explains the design decisions made during the development of the FMU.
`report`	Report file, e.g., a validation, verification or result report.
`request`	Request file, e.g., a simulation request that lead to the simulation task and hence to the creation of the FMU.
`delivery`	Delivery file, e.g., a simulation delivery document that describes the delivery of the FMU or overall simulation task.
`executable`	Executable file, e.g., a binary executable file.
`configuration`	Configuration file, e.g., a configuration file that describes the configuration of a simulation environment or other related software system.
`other`	Other related file, e.g., a file not covered by the other roles.

2.3. Structure of the FMU Archive

Any related files, including parameter or experiment files, to be included in the FMU are placed in the following extra directory: /extra/org.fmi-standard.fmi-ls-ref. It is left to implementations on whether sub-directories in this directory are used, or whether all files are placed in the directory itself. Details are described in the following sections.

documentation
   fmi-ls-ref.{txt|html}              // Optional additional documentation

extra/org.fmi-standard.fmi-ls-ref     // Contains files related to this layered standard
   fmi-ls-manifest.xml                // The layered standard manifest file
   <arbtrary filename>.ssv            // Example of an SSV parameter file
   <arbtrary filename>.exp            // Example of a EXP experiment file
   modelica/<arbitrary filename>.mo   // Example of a modelica model source file
   ...

2.4. Documentation

When shipping an FMU with reference files, it is recommended to provide further information to the importer in the file documentation/fmi-ls-ref.{txt|html}. For example, this might concern additional information on what test cases are included, their intent, to be expected deviations, areas of interest, etc.

It is recommended to incorporate a link to the documentation/fmi-ls-ref.{txt|html} file in the main documentation of the FMU.

2.5. Specific processing rules

This section details specific processing rules for certain related files, given their roles and/or MIME types.

2.5.1. Role parameter

If a related file with role parameter is given, the expectation is that the parameter set defined in the related file can be applied as-is to the FMU.

For files with type application/x-ssp-parameter-set, i.e. SSV files, the parameter set is applied as if a parameter binding without any prefix or parameter mapping referencing this parameter set were present in a component referencing the FMU, according to the [SSP20] standard. This implies that the parameter values are applied to any variables of the FMU with identical names.

2.5.2. Role experiment

If a related file with role experiment is given, the expectation is that the set of experiments defined in the file can be performed on the FMU just using the resources present in the FMU.

For files with type application/x-ma-ls-experiments, i.e. EXP files, the experiment is performed as specified in Appendix A, using the format defined therein.

References

[PW13] Preston-Werner, T. (2013): Semantic Versioning 2.0.0. https://semver.org/spec/v2.0.0.html
[SSP20] System Structure and Parameterization 2.0. https://ssp-standard.org/docs/2.0/
[RFC2119] RFC 2119. https://tools.ietf.org/html/rfc2119
[LICENSE] FMI License text. https://raw.githubusercontent.com/modelica/fmi-standard/master/LICENSE.txt

Appendix A: Experiments Format

This appendix describes the format of experiment files that can be included in an FMU as part of the layered standard. The experiments file format is a simple XML-based format that allows the description of experiment setups, including parameters, stimuli, and references.

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

An experiments file is a valid XML file that contains a root element <Experiments> with the following attributes:

Table 5. Experiments Attributes.
Attribute	Namespace	Value	Description
`name`	Name of the set of experiments.	`description`	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 6. `<Experiments>` element details.
Element	Description
`<Experiment>`	Each element describes one experiment setup.

An example of an experiments file for this layered standard 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 the FMU into a simulation engine."
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../schema/fmi3LayeredStandardReferenceExperiments.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>

Each experiment setup is described by an <Experiment> element in the layered standard manifest file.

The <Experiment> element contains the following attributes:

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

The <Experiment> element contains the following elements:

Table 8. `<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.