AcresSoilModel.h#

Acres/Source/Acres/AcresSoilModel.h Generated

Soil library and tyre-soil terramechanics (pure C++, no Unreal objects).

Three layers, all SI (metres, newtons, pascals, seconds; water contents in m3/m3 or kg/kg as named).

The soil library: seven USDA texture classes (sand to clay, including the ACRE silt loams and the Chalmers / Drummer type silty clay loams) with their water retention, density states, Atterberg limits, drained strength, Bekker pressure-sinkage reference, Janosi shear modulus, soil-rubber and soil-metal interface values and a cone-index law. Sources are cited per field in AcresSoilModel.cpp.

SoilStateAt evaluates a class at a water content, dry density and surface wetness. Moisture acts through physics, not a lookup: the suction stress of the van Genuchten curve (Lu and Likos) adds apparent cohesion (peaked in moist sand, rising as fines dry), fines near saturation load undrained with the Wroth and Wood strength of their liquidity index, and the Bekker moduli follow a bearing-capacity measure of the same state.

TyreOnSoil puts Wong's flexible / rigid tyre on that soil (inflation plus carcass pressure against the rigid-wheel ground pressure), with Lyasko slip sinkage, Bekker compaction and bulldozing resistance and the soil and interface shear capacity. BrixiusTraction gives the ASABE D497.7 reference the tests compare against.

AcresVehicleModel.cpp uses these when FGroundParameters::SoilClass (or FVehicleInput::SoilClass) selects a library class; the implement model can use the soil-metal values from SoilStateAt.

SoilClassCount#

Number of classes in the soil library (7).

int SoilClassCount();

SoilClassAt#

Library class by index, clamped to 0 .. SoilClassCount() - 1.

const FSoilClass& SoilClassAt(int Index);

FindSoilClass#

Library index of a class id ("sand", "loamy_sand", "sandy_loam", "loam", "silt_loam", "silty_clay_loam", "clay").

Argument	Description
`Id`	Class id, case sensitive. Null is allowed.

Returns: The index, or -1 when the id is unknown.

int FindSoilClass(const char* Id);

SoilClassFromTexture#

Library class for an ASABE D497 texture group (ESoilTexture in AcresVehicleModel.h), used when only the group is known (the pawn's soil map): fine -> silty clay loam, medium -> silt loam, coarse -> sandy loam.

Argument	Description
`Texture`	0 fine, 1 medium, 2 coarse (clamped).

Returns: A library index.

int SoilClassFromTexture(int Texture);

SoilThetaAtSuction#

Volumetric water content at a matric suction, from the class's van Genuchten curve.

theta = theta_r + (theta_s - theta_r) (1 + (alpha h)^n)^(-m), m = 1 - 1/n, with head h = suction / (rho_w g).

Argument	Description
`Class`	Library class.
`SuctionPa`	Matric suction, Pa (33 000 for field capacity, 1 500 000 for the wilting point).

Returns: Water content, m3/m3.

double SoilThetaAtSuction(const FSoilClass& Class, double SuctionPa);

SoilStateAt#

Evaluates a library class at a water content, density and surface wetness.

Suction from van Genuchten; suction stress sigma_s = Se psi (Lu and Likos 2006, Lu et al. 2010), capped at 150 kPa; drained strength c' + sigma_s tan(phi') and phi'. Fines (plasticity index > 0) near saturation load undrained: share smoothstep((Se - 0.8) / 0.2) * PI / (PI + 0.05) * 10 / (10 + Ks[mm/h]), strength c_u = S_t * 170 kPa * 100^(-LI) (Wroth and Wood 1978, remoulded; S_t the structure factor), friction 4 deg. The Bekker moduli scale with the Terzaghi-Vesic strip bearing capacity c N_c + 0.5 gamma B N_gamma (B = 0.5 m) relative to the class reference state (Reece's dimensionless pressure-sinkage form). Cone index from the Ayers-Perumpral law, blended toward N_k c_u (N_k = 15) where the soil is undrained. Interface friction falls from dry to wet with max(SurfaceWetness, wet-soil share).

Argument	Description
`ClassIndex`	Library index (clamped).
`Theta`	Volumetric water content, m3/m3.
`DensityMgM3`	Dry bulk density, Mg/m3; <= 0 means the class's FirmDensity.
`SurfaceWetness`	Rain film / puddling on the surface, 0..1 (FVehicleInput::Wetness).

