YAML schema for Chrono::Vehicle single-wheel test rig model specification

A Chrono YAML wheel test rig model file defines the rig mechanism of a wheel test rig simulation: the wheel assembly under test, the rig properties, and the multibody solver. It is the "multibody" side of a wheel test rig simulation, independent of the terrain and of the test scenario. It consists of the following objects:

  • [required] The Chrono version (chrono-version) that is compatible with the YAML 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 model object, which defines the wheel assembly.
  • [optional] The rig object, which defines the test rig properties.
  • [required] The solver entry, the path to the MBS solver specification file.

Wheel assembly specification

The wheel assembly is one of the following types:

  • VEHICLE: a Chrono::Vehicle wheel and tire, optionally attached to a Chrono::Vehicle suspension, all specified through Chrono::Vehicle JSON specification files.
  • CUSTOM: a wheel assembly provided by the application, for example a wheel or wheel-suspension assembly of a robot or vehicle model built outside Chrono::Vehicle. The assembly is created by a factory function that the application registers with the YAML parser.
Property Description Type Available Values Required Default
type Type of wheel assembly enum VEHICLE,CUSTOM No VEHICLE
name Name of the model string – No empty string
angle_degrees Whether angles in this file (rig.camber_angle) are specified in degrees (true) or radians (false) boolean – No true
data_path Location of the JSON data files referenced below object – No absolute paths
wheel_json JSON file for the wheel subsystem string – Yes, VEHICLE type –
tire_json JSON file for the tire subsystem string – Yes, VEHICLE type –
suspension_json JSON file for a suspension subsystem to which the wheel is attached string – No no suspension
tire Tire settings, VEHICLE type only object – No –
assembly Name of the registered factory, CUSTOM type only string – Yes, CUSTOM type –
parameters Parameters passed to the factory, CUSTOM type only object – No –

The model name is also used to name the output files.

The data_path key, if present, specifies the following properties:

Property Description Type Available Values Required Default
type Mode for data file location enum ABSOLUTE,RELATIVE Yes ABSOLUTE
root Root of data files, relative to the location of this file string – No .

Chrono::Vehicle wheel assemblies

A VEHICLE wheel assembly consists of a wheel and a tire and, optionally, a suspension.

Any Chrono::Vehicle tire with a collision geometry (rigid tires, including rigid mesh tires) can be used on any terrain type. Handling (force-element) tires, such as TMeasy or Pacejka tires, have no collision geometry and can only be used on rigid terrain. FEA (deformable) tires are not supported.

The tire key, if present, specifies the following properties:

Property Description Type Available Values Required Default
collision_type Tire-terrain collision detection type (handling tires only) enum SINGLE_POINT,FOUR_POINTS,ENVELOPE No SINGLE_POINT

With a suspension (suspension_json), the wheel is attached to the spindle of the suspension and the suspension to the rig chassis. The suspension geometry then dictates the camber and slip angles, so rig.camber_angle and the test slip_angle are ignored. A steerable suspension can be steered through the test steering input (see slip angle and steering); the rig creates a steering rack to which the suspension tierods are attached. For an independent suspension, the vertical travel of the other side (which is not supported by the terrain) is locked. The mass of the suspension is included in the mass supported by the wheel.

Custom wheel assemblies

A CUSTOM wheel assembly is created by a factory function registered by the application with the ChParserWheelRigYAML parser, under the name given by assembly. The factory receives the Chrono system and the parameters object of this file, unchanged; the content of parameters is defined by the application. The factory must return a wheel assembly derived from ChWheelTestRig::WheelAssembly; see its documentation for the requirements on a wheel assembly implementation.

For example, a program could register a factory for a custom wheel as follows (where MyWheel is a class derived from ChWheelTestRig::WheelAssembly):

parsers::ChParserWheelRigYAML parser(yaml_filename);
parser.RegisterWheelAssembly("My_wheel", [](ChSystem& sys, const YAML::Node& params) {
auto wheel = chrono_types::make_shared<MyWheel>(sys);
if (params["radius"])
wheel->SetRadius(params["radius"].as<double>());
return wheel;
});
auto sys = parser.CreateSystem();
auto rig = parser.CreateRig(*sys);

The factory must be registered before the rig is created. A rig model with a CUSTOM wheel assembly therefore cannot be used with the run_chrono program, which does not register any factories.

Rig properties

Property Description Type Available Values Required Default
normal_load Normal load on the wheel (N) double – No 1000
camber_angle Constant wheel camber angle (ignored with a suspension) double – No 0

The normal load is typically the static wheel load of the vehicle the wheel belongs to. It can be overridden for a given test through test.normal_load in the simulation file. The rig mass is set so that the total weight supported by the wheel equals this load. With a suspension, the suspension is held at its static equilibrium configuration under this load during the drop phase of a test, and released once the tire carries the normal load. This loaded configuration is also the reference for steering angles (see steering and slip angle reference).

Solver specification

The solver entry (required) must specify the path (relative to the location of this YAML file) to the YAML file with an MBS solver specification, which must follow the MBS solver schema. Its integrator time step is the step size for the multibody system and the wheel assembly dynamics.

Examples

Below is an example of a rig model with a Chrono::Vehicle wheel, tire, and steerable suspension:

## Rig mechanism: HMMWV wheel with TMeasy tire on the steerable HMMWV front suspension
chrono-version: 10.0
model:
type: VEHICLE # VEHICLE, CUSTOM
name: HMMWV_front_TMeasy
angle_degrees: true
data_path:
type: RELATIVE
root: "../../.."
wheel_json: "vehicle/hmmwv/wheel/HMMWV_Wheel.json"
tire_json: "vehicle/hmmwv/tire/HMMWV_TMeasyTire.json"
suspension_json: "vehicle/hmmwv/suspension/HMMWV_DoubleWishboneFront.json"
tire:
collision_type: FOUR_POINTS # SINGLE_POINT, FOUR_POINTS, ENVELOPE
rig:
normal_load: 6500 # HMMWV front static wheel load
#camber_angle: 0 # ignored with a suspension
solver: "rig_solver.yaml"

Below is an example of a rig model with a custom wheel assembly:

## Rig mechanism: Viper rover wheel (custom wheel assembly provided by the application), without suspension
chrono-version: 10.0
model:
type: CUSTOM # VEHICLE, CUSTOM
name: Viper_wheel
angle_degrees: true
assembly: Viper_wheel # name of the factory registered by the application
parameters: # passed unchanged to the custom wheel assembly factory
radius: 0.225
width: 0.2
grouser_height: 0.02
grouser_width: 0.01
num_grousers: 24
rig:
normal_load: 1000
camber_angle: 0
solver: "rig_solver.yaml"

YAML schema

The YAML wheel test rig model specification file must follow the data/yaml/schema/wheel_rig_model.schema.yaml provided in the Chrono data directory:

# =============================================================================
# PROJECT CHRONO - http://projectchrono.org
#
# Copyright (c) 2026 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 YAML Chrono::Vehicle single-wheel test rig mechanism specification file.
# This is the "multibody" side of a WHEEL_RIG simulation (see wheel_rig_simulation.schema): the wheel assembly under
# test, the rig properties, and the MBS solver.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
required: [chrono-version, model, solver]
chrono-version:
type: string
description: Chrono version compatible with this YAML specification (M.m or M.m.p)
# -----------------------------------------------------------------------------
# Wheel assembly
model:
description: |
Definition of the wheel assembly under test, either
- VEHICLE: a Chrono::Vehicle wheel, tire, and (optional) suspension, specified through Chrono::Vehicle JSON files
(`wheel_json` and `tire_json` required), or
- CUSTOM: a wheel assembly provided by the application (e.g., a wheel or wheel-suspension assembly of a robot or
vehicle model built outside Chrono::Vehicle), created by a factory that the application registers with the
YAML parser under the name given by `assembly` (required).
type: object
properties:
type:
type: string
description: Type of wheel assembly
enum: [VEHICLE, CUSTOM]
default: VEHICLE
name:
type: string
description: Name of the model
default: ''
assembly:
type: string
description: Name of the registered factory for a CUSTOM wheel assembly (CUSTOM type only)
parameters:
type: object
description: |
Parameters of a CUSTOM wheel assembly (CUSTOM type only). This object is passed unchanged to the factory of
the custom wheel assembly; its content is defined by the application.
angle_degrees:
type: boolean
description: Whether angles in this file (`rig.camber_angle`) are specified in degrees (true) or radians (false)
default: true
data_path:
type: object
description: Location of the JSON data files referenced in this 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, relative to the location of this script
default: "."
wheel_json:
description: JSON file for wheel subsystem specification (VEHICLE type only)
type: string
tire_json:
description: |
JSON file for tire subsystem specification (VEHICLE type only).
Handling (force-element) tires have no collision geometry and can only be used with RIGID terrain.
FEA (deformable) tires are not supported.
type: string
suspension_json:
description: |
JSON file for an optional suspension subsystem to which the wheel is attached (VEHICLE type only).
With a suspension, the suspension geometry dictates camber and slip angle, so `rig.camber_angle` and the
test `slip_angle` are ignored. A steerable suspension can be steered through the test `steering` input.
For an independent suspension, the vertical travel of the other side (not supported by the terrain) is locked.
type: string
tire:
type: object
description: Optional tire settings (VEHICLE type only)
properties:
collision_type:
type: string
description: Tire-terrain collision detection type (handling tires only)
enum: [SINGLE_POINT, FOUR_POINTS, ENVELOPE]
default: SINGLE_POINT
# -----------------------------------------------------------------------------
# Rig properties
rig:
description: Test rig properties
type: object
properties:
normal_load:
description: |
Desired normal load on the wheel (N), typically the static wheel load of the vehicle the wheel belongs to.
Can be overridden for a given test through `test.normal_load` in the simulation file.
The rig mass is set so that the total weight supported by the wheel equals this load. With a suspension,
the suspension is held at its static equilibrium configuration under this load during the drop phase.
type: number
minimum: 0
default: 1000
camber_angle:
description: Constant wheel camber angle (ignored if a suspension is specified)
type: number
default: 0
# -----------------------------------------------------------------------------
# MBS solver
solver:
description: |
MBS solver specification YAML file, with the path relative to this file.
The file must follow the mbs_solver.schema. Its integrator time step is the step size for the multibody system
and the wheel assembly dynamics.
type: string