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 fields 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]
`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.

FEA mesh nodes are included in output only if selected in the model specification file (see the output_nodes property of FEA beams). Each selected node is identified by the mesh (beam) name and its node index:

ASCII output: one FEA node entry per node, with its position and velocity, orientation and angular velocity (nodes with rotational coordinates), or slope (nodes with slope coordinates).
HDF5 output, FRAMES mode: one data set FEA Mesh <name> per mesh and output frame, with one record per selected node (fields not applicable to a node type are set to NaN).
HDF5 output, SERIES mode: one group /FEA_Nodes/<name>/node_<index> per selected node, with time series pos, lin_vel and, as applicable, rot, ang_vel (nodes with rotational coordinates) or slope.

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.

Example

Below is an example of an MBS simulation configuration:

chrono-version: 10.0
type: MBS
 
model:  "model_slider_crank.yaml"
#model:  "model_slider_crank_reduced.yaml"
#model:  "model_motors.yaml"
#model:  "model_bushing.yaml"
#model:  "model_cylindrical_joint.yaml"
 
solver: "solver_nonstiff.yaml"
#solver: "solver_stiff.yaml"
 
simulation:
  end_time: 100
  enforce_realtime: true
  
output:
  format: ASCII
  mode: SERIES
  fps: 20
 
visualization:
  type: Model_file
  render_fps: 120
  enable_shadows: true
  camera:
    vertical: Z
    location: [9, -4, 1]
    target: [2, 0, 0]
  output:
    save_images: false
    image_type: "bmp"

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