YAML schema for Chrono::Vehicle simulation specification

A Chrono YAML vehicle simulation file defines the setup for a Chrono::Vehicle simulation. It consists of the following main objects:

  • [required] The Chrono version (chrono-version) that is compatible with the YAML model specification. This is a string of the form M.m (major.minor) or M.m.p (major-minor-patch), although only the two fields are verified for compatibility.
  • [required] The simulation type, which must be VEHICLE here.
  • [required] The vehicle model object which defines YAML specification of vehicle system.
  • [required] The MBS solver object which defines YAML specification of the solver algorithms.
  • [optional] The simulation object specifying how simulation is to be performed.
  • [optional] The output object which specifies output options from the MBS simulation.
  • [optional] The visualization object which specifies run-time visualization settings.

Vehicle simulation specification

A vehicle simulation must specify the vehicle model to be simulated, integrator and solver settings, as well as optional output and run-time visualization settings.

Model and solver specification

The model entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with a vehicle model specification (which must follow the vehicle model schema).

The solver entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with an MBS solver specification (which must follow the MBS solver schema).

Simulation options

Property Description Type Available Values Required Default
enforce_realtime Whether to enforce real-time simulation boolean – No false
end_time Total simulation time in seconds double – No -1 for infinite simulation
gravity Gravitational acceleration vector [x, y, z] array[3] – No [0, 0, -9.8]
num_threads Number of threads used by the parallel components object – No –

The num_threads key, if present, specifies the following properties:

Property Description Type Available Values Required Default
chrono Number of threads used by Chrono integer – No 1
collision Number of threads used by the collision detection system integer – No 1
eigen Number of threads used by Eigen integer – No 1
pardiso Number of threads used by the PARDISO solver integer – No 1

The pardiso entry is used only when the solver file selects the PARDISO solver type.

Output options

If the output key is present, it must specify a YAML object with the following properties:

Property Description Type Available Values Required Default
format Output DB format enum NONE,ASCII,HDF5 Yes –
mode Output mode (one file per output frame, or a single time-series file) enum FRAMES,SERIES No FRAMES
fps Output frequency (FPS or Hz) double – No 100

Note that format is required whenever the output key is present. HDF5 output silently falls back to NONE in a build without HDF5 support.

Visualization options

If the visualization key is present, it must specify a YAML object with the following properties:

Property Description Type Available Values Required Default
type Type of body visualization shapes enum NONE,PRIMITIVES,MODEL_FILE,COLLISION No NONE
render_fps Rendering frequency (FPS or Hz) double – No 120
enable_shadows Turn on shadow rendering boolean – No true
camera Camera settings object – No –
output Image output settings object – No –

The camera key, if present, specifies the following properties:

Property Description Type Available Values Required Default
vertical Vertical direction (camera "up") enum Y,Z No Z
location Camera initial location array[3] – No [0,-1,0]
target Camera initial target ("look-at" point) array[3] – No [0,0,0]

The output key, if present, specifies the following properties:

Property Description Type Available Values Required Default
save_images Whether to save rendered frames as image files boolean – No false
image_type Image file type, specified through the file extension string – No bmp

Run-time visualization is enabled only if the visualization key is present and specifies a type other than NONE. In other words, omitting the visualization key and specifying type: NONE are equivalent and both result in a simulation run with no run-time visualization.

Note that type controls the visualization shapes created for plain rigid bodies. The visualization types used for the vehicle sub-systems (chassis, suspension, steering, wheels, tires, and tracked-vehicle components) are currently fixed by the parser and cannot be set from YAML.

Example

Below is an example of a simulation configuration:

chrono-version: 10.0
type: VEHICLE
model: "polaris.yaml"
#model: "marder.yaml"
solver: "solver_mbs.yaml"
simulation:
end_time: 10
enforce_realtime: true
gravity: [0, 0, -9.8]
output:
format: HDF5
mode: FRAMES
fps: 10
visualization:
type: Model_file
render_fps: 60
enable_shadows: true
camera:
vertical: Z
location: [2, 2, 1.8]
target: [0, 0, 0.6]
output:
save_images: false
image_type: "bmp"

