Vehicle¶

vehicle ¶

Vehicle models and parameters.

ControlInput `dataclass` ¶

Control inputs for the single-track model.

Parameters:

Name	Type	Description	Default
`steer`	`float`	Front-wheel steering angle [rad].	required
`longitudinal_accel_cmd`	`float`	Commanded longitudinal acceleration [m/s^2].	required

ForceBalance `dataclass` ¶

Force-balance quantities used for analysis and integration.

Parameters:

Name	Type	Description	Default
`front_slip_angle`	`float`	Front equivalent slip angle [rad].	required
`rear_slip_angle`	`float`	Rear equivalent slip angle [rad].	required
`front_lateral_force`	`float`	Front-axle lateral tire force [N].	required
`rear_lateral_force`	`float`	Rear-axle lateral tire force [N].	required
`yaw_moment`	`float`	Net yaw moment about center of gravity [N*m].	required

PointMassCalibrationResult `dataclass` ¶

Calibration outputs for matching point-mass lateral limits to single_track behavior.

Parameters:

Name	Type	Description	Default
`friction_coefficient`	`float`	Identified isotropic friction coefficient (-).	required
`speed_samples`	`ndarray`	Calibration speed samples used by the identification [m/s].	required
`single_track_lateral_limit`	`ndarray`	SingleTrack-model lateral limit evaluated at `speed_samples` [m/s^2].	required
`normal_accel_limit`	`ndarray`	Point-mass normal acceleration budget evaluated at `speed_samples` [m/s^2].	required
`mu_samples`	`ndarray`	Per-sample effective friction ratios computed as `single_track_lateral_limit / normal_accel_limit` (-).	required

PointMassModel ¶

Bases: PointMassTorchBackendMixin, PointMassNumbaBackendMixin, PointMassPhysicalMixin, EnvelopeVehicleModel

Vehicle-model API implementation for a point-mass backend.

The class is intentionally composed from separate OOP layers:

PointMassPhysicalMixin for backend-agnostic physics,
PointMassNumbaBackendMixin for numba-specific solver adapter API,
PointMassTorchBackendMixin for torch-specific solver adapter API.

init ¶

__init__(vehicle: VehicleParameters, physics: PointMassPhysics) -> None

Initialize point-mass solver backend.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle parameterization for mass, aero, and axle split.	required
`physics`	`PointMassPhysics`	Point-mass physical model settings.	required

Raises:

Type	Description
`ConfigurationError`	If any provided parameter set is invalid.

PointMassPhysics `dataclass` ¶

Physical inputs for the point-mass lap-time model.

Parameters:

Name	Type	Description	Default
`max_drive_accel`	`float`	Maximum forward tire acceleration on flat road and zero lateral demand, excluding drag and grade [m/s^2].	`8.0`
`max_brake_accel`	`float`	Maximum braking deceleration magnitude on flat road and zero lateral demand, excluding drag and grade [m/s^2].	`16.0`
`friction_coefficient`	`float`	Isotropic tire-road friction coefficient used for lateral limit and friction-circle coupling (-).	`1.7`

envelope `property` ¶

envelope: EnvelopePhysics

Return shared longitudinal envelope limits.

Returns:

Type	Description
`EnvelopePhysics`	Internal shared envelope-limit representation used by multiple
`EnvelopePhysics`	solver model families.

validate ¶

validate() -> None

Validate physical model parameters.

Raises:

Type	Description
`ConfigurationError`	If limits or friction settings violate required bounds.

SingleTrackDynamicsModel ¶

3-DOF single-track dynamics model using lateral Pacejka tire forces.

init ¶

__init__(vehicle: VehicleParameters, tires: AxleTireParameters) -> None

Initialize the single-track model with validated parameters.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle and chassis parameterization.	required
`tires`	`AxleTireParameters`	Front/rear Pacejka parameter sets.	required

Raises:

Type	Description
`ConfigurationError`	If vehicle or tire parameters are invalid.

derivatives ¶

derivatives(state: VehicleState, control: ControlInput) -> VehicleState

Compute time derivatives for state integration.

Parameters:

Name	Type	Description	Default
`state`	`VehicleState`	Vehicle state `(vx, vy, yaw_rate)`.	required
`control`	`ControlInput`	Steering and longitudinal acceleration command.	required

