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

A Chrono YAML wheel test rig terrain file defines the terrain of a wheel test rig simulation: the terrain type, the dimensions of the terrain patch, and the terrain parameters. It is independent of the rig mechanism and of the test scenario. For CRM terrain, it plays the role of the fluid specification in an FSI simulation, with the soil properties specified here and the SPH solver in a separate file. 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 terrain type.
  • [required] The patch object, which specifies the dimensions of the terrain patch.
  • [optional] The terrain parameter object matching the terrain type (rigid, scm, granular, or crm).

Terrain type and patch

type Terrain Parameter object
RIGID Rigid terrain patch rigid
SCM Soil Contact Model (SCM) deformable terrain scm
GRANULAR Granular terrain, made of rigid spheres granular
CRM Continuum Representation Model (CRM) deformable terrain, using SPH crm (required)

Only the parameter object matching the terrain type is read; the others are ignored. Parameters that are not specified take their default values.

The patch object specifies the following properties:

Property Description Type Available Values Required Default
length Patch length (m), along the direction of travel double – Yes –
width Patch width (m) double – Yes –
depth Patch depth (m), GRANULAR and CRM terrain only double – No 0

The terrain patch is placed by the rig relative to the wheel: its surface is 0.1 m below the wheel (with a suspension, in the loaded configuration) and it starts 2 wheel radii behind the initial wheel location, extending along the positive X axis. With a test longitudinal speed, the patch length therefore determines the duration of a test (see the stop_at_patch_end simulation option). Granular terrain uses a moving patch, which is relocated ahead of the wheel as the wheel advances.

Rigid terrain

The rigid key, if present, specifies the contact material of the terrain patch:

Property Description Type Available Values Required Default
friction Coefficient of friction double – No 0.8
restitution Coefficient of restitution double – No 0
Young_modulus Young's modulus (Pa), used with SMC contact double – No 2e7

SCM terrain

The scm key, if present, specifies the soil parameters of the SCM terrain:

Property Description Type Available Values Required Default
Bekker_Kphi Frictional modulus in the Bekker model double – No 2e6
Bekker_Kc Cohesive modulus in the Bekker model double – No 0
Bekker_n Exponent of sinkage in the Bekker model (usually 0.6 to 1.8) double – No 1.1
Mohr_cohesion Cohesion for shear failure (Pa) double – No 50
Mohr_friction Friction angle for shear failure, always in degrees double – No 20
Janosi_shear Shear parameter J in the Janosi-Hanamoto formula (m) double – No 0.01
grid_spacing SCM grid spacing (m) double – No 0.125
visualize_mesh Whether to create the SCM visualization mesh boolean – No true

The rig attaches an SCM active domain to the rig chassis, so that terrain deformation is only computed near the wheel. The visualization mesh can be disabled for a run without run-time visualization.

Granular terrain

The granular key, if present, specifies the particle parameters of the granular terrain:

Property Description Type Available Values Required Default
radius Particle radius (m) double – No 0.02
density Particle density (kg/m3) double – No 2000
friction Coefficient of friction double – No 0.9
cohesion Inter-particle cohesion pressure (Pa) double – No 0
Young_modulus Young's modulus (Pa), used with SMC contact double – No 1e7

The number of particle layers is set by the patch depth. Note that a granular terrain consists of many sphere bodies and practical run times require a Chrono::Multicore system, which is not yet supported by the wheel test rig YAML parser.

CRM terrain

The crm key (required for CRM terrain) specifies the following properties:

Property Description Type Available Values Required Default
soil_properties Soil properties object – No –
solver SPH solver specification file string – Yes –
visualization Rendering of SPH particles and BCE markers object – No –

The soil_properties object has the same keys and defaults as model.soil_properties in the FSI-SPH model schema, including the parameters of the MCC rheology model.

The solver entry must specify the path (relative to the location of this YAML file) to the YAML file with an SPH solver specification, which must follow the FSI-SPH solver schema. Values not specified there take the defaults of that schema. The SPH particle spacing is set by kernel.initial_spacing and the SPH (CFD) step size by integration.time_step. The multibody step size is set in the MBS solver file of the rig model, and the FSI coupling step by simulation.time_step in the simulation file.

The visualization object has the same settings as the visualization object of the FSI-SPH simulation schema. The most commonly used ones are:

Property Description Type Available Values Required Default
sph_markers Render SPH particles boolean – No true
bndry_bce_markers Render boundary BCE markers boolean – No false
rigid_bce_markers Render BCE markers on rigid solids boolean – No true

The SPH domain spans the entire terrain patch. An active domain attached to the wheel, which restricts the SPH computation to the vicinity of the wheel, can be specified through coupling.crm.active_domain in the simulation file.

Examples

Below is an example of an SCM terrain specification:

## SCM deformable terrain patch
chrono-version: 10.0
type: SCM
patch:
length: 10
width: 1
scm:
Bekker_Kphi: 2e6
Bekker_Kc: 0
Bekker_n: 1.1
Mohr_cohesion: 0
Mohr_friction: 30 # degrees
Janosi_shear: 0.01
grid_spacing: 0.05
visualize_mesh: true

