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

A Chrono YAML wheel test rig simulation file defines a simulation of a single wheel assembly on a test rig (ChWheelTestRig), running on a patch of rigid or deformable terrain. The wheel assembly is either a Chrono::Vehicle wheel and tire (optionally attached to a suspension) or a wheel assembly provided by the application.

Paralleling a Chrono FSI simulation, a wheel test rig simulation combines independent specifications of the rig mechanism (the "multibody" side) and of the terrain, so that the same rig can be tested on different terrains and with different test scenarios:

File Content Schema
simulation test scenario, coupling, simulation, output, plots, and visualization settings this page
rig model wheel assembly, rig properties, and a reference to the MBS solver file wheel test rig model schema
MBS solver multibody integrator and solver MBS solver schema
terrain terrain type, patch, and parameters; for CRM terrain, a reference to the SPH solver file wheel test rig terrain schema
SPH solver SPH solver, CRM terrain only FSI-SPH solver schema

The simulation file consists of the following main 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 simulation type, which must be WHEEL_RIG here.
  • [required] The rig entry, the path to the rig model specification file.
  • [required] The terrain entry, the path to the terrain specification file.
  • [required] The test object, which specifies the test scenario.
  • [required] The simulation object, which specifies how the simulation is to be performed.
  • [optional] The coupling object, which specifies wheel-terrain coupling settings (CRM terrain only).
  • [optional] The output object, which specifies output options.
  • [optional] The plots object, which specifies Gnuplot plots generated at the end of the simulation.
  • [optional] The visualization object, which specifies run-time visualization settings.

The single-wheel test rig

The test rig carries the wheel assembly on a rig chassis that is free to move vertically relative to a carrier body, which in turn moves along the global X axis. The rig mass is sized so that, under gravity, the total weight supported by the wheel equals the specified normal load (see the rig model schema). The test rig assumes a Z-up world frame. The motion of the wheel is controlled through:

  • a linear motor driving the carrier at the prescribed longitudinal speed,
  • a rotational motor driving the wheel at the prescribed angular speed,
  • for a wheel without a suspension, a rotation of the wheel about the vertical axis, imposing the prescribed slip angle,
  • for a wheel with a steerable suspension, a steering actuator acting on the steering mechanism of the assembly.

A motor whose function is not specified is not actuated; for example, a driven wheel is obtained by specifying only the angular speed, and a pulled (towed) wheel by specifying only the longitudinal speed.

The terrain patch is placed by the rig relative to the wheel: it starts 2 wheel radii behind the initial wheel location and extends along the positive X axis.

Rig and terrain specification

The rig entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with a rig model specification, which must follow the wheel test rig model schema.

The terrain entry (required) must specify the path (relative to the location of this YAML simulation specification file) to the YAML file with a terrain specification, which must follow the wheel test rig terrain schema.

Test scenario

The test object specifies the operation mode of the rig and the motion functions. Motion functions are functions of time (with the same specification as functions in the MBS model schema), applied after the time delay.

Property Description Type Available Values Required Default
mode Rig operation mode enum SUSPEND,DROP,TEST Yes –
angle_degrees Whether angles are specified in degrees (true) or radians (false) boolean – No true
drop_speed Wheel lowering speed (m/s), TEST mode only double – No 0.1
time_delay Settling time (s) before the motion functions are applied, measured from the end of the drop phase double – No 0
normal_load Normal load on the wheel (N), overriding the normal load of the rig model double – No rig model value
longitudinal_speed Carrier longitudinal speed (m/s) as a function of time function – No not actuated
angular_speed Wheel angular speed (rad/s) as a function of time function – No not actuated
slip_angle Wheel slip angle as a function of time, wheel without a suspension only function – No 0
steering Steering input, wheel assembly with a steering actuator only object – No –
longitudinal_slip Constant longitudinal slip (overrides longitudinal_speed and angular_speed) object – No –

The angle_degrees setting applies to the values of the slip_angle function and of the steering function with an ANGLE input.

The normal load is normally a property of the rig model (see the rig model schema). The optional normal_load entry overrides it for this test, so that the same wheel assembly can be tested under different loads without duplicating the rig model file. With a suspension, the normal load sets the loaded configuration and therefore the steering reference (see steering and slip angle reference).

