suboptimumg.log_analysis.understeer

class suboptimumg.log_analysis.understeer.UndersteerResult

Bases: BaseModel

Output of measure_understeer_gradient.

Holds the fitted polynomial coefficients and goodness-of-fit statistics, plus the raw filtered arrays needed to build a diagnostic plot.

Fields

Field	Type	Required	Default
coeffs	NDArray[float64]	Yes
groundspeeds	NDArray[float64]	Yes
lateral_accel	NDArray[float64]	Yes
normalized_residual_std	float	Yes
r_squared	float	Yes
steering_wheel_angles	NDArray[float64]	Yes
timestamps	NDArray[float64]	Yes
timestamps_full	NDArray[float64]	Yes
understeer_angle	NDArray[float64]	Yes

Parameters:

• coeffs (NDArray[float64])

• r_squared (float)

• normalized_residual_std (float)

• lateral_accel (NDArray[float64])

• understeer_angle (NDArray[float64])

• timestamps (NDArray[float64])

• timestamps_full (NDArray[float64])

• steering_wheel_angles (NDArray[float64])

• groundspeeds (NDArray[float64])

property K: float

deg/g.

Type:

Linear understeer gradient (degree-1 coefficient). Units

coeffs: NDArray[float64]

groundspeeds: NDArray[float64]

property intercept: float

deg.

Type:

Intercept (degree-0 coefficient). Units

lateral_accel: NDArray[float64]

normalized_residual_std: float

r_squared: float

steering_wheel_angles: NDArray[float64]

timestamps: NDArray[float64]

timestamps_full: NDArray[float64]

understeer_angle: NDArray[float64]

suboptimumg.log_analysis.understeer.measure_understeer_gradient(data, time_range, fit_degree=1, symmetric=False, min_lat_accel_g=0.1, force_zero_intercept=False, steering_wheel_angle='ludwig.steeringWheel.angle')

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

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

Requires add_groundspeed, add_curvature, add_accelerations, add_kinematic_steer_angle, and add_bicycle_steer_angle to have been run first.

Parameters:

• data (SingleRunData)

• time_range ((t_start_s, t_end_s)) – Analysis window in seconds.

• fit_degree (int) – Maximum polynomial degree to use when fitting curve 1 = linear, 2 = quadratic, 3 = cubic, etc.

• symmetric (bool) – Use only even powers (0, 2, 4, …) in the fit to enforce symmetry around a_y=0.

• force_zero_intercept (bool) – Force the fit through the origin.

• min_lat_accel_g (float) – Minimum lateral acceleration (Units: g) to include in the fit.

• steering_wheel_angle (str) – Steering wheel angle channel name.

Return type:

UndersteerResult

suboptimumg.log_analysis.understeer.plot_understeer(result, test_type='constant_steer', font_config=FontConfig(large=24, medium=16, small=12), layout_config=LayoutConfig(width=1000, height=700, grid_width_per_col=400, grid_height_per_row=350, grid_horizontal_spacing=0.08, grid_vertical_spacing=0.12, margin={'l': 70, 'r': 50, 't': 90, 'b': 70}, plot_bgcolor='white', scene_bgcolor='rgba(240, 240, 240, 0.8)', title_x=0.5, title_xanchor='center', title_yanchor='top'))

Return (fit_fig, diagnostic_fig) for an UndersteerResult.

fit_fig: scatter + polynomial fit of understeer angle vs lateral acceleration. diagnostic_fig: time-series of the held-constant channel over the analysis window.

Parameters:

• result (UndersteerResult)

• test_type (str) – "constant_steer" or "constant_speed". Determines which channel is shown in the diagnostic figure.

• font_config (FontConfig)

• layout_config (LayoutConfig)

Return type:

tuple[Figure, Figure]