YAML schema

The YAML vehicle simulation specification file must follow the data/yaml/schema/vehicle_simulation.schema.yaml provided in the Chrono data directory:

# =============================================================================
# PROJECT CHRONO - http://projectchrono.org
#
# Copyright (c) 2025 projectchrono.org
# All rights reserved.
#
# Use of this source code is governed by a BSD-style license that can be found
# in the LICENSE file at the top level of the distribution and at
# http://projectchrono.org/license-chrono.txt.
# =============================================================================
#
# Schema for a Chrono YAML VEHICLE simulation specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
required: [chrono-version, type, model, solver]
chrono-version:
type: string
description: Chrono version compatible with this YAML specification (M.m or M.m.p)
# -----------------------------------------------------------------------------
# Definitions of common Chrono types
vector3d: &VECTOR3D # Specification of a ChVector3d
type: array
items:
type: number
minItems: 3
maxItems: 3
# -----------------------------------------------------------------------------
# Definition of a Chrono::Vehicle simulation
type:
description: Type of Chrono simulation (must be VEHICLE)
type: string
value: VEHICLE
model:
description: |
Vehicle model specification YAML file.
The path to the model file must be provided relative to the location of this simulation specification file.
The model file must follow the vehicle_model.schema.
type: string
solver:
description: |
Solver specification YAML file
The path to the solver file must be provided relative to the location of this simulation specification file.
The solver file must follow the mbs_solver.schema.
type: string
simulation:
description: Simulation settings
type: object
properties:
end_time:
type: number
description: |
Total simulation duration in seconds.
The simulation will run from t=0 to t=end_time. A negative value indicates an infinite end time.
minimum: 0
default: -1
enforce_realtime:
type: boolean
description: Whether to enforce real-time simulation.
default: false
gravity:
type: array
<<: *VECTOR3D
description: Gravitational acceleration vector [x, y, z]
default: [0, 0, -9.8]
num_threads:
type: object
description: |
Number of threads used by the various parallel components.
Any entry that is omitted keeps its default value of 1.
properties:
chrono:
type: integer
description: Number of threads used by Chrono
minimum: 1
default: 1
collision:
type: integer
description: Number of threads used by the collision detection system
minimum: 1
default: 1
eigen:
type: integer
description: Number of threads used by Eigen
minimum: 1
default: 1
pardiso:
type: integer
description: Number of threads used by the PARDISO solver (used only with the PARDISO solver type)
minimum: 1
default: 1
output:
description: Output settings
type: object
required: [format]
properties:
format:
type: string
description: Output DB format
enum: [NONE, ASCII, HDF5]
default: NONE
mode:
type: string
description: Output mode (one file per output frame, or a single time-series file)
enum: [FRAMES, SERIES]
default: FRAMES
fps:
type: number
description: Output frequency (FPS or Hz)
minimum: 0
default: 100
visualization:
description: Visualization settings
type: object
properties:
type:
type: string
description: |
Type of body visualization shapes.
A value of NONE (the default) also disables run-time visualization altogether.
enum: [MODEL_FILE, PRIMITIVES, COLLISION, NONE]
default: NONE
render_fps:
type: number
description: Target frames per second for visualization.
minimum: 0
default: 120
enable_shadows:
type: boolean
description: Whether to enable shadows in run-time visualization system
default: true
camera:
type: object
properties:
vertical:
type: string
description: Vertical axis for camera orientation
enum: [Y, Z]
default: Z
location:
<<: *VECTOR3D
description: Initial camera location
default: [0, -1, 0]
target:
<<: *VECTOR3D
description: Initial camera look-at point
default: [0, 0, 0]
output:
type: object
description: Run-time visualization image output
properties:
save_images:
type: boolean
description: Whether to save rendered frames as image files
default: false
image_type:
type: string
description: Image file type, specified through the file extension
default: bmp