Operation modes

  • SUSPEND: the wheel is suspended above the terrain, with a locked spindle.
  • DROP: the wheel is released and falls freely onto the terrain.
  • TEST: the wheel is lowered onto the terrain at drop_speed, then the motion functions are applied after time_delay. Without a suspension, the drop phase ends when the wheel reaches the terrain. With a suspension, the suspension travel is held at its static equilibrium under the normal load and lowering continues until the tire carries the normal load; the suspension is then released, so that releasing it does not change the load on the wheel. A slow drop speed avoids impacting the terrain, which matters in particular for deformable terrain.

Rig measurements (slip, camber, and steering angles, terrain forces, drawbar pull, drive torque) are enabled in TEST mode once the time delay has elapsed; until then, they are reported as zero.

Test scenarios

Typical test scenarios are obtained through the following combinations of motion functions:

Scenario Specification
driven wheel angular_speed only
pulled wheel longitudinal_speed only
immobilized wheel longitudinal_speed and angular_speed, both constant 0
fully prescribed longitudinal_speed, angular_speed, and slip_angle (or steering, with a suspension)
constant slip longitudinal_slip

The longitudinal_slip object, if present, specifies the following properties:

Property Description Type Available Values Required Default
value Longitudinal slip double – Yes –
base_speed Base longitudinal speed (m/s) used to enforce the slip value double – No 1.0

A positive slip value indicates a spinning wheel, a negative value a sliding (skidding) wheel, and a value of -1 a wheel sliding without rotation.

Slip angle and steering

For a wheel without a suspension, the slip angle is imposed directly through the slip_angle function, by rotating the wheel about the vertical axis.

With a suspension, the suspension geometry dictates the wheel orientation, so slip_angle is ignored. A steerable suspension can instead be steered through the steering object, which specifies the following properties:

Property Description Type Available Values Required Default
input Type of steering input enum ANGLE,ACTUATOR Yes –
function Steering angle or actuator coordinate as a function of time function – Yes –
feedback Feedback correction of the actuator coordinate, ANGLE input only object – No –

The wheel is steered at the correct place, about the kingpin axis, through the steering mechanism of the wheel assembly. For a Chrono::Vehicle steerable suspension, the rig creates a steering rack to which the suspension tierods are attached; for an application-provided wheel assembly, the assembly provides its own steering actuator.

  • ACTUATOR: the function specifies the steering actuator coordinate, which is specific to the steering mechanism. For a Chrono::Vehicle steerable suspension, this is the rack displacement (m) along the rig lateral axis.
  • ANGLE: the function specifies the wheel steering angle, positive to the left. The steering angle is converted to the actuator coordinate through a kinematic steering map, computed at initialization by sweeping the steering mechanism over its range at the loaded configuration of the suspension. The resulting actuator motion is a feedforward input, so that bump and compliance steer are retained.

The feedback object, if present, specifies the following properties:

Property Description Type Available Values Required Default
enabled Whether to enable the feedback correction boolean – No false
time_constant Time constant of the feedback correction (s) double – No 0.05

With feedback enabled, an integral correction of the actuator coordinate drives the actual steering angle to the specified one. Note that this cancels bump and compliance steer.

Steering and slip angle reference

Steering angles are measured relative to the loaded configuration of the suspension: the configuration at static equilibrium under the normal load, with the steering actuator at zero. A zero steering angle therefore retains the static toe of the suspension in that configuration. This toe angle is in general different from the design toe of the suspension, because of bump steer: the loaded configuration is usually at a different ride height than the design configuration. As a consequence, a wheel with a suspension may run at a non-zero slip angle even with a zero steering input.

The two angles reported by the rig differ accordingly:

  • the slip angle is the wheel heading relative to the direction of travel and includes the loaded toe;
  • the steering angle is relative to the loaded configuration and does not include it.

For a steerable suspension, the slip angle is the negative of the sum of the steering angle and the loaded toe angle.

During a test, the ride height can change further, for example as lateral tire forces load the suspension through its geometry (jacking). Without feedback, the resulting bump steer changes the actual steering angle; feedback cancels this bump steer, but not the static toe of the loaded configuration.

Wheel-terrain coupling

The optional coupling object specifies settings for the coupling between the wheel and the terrain. Currently, it only applies to CRM terrain, through its crm object:

Property Description Type Available Values Required Default
active_domain CRM active domain attached to the wheel hub object – No –

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

