suboptimumg.log_analysis.yaw_fit_models

class suboptimumg.log_analysis.yaw_fit_models.AggregateMetrics

Bases: BaseModel

RMSE / VAF pooled across a list of WindowMetrics.

Fields

Field	Type	Required	Default
rmse_ac_rad_s	float	Yes
rmse_raw_rad_s	float	Yes
vaf_ac_pct	float	Yes

Parameters:

• rmse_raw_rad_s (float)

• rmse_ac_rad_s (float)

• vaf_ac_pct (float)

classmethod from_rows(rows)

Pool per-window rows; all-NaN when rows is empty.

Parameters:

rows (list[WindowMetrics])

Return type:

AggregateMetrics

property rmse_ac_deg_s: float

rmse_ac_rad_s in deg/s.

rmse_ac_rad_s: float

rmse_raw_rad_s: float

vaf_ac_pct: float

class suboptimumg.log_analysis.yaw_fit_models.BicycleCoeffs

Bases: BaseModel

LPV coefficients of the yaw-rate-to-front-tire-steer transfer function.

Evaluated at one or more speeds by bicycle_coeffs; every field is shaped like the input speed(s).

Fields

Field	Type	Required	Default
K	NDArray[float64]	Yes
T_z	NDArray[float64]	Yes
omega_n	NDArray[float64]	Yes
zeta	NDArray[float64]	Yes

Parameters:

• K (NDArray[float64])

• T_z (NDArray[float64])

• omega_n (NDArray[float64])

• zeta (NDArray[float64])

K: NDArray[np.float64]

T_z: NDArray[np.float64]

omega_n: NDArray[np.float64]

zeta: NDArray[np.float64]

class suboptimumg.log_analysis.yaw_fit_models.BicyclePoint

Bases: BaseModel

Linear-region bicycle coefficients evaluated at a single speed.

Fields

Field	Type	Required	Default
K	float	Yes
T_z_ms	float	Yes
V	float	Yes
wn_hz	float	Yes
zeta	float	Yes

Parameters:

• V (float)

• K (float)

• T_z_ms (float)

• wn_hz (float)

• zeta (float)

K: float

T_z_ms: float

V: float

wn_hz: float

zeta: float

class suboptimumg.log_analysis.yaw_fit_models.ChassisParams

Bases: BaseModel

The three free chassis scalars of the linear bicycle model.

Transfer-function form: H(s; V) = K wn^2 (1 + T_z s) / (s^2 + 2 zeta wn s + wn^2), evaluated by bicycle_coeffs.

Fields

Field	Type	Required	Default
Ca_f	float	Yes
Ca_r	float	Yes
Izz	float	Yes

Parameters:

• Ca_f (float)

• Ca_r (float)

• Izz (float)

Ca_f: float

Ca_r: float

Izz: float

class suboptimumg.log_analysis.yaw_fit_models.FitComparison

Bases: BaseModel

Side-by-side table of several YawFit, one row each.

Fields

Field	Type	Required	Default
rows	list['FitComparisonRow']	Yes

Parameters:

data (Any)

classmethod from_fits(fits)

Build a comparison table from fits keyed by display name.

Parameters:

fits (dict[str, YawFit])

Return type:

FitComparison

rows: list['FitComparisonRow']

class suboptimumg.log_analysis.yaw_fit_models.FitComparisonRow

Bases: BaseModel

One fit’s row in a FitComparison.

Fields

Field	Type	Required	Default
Ca_f	float	Yes
Ca_r	float	Yes
Izz	float	Yes
L_f	float	Yes
aic	float	Yes
bic	float	Yes
ca_scheduler	Literal[‘none’, ‘abs_alpha_per_axle’]	Yes
final_cost	float	Yes
n_params	int	Yes
name	str	Yes
relaxation	Literal[‘none’, ‘front’]	Yes
rmse_ac_deg_s	float	Yes
u_off_deg	float	Yes
vaf_ac_pct	float	Yes

Parameters:

• name (str)

• ca_scheduler (Literal['none', 'abs_alpha_per_axle'])

• relaxation (Literal['none', 'front'])

• n_params (int)

• final_cost (float)

• rmse_ac_deg_s (float)

• vaf_ac_pct (float)

• aic (float)

• bic (float)

• Ca_f (float)

• Ca_r (float)

• Izz (float)

• L_f (float)

• u_off_deg (float)

Ca_f: float

Ca_r: float

Izz: float

L_f: float

aic: float

bic: float

ca_scheduler: CaScheduler

final_cost: float

classmethod from_fit(name, fit)

Summarize one fit into a comparison row.

Parameters:

• name (str)

• fit (YawFit)

Return type:

FitComparisonRow

n_params: int

name: str

relaxation: Relaxation

rmse_ac_deg_s: float

u_off_deg: float

vaf_ac_pct: float

