YAML schema for Chrono model specification

Model specification

A YAML model file model.yaml defines the mechanical system for the simulation. It defines:

  1. Bodies: rigid bodies that carry mass and inertia and, optionally, collision and visualization geometry
  2. Joints: connection between a pair of bodies, specified either as a kinematic (ideal) joint or as a bushing
  3. Passive force elements: translational and rotational linear or non-linear spring-damper force elements acting between two rigid bodies
  4. 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
  5. (Optional) One can set angle_degrees to true or false to use degrees or radiance for angle units. Default is true.

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). Supported joint type are: lock, pointline, pointplane, revolute, spherical, prismatic and universal. Default type is lock.

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
location Joint location Yes
axis Axis of motion for revolute/prismatic joints Yes for revolute/prismatic joints
axis1 First axis for universal joints Yes for universal joints
axis2 Second axis for universal joints Yes for universal joints
bushing_data Bushing compliance data; if not present, the joint is kinematic No

The bushing_data models compliance behavior along the joint's degrees of freedom, instead of a rigid connection. Note that a bushing of joint type prismatic, pointline or pointplane is prohibited. For the constrained DOF, one can specify stiffness and damping coefficients,

Property Description Type
stiffness_linear Linear stiffness coefficient for "constrained" translational DOFs number
damping_linear Linear damping coefficient for "constrained" translational DOFs number
stiffness_rotational Rotational stiffness coefficient for "constrained" rotational DOFs number
damping_rotational Rotational damping coefficient for "constrained" rotational DOFs number

One can also apply compliance to the unconstrained DOF using a nested DOF object, for example,

bushing_data:
stiffness_linear: 7e7
damping_linear: 0.35e5
stiffness_rotational: 1e5
damping_rotational: 5e3
DOF:
stiffness_linear: 5000
damping_linear: 50
stiffness_rotational: 500
damping_rotational: 25

Note that the bushing formulation is valid only for small relative rotations. For rotational stiffness in the presence of large rotations, use a rotational spring-damper element, RSDA.

Constraints

Constraints connect two bodies and constrain their relative motion. Supported constraint type are: DISTANCE, REVOLUTE-SPHERICAL, REVOLUTE-TRANSLATIONAL.

Property Description Required
type Constraint type Yes
name Unique identifier for the constraint Yes
body1 Name of the first body to connect Yes
body2 Name of the second body to connect Yes
point1 Point on body1 expressed in global frame Yes
point2 Point on body2 expressed in global frame Yes

Passive spring-damper force elements

There are two types of spring-damper elements, translational and rotational, speceified as TSDA or RSDA. For a TSDA element, one can have the following fields,

Property Description Required
name Unique identifier for the force element Yes
type Spring-damper type (TSDA or RSDA) Yes
body1 Name of the first body to connect Yes
body2 Name of the second body to connect Yes
point1 Point on body1 expressed in global frame [x,y,z] Yes
point2 Point on body2 expressed in global frame [x,y,z] Yes
free_length TSDA free length No
preload preload force No
minimum_length Minimum TSDA length No
maximum_length Maximum TSDA length No

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

Optionally, you can add a visualization object to render the TSDA element,

Property Description Type
type Type of visualization geometry (segment or spring) string
color RGB color of the element [r, g, b] array[3]
radius Radius of the visualized TSDA geometry (if spring) number
resolution Number of subdivisions along one coil turn (if spring) integer
turns Number of coil turns (if spring) integer

Rotational spring-damper elements, RSDA, apply torques between bodies. One can specifiy the following fields,

Property Description Required
name Unique identifier for the element Yes
body1 Name of the first body to connect Yes
body2 Name of the second body to connect Yes
location RSDA location expressed in global frame [x,y,z] No
axis RSDA axis expressed in global frame [x,y,z] Yes
free_angle RSDA free length No
preload preload torque No
spring_coefficient Linear spring coefficient No
damping_coefficient Linear damping coefficient No
spring_curve_data Nonlinear spring curve data [[angle, torque], ...] No
damping_curve_data Nonlinear damping curve data [[angular velocity, torque], ...] No

Motors

Property Description Required Type Values
name Unique identifier for the motor Yes string
type Type of motor Yes string LINEAR, ROTATION
body1 Name of the first body to connect Yes string
body2 Name of the second body to connect Yes string
location Motor location expressed in the global frame at [x,y,z] Yes array[3] [x, y, z]
axis Motor axis expressed in the global frame at [x,y,z] Yes array[3] [x, y, z]
actuation_type Type of actuation Yes string POSITION, SPEED, FORCE
actuation_function Function of time defining the actuation Yes object See Functions
guide Guide constraint for linear motors No string FREE, PRISMATIC, SPHERICAL
spindle Spindle constraint for rotational motors No string FREE, REVOLUTE, CYLINDRICAL

Functions

A function object is used to specify actuation inputs. The only required field is type, which determines which additional fields are valid. Supported function types include:

  • CONSTANT defines a function with a fixed value;
  • POLYNOMIAL defines a polynomial function of the form f(x) = a₀ + a₁x + a₂x² + ... using the coefficients field: [a₀, a₁, a₂, ...];
  • SINE defines a sinusoidal function with amplitude, frequency and phase;
  • RAMP defines a ramp function with slope and intercept;
  • DATA interpolates a series of data points, for example:
type: DATA
data:
- [0.0, 0.0]
- [1.0, 5.0]
- [2.0, 2.5]

All function types can include an optional repeat field to periodically replicate the function, for example,

repeat:
start: 1.0
width: 2.0
shift: 3.0

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, RAMP, 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: Slope 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
data_path:
type: object
description: Location of data files in the model specification.
required: [type]
properties:
type:
type: string
description: Mode for data file location
enum: [ABSOLUTE, RELATIVE]
default: ABSOLUTE
root:
type: string
description: Root of data files, relatiuve to location of this script
default: "."
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