Menu
Create rigid terrain patches, SCM (Bekker-Wong soft-soil) terrain, and CRM (SPH) terrain for wheeled vehicle simulations.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Entry point for FSI-coupled hybrid plans (plan_type=fsi_in_scene) — any scene combining SPH fluid (water tanks, dam-break, wave channels) with multi-body dynamics, optionally with a wheeled vehicle. Pick this over mbs_in_scene whenever the plan involves a fluid domain (scene_objects with domain_type starting "sph_") or an FSI body registration (scene_objects with fsi_registration set). Routes to fsi/sph (always), veh/wheeled_vehicle (when vehicle present), and enforces FSI-specific invariants distinct from generic mbs_in_scene rigid scenes.
Entry point for rigid-body hybrid plans (plan_type=mbs_in_scene) combining a robot or vehicle with scene assets — NO fluid coupling. Routes to the correct domain skills and defines only high-level invariants. Use core/fsi_in_scene instead when the plan involves SPH fluid or FSI body registration.
Entry point for pure multi-body simulation plans (plan_type=mbs). Routes the agent to the correct mechanics, system, and camera skills and defines only high-level invariants.
Entry point for static scene plans (plan_type=scene). Routes the agent to the correct scene, system, and camera skills and defines only high-level invariants.
Set up SPH-based Fluid-Structure Interaction (FSI): create ChFsiFluidSystemSPH and ChFsiSystemSPH, configure fluid and SPH parameters, seed fluid particles with hydrostatic initialization, add container BCE boundary markers, register floating rigid bodies, optionally couple with a wheeled vehicle, and advance with sysFSI.DoStepDynamics(dT).
Translate a `geometry_relations` entry from the plan into correct PyChrono coordinate code. Read this whenever the plan declares a relation_name you have not previously encoded, and especially BEFORE writing SetPos / camera placement for any body that participates in a multi-body geometric constraint. Each subsection below is one canonical pattern named exactly as it appears in `plan.geometry_relations[i].relation_name`.
| name | terrain |
| description | Create rigid terrain patches, SCM (Bekker-Wong soft-soil) terrain, and CRM (SPH) terrain for wheeled vehicle simulations. |
| compatibility | pychrono >= 8.0 |
| metadata | {"domain":"veh"} |
Create the terrain surface under a wheeled vehicle. Three flavors, from cheap to physically rich:
| Flavor | API | Physics | Cost | Use when |
|---|---|---|---|---|
| RigidTerrain | veh.RigidTerrain | Flat / heightmap rigid body, Bullet contacts | Low | Fast demos, paved roads, baseline sanity |
| SCMTerrain | veh.SCMTerrain | Bekker-Wong empirical soft soil, deformable grid | Medium | Off-road ruts, sinkage, deformation without SPH cost |
| CRMTerrain | veh.CRMTerrain | SPH continuum (elastic granular) | High | Splashing particles, large deformation, needs GPU |
When the user asks to simulate a vehicle driving on terrain — required for any wheeled vehicle simulation. Pick the flavor by the user's physics requirement; if unsure, SCM is the recommended default for off-road scenes.
terrain = veh.RigidTerrain(veh_obj.GetSystem())
# NSC material
patch_mat = chrono.ChContactMaterialNSC()
patch_mat.SetFriction(0.9)
patch_mat.SetRestitution(0.01)
# SMC material
patch_mat = chrono.ChContactMaterialSMC()
patch_mat.SetFriction(0.9)
patch_mat.SetRestitution(0.01)
patch_mat.SetYoungModulus(2e7)
# Add patch (flat ground)
patch = terrain.AddPatch(
patch_mat,
chrono.CSYSNORM, # centered at origin, no rotation
terrainLength, # X direction size
terrainWidth # Y direction size
)
# Visual
patch.SetTexture(veh.GetVehicleDataFile("terrain/textures/tile4.jpg"), 200, 200)
patch.SetColor(chrono.ChColor(0.8, 0.8, 0.5))
terrain.Initialize()
| Parameter | Typical Value | Description |
|---|---|---|
| Friction | 0.8 - 0.9 | Friction coefficient |
| Restitution | 0.01 | Bounciness |
| YoungModulus | 2e7 | SMC only - stiffness |
SCMTerrain is a deformable soft-soil model suitable for off-road driving — wheels sink into the surface and leave visible ruts. Cheaper than CRM (no SPH particles) but richer than RigidTerrain.
CRITICAL: The ChSystem MUST have a collision system BEFORE constructing SCMTerrain.
SCMTerrain's constructor checks for an associated collision system and raises RuntimeError if none is found.
If you are creating the system yourself (not via a vehicle wrapper):
sys.SetCollisionSystemType(chrono.ChCollisionSystem.Type_BULLET)
# MUST be called BEFORE constructing SCMTerrain
If using a vehicle wrapper (hmmwv.Initialize() etc.), the vehicle sets up the collision system automatically — no extra call needed. But never call SetCollisionSystemType() AFTER hmmwv.Initialize() (see Pitfalls below).
terrain = veh.SCMTerrain(system) # takes the vehicle's ChSystem
Signature: SetSoilParameters(Bekker_Kphi, Bekker_Kc, Bekker_n, Mohr_cohesion, Mohr_friction, Janosi_shear, elastic_K, damping_R)
terrain.SetSoilParameters(
2e6, # Bekker_Kphi — frictional modulus (Pa)
0, # Bekker_Kc — cohesive modulus
1.1, # Bekker_n — exponent (1.0 soft → 1.5 hard)
0, # Mohr_cohesion — cohesive limit (Pa)
30, # Mohr_friction — friction angle (deg)
0.01, # Janosi_shear — shear coefficient (m)
2e8, # elastic_K — elastic stiffness (Pa/m)
3e4, # damping_R — vertical damping (Pa·s/m)
)
Exactly 8 positional args are required — no keyword form. Do not omit damping_R (8th arg) and do not add a 9th.
SCM does a ray-cast per grid vertex per step. A 120×120 m patch at 5 cm resolution is ~6 million vertices and will grind the sim. Attach an active domain so only cells near the vehicle are updated.
CRITICAL: Attach active domain to the CHASSIS body, NOT to wheel spindles.
SCM's UpdateActiveDomain() projects the OOBB using the reference body's orientation (SCMTerrain.cpp:957-1001). Wheel spindles rotate at hundreds of RPM — the OOBB rotates with them, causing the projected terrain range to become empty at many rotation angles. Result: rays=0, zero deformation, no ruts.
# CORRECT — chassis body stays level, stable OOBB projection
terrain.AddActiveDomain(
hmmwv.GetChassisBody(),
chrono.ChVector3d(0, 0, 0), # local centre offset
chrono.ChVector3d(5, 3, 1), # half-extents (m)
)
# WRONG — spindle rotates, OOBB becomes degenerate → rays=0
for axle in hmmwv.GetVehicle().GetAxles():
terrain.AddActiveDomain(
axle.m_wheels[0].GetSpindle(), # DO NOT USE
chrono.ChVector3d(0, 0, 0),
chrono.ChVector3d(1.5, 1.0, 1.5),
)
terrain.Initialize(120.0, 120.0, 0.1)
# length (m), width (m), grid resolution (m).
# 0.1 m grid is a good balance for performance with visible ruts.
# 0.05 m gives finer ruts but 4× more vertices and ray-cast cost.
terrain.SetMeshWireframe(False)
terrain.SetTexture(
chrono.GetChronoDataFile("vehicle/terrain/textures/dirt.jpg"),
80, 80, # UV tiling
)
SCM detects tire contact via ChCollisionSystem::RayHit() — it casts rays from each grid vertex and looks for collision shapes. Rigid tires add their own collision geometry automatically. TMEASY / PAC02 / FIALA tires do NOT — you must add explicit collision cylinders to each spindle.
tire_rad = hmmwv.GetVehicle().GetAxles()[0].m_wheels[0].GetTire().GetRadius()
tire_w = hmmwv.GetVehicle().GetAxles()[0].m_wheels[0].GetTire().GetWidth()
tire_mat = chrono.ChContactMaterialSMC()
tire_mat.SetFriction(0.9)
tire_mat.SetRestitution(0.1)
TIRE_FAMILY = 1
SUPPORT_FAMILY = 4
for axle in hmmwv.GetVehicle().GetAxles():
for iw in range(2):
spindle = axle.m_wheels[iw].GetSpindle()
spindle.AddCollisionShape(
chrono.ChCollisionShapeCylinder(tire_mat, tire_rad + 0.04, tire_w),
chrono.ChFramed(chrono.VNULL, chrono.QuatFromAngleX(math.pi / 2)),
)
spindle.EnableCollision(True)
sp_cm = spindle.GetCollisionModel()
sp_cm.SetFamily(TIRE_FAMILY)
sp_cm.DisallowCollisionsWith(TIRE_FAMILY)
sp_cm.DisallowCollisionsWith(SUPPORT_FAMILY)
# MANDATORY: rebuild all collision models after post-init shape changes
system.GetCollisionSystem().BindAll()
Three critical rules for tire collision cylinders:
Rule 1 — Use tire_rad + 0.04 not tire_rad. The extra 4 cm ensures the collision cylinder extends slightly below the terrain surface at the TMEASY equilibrium spindle height, guaranteeing SCM detects sinkage.
Rule 2 — NEVER call DisallowCollisionsWith(0) (family 0). Bullet's RayHit() queries use family 0 by default. If you disallow family 0 on the tire cylinder, SCM's ray-casts are filtered out → hits=0 → no ruts form. Chassis-tire non-collision should be handled on the chassis side (via add_collision_via_subbodies(tire_family=TIRE_FAMILY)), not on the tire side.
Rule 3 — Call collsys.BindAll() after adding shapes. The per-model Remove()/BindItem() path does NOT work — BindItem() checks HasImplementation() and silently skips models that are already bound. BindAll() forces Bullet to rebuild all collision models, making the new cylinders visible to ray-casts.
SCM is a depth-based deformable surface, not a general rigid ground. Dynamic props (rocks, cottage) placed on the terrain will free-fall through z=0. Add a hidden rigid support plane:
support_mat = make_contact_material(
friction=0.9, restitution=0.01, method="SMC", young_modulus=2e7,
)
support = chrono.ChBodyEasyBox(120.0, 120.0, 0.2, 1000, False, True, support_mat)
support.SetName("asset_support_ground")
support.SetPos(chrono.ChVector3d(0, 0, -0.1)) # top at z=0 (SCM rest plane)
support.SetFixed(True)
support.EnableCollision(True)
support_cm = support.GetCollisionModel()
support_cm.SetFamily(SUPPORT_FAMILY)
support_cm.DisallowCollisionsWith(TIRE_FAMILY) # tires ride on SCM, not support
support_cm.DisallowCollisionsWith(CHASSIS_FAMILY) # chassis rides on SCM
support_cm.DisallowCollisionsWith(3) # chassis sub-body family
system.AddBody(support)
Not available in VSG — VSG shows geometric deformation directly. Do not call SetPlotType; it is an Irrlicht-only API and is not supported.
terrain.Initialize(heightmap_path, scm_size, scm_size,
-pool_depth, 0.0, scm_resolution)
# heightmap: 16-bit PNG, white=max height, black=min height
# min_z, max_z: height range mapping
SCM uses the standard terrain synchronize/advance pattern:
terrain.Synchronize(time)
terrain.Advance(step_size)
# Pass terrain into vehicle.Synchronize so the wheels sample it
hmmwv.Synchronize(time, driver_inputs, terrain)
| Symptom | Cause | Fix |
|---|---|---|
Chassis doesn't translate at any throttle, GetSpeed() oscillates around 0 | TireModelType_RIGID (the HMMWV_Full default) on SCM — no slip/grip curve, wheels break loose under engine torque | SetTireType(TireModelType_TMEASY) + SetTireStepSize(step) + add spindle cylinders (next row). Do not try to rescue with stiffer soil / higher cohesion — the failure is structural. See veh/wheeled_vehicle/SKILL.md "Picking a tire type by terrain". |
rays=0 | Active domain on rotating spindle | Use chassis body for AddActiveDomain |
hits=0 (rays > 0) | DisallowCollisionsWith(0) on tire | Remove that call; handle on chassis side |
hits=0 (rays > 0) | Missing BindAll() after shape changes | Call collsys.BindAll() after adding tire cylinders |
patches=0 (hits > 0) | Collision cylinder too small | Use tire_rad + 0.04 not tire_rad |
| No ruts with TMEASY | No tire collision cylinders | Add explicit ChCollisionShapeCylinder to each spindle |
| Want "colored" C++-style ruts (sinkage heatmap) | SetPlotType is Irrlicht-only, silently a no-op in VSG | VSG only shows geometric mesh deformation. Accept it, or port to Irrlicht vis (big rewrite). Do not call SetPlotType under VSG. |
| Props fall through z=0 | No rigid support plane | Add hidden ChBodyEasyBox at z=-0.1 |
Do NOT call SetCollisionSystemType() after hmmwv.Initialize() | Creates new collision system, leaves dangling impl pointers on all HMMWV bodies — BindAll() skips them | Trust the collision system HMMWV already created; only call BindAll() on it |
For realistic wheel-soil interaction with deformable terrain:
from pychrono.fsi import (
ChFsiFluidSystemSPH, ChFsiSystemSPH,
ElasticMaterialProperties, SPHParameters,
IntegrationScheme_RK2, ViscosityMethod_ARTIFICIAL_BILATERAL,
BoundaryMethod_ADAMI, OutputLevel_STATE
)
# Create CRM terrain
initial_spacing = 0.03
terrain = veh.CRMTerrain(system, initial_spacing)
# Configure FSI system
sysFSI = terrain.GetFsiSystemSPH()
sysSPH = terrain.GetFluidSystemSPH()
sysSPH.EnableCudaErrorCheck(False)
terrain.SetVerbose(verbose)
terrain.SetGravitationalAcceleration(chrono.ChVector3d(0, 0, -9.81))
terrain.SetStepSizeCFD(step_size)
# Elastic material properties
mat_props = ElasticMaterialProperties()
mat_props.density = 1700
mat_props.Young_modulus = 1e6
mat_props.Poisson_ratio = 0.3
mat_props.mu_I0 = 0.04
mat_props.mu_fric_s = 0.7
mat_props.mu_fric_2 = 0.7
mat_props.average_diam = 0.005
mat_props.cohesion_coeff = 5e3
terrain.SetElasticSPH(mat_props)
# SPH parameters
sph_params = SPHParameters()
sph_params.integration_scheme = IntegrationScheme_RK2
sph_params.initial_spacing = initial_spacing
sph_params.free_surface_threshold = 0.8
sph_params.artificial_viscosity = 0.5
sph_params.viscosity_method = ViscosityMethod_ARTIFICIAL_BILATERAL
sph_params.boundary_method = BoundaryMethod_ADAMI
sph_params.use_variable_time_step = True
terrain.SetSPHParameters(sph_params)
terrain.SetOutputLevel(OutputLevel_STATE)
terrain.Initialize()
terrain.Construct(
chrono.ChVector3d(length, width, 0.25), # dimensions
chrono.ChVector3d(length / 2, 0, 0), # center
BoxSide_ALL & ~BoxSide_Z_POS # all boundaries except top
)
terrain.Construct(
veh.GetVehicleDataFile("terrain/height_maps/bump64.bmp"), # image file
terrain_length,
terrain_width,
chrono.ChVector2d(0.25, 0.55), # height range [min, max]
0.25, # depth
True, # uniform depth
chrono.ChVector3d(terrain_length / 2, 0, 0), # center
BoxSide_Z_NEG # bottom wall
)
terrain.Synchronize(time)
terrain.Advance(step_size)
# In vehicle sync, pass terrain as argument
veh_obj.Synchronize(time, driver_inputs, terrain)
aabb = terrain.GetSPHBoundingBox()
num_sph = terrain.GetNumSPHParticles()
num_bce = terrain.GetNumBoundaryBCEMarkers()
print(f"SPH particles: {num_sph}")
print(f"AABB: {aabb.min} to {aabb.max}")
For vehicle setup and system creation:
../../mbs/system_create/ — ChSystem creation../../mbs/collision/ — Contact materials../wheeled_vehicle/ — Vehicle creation../driver/ — Driver systemsallowed_classes:
allowed_methods:
allowed_constants:
allowed_utils: