Tyre and Soil

This page gives the tyre and soil model of the vehicles: the soil library, the surface selection, the sinkage, the tyre forces and the ruts. The Maxxum and the Polaris use the same functions with different parameters.

Scope and Assumptions

The model computes the forces of one tyre on the ground in each physics step. The inputs are the wheel load, the wheel speed, the speed of the contact point and the state of the ground. The outputs are the sinkage, the longitudinal force, the lateral force, the rolling resistance torque and the rut depth. The source files are AcresSoilModel.cpp, AcresVehicleModel.cpp and AcresSurfaceMap.cpp. These files are engine-free models.

The quantities of one tyre contact on deformable soil. Open the diagram

The game has three ground models.

Model	Condition	Content
Soil library	The surface is deformable and a soil class is active.	Seven soil classes, moisture and density effects, an inflated tyre. This is the default.
Legacy soil	The surface is deformable and the key soil.class is absent.	One fixed Bekker soil with a rigid footprint.
Hard surface	The surface is not deformable.	A friction curve and a rolling resistance coefficient.

The model makes these assumptions.

• The soil state is constant through the depth of the surface layer. The soil water model gives one water content for a layer of 0.3 m.
• A tyre contact is one patch with one mean ground pressure. The model does not compute a pressure distribution.
• The soil keeps no shear history. A rut changes the density and the sinkage only.
• The lateral force is a linear function of the slip angle. The tyre has no camber force and no aligning torque.
• The lateral force has priority in the friction circle. The longitudinal force gets the remainder.
• The parameters of the soil classes are typical values from the literature. They are not measurements of ACRE soils.

Symbols

Symbol	Quantity	Unit
\(N\)	Wheel load, normal to the ground	N
\(N_0\)	Static wheel load	N
\(b\)	Tyre section width	m
\(r\)	Unloaded tyre radius	m
\(p_i\), \(p_c\)	Inflation pressure and carcass pressure	Pa
\(p_g\)	Ground pressure below the flat part of the tyre, \(p_i + p_c\)	Pa
\(\delta\)	Tyre deflection	m
\(\theta\)	Volumetric water content of the soil	m³/m³
\(\theta_r\), \(\theta_s\)	Residual and saturated water content	m³/m³
\(S_e\)	Effective saturation	-
\(w\)	Gravimetric water content	kg/kg
\(\rho\)	Dry bulk density of the soil	Mg/m³
\(\rho_l\), \(\rho_f\), \(\rho_m\)	Loose, firm and maximum density of a soil class	Mg/m³
\(\gamma\)	Moist unit weight of the soil	N/m³
\(\psi\)	Matric suction	Pa
\(\sigma_s\)	Suction stress	Pa
\(c'\), \(\phi'\)	Drained cohesion and friction angle	Pa, rad
\(c_d\)	Drained cohesion with the suction stress	Pa
\(c_u\)	Undrained strength	Pa
\(f_u\)	Undrained share	-
\(\tau(\sigma)\)	Shear strength at the normal stress \(\sigma\)	Pa
\(k_c\), \(k_\phi\), \(n\)	Bekker moduli and sinkage exponent	N/m^(n+1), N/m^(n+2), -
\(k\)	Bekker modulus for the tyre width, \(k_c / b + k_\phi\)	Pa/m^n
\(K\)	Shear deformation modulus (Janosi-Hanamoto)	m
\(CI\)	Cone index	Pa
\(\mu_r\), \(c_a\)	Friction and adhesion between rubber and soil	-, Pa
\(\xi\)	Surface wetness	-
\(z_0\)	Sinkage of a rigid wheel	m
\(z_s\), \(z_j\)	Sinkage without slip and with slip	m
\(z_{rut}\)	Depth of the rut at the contact point	m
\(l_f\), \(l\)	Length of the flat part and length of the contact	m
\(A\), \(p\)	Contact area and mean ground pressure	m², Pa
\(H\)	Shear capacity of the contact	N
\(F_s\)	Shear force of the soil on the tyre (thrust)	N
\(R_c\), \(R_b\)	Compaction resistance and bulldozing resistance	N
\(F_x\), \(F_y\)	Longitudinal and lateral force on the chassis	N
\(\omega\)	Wheel speed	rad/s
\(v_x\), \(v_y\)	Speed of the contact point along the wheel heading and to its right	m/s
\(s\)	Longitudinal slip	-
\(j\)	Shear displacement at the middle of the contact	m
\(h_r\)	Relaxation length of the shear displacement	m
\(\alpha\)	Slip angle	rad
\(\mu\)	Grip ratio, \(H / N\) on soil and the friction coefficient on a hard surface	-
\(\Delta t\)	Physics step, 1/120	s

Surface under a Wheel

The function AAcresVehiclePawn::SampleSurface selects a surface template for each wheel in each physics step. A template is one entry of the block surfaces in tractor.json. The selection uses this sequence.

1. A surface that the user selects has priority. The keys 1 to 6 and the option -VehicleSurface= select it.
2. If not, the surface is mapped. The key 0 selects mapped again.
3. On the ACRE map, the surface map gives the class of the polygon at the contact point.
4. Without the surface map file, the survey grid surfaces.u8 gives the surface of the cell.
5. On other maps, a road mask selects gravel or dry_soil.

The surface map is the file Content/Simulation/ACRE/surface_polygons.json. The class FSurfaceMap puts its 521 polygons into buckets of 2 m. The polygon with the highest priority wins when polygons overlap. The later polygon in the file wins when the priorities are equal. A point in no polygon is field soil. The contact point itself selects the class, thus a wheel changes its surface at the surveyed edge.

Map Class	Priority	Template	Ground
field		dry_soil	The soil class of the mapped soil unit, with the water and the ruts of the farm.
asphalt	60	asphalt	Hard surface.
concrete	55	concrete	Hard surface.
gravel	40	gravel	Hard surface.
dirt	30	dirt_track	Bare soil with traffic compaction 0.7.
grass_lane	20	sod_lane	Sod with traffic compaction 0.6 and root cohesion 3 kPa.
grass	10	sod	Sod with traffic compaction 0.2 and root cohesion 6 kPa.

The game then adds the live state of the ground. These rules apply to a wheel that touches the ground.

• Water and ruts. On the mapped surface, FAcresFarmRuntime::Sample replaces the template values with the farm state. The page Soil Water gives the water model.
• Water content. The value is a bilinear blend of the four nearest cells of 4 m, plus the sub-grid value of the wheel tracks.
• Surface wetness. On soil, \(\xi\) is the largest of three values: the wetting of the layer, the rain film and the water depth divided by 2 mm.
• Surface wetness on a hard surface. \(\xi\) is the water depth divided by 2 mm, with a maximum of 1.
• Soil class. With soil.class set to auto, the function SoilLibraryClassAt reads the class at the contact point.
• Tilled ground. Where an implement tilled the ground in this session, the density is the loose density of the class. The root cohesion and the traffic compaction are zero.

The function SoilLibraryClassAt uses these rules. The soil unit of a survey cell is in ACRE/soil_units.u8, and the wilting point of each unit is in ACRE/soils.json.

Condition	Soil Class
The field has a texture preset from the menu.	The class of the preset.
The option -VehicleSoilTexture= gives a texture group.	The class of that group.
The field has a custom soil from the menu.	The class of the group of its wilting point.
The soil unit is fine: the wilting point is 0.19 m³/m³ or more.	silty_clay_loam
The soil unit is medium.	silt_loam
The soil unit is coarse: the wilting point is 0.10 m³/m³ or less.	sandy_loam
The point is outside the soil grid.	silt_loam

The first condition that is true gives the class. When soil.class is a class identifier, all wheels use that class, but a texture preset of a field has priority.

The density of the undisturbed ground comes from the first value in this list that is larger than zero.

1. The loose density of the class, on tilled ground.
2. The density from the traffic compaction \(t_c\) of the template (function DensityFromCompaction).
3. The key soil.density_mg_m3.
4. The firm density of the class.

\[ \rho_0 = \rho_f + t_c\,(\rho_m - \rho_f) \]

Soil Library

The soil library is a table of seven texture classes in AcresSoilModel.cpp. The functions SoilClassAt and FindSoilClass read it. The file Content/Simulation/soil_library.json is a copy of the table for other tools. The game does not read this file. To change a class, change the table in the source file and build the game again. Then write the copy again with this command.

Tools/Terramechanics/physics_tests --export-soils Acres/Content/Simulation/soil_library.json

The identifier of a class is its name in lower case with underscores, for example silty_clay_loam.

Water retention, density and plasticity

Parameter	Unit	Sand	Loamy Sand	Sandy Loam	Loam	Silt Loam	Silty Clay Loam	Clay
Sand content	%	92	82	65	40	20	10	20
Clay content	%	3	6	10	20	18	34	55
\(\theta_r\)	m³/m³	0.045	0.057	0.065	0.078	0.067	0.089	0.068
\(\theta_s\)	m³/m³	0.43	0.41	0.41	0.43	0.45	0.43	0.38
\(\alpha_{vg}\)	1/m	14.5	12.4	7.5	3.6	2.0	1.0	0.8
\(n_{vg}\)	-	2.68	2.28	1.89	1.56	1.41	1.23	1.09
\(\rho_l\), loose	Mg/m³	1.45	1.40	1.30	1.25	1.15	1.10	1.00
\(\rho_f\), firm	Mg/m³	1.60	1.58	1.52	1.45	1.45	1.40	1.25
\(\rho_m\), maximum	Mg/m³	1.80	1.80	1.80	1.75	1.75	1.65	1.47
Liquid limit	kg/kg	0	0	0.20	0.30	0.31	0.41	0.45
Plastic limit	kg/kg	0	0	0.16	0.19	0.22	0.22	0.22
Conductivity \(K_s\)	mm/h	117.8	29.9	10.9	3.4	6.5	1.0	0.3

Strength, sinkage and shear deformation