Property Description Type Available Values Required Default
type Active domain type enum NONE,AUTO,BOX Yes NONE
size Box dimensions, BOX type only array[3] – No –

With NONE, the entire SPH domain is always active. With AUTO, the active domain is a box of estimated size (2.5 times the bounding box of the wheel assembly). With BOX, the active domain is a box of the specified size, centered at the hub. These settings are ignored for other terrain types.

Simulation options

Property Description Type Available Values Required Default
time_step Rig step (s), the interval over which the rig is advanced at each call double – No MBS solver step
end_time Total simulation time in seconds double – No -1 for infinite simulation
stop_at_patch_end Whether to end the simulation when the wheel reaches either end of the terrain patch boolean – No false
enforce_realtime Whether to enforce real-time simulation boolean – No false
gravity Gravitational acceleration vector [0, 0, -g] array[3] – No [0, 0, -9.8]
num_threads Number of threads used by the parallel components object – No –

The rig step time_step is distinct from the step sizes of the solvers:

  • With CRM terrain, it is the FSI coupling step. Over each rig step, the multibody system is advanced with the step from the MBS solver file and the SPH system with the step from the SPH solver file; the two exchange data at the end of the rig step.
  • For other terrain types, the multibody system is advanced over each rig step with the step from the MBS solver file.

With stop_at_patch_end enabled, the simulation ends (before end_time) once the wheel hub is within one wheel radius of either end of the terrain patch. This setting is ignored for granular terrain, which uses a moving patch.

The test rig assumes a Z-up world frame: only gravity vectors of the form [0, 0, -g], with g >= 0, are accepted. The magnitude g is used, together with the normal load, to size the rig mass.

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

Property Description Type Available Values Required Default
chrono Number of threads used by Chrono (e.g., SCM ray casting) integer – No 1
collision Number of threads used by the collision detection system integer – No 1
eigen Number of threads used by Eigen integer – No 1
pardiso Number of threads used by the PARDISO solver integer – No 1

The pardiso entry is used only when the MBS solver file selects the PARDISO solver type.

Output options

If the output key is present, it must specify a YAML object with the following properties:

Property Description Type Available Values Required Default
format Output DB format enum NONE,ASCII,HDF5 Yes –
mode Output mode (one file per output frame, or a single time-series file) enum FRAMES,SERIES No FRAMES
fps Output frequency (FPS or Hz); also the sampling frequency of the data recorded for plots double – No 100

Note that format is required whenever the output key is present. HDF5 output silently falls back to NONE in a build without HDF5 support.

Output is written in a subdirectory of the output directory, named after the simulation specification file. The output database contains the rig output channels listed below, each with its name and units.

Output channels

All quantities are in SI units, with angles in radians. Forces and moments are expressed in the global frame and reported at the wheel hub. Quantities marked as measurements are zero until rig measurements are enabled (see operation modes).

Channel Description Units
measuring 1 if rig measurements are enabled, 0 otherwise –
long_slip Longitudinal slip, (r ω - v) / abs(v), with v the horizontal hub speed (measurement) –
slip_angle Slip angle, from the hub orientation (measurement) rad
camber_angle Camber angle, from the hub orientation (measurement) rad
steering_angle Steering angle, relative to the loaded configuration (measurement) rad
steering_actuator Steering actuator coordinate (0 without a steering actuator) actuator specific
wheel_force_x, wheel_force_y, wheel_force_z Terrain force on the wheel (measurement) N
wheel_moment_x, wheel_moment_y, wheel_moment_z Terrain moment on the wheel (measurement) N.m
drawbar_pull Drawbar pull, from the carrier motor force (measurement; 0 if the carrier is not actuated) N
drive_torque Wheel drive torque, from the wheel motor (measurement; 0 if the wheel is not actuated) N.m
wheel_angular_speed Wheel angular speed about its spin axis rad/s
carrier_speed Carrier longitudinal speed m/s
carrier_position Carrier longitudinal position m
hub_position_x, hub_position_y, hub_position_z Wheel hub position m
sinkage Wheel sinkage below the initial terrain surface, from the hub height m
suspension_travel Vertical hub displacement relative to the rig chassis, measured from the design configuration (wheel assemblies with a suspension only) m

An application-provided wheel assembly may append its own channels to this list.

Plots

