The terrain of a wheel test rig simulation is specified in a separate file, independent of the rig mechanism and of the test scenario. Depending on the terrain type, this file is either:

a wheel test rig terrain file, following the schema described on this page, for RIGID, SCM, or GRANULAR terrain; or
a Chrono::FSI-SPH simulation file for CRM terrain (see CRM terrain below), which uses exactly the same SPH simulation, model, and solver schemas as an FSI simulation.

A wheel test rig terrain file 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, or granular).

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`

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` terrain only	double	–	No	0

For all terrain types (including CRM), 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/m³)	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

CRM (Continuum Representation Model) terrain is specified through a Chrono::FSI-SPH simulation file (type: SPH), following the FSI-SPH simulation schema, which references an SPH model file (FSI-SPH model schema) and an SPH solver file (FSI-SPH solver schema). The same files can therefore be used in FSI and wheel test rig simulations. The SPH model must use CRM physics (physics_problem: CRM) and a Cartesian box fluid domain (geometry_type: CARTESIAN, no wave tank).

The parts of these specifications that apply to a test rig terrain are used as follows:

Specification	Use for a test rig terrain
model `soil_properties`	CRM soil properties, including the parameters of the MCC rheology model
model `fluid_domain.dimensions`	Patch length, width, and depth
model `fluid_domain.box_walls`	Patch sides with boundary walls; if no walls are specified, all sides but the top
model `initial_states.depth_based_pressure`	Initialize particle pressures from their depth below the patch surface
solver file	SPH solver settings; the particle spacing is set by `kernel.initial_spacing` and the SPH (CFD) step size by `integration.time_step`
simulation `visualization`	Rendering of SPH particles and BCE markers

The following parts are ignored, since the test rig places the patch relative to the wheel and the simulation settings are specified in the wheel test rig simulation file:

Specification	Reason
model `fluid_domain.box_origin`	The rig places the patch relative to the wheel
model `initial_states.zero_height`	Pressures are zero at the patch surface
model `initial_states.initial_velocity`	The terrain is initially at rest
model `container`, `computational_domain`	The rig defines the patch boundaries and the computational domain
simulation `simulation`, `output`	Set in the wheel test rig simulation file

A note is printed for ignored model settings that are present. Note that 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 wheel test rig simulation file.

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 (an SPH simulation file):

## CRM deformable terrain patch, specified as a Chrono::FSI-SPH simulation (follows fsisph_simulation.schema).
## As a wheel test rig terrain, only the model, solver, and SPH visualization settings are used;
## the simulation and output settings come from the wheel rig simulation file.
 
chrono-version: 10.0
 
type: SPH
 
model: "terrain_crm_model.yaml"
solver: "terrain_crm_solver.yaml"
 
visualization:
  sph_markers: true
  bndry_bce_markers: true
  rigid_bce_markers: true
  #color_map:
  #  type: HEIGHT                  # NONE, HEIGHT, VELOCITY, DENSITY, PRESSURE
  #  map: BROWN
  #  min: -0.2
  #  max: 0.0

with the SPH model file it references:

## SPH model for the wheel test rig CRM terrain (follows fsisph_model.schema).
## The fluid domain dimensions set the terrain patch size. The test rig places the patch relative to the wheel,
## so the fluid domain box_origin is ignored, as are any container and computational domain settings.
 
chrono-version: 10.0
 
model:
  name: CRM terrain
  physics_problem: CRM
  geometry_type: CARTESIAN
 
  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
 
  initial_states:
    depth_based_pressure: false   # zero pressure at the patch surface (zero_height is ignored)
 
  fluid_domain:
    dimensions: [10, 1, 0.2]      # patch length, width, and depth
    box_walls:                    # boundary walls on all sides but the top
      x: [true, true]             # negative, positive
      y: [true, true]             # negative, positive
      z: [true, false]            # negative, positive

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 (RIGID, SCM, or GRANULAR terrain).
# This is the "terrain" side of a WHEEL_RIG simulation (see wheel_rig_simulation.schema).
# CRM terrain is not specified with this schema, but through a Chrono::FSI-SPH simulation file (fsisph_simulation.schema),
# which references an SPH model file (fsisph_model.schema) and an SPH solver file (fsisph_solver.schema).
# 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]
 
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 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