Skip to content

Commit e009b3a

Browse files
pmaipmai
committed
Rewrite of individual variable sections for clarity
Signed-off-by: Pierre R. Mai <pmai@pmsf.de>
1 parent bd81f07 commit e009b3a

9 files changed

Lines changed: 70 additions & 89 deletions

‎doc/spec/binary_variables.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,11 @@ The version parameter of the MIME type `application/x-open-simulation-interface`
5959
It is an error if a version number is specified neither as part of the MIME type nor using the `@osi-version` attribute.
6060

6161
The guaranteed lifetime of the binary data buffer pointer transported through the actual variables is defined for each kind of variable, as specified in the following sections.
62+
63+
Generally the lifetime for inputs is from the time they are set to the time the corresponding co-simulation step calculation finishes.
64+
For outputs the lifetime is extended from the point the output is provided at the end of a co-simulation step until the end of the next co-simulation step.
65+
66+
This convention allows the use of FMUs in simulation engines that have no special support for the protocol buffer pointers:
67+
The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out of a model until the end of the next co-simulation calculation cycle.
68+
Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the model providing the output data.
69+
It is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine supporting FMI, and get valid results.

‎doc/spec/ground_truth_init_parameters.adoc‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,27 @@ All models can optionally consume `osi3::GroundTruth` via an initialization para
44
Its purpose is to provide the model with a view of the static environment, for example the map, in OSI format.
55

66
`OSMPGroundTruthInit` contains all static data encountered by the model during a simulation run, for example, roads.
7-
If it contains dynamic data, for example, moving objects, this data is not used and has no specific semantics.
7+
All data provided in this message can be assumed by the receiver to be static during the simulation run.
88

9-
If the model is instantiated multiple times, it is recommended that all instantiations should receive the exact same content.
9+
If the model is instantiated multiple times, all instantiations should receive the exact same content.
1010
This allows a model to do expensive map calculations only once during initialization, and to share the calculated data between multiple instantiations.
1111

12+
**Prefix**
13+
14+
Ground truth initialization paramters shall be named with the following prefix:
15+
16+
[source]
17+
----
18+
OSMPGroundTruthInit
19+
----
20+
1221
**Rules**
1322

