Skip to content

AcresVehicleModel.h#

Acres/Source/Acres/AcresVehicleModel.h Generated

Tractor dynamics: tyres, soil contact, suspension, drivetrain and steering (pure C++, no Unreal objects).

Everything here is SI (metres, newtons, seconds, radians). The functions compute forces and wheel/engine state only; Chaos (Unreal's physics engine) integrates the chassis. AAcresVehiclePawn::AsyncPhysicsTickActor (AcresVehicle.cpp) runs on the physics thread at a fixed 120 Hz and each step calls StepSteering, StepDrivetrain, PrepareWheel once per wheel, SolveDriveline once (the wheels are coupled through the differentials and the front-axle drive), and applies the resulting wheel forces to the Chaos body. The implement draft model (ASABE D497.7) lives here too.

No Unreal types appear here, so the maths compiles and can be tested without the engine.

Two soil models share this code. With a soil library class (FGroundParameters::SoilClass or FVehicleInput::SoilClass >= 0) the soil comes from AcresSoilModel.h (moisture, density, inflated tyres, slip sinkage, bulldozing, transient Janosi shear) and the motion resistance acts on the axle; without one, the fixed legacy soil below is used exactly as before. Fuel and the energy ledger (AcresPowerModel.h) run in both.

Lag#

Exact first-order lag step: moves Current toward Target with time constant Tau.

Returns Target + (Current - Target) * exp(-Dt / Tau), which is stable for any Dt. Tau is floored at 1e-4 s.

Argument Description
Current Present value.
Target Value being approached.
Dt Step length, s.
Tau Time constant, s.

Returns: The new value, same units as Current.

double Lag(double Current, double Target, double Dt, double Tau);

Clutch#

Torque a friction clutch passes in one step, for an explicit (one-sided) coupling.

Kept as a utility; the vehicle's own clutch is now solved implicitly with the wheels in SolveDriveline.

The torque that would bring engine and shaft to the same speed within one step, (We - Ws) / (Dt * (1/Je + 1/Js)), clamped to +/- CapacityNm. So a locked clutch behaves as a rigid coupling and a slipping one passes its full capacity.

Argument Description
EngineRadS Engine speed, rad/s.
ShaftRadS Gearbox input shaft speed (wheel speed reflected through the gearing), rad/s.
EngineInertia Engine inertia, kg m2.
ShaftInertia Driveline inertia reflected to the shaft, kg m2.
CapacityNm Present torque capacity (rated capacity times engagement), N m.
Dt Step length, s.

Returns: Clutch torque, N m. Positive drives the wheels.

double Clutch(double EngineRadS, double ShaftRadS, double EngineInertia, double ShaftInertia, double CapacityNm, double Dt);

SoilContact#

Soil footprint and strength under one tyre.

Bekker's pressure-sinkage law gives how deep the tyre sinks; Mohr-Coulomb (cohesion plus friction on the contact pressure, with a van Genuchten suction term for moist soil) gives how much shear force the soil can take before the tyre spins out. Wetter soil (higher Theta) has a lower Bekker modulus, so it sinks more, and less suction.

Argument Description
P Soil parameters, usually loaded from the "soil" block of tractor.json.
WidthM Tyre width, m.
RadiusM Unloaded tyre radius, m.
LoadN Vertical load on the tyre, N.
Theta Volumetric water content of the soil, m3/m3.

Returns: Contact length and area, pressure, sinkage, shear capacity (CapacityN), compaction resistance and suction, all SI.

FSoilContact SoilContact(const FGroundParameters& P, double WidthM, double RadiusM, double LoadN, double Theta);

Example

const FSoilContact C = SoilContact(Ground, 0.46, 0.87, 23000.0, 0.25);
const double MaxPullN = C.CapacityN;

JanosiForce#

Traction force from slip with Janosi-Hanamoto shear build-up.

F = sign(s) * CapacityN * (1 - exp(-|s| * L / (2K))). The shear displacement is taken at mid patch (s * L / 2), so short patches or stiff soil (small K) reach full traction at lower slip.

Argument Description
SlipRatio Longitudinal slip ratio s, dimensionless.
CapacityN Maximum shear force, N.
LengthM Contact patch length L, m.
KM Shear deformation modulus K, m.

Returns: Longitudinal force, N. Same sign as the slip.

double JanosiForce(double SlipRatio, double CapacityN, double LengthM, double KM);

WaterDrag#

Quadratic drag of standing water on a wheel.

F = -0.5 * rho * Cd * A * |v| * v with water density rho = 1000 kg/m3.

Argument Description
VelocityMps Contact point velocity, m/s (the caller passes the horizontal part only).
AreaM2 Wetted frontal area, m2 (negative values count as zero).
Cd Drag coefficient, dimensionless.

Returns: Drag force vector, N, opposing the velocity.

FVector3d WaterDrag(const FVector3d& VelocityMps, double AreaM2, double Cd);

SuspensionLoad#

Vertical wheel load from the suspension spring, bump stop and damper.

N = clamp(StaticLoad + K(c - c_rest) + BumpStiffnessmax(0, c - c_bump)^2 - Cv, 0, 6StaticLoad). The spring is pre-loaded so that c_rest of compression carries the static load; beyond c_bump a quadratic bump stop takes over. Load never goes negative (a wheel cannot pull the ground) and is capped at six times static. The tractor uses c_rest = 0.15 m and c_bump = 0.35 m (the defaults); the UTV model (AcresUtvModel.h) sets its own through FVehicleParameters::SuspensionRestM and BumpStopM.

Argument Description
Stiffness Combined tyre and axle spring rate K, N/m.
Damping Damper rate C, N s/m.
StaticLoad Wheel load at rest, N.
CompressionM Suspension compression c, m.
NormalSpeedMps Contact point velocity along the ground normal, m/s (negative when compressing).
BumpStiffness Quadratic bump-stop rate, N/m2.
RestCompressionM Compression c_rest that carries the static load, m.
BumpStopM Compression c_bump where the bump stop starts, m.

Returns: Normal load, N.

double SuspensionLoad(double Stiffness, double Damping, double StaticLoad, double CompressionM, double NormalSpeedMps, double BumpStiffness = 1000000, double RestCompressionM = .15, double BumpStopM = .35);

Longitudinal#

Longitudinal tyre force for a given wheel speed.

Two regimes: on soil (ContactLength > 0) Janosi-Hanamoto build-up of the soil shear capacity; on a hard surface Capacity * tanh(k s), a smooth, stiff friction curve (k = 9, the tractor's default, saturates by about 20 % slip).

Argument Description
Omega Wheel spin rate, rad/s.
Radius Rolling radius, m.
Speed Contact point speed along the wheel heading, m/s.
Load Normal load, N.
Limit Friction-circle limit left after the lateral force, N.
Capacity Friction or shear capacity as a ratio of load, dimensionless.
ContactLength Patch length, m; > 0 selects the Janosi soil branch.
JanosiK Shear deformation modulus, m.
SlipStiffness Hard-surface slip stiffness k (initial slope of force / (capacity x load) per unit slip).

Returns: Longitudinal force, N, clamped to +/- Limit. Positive pushes the tractor forward.

double Longitudinal(double Omega, double Radius, double Speed, double Load, double Limit, double Capacity, double ContactLength = 0, double JanosiK = .025, double SlipStiffness = 9);

ResetVehicle#

Resets the vehicle state and derives per-wheel constants.

Sets radius and width per axle, static load from the mass and centre of mass position (60 % of the wheelbase ahead of the body origin to the front axle, 40 % behind to the rear), the series tyre/axle spring and a damper for the requested damping ratio. A trailer spreads (1 - HitchTransfer) of its weight evenly over its wheels.

Argument Description
P Vehicle parameters.
S State to reset, overwritten. 
void ResetVehicle(const FVehicleParameters& P, FVehicleState& S);

StepDrivetrain#

Advances the engine and gearbox side of the drivetrain by one step.

Picks the gear (a change opens the clutch for ShiftTimeS), computes engine torque from the throttle, torque curve, power cap, speed governor and idle governor (and the all-speed governor droop when GovernorDroopRpm > 0; no fuel from an empty modelled tank), moves the clutch engagement, and works out the engine speed the step would end at with the clutch open (after engine drag and the PTO and hydraulic loads of the parameters plus the controls) and the clutch capacity (engagement times the anti-stall fade). Writes EngineTorqueNm, ClutchEngagement, Gear, ShiftRemainingS, DriveRatio, FreeEngineRadS, ClutchCapacityNowNm and the ledger hand-over (DragTorqueNm, AccessoryTorqueNm, PtoShaftW, HydraulicW). The clutch torque, engine speed and wheel torque are then solved implicitly together with the wheels in SolveDriveline. Does nothing but zero the torques on a trailer.

Argument Description
Dt Step length, s (1/120).
P Vehicle parameters.
Input Driver controls (Throttle, Brake, Direction, Gear, PtoKW, HydraulicKW).
S Vehicle state, updated.

Note

Call after StepSteering and before PrepareWheel / SolveDriveline, once per physics step.

void StepDrivetrain(double Dt, const FVehicleParameters& P, const FVehicleInput& Input, FVehicleState& S);

StepSteering#

Advances the steering actuator by one step and sets the front wheel angles.

The command passes through a pure delay (SteerDelayS), a first-order lag (SteerTauS), the lock limit and a rate limit, then Ackermann geometry sets wheels 0 and 1. Also advances S.TimeS by Dt, so call it exactly once per step.

Argument Description
Dt Step length, s.
P Vehicle parameters.
Input Driver controls (SteeringRadians).
S Vehicle state, updated. 
void StepSteering(double Dt, const FVehicleParameters& P, const FVehicleInput& Input, FVehicleState& S);

PrepareWheel#

Contact phase of one wheel: normal load, sinkage, lateral force and the limits its spin solve needs.

Normal load comes from the suspension; on soil it is solved together with sinkage by bisection. The lateral force follows a slip-angle law with relaxation length, limited by the friction or soil shear capacity. The longitudinal force limit left over (friction circle), grip, patch length, rolling resistance plus brake torque and the wheel inertia are stored in S.Wheels[Index] for SolveDriveline. The wheel spin is not changed here. On library soil the soil state (AcresSim::SoilStateAt at the input's water content, density raised by the rut, surface wetness) and Wong's tyre (AcresSim::TyreOnSoil) give sinkage, contact, capacity and the soil motion resistance (MotionResistanceN, applied on the axle by SolveDriveline); the tyre's hysteresis stays a torque. Hard surfaces use the wet-film friction of AcresSim::HardSurfaceFriction when the library is on.

Argument Description
Dt Step length, s.
Index Wheel index 0..3.
P Vehicle parameters.
Input Controls plus the surface under this wheel (see SampleSurface in AcresVehicle.cpp).
Sample Ground probe for this wheel.
S Vehicle state, updated. 
void PrepareWheel(double Dt, int Index, const FVehicleParameters& P, const FVehicleInput& Input, const FWheelSample& Sample, FVehicleState& S);

SolveDriveline#

Spin phase: solves all wheel speeds together through the differentials and sets the longitudinal forces.

Driveline layout. Each driven axle has a differential. Open (the default), it splits the axle torque equally between its two wheels and lets their speeds differ (so the outer wheel can run faster in a turn); the axle's carrier speed is the mean of its wheel speeds. Locked (Controls.DiffLock), it forces both wheels to one speed and the torque goes wherever the grip is. With FrontDrive (MFWD) there is no centre differential: the front carrier is geared rigidly to the rear one so the front tyres roll (1 + FrontLeadRatio) times faster, and the torque split between the axles comes out of that constraint. Without FrontDrive the front wheels roll freely.

Clutch. The engine is part of the same solve: if the clutch can hold, engine and gearbox input end the step at the same speed (a locked clutch is rigid); if that would need more than the clutch capacity, it slips and passes exactly its capacity. Releasing the throttle opens the clutch, so there is still no engine braking.

Numerics. Everything is backward Euler (speeds at the end of the step), because tyre force is very stiff in slip and the engine, reflected through a low gear, is hundreds of times heavier than the tractor. The torque a wheel needs to end the step at speed w is explicit, J (w - w_old) / Dt + Fx(w) r + resist tanh(w / 0.1), and rises with w. So for a rear carrier speed c the torque the whole driveline needs is found directly (a locked axle) or with one bisection for the open-differential speed split, and it rises with c. The engine side falls with c. One bisection on c balances the two. Free-rolling wheels (2WD front, trailer) are solved on their own.

Library soil. The tyre force comes from a transient shear displacement (FWheelState::ShearDisplacementM) that relaxes over half the contact length, so its steady value is the Janosi law of the slip while a parked tyre acts as a tread spring; FxN is the soil shear minus the motion resistance (on the axle, against travel, faded out near standstill and limited so it cannot reverse the wheel's share of the chassis within one step).

Energy. Fuel (Willans map) and the powertrain side of the ledger (S.Energy, S.Power) are filled from the torques and mid-step speeds the solve used, so fuel minus every loss and store closes to the solver tolerance.

Argument Description
Dt Step length, s.
P Vehicle parameters.
Controls Driver controls (DiffLock is read here; brakes come from the per-wheel inputs via PrepareWheel).
S Vehicle state, updated. Reads the StepDrivetrain hand-over and the PrepareWheel data; writes ClutchTorqueNm, ClutchHeatJ, Rpm and WheelTorqueNm (torque at the rear carrier), Omega, Spin, SlipRatio, FxN, ShearN, SinkageSlip, ShearDisplacementM and DriveTorqueNm of every wheel, and the fuel, distance and ledger fields. 
void SolveDriveline(double Dt, const FVehicleParameters& P, const FVehicleInput& Controls, FVehicleState& S);

Example

StepSteering(Dt, P, Controls, S);
StepDrivetrain(Dt, P, Controls, S);
for (int I = 0; I < P.WheelCount; ++I)
    PrepareWheel(Dt, I, P, SurfaceUnderWheel[I], Samples[I], S);
SolveDriveline(Dt, P, Controls, S);

AccountChassis#

Adds the chassis side of one step to the energy ledger (S.Energy cumulative, S.Power this step).

Call after the chassis has been integrated. The work terms should use mid-step speeds, (v_start + v_end) / 2, for the ledger to close to round-off with a semi-implicit integrator.

Argument Description
Dt Step length, s.
S Vehicle state, updated.
DrawbarW Power pulling the implement, W (draft x speed, >= 0 when pulling). AeroW, WaterW: Air and standing-water drag power, W (>= 0).
LateralW Tyre side-slip loss, W (minus the lateral forces' power on the chassis).
SuspensionW Minus the power of the ground normal forces on the chassis, W.
KineticChangeJ Chassis kinetic energy change this step (translation and rotation), J.
PotentialChangeJ Chassis potential energy change this step, J. 
void AccountChassis(double Dt, FVehicleState& S, double DrawbarW, double AeroW, double WaterW, double LateralW, double SuspensionW, double KineticChangeJ, double PotentialChangeJ);

FrontCarrierRatio#

Front differential carrier speed per unit of rear carrier speed for a rigid MFWD front drive.

k = (1 + FrontLeadRatio) * RearRadiusM / FrontRadiusM, so the front tyres' rolling speed omega * r leads the rear by FrontLeadRatio.

Argument Description
P Vehicle parameters.

Returns: The kinematic ratio k, dimensionless.

double FrontCarrierRatio(const FVehicleParameters& P);

RisingRoot#

Root of a function that rises with X, by bracketing and bisection.

Starts from [Guess - Step, Guess + Step], widens each end (doubling the step) until the function changes sign across the bracket, then bisects Iterations times. The driveline solves (SolveDriveline, AcresSim::SolveUtvDriveline) use it for every implicit wheel, carrier and clutch balance.

Argument Description
Function Callable double(double), non-decreasing in its argument.
Guess Centre of the first bracket.
Step Half-width of the first bracket (> 0).
Iterations Bisection steps after bracketing.

Returns: The midpoint of the final bracket.

template <typename TFunction> double RisingRoot(const TFunction& Function, double Guess, double Step, int Iterations) ;

WheelShaftTorqueNm#

Shaft torque a wheel needs to end this step spinning at Omega (the driveline building block).

Backward Euler: J (Omega - W.Omega) / Dt + tyre force x radius + (rolling resistance + brake) x tanh(Omega / 0.1), with the tyre force of the contact data PrepareWheel stored in W (Janosi on soil, the tanh friction curve on hard ground, transient shear on library soil; 0 when airborne). Rises monotonically with Omega.

Argument Description
Dt Step length, s.
P Vehicle parameters (legacy Janosi K, hard-surface slip stiffness).
W Wheel state after PrepareWheel.
OmegaRadS Trial end-of-step spin rate, rad/s.

Returns: Shaft torque, N m (positive drives the wheel forward).

double WheelShaftTorqueNm(double Dt, const FVehicleParameters& P, const FWheelState& W, double OmegaRadS);

FreeWheelSpeedRadS#

End-of-step spin rate of a wheel with no drive shaft: the speed at which it needs zero shaft torque, rad/s.

Argument Description
Dt Step length, s.
P Vehicle parameters.
W Wheel state after PrepareWheel.

Returns: Spin rate, rad/s.

double FreeWheelSpeedRadS(double Dt, const FVehicleParameters& P, const FWheelState& W);

AxleCarrierTorqueNm#

Torque an axle's differential carrier needs to turn at CarrierRadS by the end of the step.

Wheels Left and Left + 1. Locked: both wheels at the carrier speed. Open: the differential makes the two shaft torques equal while their speeds average to the carrier speed (one bisection). The carrier torque is the sum of the two shaft torques; it rises with the carrier speed.

Argument Description
Dt Step length, s.
P Vehicle parameters.
S Vehicle state after PrepareWheel.
Left Index of the axle's left wheel (0 front, 2 rear).
bLocked Differential locked (a spool).
CarrierRadS Trial carrier speed, rad/s.
OutRadS Receives the two wheel speeds, rad/s.

Returns: Carrier torque, N m.

double AxleCarrierTorqueNm(double Dt, const FVehicleParameters& P, const FVehicleState& S, int Left, bool bLocked, double CarrierRadS, double OutRadS[2]);

SettleWheels#

Last part of a driveline step, shared by SolveDriveline and AcresSim::SolveUtvDriveline.

Sets every wheel's spin (Omega, Spin), drive torque (the shaft torque at its new speed for driven wheels, 0 for free ones), soil shear and chassis force (shear minus the soil's motion resistance), slip, slip-sinkage state and transient shear, adds the axle-to-ground part of the energy ledger (wheel kinetic energy, axle work, hysteresis, brake, slip, soil and traction) to Step, then the distance, worked area, fuel per km and hectare and tractive efficiency, and finally adds Step to S.Energy and sets S.Power.

Argument Description
Dt Step length, s.
P Vehicle parameters.
OmegaRadS End-of-step spin of each wheel from the solve, rad/s.
Driven Per wheel, true when a shaft drives it (its drive torque is its shaft torque).
WorkingWidthM Implement working width for the worked area, m (0 = none).
Step This step's energy flows, with the engine-to-axle part already filled; completed here.
S Vehicle state, updated. 
void SettleWheels(double Dt, const FVehicleParameters& P, const double OmegaRadS[4], const bool Driven[4], double WorkingWidthM, FEnergyFlows& Step, FVehicleState& S);

TextureFromWilting#

Texture class from the wilting-point water content, the proxy the optimizer and the vehicle share.

Wilting point >= 0.19 m3/m3 is fine (the ACRE silty clay loams), <= 0.10 coarse, anything between medium.

Argument Description
WiltingTheta Volumetric water content at -1500 kPa, m3/m3.

Returns: SoilFine, SoilMedium or SoilCoarse.

int TextureFromWilting(double WiltingTheta);

ImplementTypeCount#

Number of entries in the implement table.

int ImplementTypeCount();

ImplementTypeAt#

Implement table entry by index (0 .. ImplementTypeCount() - 1).

const FImplementType& ImplementTypeAt(int Index);

FindImplementType#

Implement table entry by id.

Argument Description
Id "moldboard", "chisel", "disk", "cultivator", "planter" or "potato_digger".

Returns: The entry, or nullptr when the id is unknown (for example "custom").

const FImplementType* FindImplementType(const char* Id);

AsabeDraftN#

ASABE D497.7 draft of one implement.

D = F_i (A + B S + C S^2) W T with the unit conventions of FImplementType. Speed is floored at 0 and depth at 0.

Argument Description
Type Implement table entry.
Texture SoilFine, SoilMedium or SoilCoarse (clamped).
SpeedKmh Ground speed, km/h.
WidthM Working width, m.
DepthCm Working depth, cm (ignored unless Type.bDepth).

Returns: Draft force, N.

double AsabeDraftN(const FImplementType& Type, int Texture, double SpeedKmh, double WidthM, double DepthCm);

Example

const FImplementType* Chisel = FindImplementType("chisel");
const double DraftN = AsabeDraftN(*Chisel, SoilMedium, 8.0, 3.0, 20.0); // 22.8 kN

ImplementDraftN#

Live draft for the pawn: ASABE for a known type, a speed-scaled reference value for a custom one.

Custom (Type null): D = ReferenceN * (1 + 0.06 S) / (1 + 0.06 S_ref). The 0.06 per km/h is the B/A ratio the ASABE table gives for the chisel plow, field cultivator and disk harrow (0.052-0.061), so a custom value behaves like a typical tillage tool around its design speed. Known type: AsabeDraftN.

Argument Description
Type Implement table entry, or nullptr for a custom implement.
ReferenceN Custom draft at ReferenceKmh, N (unused for a known type).
ReferenceKmh Speed at which ReferenceN applies, km/h.
Texture Soil texture class.
SpeedKmh Current (smoothed) ground speed, km/h.
WidthM Working width, m.
DepthCm Working depth, cm.

Returns: Draft force, N (>= 0).

double ImplementDraftN(const FImplementType* Type, double ReferenceN, double ReferenceKmh, int Texture, double SpeedKmh, double WidthM, double DepthCm);

FGroundParameters#

struct FGroundParameters

Deformable soil parameters, loaded from the "soil" block of tractor.json.

Bekker pressure-sinkage (kc, kphi, n), Mohr-Coulomb shear (cohesion, friction angle), van Genuchten water retention (theta_r, theta_s, alpha, n) for the suction term, and the Janosi shear deformation modulus: the legacy soil model, used when no library class is selected. Defaults describe a generic loam and are not field calibrated.

Name Type Unit Default Description
ThetaResidual double .06 Residual volumetric water content, m3/m3.
ThetaSaturated double .43 Saturated water content, m3/m3.
BekkerKc double 20000 Cohesive sinkage modulus, N/m^(n+1).
BekkerKphi double 2000000 Frictional sinkage modulus, N/m^(n+2).
BekkerN double N 1.1 Sinkage exponent, dimensionless.
SaturatedBekkerRatio double .4 Factor the Bekker modulus falls to at full saturation (linear in effective saturation).
MaxSinkageM double m .35 Cap on sinkage, m.
VgAlpha double 2 Van Genuchten alpha, 1/m.
VgN double N 1.6 Van Genuchten n (> 1), dimensionless.
SuctionCapPa double Pa 100000 Cap on matric suction, Pa.
CohesionPa double Pa 3000 Mohr-Coulomb cohesion, Pa.
FrictionDegrees double 28 Internal friction angle, degrees.
DeflectionRatio double .2 Tyre deflection as a fraction of half the radius (sets footprint length), dimensionless.
JanosiKM double .025 Janosi-Hanamoto shear deformation modulus K, m.
SoilClass int -1 Soil library class (AcresSoilModel.h, index into SoilClassAt) used on deformable ground; -1 (the default) keeps the fixed parameters above (the legacy model). With a class, moisture, density and tyre inflation act through the library physics, and of the fixed values above only MaxSinkageM is used.
DensityMgM3 double 0 Dry bulk density of undisturbed ground, Mg/m3 (0 = the class's firm density).
CompactionLayerM double m .3 Thickness of the layer a rut compacts, m (AcresSim::CompactedDensity).
ClassFromTexture bool false Read by the pawn only: take the class per wheel from the soil map (tractor.json soil.class "auto") instead of SoilClass everywhere.

FSoilContact#

struct FSoilContact

Soil footprint and strength under one tyre, SI units. Output of SoilContact.

Name Type Unit Default Description
LengthM double m 0 Contact patch length along travel, m.
AreaM2 double 0 Patch area, m2.
PressurePa double Pa 0 Mean ground pressure, Pa.
SinkageM double m 0 Sinkage capped at MaxSinkageM, m.
RawSinkageM double m 0 Uncapped Bekker sinkage, m.
CapacityN double N 0 Maximum shear (traction) force the soil can carry, N.
CompactionN double N 0 Bekker compaction resistance (work per metre to cut the rut), N.
SuctionPa double Pa 0 Matric suction used in the shear term, Pa.

FVehicleParameters#

struct FVehicleParameters

All vehicle constants, SI. Filled from the "vehicle", "soil" and "implement" blocks of tractor.json by AAcresVehiclePawn::LoadConfiguration; unlisted keys keep these defaults.

The defaults are fallbacks for keys missing from tractor.json, which holds the Case IH Maxxum 150 preset (not field calibrated). The pawn also edits a few fields at runtime (MassKg, CgForwardM and PtoKW change with a mounted implement or a filling grain bunker).

Name Type Unit Default Description
MassKg double kg 6200 Chassis mass, kg (includes a mounted implement after ConfigureBody).
WheelbaseM double m 2.58 Axle spacing, m.
TrackM double m 1.9 Left-right wheel spacing, m.
CgHeightM double m 1.1 Height of the tractor's own centre of mass above level, firm ground at rest, m. The body origin is placed at this height (the wheel mounts are measured from it) and the tractor's centre of mass sits at the origin; a mounted implement or harvest bunker then moves the combined centre of mass towards its own height (AAcresVehiclePawn::ConfigureBody).
CgForwardM double m 0 Forward offset of the centre of mass from the body origin, which sits 40 % of the wheelbase ahead of the rear axle, m.
FrontRadiusM, RearRadiusM, FrontWidthM, RearWidthM double FrontRadiusM, RearRadiusM: unloaded tyre radii, m. FrontWidthM, RearWidthM: tyre section widths, m.
FrontTireStiffness, RearTireStiffness, FrontAxleStiffness, RearAxleStiffness double FrontTireStiffness, RearTireStiffness: tyre vertical rates, N/m. FrontAxleStiffness, RearAxleStiffness: axle/suspension rates, N/m. Each wheel's spring is the tyre and axle in series.
SuspensionDamping double .7 Damping ratio zeta, dimensionless.
BumpStiffness double 1000000 Quadratic bump-stop rate, N/m2.
CorneringPerLoad double 5 Cornering stiffness per unit load, 1/rad.
LateralRelaxationM double m .6 Tyre relaxation length, m.
SuspensionRestM, BumpStopM, HardSlipStiffness double Suspension geometry for SuspensionLoad: SuspensionRestM, compression (0.5 m minus FWheelSample::SuspensionM) that carries the static load, m; BumpStopM, compression where the bump stop starts, m. HardSlipStiffness: hard-surface slip stiffness k of the tanh(k s) friction curve. The defaults are the tractor's; the UTV model (AcresUtvModel.h) sets its own.
SteerDelayS double s .12 Pure transport delay of the steering command, s.
SteerTauS double s .18 First-order lag, s.
SteerRateRadS double s .6981317008 Maximum steering rate, rad/s (0.698 = 40 deg/s).
MaxSteerRad double rad .6632251158 Steering lock, rad (0.663 = 38 deg).
IdleRpm double rev/min 800 See above.
MaxRpm double rev/min 2300 Idle and cut-off engine speeds, rev/min.
PeakTorqueNm double N·m 600 Peak of the torque curve, N m.
GearRatio double 4 Gearbox ratio used when no gear list is configured.
FinalDrive double 10 Axle ratio.
Efficiency double .9 Driveline efficiency, 0..1.
EngineInertia double 2 Kg m2.
EngineDragNm double N·m 15 Engine friction at idle speed (grows linearly with speed), N m.
ClutchCapacityNm double N·m 900 Clutch torque capacity, N m.
ClutchEngagementS double s .8 Time to fully engage or release, s.
PtoKW double kW 0 Constant power-take-off load, kW.
TorqueCurve std::vector&lt;FTorquePoint> Full-load torque curve (rpm, N m). Empty means use the built-in 9-point curve in AcresVehicleModel.cpp.
ForwardGears, ReverseGears std::vector&lt;double> ForwardGears, ReverseGears: gearbox ratios, index 0 = first gear. Empty falls back to GearRatio.
RatedPowerKW double kW 0 Rated power, kW (loaded but unused).
MaxPowerKW double kW 0 Power cap without boost, kW (0 = no cap).
BoostPowerKW double kW 0 Power cap with boost, kW.
MaxPtoKW double kW 0 PTO limit used only to validate PtoKW, kW.
MaxSpeedMps double m/s 0 Road speed governor, m/s (0 = none).
ShiftTimeS double s .3 Clutch-open time while changing gear, s.
FrontDrive bool true Four-wheel drive (front axle driven).
BoostEnabled bool false Use BoostPowerKW and scale the torque curve by BoostPowerKW / MaxPowerKW.
FrontLeadRatio double 0 Front-wheel lead of a mechanical front-wheel drive (MFWD), dimensionless: with FrontDrive the front axle is geared rigidly to the rear axle so that the front tyres' rolling speed is (1 + FrontLeadRatio) times the rear tyres' (0.015 = 1.5 % lead; typical tractors 1-5 %). 0 = matched speeds.
Trailer bool false True for the trailed implement: no engine, no steering, wheels all "rear" type.
HitchTransfer double .15 Fraction of the trailer's weight carried by the hitch, 0..1.
HitchToCgM double m 3.2 Hitch to trailer centre of mass distance, m.
WaterDragCd double 1.1 Water drag coefficient for wheels in standing water, dimensionless.
FrontInflationKPa, RearInflationKPa double Tyre inflation pressures, kPa. 0 (the default) keeps the legacy fixed-footprint tyre and the configured tyre stiffnesses; above 0 the tyre is an inflated membrane (AcresSim::TyreDeflection) whose vertical rate replaces Front/RearTireStiffness and, on library soil, follows Wong's flexible / rigid tyre model (AcresSim::TyreOnSoil).
CarcassKPa double kPa 20 Carcass stiffness expressed as a pressure p_c, kPa (Wong; ground pressure of the flat = p_i + p_c). FrontAspectRatio,
FrontAspectRatio double .85 See above.
RearAspectRatio double .85 Section height over width (0.65 for a /65 tyre), for Brixius' deflection term.
TyreHysteresis double .2 Rolling resistance per unit relative deflection, f = TyreHysteresis * deflection / section height (library soil with inflation; otherwise 0.01 on soil and the surface's rolling value on hard ground).
TyreLugHeightM, TyreLugAreaRatio, TyreTreadKM double Tread, used on library soil: TyreLugHeightM, lug height, m (0 = smooth tyre); TyreLugAreaRatio, share of the envelope covered by lug faces; TyreTreadKM, longitudinal shear compliance of tread and carcass expressed as a Janosi modulus, m, added in series to the soil's K (the tyre's own deformation takes part of the slip).
GovernorDroopRpm double rev/min 0 Engine governor droop, rev/min. 0 (the default): the pedal scales the full-load torque (legacy). Above 0: an all-speed governor; the pedal sets the no-load speed IdleRpm + pedal * (MaxRpm - IdleRpm) and fuelling falls linearly to zero over the droop band below it, so rpm droops under load as on a mechanical governor.
EngineDisplacementL, IndicatedEfficiency, FmepBar, FmepBarPerKrpm, FmepBarPerKrpm2 double Willans fuel map (AcresSim::WillansFuelPowerW): EngineDisplacementL, L; IndicatedEfficiency, 0..1; friction mean effective pressure FMEP = FmepBar + FmepBarPerKrpm * krpm + FmepBarPerKrpm2 * krpm^2, bar. Defaults: the Maxxum 150's FPT 6.7 L engine calibrated to OECD test 2974 (see AcresPowerModel.h).
FuelLhvMJKg double 42.8 Diesel lower heating value, MJ/kg.
FuelDensityKgL double L .835 Diesel density, kg/L.
FuelTankL double L 0 Tank capacity, L; 0 = the tank is not modelled (never runs dry).
PtoEfficiency double 1 PTO shaft power over the engine power it takes (1 = PtoKW is taken straight off the engine, the legacy meaning).
HydraulicKW double kW 0 Constant hydraulic power delivered to consumers, kW.
HydraulicEfficiency double .85 Hydraulic power over the engine power the pump takes.
WheelCount int 4 Number of wheels in use: 4 for the tractor, 2 for the trailer.
Ground FGroundParameters Deformable soil parameters.

FVehicleInput#

struct FVehicleInput

Driver controls plus the surface under one wheel, for one physics step.

The pawn keeps one copy holding the driver's controls; SampleSurface then makes a per-wheel copy with the surface fields filled from tractor.json "surfaces", the road mask and the farm water model.

Name Type Unit Default Description
Throttle double 0 Pedal 0..1.
Brake double 1 Pedal 0..1 (starts applied).
SteeringRadians double 0 Requested bicycle-model steering angle, rad, positive = left.
Direction double 1 +1 forward, -1 reverse.
Wetness double 0 Surface wetness 0..1 (lowers hard-surface friction by up to 35 %).
Theta double .20 Soil volumetric water content, m3/m3.
WaterDepthM double m 0 Standing water depth, m.
Friction double .8 Hard-surface friction coefficient.
Rolling double .025 Hard-surface rolling resistance coefficient.
RutDepthM double m 0 Existing rut depth at the contact, m.
Soil bool false True on deformable soil (Bekker/Mohr-Coulomb model), false on hard ground (friction model).
SurfaceIndex int -1 Surface override: 0..5 = asphalt, concrete, gravel, dry_soil, wet_soil, mud; 6 = mapped; -1 = config default.
Gear int -1 Selected gear, 0-based index into ForwardGears/ReverseGears; -1 = use GearRatio.
DiffLock int 0 Differential lock: 0 both axle differentials open, 1 rear locked, 2 rear and front locked (the front lock only matters with FrontDrive). L key in the pawn, -VehicleDiffLock= on the command line.
SoilClass int -1 Soil library class under this wheel (-1 = FGroundParameters::SoilClass). DensityMgM3: dry density of the undisturbed ground here, Mg/m3 (0 = FGroundParameters::DensityMgM3, then the class's firm density); ruts add compaction on top (AcresSim::CompactedDensity).
TrafficCompaction double 0 0..1 compaction of a trafficked lane or track, turned into a density with DensityFromCompaction when DensityMgM3 is 0 (0 keeps the firm density).
RootCohesionPa double Pa 0 Grass root reinforcement, Pa (SoilStateAt; 0 on bare soil).
PtoKW, HydraulicKW double Extra engine loads from implements this step, on top of the parameters' PtoKW and HydraulicKW: PtoKW, shaft power, kW; HydraulicKW, power delivered to hydraulic consumers, kW. Read from the controls by StepDrivetrain.
WorkingWidthM double m 0 Working width of an implement that is working, m (0 = none): accumulates worked area for fuel per hectare.

FWheelState#

struct FWheelState

State and last-step outputs of one wheel, SI.

Name Type Unit Default Description
RadiusM double m 0 Tyre radius, m.
WidthM double m 0 Tyre width, m.
StaticLoadN double N 0 Load at rest, N.
Spring double 0 Combined spring rate, N/m.
Damper double 0 Damper rate, N s/m.
Omega double 0 Spin rate, rad/s.
Spin double 0 Accumulated spin angle for the visual, rad.
Angle double 0 Steering angle, rad.
SuspensionM double m .35 Mount-to-wheel-centre extension, m (0.35 at rest; includes sinkage on soil).
NormalN double N 0 Ground normal load, N.
FxN double N 0 Longitudinal force on the chassis, N (on library soil the shear minus the soil's motion resistance).
FyN double N 0 Lateral force, N (positive toward the wheel's right).
SlipRatio double 0 Longitudinal slip.
LateralStateN double N 0 Relaxed lateral force state, N.
SinkageM double m 0 Sinkage or rut depth, m.
PressurePa double Pa 0 Ground pressure, Pa.
ShearCapacityN double N 0 Friction or soil shear limit, N.
ContactAreaM2 double 0 Footprint area, m2.
WaterDragN double N 0 Magnitude of water drag, N.
Contact bool false True when the wheel touches the ground with at least 1 N of load.
SurfaceIndex int -1 Surface index used this step (see FVehicleInput::SurfaceIndex).
Wetness double 0 Surface wetness 0..1 this step.
WaterDepthM double m 0 Standing water depth this step, m.
DriveTorqueNm double N·m 0 Torque the driveline put on this wheel's axle shaft this step, N m (after the differentials; positive drives forward). Output of SolveDriveline.
ForwardSpeedMps double m/s 0 Contact speed along the wheel heading, m/s.
LimitN double N 0 Longitudinal force limit left by the lateral force, N.
GripRatio double 0 Friction or soil shear capacity per unit load.
PatchLengthM double m 0 Soil contact length, m (0 on hard ground, which selects the friction curve).
ResistNm double N·m 0 Rolling resistance plus brake torque, N m.
InertiaKgM2 double 1 Wheel spin inertia, kg m2.
HysteresisNm, BrakeNm double Split of ResistNm: HysteresisNm, tyre rolling resistance torque; BrakeNm, brake torque (both N m, before the near-standstill fade).
ShearN double N 0 Soil shear (gross thrust) this step, N; FxN is ShearN minus the motion resistance.
MotionResistanceN double N 0 Soil compaction plus bulldozing resistance acting on the axle, N.
BulldozingN double N 0 Its bulldozing part, N.
JanosiKM double 0 Shear deformation modulus of the soil under the wheel, m.
DeflectionM double m 0 Tyre deflection on hard ground at this load (inflated tyres), m.
ContactLengthM double m 0 Contact length, m.
ConeIndexPa double Pa 0 Cone index of the soil under the wheel, Pa.
DensityMgM3 double 0 Its dry density after ruts, Mg/m3.
Theta double 0 Its water content, m3/m3.
TyreMode int 0 0 hard ground, 1 flexible tyre, 2 rigid wheel (AcresSim::FTyreContact::Mode).
SoilClass int -1 Library class used (-1 legacy soil or hard ground).
SinkageSlip double 0 Slip that drives slip sinkage: |slip| relaxed over the contact length travelled (state), dimensionless.
RelaxationM double m 0 Relaxation length, half the contact length, m (hand-over from PrepareWheel).
ShearDisplacementM double m 0 Janosi shear displacement at mid patch, m (state): it grows with the slip velocity and relaxes as the tread rolls through, so its steady value is slip x RelaxationM, the steady law, while at standstill the tyre acts as a tread spring instead of an infinitely stiff slip damper (which made a parked tractor chatter).

FWheelSample#

struct FWheelSample

Ground probe result for one wheel, measured by the pawn with a line trace. SI.

Name Type Unit Default Description
Hit bool false True when the trace hit ground.
SuspensionM double m .65 Distance from the wheel mount to the contact point minus the radius, m.
NormalSpeedMps double m/s 0 Contact point velocity along the ground normal, m/s. ForwardSpeedMps,
ForwardSpeedMps double m/s 0 See above.
LateralSpeedMps double m/s 0 Contact point velocity along the wheel heading and to its right, m/s.

FVehicleState#

struct FVehicleState

Everything the model integrates between steps: wheels, steering, engine and clutch.

Owned by the pawn and only touched on the physics thread; a copy of Wheels goes out in the telemetry.

Name Type Unit Default Description
Wheels std::array&lt;FWheelState, 4> Per-wheel state. Index 0 front left, 1 front right, 2 rear left, 3 rear right (trailer uses 0 and 1).
TimeS double s 0 Episode time since the last reset, s.
Steering double 0 Actual bicycle-model steering angle, rad.
Rpm double 800 Engine speed, rev/min.
ClutchEngagement double 0 0..1.
ClutchTorqueNm double N·m 0 Torque through the clutch, N m.
EngineTorqueNm double N·m 0 Engine output torque, N m.
WheelTorqueNm double N·m 0 Driveline torque at the rear differential carrier (clutch torque x overall ratio x efficiency; with MFWD part of it reaches the front axle), N m.
ClutchHeatJ double J 0 Accumulated clutch slip energy, J.
DriveRatio double 0 Gearbox x final drive, negative in reverse (gearbox input speed = DriveRatio x rear carrier speed).
FreeEngineRadS double s 0 Engine speed at the end of the step if the clutch were open, rad/s.
ClutchCapacityNowNm double N·m 0 Clutch torque capacity this step (engagement and anti-stall applied), N m.
Gear int -1 Gear index currently engaged (-1 = none configured).
ShiftRemainingS double s 0 Time left in the current gear change, s.
SteeringDelay std::deque&lt;std::pair&lt;double, double>> History of (time s, requested steering rad) used to delay the steering command by SteerDelayS.
DragTorqueNm, AccessoryTorqueNm, PtoShaftW, HydraulicW double More StepDrivetrain hand-over, at the start-of-step engine speed: DragTorqueNm, engine drag; AccessoryTorqueNm, PTO plus hydraulic load torque; PtoShaftW and HydraulicW, the power those loads deliver, W.
Energy, Power FEnergyFlows Energy ledger: Energy, cumulative since reset, J; Power, the last step, W. SolveDriveline fills the powertrain side; AccountChassis the chassis side.
FuelRateLph double L/h 0 Fuel flow this step, L/h.
FuelUsedL double L 0 Fuel burnt since reset, L.
FuelTankL double L 0 Fuel left, L (counts down only when FVehicleParameters::FuelTankL > 0; at 0 the engine gets no fuel).
DistanceM double m 0 Distance travelled (mean contact speed of the wheels on the ground), m.
AreaM2 double 0 Area worked (FVehicleInput::WorkingWidthM times distance), m2. FuelPerKmL,
FuelPerKmL double L 0 See above.
FuelPerHaL double L 0 Fuel since reset per km and per hectare worked, L (0 until 1 m / 1 m2).
TractiveEfficiency double 0 Net tyre work on the chassis over the work put into the axles this step, 0..1.

ESoilTexture#

enum ESoilTexture : int

Soil texture classes of ASABE D497.7 (the F1/F2/F3 columns of its draft table).

Value Description
SoilFine Clays and silty clay loams.
SoilMedium Loams and silt loams.
SoilCoarse Sands and sandy loams.

FImplementType#

struct FImplementType

One implement type for the ASABE D497.7 draft equation D = F_i (A + B S + C S^2) W T.

S is ground speed in km/h. W is the number of tools or rows (width / SpacingM) or, when SpacingM is 0, the working width in metres. T is the working depth in cm for tillage tools (bDepth) and 1 otherwise. The result is in newtons. F_i scales A..C for soil texture (fine, medium, coarse).

Name Type Unit Default Description
Id const char* Id: key used in tractor.json implement.type, the menu and the optimizer ("chisel"). Label: display name. Source: where the coefficients come from.
A double N per unit (per cm of depth for tillage).
B double N per unit per km/h.
C double N per unit per (km/h)^2.
Fi double Texture adjustment F_i for fine, medium and coarse soil.
SpacingM double m Tool or row spacing, m; 0 means W is the width in metres.
bDepth bool True when draft is proportional to working depth (T in cm).
MinKmh double See above.
MaxKmh double Usual working speed range, km/h.
DesignKmh double Typical speed, km/h.
DesignDepthCm double cm Typical working depth, cm.
DesignWidthM double m Typical (or fixed, for FixedWidth) working width, m.
bFixedWidth bool True when the width is fixed by the machine (the 2-row digger) rather than chosen by the user.
PtoKw double kW Power the implement draws from the PTO while working, kW.
MassPerM double m Implement mass per metre of working width, kg/m.