suboptimumg.vehicle.vehicle

class suboptimumg.vehicle.vehicle.Car(vehicle_model)

Bases: object

Composes all vehicle subsystems and simulates the car moving through a corner.

Parameters:

vehicle_model (VehicleModel)

accelerate_forwards_dx(radius, distance_step, state)

Advance the car forward by one distance step while accelerating.

Parameters:

• radius (float) – Radius of the current corner (m).

• distance_step (float) – Distance to advance (m).

• state (SimulationState) – Current simulation state.

Returns:

Updated simulation state after the step.

Return type:

SimulationState

brake_backwards_dx(radius, distance_step, state)

Integrate the car backward by one distance step while braking.

Parameters:

• radius (float) – Radius of the current corner (m).

• distance_step (float) – Distance to integrate backward (m).

• state (SimulationState) – Current simulation state.

Returns:

Updated simulation state after the step.

Return type:

SimulationState

calculate_and_return_longitudinal_forces(forces)

Compute the remaining longitudinal force budget for each tire.

Parameters:

forces (TireForces) – Tire forces to compute the remaining grip from.

Returns:

Longitudinal force budget (N) for each tire, in front-left, front-right, rear-left, rear-right order.

Return type:

list of float

calculate_tire_forces(acc, lat_acc, roll, pitch, vel, backwards_pass=False)

Compute the forces on each tire from weight transfer, aero lift and cornering.

Parameters:

• acc (float) – Longitudinal acceleration (m/s^2).

• lat_acc (float) – Lateral acceleration (m/s^2).

• roll (float) – Roll angle (rad).

• pitch (float) – Pitch angle (rad).

• vel (float) – Vehicle velocity (m/s).

• backwards_pass (bool) – Whether this is a backwards (braking) integration pass.

Returns:

Normal and lateral forces on all four tires.

Return type:

TireForces

calculate_top_speed(max_steps=20, v_low=0, v_high=50)

Binary search for the velocity where drag and rolling resistance equal max motor force.

Parameters:

• max_steps (int) – Maximum number of binary search iterations.

• v_low (float) – Lower bound of the search interval (m/s).

• v_high (float) – Upper bound of the search interval (m/s).

Returns:

Estimated top speed (m/s).

Return type:

float

car_weight_distributor(backwards_pass=False, *, acc, lat_acc)

Compute weight transfer and return each tire’s normal force.

Parameters:

• backwards_pass (bool) – Whether this is a backwards (braking) integration pass; flips the sign of the longitudinal acceleration used for weight transfer.

• acc (float) – Longitudinal acceleration (m/s^2).

• lat_acc (float) – Lateral acceleration (m/s^2).

Returns:

Normal forces (N) for the front-left, front-right, rear-left, and rear-right tires.

Return type:

tuple of float

check_all_tires_valid_lateral_force(forces)

Check whether every tire’s lateral force is within its friction limit.

Parameters:

forces (TireForces) – Tire forces to check.

Returns:

True if all tires satisfy their lateral force limit.

Return type:

bool

coast_forwards_dx(radius, distance_step, state)

Lift off the throttle and coast (with regen) for one distance step.

Parameters:

• radius (float) – Radius of the current corner (m).

• distance_step (float) – Distance to advance (m).

• state (SimulationState) – Current simulation state.

Returns:

Updated simulation state after the step.

Return type:

SimulationState

convert_rotating_mass_to_linear_mass()

Compute the linear-mass equivalent of all rotating inertia (tires, rims, motor, gearbox).

Returns:

Equivalent linear mass (kg), i.e. rotating inertia J divided by tire radius squared, summed across all rotating components.

Return type:

float

get_current_params(var_name)

Retrieve the current value of a car parameter given its dotted name.

Parameters:

var_name (str) – The name of the parameter to retrieve (e.g., ‘pwrtn.motor.max_rpm’).

Returns:

The current value of the specified parameter.

Return type:

object

Raises:

AttributeError – If var_name does not name a car parameter.

Notes

Parameters hold values of many types, so the value is returned as-is. Callers that need a number are responsible for asserting that the value is numeric, which is application-specific.

max_stable_speed(radius, converge_steps=20, resolution=0.008, stabilize_steps=1)

Binary search for the maximum speed at which the car can safely navigate a corner.

Parameters:

• radius (float) – Radius of the corner (m).

• converge_steps (int) – Maximum number of solution iterations.

• resolution (float) – Tolerance of the final velocity solution (m/s).

• stabilize_steps (int) – How many times to iterate each velocity check. Needed for roll/pitch/etc. sensitivity (should be >1, ideally >5, when used).

Returns:

The maximum stable cornering speed (m/s).

Return type:

float

Notes

The acceleration does not need to be near zero when converged (e.g. for an understeery car).

modify_params(var_name, new_var_value)

Modify a car parameter given its dotted name and new value.

Parameters:

• var_name (str) – The name of the parameter to modify (e.g., ‘pwrtn.motor.max_rpm’).

• new_var_value (object) – The new value to set for the specified parameter.

Raises:

• AttributeError – If var_name does not name a car parameter.

• ValidationError – If the value is rejected by the parameter’s own validation.

Return type:

None

Notes

The parameter models use validate_assignment, so an unknown leaf name surfaces as a Pydantic ValidationError rather than an AttributeError. That case is translated here so a bad name always raises AttributeError, whichever part of the path is wrong, while a genuinely invalid value keeps its original validation error.

try_accelerate_forwards_for_max_speed_calc(radius, state)

Check whether the car can hold the given speed through a corner of the given radius.

Parameters:

• radius (float) – Corner radius (m).

• state (SimulationState) – Current simulation state.

Returns:

True if the powertrain and tires can sustain this speed through the corner.

Return type:

bool

Notes

Approximates a steady-state weight transfer by zeroing longitudinal acceleration for this check (a simplification pending further investigation of longitudinal weight transfer behavior).