suboptimumg.vehicle.vehicle_models

class suboptimumg.vehicle.vehicle_models.AlignmentModel

Bases: BaseModel

Wheel alignment configuration.

Fields

Field	Type	Required	Default
camber_front_deg	float	Yes
camber_rear_deg	float	Yes
toe_front_deg	float	Yes
toe_rear_deg	float	Yes

Parameters:

• camber_front_deg (float)

• camber_rear_deg (float)

• toe_front_deg (float)

• toe_rear_deg (float)

camber_front_deg: float

camber_rear_deg: float

toe_front_deg: float

toe_rear_deg: float

class suboptimumg.vehicle.vehicle_models.DynamicsPriorBoundsModel

Bases: BaseModel

Soft +/- percentage bounds for the yaw-response bicycle priors.

Used by an LPV output-error fit to build the optimizer’s parameter box around Ca_front, Ca_rear and Izz.

Fields

Field	Type	Required	Default	Constraints
Ca_front_pct	float	Yes		ge=0
Ca_rear_pct	float	Yes		ge=0
Izz_pct	float	Yes		ge=0

Parameters:

• Ca_front_pct (Annotated[float, Ge(ge=0)])

• Ca_rear_pct (Annotated[float, Ge(ge=0)])

• Izz_pct (Annotated[float, Ge(ge=0)])

Ca_front_pct: float

Ca_rear_pct: float

Izz_pct: float

class suboptimumg.vehicle.vehicle_models.DynamicsSetupModel

Bases: BaseModel

Linear-region bicycle-model parameters used as soft priors for a LPV yaw-response output-error fit

Backsolve from four cornering operating points (skidpad / steady turns) using SAE bicycle algebra:

delta_tire = L/R + (m/L)(l_r/Ca_f - l_f/Ca_r) V^2/R beta = l_r/R - (m a_y l_f) / (L Ca_r)

Ca_r is the multi-point consensus from three well-conditioned points. Ca_f comes from the lowest-a_y point only (front tires saturate above ~1g, biasing fits low). Izz should be an FSAE rule-of-thumb (~0.7 m wb track / 4).

Fields

Field	Type	Required	Default	Constraints
Ca_front_N_per_rad	float	Yes		gt=0
Ca_rear_N_per_rad	float	Yes		gt=0
Izz_kg_m2	float	Yes		gt=0
prior_bounds	DynamicsPriorBoundsModel	Yes

Parameters:

• Ca_front_N_per_rad (Annotated[float, Gt(gt=0)])

• Ca_rear_N_per_rad (Annotated[float, Gt(gt=0)])

• Izz_kg_m2 (Annotated[float, Gt(gt=0)])

• prior_bounds (DynamicsPriorBoundsModel)

Ca_front_N_per_rad: float

Ca_rear_N_per_rad: float

Izz_kg_m2: float

prior_bounds: DynamicsPriorBoundsModel

class suboptimumg.vehicle.vehicle_models.ExtendedVehicleModel

Bases: VehicleModel

VehicleModel extended with real-world session setup parameters.

Set type: irl_setup in the YAML to trigger this model. Includes alignment, steering ackermann, suspension setup, and yaw-response dynamics priors on top of the base car parameters.

Fields

Field	Type	Required	Default	Constraints
accum	AccumulatorModel	Yes
aero	AeroModel	Yes
alignment	AlignmentModel	Yes
cg_h	float	Yes		gt=0
chass	ChassisModel | None	No	None
dri	DriverInterfaceModel	Yes
dynamics_setup	DynamicsSetupModel	Yes
front_track	float	Yes		gt=0
mass	float	Yes		gt=0
pwrtn	PowertrainModel	Yes
rear_track	float	Yes		gt=0
rolling_coeff	float	Yes		ge=0
steering_setup	SteeringSetupModel	Yes
sus	SimpleSuspensionModel | ComplexSuspensionModel	Yes
suspension_setup	SuspensionSetupModel	Yes
tires	TireModel	Yes
type	Literal[‘irl_setup’]	No	'irl_setup'
w_distr_b	float	Yes		gt=0, lt=1
wb	float	Yes		gt=0

Validators

Validator	Mode	Fields
validate_rolling_coeff	after	rolling_coeff

Parameters:

• type (Literal['irl_setup'])

• mass (Annotated[float, Gt(gt=0)])

• w_distr_b (Annotated[float, Gt(gt=0), Lt(lt=1)])

• cg_h (Annotated[float, Gt(gt=0)])

• wb (Annotated[float, Gt(gt=0)])

• front_track (Annotated[float, Gt(gt=0)])

• rear_track (Annotated[float, Gt(gt=0)])

• rolling_coeff (Annotated[float, Ge(ge=0)])

• aero (AeroModel)

• pwrtn (PowertrainModel)

• accum (AccumulatorModel)

• sus (SimpleSuspensionModel | ComplexSuspensionModel)

• tires (TireModel)

• dri (DriverInterfaceModel)

• chass (ChassisModel | None)

• alignment (AlignmentModel)

• steering_setup (SteeringSetupModel)

• suspension_setup (SuspensionSetupModel)

• dynamics_setup (DynamicsSetupModel)

alignment: AlignmentModel

dynamics_setup: DynamicsSetupModel

steering_setup: SteeringSetupModel

suspension_setup: SuspensionSetupModel

type: Literal['irl_setup']

class suboptimumg.vehicle.vehicle_models.FittedCurve(data, poly_order)

Bases: object

Polynomial fit of tabulated [x, y] data with Horner evaluation.

Parameters:

• data (list of [x, y] pairs) – Raw tabulated input data.

• poly_order (int) – Polynomial degree for the least-squares fit.

x_raw, y_raw

Original input arrays.

Type:

NDArray[np.float64]

poly_order

Type:

int

coeffs

Polynomial coefficients in descending degree order [c_n, c_{n-1}, ..., c_1, c_0], matching np.polyfit output and the order Horner’s method consumes directly.

Type:

NDArray[np.float64]

coeffs: NDArray[float64]

evaluate(x)

Evaluate the fitted polynomial via Horner’s method.

Parameters:

x (float | NDArray[np.float64]) – Input value(s) at which to evaluate.

Returns:

Evaluated polynomial value(s).

Return type:

np.float64 | NDArray[np.float64]

x_raw: NDArray[float64]

y_raw: NDArray[float64]

class suboptimumg.vehicle.vehicle_models.FittedCurveData

Bases: TypedDict

Raw YAML shape for a FittedCurve before it is constructed.

data: list[list[float]]

poly_order: int

class suboptimumg.vehicle.vehicle_models.SteeringSetupModel

Bases: BaseModel

Steering geometry and ackermann curve configuration.

Fields

Field	Type	Required	Default
ackermann	FittedCurve	Yes

Validators

Validator	Mode	Fields
coerce_ackermann	before	ackermann

Parameters:

ackermann (FittedCurve)

ackermann: FittedCurve

classmethod coerce_ackermann(v)

Parameters:

v (FittedCurve | FittedCurveData)

Return type:

FittedCurve | FittedCurveData

class suboptimumg.vehicle.vehicle_models.SuspensionSetupModel

Bases: BaseModel

Real-world suspension setup parameters.

Fields

Field	Type	Required	Default	Constraints
anti_dive_pct	float	Yes		ge=0, le=1
anti_squat_pct	float	Yes		ge=0, le=1
heave_stiffness_front_N_per_m	float	Yes		gt=0
heave_stiffness_rear_N_per_m	float	Yes		gt=0
motion_ratio_front	float	Yes		gt=0
motion_ratio_rear	float	Yes		gt=0
roll_stiffness_front_Nm_per_rad	float	Yes		gt=0
roll_stiffness_rear_Nm_per_rad	float	Yes		gt=0

Parameters:

• roll_stiffness_front_Nm_per_rad (Annotated[float, Gt(gt=0)])

• roll_stiffness_rear_Nm_per_rad (Annotated[float, Gt(gt=0)])

• heave_stiffness_front_N_per_m (Annotated[float, Gt(gt=0)])

• heave_stiffness_rear_N_per_m (Annotated[float, Gt(gt=0)])

• anti_dive_pct (Annotated[float, Ge(ge=0), Le(le=1.0)])

• anti_squat_pct (Annotated[float, Ge(ge=0), Le(le=1.0)])

• motion_ratio_front (Annotated[float, Gt(gt=0)])

• motion_ratio_rear (Annotated[float, Gt(gt=0)])

anti_dive_pct: float

anti_squat_pct: float

heave_stiffness_front_N_per_m: float

heave_stiffness_rear_N_per_m: float

motion_ratio_front: float

motion_ratio_rear: float

roll_stiffness_front_Nm_per_rad: float

roll_stiffness_rear_Nm_per_rad: float

class suboptimumg.vehicle.vehicle_models.VehicleModel

Bases: BaseModel

Full vehicle configuration composed of all subsystem models.

Fields

Field	Type	Required	Default	Constraints
accum	AccumulatorModel	Yes
aero	AeroModel	Yes
cg_h	float	Yes		gt=0
chass	ChassisModel | None	No	None
dri	DriverInterfaceModel	Yes
front_track	float	Yes		gt=0
mass	float	Yes		gt=0
pwrtn	PowertrainModel	Yes
rear_track	float	Yes		gt=0
rolling_coeff	float	Yes		ge=0
sus	SimpleSuspensionModel | ComplexSuspensionModel	Yes
tires	TireModel	Yes
type	Literal[‘base’]	No	'base'
w_distr_b	float	Yes		gt=0, lt=1
wb	float	Yes		gt=0

Validators

Validator	Mode	Fields
validate_rolling_coeff	after	rolling_coeff

Parameters:

• type (Literal['base'])

• mass (Annotated[float, Gt(gt=0)])

• w_distr_b (Annotated[float, Gt(gt=0), Lt(lt=1)])

• cg_h (Annotated[float, Gt(gt=0)])

• wb (Annotated[float, Gt(gt=0)])

• front_track (Annotated[float, Gt(gt=0)])

• rear_track (Annotated[float, Gt(gt=0)])

• rolling_coeff (Annotated[float, Ge(ge=0)])

• aero (AeroModel)

• pwrtn (PowertrainModel)

• accum (AccumulatorModel)

• sus (SimpleSuspensionModel | ComplexSuspensionModel)

• tires (TireModel)

• dri (DriverInterfaceModel)

• chass (ChassisModel | None)

accum: AccumulatorModel

aero: AeroModel

cg_h: float

chass: ChassisModel | None

dri: DriverInterfaceModel

front_track: float

mass: float

pwrtn: PowertrainModel

rear_track: float

rolling_coeff: float

sus: SimpleSuspensionModel | ComplexSuspensionModel

tires: TireModel

property track: float

type: Literal['base']

classmethod validate_rolling_coeff(v)

Parameters:

v (float)

Return type:

float

w_distr_b: float

property w_distr_front: float

wb: float