Returns: The evaluated state.

FSoilState SoilStateAt(int ClassIndex, double Theta, double DensityMgM3, double SurfaceWetness = 0, double RootCohesionPa = 0);

Example

const FSoilState Wet = SoilStateAt(SoilClassSiltLoam, 0.40, 0, 0.8);
const double PullCapacityN = Wet.CohesionPa * AreaM2 + LoadN * std::tan(Wet.FrictionDeg * 3.14159 / 180);

SoilShearStrengthPa#

Shear strength of the soil at a normal stress: the drained Mohr-Coulomb line blended toward the undrained one (c_u, 4 deg) by the undrained share, taking the weaker of the two so wetting can only weaken the soil.

Argument	Description
`Soil`	Evaluated soil (SoilStateAt).
`NormalPa`	Normal stress on the shear surface, Pa.

Returns: Shear strength, Pa.

double SoilShearStrengthPa(const FSoilState& Soil, double NormalPa);

CompactedDensity#

Dry density after a rut of the given depth, by mass conservation in the compactable layer.

rho = rho0 * H / (H - kappa * rut), capped at MaxDensity, with kappa = 0.5 the share of rut volume taken up by compaction (the rest is pushed sideways). The farm's rut map (AcresFarmRuntime) feeds this through FVehicleInput::RutDepthM, so a second pass runs on denser, stronger soil.