Below is an example of a CRM terrain specification:

## CRM deformable terrain patch
chrono-version: 10.0
type: CRM
patch:
length: 10
width: 1
depth: 0.2
crm:
soil_properties:
density: 1700
Young_modulus: 2e6
cohesion_coefficient: 1e2
#Poisson_ratio: 0.3
#mu_I0: 0.03
#mu_fric_s: 0.7
#mu_fric_2: 0.7
#average_diam: 0.005
#rheology_model: MU_OF_I # MU_OF_I, MCC
#mcc_M: 1.2 # MCC only
#mcc_kappa: 0.00625 # MCC only
#mcc_lambda: 0.025 # MCC only
#mcc_v_lambda: 2.0 # MCC only
solver: "terrain_crm_solver.yaml"
visualization:
sph_markers: true
bndry_bce_markers: true
rigid_bce_markers: true

YAML schema

The YAML wheel test rig terrain specification file must follow the data/yaml/schema/wheel_rig_terrain.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 terrain specification file.
# This is the "terrain" side of a WHEEL_RIG simulation (see wheel_rig_simulation.schema). For CRM terrain, it plays
# the role of the fluid specification in an FSI simulation: soil properties here, SPH solver in a separate file.
# The terrain patch is placed by the rig relative to the wheel.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
required: [chrono-version, type, patch]
chrono-version:
type: string
description: Chrono version compatible with this YAML specification (M.m or M.m.p)
# -----------------------------------------------------------------------------
# Terrain type and patch
type:
description: |
Terrain type.
Only the parameter object matching the type is read (e.g., `scm` for type SCM); the others are ignored.
type: string
enum: [RIGID, SCM, GRANULAR, CRM]
patch:
type: object
description: Terrain patch dimensions
required: [length, width]
properties:
length:
type: number
minimum: 0
width:
type: number
minimum: 0
depth:
type: number
description: Patch depth (used by GRANULAR and CRM terrain only)
minimum: 0
default: 0
# -----------------------------------------------------------------------------
# Terrain parameters
rigid:
type: object
description: Contact material for RIGID terrain
properties:
friction:
type: number
minimum: 0
default: 0.8
restitution:
type: number
minimum: 0
maximum: 1
default: 0
Young_modulus:
type: number
description: Young's modulus (Pa), used with SMC contact
minimum: 0
default: 2e7
scm:
type: object
description: Soil parameters for SCM terrain
properties:
Bekker_Kphi:
type: number
description: Frictional modulus in Bekker model
default: 2e6
Bekker_Kc:
type: number
description: Cohesive modulus in Bekker model
default: 0
Bekker_n:
type: number
description: Exponent of sinkage in Bekker model (usually 0.6...1.8)
default: 1.1
Mohr_cohesion:
type: number
description: Cohesion for shear failure (Pa)
default: 50
Mohr_friction:
type: number
description: Friction angle for shear failure, always in degrees
default: 20
Janosi_shear:
type: number
description: Shear parameter J in Janosi-Hanamoto formula (m)
default: 0.01
grid_spacing:
type: number
description: SCM grid spacing
minimum: 0
default: 0.125
visualize_mesh:
type: boolean
description: Whether to create the SCM visualization mesh
default: true
granular:
type: object
description: |
Particle parameters for GRANULAR terrain.
A granular terrain consists of many sphere bodies; practical run times require a Chrono::Multicore system, which
is not yet supported by the wheel test rig YAML parser.
properties:
radius:
type: number
minimum: 0
default: 0.02
density:
type: number
minimum: 0
default: 2000
friction:
type: number
minimum: 0
default: 0.9
cohesion:
type: number
description: Inter-particle cohesion pressure (Pa)
minimum: 0
default: 0
Young_modulus:
type: number
description: Young's modulus (Pa), used with SMC contact
minimum: 0
default: 1e7
crm:
type: object
description: Parameters for CRM (SPH continuum) terrain
required: [solver]
properties:
soil_properties:
type: object
description: |
Soil properties, with the same keys and defaults as `model.soil_properties` in fsisph_model.schema
(including the MCC rheology parameters).
solver:
type: string
description: |
SPH solver specification YAML file, following the fsisph_solver.schema, with the path relative to this file.
Values not specified there take the fsisph_solver.schema defaults. The SPH particle spacing is set by
`kernel.initial_spacing` and the SPH (CFD) step size by `integration.time_step`.
visualization:
type: object
description: |
Rendering of SPH particles and BCE markers. Same settings as the `visualization` object of the
fsisph_simulation.schema; only the most commonly used ones are listed here.
properties:
sph_markers:
type: boolean
description: Render SPH particles
default: true
bndry_bce_markers:
type: boolean
description: Render boundary BCE markers
default: false
rigid_bce_markers:
type: boolean
description: Render BCE markers on rigid solids
default: true