YAML schema for Chrono simulation specification

A YAML file simulation.yaml defines the main parameters needed to run a Chrono simulation. It includes:

  1. Time Settings: How long to run the simulation and at what resolution
  2. Contact Settings: How to handle collisions and contacts
  3. Solver Settings: How to solve the equations of motion
  4. Visualization Settings: How to display the simulation

File Structure

A simulation file contains these main sections:

Required Parameters

Property Description Type
time_step Integration timestep in seconds number
contact_method Contact method for collision detection and response string (SMC/NSC)

Optional Parameters

Property Description Type
end_time Total simulation time in seconds number
enforce_realtime Whether to enforce real-time simulation boolean
gravity Gravitational acceleration vector [x, y, z] array[3]

Integrator, solver, and visualization settings

Property Description Type
integrator Integrator type and parameters object
solver (DVI or linear) solver type and parameters object
visualization Run-time visualization settings object

Integrator types and parameters

The integrator can be of one of the following types:

  • EULER_IMPLICIT_LINEARIZED
  • EULER_IMPLICIT_PROJECTED
  • EULER_IMPLICIT
  • HHT

Solver types and parameters

The solver can be one of the following types:

  • BARZILAI_BORWEIN
  • PSOR
  • APGD
  • MINRES
  • GMRES
  • BICGSTAB
  • PARDISO
  • MUMPS
  • SPARSE_LU
  • SPARSE_QR

Run-time visualization parameters

If an entry with key visualization is present, run-time visualization will be enabled. The following optional parameters can be set:

Property Description Type
render_fps Target frames per second for visualization number
enable_shadows Whether or not shadows are enabled in the visualization system boolean
camera Camera vertical, location, and look-at point object

Example

Below is an example of a simulation configuration:

# Basic MBS simulation
contact_method: SMC
time_step: 1e-4
end_time: 100
enforce_realtime: true
integrator:
type: Euler_implicit_linearized
solver:
type: Barzilai_Borwein
max_iterations: 100
overrelaxation_factor: 1.0
sharpness_factor: 1.0
visualization:
render_fps: 120
enable_shadows: true
camera:
vertical: Z
location: [9, -4, 1]
target: [2, 0, 0]

YAML schema

The YAML model specification file must follow the data/yaml/schema/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 simulation specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
# The `simulation` object contains the schema for the simulation YAML specification.
#
# =============================================================================
chrono-version:
type: string
description: Chrono version compatible with this YAML simulation 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
simulation:
description: |
Schema for simulation parameters.
This schema defines the numerical integration, solver, and visualization settings.
type: object
required: [time_step, contact_method]
properties:
time_step:
type: number
description: Time step size in seconds.
minimum: 0
contact_method:
type: string
description: Contact method for collision detection and response.
enum: [SMC, NSC]
end_time:
type: number
description: |
Total simulation duration in seconds.
The simulation will run from t=0 to t=end_time.
minimum: 0
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]
integrator:
type: object
description: Integrator type and parameters.
required: [type]
properties:
type:
type: string
description: Type of numerical integrator.
enum: [EULER_IMPLICIT_LINEARIZED, EULER_IMPLICIT_PROJECTED, EULER_IMPLICIT, HHT]
rel_tolerance:
type: number
description: Relative tolerance (HHT and implicit Euler).
minimum: 0
default: 1e-4
abs_tolerance_states:
type: number
description: Absolute tolerance for state variables (HHT and implicit Euler).
minimum: 0
default: 1e-4
abs_tolerance_multipliers:
type: number
description: Absolute tolerance for Lagrange multipliers (HHT and implicit Euler).
minimum: 0
default: 1e2
max_iterations:
type: number
description: Maximum number of non-linear iteration for implicit integrators.
minimum: 0
default: 50
use_stepsize_control:
type: boolean
description: Whether to use internal step-size control
default: false
use_modified_newton:
type: boolean
description: Whether to use a modified Newton iteration.
default: false
solver:
type: object
description: Solver type and parameters.
required: [type]
properties:
type:
type: string
description: Type of linear solver.
enum: [BARZILAI_BORWEIN, PSOR, APGD, MINRES, GMRES, BICGSTAB, PARDISO, MUMPS, SPARSE_LU, SPARSE_QR]
max_iterations:
type: number
description: Maximum number of iteration for iterative DVI and linear solvers.
minimum: 0
default: 100
overrelaxation_factor:
type: number
description: Overrelaxation factor for iterative DVI solvers.
minimum: 0
default: 1.0
sharpness_factor:
type: number
description: Sharpness factor for iterative DVI solvers.
minimum: 0
default: 1.0
tolerance:
type: number
description: Tolerance for iterative Krylov linear solvers.
minimum: 0
default: 0.0
enable_diagonal_preconditioner:
type: boolean
description: Whether to use a diagonal preconditioner for iterative Krylov linear solvers.
default: false
lock_sparsity_pattern:
type: boolean
description: Keep matrix sparsity pattern unchanged (direct sparse linear solvers).
default: false
use_sparsity_pattern_learner:
type: boolean
description: Evaluate matrix sparsity pattern in a pre-processing stage (direct sparse linear solvers).
default: true
visualization:
type: object
properties:
render_fps:
type: number
description: Target frames per second for visualization.
minimum: 0
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 (x, y, z)
default: [0, -1, 0]
target:
<<: *VECTOR3D
description: Initial camera look-at point
default: [0, 0, 0]