How to Use the Simulator

🚀 Running the Simulator

The ACSL Physics Simulator is configured entirely through the YAML files in the config/ directory. In most cases, you do not need to recompile the simulator when changing simulation settings—simply modify the configuration files and restart the simulator.

config/
├── sim-config.yaml   # Simulation mode, UAV platform, debugging
├── phy-config.yaml   # Physics engine, solver, timestep, collisions
└── vis-config.yaml   # Visualization, rendering, camera options

The recommended workflow is

1. ⚙️ Configure the simulation mode (sim-config.yaml)
2. 🌍 Configure the physics engine (phy-config.yaml)
3. 🎮 Configure visualization (vis-config.yaml)
4. 🚀 Launch the simulator

---

⚙️ 1. Configure the Simulation Mode

Open

config/sim-config.yaml

This file determines

• 🛫 The simulation mode (MIL or SIL/HIL)
• 🚁 The UAV platform
• 🐞 Debugging and logging options

🛫 Model-in-the-Loop (MIL)

To run the simulator using the internal controller, set

mode:
  enable_flightstack_loop: false

Caution

HIL/SIL functionality is currently under development and is not yet fully available. Support will be added in a future simulator release. Refer to the Milestones section for updates.

---

✈️ Selecting the Vehicle Frame

For quadrotors

mode:
  enable_biplane_frame_data: false

For biplanes

mode:
  enable_biplane_frame_data: true

Note

This flag changes the frame used for controller computations. Enable it only for quad-biplane platforms.

---

🐞 Debugging Options

Example configuration

debug:
  terminal: true
  log_physics: true
  sim_debug_stop: false
  sim_stop_time: 23.0

Option	Description
terminal	Print chassis state information to the terminal.
log_physics	Log chassis and propeller states to disk.
sim_debug_stop	Automatically stop the simulation after a specified time.
sim_stop_time	Time (seconds) at which the simulation terminates.

For example, to automatically stop after 15 seconds

debug:
  sim_debug_stop: true
  sim_stop_time: 15.0

Note

Debugging options affect only the simulator. Controller-specific logging is configured separately inside the Flight Stack and the control module of the simulator always logs data.

Warning

Only one UAV platform should be enabled at a time. When adding a new platform, it must also be registered in:

• sim-platforms.hpp
• sim-bridge.hpp
• sim-bridge.cpp
• The corresponding platform implementation (.hpp / .cpp)

---

🌍 2. Configure the Physics Engine

Open

config/phy-config.yaml

This file configures

• 🌎 Gravity
• ⚙️ Solver
• ⏱️ Physics timestep
• 💥 Collision system
• 🕒 Real-time execution

---

🌎 Gravity

Enable normal Earth gravity

physics:
  gravity: true

Disable gravity

physics:
  gravity: false

---

⚙️ Solver Configuration

Example

solver:
  PSOR: true
  MaxIterations: 50
  EnableWarmStart: true
  StepSize: 5e-3
  ThrottleRealTime: false

Parameter descriptions

Parameter	Description
PSOR	Enables the Projected Successive Over-Relaxation solver.
MaxIterations	Maximum solver iterations performed every timestep.
EnableWarmStart	Uses the previous solution to accelerate convergence.
StepSize	Physics timestep (seconds).
ThrottleRealTime	Attempts to maintain real-time execution.

For higher simulation accuracy

solver:
  MaxIterations: 100
  StepSize: 2.5e-3

For faster execution

solver:
  MaxIterations: 30
  StepSize: 5e-3

Warning

Only one solver should be enabled at a time.

Note

If the simulator begins producing NaN states, increasing MaxIterations usually improves solver convergence.

Note

ThrottleRealTime is intended for soft real-time execution. It is generally recommended to leave this option disabled for faster-than-real-time simulations and benchmarking. Since the simulator's execution speed is highly dependent on your CPU performance, enable this option only if your hardware is capable of running the simulation faster than real time and you wish to emulate real-time execution for SIL or HIL testing. Otherwise, leave this option disabled.

---

💥 Collision System

Example

collision:
  BULLET: true
  MULTICORE: false

Warning

Enable only one collision detection system at a time.

---

🎮 3. Configure Visualization

Open

config/vis-config.yaml

This file controls

• 🖥️ Rendering backend
• 📷 Camera
• 🎨 Rendering overlays
• 🎞️ Visualization frame rate

---

🖥️ Enable Visualization

Interactive mode

main:
  enable_vis: true

Headless mode

main:
  enable_vis: false

Note

Running without visualization significantly increases simulation speed and is recommended for automated testing or long-duration simulations.

---

🎨 Rendering Backend

Default Vulkan renderer

main:
  enable_vulkan: true
  enable_irrlicht: false

Irrlicht renderer

main:
  enable_vulkan: false
  enable_irrlicht: true

Warning

Enable only one visualization backend. Vulkan and Irrlicht cannot be used simultaneously.

---

📷 Camera Options

Example

camera:
  enable_static_cam: false
  mv_cam_chase_ht: 1.0
  mv_cam_chase_dt: 1.0

Static camera

camera:
  enable_static_cam: true

Follow camera

camera:
  enable_static_cam: false

---

🛰️ Rendering Options

Example

render:
  render_ned_frame: true
  render_body_frame: true
  render_prop_frames: false
  render_all_COG_frames: false
  render_trajectory: true
  render_biplane_frame: false

Common useful configurations

Show only the trajectory

render:
  render_ned_frame: false
  render_body_frame: false
  render_trajectory: true

Show all coordinate frames

render:
  render_ned_frame: true
  render_body_frame: true
  render_prop_frames: true
  render_all_COG_frames: true

---

🚀 4. Launch the Simulator

After configuring the YAML files, launch the simulator normally.

During startup the simulator will

1. 📄 Load all configuration files.
2. 🌍 Initialize the Chrono physics engine.
3. 🚁 Construct the selected UAV platform.
4. 🎮 Initialize the visualization backend (if enabled).
5. ▶️ Start the simulation loop.

Start the simulation loop:

Navigate to the build/ folder in the project's root directory where you compiled the simulator in the installation section. Then launch the simulation with

./acsl_sim

Note

Changes to the YAML configuration files are loaded every time the simulator starts. You do not need to rebuild the project unless you modify the simulator source code.

Tip

A good starting configuration for most users is:

# sim-config.yaml
mode:
  enable_flightstack_loop: false

# phy-config.yaml
physics:
  gravity: true

solver:
  PSOR: true
  MaxIterations: 50
  StepSize: 5e-3

# vis-config.yaml
main:
  enable_vis: true
  enable_vulkan: true