Maxxum 150 Dynamics#

This page gives the vehicle dynamics of the Maxxum: the chassis, the suspension, the steering, the engine, the driveline and the brakes. The page Tyre and Soil gives the tyre forces, and the page Energy and Fuel gives the fuel.

Scope and Assumptions#

The model is an engine-free model in AcresVehicleModel.cpp and AcresSimModel.cpp. It computes the forces of the wheels and the state of the engine and the driveline. The physics engine of Unreal (Chaos) integrates the motion of the chassis. The class AAcresVehiclePawn connects the two parts.

The model makes these assumptions.

The chassis is one rigid body with six degrees of freedom. The axles and the wheels are not separate bodies.
Each wheel is a ray cast with a spring and a damper. A wheel has one degree of freedom, its spin.
The physics step is fixed at 1/120 s. The driveline equations use the backward Euler method.
The parameters describe a Case IH Maxxum 150 with the ActiveDrive 4 transmission. They are estimates from the manufacturer data and the tyre sizes.
No measurement of a real tractor calibrates the dynamics. Only the fuel map has a calibration.
The torque curve and the gear ratios are estimates of the shape. They do not come from measured maps.

Symbols#

Symbol	Quantity	Unit
\(m\)	Mass of the chassis body	kg
\(g\)	Standard gravity, 9.80665	m/s²
\(L\), \(T\)	Wheelbase and track	m
\(h_{cg}\)	Height of the centre of mass above firm ground at rest	m
\(x_{cg}\)	Forward offset of the centre of mass from the body origin	m
\(r_f\), \(r_r\)	Unloaded radius of a front tyre and of a rear tyre	m
\(N\), \(N_0\)	Wheel load and static wheel load	N
\(e\), \(c\)	Extension and compression of the suspension	m
\(k\), \(k_t\), \(k_a\)	Spring rate of a wheel, of the tyre and of the axle	N/m
\(C\), \(\zeta\)	Damper rate and damping ratio	N s/m, -
\(k_b\)	Rate of the bump stop	N/m²
\(v_n\)	Speed of the contact point along the ground normal	m/s
\(\delta\)	Steering angle of the bicycle model, positive to the left	rad
\(\delta_{in}\), \(\delta_{out}\)	Steering angle of the inner and the outer front wheel	rad
\(n\), \(\omega_e\)	Engine speed	rpm, rad/s
\(u\)	Command: the larger of the pedal and the hand throttle	-
\(d\)	Fuel demand of the governor	-
\(T_{full}\)	Full-load torque of the engine	N m
\(T_e\)	Engine torque	N m
\(T_{drag}\), \(T_{acc}\)	Engine drag torque and accessory torque	N m
\(J_e\), \(J_w\)	Inertia of the engine and of a wheel	kg m²
\(\epsilon\)	Clutch engagement	-
\(T_{cap}\), \(T_c\)	Clutch capacity and clutch torque	N m
\(i\)	Overall ratio: gear ratio multiplied by the final drive, negative in reverse	-
\(\eta\)	Driveline efficiency	-
\(\omega_c\)	Speed of the rear differential carrier	rad/s
\(\kappa\)	Ratio of the front carrier speed to the rear carrier speed	-
\(\omega_j\)	Speed of wheel \(j\)	rad/s
\(S_j(\omega)\)	Shaft torque that wheel \(j\) needs to end the step at the speed \(\omega\)	N m
\(F_{s,j}\)	Shear force of the tyre of wheel \(j\)	N
\(T_h\), \(T_b\)	Rolling resistance torque and brake torque of a wheel	N m
\(b_k\)	Brake command	-
\(\Delta t\)	Physics step, 1/120	s

Frames and Units#

The model uses SI units and radians. Chaos uses centimetres, thus the game converts the values at the interface.

Quantity	Conversion to Chaos
Position, velocity	Multiply by 100 (m to cm).
Force	Multiply by 100 (N to kg cm/s²).
Torque	Multiply by 10 000 (N m to kg cm²/s²).
Inertia	Multiply by 10 000 (kg m² to kg cm²).

The body frame has X forward, Y to the right and Z up. The world frame has X east, Y south and Z up. The wheel indices are 0 front left, 1 front right, 2 rear left and 3 rear right.

The Physics Step#

The function AAcresVehiclePawn::AsyncPhysicsTickActor runs one physics step on the physics thread. The step length comes from AsyncFixedTimeStepSize in Config/DefaultEngine.ini.

The sequence of one physics step of a vehicle. Open the diagram

Step	Action	Function
1	Copy the controls of the game thread. Take the command of the vehicle bridge for this step. Read the reset request.	`BridgeControlQueue.Take`
2	Write the mass properties to the Chaos body when they changed. Add the chassis energy of the last step to the ledger. Apply a reset.	`AccountChassisStep`, `ResetVehicle`
3	Advance the weather and the farm. Agent 0 does this for the session.	`FAcresEnvironmentRuntime::Advance`, `FAcresFarmRuntime::Advance`
4	Select the control source. Apply the hand throttle and the park brake. An automatic driver can replace the controls.	`DriveReplay`, `DriveScript`
5	Advance the steering, the engine and the clutch engagement.	`StepSteering`, `StepDrivetrain`
6	For each wheel: cast a ray, select the surface, read the soil state, compute the load and the lateral force.	`SampleSurface`, `PrepareWheel`
7	Solve all wheel speeds, the clutch torque and the engine speed together. Compute the fuel.	`SolveDriveline`
8	For each wheel: write the rut and the crushed crop, add the water drag, add the wheel force to the sum.	`FAcresFarmRuntime::Wheel`, `WaterDrag`
9	Add the air drag. Advance the implement and add its force, its mass and its engine loads.	`StepImplementPhysics`
10	Give the sum of the forces and the torques to Chaos.	`AddForce`, `AddTorque`
11	Publish the telemetry. Add a row to the session log, the sensor recorder and the episode log.	`FAcresSessionLog::Push`

The game thread and the physics thread share only the controls and the telemetry. One lock protects the two structures. The page Time Stepping and Determinism gives the timing of the step.

Chassis and Mass Properties#

The Chaos body is a box with the length body_length_m, a width of 2.1 m and a height of 0.7 m. The box collides with buildings and obstacles. The wheels do not collide. They are ray casts on the collision channel WheelGround. The body has no linear damping, an angular damping of 0.08 and continuous collision detection. It does not sleep.

The function ConfigureBody sets the mass properties.

Property	Value	Source
Mass \(m\)	5820 kg	`mass_kg`
Principal inertia about the centre of mass	6168, 12 915, 12 791 kg m² (roll, pitch, yaw)	`inertia_kg_m2`
Centre of mass	At the body origin plus \(x_{cg}\)	`cg_forward_m`
Body origin	\(0.4 L\) in front of the rear axle, \(h_{cg}\) above firm ground	`wheelbase_m`, `cg_height_m`

The centre of mass of the Maxxum is thus 1.057 m in front of the rear axle and 1.10 m above the ground. The inertia is the sum of the eleven rigid bodies of the mechanical data of the Maxxum, with the parallel-axis terms. The principal axes are the body axes. The model ignores the products of inertia.

The mount of wheel \(j\) is at this position in the body frame (function WheelMountCm):

\[ x_j = \begin{cases} 0.6\,L & \text{front} \\ -0.4\,L & \text{rear} \end{cases}, \qquad y_j = \pm\frac{T}{2}, \qquad z_j = r_j + 0.35 - h_{cg} \]

The static wheel loads follow from the position of the centre of mass (function ResetVehicle).

\[ s_f = \operatorname{clamp}\!\left(\frac{0.4\,L + x_{cg}}{L},\ 0.05,\ 0.95\right), \qquad N_{0,front} = \frac{m\,g\,s_f}{2}, \qquad N_{0,rear} = \frac{m\,g\,(1 - s_f)}{2} \]

For the shipped values, \(N_0\) is 11.42 kN for a front wheel and 17.12 kN for a rear wheel.

Implement mass. An implement that the tractor carries adds its mass to the body (function ApplyImplementMass). With the implement mass \(m_i\) at the position \(\vec{r}_i\) and the tractor mass \(m\) at \(\vec{r}\):