If the plots key is present, Gnuplot plots of the output channels are generated at the end of the simulation. Plot generation requires the Chrono::Postprocess module and a Gnuplot installation.

Property Description Type Available Values Required Default
output Plot output: interactive Gnuplot windows, PNG images, or PDF files enum WINDOW,PNG,PDF No PNG
measuring_only Whether to plot only data recorded while rig measurements are enabled boolean – No true
figures List of figures array – Yes –

Each entry in figures is either a channel name, which plots that channel as a function of time, or an object with the following properties:

Property Description Type Available Values Required Default
y Ordinate channel or list of channels string or array – Yes –
x Abscissa channel string – No time
title Figure title string – No –
y_range Ordinate range [min, max] array[2] – No automatic

Channels are recorded at the output frequency (output.fps), even if no output database is written (output.format: NONE). For each figure, a Gnuplot script (plot_<n>.gpl) and, for PNG or PDF output, the plot (plot_<n>.png or plot_<n>.pdf) are written to the output directory. Unknown channel names are reported and skipped.

Visualization options

If the visualization key is present, it must specify a YAML object with the following properties:

Property Description Type Available Values Required Default
type Type of wheel assembly visualization shapes enum NONE,PRIMITIVES,MODEL_FILE,COLLISION No NONE
render_fps Rendering frequency (FPS or Hz) double – No 120
enable_shadows Turn on shadow rendering boolean – No true
camera Camera settings object – No –
output Image output settings object – No –

The camera follows the wheel hub. The camera key, if present, specifies the following properties:

Property Description Type Available Values Required Default
vertical Vertical direction (camera "up"); the rig requires Z enum Z No Z
offset Camera location relative to the wheel hub position (in the world frame) array[3] – No [2.0, 2.5, 1.0]
target_offset Camera look-at point relative to the wheel hub position (in the world frame) array[3] – No [0, 0.25, -0.25]

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

Property Description Type Available Values Required Default
save_images Whether to save rendered frames as image files boolean – No false
image_type Image file type, specified through the file extension string – No bmp

Run-time visualization is enabled only if the visualization key is present and specifies a type other than NONE. Rendering of SPH particles and BCE markers (CRM terrain) is specified in the terrain file. For deformable terrain, COLLISION shows the tire geometry that interacts with the terrain.

Running a wheel test rig simulation

A wheel test rig simulation can be run with the run_chrono program (see the YAML parser overview), for example:

./run_chrono -s ../data/yaml/vehicle/wheel_rig/wheel_suspension_rig_rigid.yaml

run_chrono can only create wheel assemblies specified through Chrono::Vehicle JSON files. A rig model with an application-provided (CUSTOM) wheel assembly requires a program that registers the corresponding factory with the ChParserWheelRigYAML parser before creating the rig (see the rig model schema). The demo_YAML_wheel_rig demo program illustrates this and allows selecting one of several wheel test rig specification files at run time.

Example

Below is an example of a wheel test rig simulation configuration, for a wheel with a steerable suspension on rigid terrain:

## Wheel with a steerable suspension on rigid terrain
chrono-version: 10.0
type: WHEEL_RIG
rig: "rig_model_hmmwv_front_tmeasy.yaml"
terrain: "terrain_rigid.yaml"
test:
angle_degrees: true
mode: TEST # SUSPEND, DROP, TEST
drop_speed: 0.05
time_delay: 1.0
#normal_load: 1000 # overrides the rig model normal load (N)
longitudinal_speed:
type: CONSTANT
value: 0.2
angular_speed: # 4.25 RPM (small longitudinal slip, about 2.5%)
type: CONSTANT
value: 0.4450589593
#slip_angle: # ignored with a suspension (use steering)
steering: # +-5 deg with a 5 s period, about the kingpin
input: ANGLE # ANGLE (through kinematic map), ACTUATOR (rack displacement in m)
function:
type: SINE
amplitude: 5
frequency: 0.2
feedback: # ANGLE input only; cancels bump and compliance steer
enabled: false
time_constant: 0.05
#steering:
# input: ACTUATOR
# function:
# type: SINE
# amplitude: 0.01
# frequency: 0.2
## Constant longitudinal slip (overrides longitudinal_speed and angular_speed)
#longitudinal_slip:
# value: 0.2
# base_speed: 0.1
simulation:
time_step: 2e-4 # rig step (FSI coupling step with CRM terrain); default: MBS solver step
end_time: 40 # negative for infinite end time
stop_at_patch_end: true # end the simulation when the wheel reaches the end of the patch
enforce_realtime: false
gravity: [0, 0, -9.8] # must be vertical: [0, 0, -g]
num_threads:
chrono: 8
collision: 1
eigen: 1
pardiso: 8
output:
format: ASCII # NONE, ASCII, HDF5
mode: SERIES # FRAMES, SERIES
fps: 100
plots:
output: PNG # WINDOW, PNG, PDF
measuring_only: true # plot only after the time delay
figures:
- y: [wheel_force_x, wheel_force_y, wheel_force_z]
title: Wheel forces
- y: [slip_angle, steering_angle, camber_angle]
title: Wheel angles
#y_range: [-0.1, 0.1]
- x: slip_angle
y: wheel_force_y
title: Lateral force vs. slip angle
- long_slip
- drawbar_pull
- drive_torque
- sinkage
- suspension_travel
visualization:
type: MODEL_FILE # MODEL_FILE, PRIMITIVES, COLLISION, NONE
render_fps: 100
enable_shadows: true
camera:
vertical: Z
offset: [2.0, 2.5, 1.0]
target_offset: [0, 0.25, -0.25]
output:
save_images: false
image_type: "bmp"

YAML schema

