..
  *******************************************************************************
  Copyright (c) 2021 ITK Engineering GmbH
                2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)

  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
  *******************************************************************************

.. _user_guide_overview:

Overview
========

openPASS is an open-source software, which is continuously being improved by stakeholders of the openPASS working group: |op_oss| (https://openpass.eclipse.org/)
openPASS can simulate traffic situations with the goal of predicting and evaluating the safety of driver assistance systems, more specifically ADAS (Advanced Driving Assistance Systems) or AD functions. Its main use-cases are PCM-(PreCrash Matrix), and scenario-based simulations.
Let’s have a look at what that means:

.. image:: sim_user_guide/_static/images/crash-scenario.png
  :width: 600
  :align: center

1. PCM Simulations: “Crash re-simulations”

  * PCM of GIDAS: PreCrash Matrix with trajectories from the database of the German In-Depth Accident Study
  * Re-simulate real crashes from the past, but with cars having ADAS or AD functions and assess if the tested technology would have improved the safety.

2. (Traffic-)scenario based simulations

  * This is the most common use-case for openPASS.
  * Enables simulation of whole traffic scenarios. That includes stochastic variation of those scenarios, intervention through detection of events and triggered actions and much more.
  * To get a better understanding about how these simulations are performed, please look at the scenario-based simulation tutorial.

For beginners, this presentation gives more illustrations and background about openPASS: https://openpass.eclipse.org/target_objectives/openPASS_at_a_glance.pdf

Getting Started
---------------

.. _OpenSCENARIO: https://www.asam.net/standards/detail/openscenario/

This chapter provides insights on openPASS and how to work with the simulation.
The following step-by-step guides are included to guide you through your first simulations with openPASS:

   * Scenario-based Simulation: traffic simulation based on `OpenSCENARIO`_ description
   * PCM Simulation: crash re-simulation based on GIDAS record

In particular, it is presented how to go through the required steps until a simulation can be run successfully.  
To enhance the guiding, there are going to be examples in every section. 
It is important to mention that openPASS is still in progress and e. g. some plugins and options have not been fully implemented yet.

Intended Audience
-----------------

This manual serves as an entry point for users who have an operational simulator at hand (see :ref:`sim_install_guide`) and want to carry out (first) experiments at the invocation level (*GUI-less mode*).
In this sense, it primarily tackles how input-sets are composed, their interdependencies and, finally, the generated outputs.

.. figure:: ./sim_user_guide/_static/draw.io/workflow.png

   |op| Workflow

This image shows the *GUI-less* workflow, starting with the input-set, bundled together in a folder typically named ``configs``.
The ``core``, executed manually by the experimenter, processes these configs and generates an (configurable) output-set typically placed in a folder named ``results``.
Thereby, the **Simulation Output** is again a set of files.


Workflow
--------

A typical workflow can be:

   1. Configure systems and agents
   2. Configure the simulation
   3. Run the simulation
   4. Evaluate the simulation results
   5. Close the loop by continuing with your next simulation

.. _primer:

Primer
------

In the following the input and output sets are described with respect to the intended audience.
For detailed information please refer to the "in-depth" documentation of the individual files.

Inputs
^^^^^^

The input is focused around the files presented in the following chart, which depticts the information flow between the files: 

.. figure:: ./sim_user_guide/_static/draw.io/overview-configs.png

In the following list, those files are discussed further and listed with decreasing importance for the current audience.

- **Scenario**
  
  This file describes the overall situation in terms of the **ASAM OpenSCENARIO 1.0** standard.
  This includes placement of cars, the story (what happens when), how long the simulation will run.
  
  On top it contains links to additionally needed files, where the following might need modification with respect to the current audience:

  - **Scenery** (``*.xosc``)
  
    The **scenery** file describes the world in which the experiment runs.
    As such, it contains the description of the road network and any static object, such as a highway, a parking lot, or traffic signs and obstacles. 
    It follows the **ASAM OpenDRIVE 1.6** standard.

  - **ProfilesCatalog** (``*.xml``)
  
   This catalog is the probabilistic heart of the simulation as it describes the composition of various simulation components and entities, using both, deterministic and stochastic definitions.
   The ProfilesCatalog defines which of the available components are actually existing in the simulation:
   That includes vehicles (from the ``VehicleModelCatalog.xosc``), pedestrians (from the ``PedestrianModelCatalog.xosc``), but also components like sensors, driver assistance systems or driver models being used.
   A Profile provides, for example, information about which components are generally available in an agent (vehicle with driver) and how likely it is that they are actually existent.
   Such components could be ADAS sensors, which means that they are parametrized in this section as well.
   On the implementation level, a Profile is a set of parameters which will be provided to the instantiated components of an agent or to a simulation core component, e.g. Spawner.
   For every parameterizable component an associated ProfileGroup contains one or more Profiles, from which one will be selected based on the given probabilities.

   .. note:: As **OpenSCENARIO** does not support probabilities (yet), this file is not conform to the standard.

  - **VehicleCatalog** and **PedestrianCatalog**: (``*.xosc``)

    These catalogs, also based on **OpenSCENARIO**, describes the physical parameters of available vehicles or pedestrians, respectively.

    .. note:: 
    
       Historically, the referenced files carry the word *Model*  in the filename: ``VehicleModelsCatalog.xosc`` and ``PedestrianModelsCatalog.xosc``

- **SimulationConfig** (``simulationConfig.xml``)

  This is the entry point for the simulation, containing the setup of the core, such as active observers, reference to the scenario, the initial random seed, and the number or invocations.

  .. note::
     
     This file is normally of limited interest.
     Yet, some variations, such as *environmental conditions* are historically placed in here and not in the scenario description. 
     It is therefore recommended to study the contents of this file.

- **SystemConfigBlueprint** (``systemConfigBlueprint.xml``)

  This file is contains a superset of all possible *components* and their valid connections. 
  Such components can be lateral and longitudinal controllers, assistance systems, prioritizers, driver models, and so on.
  Depending on the configured profiles and their probabilities, the core picks a subset of components to create one complete *system*.

  .. warning:: This file should not be changed without the proper (developer) expertise.

  .. note:: 
  
     Instead of using an overall blueprint, concrete (static) systems can be specified using the same format. 
     These files are simply referred to as ``SystemConfig`` files.

Some components need their own input files (e.g. a configuration).
It is convention to put these files also into the ``configs`` folder, which is internally provided as path to the components.
This helps to keep experiments separated.

Outputs
^^^^^^^

Outputs are generated by individual observers, configured by the **SimulationConfig**, and collected within the folder `results`.
This section describes the output files by the :ref:`observation_log`, as configured by the provided example configurations.

Please refer to the documentation of the individual observers and files for more details.

- **Simulation Output** (``simulationOutput.xml``)

  This file acts as central entry point for further evaluation, such as the visualization.
  It contains central information about all executed invocations within an experiment, such as the executed scenario and the run results, which can be seen as current values from the random sampling of the given probabilities.
  As such, each run result contains, a list of participating moving entities (also referred to as agents), events related to the entities, such as collisions or activation of ADAS's, and a reference to the *cyclics file*.

  .. note:: This file **does not** contain information about the actual position of agents.

- **Cyclic Output** (``Cyclics_Run_###.csv``)

  This file contains the ground truth information for each agent at each time step.
  For each invocation, a new file is generated (starting with ``Cyclics_Run_000.csv`` and referenced in the according run results in the ``simulationOutput.xml``.

  .. note:: This file **does not** contain information about the interaction between agents.

.. note:: 

   The core generates a file called ``opSimulation.log`` at the execution path, which logs errors and warnings.
   If the simulation behaves strange or did not produce any output, check this file.

