diff --git a/docs/examples/fmi_ls_ref_experiments_example.xml b/docs/examples/fmi_ls_ref_experiments_example.xml
index 1996e21..f4e7488 100644
--- a/docs/examples/fmi_ls_ref_experiments_example.xml
+++ b/docs/examples/fmi_ls_ref_experiments_example.xml
@@ -1,17 +1,24 @@
-
-
-
+
+
+
+
+
+
-
-
-
-
+
+
+
+
+
+
+
diff --git a/docs/index.adoc b/docs/index.adoc
index b1566d9..017480f 100644
--- a/docs/index.adoc
+++ b/docs/index.adoc
@@ -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
@@ -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
@@ -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
.ssv // Example of an SSV parameter file
+ .ssm // Example of an SSP parameter-mapping file
.exp // Example of a EXP experiment file
modelica/.mo // Example of a modelica model source file
...
@@ -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 <>, 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
@@ -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 `` 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]
+----
+
+
+
+
+
+
+----
+
+=== ``
+
+The root element `` contains the following attributes:
-.Experiments Attributes.
+.`` 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 `` contains the following elements:
+The root element `` contains the following elements:
-.`` element details.
+.`` Elements
[[table-schema-fmi-ls-ref-experiments-root-elements]]
-[cols="1,3"]
+[cols="1,1,2"]
|====
-|Element |Description
+|Element |Required |Description
|``
+|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 `` element in the layered standard manifest file.
+=== ``
The `` element contains the following attributes:
-.Experiment Attributes.
+.`` 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 `` element contains the following elements:
-.`` element details.
+.`` Elements
[[table-schema-fmi-ls-ref-experiment-elements]]
-[cols="1,3"]
+[cols="1,1,2"]
|====
-|Element |Description
+|Element |Required |Description
|``
+|Optional
|Parameters for the experiment setup.
|``
+|Optional
|Reference stimuli for the experiment setup.
|``
+|Optional
|Reference results for the experiment setup.
|====
+==== ``
+
+The `` element contains the following attributes:
+
+.`` 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.
+|====
+
+==== ``
+
+The `` element contains the following attributes:
+
+.`` 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.
+|====
+
+==== ``
+
+The `` element contains the following attributes:
+
+.`` 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 `` element contains the following elements:
+
+.`` Elements
+[[table-schema-fmi-ls-ref-references-elements]]
+[cols="1,1,2"]
+|====
+|Element |Required |Description
+
+|``
+|Optional, repeatable
+|Nested signal selection used to restrict which reference signals are compared.
+|====
+
+===== ``
+
+The `` element contains the following attributes:
+
+.`` 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.
+|====
diff --git a/schema/fmi3LayeredStandardReferenceExperiments.xsd b/schema/fmi3LayeredStandardReferenceExperiments.xsd
index 1df1d35..fe5a9ec 100644
--- a/schema/fmi3LayeredStandardReferenceExperiments.xsd
+++ b/schema/fmi3LayeredStandardReferenceExperiments.xsd
@@ -33,69 +33,144 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
----------------------------------------------------------------------------
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
This attribute specifies the MIME type of the parameter data source, which
defaults to application/x-ssp-parameter-set to indicate the SSV file format
- as specified in the SSP standard. No further types are currently defined,
- but can of course be added at a later date.
+ as specified in the SSP standard.
- This attribute indicates the source of the parameter source as a URI
- (cf. RFC 3986). For purposes of the resolution of relative URIs
- the base URI is the URI of the fmiReference file.
+ URI of the parameter data source. For SSP archives, this is resolved
+ relative to the layered standard reference file.
+
+
+
+
+
+
+ Optional SSP parameter-mapping file (SSM) used to map source names to
+ experiment target parameter names.
-
+
- This attribute specifies the MIME type of the time series data source, which
- defaults to text/csv to indicate the CSV file format as specified in XXX.
- No further types are currently defined, but can of course be added at a later
- date, e.g. for pre-existing time series file formats, like HDF5, MDF, etc.
+ This attribute specifies the MIME type of the stimuli data source, which
+ defaults to text/csv.
- This attribute indicates the source of the time series data as a URI
- (cf. RFC 3986). For purposes of the resolution of relative URIs
- the base URI is the URI of the current file.
+ URI of the stimuli data source. For SSP archives, this is resolved relative
+ to the layered standard reference file.
+
+
+
+
+
+
+ Default binding mode for stimuli columns. The current layered-standard
+ implementation only supports systemConnectorName.
+
+
+
+
+
+
+ Optional SSP parameter-mapping file (SSM) used to map stimuli names to
+ system connector names.
+
+
+
+
+
+
+
+
+
+
+
+
+ This attribute specifies the MIME type of the reference data source, which
+ defaults to text/csv.
+
+
+
+
+
+
+ URI of the reference result data source. For SSP archives, this is resolved
+ relative to the layered standard reference file.
+
+
+
+
+
+
+ Optional SSP parameter-mapping file (SSM) used to map reference signal names
+ to SSP output connector names.
+
+
+
+
+
+
+ Default binding mode for reference signal columns. The current layered-standard
+ implementation only supports systemConnectorName.
+
+
+
+
+
+
+
+
+
+ Name of the reference signal to include in comparison.