class suboptimumg.log_analysis.yaw_fit_models.FitContext

Bases: BaseModel

Channel names, units, and the car geometry shared by every fit.

Built once per notebook run. Holds everything the predictor and optimizer need that depends on neither the fit spec nor the parameter vector.

Fields

Field	Type	Required	Default
bicycle_steer_col	str	No	'front.steerAngle.bicycle'
bicycle_steer_units	Literal[‘rad’, ‘deg’]	No	'deg'
body_slip_col	str	No	'body.slipAngle'
body_slip_units	Literal[‘rad’, ‘deg’]	No	'deg'
input_col	str	No	'front.steerAngle.bicycle'
input_units	Literal[‘rad’, ‘deg’]	No	'deg'
irl_car	IrlCar	Yes
speed_col	str	No	'pcm.vnav.velocityBody.x'
yaw_rate_col	str	No	'pcm.vnav.compensatedAngularRate.z'

Parameters:

• irl_car (IrlCar)

• input_col (str)

• input_units (Literal['rad', 'deg'])

• speed_col (str)

• yaw_rate_col (str)

• body_slip_col (str)

• body_slip_units (Literal['rad', 'deg'])

• bicycle_steer_col (str)

• bicycle_steer_units (Literal['rad', 'deg'])

bicycle_steer_col: str

bicycle_steer_units: Literal['rad', 'deg']

body_slip_col: str

body_slip_units: Literal['rad', 'deg']

input_col: str

input_units: Literal['rad', 'deg']

irl_car: IrlCar

speed_col: str

yaw_rate_col: str

class suboptimumg.log_analysis.yaw_fit_models.FitSpec

Bases: BaseModel

Selects the Ca-decay scheduler and the tire-relaxation flavor.

Together with a ParamLayout (which decides which scalars are free) this fully determines the prediction pipeline.

Fields

Field	Type	Required	Default
ca_scheduler	Literal[‘none’, ‘abs_alpha_per_axle’]	No	'none'
name	str	Yes
relaxation	Literal[‘none’, ‘front’]	No	'none'

Parameters:

• name (str)

• ca_scheduler (Literal['none', 'abs_alpha_per_axle'])

• relaxation (Literal['none', 'front'])

ca_scheduler: CaScheduler

name: str

relaxation: Relaxation

class suboptimumg.log_analysis.yaw_fit_models.Param

Bases: BaseModel

One entry of the optimizer’s parameter vector.

A pinned param is held at init and never handed to the optimizer, so it carries no bounds.

Fields

Field	Type	Required	Default
hi	float	Yes
init	float	Yes
lo	float	Yes
name	str	Yes
pinned	bool	No	False
scale	float	Yes

Parameters:

• name (str)

• init (float)

• lo (float)

• hi (float)

• scale (float)

• pinned (bool)

format(value)

Render value in this parameter’s display units.

Parameters:

value (float)

Return type:

str

hi: float

init: float

lo: float

name: str

pinned: bool

scale: float

class suboptimumg.log_analysis.yaw_fit_models.ParamLayout

Bases: BaseModel

The ordered parameter vector for a fit: what is free, and within what box.

Free params appear in the optimizer’s x in free order; pinned params are held at their initial value and never reach the optimizer.

Fields

Field	Type	Required	Default
params	list[Param]	Yes

Parameters:

params (list[Param])

property bounds: tuple[NDArray[float64], NDArray[float64]]

(lo, hi) arrays, aligned with free.

property free: list[Param]

The parameters handed to the optimizer, in x order.

get(x, name)

Value of name given the optimizer’s current x.

Pinned parameters ignore x and return their held value.

Parameters:

• x (NDArray[float64])

• name (str)

Return type:

float

has(name)

Whether name is a parameter of this fit, free or pinned.

Parameters:

name (str)

Return type:

bool

property n_free: int

Length of the optimizer’s x vector.

named(x)

Every parameter keyed by name, free values taken from x.

Parameters:

x (NDArray[float64])

Return type:

dict[str, float]

params: list[Param]

property x0: NDArray[float64]

Initial guess, aligned with free.

property x_scale: NDArray[float64]

Characteristic magnitudes, aligned with free.

class suboptimumg.log_analysis.yaw_fit_models.Prediction

Bases: BaseModel

Per-sub-window predictions and residual diagnostics.

Shared by a training fit and a held-out evaluation, which differ only in which sub-windows they were computed over.

Fields

Field	Type	Required	Default
aic	float	Yes
bic	float	Yes
err_per_window	list[NDArray[float64]]	Yes
n_samples	int	Yes
window_metrics	list[WindowMetrics]	Yes
y_hat_per_window	list[NDArray[float64]]	Yes

Parameters:

• y_hat_per_window (list[NDArray[float64]])

• err_per_window (list[NDArray[float64]])

• window_metrics (list[WindowMetrics])