Parameter	Unit	Sand	Loamy Sand	Sandy Loam	Loam	Silt Loam	Silty Clay Loam	Clay
\(c'\), loose	kPa	0.2	0.4	1.5	3.0	2.5	4.0	6.0
\(c'\), firm	kPa	0.5	1.0	3.0	5.0	6.0	10.0	15.0
\(\phi'\), loose	deg	30	30	29	30	29	25	20
\(\phi'\), firm	deg	36	35	34	34	33	29	24
\(n\)	-	0.95	0.85	0.66	1.01	0.87	0.73	0.50
\(k_{c,ref}\)	kN/m^(n+1)	10	8	6.9	0.06	20	41.6	13.19
\(k_{\phi,ref}\)	kN/m^(n+2)	2850	1600	752	5880	4000	2471	692.15
Reference density	Mg/m³	1.50	1.45	1.30	1.45	1.45	1.40	1.25
Reference \(S_e\)	-	0.02	0.20	0.50	0.60	0.60	0.85	0.95
\(K\), loose	cm	2.5	2.5	2.2	2.0	2.0	1.8	1.5
\(K\), firm	cm	1.2	1.2	1.2	1.0	1.0	0.8	0.6
Bulldozing share \(\beta_{class}\)	-	1.0	0.8	0.5	0.2	0.15	0.1	0.1
Structure factor \(S_t\)	-	1	1	3	3	3	3	3

Interfaces and cone index

Parameter	Unit	Sand	Loamy Sand	Sandy Loam	Loam	Silt Loam	Silty Clay Loam	Clay
\(\mu_r\), dry	-	0.75	0.78	0.85	0.90	0.90	0.90	0.85
\(\mu_r\), wet	-	0.65	0.62	0.60	0.55	0.50	0.45	0.35
\(c_a\)	kPa	0	0	0.5	1.0	1.5	2.0	3.0
Metal friction, dry	deg	25	24	24	23	22	21	20
Metal friction, wet	deg	22	21	20	18	17	15	12
Metal adhesion, peak	kPa	0.3	0.5	2	4	5	8	10
\(CI_{ref}\)	MPa	0.425	0.50	1.00	1.20	1.20	1.30	1.50
\(C_2\)	(kg/kg)²	0.010	0.010	0.008	0.004	0.004	0.004	0.004
\(C_3\)	kg/kg	0.06	0.07	0.03	0	0	0	0
Shape exponent \(q\)	-	1	1	1	1.5	1.5	1.5	1.5

The density exponent of the cone index is 3 for all classes. The section References gives the source of each group of values.

Soil State

The function SoilStateAt evaluates a soil class at a water content \(\theta\), a dry density \(\rho\), a surface wetness \(\xi\) and a root cohesion \(c_R\). The result is the structure FSoilState. Moisture changes the soil through the equations below, not through a table.

Density Position

The function limits the density to the range \(0.7\,\rho_l\) to \(\rho_m\). The density position \(P\) is 0 for loose soil and 1 for firm soil.

\[ P = \operatorname{clamp}\!\left(\frac{\rho - \rho_l}{\rho_f - \rho_l},\ -0.5,\ \frac{\rho_m - \rho_l}{\rho_f - \rho_l}\right), \qquad \Lambda = \operatorname{clamp}(1 - P,\ 0,\ 1) \]

\(\Lambda\) is the looseness. The drained strength and the shear deformation modulus are linear in \(P\) between the loose value (index \(l\)) and the firm value (index \(f\)).

\[ \phi' = \operatorname{clamp}\!\bigl(\phi_l + (\phi_f - \phi_l)P,\ \phi_l - 3^\circ,\ \phi_f + 4^\circ\bigr), \qquad c' = \max\bigl(0,\ c_l + (c_f - c_l)P\bigr) \]

\[ K_{soil} = \operatorname{clamp}\!\bigl(K_l + (K_f - K_l)P,\ 0.5\,K_f,\ 1.5\,K_l\bigr) \]

Water Content and Suction

A compacted soil has less pore space. The saturated water content is not more than 95 % of the porosity, with the particle density 2.65 Mg/m³.

\[ \theta_s(\rho) = \max\!\Bigl(\theta_r + 0.02,\ \min\bigl(\theta_s,\ 0.95\,(1 - \rho / 2.65)\bigr)\Bigr), \qquad S_e = \operatorname{clamp}\!\left(\frac{\theta - \theta_r}{\theta_s(\rho) - \theta_r},\ 0.001,\ 1\right) \]

\[ w = \frac{\theta}{\rho}, \qquad \gamma = 1000\,\rho\,g\,(1 + w) \]

The suction follows the van Genuchten curve, with a maximum of 1.5 MPa. Here \(\rho_w g\) is 9806.65 N/m³ and \(m = 1 - 1/n_{vg}\).

\[ \psi = \min\!\left(1.5\ \text{MPa},\ \frac{\rho_w g}{\alpha_{vg}}\left(S_e^{-1/m} - 1\right)^{1/n_{vg}}\right) \]

The suction stress of Lu and Likos adds apparent cohesion. Its maximum is 150 kPa.

\[ \sigma_s = \min(150\ \text{kPa},\ S_e\,\psi), \qquad c_d = c' + \sigma_s \tan\phi' + c_R \]

The root cohesion \(c_R\) comes from the surface template. Its range is 0 to 50 kPa.

Undrained Strength of Wet Fines

A tyre loads the soil for a fraction of a second. A plastic soil with a low conductivity cannot drain in this time when it is near saturation. The undrained strength follows Wroth and Wood, as a function of the liquidity index \(LI\). \(LL\) and \(PL\) are the liquid limit and the plastic limit.

\[ LI = \frac{w - PL}{LL - PL}, \qquad c_u = S_t \cdot 170\ \text{kPa} \cdot 100^{-\max(0,\,LI)} + c_R \]

\[ f_u = \operatorname{smoothstep}\!\left(\frac{S_e - 0.8}{0.2}\right) \frac{LL - PL}{LL - PL + 0.05}\ \frac{10}{10 + K_s} \]

Here \(\operatorname{smoothstep}(t) = t^2(3 - 2t)\) for \(t\) between 0 and 1, and \(K_s\) is in mm/h. A soil without plasticity has \(f_u = 0\), thus its undrained strength has no effect. The function SoilShearStrengthPa gives the shear strength.

\[ \tau(\sigma) = (1 - f_u)\,\tau_d + f_u \min\bigl(\tau_d,\ c_u + \sigma\tan 4^\circ\bigr), \qquad \tau_d = c_d + \sigma\tan\phi' \]

The minimum makes sure that more water cannot increase the strength. The fields CohesionPa and FrictionDeg of the state are one representative pair for a normal stress of 100 kPa.

\[ c = (1 - f_u)\,c_d + f_u \min\bigl(c_u,\ c_d + 100\ \text{kPa}\,(\tan\phi' - \tan 4^\circ)\bigr), \qquad \phi = \arctan\bigl((1 - f_u)\tan\phi' + f_u\tan 4^\circ\bigr) \]

Bekker Moduli

Each class has Bekker moduli for one reference state. The function scales them with the bearing capacity of the current state (the form of Reece). The bearing capacity is that of a strip of width \(B = 0.5\) m, with the factors of Prandtl, Reissner and Vesic.

\[ Q(c, \phi, \gamma) = c\,N_c + \tfrac{1}{2}\,\gamma\,B\,N_\gamma \]

\[ N_q = e^{\pi\tan\phi}\tan^2\!\left(\frac{\pi}{4} + \frac{\phi}{2}\right), \qquad N_c = \frac{N_q - 1}{\tan\phi}, \qquad N_\gamma = 2\,(N_q + 1)\tan\phi \]

For \(\tan\phi\) below \(10^{-4}\), \(N_c = \pi + 2\). A saturated surface layer uses the buoyant unit weight.

\[ \gamma' = \gamma - \operatorname{smoothstep}\!\left(\frac{S_e - 0.9}{0.1}\right)\rho_w g \]

\[ Q_{state} = (1 - f_u)\,Q(c_d, \phi', \gamma') + f_u \min\bigl(Q(c_d, \phi', \gamma'),\ Q(c_u, 4^\circ, \gamma')\bigr) \]

\[ \beta_Q = \operatorname{clamp}\!\left(\frac{Q_{state}}{Q_{ref}},\ 0.02,\ 50\right), \qquad k_c = \beta_Q\,k_{c,ref}, \qquad k_\phi = \beta_Q\,k_{\phi,ref} \]

\(Q_{ref}\) is the same expression for the reference density and the reference saturation of the class, without root cohesion. The exponent \(n\) does not change.

Cone Index

The cone index uses the form of Ayers and Perumpral with a shape exponent \(q\). \(CI_{ref}\) is the value at the firm density and \(S_e = 0.6\).

\[ CI_d = CI_{ref}\left(\frac{\rho}{\rho_f}\right)^{3}\left[\frac{C_2 + (w_{ref} - C_3)^2}{C_2 + (w - C_3)^2}\right]^{q}, \qquad w_{ref} = \frac{\theta_r + 0.6\,\bigl(\theta_s(\rho_f) - \theta_r\bigr)}{\rho_f} \]

\[ CI = \operatorname{clamp}\!\bigl((1 - f_u)\,CI_d + f_u \min(CI_d,\ 15\,c_u),\ 20\ \text{kPa},\ 6\ \text{MPa}\bigr) \]

The tyre model does not use the cone index. The HUD, the session log and the tests show it, and the tests compare the model with the Brixius equations.

Interfaces

A rain film or a surface near saturation decreases the friction between rubber and soil.

\[ \mu_r = \mu_{dry} - (\mu_{dry} - \mu_{wet})\,\max\!\left(\operatorname{clamp}(\xi, 0, 1),\ \operatorname{smoothstep}\!\left(\frac{S_e - 0.7}{0.3}\right)\right) \]

The adhesion \(c_a\) is the class value. The state also contains the friction angle and the adhesion between soil and metal. The implement model uses these two values. The page Implement Mechanics gives their use.

\[ \delta_m = \delta_{dry} - (\delta_{dry} - \delta_{wet})\,S_e, \qquad a_m = a_{peak}\exp\!\left(-\left(\frac{w - w_{peak}}{0.06}\right)^{2}\right) \]

\(w_{peak}\) is the plastic limit for a plastic soil. For other soils it is the water content at a suction of 33 kPa. The bulldozing share of the state is the class value multiplied by the looseness: \(\beta = \beta_{class}\,\Lambda\).

Example States

This table shows the silt loam at its firm density of 1.45 Mg/m³, at four values of \(S_e\). The values are from soil_library.json.

Quantity	Unit	0.2	0.5	0.8	1.0
Water content \(\theta\)	m³/m³	0.140	0.249	0.358	0.430
Cohesion \(c\)	kPa	38.2	14.1	8.8	7.6
Friction angle \(\phi\)	deg	33.0	33.0	33.0	23.0
\(k_c\)	kN/m^(n+1)	53.2	22.8	16.4	7.0
\(k_\phi\)	kN/m^(n+2)	10 646	4555	3280	1403
Cone index	MPa	6.00	1.73	0.64	0.29
Rubber friction \(\mu_r\)	-	0.90	0.90	0.80	0.50

Ruts and Compaction

A wheel that sinks leaves a rut. The farm keeps the rut depth in a map with cells of 0.25 m (function FAcresFarmRuntime::Wheel). The function goes across the footprint of the tyre in steps of 0.125 m. The footprint length is the contact length plus the travel of this step.

\[ z_{rut} \leftarrow \max\bigl(z_{rut},\ \min(0.35\ \text{m},\ 0.65\,z)\bigr) \]

The rut keeps 65 % of the sinkage. The model assumes that the other 35 % comes back. No measurement supports this share.

A rut does not become less deep with time. Tillage removes the ruts of the cells that the implement works. The saved farm state contains the ruts, thus the ruts stay when you load the state. Without the farm, the game keeps a rut map for the vehicle with the same rule, and a reset clears it.

A rut changes the next pass in four ways.

• Density. The soil below the rut is denser, thus stronger (function CompactedDensity).
• Sinkage. The wheel is at the rut depth or deeper: \(z_w = \max(z_{rut},\ z_j)\).
• Resistance. The compaction resistance and the bulldozing resistance act only on the sinkage below the rut.
• Water. Standing water fills the ruts first. The farm also decreases the infiltration of a compacted cell.

The density follows from mass conservation in the layer of thickness \(H_c\) (soil.compaction_layer_m, 0.3 m). Half of the rut volume is compaction. The other half moves to the sides of the rut.

\[ \rho = \min\!\left(\rho_m,\ \max\!\left(\rho_0,\ \rho_0\,\frac{H_c}{H_c - 0.5\,z_{rut}}\right)\right), \qquad 0 \le z_{rut} \le 0.8\,H_c \]

The rear wheels of a vehicle that moves straight run in the ruts of the front wheels. This is the multipass effect of the model. The test "second pass in the rut" shows this effect on wet silt loam. The density increases from 1.250 to 1.306 Mg/m³, and the soil resistance decreases from 1398 N to 189 N.

Tyre on Hard Ground

With an inflation pressure above zero, the tyre is an inflated membrane with the shape of a torus (function TyreDeflection). The ground plane cuts the torus in an ellipse of area \(2\pi\delta\sqrt{r b / 2}\). This area carries the load at the pressure \(p_g\).

\[ \delta = \min\!\left(0.45\,r,\ \frac{N}{2\pi\,p_g\sqrt{r\,b/2}}\right), \qquad k_t = 2\pi\,p_g\sqrt{r\,b/2} \]

\(k_t\) is the vertical rate of the tyre. The suspension uses it, see Maxxum 150 Dynamics. On a hard surface, the contact area and the contact length are:

\[ A = \frac{N}{p_g}, \qquad l = 2\sqrt{2\,r\,\delta} \]

For the Maxxum at 80 kPa, \(k_t\) is 274 kN/m for a front tyre and 341 kN/m for a rear tyre. The rear tyre has a deflection of 5.0 cm at its static load of 17.1 kN.

Pressure and Sinkage

The function TyreOnSoil puts the tyre on the soil state. It follows the flexible tyre and rigid wheel model of Wong. First it computes the sinkage of a rigid wheel and the ground pressure below that wheel (Bekker).

\[ z_0 = \left[\frac{3\,N}{(3 - n)\,(k_c + b\,k_\phi)\,\sqrt{2r}}\right]^{\frac{2}{2n + 1}}, \qquad p_{gcr} = k\,z_0^{\,n}, \qquad k = \frac{k_c}{b} + k_\phi \]

The tyre is in one of two modes.

Mode	Condition	Sinkage	Flat Length	Deflection
Flexible (1)	\(p_i > 0\) and \(p_g < p_{gcr}\)	\(z = (p_g / k)^{1/n}\)	\(l_f = \min\bigl(N / (b\,p_g),\ 1.6\,r\bigr)\)	\(\delta = r - \sqrt{r^2 - l_f^2 / 4}\)
Rigid (2)	All other conditions	\(z = z_0\)	\(l_f = 0\)	\(\delta = 0\)

In the flexible mode, the bottom of the tyre is flat and the soil below it carries the pressure \(p_g\). A lower inflation pressure thus gives a larger contact and less sinkage on soft soil.

Slip sinkage. A tyre that slips digs into the soil. The model uses the relation of Lyasko.

\[ z_s = \min(z,\ z_{max}), \qquad z_j = \min\!\left(z\,\frac{1 + \tilde{s}}{1 - 0.5\,\tilde{s}},\ z_{max}\right), \qquad 0 \le \tilde{s} \le 0.9 \]

\(z_{max}\) is soil.max_sinkage_m. \(\tilde{s}\) is the absolute slip after a lag over one contact length of travel (function SettleWheels).

\[ \tilde{s} \leftarrow \lvert s \rvert + (\tilde{s} - \lvert s \rvert)\,e^{-\Delta t / T_s}, \qquad T_s = \frac{\max(0.1,\ l)}{\max(0.3,\ \lvert v_x \rvert)} \]

Contact. The contact is the rear half of the flat part plus the front arc up to the soil surface. The model has no contact behind the flat part.

\[ l = \max\!\left(0.05,\ \frac{l_f}{2} + \sqrt{r^2 - (r - \delta - z_j)^2}\right), \qquad A = b\,l, \qquad p = \frac{N}{A} \]

When \(r - \delta - z_j\) is not positive, the front arc term is \(r\).

Load and sinkage together. The sinkage extends the suspension, and this decreases the load. The function PrepareWheel solves the two quantities together. It looks for the load \(N\) that the suspension gives when the compression decreases by \(\max(z_{rut},\ z_j(N))\). The search is a bisection of the range 0 to \(6 N_0\) in 18 steps. The wheel then is at the depth \(z_w = \max(z_{rut}, z_j)\), and the game applies the tyre forces at the bottom of the rut.

Motion Resistance

The soil resistance acts on the axle, against the direction of travel. The function TyreOnSoil computes its two parts.

Compaction resistance. This is the compaction work of Bekker for each metre of travel. The work presses the rut from its depth before the pass to the sinkage without slip.

\[ R_c = \frac{b\,k\,\bigl(z_s^{\,n+1} - z_r^{\,n+1}\bigr)}{n + 1}\,\sqrt{\frac{z_j}{z_s}}, \qquad z_r = \min\bigl(z_{rut},\ z_s\bigr) \]

The slip sinkage is excavation, and the slip loss contains its energy. It increases only the entry angle, which is the square root factor.

Bulldozing resistance. A tyre pushes loose soil in front of it. The term acts on the new sinkage \(z_f = \max(0,\ z_j - z_{rut})\). It uses the local shear values of Terzaghi: \(\tfrac{2}{3}c\) and \(\tan\phi^* = \tfrac{2}{3}\tan\phi\).

\[ R_b = \beta\,b\left(0.67 \cdot \tfrac{2}{3}c \cdot z_f\,K_{pc} + \tfrac{1}{2}\,z_f^{\,2}\,\gamma\,K_{p\gamma}\right) \]

\[ K_{pc} = (N_c - \tan\phi^*)\cos^2\phi^*, \qquad K_{p\gamma} = \bigl(4\,(N_q + 1) + 1\bigr)\cos^2\phi^* \]

\(N_c\) and \(N_q\) are the bearing factors for \(\phi^*\). The share \(\beta\) is zero at the firm density, thus firm soil does not bulldoze.

Force on the axle. The function SettleWheels applies the sum \(R = R_c + R_b\). The force decreases to zero near standstill. A limit prevents that the force reverses the motion of the wheel in one step.

\[ R_{eff} = \operatorname{clamp}\!\left(R\,\tanh\!\frac{v_x}{0.1},\ -\frac{N_0\,\lvert v_x \rvert}{g\,\Delta t},\ \frac{N_0\,\lvert v_x \rvert}{g\,\Delta t}\right) \]

Rolling resistance of the tyre. The flexing of the tyre is a torque on the wheel, not a force on the axle.

\[ T_h = \min(f,\ 0.45)\,N\,r, \qquad f = \begin{cases} k_h\,\delta_h / \max(0.05,\ b\,a_r) & \text{soil library, } p_i > 0 \\ 0.01 & \text{soil library, } p_i = 0 \\ \text{rolling of the template} & \text{hard surface} \end{cases} \]

\(k_h\) is tyre_hysteresis, \(a_r\) is the aspect ratio and \(\delta_h\) is the hard-ground deflection at the load \(N\). For a rear tyre of the Maxxum at its static load, \(f\) is 0.030. The legacy soil model uses a different coefficient, see Legacy Soil Model.

Shear Capacity

The shear capacity \(H\) is the largest shear force that the contact can give. The function TyreOnSoil computes it in three steps.

Lugs. The lugs carry the load on a share \(a_l\) of the contact (tyre_lug_area_ratio). They thus sink in at a higher pressure. \(h_l\) is the lug height and \(e\) is the embedded fraction of the lugs.

\[ e = \operatorname{clamp}\!\left(\frac{1}{h_l}\left(\frac{p}{a_l\,k}\right)^{1/n},\ 0,\ 1\right), \qquad \lambda = \frac{e\,h_l}{b} \]

Soil. The shear strength at the mean pressure has a cohesive part and a frictional part. Each part gets the grouser factor of Bekker.

\[ H_{soil} = A\left[\tau(0)\,(1 + 2\lambda) + \bigl(\tau(p) - \tau(0)\bigr)\left(1 + 0.64\,\lambda\left(\frac{\pi}{2} - \arctan\lambda\right)\right)\right] \]

Interface. Lugs that are not in the soil slide on the rubber. Wet plastic soil fills the space between the lugs, thus the factor \(1 - f_u\).

\[ H_{int} = c_a\,A + \mu_r\,N, \qquad \eta_i = 1 - (1 - a_l)\,e\,(1 - f_u) \]

\[ H = H_{soil} - \eta_i \max(0,\ H_{soil} - H_{int}), \qquad \mu = \frac{H}{N} \]

For a tyre without lugs, \(\eta_i = 1\) and \(H = \min(H_{soil}, H_{int})\).

Longitudinal Force

The slip compares the speed of the tread with the speed of the contact point (function Slip). The floor of 0.2 m/s keeps the value finite near standstill.

\[ s = \frac{\omega r - v_x}{\max(0.2,\ \lvert\omega r\rvert,\ \lvert v_x\rvert)} \]

The model keeps the shear displacement \(j\) of each wheel as a state. It increases with the slip speed and decreases while the tread rolls through the contact.

\[ \frac{dj}{dt} = (\omega r - v_x) - \frac{j}{h_r}\max(\lvert\omega r\rvert,\ \lvert v_x\rvert,\ 0.2), \qquad h_r = \max\!\left(0.05,\ \frac{l}{2}\right) \]

The driveline solve integrates this equation with the backward Euler method for each trial wheel speed.

\[ j^{+} = \operatorname{clamp}\!\left(\frac{j + \Delta t\,(\omega r - v_x)}{1 + \Delta t\,\max(\lvert\omega r\rvert,\ \lvert v_x\rvert,\ 0.2) / h_r},\ -h_r,\ h_r\right), \qquad s_t = \frac{j^{+}}{h_r} \]

In steady motion, \(j = s\,h_r\) and \(s_t = s\). At standstill the tyre acts as a spring, thus a parked vehicle does not vibrate. The shear force follows the Janosi-Hanamoto relation at the middle of the contact.

\[ F_s = \operatorname{sign}(s_t)\,H\left(1 - \exp\!\left(-\frac{\lvert s_t\rvert\,l}{2K}\right)\right), \qquad K = K_{soil} + K_{tread} \]

\(K_{tread}\) is tyre_tread_k_m. It is the shear compliance of the tread and the carcass, in series with the soil. The friction circle then limits the force, and the motion resistance decreases the force on the chassis.

\[ F_s \leftarrow \operatorname{clamp}(F_s,\ -F_{lim},\ F_{lim}), \qquad F_x = F_s - R_{eff} \]

The functions are TyreForce and SettleWheels. A wheel that does not touch the ground has no tyre force.

Lateral Force and Combined Slip

The function PrepareWheel computes the lateral force before the driveline solve. The slip angle uses a speed floor of 0.2 m/s.

\[ \alpha = \operatorname{atan2}\bigl(v_y,\ \max(0.2,\ \lvert v_x\rvert)\bigr), \qquad F_y^{*} = \operatorname{clamp}(-C_\alpha\,N\,\alpha,\ -\mu N,\ \mu N) \]

\(C_\alpha\) is cornering_stiffness_per_load. The force follows its target with a relaxation length \(L_r\) (lateral_relaxation_m).

\[ F_y \leftarrow F_y^{*} + (F_y - F_y^{*})\,\exp\!\left(-\frac{\Delta t\,\max(0.2,\ \lvert v_x\rvert)}{L_r}\right) \]

The lateral force and the longitudinal force share one friction circle. The lateral force has priority.

\[ F_{lim} = \sqrt{\max\bigl(0,\ (\mu N)^2 - F_y^{\,2}\bigr)} \]

On soil, \(\mu N\) is the shear capacity \(H\). The same capacity thus limits traction, braking and cornering.

Hard Surfaces

On asphalt, concrete and gravel the tyre does not sink. The grip ratio is the friction coefficient of the template, decreased by a water film (function HardSurfaceFriction).

\[ \mu = \mu_0\,\bigl(1 - \operatorname{clamp}(\xi, 0, 1)\,(1 - q_w)\bigr) \]

Surface	Dry Friction	Wet-to-Dry Ratio	Wet Friction	Rolling Coefficient
asphalt	0.90	0.6 / 0.85 = 0.706	0.635	0.015
concrete	0.85	0.8 / 0.85 = 0.941	0.800	0.012
gravel	0.65	0.85	0.553	0.035

The dry friction is \(\mu_0\), the wet-to-dry ratio is \(q_w\) and the wet friction is \(\mu\) at \(\xi = 1\).

The longitudinal force is a smooth friction curve of the transient slip. \(k_s\) is 9 for the Maxxum.

\[ F_s = \mu\,N\,\tanh(k_s\,s_t) \]

The curve reaches 95 % of \(\mu N\) at 20 % slip. The lateral force and the friction circle are the same as on soil. The rolling resistance torque uses the coefficient rolling of the template. Without a soil class (legacy), the wet factor is \(1 - 0.35\,\xi\) for all hard surfaces and the slip is the steady slip \(s\).

Standing Water

Water on the ground slows each wheel. The game computes a drag force on the wet part of the tyre face (function WaterDrag).

\[ \vec{F}_w = -\tfrac{1}{2}\,\rho_w\,C_d\,A_w\,\lvert\vec{v}_h\rvert\,\vec{v}_h, \qquad A_w = b\,\min(2r,\ h_w) \]

\(\vec{v}_h\) is the horizontal velocity of the contact point, \(h_w\) is the water depth, \(\rho_w\) is 1000 kg/m³ and \(C_d\) is water_drag_cd. The model has no buoyancy. The water depth comes from the template or from the soil water model.

Legacy Soil Model

The legacy model runs when the key soil.class is absent and no option selects a class. The functions are SoilContact and JanosiForce. The tyre is a rigid circle. Its deflection is a fixed share of the radius and does not depend on the load.

\[ \delta = \operatorname{clamp}(0.5\,d_r\,r,\ 0.005,\ 0.4\,r), \qquad l = 2\sqrt{2 r \delta - \delta^2}, \qquad A = b\,l, \qquad p = \frac{N}{A} \]

\(d_r\) is tire_deflection_ratio. The Bekker modulus decreases linearly with the saturation, and the pressure gives the sinkage.

\[ S_e = \operatorname{clamp}\!\left(\frac{\theta - \theta_r}{\theta_s - \theta_r},\ 0.001,\ 1\right), \qquad k = \left(\frac{k_c}{b} + k_\phi\right)\bigl(1 + (q_{sat} - 1)\,S_e\bigr), \qquad z = \min\!\left(\left(\frac{p}{k}\right)^{1/n},\ z_{max}\right) \]

The shear capacity is the Mohr-Coulomb strength with a suction term from the van Genuchten curve. \(\psi_{cap}\) is suction_cap_pa.

\[ \psi = \min\!\left(\psi_{cap},\ \frac{\rho_w g}{\alpha_{vg}}\left(S_e^{-1/m} - 1\right)^{1/n_{vg}}\right), \qquad H = A\,\bigl(c + (p + S_e\,\psi)\tan\phi\bigr) \]

The shear force uses the steady slip, without the shear displacement state.

\[ F_s = \operatorname{sign}(s)\,H\left(1 - \exp\!\left(-\frac{\lvert s\rvert\,l}{2K}\right)\right) \]

The soil resistance is a part of the rolling resistance torque in this model, not a force on the axle.

\[ f = 0.01 + \frac{b\,k\,z^{\,n+1}}{(n + 1)\,N}\left(1 - \operatorname{clamp}\!\left(\frac{z_{rut}}{z},\ 0,\ 1\right)^{n+1}\right) \]

Worked Example

This example is one rear tyre of the Maxxum (650/65R38, 80 kPa) at its static load on silt loam. The soil state is that of field F21 in the tutorial Drive the Maxxum Tractor: \(\theta = 0.224\), firm density, dry surface. The numbers come from the model functions.

Quantity	Value
Load \(N\)	17.12 kN
Effective saturation \(S_e\)	0.433
Suction \(\psi\), suction stress \(\sigma_s\)	36.3 kPa, 15.7 kPa
Cohesion \(c\), friction angle \(\phi\)	16.2 kPa, 33.0°
Bearing ratio \(\beta_Q\)	1.27
\(k_c\), \(k_\phi\)	25.4 kN/m^(n+1), 5086 kN/m^(n+2)
Cone index	2.26 MPa
Rigid-wheel pressure \(p_{gcr}\)	186 kPa, thus the mode is flexible
Sinkage \(z_s = z_j\)	1.08 cm
Flat length \(l_f\), deflection \(\delta\)	0.263 m, 0.96 cm
Contact length \(l\), area \(A\), pressure \(p\)	0.323 m, 0.210 m², 81.5 kPa
Compaction resistance \(R_c\), bulldozing \(R_b\)	377 N, 0 N
Shear capacity \(H\)	15.6 kN, thus \(\mu = 0.91\)
\(F_s / N\) at 5 %, 10 %, 15 %, 20 % slip	0.30, 0.51, 0.64, 0.73

In the game, the same tyre showed a sinkage of 1.1 cm and a cone index of 2.42 MPa on this field. The game value includes the compaction of the rut.

Shared Use by the Polaris

The Polaris uses the same contact model. Its function PrepareUtvWheel calls PrepareWheel with the wheel parameters of polaris.json.

Part	Maxxum	Polaris
Surface selection, soil class, farm state	SampleSurface, soil block of tractor.json	The same code and the same soil block
Suspension load	SuspensionLoad	The same function, with its own rest and bump-stop values
Sinkage, shear capacity, motion resistance	TyreOnSoil	The same function, with a sinkage limit of 0.2 m
Lateral force, friction circle	PrepareWheel	The same function
Shear displacement, wheel speeds, ledger	SettleWheels and the shaft torque functions	The same functions
Brake torque	\(1.5\,b_k\,N\,r\)	Hydraulic pressure multiplied by a torque gain
Driveline solve	SolveDriveline	SolveUtvDriveline

The page Polaris Ranger Dynamics gives the parameters and the driveline of the Polaris.

Verification

The folder Tools/Terramechanics contains engine-free tests of this model. Build and run them from the repository root.

sh Tools/Terramechanics/build.sh
Tools/Terramechanics/physics_tests

Expected Result

The last line is 49 passed, 0 failed.

The tests run the Maxxum on a planar test stand (VehicleBench.h) with the same model sources as the game.

Test Group	Result
Drawbar test against Brixius (ASABE D497.7)	Firm loam: maximum distance 0.009 in net traction ratio for 5 % to 30 % slip. Tilled loam 0.034, wet silty clay loam 0.002, dry loose sand 0.21.
Tractive efficiency	The peak is 0.78 on firm loam at a pull of 0.40 of the weight.
Moisture	Net traction of silt loam at 15 % slip decreases from 0.69 to 0.38 from \(S_e\) 0.3 to saturation. The sinkage increases from 0.9 cm to 5.9 cm.
Step size	Steps of 1/60 s, 1/120 s and 1/240 s give the same steady state.
Static equilibrium	The sum of the wheel loads is the weight. A parked vehicle does not move.
Inflation	60 kPa gives a sinkage of 2.8 cm, 160 kPa gives 5.7 cm on the test soil.
Slip sinkage in loose sand	The sinkage increases from 4.2 cm to 7.4 cm from 0 % to 40 % slip.
Sod	The sinkage is 1.8 cm on field soil, 1.0 cm on a grass lane and 1.2 cm on a grass verge.
Soil library copy	soil_library.json agrees with the source table.

The study in Calibration/Tractor/soil_weather_results.md compares the game with these tests on one field in six soil states. The rear slip of the game and of the test stand agree to 0.3 percentage points.

Note

The model gives approximately half the slip of the Brixius equations at rear tyre loads of 32 kN to 35 kN. This is an open question. Field data with measured slip are necessary to decide it.

Parameters

Tyre Keys in tractor.json

These keys are in the block vehicle.

Name	Type	Unit	Default	Description
front_radius_m	number	m	0.7066	The unloaded radius of a front tyre (540/65R28).
rear_radius_m	number	m	0.9051	The unloaded radius of a rear tyre (650/65R38).
front_width_m	number	m	0.54	The section width of a front tyre.
rear_width_m	number	m	0.65	The section width of a rear tyre.
front_inflation_kpa	number	kPa	80	The inflation pressure of the front tyres. 0 selects a tyre with a fixed footprint.
rear_inflation_kpa	number	kPa	80	The inflation pressure of the rear tyres.
tyre_carcass_kpa	number	kPa	20	The carcass stiffness as a pressure \(p_c\).
front_aspect_ratio	number	-	0.65	The section height divided by the width, front.
rear_aspect_ratio	number	-	0.65	The section height divided by the width, rear.
tyre_hysteresis	number	-	0.25	The rolling resistance for each unit of relative deflection, \(k_h\).
tyre_lug_height_m	number	m	0.04	The lug height \(h_l\). 0 is a smooth tyre.
tyre_lug_area_ratio	number	-	0.25	The share of the contact that the lug faces cover, \(a_l\).
tyre_tread_k_m	number	m	0.01	The shear compliance of the tread and carcass, \(K_{tread}\).
cornering_stiffness_per_load	number	1/rad	5	The cornering stiffness divided by the load, \(C_\alpha\).
lateral_relaxation_m	number	m	0.6	The relaxation length of the lateral force, \(L_r\).
water_drag_cd	number	-	1.1	The drag coefficient of a wheel in standing water.
front_tire_stiffness_n_m	number	N/m	250000	The vertical rate of a front tyre. The model uses it only when the inflation is 0.
rear_tire_stiffness_n_m	number	N/m	400000	The vertical rate of a rear tyre. The model uses it only when the inflation is 0.

Block soil in tractor.json

Name	Type	Unit	Default	Description
class	string		auto	A soil class identifier, or auto for the class of the mapped soil unit below each wheel. Without the key, the legacy soil model runs.
density_mg_m3	number	Mg/m³	0	The dry density of undisturbed ground. 0 selects the firm density of the class.
compaction_layer_m	number	m	0.3	The thickness of the layer that a rut compacts, \(H_c\).
max_sinkage_m	number	m	0.35	The sinkage limit \(z_{max}\). Both soil models use it.
bekker_kc	number	N/m^(n+1)	20000	Legacy: the cohesive modulus \(k_c\).
bekker_kphi	number	N/m^(n+2)	2000000	Legacy: the frictional modulus \(k_\phi\).
bekker_n	number	-	1.1	Legacy: the sinkage exponent \(n\).
saturated_bekker_ratio	number	-	0.4	Legacy: the factor \(q_{sat}\) of the modulus at saturation.
cohesion_pa	number	Pa	3000	Legacy: the cohesion \(c\).
friction_degrees	number	deg	28	Legacy: the friction angle \(\phi\).
janosi_k_m	number	m	0.025	Legacy: the shear deformation modulus \(K\).
theta_residual	number	m³/m³	0.06	Legacy: the residual water content.
theta_saturated	number	m³/m³	0.43	Legacy: the saturated water content.
vg_alpha_m_inv	number	1/m	2	Legacy: the van Genuchten \(\alpha_{vg}\).
vg_n	number	-	1.6	Legacy: the van Genuchten \(n_{vg}\).
suction_cap_pa	number	Pa	100000	Legacy: the maximum suction \(\psi_{cap}\).
tire_deflection_ratio	number	-	0.2	Legacy: the deflection ratio \(d_r\).

Block surfaces in tractor.json

Each entry of the block is one surface template with these keys.

Name	Type	Unit	Default	Description
deformable	boolean			true selects a soil model, false selects the hard-surface model.
friction	number	-		The dry friction coefficient \(\mu_0\) of a hard surface.
rolling	number	-		The rolling resistance coefficient of a hard surface.
theta	number	m³/m³		The water content of the soil when the farm does not give one.
wetness	number	-		The surface wetness \(\xi\) when the farm does not give one.
water_depth_m	number	m		The depth of standing water when the farm does not give one.
traffic_compaction	number	-	0	The position of the density between firm (0) and maximum (1), \(t_c\).
root_cohesion_pa	number	Pa	0	The root cohesion \(c_R\) of a sod. The permitted range is 0 to 50000.

The shipped templates have these values. The index is the value of the surface columns of the session log.

Index	Template	Deformable	Friction	Rolling	Theta	Wetness	Water Depth (m)
0	asphalt	false	0.9	0.015	0.2	0	0
1	concrete	false	0.85	0.012	0.2	0	0
2	gravel	false	0.65	0.035	0.2	0	0
3	dry_soil	true	0.7	0.05	0.12	0	0
4	wet_soil	true	0.7	0.05	0.38	0.85	0
5	mud	true	0.7	0.05	0.43	1	0.12
7	sod_lane	true	0.7	0.05	0.2	0	0
8	sod	true	0.7	0.05	0.2	0	0
9	dirt_track	true	0.7	0.05	0.2	0	0

Three templates have the two keys of the surface map.

Template	Traffic Compaction	Root Cohesion (Pa)
sod_lane	0.6	3000
sod	0.2	6000
dirt_track	0.7	0

Index 6 is the selection mapped. The soil models do not use friction and rolling on a deformable surface.

Keys of a Soil Class

The copy soil_library.json uses these keys for each class. The default column shows the class silt_loam.

Name	Type	Unit	Default	Description
id	string		silt_loam	The identifier for soil.class and -VehicleSoilClass=.
sand_pct, clay_pct	number	%	20, 18	The representative texture. For information only.
theta_residual	number	m³/m³	0.067	\(\theta_r\) of the van Genuchten curve.
theta_saturated	number	m³/m³	0.45	\(\theta_s\) of the van Genuchten curve.
vg_alpha_per_m	number	1/m	2	\(\alpha_{vg}\).
vg_n	number	-	1.41	\(n_{vg}\).
loose_density	number	Mg/m³	1.15	The density of tilled soil, \(\rho_l\).
firm_density	number	Mg/m³	1.45	The density of settled soil, \(\rho_f\).
max_density	number	Mg/m³	1.75	The compaction limit \(\rho_m\).
liquid_limit, plastic_limit	number	kg/kg	0.31, 0.22	The Atterberg limits. Both are 0 for a soil without plasticity.
loose_cohesion_pa, firm_cohesion_pa	number	Pa	2500, 6000	The drained cohesion at the two densities.
loose_friction_deg, firm_friction_deg	number	deg	29, 33	The drained friction angle at the two densities.
bekker_n	number	-	0.87	The sinkage exponent.
bekker_kc	number	N/m^(n+1)	20000	\(k_{c,ref}\) at the reference state.
bekker_kphi	number	N/m^(n+2)	4000000	\(k_{\phi,ref}\) at the reference state.
reference_density	number	Mg/m³	1.45	The density of the reference state.
reference_saturation	number	-	0.6	The effective saturation of the reference state.
loose_janosi_m, firm_janosi_m	number	m	0.02, 0.01	The shear deformation modulus at the two densities.
rubber_friction_dry, rubber_friction_wet	number	-	0.9, 0.5	The friction between rubber and soil.
rubber_adhesion_pa	number	Pa	1500	The adhesion between rubber and soil, \(c_a\).
metal_friction_dry_deg, metal_friction_wet_deg	number	deg	22, 17	The friction angle between soil and metal.
metal_adhesion_pa	number	Pa	5000	The peak adhesion between soil and metal.
cone_index_pa	number	Pa	1200000	\(CI_{ref}\).
cone_width, cone_peak	number	(kg/kg)², kg/kg	0.004, 0	\(C_2\) and \(C_3\) of the cone index.
cone_density_exponent	number	-	3	The density exponent of the cone index.
bulldozing_share	number	-	0.15	The bulldozing share of loose soil, \(\beta_{class}\).
structure_factor	number	-	3	\(S_t\), the ratio of intact strength to remoulded strength.
conductivity_mm_h	number	mm/h	6.5	The saturated conductivity \(K_s\).
field_capacity_theta, wilting_theta	number	m³/m³	0.2301, 0.1018	Derived: \(\theta\) at 33 kPa and at 1500 kPa.
states	list			Derived: the soil state at \(S_e\) 0.2, 0.5, 0.8 and 1.0.

The shape exponent \(q\) of the cone index is in the source table only.

Constants in the Source Code

Constant	Value	Function
Slip speed floor	0.2 m/s	Slip
Hard-surface slip stiffness \(k_s\)	9	FVehicleParameters::HardSlipStiffness
Rut share of the sinkage	0.65	FAcresFarmRuntime::Wheel
Maximum rut depth	0.35 m	FAcresFarmRuntime::Wheel
Rut cell	0.25 m	FAcresFarmRuntime::Wheel
Compaction share of the rut volume	0.5	CompactedDensity
Suction stress limit	150 kPa	SoilStateAt
Undrained friction angle	4°	SoilStateAt
Footing width \(B\) of the bearing measure	0.5 m	SoilStateAt
Cone factor	15	SoilStateAt
Cone index limits	20 kPa, 6 MPa	SoilStateAt
Particle density	2.65 Mg/m³	SoilStateAt
Maximum rolling coefficient	0.45	PrepareWheel
Water film for full wetness	2 mm	FAcresFarmRuntime::Sample

Command-Line Options

Name	Type	Unit	Default	Description
-VehicleSurface=	string		mapped	The surface template for all wheels, or mapped.
-VehicleSoilClass=	string		from soil.class	A soil class identifier or auto.
-VehicleConfig=	path		Content/Simulation/tractor.json	The vehicle configuration file.

Code Map

Item	File	Function
Surface template of a wheel	AcresVehicle.cpp	AAcresVehiclePawn::SampleSurface
Surface class at a point	AcresSurfaceMap.cpp	FSurfaceMap::ClassAt
Soil class at a point	AcresVehicle.cpp	AAcresVehiclePawn::SoilLibraryClassAt, SoilTextureAt
Water, wetness and rut at a point	AcresFarmRuntime.cpp	FAcresFarmRuntime::Sample
Soil library table	AcresSoilModel.cpp	SoilClassAt, FindSoilClass, SoilClassFromTexture
Soil state	AcresSoilModel.cpp	SoilStateAt, SoilShearStrengthPa, SoilThetaAtSuction
Density	AcresSoilModel.cpp	CompactedDensity, DensityFromCompaction
Tyre deflection	AcresSoilModel.cpp	TyreDeflection
Sinkage, resistance, capacity	AcresSoilModel.cpp	TyreOnSoil
Hard-surface friction	AcresSoilModel.cpp	HardSurfaceFriction
Load, lateral force, friction circle	AcresVehicleModel.cpp	PrepareWheel
Slip	AcresSimModel.cpp	Slip
Shear displacement and shear force	AcresVehicleModel.cpp	ShearDisplacement, TyreForce, JanosiForce
Force on the chassis, slip sinkage state	AcresVehicleModel.cpp	SettleWheels
Legacy soil	AcresVehicleModel.cpp	SoilContact, Longitudinal
Water drag	AcresVehicleModel.cpp	WaterDrag
Ruts	AcresFarmRuntime.cpp	FAcresFarmRuntime::Wheel
Brixius reference for the tests	AcresSoilModel.cpp	BrixiusTraction
Tests	Tools/Terramechanics/physics_tests.cpp

Limitations

• No measurement at ACRE calibrates the model. The soil classes use typical values of each texture class.
• The slip at high rear loads is lower than the Brixius equations give. The absolute slip is thus optimistic.
• Loose dry sand pulls approximately 0.2 of the weight less than the Brixius equations. That soil is outside their range.
• The soil is one layer. A wet surface on a dry layer shows only through the surface wetness.
• The rut depth does not decrease with time. Only tillage removes a rut.
• The rut share of 0.65 and the compaction share of 0.5 are assumptions.
• A hard surface gets its wetness from standing water only. The rain film has no effect there.
• When the user selects a soil surface with the keys 1 to 6 during a farm session, the wheels do not read the ruts.
• The hard-surface friction curve does not depend on the load. The tyre has no camber force and no aligning torque.
• The inflation sets the footprint through a membrane model, not through a measured load and deflection chart.

References

• ASABE D497.7 (2011, reaffirmed 2015). Agricultural Machinery Management Data. American Society of Agricultural and Biological Engineers, St. Joseph, Michigan.
• Ayers, P. D. and Perumpral, J. V. (1982). Moisture and density effect on cone index. Transactions of the ASAE 25(5):1169-1172.
• Bekker, M. G. (1960). Off-the-Road Locomotion. University of Michigan Press, Ann Arbor.
• Bekker, M. G. (1969). Introduction to Terrain-Vehicle Systems. University of Michigan Press, Ann Arbor.
• Brixius, W. W. (1987). Traction prediction equations for bias ply tires. ASAE Paper 87-1622. American Society of Agricultural Engineers, St. Joseph, Michigan.
• Carsel, R. F. and Parrish, R. S. (1988). Developing joint probability distributions of soil water retention characteristics. Water Resources Research 24(5):755-769.
• De Baets, S., Poesen, J., Reubens, B., Wemans, K., De Baerdemaeker, J. and Muys, B. (2008). Root tensile strength and root distribution of typical Mediterranean plant species and their contribution to soil shear strength. Plant and Soil 305:207-226.
• Fountaine, E. R. (1954). Investigations into the mechanism of soil adhesion. Journal of Soil Science 5(2):251-263.
• Håkansson, I. (1990). A method for characterizing the state of compactness of the plough layer. Soil and Tillage Research 16:105-120.
• Janosi, Z. and Hanamoto, B. (1961). The analytical determination of drawbar pull as a function of slip for tracked vehicles in deformable soils. Proceedings of the 1st International Conference on the Mechanics of Soil-Vehicle Systems, Turin.
• Lu, N. and Likos, W. J. (2006). Suction stress characteristic curve for unsaturated soil. Journal of Geotechnical and Geoenvironmental Engineering 132(2):131-142.
• Lu, N., Godt, J. W. and Wu, D. T. (2010). A closed-form equation for effective stress in unsaturated soil. Water Resources Research 46, W05515.
• Lyasko, M. (2010). Slip sinkage effect in soil-vehicle mechanics. Journal of Terramechanics 47(1):21-31.
• McKyes, E. (1985). Soil Cutting and Tillage. Elsevier, Amsterdam.
• Pollen, N. and Simon, A. (2005). Estimating the mechanical effects of riparian vegetation on stream bank stability using a fiber bundle model. Water Resources Research 41, W07025.
• Rawls, W. J., Brakensiek, D. L. and Miller, N. (1983). Green-Ampt infiltration parameters from soils data. Journal of Hydraulic Engineering 109(1):62-70.
• Reece, A. R. (1965). Principles of soil-vehicle mechanics. Proceedings of the Institution of Mechanical Engineers 180(2A):45-66.
• Robertson, P. K. and Cabal, K. L. (2015). Guide to Cone Penetration Testing for Geotechnical Engineering, 6th edition. Gregg Drilling and Testing, Signal Hill, California.
• Terzaghi, K. (1943). Theoretical Soil Mechanics. John Wiley and Sons, New York.
• USDA Natural Resources Conservation Service (2008). Soil Quality Indicators: Bulk Density.
• van Genuchten, M. Th. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal 44(5):892-898.
• Vesic, A. S. (1973). Analysis of ultimate loads of shallow foundations. Journal of the Soil Mechanics and Foundations Division 99(SM1):45-73.
• Wong, J. Y. (2008). Theory of Ground Vehicles, 4th edition. John Wiley and Sons, Hoboken, New Jersey.
• Wroth, C. P. and Wood, D. M. (1978). The correlation of index properties with some basic engineering properties of soils. Canadian Geotechnical Journal 15(2):137-145.
• Wu, T. H., McKinnell, W. P. and Swanston, D. N. (1979). Strength of tree roots and landslides on Prince of Wales Island, Alaska. Canadian Geotechnical Journal 16(1):19-33.
• Zoz, F. M. and Grisso, R. D. (2003). Traction and Tractor Performance. ASAE Distinguished Lecture Series 27. American Society of Agricultural Engineers, St. Joseph, Michigan.

The values of each group in the soil library come from these sources.

Group	Source
Water retention	Carsel and Parrish (1988), class means of the van Genuchten parameters.
Bekker moduli	Wong (2008), Table 2.3. Sand is a geometric mean of two sands. Loamy sand and silt loam are interpolations.
Shear deformation modulus	Wong (2008), Section 2.4.
Density states	Firm values agree with the soil survey of ACRE. Maximum values from USDA (2008).
Atterberg limits, drained strength	Typical values of the texture class.
Undrained strength	Wroth and Wood (1978). Conductivity from Rawls, Brakensiek and Miller (1983).
Suction stress	Lu and Likos (2006), Lu, Godt and Wu (2010).
Bearing factors	Prandtl and Reissner factors, Vesic (1973), Reece (1965).
Cone index	The form of Ayers and Perumpral (1982). The coefficients give the ASABE D497 reference values.
Rubber interface	Trends of Wong (2008), Table 1.3. The values are estimates.
Metal interface	Ranges of McKyes (1985) with the moisture trend of Fountaine (1954). The values are estimates.
Traffic compaction, root cohesion	Håkansson (1990), Wu and others (1979), Pollen and Simon (2005), De Baets and others (2008).