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 Default
enforce_realtime Whether to enforce real-time simulation boolean false
end_time Total simulation time in seconds number -1 for infinite simulation
gravity Gravitational acceleration vector [x, y, z] array[3] [0, 0, -9.8]

Integrator, solver, and visualization settings

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

Integrator types and parameters

The integrator can be of one of the following types:

  • EULER_IMPLICIT_LINEARIZED
  • EULER_IMPLICIT_PROJECTED
  • EULER_IMPLICIT
  • HHT

Each integrator can support the following settings depending on the integrator type:

Property Description Type Default
rel_tolerance Relative tolerance (HHT and implicit Euler) number 1e-4
abs_tolerance_states Absolute tolerance for state variables (HHT and implicit Euler) number 1e-4
abs_tolerance_multipliers Absolute tolerance for Lagrange multipliers (HHT and implicit Euler) number 1e2
max_iterations Maximum number of non-linear iteration for implicit integrators. number 50
use_stepsize_control Whether to use internal step-size control boolean false
use_modified_newton Whether to use a modified Newton iteration boolean false

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

Each solver supports different configuration parameters depending on the solver type:

Iterative DVI Solvers (BARZILAI_BORWEIN, APGD, PSOR)

Property Description Type Default
max_iterations Maximum number of iterations number 100
overrelaxation_factor Overrelaxation factor for improved convergence number 1.0
sharpness_factor Sharpness factor for solver response tuning number 1.0

Iterative Krylov Linear Solvers (BICGSTAB, MINRES, GMRES)

Property Description Type Default
max_iterations Maximum number of iterations number 100
tolerance Residual tolerance for convergence number 0.0
enable_diagonal_preconditioner Enable diagonal preconditioner to accelerate convergence boolean fasle

Direct Sparse Linear Solvers (SPARSE_LU, SPARSE_QR, PARDISO_MKL, MUMPS)

Property Description Type Default
lock_sparsity_pattern Keep matrix sparsity pattern unchanged boolean false
use_sparsity_pattern_learner Evaluate matrix sparsity pattern in a pre-processing stage (for SPARSE_LU and SPARESE_QR only) boolean true

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

Camera Settings

The camera object specifies the initial view configuration for run-time visualization. All fields are optional; if omitted, defaults will be used.

Property Description Type Default
vertical Vertical axis for camera orientation string (Y or Z) Z
location Initial amera location [x, y, z] array[3] [0, -1, 0]
target Initial camera look-at point [x, y, z] array[3] [0, 0, 0]

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. A negative value indicates na 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]
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 (HHT).
default: false
use_modified_newton:
type: boolean
description: Whether to use a modified Newton iteration (HHT).
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:
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 (x, y, z)
default: [0, -1, 0]
target:
<<: *VECTOR3D
description: Initial camera look-at point
default: [0, 0, 0]