Argument	Description
`Class`	Library class.
`BaseDensity`	Density before any rut, Mg/m3 (<= 0 means FirmDensity).
`RutDepthM`	Existing rut depth, m.
`LayerM`	Compactable layer thickness H, m (0.3 m, the farm's surface layer).

Returns: Dry density, Mg/m3.

double CompactedDensity(const FSoilClass& Class, double BaseDensity, double RutDepthM, double LayerM = .3);

DensityFromCompaction#

Density from the farm's 0..1 wheel-compaction value: FirmDensity + compaction * (MaxDensity - FirmDensity).

Argument	Description
`Class`	Library class.
`Compaction`	AcresFarm compaction 0..1.

Returns: Dry density, Mg/m3.

double DensityFromCompaction(const FSoilClass& Class, double Compaction);

HardSurfaceFriction#

Friction of a hard surface with a water film.

mu = mu_config * (1 - w * (1 - mu_wet / mu_dry)) with the wet-to-dry ratio of the surface from Wong (2008) Table 1.3 (asphalt 0.6/0.85, concrete 0.8/0.85, gravel 0.55/0.6 peak values); other indices keep the legacy 35 % loss.

Argument	Description
`SurfaceIndex`	0 asphalt, 1 concrete, 2 gravel (FVehicleInput::SurfaceIndex).
`DryFriction`	Configured dry friction coefficient (tractor.json surfaces).
`Wetness`	Water film 0..1.

Returns: Friction coefficient.

double HardSurfaceFriction(int SurfaceIndex, double DryFriction, double Wetness);

TyreDeflection#

Hard-ground deflection of a pneumatic tyre as an inflated toroidal membrane.

The ground plane cuts the torus (major radius R, crown radius b/2) in an ellipse of area 2 pi delta sqrt(R b / 2), which carries the load at the inflation plus carcass pressure: delta = W / (2 pi (p_i + p_c) sqrt(R b / 2)). So the vertical rate is 2 pi (p_i + p_c) sqrt(R b / 2): linear in pressure, as measured for tractor tyres.

Argument	Description
`WidthM`	Section width b, m.
`RadiusM`	Unloaded radius R, m.
`PressurePa`	Inflation plus carcass pressure, Pa.
`LoadN`	Vertical load, N.

Returns: Deflection, m (capped at 0.45 R).

double TyreDeflection(double WidthM, double RadiusM, double PressurePa, double LoadN);

TyreOnSoil#

Tyre on soil after Wong (2008), Section 2.7.

Rigid-wheel sinkage z0 = [3 W / ((3 - n)(kc + b kphi) sqrt(D))]^(2 / (2n + 1)) and ground pressure p_gcr = (kc / b + kphi) z0^n. If p_i + p_c >= p_gcr the tyre stays round (rigid mode, sinkage z0); otherwise its bottom flattens at p_i + p_c (flexible mode): z = ((p_i + p_c) / k)^(1/n), flat length W / (b (p_i + p_c)). Slip sinkage multiplies z by (1 + s) / (1 - 0.5 s) (Lyasko 2010). Compaction resistance b k z^(n+1) / (n+1) (Bekker); bulldozing b (0.67 c z K_pc + 0.5 z^2 gamma K_pgamma) with local-shear c, phi (Bekker 1960, Wong 2008) on the fresh sinkage, weighted by FSoilState::BulldozingShare. Contact length: flat half plus the front arc to the surface. Soil shear capacity with Bekker's grouser terms for the embedded lug height h (Wong 2008, Section 2.4): A c (1 + 2h/b) + W tan(phi) (1 + 0.64 (h/b) arccot(h/b)). Lugs that have not sunk in slide on the rubber-soil interface (c_a A + mu W): the interface limits a share 1 - (1 - LugAreaRatio) e of the contact, e the embedded fraction of the lug height.

Argument	Description
`Soil`	Evaluated soil (SoilStateAt).
`Tyre`	Tyre geometry, pressures and tread.
`LoadN`	Vertical load W, N.
`SlipRatio`	Slip used for slip sinkage (a smoothed \|slip\|, clamped to 0..0.9).
`RutDepthM`	Existing rut depth, m (bulldozing and compaction act only on sinkage below it).
`MaxSinkageM`	Sinkage cap, m.

Returns: Mode, footprint, sinkage, resistances and capacity.

FTyreContact TyreOnSoil(const FSoilState& Soil, const FTyreSpec& Tyre, double LoadN, double SlipRatio, double RutDepthM, double MaxSinkageM);

BrixiusTraction#

Brixius (1987) traction equations as adopted in ASAE D497.

Bn = (CI b d / W) (1 + 5 delta / h) / (1 + 3 b / d); GT / W = 0.88 (1 - e^(-0.1 Bn))(1 - e^(-7.5 s)) + 0.04; MR / W = 1 / Bn + 0.04 + 0.5 s / sqrt(Bn); NT = GT - MR. With Radial set, the radial-ply coefficients of the Zoz and Grisso (2003) tractor performance spreadsheet: 0.88 (1 - e^(-0.08 Bn))(1 - e^(-7 s)) + 0.03 and 1.2 / Bn + 0.03 + 0.5 s / sqrt(Bn).

Argument	Description
`ConeIndexPa`	Cone index CI, Pa.
`WidthM`	Unloaded section width b, m.
`DiameterM`	Unloaded diameter d, m.
`SectionHeightM`	Section height h, m.
`DeflectionM`	Tyre deflection delta, m.
`LoadN`	Wheel load W, N.
`Slip`	Travel reduction s, 0..1.
`bRadial`	Use the radial-ply coefficients.

Returns: Bn and the traction ratios.

FBrixiusTraction BrixiusTraction(double ConeIndexPa, double WidthM, double DiameterM, double SectionHeightM, double DeflectionM, double LoadN, double Slip, bool bRadial = false);

ESoilClass#

enum ESoilClass : int

Texture classes of the soil library, in library order (index into SoilClassAt).

Value	Description
`SoilClassSand`	Sand.
`SoilClassLoamySand`	Loamy sand.
`SoilClassSandyLoam`	Sandy loam.
`SoilClassLoam`	Loam.
`SoilClassSiltLoam`	Silt loam (most ACRE map units: Raub, Brenton, Crosby, Miami, Rockfield ...).
`SoilClassSiltyClayLoam`	Silty clay loam (ACRE Chalmers, Pella, Milford, Peotone; Drummer type).
`SoilClassClay`	Clay.

FSoilClass#

struct FSoilClass

One texture class of the soil library. All fields SI; see AcresSoilModel.cpp for the value table and sources.

Name	Type	Description
`Id`	`const char*`	Id: key used in tractor.json ("silt_loam"). Label: display name. Source: where the numbers come from.
`SandPct, ClayPct`	`double`	SandPct, ClayPct: representative texture, % by mass (informational).
`ThetaResidual, ThetaSaturated, VgAlphaPerM, VgN`	`double`	van Genuchten (1980) retention: ThetaResidual, ThetaSaturated, m3/m3; VgAlphaPerM, 1/m; VgN, dimensionless (Carsel and Parrish 1988 class means).
`LooseDensity, FirmDensity, MaxDensity`	`double`	Dry bulk density states, Mg/m3 (= g/cm3): LooseDensity freshly tilled, FirmDensity settled / untilled (the default), MaxDensity the root-restricting compaction limit ruts cannot exceed.
`LiquidLimit, PlasticLimit`	`double`	Atterberg limits as gravimetric water content, kg/kg. Both 0 for non-plastic soils.
`LooseCohesionPa, FirmCohesionPa, LooseFrictionDeg, FirmFrictionDeg`	`double`	Drained (effective-stress) Mohr-Coulomb strength at the loose and firm densities: cohesion, Pa; friction angle, degrees. Interpolated linearly in density between the two states.
`BekkerN, BekkerKc, BekkerKphi`	`double`	Bekker pressure-sinkage reference p = (kc / b + kphi) z^n at the reference state below: BekkerN, dimensionless; BekkerKc, N/m^(n+1); BekkerKphi, N/m^(n+2). From Wong's terrain table (see the .cpp).
`ReferenceDensity, ReferenceSaturation`	`double`	Reference state the Bekker values describe: dry density, Mg/m3, and effective saturation, 0..1.
`LooseJanosiM, FirmJanosiM`	`double`	Janosi-Hanamoto shear deformation modulus K at the loose and firm densities, m.
`RubberFrictionDry, RubberFrictionWet, RubberAdhesionPa`	`double`	Soil-rubber interface: friction coefficient on a dry and on a wet (smeared) surface, dimensionless; adhesion, Pa.
`MetalFrictionDryDeg, MetalFrictionWetDeg, MetalAdhesionPa`	`double`	Soil-metal interface (tillage tools): friction angle dry and wet, degrees; peak adhesion, Pa (reached near the plastic limit for plastic soils, near field capacity for non-plastic ones).
`ConeIndexPa, ConeWidth, ConePeak, ConeDensityExponent, ConeShapeExponent`	`double`	Cone index law in the Ayers and Perumpral (1982) form CI = C1 rho^e / (C2 + (w - C3)^2)^q, normalised so that ConeIndexPa is the cone index at FirmDensity and effective saturation 0.6: ConeIndexPa, Pa; ConeWidth C2, (kg/kg)^2; ConePeak C3, kg/kg; ConeDensityExponent e; ConeShapeExponent q (1 is the published form and keeps the moist-sand peak; 1.5 for fines, whose peak lies at the dry end, gives a Busscher-like power-law fall CI ~ w^-3 on the wet side).
`BulldozingShare`	`double`	Share of the Bekker bulldozing resistance that acts in this soil when loose (1 for sand, which cannot compact and must be pushed aside; small for compressible fines). Scaled down to 0 at FirmDensity.
`StructureFactor`	`double`	Ratio of intact to remoulded undrained strength (soil structure / sensitivity) applied to Wroth and Wood's remoulded strength, dimensionless.
`ConductivityMmH`	`double`	Saturated hydraulic conductivity of the texture class, mm/h (Rawls, Brakensiek and Miller 1983). Sets how much of a wet soil's response to a passing tyre is undrained (a tight soil cannot drain in a fraction of a second).

FSoilState#

struct FSoilState

Soil at one point: a library class evaluated at a water content, density and surface wetness. SI.

Name	Type	Unit	Default	Description
`Class`	`int`		`SoilClassLoam`	Class: library index. Theta: volumetric water content, m3/m3. DensityMgM3: dry bulk density, Mg/m3. Saturation: effective saturation Se, 0..1. Gravimetric: water content, kg/kg. LiquidityIndex: (w - PL) / PI (0 for non-plastic soils).
`SuctionPa`	`double`	Pa	`0`	Matric suction, Pa.
`SuctionStressPa`	`double`	Pa	`0`	Lu-Likos suction stress Se * suction (capped), Pa.
`UndrainedPa`	`double`	Pa	`0`	Wroth-Wood undrained strength times the structure factor, Pa.
`UndrainedShare`	`double`		`0`	0..1 weight of the undrained response (fines near saturation).
`CohesionPa, FrictionDeg, DrainedCohesionPa, DrainedFrictionDeg`	`double`			Representative Mohr-Coulomb pair for a tyre or tool: CohesionPa (includes the apparent cohesion from suction), Pa; FrictionDeg, degrees; the drained / undrained blend at 100 kPa normal stress (SoilShearStrengthPa gives it at any stress). DrainedCohesionPa: c' + sigma_s tan(phi'), Pa. DrainedFrictionDeg: phi', degrees.
`BekkerKc, BekkerKphi, BekkerN, BearingRatio`	`double`			Bekker moduli at this state: BekkerKc, N/m^(n+1); BekkerKphi, N/m^(n+2); BekkerN. BearingRatio: the bearing-capacity measure of this state over that of the class's reference state (the scale on kc, kphi).
`JanosiKM`	`double`		`.02`	Shear deformation modulus, m.
`UnitWeightNm3`	`double`		`15000`	Moist unit weight, N/m3.
`Looseness`	`double`		`0`	1 at LooseDensity, 0 at FirmDensity and above.
`ConeIndexPa`	`double`	Pa	`0`	ConeIndexPa: cone index (ASABE S313 cone), Pa.
`RubberFriction, RubberAdhesionPa`	`double`			Soil-rubber interface this step: RubberFriction, dimensionless; RubberAdhesionPa, Pa.
`MetalFrictionDeg, MetalAdhesionPa`	`double`			Soil-metal interface (for tillage tools): MetalFrictionDeg, degrees; MetalAdhesionPa, Pa.
`BulldozingShare`	`double`		`0`	BulldozingShare: the class share scaled by looseness, 0..1.
`RootCohesionPa`	`double`	Pa	`0`	RootCohesionPa: root reinforcement of a sod (grass lane, verge, lawn) added to the drained and undrained strength, Pa (0 on field soil). See SoilStateAt.

