Install Simulation Framework

For detailed instructions, refer to the installation guide.

Environment dependencies

If you install Simulation Framework locally in ubuntu 24.04 machine or inside ubuntu 24.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 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.

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.

Foxglove Activity

This activity supports visualization by starting a Foxglove websocket server on a default host and port. A Lichtblick Client(A Visualization Tool) can connect to the server and consume OSI groundtruth data via a streaming websocket in order to visualize. The default host and port used are localhost:8679. The host and port can be configured by the user by setting values as given in Enabling Visualization using Lichtblick section.

Enabling Visualization using Lichtblick

The user needs to add the below config setting json node as a child of simulation_scheduling in the solver_setting_configuration.json in order to enable visualization using Lichtblick.

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 InternalMovement.

• InternalMovement: 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 TrafficUpdate from 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. To enable creation of the trace file, user needs to add and enable the below field save_mcap as below in the config solver_setting_configuration.json.

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 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 Simulation Framework 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:

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.

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.

Troubleshooting

If simulation or setup faced critical error and can not proceed, Simulation Framework will terminate the simulation or throw exceptions with proper messages to indicate a solution or root causes.

Licensing error

Unset of ANSYSLMD_LICENSE_FILE

Connection with license server failed

Path error

Can not access simulation config

If one non-existing path to the scheduling config is given or you do not have read permission to this file, simulation cannot be started and raises following error:

Scheduling error

Wrong definition in config Any wrong definitions, e.g. missing mandatory field or wrongly defined parameter, name or dependency, exception will be thrown immediately. E.g. If no activity is assigned as is_primary_activity in scheduling config, simulation cannot be started and raises following error:

Failed connection to activity

In case one scheduling event was sent from scheduler server of Simulation Framework but an expected feedback is missing, simulation aborts immediately to ensure the deterministic behavior. This happens usually when running your application with standalone activity, where it loses the connection with main process or dead. In that case, you will see this kind of error like following:

Receiving scheduling event from unexpected source

In case one unexpected event was received by scheduler server, simulation aborts immediately by raising following error:

The root cause of this issue could be that the environment where your simulation applicaiont runs does not have enough resouces, e.g. the CPU was stressed or memory is not enough. Other possible reason is that you have another application process built with Simulation Framework running in the same simulation domain. Please refer to the documentation of Simulation domain ID section in lifecycle

Communication error

Multiple publisher for same Topic

In Simulation Framework, it is not allowed to have more than one publisher on one Topic. The identifier is the unique TopicId in type string. If you try to create publishers on same Topic, e.g. on "YourTopic", following error will be raised:

Used undefined topic

If you try to use undefined Topic, e.g. "UndefinedTopic", from topic registry (core/communication/topic_registry.h) or use one Topic in Activity without registering it in constructor, following error will be raised:

Missing Publisher/Subscriber for one Topic

To optimize simulation load, the system does not permit starting a simulation if an activity publishes a topic that lacks a subscriber. Before the simulation begins, the system checks for matching publishers and subscribers. A default timeout of 10 seconds is applied during this check. If no subscriber is found within this period, the system will throw an exception to indicate the failure.

and vice versa, if you missing publisher for one Topic:

Security consideration

By prioritizing these security measures, Simulation Framework aims to provide a secure environment for the user to RTI DDS communication as middleware and mitigate risks associated with third-party integrations.

Third-party integration security

• Conduct thorough security assessments of third-party components.
• Regularly review and update dependencies to mitigate vulnerabilities.
• Promptly address vulnerabilities in third-party dependencies.

RTI DDS as communication

• Access Control: Enforce access control policies to restrict which entities can publish or subscribe to specific topics within the specified DDS domain.
• Data Encryption: Implement robust encryption mechanisms to ensure the confidentiality of data transmitted over RTI DDS. Configure encryption settings to adhere to industry best practices and regulatory requirements.
• Authentication: Enforce strong authentication mechanisms to verify the identities of participants within the DDS network. Utilize authentication protocols supported by RTI DDS to prevent unauthorized access and ensure the integrity of the communication.

Additional documentation and user forums can be found on rti community.