Skip to content

Latest commit

 

History

History
230 lines (163 loc) · 7.89 KB

index.adoc

File metadata and controls

230 lines (163 loc) · 7.89 KB

Layered Standard References

Contents

Based on FMI 2.0 and FMI 3.0, this layered standard defines how to provide basic experiments with stimuli and reference results for limited re-validation purposes.

[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.]


Copyright © 2012-2024 The Modelica Association Project FMI.

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, reference stimuli and results, which can be used in 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. Layered Standard Manifest File

All information about the related files included with the FMU, as well as additional experiment definitions 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, reference stimuli and results 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

<Experiment>

Each element describes one additional experiment setup, including settings, stimuli, references and parameters.

<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:

link:examples/fmi_ls_ref_manifest_example.xml[role=include]

3. Common Concepts

This layered standard provides the capability to include additional related files, as well as multiple experiment setups, in an FMU. The experiment setups can include experiment-related settings, parameter sets, reference inputs, and reference outputs.

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 sufficient information to provide smoke test validation of an FMU in a new simulation environment.

3.1. Structure of the FMU Archive

Any related files, including parameter or time-series data 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>.csv            // Example of a CSV time series file
   modelica/<arbitrary filename>.mo   // Example of a modelica model source file
   ...

3.2. 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 experiments 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.

3.3. Experiment Setup

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

The <Experiment> element contains the following attributes:

Table 3. 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 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.

3.4. 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 5. 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, etc.

description

Brief description of the related file that is suitable for display to users.

References