Install Simulation Framework
Last update: 16.07.2025Make sure the simfwk debian package SimulationFramework_<version>_amd64.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. Doxygen will be generated during installation, to see it you can open documentation/doxygen/html/index.xhtml in your web browser.
You can verify the installtion by running simfwk_cli with default setup, please make sure you have valid license setup and be able to connect with Ansys License Manager.
You will see the execution log in the console. After the simulation completes, the output files will be stored under the default path /tmp/simfwk-out, which is customizable in the simulation configuration file ./solver_setting_configuration.json.
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 | https://github.com/bazelbuild/bazelisk/releases/download/v1.5.0/bazelisk-linux-amd64 |
| 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, 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 to use APIs of Simulation Framework and how to do customization. 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.
Built-in and default standalone Activities
The autonomy simfwk_cli 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 simfwk-autonomy, 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.
| Activity Description | Type | Name in Simulation Config | Publish Topic(s) | Subscribe Topic(s) |
|---|---|---|---|---|
| GroundTruth Generator | built-in | "groundtruth_generator_activity" | SensorViewTopic | TrafficUpdateTopic |
| Mcap Trace Writer | built-in | "mcap_writer_activity" | SensorViewTopic | N/A |
| GroundTruth KPI Evaluator | built-in | "kpi_evaluator_activity" | KpiLoggerTopic | SensorViewTopic |
| Default KPI Logger | built-in | "kpi_logger_activity" | N/A | KpiLoggerTopic |
| Dummy TPM Model | built-in | "dummy_tpm_activity" | TrafficUpdateTopic | SensorViewTopic |
| Dummy Driver Model | built-in | "dummy_driver_activity" | DriverInputTopic | SensorViewTopic |
| Standalone GroundTruth Generator | standalone | "standalone_gt_gen_activity" | SensorViewTopic | TrafficUpdateTopic |
| Standalone Foxglove Connector | standalone | "standalone_foxglove_activity" | N/A | SensorViewTopic |
The table above illustrates the names of default activities provided in the Simulation Framework Autonomy package, their type and configuration name strings, the topics they publish and subscribe to.
These built-in activities are provided within the Simulation Framework Autonomy binary, and their source code is not included. The exception is the source code for the KPI implementation used by the KPI Evaluator. This implementation provides three KPIs: min_ttc, predictive_min_ttc, and driven_dist. They are based on a simple generic mathematical model and are included in the package under ./include/autonomy/evaluator. Please verify the logic and use the default KPI Evaluator at your own risk.
GroundTruth Generator (GT Gen)
GT Gen serves as the default world simulator in Autonomy 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 modes: ExternalMovement and ExternalMovement.
- ExternalMovement: This open-loop mode provides simulation ground truth based on a predefined trajectory in the open scenario and map.
- ExternalMovement (Closed-loop): This mode receives
TrafficUpdatefrom an external driver and follows its movement commands for closed-loop behavior.
Mcap Trace Writer
This activity writes the GroundTruth (OSI) data into a trace file in MCAP format. After the simulation finishes successfully, the trace file simout_trace.mcap will be available in the specified output directory.
Dummy TPM Model
The Dummy Traffic Participant (TPM) model uses the ground truth information generated by GT Gen to control the host vehicle's movement. It relies on a simple mathematical model to publish TrafficUpdateTopic.
Dummy Driver Model
The Dummy Driver Model mimics driver behavior based on GroundTruth and publishes a driver input topic that contains log data (in KPI format) of the driver’s behavior.
Standalone Foxglove Connector
The Standalone Foxglove Connector acts as a message provider via a Foxglove socket, enabling visualization using the Foxglove plugin to verify GroundTruth (OSI) data. This is a separate executable that uses the simfwk-core standalone activity service and must be run before starting the simulation with simfwk_cli.
Standalone GroundTruth Generator
The Standalone GroundTruth Generator functions similarly to the built-in GroundTruth Generator. The difference is that it is a separate executable using the simfwk-core standalone activity service and must be run before starting the simulation with simfwk_cli.
GroundTruth KPI Evaluator
The KPI Evaluator calculates three KPIs based on GroundTruth:
- **
min_ttc**: The minimum time to collision during the simulation. If the value is zero, it indicates a critical collision occurred during the simulation. - **
predictive_min_ttc**: The minimum time to collision during the simulation, considering the predictive movement of vehicles. If the value is zero, it indicates a critical collision occurred during the simulation. - **
driven_dist**: The total distance driven by the ego vehicle during the simulation.
To add more KPIs to the simulation, please refer to the customized KPI chapter.
Default KPI logger
The KPI logger captures the evaluated KPI data in KpiLoggerTopic, sent from KPI Evaluator, and stores them in JSON output for analyzing your simulation later. If you use the default GroundTruth KPI Evaluator, the final KPI file kpi_results.json could consist of the following fields:
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:
- 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.
- 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.
- 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.
Customization
The Simulation Framework Autonomy 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 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.
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.
