Skip to content

Commit 668b5ec

Browse files
restenbrestenb
committed
updated configuration description to include ECCO algorithm changes
1 parent 3be1b77 commit 668b5ec

File tree

1 file changed

+30
-8
lines changed

1 file changed

+30
-8
lines changed

‎libcosim/configuration.md‎

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,21 @@ The OSP system structure configuration format is based on the OSP Inteface Speci
1212
[OSP-IS](https://open-simulation-platform.com/specification/){:target="_blank"}
1313
and is used to configure the simulation system structure, including
1414
connections between FMUs and setting of initial values for input and parameter variables. The configuration format is XML according to schema
15-
[OspSystemStructure.xsd](https://open-simulation-platform.com/xsd/OspSystemStructure-0.1.xsd){:target="_blank"}.
15+
[OspSystemStructure.xsd](https://open-simulation-platform.com/xsd/OspSystemStructure-0.1.1.xsd){:target="_blank"}.
1616
Description of the OspSystemStructure elements and their attributes are shown below. Code implementation examples follow.
1717

1818
## \<OspSystemStructure>
1919
`<OspSystemStructure>` is the root element that contains xml elements as specified below.
2020

21-
| `<OspSystemStructure>` | Description |
21+
| Sub-element | Description |
2222
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
2323
| <*StartTime*> | Simulation starting time, unit in seconds.|
2424
| <*BaseStepSize*> | Base step size of co-simulation, aka, macro time step size, unit in seconds.|
25-
| <*Algorithm*> | Co-simulation master algorithm, currently a `fixedStep` algorithm is supported.|
25+
| <*Algorithm*> | Co-simulation master algorithm. Currently supports `fixedStep` and `ecco`.|
2626
| <*Simulators*> | Contains all sub-simulators in the system specified as `<simulator>` elements.|
2727
| <*Functions*> | Contains all functions, currently supported functions include `LinearTransformation`, `Sum`, `VectorSum`. |
2828
| <*Connections*> | Contains all scalar and variableGroup connections between simulators, or between simulators and functions. Sub-elements may include: `<VariableConnection>`, `<SignalConnection>`, `<VariableGroupConnection>` and `<SignalGroupConnection>`. |
29+
| <*EccoConfiguration*> | Contains configuration specific to the ECCO *(Energy-Conservation-based Co-simulation)* algorithm.
2930

3031
```xml
3132
<?xml version="1.0" encoding="utf-8" ?>
@@ -38,20 +39,21 @@ Description of the OspSystemStructure elements and their attributes are shown be
3839
<Simulators> ... <Simulators>
3940
<Functions> ... </Functions>
4041
<Connections> ... </Connections>
42+
<EccoConfiguration> ... </EccoConfiguration>
4143
</OspSystemStructure>
4244
```
4345

4446
## \<Simulator>
4547
Each running simulator must be assigned to a model(fmu). One FMU can be used by several simulators given different names.
4648
`<Simulator>` may contain sub-element `<InitialValues>`. `<InitialValues>` is optional when initial values of one or multiple variables in the simulator needs to be defined.
4749

48-
| attribute | Description |
50+
| Attribute | Description |
4951
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
50-
| `name` | Define an unique name for each simulator. |
52+
| `name` | Defines an unique name for each simulator. |
5153
| `source` | Source of the simulator, example below shows three different options to specify the path to a simulator.|
5254
| `stepSize` | Simulation step size for this individual simulator, aka. micro time step size.|
5355

54-
| sub-element | attribute | Description |
56+
| Sub-element | Attribute | Description |
5557
| :--------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
5658
| <*InitialValues*> | `variable` | Contains sub-element <*InitialValue*> defying all initial values of variables in need. Attribute `variable` is a string that refers to a variable in the simulator.|
5759
| <*InitialValue*> | `value` | Contains sub-element specifying the variable type which can be `<Real>`, `<Integer>`, `<Boolean>`, or `<String>`. Attribute `value` gives the initial value of the variable.|
@@ -78,7 +80,7 @@ Each running simulator must be assigned to a model(fmu). One FMU can be used by
7880
`Functions` are provided to handle manipulations of variables outside individual FMUs, for example, arithmetical operation.
7981
This is especially important when different models are provided by different vendors.
8082

81-
| Function | attribute |Description |
83+
| Function | Attribute |Description |
8284
| :--------------- | :----------------------------------| :----------------------------------------------------------------------------------------------------- |
8385
| *LinearTransformation* | `offset`| The linear transformation function is the operation that preserves the operations of addition and scalar multiplication, with attribute `offset` being the additional part.|
8486
| | `factor`| `factor` is the multiplication factor of the linear transformation function.|
@@ -98,7 +100,7 @@ This is especially important when different models are provided by different ven
98100
## \<Connection>
99101
As defined in OSP-IS, `connections` are configured through variables and variableGroups. It is highly recommended to follow the specification for its interfaces when exporting a model for connections.
100102

101-
| sub-element | attribute |Description |
103+
| Sub-element | Attribute |Description |
102104
| :--------------- | :----------------------------------| :----------------------------------------------------------------------------------------------------- |
103105
| <*VariableConnection*> | `simulator`; `name`| Contains sub-elements `<Variable>` with attributes specifying the `simulator` of which the variable belongs to and name of the variable.|
104106
| <*SignalConnection*> |`simulator`; `name`| Contains sub-elements `<Variable>` with attributes specifying the `simulator` of which the variable belongs to and `name` of the variable.|
@@ -130,6 +132,26 @@ As defined in OSP-IS, `connections` are configured through variables and variabl
130132
</SignalGroupConnection>
131133
</Connections>
132134
```
135+
## \<EccoConfiguration>
136+
`EccoConfiguration` is an *optional* element that shall be included if the `Algorithm` is chosen as `ecco`. This element contains a list of configuration options specific to the ECCO algorithm. Sensible default values to start with are also provided.
137+
138+
| sub-element | Default value |Description |
139+
| :--------------- | :----------------------------------| :----------------------------------------------------------------------------------------------------- |
140+
| <*SafetyFactor*> | 0.99 | A tuning factor to account for the fact that the error terms in general cannot be exactly compensated for. |
141+
| <*StepSize*> | 0.01 | The step size the algorithms starts with, effectively it's initial value. |
142+
| <*MinimumStepSize*> | 0.1 | The maximum step size the step size controller is allowed to set. | |
143+
| <*MaximumStepSize*> | 1e-4 | The minimum step size the step size controller is allowed to set. |
144+
| <*MinimumChangeRate*> | 0.2 | Multiplicative factor expressing the minimum rate of change of the step size for each iteration. |
145+
| <*MaximumChangeRate*> | 1.5 | Multiplicative factor expressing the maximum rate of change of the step size for each iteration. |
146+
| <*ProportionalGain*> | 0.2 | The proportional gain of the underlying PI-controller. |
147+
| <*IntegralGain*> | 0.15 | The integral gain of the underlying PI-controller. |
148+
| <*RelativeTolerance*> | 1e-6 | Error tolerance for the relative error. |
149+
| <*AbsoluteTolerance*> | 1e-6 | Error tolerance for the absolute error. |
150+
151+
152+
153+
154+
133155

134156
Alternatively, co-simulation configuration using the [SSP standard](https://ssp-standard.org/){:target="_blank"} is also supported. The SSP standard is one of the standardization projects of the FMI standard.
135157
The normative XML Schema 1.0 schema for the MAP SSP can be found [here](https://github.com/open-simulation-platform/cse-core/tree/master/test/data/ssp/SSP10){:target="_blank"}.

0 commit comments

Comments
 (0)