suboptimumg.loganalysis.understeer#

Understeer gradient measurement from steady-state test data.

suboptimumg.loganalysis.understeer.measure_understeer_gradient(df, time_range, irl_car, test_type='constant_steer', min_ay_g=0.1, force_zero_intercept=False, fit_mode='linear', symmetric=False, show_ramp=False, overlay_diagnostics=False, sw_col='ludwig.steeringWheel.angle', ay_col='body.accLat', kinematic_col='body.steerAngle', bicycle_col='front.steerAngle.bicycle', vel_col='groundSpeed')[source]#

Measure the understeer gradient K from a steady-state test window.

Computes understeer_angle = |delta_bicycle| - |delta_kinematic| and fits a line against |a_y| in g’s. The slope is the understeer gradient K (deg/g). K > 0 = understeer, K < 0 = oversteer.

Works for both constant-speed/increasing-steer and constant-steer/increasing-speed test procedures — the core math is the same; test_type only affects the diagnostic subplot.

Parameters:

  • df (DataFrame) – Must contain the columns referenced by the *_col arguments. The DataFrame is not modified.

  • time_range ((t_start, t_end)) – time_s window to analyse.

  • irl_car (IrlCar) – Used only for display / future extensions.

  • test_type (str) – "constant_steer" or "constant_speed". Controls which variable is shown in the diagnostic subplot.

  • min_ay_g (float) – Minimum lateral acceleration (g) to include in the fit. Filters out low-speed noise.

  • force_zero_intercept (bool) – If True, force the fit through the origin (intercept = 0). Useful when a systematic offset (e.g. steering sensor zero error) is inflating the intercept.

  • fit_mode (str) – "linear" (default) — classic K = slope of UG vs a_y. "quadratic" — fits UG = c2 * a_y^2 + c1 * a_y + c0. "cubic" — fits UG = c3 * a_y^3 + c2 * a_y^2 + c1 * a_y + c0. For non-linear modes the reported K is the local slope at a_y = 0 (the c1 term); higher-order terms capture progressive under/oversteer with rising lateral load.

  • symmetric (bool) – If True, force the fitted equation to be symmetric across the y-axis (f(-x) = f(x)) by zeroing all odd-degree terms. Quadratic becomes c2 * a_y^2 + c0; cubic likewise reduces to even-only terms. Combined with force_zero_intercept the quadratic/cubic fits collapse to c2 * a_y^2. Linear + symmetric is degenerate (constant only) and not allowed.

  • show_ramp (bool) – If True, add a subplot for the ramped variable (speed for constant_steer, steering angle for constant_speed).

  • overlay_diagnostics (bool) – If True and show_ramp is True, overlay both diagnostic traces on a single subplot with dual y-axes instead of separate subplots.

  • sw_col (str) – Column names in df.

  • ay_col (str) – Column names in df.

  • kinematic_col (str) – Column names in df.

  • bicycle_col (str) – Column names in df.

  • vel_col (str) – Column names in df.

Returns:

Multi-panel figure: scatter + fit (top), diagnostic time-series (bottom panel(s)).

Return type:

go.Figure