## On this page # Install Simulation Framework Last update: 16.07.2025 Make sure the simfwk debian package `simfwk--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. ./install.sh 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. Type Name Version Source Compiler GCC/G++ 11 add-apt-repository -y ppa:ubuntu-toolchain-r/test &&% apt-get install gcc-11 g++-11 Build System (default) BAZEL 5.1.1 Ubuntu (Focal 20.04) Package Build Essential latest apt-get install build-essential Ubuntu (Focal 20.04) Package software-properties-common latest apt-get install software-properties-common Ubuntu (Focal 20.04) Package Manual pages latest apt-get install manpages-dev Ubuntu (Focal 20.04) Package Cartographic projection library latest apt-get install proj-bin ### System requirement Depending on how complex your simulation is, you might need different recommended CPU/memory resources. For execution of the [reference simulation](#reference-simulation), following requirements shall be considered: Environment recommended. CPU recommended. Memory recommended. Disk Space Workstation or VM 2.5 GHz processor, 4 cores 8GB 30 GB k8s Cluster 300m 400Mi 30 GB ## 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](md_docs_markdown_setup_license.xhtml) cd example ./my_activity/run.sh This script compiles automatically the example `my_activity` and triggers the simulation using `my_activity` by means of [command line tool](md_docs_markdown_command_line_tool.xhtml) 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](md_docs_markdown_scheduling_configuration.xhtml) Activity Name Type Name in Config Pub Topics Sub Topics Core Interface GroundTruth Generator built-in "groundtruth\_generator\_activity" SensorViewTopic TrafficUpdateTopic `IWorldSimulator` TPM Model standalone "tpm\_standalone\_activity" TrafficUpdateTopic SensorViewTopic n/a KPI Evaluator​ built-in "kpi\_evaluator\_activity" KpiLoggerTopic SensorViewTopic `IKpi` , `IEvaluator` KPI Logger​ built-in "kpi\_logger\_activity" n/a KpiLoggerTopic `std::unique_ptr`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](md_docs_markdown_customized_kpi_evaluator.xhtml). ### 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: "name": { "datatype" : "", "latest_timestamp_in_ms":"", "unit" : "", "value" : "" } As default, you will have the `min_ttc` after the simulation is successfully executed, e.g. "min_ttc": { "datatype": "double", "latest_timestamp_in_ms":4000, "unit": "ms", "value": 24160.0 } To add more KPIs to the simulation, please refer to the [customized KPI chapter](md_docs_markdown_customized_kpi_evaluator.xhtml). ### 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](https://www.rti.com/products/dds-standard) 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: \# open new terminal and adapt the Domian ID in this console export SIMFWK_DDS_DOMAIN_ID=<other_uint16_number> \# then execute simfwk_cli, it will runs in different domain ./simfwk_cli -s <your_scenario.xosc> -o <your_output_path> -d <your_config_json_path> or run one customized activity in different domain rather than default `147` \# open new terminal and adapt the Domian ID in this console export SIMFWK_DDS_DOMAIN_ID=407 \# then execute simfwk_cli, it will runs in domain 407 ./your_customized_activity_executable 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](md_docs_markdown_customized_activity.xhtml). Furthermore, guidance on adding and utilizing customized KPIs can be found in [how to add and use customized KPIs](md_docs_markdown_customized_kpi_evaluator.xhtml).