YAML schema for Chrono model specification
Model specification
A YAML model file model.yaml defines the mechanical system for the simulation. It defines:
- Bodies: rigid bodies that carry mass and inertia and, optionally, collision and visualization geometry
- Joints: connection between a pair of bodies, specified either as a kinematic (ideal) joint or as a bushing
- Passive force elements: translational and rotational linear or non-linear spring-damper force elements acting between two rigid bodies
- Motors and actuators:
- translational and rotational motors acting between two rigid bodies at the position (displacement or angle), velocity (linear or angular speed), or force (force or torque) levels. Motors are specified through a time function for the control input (position, velocity, or force)
- external actuators
Bodies
Each body represents a physical object in the simulation with the following properties:
| Property | Description | Required | Default |
|---|---|---|---|
name | Unique identifier for the body | Yes | |
fixed | Indicates if body fixed relative to global frame | No | false |
mass | Mass in kg | Yes, if body not fixed | |
com | Center of Mass, relative to body reference frame | No | same as body reference frame |
inertia->moments | Moments of inertia [Ixx, Iyy, Izz] relative to centroidal frame | Yes, if body not fixed | |
inertia->products | Products of inertia [Ixy, Iyz, Izx] relative to centroidal frame | No | [0, 0, 0] |
location | Origin of the body reference frame, relative to model frame | Yes | |
orientation | Orientation of the body reference frame relative to model frame | No | identity rotation |
Joints
Joints connect two bodies and constrain their relative motion. They can be represented through constraints (kinematic joints) or through stiff compliance (bushings).
| Property | Description | Required |
|---|---|---|
type | Joint type (revolute, prismatic, spherical, etc.) | Yes |
name | Unique identifier for the joint | Yes |
body1 | Name of the first body to connect | Yes |
body2 | Name of the second body to connect | Yes |
bushing_data | Bushing compliance data; if not present, the joint is kinematic | No |
Passive spring-damper force elements
Spring-damper elements apply forces between bodies.
| Property | Description | Required |
|---|---|---|
type | Spring-damper type type (TSDA, RSDA) | Yes |
name | Unique identifier for the force element | Yes |
body1 | Name of the first body to connect | Yes |
body2 | Name of the second body to connect | Yes |
For linear spring-dampers, use the spring_coefficient and damping_coefficient properties. For example:
spring_dampers:
- name: linear_spring_damper
type: TSDA
body1: first_body
body2: second_body
point1: [6.5, 0, 0]
point2: [5.5, 0, 0]
spring_coefficient: 50.0
damping_coefficient: 5.0
free_length: 1.0
visualization:
type: SPRING
radius: 0.05
resolution: 80
turns: 15
For nonlinear behavior, use spring_curve_data and/or damping_curve_data and/or the pair deformation/map_data. These properties allow specification of spring-damper characteristics as tabular data (which will be linearly interpolated by Chrono at run-time). For example:
spring_dampers:
- name: nonlinear_spring_damper
type: TSDA
body1: first_body
body2: second_body
point1: [6.5, 0, 0]
point2: [5.5, 0, 0]
deformation: [ 0.273304, 0.278384, 0.283464, 0.288544, 0.293624, 0.324104, 0.343002, 0.361899, 0.380797, 0.399694, 0.418592, 0.423672, 0.428752, 0.433832, 0.438912 ],
map_data: [
[ -0.666667, -5691.62, -5691.62, -5691.62, -5691.62, -5691.62, -9690.35, -9690.35, -9690.35, -9690.35, -9690.35, -9690.35, -5691.62, -5691.62, -5691.62, -5691.62 ],
[ -0.333333, -2845.81, -2845.81, -2845.81, -2845.81, -2845.81, -4845.17, -4845.17, -4845.17, -4845.17, -4845.17, -4845.17, -2845.81, -2845.81, -2845.81, -2845.81 ],
[ 0.0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ],
[ 0.333333, 21307.1, 21307.1, 21307.1, 21307.1, 21307.1, 11675.1, 11675.1, 11675.1, 11675.1, 11675.1, 11675.1, 21307.1, 21307.1, 21307.1, 21307.1 ],
[ 0.666667, 42614.2, 42614.2, 42614.2, 42614.2, 42614.2, 23350.2, 23350.2, 23350.2, 23350.2, 23350.2, 23350.2, 42614.2, 42614.2, 42614.2, 42614.2 ]
]
Motors
YAML schema
The YAML model specification file must follow the data/yaml/schema/model.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 model specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
# The `model` object contains the schema for the model YAML specification.
#
# Notes:
# - Chrono is unit-independent.
# While any consistent set of units is acceptable, most models are specified
# in SI units. For convenience, the Chrono YAML specification allows definition
# of angles in radians or degrees.
#
# =============================================================================
chrono-version:
type: string
description: Chrono version compatible with this YAML model specification (M.m or M.m.p)
# -----------------------------------------------------------------------------
# Definitions of common Chrono types
# -----------------------------------------------------------------------------
# Specification of a ChVector3d
vector3d: &VECTOR3D
type: array
items:
type: number
minItems: 3
maxItems: 3
# Specification of a 3D rotation
# A rotation can be provided as:
# - an Euler angle sequence [roll, pitch, yaw], with angles assumed in radians or degrees, or
# - a unit quaternion [e0, e1, e2, e3]
orientation3d: &ORIENTATION3D
type: array
description: Frame orientation as Euler angles or as quaternion
items:
type: number
minItems: 3
maxItems: 4
# Specification of a color
color: &COLOR
type: array
description: RGB color [r, g, b]
items:
type: number
minimum: 0
maximum: 1
minItems: 3
maxItems: 3
# Specification of an inertia matrix
inertia33: &INERTIA33
type: object
description: Inertia moments and products
properties:
moments:
type: array
description: Moments of inertia [Ixx, Iyy, Izz]
items:
type: number
minimum: 0
minItems: 3
maxItems: 3
products:
type: array
description: Products of inertia [Ixy, Ixz, Iyz]
items:
type: number
default: 0
minItems: 3
maxItems: 3
# Specification of a function of one variable
function: &FUNCTION
type: object
description: Function of one variable
required: [type]
properties:
type:
type: string
enum: [CONSTANT, POLYNOMIAL, SINE, DATA]
description: Function type
repeat:
type: object
description: Periodic replication of the underlying function
start:
type: number
description: Slice start position
width:
type: number
description: Slice width
shift:
type: number
description: Slice shift
value:
type: number
description: Constant value for CONSTANT type
coefficients:
type: array
description: Coefficents for POLYNOMIAL type
items:
type: number
minItems: 2
amplitude:
type: number
description: Amplitude for SINE type
frequency:
type: number
description: Frequency for SINE type
phase:
type: number
description: Phase for SINE type
default: 0.0
slope:
type: number
description: Slopr for RAMP type
intercept:
type: number
description: Intercept value for RAMP type
default: 0.0
data:
<<: *DATA_ARRAY_2
description: Interpolation data points for DATA type [[x, f(x)], ...]
# Specification of a data array with 2 columns
data_array_2: &DATA_ARRAY_2
type: array
description: Array of number pairs
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
# Specification of a data array with 3 columns
data_array_3: &DATA_ARRAY_3
type: array
description: Array of number 3-tuples
items:
type: array
items:
type: number
minItems: 3
maxItems: 3
# Specification of a data array with N columns
data_array_N: &DATA_ARRAY_N
type: array
description: Array of N-tuples
items:
type: array
items:
type: number
minItems: 1
# -----------------------------------------------------------------------------
# Definition of a Chrono multibody model
# -----------------------------------------------------------------------------
model:
type: object
description: Definition of a Chrono multibody model
required: [bodies]
properties:
name:
type: string
description: Name of the model
default: ''
angle_degrees:
type: boolean
description: Whether angles are specified in degrees (true) or radians (false)
default: true
bodies:
type: array
description: List of bodies in the system
items:
type: object
required: [name, location]
properties:
name:
type: string
description: Unique identifier for the body
fixed:
type: boolean
description: Whether the body is fixed to ground
default: false
location:
<<: *VECTOR3D
description: Initial body reference frame origin relative to global frame
orientation:
<<: *ORIENTATION3D
description: Initial body reference frame orientation relative to global frame
default: [0, 0, 0]
mass:
type: number
description: Mass of the body
minimum: 0
com:
type: object
description: Center of mass (COM) frame
properties:
location:
<<: *VECTOR3D
description: COM frame origin relative to body reference frame
default: [0, 0, 0]
orientation:
<<: *ORIENTATION3D
description: COM frame orientation relative to body reference frame
default: [1, 0, 0, 0]
inertia:
<<: *INERTIA33
description: Body inertia properties
joints:
type: array
description: List of joints connecting bodies
items:
type: object
required: [name, type, body1, body2, location]
properties:
name:
type: string
description: Unique identifier for the joint
type:
type: string
description: Type of joint
enum: [lock, pointline, pointplane, revolute, spherical, prismatic, universal]
body1:
type: string
description: Name of the first body to connect
body2:
type: string
description: Name of the second body to connect
location:
type: array
description: Joint location
items:
type: number
minItems: 3
maxItems: 3
axis:
<<: *VECTOR3D
description: Axis of motion for revolute/prismatic joints
axis1:
<<: *VECTOR3D
description: First axis for universal joint
axis2:
<<: *VECTOR3D
description: Second axis for universal joint
bushing_data:
type: object
description: Bushing properties
properties:
stiffness_linear:
type: number
description: Linear stiffness coefficient for "constrained" translational DOFs
damping_linear:
type: number
description: Linear damping coefficient for "constrained" translational DOFs
stiffness_rotational:
type: number
description: Rotational stiffness coefficient for "constrained" rotational DOFs
damping_rotational:
type: number
description: Rotational damping coefficient for "constrained" rotational DOFs
DOF:
type: object
description: Degree of freedom specific properties
properties:
stiffness_linear:
type: number
description: Linear stiffness coefficient for "unconstrained" translational DOF
damping_linear:
type: number
description: Linear damping coefficient for "unconstrained" translational DOF
stiffness_rotational:
type: number
description: Rotational stiffness coefficient for "unconstrained" rotational DOF
damping_rotational:
type: number
description: Rotational damping coefficient for "unconstrained" rotational DOF
constraints:
type: array
description: List of constraints in the system
items:
type: object
required: [name, type, body1, body2]
properties:
name:
type: string
description: Unique identifier for the constraint
type:
type: string
enum: [DISTANCE, REVOLUTE-SPHERICAL, REVOLUTE-TRANSLATIONAL]
description: Type of constraint
body1:
type: string
description: Name of the first body to connect
body2:
type: string
description: Name of the second body to connect
point1:
<<: *VECTOR3D
description: Point on body1 expressed in global frame
point2:
<<: *VECTOR3D
description: Point on body2 expressed in global frame
tsdas:
type: array
description: List of translational spring-damper (TSDA) elements
items:
type: object
required: [name, body1, body2, point1, point2]
properties:
name:
type: string
description: Unique identifier for the element
body1:
type: string
description: Name of the first body to connect
body2:
type: string
description: Name of the second body to connect
point1:
<<: *VECTOR3D
description: Point on body1 expressed in global frame
point2:
<<: *VECTOR3D
description: Point on body2 expressed in global frame
free_length:
type: number
description: TSDA free length
spring_coefficient:
type: number
description: Linear spring coefficient
damping_coefficient:
type: number
description: Linear damping coefficient
spring_curve_data:
<<: *DATA_ARRAY_2
description: Nonlinear spring curve data [[displacement, force], ...]
damping_curve_data:
<<: *DATA_ARRAY_2
description: Nonlinear damping curve data [[velocity, force], ...]
deformation:
type: array
description: TSDA deformation values for full non-linear map TSDA (required if map_data present)
items:
type: number
minItems: 1
map_data:
<<: *DATA_ARRAY_N
description: TSDA full non-linear map [[velocity, forces[]], ...]
preload:
type: number
description: Preload force
minimum_length:
type: number
description: Minimum TSDA length
maximum_length:
type: number
description: Maximum TSDA length
visualization:
type: object
description: Visualization settings for the element
properties:
type:
type: string
enum: [segment, spring]
description: Type of visualization
radius:
type: number
description: Radius of the visualization element
color:
<<: *COLOR
rsdas:
type: array
description: List of rotational spring-damper (RSDA) elements
items:
type: object
required: [name, body1, body2, axis]
properties:
name:
type: string
description: Unique identifier for the element
body1:
type: string
description: Name of the first body to connect
body2:
type: string
description: Name of the second body to connect
location:
<<: *VECTOR3D
description: RSDA location expressed in global frame
axis:
<<: *VECTOR3D
description: RSDA axis expressed in global frame
free_angle:
type: number
description: RSDA free angle
spring_coefficient:
type: number
description: Linear spring coefficient
damping_coefficient:
type: number
description: Linear damping coefficient
spring_curve_data:
<<: *DATA_ARRAY_2
description: Nonlinear spring curve data [[displacement, force], ...]
damping_curve_data:
<<: *DATA_ARRAY_2
description: Nonlinear damping curve data [[velocity, force], ...]
preload:
type: number
description: Preload torque
motors:
type: array
description: List of motors in the system
items:
type: object
required: [name, type, body1, body2, location, axis, actuation_type, actuation_function]
properties:
name:
type: string
description: Unique identifier for the motor
type:
type: string
enum: [LINEAR, ROTATION]
description: Type of motor
body1:
type: string
description: Name of the first body to connect
body2:
type: string
description: Name of the second body to connect
location:
<<: *VECTOR3D
description: Motor location expressed in global frame
axis:
<<: *VECTOR3D
description: Motor axis expressed in global frame
actuation_type:
type: string
enum: [POSITION, SPEED, FORCE]
description: Type of actuation
actuation_function:
<<: *FUNCTION
description: Function of time defining actuation
guide:
type: string
enum: [FREE, PRISMATIC, SPHERICAL]
description: Guide constraint for linear motor
spindle:
type: string
enum: [FREE, REVOLUTE, CYLINDRICAL]
description: Spindle constraint for rotation motor
