From ba2fd4288450ff5a0e5e925f8199c0cbd6eb2fc0 Mon Sep 17 00:00:00 2001 From: Erik Rosenlund Date: Tue, 5 May 2026 10:17:12 +0200 Subject: [PATCH 1/4] Initial ssp adaptation --- ...mi3LayeredStandardReferenceExperiments.xsd | 125 ++++++++++++++---- 1 file changed, 96 insertions(+), 29 deletions(-) diff --git a/schema/fmi3LayeredStandardReferenceExperiments.xsd b/schema/fmi3LayeredStandardReferenceExperiments.xsd index 1df1d35..d3754b6 100644 --- a/schema/fmi3LayeredStandardReferenceExperiments.xsd +++ b/schema/fmi3LayeredStandardReferenceExperiments.xsd @@ -33,69 +33,136 @@ 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. + + + + + + + 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 stimuli data source, which + defaults to text/csv. - 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 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 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 reference 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 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. + + + + + + + + + + Name of the reference signal to include in comparison. From d5d19f62842972fe349f9d955b5afb06736b1952 Mon Sep 17 00:00:00 2001 From: Erik Rosenlund Date: Tue, 5 May 2026 10:52:47 +0200 Subject: [PATCH 2/4] Extend the docs and examples --- .../fmi_ls_ref_experiments_example.xml | 23 ++++-- docs/index.adoc | 78 ++++++++++++++++++- ...mi3LayeredStandardReferenceExperiments.xsd | 8 ++ 3 files changed, 100 insertions(+), 9 deletions(-) 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..2024eb2 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,6 +292,7 @@ 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`. @@ -324,7 +329,7 @@ An example of an experiments file for this layered standard is shown below: include::examples/fmi_ls_ref_experiments_example.xml[] ---- -Each experiment setup is described by an `` element in the layered standard manifest file. +Each experiment setup is described by an `` element in the experiments file. The `` element contains the following attributes: @@ -340,6 +345,9 @@ The `` element contains the following attributes: |`description` | Brief description of the experiment that is suitable for display to users. +|`target` +| Archive-relative target system description for the experiment, e.g. `SystemStructure.ssd`. + |`startTime` | Start time of the experiment setup. @@ -369,5 +377,73 @@ The `` element contains the following elements: |`` |Reference results for the experiment setup. + +|`` +|Name of a reference signal to include in comparison. +|==== + +The following tables describe the attributes of each experiment element in more detail. + +.`` Attributes +[[table-schema-fmi-ls-ref-parameters-attributes]] +[cols="1,2"] |==== +|Attribute |Description + +|`source` +| Source of the parameter data. The URI is resolved relative to the experiments file. + +|`type` +| MIME type of the parameter data source. Defaults to `application/x-ssp-parameter-set`. + +|`mapping` +| Optional SSP `SSM` file used to map parameter names onto the target system. +|==== + +.`` Attributes +[[table-schema-fmi-ls-ref-stimuli-attributes]] +[cols="1,2"] +|==== +|Attribute |Description + +|`source` +| Source of the stimuli data. The URI is resolved relative to the experiments file. + +|`type` +| MIME type of the stimuli data source. Defaults to `text/csv`. +|`matchBy` +| Binding mode for stimuli columns. Defaults to `systemConnectorName`. + +|`mapping` +| Optional SSP `SSM` file used for explicit stimulus binding. +|==== + +.`` Attributes +[[table-schema-fmi-ls-ref-references-attributes]] +[cols="1,2"] +|==== +|Attribute |Description + +|`source` +| Source of the reference results. The URI is resolved relative to the experiments file. + +|`type` +| MIME type of the reference result data source. Defaults to `text/csv`. + +|`matchBy` +| Binding mode for reference signal columns. Defaults to `systemConnectorName`. + +|`mapping` +| Optional SSP `SSM` file used to map reference signal names to outputs. +|==== + +.`` Attributes +[[table-schema-fmi-ls-ref-signal-attributes]] +[cols="1,2"] +|==== +|Attribute |Description + +|`name` +| Name of a reference signal to include in comparison. +|==== diff --git a/schema/fmi3LayeredStandardReferenceExperiments.xsd b/schema/fmi3LayeredStandardReferenceExperiments.xsd index d3754b6..cc610aa 100644 --- a/schema/fmi3LayeredStandardReferenceExperiments.xsd +++ b/schema/fmi3LayeredStandardReferenceExperiments.xsd @@ -156,6 +156,14 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + + Default binding mode for reference signal columns. The current layered-standard + implementation only supports systemConnectorName. + + + From d3ff582fc14f79f588e35e1c71a11c0da4756680 Mon Sep 17 00:00:00 2001 From: Erik Rosenlund Date: Tue, 5 May 2026 11:08:07 +0200 Subject: [PATCH 3/4] Restructure doc to better reflect hierarchy --- docs/index.adoc | 132 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 98 insertions(+), 34 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index 2024eb2..017480f 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -296,154 +296,218 @@ The reference implementation in this repository extends the same XML shape for S 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: -.Experiments Attributes. +[source, text] +---- + + + + + + +---- + +=== `` + +The root element `` contains the following 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 experiments 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. - -|`` -|Name of a reference signal to include in comparison. |==== -The following tables describe the attributes of each experiment element in more detail. +==== `` + +The `` element contains the following attributes: .`` Attributes [[table-schema-fmi-ls-ref-parameters-attributes]] -[cols="1,2"] +[cols="1,1,2"] |==== -|Attribute |Description +|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,2"] +[cols="1,1,2"] |==== -|Attribute |Description +|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,2"] +[cols="1,1,2"] |==== -|Attribute |Description +|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,2"] +[cols="1,1,2"] |==== -|Attribute |Description +|Attribute |Required |Description |`name` +|Required | Name of a reference signal to include in comparison. |==== From 2f280d4d4a194bd789f7acbd952c87382724449e Mon Sep 17 00:00:00 2001 From: Erik Rosenlund Date: Tue, 5 May 2026 21:41:26 +0200 Subject: [PATCH 4/4] Minor --- schema/fmi3LayeredStandardReferenceExperiments.xsd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/schema/fmi3LayeredStandardReferenceExperiments.xsd b/schema/fmi3LayeredStandardReferenceExperiments.xsd index cc610aa..fe5a9ec 100644 --- a/schema/fmi3LayeredStandardReferenceExperiments.xsd +++ b/schema/fmi3LayeredStandardReferenceExperiments.xsd @@ -52,9 +52,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - - + + +