## On this page

  

 

 # Simulation Configuration 

 Last update: 16.07.2025 

The Simulation Framework command-line interface (`simfwk_cli`) serves as the primary entry point for executing a simulation loop using the Simulation Framework.

To align with AVx Architecture 2.0, `simfwk_cli` now requires a single mandatory simulation configuration file in JSON format. This file is referred to as the "solver setting configuration" throughout this documentation and represents the simulation configuration file.

To perform a quick test with the default solver setting configuration, use the following command:

cd simulation_framework/bin

./simfwk_cli -s solver_setting_configuration.json



As shown above, the minimum input required to run the simulation is a single configuration file. This configuration file is defined in JSON format and contains two mandatory fields.

### <a class="anchor" id="autotoc_md1"></a>simulation\_parameters

"simulation_parameters": {

 "input_open_scenario": "../data/test_scenario_alks_4.1.1_modified_4s.xosc",

 "input_driver_input": "../data/driver_input_default.json",

 "input_user_settings": "../data/UserSettings.ini",

 "output_directory": "/tmp/simfwk-out",

 "enable_mcap_generation": true,

 "job_id": "simulation_framework"

},



Mandatory Parameters:

- `input_open_scenario`: Specifies the file containing the autonomy simulation scenario.
- `input_driver_input`: Defines the file for driver's input data.
- `input_user_settings`: Provides the file containing user-specific simulation settings.
- `output_directory`: Specifies the directory where simulation outputs will be saved.

Note: If relative paths are used for files or the output directory, they must be relative to the `simfwk_cli` binary, located in the `bin` folder.

### <a class="anchor" id="autotoc_md2"></a>simulation\_scheduling

This section is specifically designed for setting up simulation scheduling. It allows users to define the Activities and configure their behavior during simulations. Below is an example of `simulation_scheduling`.

For a detailed explanation, please refer to the dedicated chapter: [Simulation Scheduling](md_documentation_markdown_simulation_scheduling.xhtml).

"simulation_scheduling": {

 "sim_instance_name": "gt_gen_with_driver_and_kpi_logger",

 "activities": [

 {

 "name": "groundtruth_generator_activity",

 "is_primary_activity": true,

 "topics_cycling_info": [

 {

 "topic_id": "__all__",

 "topic_cycle_time_in_ms": 200

 }

 ],

 "type": "built-in"

 },

 {

 "name": "dummy_tpm_activity",

 "depends_on": [

 "groundtruth_generator_activity"

 ],

 "type": "built-in"

 },

 {

 "name": "dummy_driver_activity",

 "depends_on": [

 "groundtruth_generator_activity"

 ],

 "type": "built-in"

 },

 {

 "name": "kpi_evaluator_activity",

 "depends_on": [

 "dummy_driver_activity"

 ],

 "type": "built-in"

 },

 {

 "name": "kpi_logger_activity",

 "depends_on": [

 "kpi_evaluator_activity"

 ],

 "type": "built-in"

 },

 {

 "name": "mcap_writer_activity",

 "depends_on": [

 "groundtruth_generator_activity"

 ],

 "type": "built-in"

 }

 ]

}



### <a class="anchor" id="autotoc_md3"></a>Running Simulation Framework using the CLI executable

Different arguments can be passed as options to configure the simulation:

usage:

 &lt;executable&gt; [&lt;Simulation input files given in pattern 'name:path'&gt; ... ] options

 

where options are:

 -?, -h, --help display usage information

 -v, --version Prints application version information

 -s, --simulation-config &lt;simulation Mandatory argument to specify the 

 setup/configuration file&gt; parameters of [autonomy](namespaceautonomy.xhtml) simulation

 configurationn and parameters

 -c, --control-mode &lt;If using CLI Optional argument to specify if

 controller for simfwk&gt; the [cli](namespacecli.xhtml) client should be enabled

 -g, --[cli](namespacecli.xhtml)-grpc-channel &lt;[cli](namespacecli.xhtml) controller Optional argument to specify the

 grpc channel's IP adress&gt; cli server/controller grpc

 channel's IP adress

 -t, --timeout &lt;Timeout for simfwk Optional integer argument to set

 scheduler events in milliseconds&gt; the scheduling event timeout in

 milliseconds

 -f, --[time](namespacetime.xhtml)-scaling-factor &lt;Time Optional float argument to set

 Scaling Factor&gt; the speed at which the simulation

 runs relative to real-[time](namespacetime.xhtml).

 Possible values:

 1.0: Real-[time](namespacetime.xhtml).

 &lt; 1.0: Slower than real-[time](namespacetime.xhtml).

 &gt; 1.0: Faster than real-[time](namespacetime.xhtml).

 -1.0: (default) As fast as

 system performance and resources

 allow.

 Entering a negative value

 requires an "=". E.g., `-f=-1.0`.

 All values &lt;= 0 will result in

 the default behaviour.



where `-s <simulation_configuration.json>` is only mandatory argument. If extra inputs file are required by customized autonomy simulation, they can be given through cli. Thus, the file path can be retrieved by using getter API of any activity. More explaination about getter API in activity can be found [here](md_documentation_markdown_customized_activity.xhtml).

E.g. if you want a file named "file\_foo" with path "path/to/file\_foo.txt", following command can be given using cli:

./simfwk_cli file_foo:path/to/file_foo.txt -s your_solver_settings_configuration.json



If more files are required by your simulation, the same pattern should be followed:

./simfwk_cli file_foo1:path/to/file_foo1.txt file_foo2:path/to/file_foo2.txt -s your_solver_settings_configuration.json



### <a class="anchor" id="autotoc_md4"></a>Batch Mode Usage

If you want to execute the scenario and simply have the output, `simfwk_cli` can be executed using the command below:

./simfwk_cli -s your_solver_settings_configuration.json



### <a class="anchor" id="autotoc_md5"></a>Interactive Usage

Additionally, you can trigger the cli controller mode by option `-c true`

./simfwk_cli -s your_solver_settings_configuration.json -c true



this enables the user control of simulation framework via `cli_controller`, instead of just running through of your scenario. With the `cli controller` , the user can send commands like `run` , `pause` , `resume` , `restart` , `step` or `kill` , to interact with simulation.

### <a class="anchor" id="autotoc_md6"></a>Interact with simulation using the cli\_controller

When the `-c true` is applied, a server will be created for listening to the user command. To control the simulation, following command are available:

./cli_controller &lt;user command&gt;



Supported commands:

[run] : trigger the execution the simulation, it will continue running til simulation is done

[step] : step the simulation for given count. e.g. "step 5" for stepping simulation for 5 [time](namespacetime.xhtml) default for 1 [time](namespacetime.xhtml)

[pause] : pause the simulation and waiting for user command

[resume] : resume the simulation

[kill] : kill the program

[restart] : restart simulation from initial state and wait for user command

[help] : display usage information



### <a class="anchor" id="autotoc_md7"></a>Example

- First start your simulation and enable user control:

./simfwk_cli -s your_solver_settings_configuration.json -c true



- Then you will see following message in the console, if the default controller port is not changed:

[LogDebug][Cli] simulation with cli controller is enabled! Trying to start simulation with setup and connect with simfwk core server at IP address 0.0.0.0:50051 with client at IP address localhost:50051

SimfwkCliServer started: listening on IP 0.0.0.0:50051



- Open a new terminal, and try trigger the simulation:

./cli_controller run



- After a successful execution, the console shows `Cli Controller Executation Status OK!` . Then you can see the simulation started.

[LogDebug][CliCommandProcessor] received action from cli controller 

[LogInfo][SimRunner] Starting simulation.



**Note: In this control mode, the simulation process `simfwk_cli` will not terminate unless you send `kill` from the cli\_controller or manually send `ctrl+c`**.