\[ m' = m + m_i, \qquad \vec{r}\,' = \frac{m\,\vec{r} + m_i\,\vec{r}_i}{m'} \]

\[ I' = I + m\,D(\vec{r} - \vec{r}\,') + m_i\,D(\vec{r}_i - \vec{r}\,') + I_i, \qquad D(\vec{a}) = \bigl(a_y^2 + a_z^2,\ a_x^2 + a_z^2,\ a_x^2 + a_y^2\bigr) \]

\(I\) and \(I_i\) are the principal inertias as vectors. The game then computes the static wheel loads and the damper rates again. The game does this each time the mass changes by 0.5 kg or the centre of mass moves by 5 mm. In each physics step, the game compares the Chaos body with these values and writes them again when they are different.

Air drag. The drag acts at the centre of mass, with \(\rho_a = 1.225\) kg/m³, \(C_d = 0.8\) and \(A = 4\) m². These values are constants in the source code.

\[ \vec{F}_a = -\tfrac{1}{2}\,\rho_a\,C_d\,A\,\lvert\vec{v}\rvert\,\vec{v} \]

Suspension and Wheel Load#

The Maxxum has no suspension body. Each wheel has a spring and a damper between its mount and the ground.

Ground probe. The game casts a ray from the mount along the down axis of the chassis. The ray length is the tyre radius plus 0.75 m. The extension \(e\) is the distance from the mount to the contact point minus the tyre radius. The compression is \(c = 0.5 - e\). At rest on firm ground, \(e = 0.35\) m and \(c = 0.15\) m.

Terrain edits. The terrain edits of the menu and the pits of the backhoe are not in the collision mesh. The game adds their height \(\Delta(x, y)\) to the contact point and tilts the ground normal.

\[ \vec{n} \leftarrow \operatorname{normalize}\!\left(\vec{n} - \left(\frac{\partial\Delta}{\partial x},\ \frac{\partial\Delta}{\partial y},\ 0\right)\right) \]

The gradient is a central difference with a half width of 0.4 m for terrain edits and 0.2 m for pits.

Contact velocity. The velocity of the contact point is \(\vec{v}_c = \vec{v} + \vec{\omega}\times(\vec{p}_c - \vec{p}_{cm})\). The wheel heading \(\vec{f}\) is the forward axis of the chassis, turned by the wheel angle and projected on the ground plane. The three speeds of the contact point are \(v_n = \vec{v}_c\cdot\vec{n}\), \(v_x = \vec{v}_c\cdot\vec{f}\) and \(v_y = \vec{v}_c\cdot(\vec{n}\times\vec{f})\).

Spring and damper. The tyre and the axle are two springs in series (function ResetVehicle).

\[ k = \left(\frac{1}{k_t} + \frac{1}{k_a}\right)^{-1}, \qquad C = 2\,\zeta\sqrt{\frac{k\,N_0}{g}} \]

With an inflation pressure, \(k_t\) is the rate of the inflated tyre, see Tyre and Soil.

Quantity	Unit	Front Wheel	Rear Wheel
Tyre rate \(k_t\) at 80 kPa	kN/m	274.4	340.8
Axle rate \(k_a\)	kN/m	500	20 000
Wheel rate \(k\)	kN/m	177.2	335.1
Damper rate \(C\)	kN s/m	20.1	33.9
Wheel inertia \(J_w\)	kg m²	27.5	90.1

Wheel load. The function SuspensionLoad gives the load. The spring carries the static load at the rest compression of 0.15 m.

\[ N = \operatorname{clamp}\!\bigl(N_0 + k\,(c - 0.15) + k_b\,\max(0,\ c - 0.35)^2 - C\,v_n,\ 0,\ 6\,N_0\bigr) \]

A wheel cannot pull the ground, thus the load is not negative. The upper limit prevents large peaks at an impact. A wheel is in the air when the ray finds no ground or the load is below 1 N. Then the tyre gives no force. On soil, the function PrepareWheel solves the load and the sinkage together, see Tyre and Soil.

Wheel inertia. Each wheel is a uniform disc: \(J_w = \tfrac{1}{2}\,m_w\,r^2\). The mass \(m_w\) is 110 kg for a front wheel and 220 kg for a rear wheel.

Front-Axle Oscillation#

The real front axle of the Maxxum turns about a longitudinal pin. The physics model has no such joint. Each front wheel has its own spring, and the low front spring rate lets the two wheels follow uneven ground. The equipment rig shows the oscillation. The function UpdateRigs computes the angle from the extensions of the two front wheels.

\[ \theta_{axle} = \operatorname{clamp}\!\left(\arctan\frac{e_{FR} - e_{FL}}{T},\ -10^\circ,\ 10^\circ\right) \]

Steering#

The function StepSteering computes the steering angle \(\delta\) of the bicycle model from the command \(\delta_{cmd}\). The keyboard gives a command of full lock or zero. The chain of four parts below makes the motion of the wheels smooth.

Part	Equation	Value
Delay	\(\delta_1(t) = \delta_{cmd}(t - \tau_d)\), and 0 for \(t < \tau_d\)	\(\tau_d = 0.12\) s
Lag	\(\delta_2 = \delta_1 + (\delta - \delta_1)\,e^{-\Delta t / \tau_s}\)	\(\tau_s = 0.18\) s
Lock	\(\delta_3 = \operatorname{clamp}(\delta_2,\ -\delta_{max},\ \delta_{max})\)	\(\delta_{max} = 0.6632\) rad (38°)
Rate limit	\(\delta \leftarrow \delta + \operatorname{clamp}(\delta_3 - \delta,\ -\dot\delta_{max}\Delta t,\ \dot\delta_{max}\Delta t)\)	\(\dot\delta_{max} = 0.6981\) rad/s (40°/s)

The delay keeps a queue of commands with their times. It uses the newest command that is at least \(\tau_d\) old.

The function Ackermann gives the angles of the two front wheels. Both wheels point at one turn centre on the line of the rear axle.

\[ R = \frac{L}{\tan\lvert\delta\rvert}, \qquad \delta_{in} = \arctan\frac{L}{\max(0.1,\ R - T/2)}, \qquad \delta_{out} = \arctan\frac{L}{R + T/2} \]

In a left turn the left wheel is the inner wheel. For \(\lvert\delta\rvert\) below \(10^{-5}\) rad, both angles are zero. At full lock, \(R\) is 3.38 m, \(\delta_{in}\) is 47.4° and \(\delta_{out}\) is 31.4°. The steering moves from lock to lock in 1.9 s.

Engine#

The function StepDrivetrain computes the engine torque in each step.

The powertrain of the Maxxum with the governor and the loads on the engine. Open the diagram

Torque Curve#

The function Torque interpolates the key torque_curve linearly. It multiplies the curve so that its maximum is peak_torque_nm. The torque is zero at max_rpm and above. Below the first point, the torque is that of the first point.

Engine Speed (rpm)	Full-Load Torque (N m)	Power (kW)
800	400	33.5
1000	550	57.6
1200	680	85.5
1400	700	102.6
1600	670	112.3
1800	610	115.0
1900	584.1	116.2
2000	550	115.2
2200	478.9	110.3
2300	0	0

The rated power is 110.3 kW at 2200 rpm and the maximum power is 116.2 kW at 1900 rpm. A power limit \(P_{max}\) (max_power_kw) also applies. The engine speed in the limit has a floor of 20 rad/s.

\[ T_{avail} = \min\!\left(T_{full}(n),\ \frac{P_{max}}{\max(\omega_e,\ 20)}\right) \]

With boost_enabled, the curve increases by the factor boost_power_kw / max_power_kw and the limit is boost_power_kw. The shipped value is false. When the fuel tank is empty, \(T_{avail}\) is zero.

All-Speed Governor#

The command \(u\) does not set the torque. It sets the no-load speed of an all-speed governor, as the hand lever of a tractor does.

\[ n_0 = n_{idle} + u\,(n_{max} - n_{idle}), \qquad d = \operatorname{clamp}\!\left(\frac{n_0 - n}{\Delta n},\ 0,\ 1\right) \]

\(\Delta n\) is the droop governor_droop_rpm, 100 rpm. The fuel demand \(d\) decreases linearly to zero in the droop band below \(n_0\). The engine speed thus decreases by a maximum of 100 rpm from no load to full load. At full command and without a load, the engine runs at 2267 rpm. With a droop of 0, the governor is off and \(d = u\).

Two more governors change the demand.

\[ g_v = \operatorname{clamp}\!\left(\frac{v_{max} - v_w}{0.5},\ 0,\ 1\right), \qquad d_{idle} = \operatorname{clamp}\bigl(0.02\,(\omega_{idle} - \omega_e),\ 0,\ 0.35\bigr) \]

\[ T_e = T_{avail}\,\max(d\,g_v,\ d_{idle}) \]

\(g_v\) is the road speed governor. \(v_w\) is the mean speed of the rear tyres in the direction of travel, and \(v_{max}\) is max_speed_mps (40.2 km/h). \(d_{idle}\) is the idle governor. It adds fuel when the engine speed is below the idle speed, for all commands.

Loads on the Engine#

The engine drag increases linearly with the speed. The accessory torque comes from the PTO shaft and the hydraulic pump.

\[ T_{drag} = T_{d0}\,\frac{\omega_e}{\omega_{idle}}, \qquad T_{acc} = \frac{P_{pto}/\eta_{pto} + P_{hyd}/\eta_{hyd}}{\max(\omega_e,\ 20)} \]

\(T_{d0}\) is engine_drag_nm. \(P_{pto}\) is the sum of pto_kw and the PTO power of the implement. \(P_{hyd}\) is the sum of hydraulic_kw and the hydraulic power of the implement. The engine speed that the engine gets with an open clutch is:

\[ \omega_{free} = \max\!\left(0,\ \omega_e + \frac{\Delta t}{J_e}\,(T_e - T_{drag} - T_{acc})\right) \]

Hand Throttle#

The hand throttle is a second command between 0 and 1. The engine uses the larger of the pedal and the hand throttle: \(u = \max(u_{pedal},\ u_{hand})\). The keys = and - change it in steps of 0.05. The vehicle bridge sets it with the field hand_throttle. When the user engages the PTO, the game sets the hand throttle to the value for the rated PTO speed.

\[ u_{hand} \ge \frac{n_{pto} + 0.5\,\Delta n - n_{idle}}{n_{max} - n_{idle}} \]

\(n_{pto}\) is pto_540_engine_rpm or pto_1000_engine_rpm. The result is 0.81 for the 540 rpm PTO and 0.76 for the 1000 rpm PTO.

Clutch#

The clutch engagement \(\epsilon\) moves to 1 when three conditions are true: \(u > 0.01\), \(b_k < 0.1\) and no gear change is in progress. In all other conditions it moves to 0. The rate is \(1 / t_c\), with \(t_c\) = clutch_engagement_s.

\[ \epsilon \leftarrow \epsilon + \operatorname{clamp}\!\left(\epsilon_{target} - \epsilon,\ -\frac{\Delta t}{t_c},\ \frac{\Delta t}{t_c}\right) \]

The clutch capacity includes a protection against an engine stall. The capacity decreases to zero when the engine speed decreases from 100 % to 60 % of the idle speed.

\[ T_{cap} = T_{cl}\,\epsilon\,\operatorname{clamp}\!\left(\frac{\omega_{free} - 0.6\,\omega_{idle}}{0.4\,\omega_{idle}},\ 0,\ 1\right) \]

\(T_{cl}\) is clutch_capacity_nm. The driveline solve computes the clutch torque \(T_c\).

Note

The clutch opens when the user releases the pedal and the hand throttle is zero. The Maxxum then coasts. The model has no engine braking.

Transmission#

The transmission has 16 forward gears and 16 reverse gears with the same ratios. The ratio of one gear to the next is 1.2211. The overall ratio is \(i = \pm\,i_g\,i_f\), with the gear ratio \(i_g\) and the final drive \(i_f = 10\). The sign is negative in reverse.

Gear	Ratio	Speed (km/h)	Gear	Ratio	Speed (km/h)
1	36.017	2.08	9	7.288	10.30
2	29.497	2.54	10	5.969	12.58
3	24.157	3.11	11	4.888	15.36
4	19.783	3.79	12	4.003	18.75
5	16.202	4.63	13	3.279	22.90
6	13.269	5.66	14	2.685	27.96
7	10.867	6.91	15	2.199	34.14
8	8.899	8.44	16	1.801	41.68

The speed in the table is \(v = \omega_e\,r_r / (i_g\,i_f)\) at 2200 rpm, without slip. The road speed governor limits gear 16 to 40.2 km/h.

Start gear. The key initial_gear and the option -VehicleGear= set the gear at the start. The first gear is 1.
Gear change. A new gear sets the engagement target of the clutch to 0 for shift_time_s. From full engagement, \(\epsilon\) decreases to approximately 0.63 in 0.3 s.
Direction. The key V changes the direction when the speed is below 0.25 m/s. The clutch does not open for a direction change.
Efficiency. One efficiency \(\eta\) applies to the gearbox and the axles together. The torque at the rear carrier is \(i\,\eta\,T_c\).

Driveline Solve#

The function SolveDriveline finds the speeds of all wheels, the clutch torque and the engine speed at the end of the step. One solve is necessary because the differentials, the front-wheel drive and a locked clutch connect the wheels and the engine. The tyre force is a stiff function of the wheel speed, thus all equations use the speeds at the end of the step (backward Euler).

Wheel#

The shaft torque that wheel \(j\) needs to end the step at the speed \(\omega\) is (function WheelShaftTorqueNm):

\[ S_j(\omega) = J_w\,\frac{\omega - \omega_j}{\Delta t} + F_{s,j}(\omega)\,r_j + (T_h + T_b)\tanh\frac{\omega}{0.1} \]

\(F_{s,j}(\omega)\) is the shear force of the tyre for this trial speed, see Tyre and Soil. The hyperbolic tangent makes the resistances act against the spin and decrease to zero near standstill. \(S_j\) increases with \(\omega\). A wheel without a drive shaft has the speed at which \(S_j(\omega) = 0\).

Axle and Differential#

The torque that an axle needs at its differential carrier for the carrier speed \(\omega_c\) is (function AxleCarrierTorqueNm):

Differential	Wheel Speeds	Carrier Torque
Open	\(\omega_L + \omega_R = 2\,\omega_c\) and \(S_L(\omega_L) = S_R(\omega_R)\)	\(S_L(\omega_L) + S_R(\omega_R)\)
Locked	\(\omega_L = \omega_R = \omega_c\)	\(S_L(\omega_c) + S_R(\omega_c)\)

An open differential gives the same torque to its two wheels. A locked differential gives the same speed to its two wheels. The differential lock has three states: 0 is open, 1 locks the rear axle, 2 locks the rear axle and the front axle. The key L and the option -VehicleDiffLock= set the state.

Front-Wheel Drive#

With front_drive (MFD), gears connect the front carrier rigidly to the rear carrier. The model has no centre differential. The front tyres roll faster than the rear tyres by the front lead \(\lambda\) (front_lead_ratio, 1.5 %).

\[ \kappa = (1 + \lambda)\,\frac{r_r}{r_f} = 1.300, \qquad D(\omega_c) = S_{rear}(\omega_c) + \kappa\,S_{front}(\kappa\,\omega_c) \]

\(D\) is the torque that the driveline needs at the rear carrier. \(S_{rear}\) and \(S_{front}\) are the carrier torques of the two axles. The torque split between the axles follows from this constraint. With -Vehicle2WD, the front wheels have no drive shaft.

Clutch and Engine#

A locked clutch makes the engine speed equal to the speed of the gearbox input, \(i\,\omega_c\). The clutch torque for this is:

\[ T_c = \frac{J_e\,(\omega_{free} - i\,\omega_c)}{\Delta t} \]

The solve finds the carrier speed that balances the two sides.

\[ D(\omega_c) = i\,\eta\,T_c \]

Case	Condition	Equations
Locked clutch	\(\lvert T_c\rvert \le T_{cap}\)	The two equations above.
Slipping clutch	\(\lvert T_c\rvert > T_{cap}\)	\(T_c = \pm T_{cap}\), then \(D(\omega_c) = i\,\eta\,T_c\).
Open clutch	\(T_{cap} = 0\) or \(i = 0\)	\(T_c = 0\), then \(D(\omega_c) = 0\).

The engine speed at the end of the step is \(\omega_e = \max(0,\ \omega_{free} - \Delta t\,T_c / J_e)\). The clutch heat increases by \(\max\bigl(0,\ T_c\,(\omega_e - i\,\omega_c)\bigr)\,\Delta t\) in each step.

Numerical Method#

Each equation of the solve is the root of a function that increases with its unknown. The function RisingRoot finds the root. It starts with an interval around an estimate. It makes the interval two times larger until the function changes its sign, then it bisects.

Root	Estimate	Bisections
Wheel without a drive shaft	The speed at the start of the step	40
Speed split of an open differential	The carrier speed plus half of the speed difference at the start	36
Carrier speed, locked clutch	\(\omega_{free} / i\)	48
Carrier speed, slipping or open clutch	The carrier speed at the start	44

After the solve, the function SettleWheels sets the speed, the spin angle, the slip and the force of each wheel.

Brakes and Park Brake#

Each of the four wheels has a brake. The brake torque is proportional to the wheel load (function PrepareWheel).

\[ T_b = 1.5\,b_k\,N\,r \]

For a wheel in the air, the torque uses the static load \(N_0\). The keyboard gives \(b_k = 0\) or 1. The brake force at the ground is not larger than the grip of the tyre. Full braking locks a wheel when its grip ratio is below 1.5.

A brake command of 0.1 or more also opens the clutch. The park brake sets \(b_k = 1\) until the user releases it. The key P and the field park_brake of the vehicle bridge control the park brake. The model has no anti-lock function.

Forces on the Chassis#

The game applies the force of each wheel at the contact point. On soil, the point is at the bottom of the rut.

\[ \vec{F}_j = N\,\vec{n} + F_x\,\vec{f} + F_y\,(\vec{n}\times\vec{f}) + \vec{F}_w, \qquad \vec{M}_j = (\vec{p}_j - \vec{p}_{cm})\times\vec{F}_j \]

\(F_x\), \(F_y\) and the water drag \(\vec{F}_w\) come from the tyre model. The total force on the body in one step is:

\[ \vec{F} = \sum_j \vec{F}_j + \vec{F}_a + \vec{F}_{impl}, \qquad \vec{M} = \sum_j \vec{M}_j + \vec{M}_{impl} \]

Chaos adds the gravity and integrates the body. Chaos also resolves the contacts of the chassis box with obstacles.

Implement Coupling#

This section gives the vehicle side of the coupling. The page Implement Mechanics gives the implement side. The function StepImplementPhysics runs the implement model in each physics step and applies its results to the tractor.

Quantity	Direction	Rule
Speed and acceleration of the chassis	To the implement	The acceleration has a lag of 50 ms.
Engine speed	To the implement	The PTO speed is the engine speed multiplied by the PTO ratio. The pump flow follows \(n / n_{rated}\).
Force and moment	To the chassis	The force acts at the attachment point. The limit is 250 kN.
Mass, centre of mass, inertia	To the chassis	See Chassis and Mass Properties.
PTO power and hydraulic power	To the engine	The engine gets the loads of the last step, thus one step later.

The PTO ratio is the rated PTO speed divided by the engine speed for that PTO speed. It is 540 / 1969 for the sprayer and 1000 / 1893 for the baler.

Carried implements. The tractor carries seven of the eight implements: on the hitch, on the loader arms or on the backhoe mount. Their mass is a part of the chassis body. The implement model gives the soil forces as a force and a moment in the tractor frame.

Square baler. The square baler is the only trailed implement. On the vehicle side it is a kinematic trailer with one axle. The axle point \(\vec{a}\) follows the drawbar pin \(\vec{h}\) at the fixed distance \(L_b\).

\[ \vec{a} \leftarrow \vec{h} + L_b\,\frac{\vec{a} - \vec{h}}{\lvert\vec{a} - \vec{h}\rvert} \]

The angle between the baler and the tractor is \(\psi_b\). The implement model gives the drawbar load \((D_x, D_y, D_z)\) in the baler frame. The game turns it by \(\psi_b\) and applies it at the drawbar pin.

\[ \vec{F}_{impl} = \bigl(D_x\cos\psi_b - D_y\sin\psi_b,\ D_x\sin\psi_b + D_y\cos\psi_b,\ D_z\bigr) \]

The mass of the baler is not in the chassis body. On a slope, the game adds \(g\) multiplied by the slope to the acceleration that the baler gets.

Legacy Tractor#

The option -VehicleModel=legacy selects the legacy tractor. It uses the same equations with these differences.

Item	Legacy Tractor
Governor	The droop is 0, thus the command multiplies the full-load torque.
Inertia	A solid box of \((L + 0.55) \times (T + 0.5) \times 2.5\) m.
Visual	Static meshes without an equipment rig.
Implement	A draft force from ASABE D497.7 (functions `AsabeDraftN` and `ImplementDraftN`), not the implement model.
Mounted implement	A mass 1 m behind the hitch point, at `implement.cg_height_m` above the ground. Its inertia is that of a box of 2 × 2.4 × 0.7 m.
Trailed implement	A second body with two free wheels. A Chaos ball joint connects it to the tractor.

The draft of the legacy implement is \(D = F_i\,(A + B\,S + C\,S^2)\,W\,T_d\). \(S\) is the speed in km/h with a lag of 0.5 s. \(W\) is the width in metres or the number of tools, \(T_d\) is the depth in centimetres and \(F_i\) is the soil texture factor. The force acts against the horizontal velocity with the factor \(\tanh(v / 0.2)\). Its point is 0.8 m below the body origin, at the hitch position for a mounted implement. An implement of the table pulls only when its tool point is on a deformable surface.

The ball joint permits 75° of yaw, 30° of pitch and 25° of roll. The trailer axle is at the distance \(d_h\,t_h / (1 - t_h)\) behind its centre of mass. \(d_h\) is hitch_to_cg_m and \(t_h\) is hitch_transfer. The hitch then carries the share \(t_h\) of the trailer weight.

Type	A	B	C	Unit of W	Texture Factor: Fine, Medium, Coarse
`moldboard`	652	0	5.1	Width in m	1, 0.70, 0.45
`chisel`	91	5.4	0	Tools at 0.30 m	1, 0.85, 0.65
`disk`	309	16	0	Width in m	1, 0.88, 0.78
`cultivator`	46	2.8	0	Tools at 0.20 m	1, 0.85, 0.65
`planter`	500	0	0	Rows at 0.76 m, no depth	1, 1, 1
`potato_digger`	250	12	0	Width in m	1, 0.88, 0.78
`custom`					\(D = D_{ref}\,(1 + 0.06\,S) / (1 + 0.06\,S_{ref})\)

The potato digger is not in the standard. Its coefficients are an estimate.

Verification#

Two sets of tests examine the model.

Engine-free tests. The folder Tools/Terramechanics builds the model without Unreal Engine and runs it on a planar test stand. The page Tyre and Soil gives the commands and the results.

Scripted tests in the game. The option -VehicleTest= runs a fixed sequence on a flat test pad and writes vehicle.csv. The sequence is: brake for 3 s, a command of 0.7 until 11 s, then brake.

Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -VehicleTest=straight \
  -VehicleSurface=concrete -VehicleOutput=/tmp/acres-test

Expected Result

The log contains ACRES_VEHICLE_TEST_FINISHED steps=2040 written=1. The folder contains vehicle.csv and metadata.json. At rest, a rear wheel has a load of 17.12 kN. With the command of 0.7 in gear 10, the engine speed is 1842 rpm and the speed is 10.6 km/h.

The no-load speed of the governor for a command of 0.7 is 1850 rpm. The gear table gives 10.5 km/h for gear 10 at 1842 rpm.

The page Command-Line Options lists the test names. The page Session Log gives the columns of vehicle.csv.

Parameters#

All keys of this section are in the block vehicle of Content/Simulation/tractor.json. The option -VehicleConfig= selects a different file. A key that is absent uses the default of the structure FVehicleParameters. The default column shows the shipped value. The page Tyre and Soil gives the tyre keys, and the page Energy and Fuel gives the fuel keys.

Chassis and Suspension#

Name	Type	Unit	Default	Description
`model`	string		`maxxum_150`	The tractor: `maxxum_150` or `legacy`.
`mass_kg`	number	kg	5820	The mass of the tractor without an implement. The minimum is 500.
`wheelbase_m`	number	m	2.6416	The distance between the axles, \(L\).
`track_m`	number	m	1.9	The distance between the left and the right wheels, \(T\).
`cg_height_m`	number	m	1.1	The height of the centre of mass above firm ground at rest, \(h_{cg}\).
`cg_forward_m`	number	m	0	The forward offset of the centre of mass from the body origin, \(x_{cg}\).
`inertia_kg_m2`	list of 3 numbers	kg m²	6168, 12915, 12791	The principal inertia about the centre of mass: roll, pitch, yaw.
`body_length_m`	number	m	4.2164	The length of the collision box.
`front_axle_stiffness_n_m`	number	N/m	500000	The spring rate of the front axle for each wheel, \(k_a\).
`rear_axle_stiffness_n_m`	number	N/m	20000000	The spring rate of the rear axle for each wheel, \(k_a\).
`suspension_damping_ratio`	number	-	0.7	The damping ratio \(\zeta\).
`bump_stiffness_n_m`	number	N/m²	1000000	The rate of the bump stop, \(k_b\).

Steering#

Name	Type	Unit	Default	Description
`steer_delay_s`	number	s	0.12	The delay \(\tau_d\) of the steering command.
`steer_time_constant_s`	number	s	0.18	The time constant \(\tau_s\) of the lag.
`steer_rate_rad_s`	number	rad/s	0.6981	The maximum steering rate (40°/s).
`max_steer_rad`	number	rad	0.6632	The steering lock \(\delta_{max}\) (38°).

Engine#

Name	Type	Unit	Default	Description
`idle_rpm`	number	rpm	800	The idle speed \(n_{idle}\).
`max_rpm`	number	rpm	2300	The speed at which the torque is zero, \(n_{max}\).
`rated_rpm`	number	rpm	2200	The rated speed. The pump flow of an implement follows \(n / n_{rated}\).
`peak_torque_nm`	number	N m	700	The maximum of the torque curve.
`torque_curve`	list of pairs	rpm, N m	10 points	The full-load torque curve. Without the key, a curve of 9 points in the source code applies.
`rated_power_kw`	number	kW	110.32	The rated power. The dynamics do not use it.
`max_power_kw`	number	kW	116.21	The power limit \(P_{max}\). 0 is no limit.
`boost_power_kw`	number	kW	128.71	The power limit with boost.
`boost_enabled`	boolean		false	Uses the boost limit and multiplies the curve.
`governor_droop_rpm`	number	rpm	100	The droop \(\Delta n\) of the governor. 0 makes the command a torque command.
`engine_inertia_kg_m2`	number	kg m²	2	The inertia \(J_e\) of the engine.
`engine_drag_nm`	number	N m	15	The drag torque \(T_{d0}\) at the idle speed.
`max_speed_mps`	number	m/s	11.176	The speed of the road speed governor. 0 is no limit.

Clutch, Transmission and Axles#

Name	Type	Unit	Default	Description
`clutch_capacity_nm`	number	N m	900	The torque capacity \(T_{cl}\) of the clutch.
`clutch_engagement_s`	number	s	0.8	The time \(t_c\) for full engagement or full release.
`forward_gears`	list of 16 numbers	-	36.017 to 1.801	The forward gear ratios. The first entry is gear 1.
`reverse_gears`	list of 16 numbers	-	36.017 to 1.801	The reverse gear ratios.
`gear_ratio`	number	-	4	The gear ratio when the gear lists are absent.
`initial_gear`	integer		10	The gear at the start. The first gear is 1.
`shift_time_s`	number	s	0.3	The time of a gear change.
`final_drive`	number	-	10	The ratio \(i_f\) of the axles.
`efficiency`	number	-	0.9	The driveline efficiency \(\eta\).
`front_drive`	boolean		true	Engages the front-wheel drive (MFD).
`front_lead_ratio`	number	-	0.015	The front lead \(\lambda\). The permitted range is 0 to 0.1.

PTO and Hydraulics#

Name	Type	Unit	Default	Description
`pto_kw`	number	kW	0	A constant PTO load.
`max_pto_kw`	number	kW	93.21	The limit for `pto_kw`. The game stops at the start when `pto_kw` is larger.
`pto_efficiency`	number	-	1.0	The PTO shaft power divided by the engine power that it takes, \(\eta_{pto}\).
`hydraulic_kw`	number	kW	0	A constant hydraulic load.
`hydraulic_efficiency`	number	-	0.85	The hydraulic power divided by the engine power that the pump takes, \(\eta_{hyd}\).
`pto_540_engine_rpm`	number	rpm	1969	The engine speed at a PTO speed of 540 rpm.
`pto_1000_engine_rpm`	number	rpm	1893	The engine speed at a PTO speed of 1000 rpm.

Legacy Implement Block#

These keys are in the block implement. Only the legacy tractor uses them.

Name	Type	Unit	Default	Description
`empty_mass_kg`	number	kg	1200	The mass of the implement or trailer without payload.
`payload_kg`	number	kg	0	The payload.
`rated_payload_kg`	number	kg	2000	The maximum payload.
`hitch_overhang_m`	number	m	0.6	The distance of the hitch point behind the rear axle.
`hitch_to_cg_m`	number	m	3.2	The distance from the hitch point to the centre of mass of the trailer, \(d_h\).
`hitch_transfer`	number	-	0.15	The share of the trailer weight on the hitch point, \(t_h\).
`cg_height_m`	number	m	0.9	The height of the centre of mass of a mounted implement.
`type`	string		`custom`	The implement type of the draft table.
`width_m`	number	m	3.0	The working width.
`depth_cm`	number	cm	18	The working depth \(T_d\).
`design_speed_kmh`	number	km/h	8	The speed \(S_{ref}\) of a `custom` implement.
`draft_n`	number	N	0	The draft \(D_{ref}\) of a `custom` implement at the design speed.
`soil_texture`	string		`auto`	The soil texture for \(F_i\): `auto`, `fine`, `medium` or `coarse`.

Constants in the Source Code#

Constant	Value	Function
Rest extension of the suspension	0.35 m	`WheelMountCm`
Compression datum	0.5 m	`PrepareWheel`
Rest compression, start of the bump stop	0.15 m, 0.35 m	`SuspensionLoad`
Ray length below the mount	\(r\) + 0.75 m	`AsyncPhysicsTickActor`
Maximum wheel load	\(6\,N_0\)	`SuspensionLoad`
Wheel mass, front and rear	110 kg, 220 kg	`ResetVehicle`
Brake gain	1.5	`PrepareWheel`
Air density, drag coefficient, frontal area	1.225 kg/m³, 0.8, 4 m²	`AsyncPhysicsTickActor`
Idle governor gain and limit	0.02 s/rad, 0.35	`StepDrivetrain`
Band of the road speed governor	0.5 m/s	`StepDrivetrain`
Stall protection range	60 % to 100 % of the idle speed	`StepDrivetrain`
Speed scale of the resistance torques	0.1 rad/s	`WheelShaftTorqueNm`
Angular damping of the body	0.08	`AAcresVehiclePawn` constructor
Limit of the implement force	250 kN	`StepImplementPhysics`

Command-Line Options#

Name	Type	Unit	Default	Description
`-VehicleConfig=`	path		`Content/Simulation/tractor.json`	The vehicle configuration file.
`-VehicleModel=`	string		`maxxum_150`	`maxxum_150` or `legacy`.
`-VehicleGear=`	integer		10	The gear at the start.
`-Vehicle2WD`	switch		off	Disengages the front-wheel drive.
`-VehicleDiffLock=`	string		`off`	The differential lock at the start: `off`, `rear` or `all`.
`-VehiclePtoKW=`	number	kW	0	A constant PTO load. It replaces `pto_kw`.

Code Map#

Item	File	Function
Physics step	`AcresVehicle.cpp`	`AAcresVehiclePawn::AsyncPhysicsTickActor`
Configuration	`AcresVehicle.cpp`	`AAcresVehiclePawn::LoadConfiguration`
Mass properties	`AcresVehicle.cpp`	`ConfigureBody`, `ApplyMassProperties`, `ApplyImplementMass`
Wheel mounts	`AcresVehicle.cpp`	`WheelMountCm`
Static loads, springs, dampers	`AcresVehicleModel.cpp`	`ResetVehicle`
Wheel load	`AcresVehicleModel.cpp`	`SuspensionLoad`, `PrepareWheel`
Steering	`AcresVehicleModel.cpp`, `AcresSimModel.cpp`	`StepSteering`, `Ackermann`
Engine, governor, clutch engagement	`AcresVehicleModel.cpp`, `AcresSimModel.cpp`	`StepDrivetrain`, `Torque`
Driveline solve	`AcresVehicleModel.cpp`	`SolveDriveline`, `AxleCarrierTorqueNm`, `WheelShaftTorqueNm`, `RisingRoot`
Wheel state after the solve	`AcresVehicleModel.cpp`	`SettleWheels`
Brake torque	`AcresVehicleModel.cpp`	`PrepareWheel`
Implement coupling	`AcresVehicle.cpp`	`StepImplementPhysics`
Keyboard controls	`AcresVehicle.cpp`	`AAcresVehiclePawn::Tick`, `ReadImplementKeys`
Front-axle angle of the equipment rig	`AcresVehicle.cpp`	`UpdateRigs`
Legacy draft	`AcresVehicleModel.cpp`	`AsabeDraftN`, `ImplementDraftN`
Engine-free test stand	`Tools/Terramechanics/VehicleBench.h`	`Bench::FBench::Step`

Limitations#

The parameters are estimates. No measurement of a real Maxxum 150 calibrates the dynamics.
The torque curve has an estimated shape. The gear ratios have an estimated geometric spacing.
The clutch opens when the command is zero, thus the model has no engine braking.
The transmission has no automatic gear change. The four ranges of the real transmission are not in the model.
A gear change decreases the clutch engagement to approximately 0.63 only. The clutch capacity then is 570 N m, thus the clutch slips only at a high engine torque.
The front axle has no pivot joint. Each front wheel has its own spring.
The brake torque is proportional to the wheel load, with a fixed gain. The brakes have no anti-lock function.
The differentials are open or locked. The model has no limited-slip differential.
The wheel masses, the air drag values and the brake gain are constants in the source code.
The inertia of the body is diagonal. The game ignores the products of inertia of a carried implement.

References#

ASABE D497.7 (2011, reaffirmed 2015). Agricultural Machinery Management Data. American Society of Agricultural and Biological Engineers, St. Joseph, Michigan.
Case IH (2016). Maxxum Series Tractors, brochure CIH11291601. CNH Industrial America LLC, Racine, Wisconsin.
Nebraska Tractor Test Laboratory (2016). Nebraska OECD Tractor Test 2974, Summary 1097: Case IH Maxxum 150. University of Nebraska-Lincoln.
Wong, J. Y. (2008). Theory of Ground Vehicles, 4th edition. John Wiley and Sons, Hoboken, New Jersey.