Skip to content

Ssp experiment adaptation #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jkCXf9X4 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Ssp experiment adaptation #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ba2fd42
Initial ssp adaptation
jkCXf9X4 May 5, 2026
d5d19f6
Extend the docs and examples
jkCXf9X4 May 5, 2026
d3ff582
Restructure doc to better reflect hierarchy
jkCXf9X4 May 5, 2026
2f280d4
Minor
jkCXf9X4 May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions docs/examples/fmi_ls_ref_experiments_example.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
<?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."
description="Simple set of smoke tests to validate the integration of the SSP 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"
<Experiment name="Test1" description="Baseline steady-state test" target="SystemStructure.ssd"
startTime="0.0" stopTime="10.0" stepSize="0.001" tolerance="0.004">
<Stimuli source="test1-in.csv"/>
<References source="test1-ref.csv"/>
<Parameters source="test1-params.ssv" mapping="test1-params.ssm"/>
<Stimuli source="test1-in.csv" matchBy="systemConnectorName" mapping="test1-in.ssm"/>
<References source="test1-ref.csv" matchBy="systemConnectorName" mapping="test1-ref.ssm">
<Signal name="y"/>
<Signal name="z"/>
</References>
</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 name="Test2" description="Baseline dynamic test" target="SystemStructure.ssd" startTime="0.0" stopTime="15.0" stepSize="0.010">
<Parameters source="dynamic-params.ssv" mapping="dynamic-params.ssm"/>
<Stimuli source="test2-in.csv" type="text/csv" matchBy="systemConnectorName" mapping="test2-in.ssm"/>
<References source="test2-ref.hdf5" type="application/hdf5" matchBy="systemConnectorName" mapping="test2-ref.ssm">
<Signal name="u"/>
<Signal name="v"/>
</References>
</Experiment>
</Experiments>
184 changes: 162 additions & 22 deletions docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ The licenses text can be found in the link:LICENSE.txt[LICENSE.txt] file that ac

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.
The reference implementation in this repository also applies the experiment format to SSP archives, where the experiment file can identify a target `SystemStructure.ssd` and use SSP mapping files to bind parameters, stimuli, and reference results.

=== How to Read This Document

Expand Down Expand Up @@ -65,6 +66,7 @@ This supports the following use cases, among others:
* 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.
* Inclusion of SSP-oriented experiment bundles that target a system description, bind stimuli to connectors, and map reference signals to outputs.

=== Layered Standard Manifest File

Expand Down Expand Up @@ -239,6 +241,7 @@ 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>.ssm // Example of an SSP parameter-mapping file
<arbtrary filename>.exp // Example of a EXP experiment file
modelica/<arbitrary filename>.mo // Example of a modelica model source file
...
Expand Down Expand Up @@ -271,6 +274,7 @@ If the sub-role `validation` is given, the expectation is that the experiment(s)
If the sub-role `uncertainty-analysis` is given, the expectation is that the experiment(s) defined in the file can be used to perform an uncertainty analysis of the FMU in a simulation environment.

For files with type `application/x-ma-ls-experiments`, i.e. EXP files, the experiment is performed as specified in <<fmi-ls-ref-experiments>>, using the format defined therein.
For SSP archives, the same experiment structure may additionally carry a `target` attribute that identifies the archive-relative SSD to execute, plus optional SSP mapping files for parameters, stimuli, and references.

[bibliography]
== References
Expand All @@ -288,86 +292,222 @@ It is expected that this appendix will be moved to a separate document in the fu

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.
The reference implementation in this repository extends the same XML shape for SSP archives by adding an optional `target` attribute and explicit mapping fields for parameters, stimuli, and reference signals.

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:
An example of an experiments file for this layered standard is shown below:

[source, xml]
----
include::examples/fmi_ls_ref_experiments_example.xml[]
----

The element hierarchy is:

[source, text]
----
<Experiments>
<Experiment>
<Parameters>
<Stimuli>
<References>
<Signal>
----

=== `<Experiments>`

The root element `<Experiments>` contains the following attributes:

.Experiments Attributes.
.`<Experiments>` Attributes
[[table-schema-fmi-ls-ref-experiments-root-attributes]]
[cols="1,1,1,2"]
[cols="1,1,2"]
|====
|Attribute |Namespace |Value |Description
|Attribute |Required |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:
The root element `<Experiments>` contains the following elements:

.`<Experiments>` element details.
.`<Experiments>` Elements
[[table-schema-fmi-ls-ref-experiments-root-elements]]
[cols="1,3"]
[cols="1,1,2"]
|====
|Element |Description
|Element |Required |Description

|`<Experiment>`
|Required, repeatable
|Each element describes one experiment setup.
|====

An example of an experiments file for this layered standard is shown below:

[source, xml]
----
include::examples/fmi_ls_ref_experiments_example.xml[]
----

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

The `<Experiment>` element contains the following attributes:

.Experiment Attributes.
.`<Experiment>` Attributes
[[table-schema-fmi-ls-ref-experiment-attributes]]
[cols="1,2"]
[cols="1,1,2"]
|====
|Attribute |Description
|Attribute |Required |Description

|`name`
|Required
| Name of the experiment.

|`description`
|Optional
| Brief description of the experiment that is suitable for display to users.

|`target`
|Optional
| Archive-relative target system description for the experiment, e.g. `SystemStructure.ssd`.

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

.`<Experiment>` element details.
.`<Experiment>` Elements
[[table-schema-fmi-ls-ref-experiment-elements]]
[cols="1,3"]
[cols="1,1,2"]
|====
|Element |Description
|Element |Required |Description

|`<Parameters>`
|Optional
|Parameters for the experiment setup.

|`<Stimuli>`
|Optional
|Reference stimuli for the experiment setup.

|`<References>`
|Optional
|Reference results for the experiment setup.
|====

==== `<Parameters>`

The `<Parameters>` element contains the following attributes:

.`<Parameters>` Attributes
[[table-schema-fmi-ls-ref-parameters-attributes]]
[cols="1,1,2"]
|====
|Attribute |Required |Description

|`source`
|Required
| Source of the parameter data. The URI is resolved relative to the experiments file.

|`type`
|Optional
| MIME type of the parameter data source. Defaults to `application/x-ssp-parameter-set`.

|`mapping`
|Optional
| Optional SSP `SSM` file used to map parameter names onto the target system.
|====

==== `<Stimuli>`

The `<Stimuli>` element contains the following attributes:

.`<Stimuli>` Attributes
[[table-schema-fmi-ls-ref-stimuli-attributes]]
[cols="1,1,2"]
|====
|Attribute |Required |Description

|`source`
|Required
| Source of the stimuli data. The URI is resolved relative to the experiments file.

|`type`
|Optional
| MIME type of the stimuli data source. Defaults to `text/csv`.

|`matchBy`
|Optional
| Binding mode for stimuli columns. Defaults to `systemConnectorName`.

|`mapping`
|Optional
| Optional SSP `SSM` file used for explicit stimulus binding.
|====

==== `<References>`

The `<References>` element contains the following attributes:

.`<References>` Attributes
[[table-schema-fmi-ls-ref-references-attributes]]
[cols="1,1,2"]
|====
|Attribute |Required |Description

|`source`
|Required
| Source of the reference results. The URI is resolved relative to the experiments file.

|`type`
|Optional
| MIME type of the reference result data source. Defaults to `text/csv`.

|`matchBy`
|Optional
| Binding mode for reference signal columns. Defaults to `systemConnectorName`.

|`mapping`
|Optional
| Optional SSP `SSM` file used to map reference signal names to outputs.
|====

The `<References>` element contains the following elements:

.`<References>` Elements
[[table-schema-fmi-ls-ref-references-elements]]
[cols="1,1,2"]
|====
|Element |Required |Description

|`<Signal>`
|Optional, repeatable
|Nested signal selection used to restrict which reference signals are compared.
|====

===== `<Signal>`

The `<Signal>` element contains the following attributes:

.`<Signal>` Attributes
[[table-schema-fmi-ls-ref-signal-attributes]]
[cols="1,1,2"]
|====
|Attribute |Required |Description

|`name`
|Required
| Name of a reference signal to include in comparison.
|====
Loading
Loading