Returns:

Type	Description
`VehicleState`	Time derivatives `(dvx/dt, dvy/dt, dr/dt)` in SI units.

force_balance ¶

force_balance(state: VehicleState, control: ControlInput) -> ForceBalance

Evaluate lateral forces and yaw moment for the current state.

Parameters:

Name	Type	Description	Default
`state`	`VehicleState`	Vehicle state `(vx, vy, yaw_rate)`.	required
`control`	`ControlInput`	Steering and longitudinal acceleration command.	required

Returns:

Type	Description
`ForceBalance`	Force-balance terms including slip angles, tire forces, and yaw moment.

from_array `staticmethod` ¶

from_array(values: ndarray) -> VehicleState

Convert ndarray to state dataclass.

Parameters:

Name	Type	Description	Default
`values`	`ndarray`	State vector with at least three elements.	required

Returns:

Type	Description
`VehicleState`	Parsed vehicle state dataclass.

sanitize_speed `staticmethod` ¶

sanitize_speed(speed: float) -> float

Apply a numerical lower bound to speed.

Parameters:

Name	Type	Description	Default
`speed`	`float`	Raw speed [m/s].	required

Returns:

Type	Description
`float`	Speed clamped to a positive lower bound for numerical stability.

slip_angles ¶

slip_angles(state: VehicleState, steer: float) -> tuple[float, float]

Compute front and rear axle slip angles.

Parameters:

Name	Type	Description	Default
`state`	`VehicleState`	Vehicle state `(vx, vy, yaw_rate)`.	required
`steer`	`float`	Front-wheel steering angle [rad].	required

Returns:

Type	Description
`tuple[float, float]`	Tuple `(front_slip_angle, rear_slip_angle)`.

to_array `staticmethod` ¶

to_array(state: VehicleState) -> np.ndarray

Convert state dataclass to ndarray.

Parameters:

Name	Type	Description	Default
`state`	`VehicleState`	Vehicle state dataclass.	required

Returns:

Type	Description
`ndarray`	State vector `[vx, vy, yaw_rate]`.

SingleTrackModel ¶

Bases: SingleTrackTorchBackendMixin, SingleTrackNumbaBackendMixin, SingleTrackPhysicalMixin, EnvelopeVehicleModel

Vehicle-model API implementation for the single-track dynamics backend.

The class is intentionally composed from separate OOP layers:

SingleTrackPhysicalMixin for backend-agnostic single-track physics,
SingleTrackNumbaBackendMixin for numba-specific solver adapter API,
SingleTrackTorchBackendMixin for torch-specific solver adapter API.

init ¶

__init__(vehicle: VehicleParameters, tires: AxleTireParameters, physics: SingleTrackPhysics, numerics: SingleTrackNumerics) -> None

Initialize single-track-backed solver adapter.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle parameterization for dynamics and aero.	required
`tires`	`AxleTireParameters`	Front/rear Pacejka tire coefficients.	required
`physics`	`SingleTrackPhysics`	Physical model inputs for the adapter.	required
`numerics`	`SingleTrackNumerics`	Numerical controls for iterative envelope solving.	required

Raises:

Type	Description
`ConfigurationError`	If any provided parameter set is invalid.

SingleTrackNumerics `dataclass` ¶

Numerical controls for the single-track solver model.

Parameters:

Name	Type	Description	Default
`min_lateral_accel_limit`	`float`	Lower bound for lateral-acceleration iteration to avoid degenerate starts [m/s^2].	`DEFAULT_MIN_LATERAL_ACCEL_LIMIT`
`lateral_limit_max_iterations`	`int`	Maximum fixed-point iterations for lateral acceleration limit estimation.	`DEFAULT_LATERAL_LIMIT_MAX_ITERATIONS`
`lateral_limit_convergence_tolerance`	`float`	Convergence threshold for lateral acceleration fixed-point updates [m/s^2].	`DEFAULT_LATERAL_LIMIT_CONVERGENCE_TOLERANCE`

validate ¶

validate() -> None

Validate numerical settings for the adapter.

Raises:

Type	Description
`ConfigurationError`	If numerical values violate bounds needed for robust convergence.

SingleTrackPhysics `dataclass` ¶

Physical and model-level inputs for the single-track solver model.