FTyreContact#

struct FTyreContact

Pneumatic tyre on deformable soil (and its hard-ground footprint), SI. Output of TyreOnSoil.

Name	Type	Unit	Default	Description
`Mode`	`int`		`0`	Mode: 0 hard ground, 1 flexible tyre (flat section at inflation + carcass pressure), 2 rigid wheel.
`DeflectionM`	`double`	m	`0`	Tyre deflection, m.
`FlatLengthM`	`double`	m	`0`	Flattened section length, m.
`LengthM`	`double`	m	`0`	Total contact length along travel (the Janosi shear length), m.
`AreaM2`	`double`		`0`	Shear area, m2.
`PressurePa`	`double`	Pa	`0`	Mean ground pressure, Pa.
`StaticSinkageM`	`double`	m	`0`	Sinkage without slip, m.
`SinkageM`	`double`	m	`0`	With slip-sinkage, capped, m.
`CompactionN`	`double`	N	`0`	Bekker compaction resistance of the fresh rut, N.
`BulldozingN`	`double`	N	`0`	Bulldozing resistance, N.
`SoilCapacityN`	`double`	N	`0`	Soil shear capacity c A + W tan(phi), N.
`CapacityN`	`double`	N	`0`	Limit after the rubber interface, N.
`CriticalPressurePa`	`double`	Pa	`0`	CriticalPressurePa: Wong's rigid-wheel ground pressure p_gcr, Pa.

FTyreSpec#

struct FTyreSpec

A pneumatic tyre for TyreOnSoil. SI.

Name	Type	Unit	Default	Description
`WidthM`	`double`	m	`.5`	Section width b, m.
`RadiusM`	`double`	m	`.8`	Unloaded radius R, m.
`InflationPa`	`double`	Pa	`0`	Inflation pressure p_i, Pa (0 = treat the tyre as a rigid wheel).
`CarcassPa`	`double`	Pa	`20000`	Carcass stiffness pressure p_c, Pa.
`LugHeightM`	`double`	m	`0`	Tread lug height, m (0 = smooth).
`LugAreaRatio`	`double`		`.25`	Share of the envelope the lug faces cover.

FBrixiusTraction#

struct FBrixiusTraction

ASABE D497.7 / Brixius (1987) traction of one tyre, the reference the tests compare against.

Name	Type	Default	Description
`MobilityNumber`	`double`	`0`	Bn.
`GrossRatio`	`double`	`0`	GT / W.
`MotionRatio`	`double`	`0`	MR / W.
`NetRatio`	`double`	`0`	NT / W.
`TractiveEfficiency`	`double`	`0`	(1 - s) NT / GT.