.. | |
******************************************************************************* | |
Copyright (c) 2021 in-tech GmbH | |
This program and the accompanying materials are made available under the | |
terms of the Eclipse Public License 2.0 which is available at | |
http://www.eclipse.org/legal/epl-2.0. | |
SPDX-License-Identifier: EPL-2.0 | |
******************************************************************************* | |
.. _simulationconfig: | |
SimulationConfig | |
================ | |
.. todo: Write a nicer introduction for the simulationconfig, similar to "Overview" section in scenery | |
This file describes the user configurable parameters of an experiment. | |
Several parameters depend on probabilities. | |
Each invocation then rolls for said probabilities. | |
All probabilities need to add up to 1.0. | |
The simulationConfig.xml consists of the following sections: | |
* :ref:`simulationconfig_profilescatalog` | |
* :ref:`simulationconfig_experiment` | |
* :ref:`simulationconfig_scenario` | |
* :ref:`simulationconfig_environment` | |
* :ref:`simulationconfig_observations` | |
* :ref:`simulationconfig_spawners` | |
.. _simulationconfig_profilescatalog: | |
ProfilesCatalog | |
--------------- | |
Specifies the :ref:`profilescatalog` for the experiment. | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:start-at: <ProfilesCatalog> | |
:end-at: </ProfilesCatalog> | |
.. _simulationconfig_experiment: | |
Experiment | |
---------- | |
Specifies the general experiment setup, not specific to a single invocation. | |
.. table:: | |
:class: tight-table | |
===================== ================================================== ========= | |
Tag Description Mandatory | |
===================== ================================================== ========= | |
ExperimentId Id of the experiment yes | |
NumberOfInvocations Number of invocation in the experiment. | |
For each invocation probabilities are rerolled. yes | |
RandomSeed Random seed for the entire experiment. | |
Must be within the bounds of an unsigned integer. yes | |
Libraries Name of the core module Libraries to use. | |
If not specified the default name is assumed. yes | |
===================== ================================================== ========= | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:start-at: <Experiment> | |
:end-at: </Experiment> | |
.. _simulationconfig_scenario: | |
Scenario | |
-------- | |
This section contains information about the scenario setup for the experiment. This information does not change between invocations. | |
.. table:: | |
:class: tight-table | |
================ ========================= ========= | |
Tag Description Mandatory | |
================ ========================= ========= | |
OpenScenarioFile Name of the scenario file yes | |
================ ========================= ========= | |
**Example** | |
This experiment uses the "HighwayScenario.xosc" scenario file. | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:start-at: <Scenario> | |
:end-at: </Scenario> | |
.. _simulationconfig_environment: | |
Environment | |
----------- | |
This section contains information about the world and the general environment inside the simulation. Every invocation re-rolls the environment probabilities. | |
All probabilities need to add up to 1.0. | |
.. table:: | |
:class: tight-table | |
=================== ============================================================================================== ========= | |
Tag Description Mandatory | |
=================== ============================================================================================== ========= | |
TimeOfDay **Currently unused.** Time of day ranging from 1-24 [h]. 1+ entry | |
VisibilityDistance Defines how far a human driver can see [m]. 1+ entry | |
Friction Friction on the road. Used by DynamicsRegularDriving and LimiterAccelerationVehicleComponents. 1+ entry | |
Weather **Currently unused.** Weather as string 1+ entry | |
TrafficRules Defines which set of TrafficRules to use from the ProfilesCatalog yes | |
=================== ============================================================================================== ========= | |
**Example** | |
Every invocation has the time set to 15:00. | |
In 70% of all invocation drivers can see 125 meter and for the other 30% of invocations the drivers can see 250 meter. | |
Every invocation has a friction of 0.3. | |
Every invocation has sunny weather. | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:start-at: <Environment> | |
:end-at: </Environment> | |
.. _simulationconfig_observations: | |
Observations | |
------------ | |
In this section all observation libraries are defined with their parameters. | |
A specific library is loaded by adding an entry to the `Observations` tag: | |
.. code-block:: xml | |
<Observations> | |
<!-- first observer --> | |
<Observation> | |
<Library>THE_OBSERVATION_LIBRARY</Library> | |
<!-- observer specific parameter --> | |
<Parameters> | |
<String Key="THE_KEY" Value="THE_VALUE"/> | |
<Bool Key="ANOTHER_KEY" Value="false"/> | |
... | |
</Parameters> | |
</Observation> | |
<!-- second observer --> | |
<Observation> | |
... | |
</Observation> | |
</Observations> | |
Here, the ``Library`` tag contains the name of the library, and ``Parameters`` contain an optional list of key/value pairs, specific for each observer. | |
Please refer to the documentation of the individual observers for available parameters: | |
.. toctree:: | |
:glob: | |
:maxdepth: 1 | |
../outputs/* | |
.. _simulationconfig_spawners: | |
Spawners | |
-------- | |
In this section the spawners are defined with their Profile (defined in the ProfilesCatalog). | |
The same library can be loaded multiple times with different profiles. | |
A spawner is either of type "PreRun", meaning it is triggered only once at the start of the simulation, or "Runtime", meaning it is triggered in every timestep. | |
If different spawners are to be triggered at the same time the spawner with the highest priority is triggered first. | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:start-at: <Spawners> | |
:end-at: </Spawners> | |
Full Example | |
------------ | |
.. literalinclude:: /../../../repo/sim/contrib/examples/Common/simulationConfig.xml | |
:language: xml | |
:caption: simulationConfig.xml | |
:linenos: |