Install Simulation Framework

Make sure the simfwk debian package simfwk-<version>-linux-x64.deb is at same directory of installation script install.sh .

Then simply execute installation script in bash command, super user credential is required during installation for pulling other run-time dependencies fron artifacts.

A folder named simulation_framework will be unpacked to the current directory, containing subdirectories example , docs , bin , include and lib . Doxygen will be generated during installation, to see it you can open docs/doxygen/html/index.xhtml in your web browser.

Environment dependencies

If you install Simulation Framework locally in ubuntu 20.04 machine or inside ubuntu 20.04 VM , all build and runtime dependencies will be installed during the installation script above. Alternatively, a Dockerfile containing all required dependencies is also provided, if you need to build or test in virtual environment for cloud deployment.

Build dependencies

In Simulation Framework deployment, a bazel WORKSPACE is provided as default build system. You can run example or build your own activity application based on that. However, Simulation Framework is not restricted to any build system.

System requirement

Depending on how complex your simulation is, you might need different recommended CPU/memory resources. For execution of the reference simulation, following requirements shall be considered:

Run example

Within the deployment, an example code is provided to show how a customized activity can be created and used into simulation with simfwk_cli . To verify if installation is successful and Simulation Framework is running in your develop environment, go to example/my_activity folder and execute the run.sh script. Before running the example, please make sure you have valid license setup and be able to connect with Ansys License Manager. More hint please see setup License

This script compiles automatically the example my_activity and triggers the simulation using my_activity by means of command line tool provided by Simulation Framework. It provides a basic example using bazel to show how Simulation Framework is used as lib. If the test works, you should see some simulation logs and then the evaluated min_ttc result in json format prints in console.

Reference simulation

The reference simulation (RefSim) stands as an exemplary application constructed with the Simulation Framework library, offering four predefined activities as references. Users have the flexibility to use these activities to initiate the default simulation application or seamlessly integrate them into a customized simulation. These activities, implemented in the core, can be selected as 'built-in' activities based on their specified 'type' in the configuration, contributing to the adaptability of the simulation at any given point. Details about config please refer to schedule your simulation

The table above illustrates the names of reference activities in the Simulation Framework, their configuration name strings, the topics they publish and subscribe to, and the main interface(s) they require.

The reference activities are provided inside the Simulation Framework binary, and the source code for them is not provided. An exception is the source code for one KPI implementation used by the KPI Evaluator. This implementation provides only one KPI, min_ttc (the minimum time to collision during the simulation), based on basic mathematical calculations, and it is included inside the deployment. Please verify the mathematical logic and use the result of min_ttc at your own risk.

GroundTruth generator (GT Gen)​

GT Gen serves as the default world simulator in the Simulation Framework and provides ground truth information for the entire simulation based on input OpenScenario and OpenDRIVE files. Depending on the configuration, it can operate in two different modes: ExternalMovement and ExternalMovement . ExternalMovement is an open-loop mode where GroundTruth Generator provides simulation ground truth based on a predefined trajectory in the open scenario and map, while ExternalMovement can receive the TrafficUpdate from an external driver and follow its movement commands to realize a closed-loop behavior.

Reference TPM model

The reference traffic participant model uses the ground truth information generated by GT Gen to control the host vehicle's movement based on OpenScenario controller logic by publishing TrafficUpdateTopic. This reference model is implemented as standalone activity using dog library.

Reference KPI evaluator​

The KPI evaluator calculates the min_ttc (the minimum time to collision during the simulation) based on ground truth as a reference KPI. It is achieved by calculating the time to collision in every simulation frame and storing only the minimal value during the simulation. If the outputted min_ttc is zero, it means a critical collision occurred in the simulation.

Time to collision (TTC) calculation algorithm

The TimeToCollisionCalculator class is used to calculate the time of Ego to collision with other traffic cars based on OSI GroundTruth. The implementation of the TTC calculation logic can be found in the following exposed files: include/evaluator/ttc_calculator/ttc_calculator.h and include/evaluator/ttc_calculator/ttc_calculator.cpp .