Parameters:

Name	Type	Description	Default
`max_drive_accel`	`float`	Maximum forward tire acceleration on flat road and zero lateral demand, excluding drag and grade [m/s^2].	`8.0`
`max_brake_accel`	`float`	Maximum braking deceleration magnitude on flat road and zero lateral demand, excluding drag and grade [m/s^2].	`16.0`
`peak_slip_angle`	`float`	Quasi-steady peak slip angle used to evaluate tire lateral force capability in the envelope iteration [rad].	`0.12`

envelope `property` ¶

envelope: EnvelopePhysics

Return shared longitudinal envelope limits.

Returns:

Type	Description
`EnvelopePhysics`	Internal shared envelope-limit representation used by multiple
`EnvelopePhysics`	solver model families.

single_track_lateral `property` ¶

single_track_lateral: _SingleTrackLateralPhysics

Return single-track-specific lateral approximation inputs.

Returns:

Type	Description
`_SingleTrackLateralPhysics`	Internal single-track-specific lateral-envelope representation.

validate ¶

validate() -> None

Validate physical adapter parameters.

Raises:

Type	Description
`ConfigurationError`	If limits are not strictly positive.

VehicleParameters `dataclass` ¶

Vehicle and chassis parameters for lap-time simulation.

Parameters:

Name	Type	Description	Default
`mass`	`float`	Vehicle mass [kg].	required
`yaw_inertia`	`float`	Yaw moment of inertia [kg*m^2].	required
`cg_height`	`float`	Center-of-gravity height above ground [m].	required
`wheelbase`	`float`	Wheelbase [m].	required
`front_track`	`float`	Front track width [m].	required
`rear_track`	`float`	Rear track width [m].	required
`front_weight_fraction`	`float`	Static front axle weight fraction in [0, 1].	required
`cop_position`	`float`	Center-of-pressure position relative to CoG [m].	required
`lift_coefficient`	`float`	Aerodynamic lift/downforce coefficient.	required
`drag_coefficient`	`float`	Aerodynamic drag coefficient.	required
`frontal_area`	`float`	Frontal reference area [m^2].	required
`roll_rate`	`float`	Roll rate [N*m/deg].	required
`front_spring_rate`	`float`	Front spring rate [N/m].	required
`rear_spring_rate`	`float`	Rear spring rate [N/m].	required
`front_arb_distribution`	`float`	Front anti-roll-bar distribution in [0, 1].	required
`front_ride_height`	`float`	Front ride height [m].	required
`rear_ride_height`	`float`	Rear ride height [m].	required
`air_density`	`float`	Air density [kg/m^3].	required

cg_to_front_axle `property` ¶

cg_to_front_axle: float

Distance from center of gravity to front axle.

Returns:

Type	Description
`float`	Front axle distance from center of gravity [m].

cg_to_rear_axle `property` ¶

cg_to_rear_axle: float

Distance from center of gravity to rear axle.

Returns:

Type	Description
`float`	Rear axle distance from center of gravity [m].

validate ¶

validate() -> None

Validate configuration values before simulation.

Raises:

Type	Description
`ConfigurationError`	If any parameter violates its defined bound.

VehicleState `dataclass` ¶

Vehicle state for the single-track model.

Parameters:

Name	Type	Description	Default
`vx`	`float`	Longitudinal velocity in body frame [m/s].	required
`vy`	`float`	Lateral velocity in body frame [m/s].	required
`yaw_rate`	`float`	Yaw rate [rad/s].	required

getattr ¶

__getattr__(name: str) -> Any

Resolve lazily imported symbols for public package exports.

Parameters:

Name	Type	Description	Default
`name`	`str`	Attribute name requested from the package namespace.	required

Returns:

Type	Description
`Any`	Exported class or function matching `name`.

Raises:

Type	Description
`AttributeError`	If `name` is not part of the public export surface.

build_point_mass_model ¶

build_point_mass_model(vehicle: VehicleParameters, physics: PointMassPhysics | None = None) -> PointMassModel

Build a point-mass solver model with sensible defaults.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle parameterization for mass, aero, and axle split.	required
`physics`	`PointMassPhysics \| None`	Optional physical model settings. Defaults to :class:`PointMassPhysics`.	`None`

Returns:

Type	Description
`PointMassModel`	Fully validated solver-facing point-mass model.

build_single_track_model ¶

build_single_track_model(vehicle: VehicleParameters, tires: AxleTireParameters, physics: SingleTrackPhysics | None = None, numerics: SingleTrackNumerics | None = None) -> SingleTrackModel

Build a single-track solver model with sensible numerical defaults.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle parameterization for dynamics and aero.	required
`tires`	`AxleTireParameters`	Front/rear Pacejka tire coefficients.	required
`physics`	`SingleTrackPhysics \| None`	Optional physical model inputs for longitudinal and lateral limits. Defaults to :class:`SingleTrackPhysics`.	`None`
`numerics`	`SingleTrackNumerics \| None`	Optional numerical controls. Defaults to :class:`SingleTrackNumerics`.	`None`

Returns:

Type	Description
`SingleTrackModel`	Fully validated solver-facing single-track model.

calibrate_point_mass_friction_to_single_track ¶

calibrate_point_mass_friction_to_single_track(vehicle: VehicleParameters, tires: AxleTireParameters, single_track_physics: SingleTrackPhysics | None = None, single_track_numerics: SingleTrackNumerics | None = None, speed_samples: ndarray | None = None) -> PointMassCalibrationResult

Calibrate point-mass friction coefficient to single_track lateral capability.

The calibration matches the point-mass isotropic lateral limit mu * (g + F_down(v)/m) to the single_track model's quasi-steady lateral limit in a least-squares sense over provided speed samples.

Parameters:

Name	Type	Description	Default
`vehicle`	`VehicleParameters`	Vehicle parameterization shared by both models.	required
`tires`	`AxleTireParameters`	Tire parameters used by the single_track model.	required
`single_track_physics`	`SingleTrackPhysics \| None`	Optional single_track-physics settings for calibration. Defaults to :class:`apexsim.vehicle.SingleTrackPhysics`.	`None`
`single_track_numerics`	`SingleTrackNumerics \| None`	Optional single_track numerical settings for calibration. Defaults to :class:`apexsim.vehicle.SingleTrackNumerics`.	`None`
`speed_samples`	`ndarray \| None`	Optional calibration speeds [m/s]. If omitted, a linear sweep from 10 to 90 m/s is used.	`None`

Returns:

Type	Description
`PointMassCalibrationResult`	Calibration result with identified friction coefficient and
`PointMassCalibrationResult`	intermediate traces.

Raises:

Type	Description
`ConfigurationError`	If provided speed samples are empty or contain non-positive entries.

Vehicle¶

vehicle ¶

ControlInput dataclass ¶

ForceBalance dataclass ¶

PointMassCalibrationResult dataclass ¶

PointMassModel ¶

__init__ ¶

PointMassPhysics dataclass ¶

envelope property ¶

validate ¶

SingleTrackDynamicsModel ¶

__init__ ¶

derivatives ¶

force_balance ¶

from_array staticmethod ¶

sanitize_speed staticmethod ¶

slip_angles ¶

to_array staticmethod ¶

SingleTrackModel ¶

__init__ ¶

SingleTrackNumerics dataclass ¶

validate ¶

SingleTrackPhysics dataclass ¶

envelope property ¶

single_track_lateral property ¶

validate ¶

VehicleParameters dataclass ¶

cg_to_front_axle property ¶

cg_to_rear_axle property ¶

validate ¶

VehicleState dataclass ¶

__getattr__ ¶

build_point_mass_model ¶

build_single_track_model ¶

calibrate_point_mass_friction_to_single_track ¶

ControlInput `dataclass` ¶

ForceBalance `dataclass` ¶

PointMassCalibrationResult `dataclass` ¶

init ¶

PointMassPhysics `dataclass` ¶

envelope `property` ¶

init ¶

from_array `staticmethod` ¶

sanitize_speed `staticmethod` ¶

to_array `staticmethod` ¶

init ¶

SingleTrackNumerics `dataclass` ¶

SingleTrackPhysics `dataclass` ¶

envelope `property` ¶

single_track_lateral `property` ¶

VehicleParameters `dataclass` ¶

cg_to_front_axle `property` ¶

cg_to_rear_axle `property` ¶

VehicleState `dataclass` ¶

getattr ¶