A Chrono YAML MBS simulation file defines the setup for a Chrono multibody 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 MBS here.
[required] The MBS model object which defines YAML specification of multibody problem.
[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.

MBS simulation specification

An MBS simulation must specify the multibody 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 an MBS model specification (which must follow the MBS 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 an MBS simulation configuration:

chrono-version: 9.0
type: MBS
 
model:  "model_slider_crank.yaml"
#model:  "model_slider_crank_reduced.yaml"
#model:  "model_motors.yaml"
#model:  "model_bushing.yaml"
 
solver: "solver_mbs.yaml"
#solver: "solver_mbs_stiff.yaml"
 
simulation:
  end_time: 100
  enforce_realtime: true
  
output:
  type: HDF5
  fps: 20
 
visualization:
  type: Model_file
  render_fps: 120
  enable_shadows: true
  camera:
    vertical: Z
    location: [9, -4, 1]
    target: [2, 0, 0]

YAML schema

The YAML MBS simulation specification file must follow the data/yaml/schema/mbs_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 MBS 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 simulation
 
type:
  description: Type of Chrono simulation (must be MBS)
  type: string
  value: MBS
 
model:
  description: |
      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 mbs_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]
  