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 fileds 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]

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
`type`	Output DB type	enum	`NONE`,`ASCII`,`HDF5`	No	`NONE`
`mode`	Output mode	enum	`FRAMES`,`SERIES`	No	`FRAMES`
`fps`	Output frequency (FPS or Hz)	double	–	No	30

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 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	–

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]

Example

Below is an example of a simulation configuration:

chrono-version: 9.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:
  type: HDF5
  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]

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]
    
output:
  description: Output settings
  type: object
  properties:
     type:
        type: string
        description: Output DB type
        enum: [NONE, ASCII, HDF5]
        default: NONE
     fps:
        type: number
        description: Output frequency
        minimum: 0
 
visualization:
  description: Visualization settings
  type: object
  properties:
      type:
          type: string
          description: Visualization type.
          enum: [MODEL_FILE, PRIMITIVES, COLLISION, NONE]
          default: MODEL_FILE
      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]
  