14-
* `OSMPGroundTruthInit` shall be encoded as `osi3::GroundTruth`.
1523
* If a model needs ground truth during initialization, it shall have a parameter named `OSMPGroundTruthInit`.
1624
* `OSMPGroundTruthInit` shall be defined as a notional discrete binary input parameter variable, with `@causality="parameter"`, `@variability="fixed"` and `@initial="exact"`.
17-
* The MIME type of the variable shall specify the `@type=GroundTruth`.
25+
* The MIME type of the variable shall specify the `type=GroundTruth` as part of the MIME type parameters.
26+
* `OSMPGroundTruthInit` shall be encoded as `osi3::GroundTruth`.
1827
* `OSMPGroundTruthInit` shall contain all static data encountered by the model during a simulation run.
19-
* If `OSMPGroundTruthInit` contains any dynamic data, it shall not be used.
2028
* The IDs of objects in `OSMPGroundTruthInit` shall be identical to the IDs of the same objects contained in later `OSMPSensorViewIn` or other input data.
2129
* If the model is instantiated multiple times, then all instantiations should receive the exact same content stored in the `OSMPGroundTruthInit` parameter.
2230
* The guaranteed lifetime of the ground-truth protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2ExitInitializationMode` call.

‎doc/spec/sensor_data_inputs.adoc‎

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,8 @@
11
= Sensor data inputs
22

3-
Sensor-data inputs are present in logical models.
4-
The sensor data passed to the model depends on prior models or processes that generated the data.
5-
The exact details of the contents therefore depend on the processing pipeline.
6-
7-
The logical model can rely on the provided buffer remaining valid from the moment it is passed in until the end of the corresponding calculation.
8-
It does not need to copy the contents (zero-copy input).
9-
103
**Prefix**
114

12-
Sensor-data inputs shall be named with the following prefix:
5+
Sensor data inputs shall be named with the following prefix:
136

147
[source]
158
----
@@ -18,10 +11,10 @@ OSMPSensorDataIn
1811

1912
**Rules**
2013

21-
* Sensor data shall be encoded as `osi3::SensorData`.
22-
* If only one sensor-data input is configured, the prefix shall only be `OSMPSensorDataIn`.
23-
* If more than one sensor-data input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataIn[1]` and `OSMPSensorDataIn[2]`.
14+
* If only one sensor data input is configured, the prefix shall only be `OSMPSensorDataIn`.
15+
* If more than one sensor data input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataIn[1]` and `OSMPSensorDataIn[2]`.
2416
* Array indices shall start at 1 and shall be consecutive.
25-
* Each sensor-data input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`.
26-
* The MIME type of the variable shall specify the `@type="SensorData"`.
27-
* The guaranteed lifetime of the sensor-data protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2DoStep` call.
17+
* Each sensor data input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`.
18+
* The MIME type of the variable shall specify the `type="SensorData"` as part of the MIME type parameters.
19+
* Sensor data shall be encoded as `osi3::SensorData`.
20+
* The guaranteed lifetime of the sensor data protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2DoStep` call.

‎doc/spec/sensor_data_outputs.adoc‎

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,8 @@
11
= Sensor data outputs
22

3-
Sensor-data outputs are present in sensor models and logical models.
4-
5-
The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out until the end of the next co-simulation calculation cycle.
6-
Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the sensor model.
7-
This arrangement is required to support use of the sensor model FMUs in simulation engines that have no special support for the protocol buffer pointers.
8-
Using this convention, it is possible to daisy chain FMUs with protocol buffer inputs and outputs in a normal simulation engine, for example, MATLAB/Simulink, and get valid results.
9-
103
**Prefix**
114

12-
Sensor-data outputs shall be named with the following prefix:
5+
Sensor data outputs shall be named with the following prefix:
136

147
[source]
158
----
@@ -18,10 +11,10 @@ OSMPSensorDataOut
1811

1912
**Rules**
2013

21-
* Sensor data shall be encoded as `osi3::SensorData`.
22-
* If only one sensor-data output is configured, the prefix shall only be `OSMPSensorDataOut`.
23-
* If more than one sensor-data output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataOut[1]` and `OSMPSensorDataOut[2]`.
14+
* If only one sensor data output is configured, the prefix shall only be `OSMPSensorDataOut`.
15+
* If more than one sensor data output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataOut[1]` and `OSMPSensorDataOut[2]`.
2416
* Array indices shall start at 1 and shall be consecutive.
25-
* Each sensor-data output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`.
26-
* The MIME type of the variable shall specify `@type="SensorData"`.
27-
* The guaranteed lifetime of the sensor-data protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that.
17+
* Each sensor data output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`.
18+
* The MIME type of the variable shall specify `type="SensorData"` as part of the MIME type parameters.
19+
* Sensor data shall be encoded as `osi3::SensorData`.
20+
* The guaranteed lifetime of the sensor data protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that.

‎doc/spec/sensor_view_input_configuration.adoc‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,40 @@
11
= Sensor view input configuration
22

3-
Sensor-view input configurations are present in sensor models.
4-
53
For each notional sensor view input variable with the base prefix `OSMPSensorViewIn`, a corresponding calculated parameter with the base prefix `OSMPSensorViewInConfigRequest` and a parameter with the base prefix `OSMPSensorViewInConfig` can exist.
64

75
During FMI initialization mode, the simulation environment queries the value of `OSMPSensorViewInConfigRequest`.
8-
Taking this value into account, a suitable and supported sensor-view input configuration is determined.
6+
Taking this value into account, a suitable and supported sensor view input configuration is determined.
97
Before exiting initialization mode, the simulation environment then sets this configuration using the corresponding `OSMPSensorViewInConfig` parameter.
108

11-
129
**Prefix**
1310

14-
Sensor-view input configurations shall be named with the following prefix:
11+
Sensor view input configurations shall be named with the following prefix:
1512

1613
[source]
1714
----
1815
OSMPSensorViewInConfig
1916
----
2017

21-
Sensor-view input-configuration requests shall be named with the following prefix:
18+
Sensor view input-configuration requests shall be named with the following prefix:
2219

2320
[source]
2421
----
2522
OSMPSensorViewInConfigRequest
2623
----
2724

28-
2925
**Rules**
3026

27+
* If more than one sensor view input is to be configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewInConfigRequest[1]`, `OSMPSensorViewInConfig[1]`, `OSMPSensorViewInConfigRequest[2]`, and `OSMPSensorViewInConfig[2]`.
28+
* Array indices shall start at 1, shall be consecutive, and shall correspond between sensor view inputs and sensor view configuration parameters.
3129
* If the calculated parameter `OSMPSensorViewInConfigRequest` exists, then the corresponding parameter `OSMPSensorViewInConfig` shall exist.
32-
* The variable values shall be encoded as `osi3::SensorViewConfiguration`.
3330
* `OSMPSensorViewInConfigRequest` shall have a `@causality = "calculatedParameter"` and a `@variability = "fixed"` or `@variability = "tunable"`.
3431
* `OSMPSensorViewInConfig` shall have a `@causality = "parameter"` and a `@variability = "fixed"` or `@variability = "tunable"`.
3532
* The `@variability` values of `OSMPSensorViewInConfigRequest` and `OSMPSensorViewInConfig` shall match.
36-
* The MIME type of both variables shall specify `@type="SensorViewConfiguration"`.
33+
* The MIME type of both variables shall specify `type="SensorViewConfiguration"` as part of the MIME type parameters.
34+
* The variable values shall be encoded as `osi3::SensorViewConfiguration`.
3735
* As long as no non-zero value has been assigned to `OSMPSensorViewInConfig`, the value of the corresponding `OSMPSensorViewInConfigRequest` shall be the desired sensor view configuration for the corresponding variable `OSMPSensorViewIn`.
3836
This configuration is based on model-internal requirements or any other parameters on which this calculated parameter depends.
3937
* Once a non-zero value has been assigned to `OSMPSensorViewInConfig`, the value of the corresponding `OSMPSensorViewInConfigRequest` shall be an encoded OSI protocol buffer containing the same data as the `OSMPSensorViewInConfig`.
40-
* During FMI initialization mode, the simulation environment should query the value of `OSMPSensorViewInConfigRequest` and determine a suitable sensor-view input configuration.
41-
* Before exiting initialization mode, the simulation environment shall set the sensor-view input configuration using the corresponding `OSMPSensorViewInConfig` parameter.
38+
* During FMI initialization mode, the simulation environment should query the value of `OSMPSensorViewInConfigRequest` and determine a suitable sensor view input configuration.
39+
* Before exiting initialization mode, the simulation environment shall set the sensor view input configuration using the corresponding `OSMPSensorViewInConfig` parameter.
40+
* The guaranteed lifetime of the sensor view configuration protocol-buffer pointers shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the FMI initialization mode, indicating by the return of the `fmi2ExitInitializationMode` call.

‎doc/spec/sensor_view_inputs.adoc‎

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,8 @@
11
= Sensor view inputs
22

3-
Sensor-view inputs are present in sensor models.
4-
5-
The sensor model can rely on the provided buffer remaining valid from the moment it is passed in until the end of the corresponding calculation.
6-
It does not need to copy the contents (zero-copy input).
7-
83
**Prefix**
94

10-
Sensor-view inputs shall be named with the following prefix:
5+
Sensor view inputs shall be named with the following prefix:
116

127
[source]
138
----
@@ -16,11 +11,11 @@ OSMPSensorViewIn
1611

1712
**Rules**
1813

19-
* Sensor-view data shall be encoded as `osi3::SensorView`.
20-
* If only one sensor-view input is configured, the prefix shall only be `OSMPSensorViewIn`.
21-
* If more than one sensor-view input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewIn[1]` and `OSMPSensorViewIn[2]`.
14+
* If only one sensor view input is configured, the prefix shall only be `OSMPSensorViewIn`.
15+
* If more than one sensor view input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewIn[1]` and `OSMPSensorViewIn[2]`.
2216
* Array indices shall start at 1 and shall be consecutive.
23-
* Each sensor-view input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`.
24-
* The MIME type of the variable shall specify the `@type=SensorView`.
25-
* The guaranteed lifetime of the sensor-view protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2DoStep` call.
26-
* The sensor view passed to the model shall contain data as specified by the parameter `OSMPSensorViewInConfiguration`.
17+
* Each sensor view input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`.
18+
* The MIME type of the variable shall specify the `type=SensorView` as part of the MIME type parameters.
19+
* Sensor view data shall be encoded as `osi3::SensorView`.
20+
* The sensor view passed to the model shall contain data as specified by the parameter `OSMPSensorViewInConfiguration`.
21+
* The guaranteed lifetime of the sensor view protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2DoStep` call.

‎doc/spec/sensor_view_outputs.adoc‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,5 @@
11
= Sensor view outputs
22

3-
Sensor-view outputs are present in environmental effect models.
4-
5-
The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out until the end of the next co-simulation calculation cycle.
6-
Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the environmental effect model.
7-
This arrangement is required to support use of the environmental effect model FMUs in simulation engines that have no special support for the protocol buffer pointers.
8-
Using this convention, it is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine, for example, MATLAB/Simulink, and get valid results.
9-
103
**Prefix**
114

125
Sensor view outputs shall be named with the following prefix:
@@ -18,10 +11,10 @@ OSMPSensorViewOut
1811

1912
**Rules**
2013

21-
* Sensor-view data shall be encoded as `osi3::SensorView`.
22-
* If only one sensor-view output is configured, the prefix shall only be `OSMPSensorViewOut`.
23-
* If more than one sensor-view output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewOut[1]` and `OSMPSensorViewOut[2]`.
14+
* If only one sensor view output is configured, the prefix shall only be `OSMPSensorViewOut`.
15+
* If more than one sensor view output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewOut[1]` and `OSMPSensorViewOut[2]`.
2416
* Array indices shall start at 1 and shall be consecutive.
25-
* Each sensor-view output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`.
26-
* The MIME type of the variable shall specify the `@type="SensorView"`.
27-
* The guaranteed lifetime of the sensor-view protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that.
17+
* Each sensor view output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`.
18+
* The MIME type of the variable shall specify the `type="SensorView"` as part of the MIME type parameters.
19+
* Sensor view data shall be encoded as `osi3::SensorView`.
20+
* The guaranteed lifetime of the sensor view protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that.

0 commit comments

Comments
 (0)