1. find out the Ego vehicle index within osi3::MovingObject list from osi3::GroundTruth and compute the BoundingBox
2. find out the nearest with possible colliding traffic vehicle index within osi3::MovingObject list from osi3::GroundTruth and compute the BoundingBox .
3. calculate the distance between ego and nearest possible colliding traffic vehicle, with consideraion of dimensions of ego and traffic car with approximation using half length from both.
4. check if two bounding boxes are overlapping, if yes return ttc value to 0 (zero) meaning collision happens; if no, go to No.5.
5. calculate current TTC based on velocity difference (2d velocity vector Norm difference) and distance. If velocity difference has a negative value, which means the nearest traffic car is driving faster than ego, ttc value will be returned as std::chrono::milliseconds::max()

The reference KPI Evaluator serves only as a reference KPI and cannot be extended/adapted without applying a patch to the simulation library. To use your own and add more KPIs to the simulation, please refer to the customized KPI chapter.

KPI logger​

The KPI logger captures the KPI data stored in the KpiLoggerTopic and stores them in JSON output for analyzing the system under test. One KPI could consist of the following fields:

As default, you will have the min_ttc after the simulation is successfully executed, e.g.

To add more KPIs to the simulation, please refer to the customized KPI chapter.

How to safely utilize the KPI logger

As outlined above, the KPI logger subscribes to KPI messages and records them in a JSON file. To effectively use the KPI logger, follow these steps:

1. Set dependency on KPI evaluator In your simulation configuration, ensure that you set a dependency on the KPI evaluator. This KPI evaluator can be sourced from the reference simulation or a customized one. Once this dependency is established, the logger will capture all KPI messages.
2. Caution regarding dependency It is crucial to note that the KPI logger can operate independently, allowing you to run simulations without the KPI evaluator dependency. However, be mindful that doing so may result in incomplete logging. Running simulations using logger and evaluator in different frequencies may lead to the omission of certain KPI values. Exercise caution, as this could mean overlooking critical KPI information during the simulation.
3. Understanding potential hazards When running the simulation without the specified dependency, be aware that not all KPI values will be logged, if logger and evaluator run in different frequencies. Hence, some KPI samples might be neglected. This introduces the hazard of missing essential KPI data, requiring a thorough understanding of the circumstances and the potential impact on your evaluation.

By following these guidelines, you can ensure the safe and effective use of the KPI logger in your simulation. By verifying the field latest_timestamp_in_ms into your KPI analysis, you can enhance the reliability of your simulation results and foster a more robust safety protocol for your application.

Simulation domain ID

The connection between standalone activities, built-in activities and simfwk core is achieved through RTIDDS communication using the domain ID (in type of uint16). By default, the binaries in the deployment package use the same domain 147 as default and can communicate with each other.

For the use case where you want to customized the domain ID, i.e. to isolate one standalone activity from simfwk_cli or want to run two simfwk_cli executables in the same machine. for instance, you can adapt the simfwk_cli domain ID through environment variable:

or run one customized activity in different domain rather than default 147

Note that please be careful to use this feature because two same processes in the same domain might interfere with each other and results in unexpected behavior, e.g. two simfwk_cli run in same domain will received events from other and simulation ends up with wrong scheduling or abortion. Please make sure the processes are isolated correctly if you use this feature and no unexpected hidden process running in background within the same domain, while testing your customized activity.

Customization

The Simulation Framework not only offers users the capability to extend or customize the default simulation setup but also empowers them to bring their own logic into specific activities and seamlessly communicate with other activities through the introduction of new topics. Additionally, users can incorporate new Key Performance Indicators (KPIs), which will be automatically logged by the Simulation Framework.

For detailed instructions on implementing and using customized activities, refer to how to implement and use customized Activity. Furthermore, guidance on adding and utilizing customized KPIs can be found in how to add and use customized KPIs.