• n_samples (int)

• aic (float)

• bic (float)

aggregate()

RMSE / VAF pooled across this prediction’s sub-windows.

Return type:

AggregateMetrics

aic: float

bic: float

err_per_window: list[NDArray[np.float64]]

n_samples: int

window_metrics: list[WindowMetrics]

y_hat_per_window: list[NDArray[np.float64]]

class suboptimumg.log_analysis.yaw_fit_models.WindowArrays

Bases: BaseModel

Aligned numpy arrays for one sub-window, as the optimizer sees it.

Built once per sub-window by FitContext.arrays; every array shares the yaw-rate timestamp grid. u_rad is the steering input already converted to radians. body_slip_rad and bicycle_steer_rad are None when the corresponding channel is absent from the sub-window.

Fields

Field	Type	Required	Default
bicycle_steer_rad	NDArray[float64] | None	Yes
body_slip_rad	NDArray[float64] | None	Yes
speed	NDArray[float64]	Yes
sw_id	int	Yes
t	NDArray[float64]	Yes
u_rad	NDArray[float64]	Yes
yaw_rate	NDArray[float64]	Yes

Parameters:

• sw_id (int)

• t (NDArray[float64])

• speed (NDArray[float64])

• yaw_rate (NDArray[float64])

• u_rad (NDArray[float64])

• body_slip_rad (NDArray[float64] | None)

• bicycle_steer_rad (NDArray[float64] | None)

bicycle_steer_rad: NDArray[np.float64] | None

body_slip_rad: NDArray[np.float64] | None

property duration_s: float

Time spanned by the sub-window (s).

speed: NDArray[np.float64]

sw_id: int

t: NDArray[np.float64]

u_rad: NDArray[np.float64]

yaw_rate: NDArray[np.float64]

class suboptimumg.log_analysis.yaw_fit_models.WindowMetrics

Bases: BaseModel

Residual diagnostics for one sub-window.

ac metrics have the per-window DC offset removed, isolating how well the dynamics are captured from any steady-state bias.

Fields

Field	Type	Required	Default
dc_offset_rad_s	float	Yes
duration_s	float	Yes
mean_speed_mps	float	Yes
rmse_ac_rad_s	float	Yes
rmse_raw_rad_s	float	Yes
subwindow_id	int	Yes
vaf_ac_pct	float	Yes
yaw_rate_std_meas_rad_s	float	Yes

Parameters:

• subwindow_id (int)

• duration_s (float)

• mean_speed_mps (float)

• dc_offset_rad_s (float)

• rmse_raw_rad_s (float)

• rmse_ac_rad_s (float)

• yaw_rate_std_meas_rad_s (float)

• vaf_ac_pct (float)

dc_offset_rad_s: float

duration_s: float

mean_speed_mps: float

property rmse_ac_deg_s: float

rmse_ac_rad_s in deg/s.

rmse_ac_rad_s: float

rmse_raw_rad_s: float

subwindow_id: int

vaf_ac_pct: float

yaw_rate_std_meas_rad_s: float

class suboptimumg.log_analysis.yaw_fit_models.YawFit

Bases: BaseModel

A fitted yaw-response model: the spec, the parameters, and how well it did.

Carries everything needed to evaluate the model on new data (spec / layout / ctx / x_hat) and everything needed to report on the fit that produced it (train).

Fields

Field	Type	Required	Default
balance_mode	str	Yes
ctx	FitContext	Yes
final_cost	float	Yes
fit_view_count	int	Yes
layout	ParamLayout	Yes
message	str	Yes
n_eval	int	Yes
source_window_count	int	Yes
spec	FitSpec	Yes
status	int	Yes
train	Prediction	Yes
x_hat	NDArray[float64]	Yes

Parameters:

• spec (FitSpec)

• layout (ParamLayout)

• ctx (FitContext)

• x_hat (NDArray[float64])

• train (Prediction)

• final_cost (float)

• n_eval (int)

• status (int)

• message (str)

• balance_mode (str)

• fit_view_count (int)

• source_window_count (int)

aggregate()

RMSE / VAF pooled across the training sub-windows.

Return type:

AggregateMetrics

balance_mode: str

chassis_params()

This fit’s (Ca_f, Ca_r, Izz) triple.

Return type:

ChassisParams

ctx: FitContext

final_cost: float

fit_view_count: int

has_param(name)

Whether name is a parameter of this fit.

Parameters:

name (str)

Return type:

bool

layout: ParamLayout

message: str

n_eval: int

property n_params: int

Number of free parameters.

param(name)

Fitted (or pinned) value of name.

Parameters:

name (str)

Return type:

float

params_named()

Every fitted and pinned parameter, keyed by name.

Return type:

dict[str, float]

source_window_count: int

spec: FitSpec

status: int

train: Prediction

x_hat: NDArray[np.float64]