The YAML wheel test rig simulation specification file must follow the data/yaml/schema/wheel_rig_simulation.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 Chrono YAML WHEEL_RIG simulation specification file.
# A WHEEL_RIG simulation runs a Chrono::Vehicle single-wheel test rig (ChWheelTestRig).
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# A WHEEL_RIG simulation combines (paralleling a Chrono FSI simulation):
# rig - the rig mechanism: wheel assembly and rig properties, plus the MBS solver (wheel_rig_model.schema)
# terrain - the terrain: type, patch, and parameters, plus the SPH solver for CRM terrain (wheel_rig_terrain.schema)
# test - the test scenario: operation mode and motion functions
# coupling - wheel-terrain coupling settings (CRM terrain only)
# Rig, terrain, and test are independent, so that the same rig can be tested on different terrains and with
# different scenarios.
#
# =============================================================================
required: [chrono-version, type, rig, terrain, test, simulation]
chrono-version:
type: string
description: Chrono version compatible with this YAML 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
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 function of one variable (same as in mbs_model.schema)
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)], ...]
# -----------------------------------------------------------------------------
# Definition of a single-wheel test rig simulation
type:
description: Type of Chrono simulation (must be WHEEL_RIG)
type: string
value: WHEEL_RIG
rig:
description: |
Rig mechanism specification YAML file (wheel assembly, rig properties, and MBS solver).
The path must be provided relative to the location of this simulation specification file.
The file must follow the wheel_rig_model.schema.
type: string
terrain:
description: |
Terrain specification YAML file (terrain type, patch, parameters, and, for CRM terrain, the SPH solver).
The path must be provided relative to the location of this simulation specification file.
The file must follow the wheel_rig_terrain.schema.
type: string
test:
description: |
Test scenario: operation mode and motion functions.
Motion functions are functions of time, applied after `time_delay`.
Supported scenarios include:
driven wheel: angular_speed only
pulled wheel: longitudinal_speed only
immobilized wheel: longitudinal_speed and angular_speed both CONSTANT 0
fully prescribed: longitudinal_speed, angular_speed, and slip_angle (or steering, with a suspension)
constant slip: longitudinal_slip (overrides longitudinal_speed and angular_speed)
type: object
required: [mode]
properties:
angle_degrees:
type: boolean
description: |
Whether angles are specified in degrees (true) or radians (false).
Applies to the values of the `slip_angle` and `steering` (ANGLE input) functions.
default: true
mode:
type: string
description: |
SUSPEND: suspended wheel (locked spindle).
DROP: free wheel drop test.
TEST: wheel lowered onto the terrain at `drop_speed`, then motion functions applied.
Without a suspension, the drop phase ends when the wheel reaches the terrain. With a suspension,
the suspension travel is held at its loaded equilibrium and lowering continues until the tire
carries the normal load; the suspension is then released.
enum: [SUSPEND, DROP, TEST]
drop_speed:
type: number
description: Wheel lowering speed (m/s), TEST mode only
minimum: 0
default: 0.1
time_delay:
type: number
description: Settling time (s) before the motion functions are applied, measured from the end of the drop phase
minimum: 0
default: 0
normal_load:
type: number
description: |
Normal load on the wheel (N). If present, overrides `rig.normal_load` from the rig model file, e.g., to test
the same wheel assembly under different loads. With a suspension, the normal load sets the loaded
configuration and therefore the steering reference (see `steering`).
minimum: 0
longitudinal_speed:
<<: *FUNCTION
description: Rig carrier longitudinal speed (m/s) as a function of time; if absent, the carrier is not actuated
angular_speed:
<<: *FUNCTION
description: Wheel angular speed (rad/s) as a function of time; if absent, the wheel is not actuated
slip_angle:
<<: *FUNCTION
description: |
Wheel slip angle as a function of time (default: 0), in degrees or radians per `angle_degrees`.
Wheel without a suspension only (ignored otherwise; use `steering`).
steering:
type: object
description: |
Steering input (requires a wheel assembly with a steering actuator, e.g., a steerable suspension; ignored
otherwise, use `slip_angle` for a wheel without a suspension). The wheel is steered through the steering
mechanism of the assembly; for a Chrono::Vehicle steerable suspension, a rig steering rack to which the
suspension tierods are attached.
required: [input, function]
properties:
input:
type: string
description: |
ANGLE: wheel steering angle (degrees or radians per `angle_degrees`), relative to the loaded
configuration and positive to the left. Converted to the actuator coordinate through a kinematic
map computed at initialization, so bump and compliance steer are retained. A zero steering
angle retains the static toe of the suspension in the loaded configuration (in general different
from the design toe, because of bump steer), so the wheel may run at a non-zero slip angle; the
`slip_angle` output channel includes that toe, the `steering_angle` channel does not.
ACTUATOR: steering actuator coordinate, specific to the steering mechanism (for a Chrono::Vehicle
steerable suspension, the rack displacement in m along the rig lateral axis).
enum: [ANGLE, ACTUATOR]
function:
<<: *FUNCTION
description: Steering angle or actuator coordinate as a function of time
feedback:
type: object
description: |
Optional feedback correction of the actuator coordinate (ANGLE input only), driving the actual steering
angle to the specified one. Note that this cancels bump and compliance steer.
properties:
enabled:
type: boolean
default: false
time_constant:
type: number
description: Time constant of the feedback correction (s)
minimum: 0
default: 0.05
longitudinal_slip:
type: object
description: |
Constant longitudinal slip. Overrides `longitudinal_speed` and `angular_speed`.
A positive value indicates a spinning wheel; a negative value a sliding (skidding) wheel; -1 is
sliding without rotation.
required: [value]
properties:
value:
type: number
base_speed:
type: number
description: Base longitudinal speed (m/s) used to enforce the slip value
default: 1.0
coupling:
description: Wheel-terrain coupling settings
type: object
properties:
crm:
type: object
description: Coupling with CRM terrain (ignored for other terrain types)
properties:
active_domain:
type: object
description: |
CRM active domain attached to the wheel hub.
NONE: no active domain (the entire SPH domain is always active).
AUTO: box of estimated size (2.5 times the wheel assembly AABB).
BOX: box of the specified size, centered at the hub.
required: [type]
properties:
type:
type: string
enum: [NONE, AUTO, BOX]
default: NONE
size:
<<: *VECTOR3D
description: Box dimensions (BOX type only)
simulation:
description: Simulation settings
type: object
properties:
time_step:
type: number
description: |
Rig step (s): the interval over which the rig is advanced at each call.
With CRM terrain, this is the FSI coupling step: the multibody system (step from the MBS solver file) and the
SPH system (step from the SPH solver file) are each advanced over it and exchange data at its end.
For other terrain types, the multibody system is advanced over it with the step from the MBS solver file.
If omitted, the MBS solver step is used.
minimum: 0
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 an infinite end time.
default: -1
stop_at_patch_end:
type: boolean
description: |
Whether to end the simulation (before end_time) when the wheel reaches either end of the terrain patch, i.e.,
when the wheel hub is within one wheel radius of the patch boundary along the direction of travel.
Ignored for granular terrain, which uses a moving patch.
default: false
enforce_realtime:
type: boolean
description: Whether to enforce real-time simulation.
default: false
gravity:
<<: *VECTOR3D
description: |
Gravitational acceleration vector [x, y, z].
The test rig assumes a vertical (Z-up) world frame: only vectors of the form [0, 0, -g] with g >= 0 are
accepted. The magnitude g is passed to the rig, which uses it (together with the specified normal load) to
size the rig mass.
default: [0, 0, -9.8]
num_threads:
type: object
description: |
Number of threads used by the various parallel components.
Any entry that is omitted keeps its default value of 1.
properties:
chrono:
type: integer
description: Number of threads used by Chrono (e.g., SCM ray casting)
minimum: 1
default: 1
collision:
type: integer
description: Number of threads used by the collision detection system
minimum: 1
default: 1
eigen:
type: integer
description: Number of threads used by Eigen
minimum: 1
default: 1
pardiso:
type: integer
description: Number of threads used by the PARDISO solver (used only with the PARDISO solver type)
minimum: 1
default: 1
output:
description: Output settings
type: object
required: [format]
properties:
format:
type: string
description: Output DB format
enum: [NONE, ASCII, HDF5]
default: NONE
mode:
type: string
description: Output mode (one file per output frame, or a single time-series file)
enum: [FRAMES, SERIES]
default: FRAMES
fps:
type: number
description: Output frequency (FPS or Hz); also the sampling frequency of the data recorded for plots
minimum: 0
default: 100
plots:
description: |
Gnuplot plots generated at the end of the simulation from the rig output channels (requires Chrono::Postprocess
and Gnuplot). Channels are sampled at the output frequency (output.fps), even if no output database is written
(output.format NONE). For each figure, a Gnuplot script (plot_<n>.gpl) and, for PNG or PDF output, the plot image
(plot_<n>.png or plot_<n>.pdf) are written to the output directory.
Available channels: measuring, long_slip, slip_angle, camber_angle, steering_angle, steering_actuator,
wheel_force_x, wheel_force_y, wheel_force_z, wheel_moment_x, wheel_moment_y, wheel_moment_z, drawbar_pull,
drive_torque, wheel_angular_speed, carrier_speed, carrier_position, hub_position_x, hub_position_y, hub_position_z,
sinkage, suspension_travel (wheel assemblies with suspension only), plus any channels specific to a custom wheel
assembly. Quantities are in SI units, with angles in radians.
type: object
required: [figures]
properties:
output:
type: string
description: Plot output (interactive Gnuplot windows, PNG images, or PDF files)
enum: [WINDOW, PNG, PDF]
default: PNG
measuring_only:
type: boolean
description: If true, plot only data recorded while rig measurements are enabled (after the time delay)
default: true
figures:
type: array
description: |
List of figures. A figure is either a channel name (that channel as a function of time) or an object
specifying one or more channels as functions of time or of another channel.
items:
oneOf:
- type: string
description: Channel plotted as a function of time
- type: object
required: [y]
properties:
x:
type: string
description: Abscissa channel (default time)
y:
description: Ordinate channel or list of channels
oneOf:
- type: string
- type: array
items:
type: string
title:
type: string
description: Figure title
y_range:
type: array
description: Ordinate range [min, max] (default automatic)
items:
type: number
minItems: 2
maxItems: 2
visualization:
description: |
Run-time visualization settings.
Rendering of SPH particles and BCE markers (CRM terrain) is specified in the terrain file.
type: object
properties:
type:
type: string
description: |
Type of wheel assembly visualization shapes.
A value of NONE (the default) also disables run-time visualization altogether.
enum: [MODEL_FILE, PRIMITIVES, COLLISION, NONE]
default: NONE
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
description: Camera that follows the wheel hub
properties:
vertical:
type: string
description: Vertical axis for camera orientation (the rig requires Z)
enum: [Z]
default: Z
offset:
<<: *VECTOR3D
description: Camera location relative to the wheel hub position (in the world frame)
default: [2.0, 2.5, 1.0]
target_offset:
<<: *VECTOR3D
description: Camera look-at point relative to the wheel hub position (in the world frame)
default: [0, 0.25, -0.25]
output:
type: object
description: Run-time visualization image output
properties:
save_images:
type: boolean
description: Whether to save rendered frames as image files
default: false
image_type:
type: string
description: Image file type, specified through the file extension
default: bmp