Simulation

simulation

Simulation solvers and runners.

LapResult dataclass

Simulation output arrays and integrated metrics.

Parameters:

Name	Type	Description	Default
track	TrackData	Track geometry used for the simulation.	required
speed	ndarray	Converged speed trace along arc length [m/s].	required
longitudinal_accel	ndarray	Net longitudinal acceleration trace [m/s^2].	required
lateral_accel	ndarray	Lateral acceleration trace [m/s^2].	required
yaw_moment	ndarray	Yaw moment trace from model diagnostics [N*m].	required
front_axle_load	ndarray	Front-axle normal load trace [N].	required
rear_axle_load	ndarray	Rear-axle normal load trace [N].	required
power	ndarray	Tractive power trace [W].	required
energy	float	Integrated positive tractive energy [J].	required
lap_time	float	Integrated lap time [s].	required

ModelDiagnostics dataclass

Per-track-point diagnostics exposed by a vehicle model.

Parameters:

Name	Type	Description	Default
yaw_moment	float	Net yaw moment at the operating point [N*m].	required
front_axle_load	float	Front-axle normal load [N].	required
rear_axle_load	float	Rear-axle normal load [N].	required
power	float	Instantaneous tractive power [W].	required

NumericsConfig dataclass

Numerical controls for the lap-time solver.

Parameters:

Name	Type	Description	Default
min_speed	float	Numerical floor for speed to avoid singular divisions [m/s].	DEFAULT_MIN_SPEED
lateral_envelope_max_iterations	int	Maximum fixed-point iterations for the lateral-speed envelope solver.	DEFAULT_LATERAL_ENVELOPE_MAX_ITERATIONS
lateral_envelope_convergence_tolerance	float	Early-stop threshold for the lateral envelope fixed-point update (max |v_k - v_{k-1}|) [m/s].	DEFAULT_LATERAL_ENVELOPE_CONVERGENCE_TOLERANCE
transient_step	float	Integration step for optional transient refinement [s].	DEFAULT_TRANSIENT_STEP

validate

validate() -> None

Validate numerical solver settings.

Raises:

Type	Description
ConfigurationError	If any solver configuration value violates its bound.

RuntimeConfig dataclass

Runtime controls that define simulation scenario boundaries.

Parameters:

Name	Type	Description	Default
max_speed	float	Hard speed cap used by the quasi-steady profile solver [m/s].	required
initial_speed	float | None	Optional initial speed at the first track sample [m/s]. If None, the solver keeps the legacy behavior and initializes from lateral/global speed limits.	DEFAULT_INITIAL_SPEED
enable_transient_refinement	bool	Flag for optional second-pass transient solve.	DEFAULT_ENABLE_TRANSIENT_REFINEMENT
compute_backend	str	Numerical backend identifier (numpy, numba, or torch).	DEFAULT_COMPUTE_BACKEND
torch_device	str	Torch device identifier. numpy and numba are CPU-only backends and therefore require torch_device='cpu'.	DEFAULT_TORCH_DEVICE
torch_compile	bool	Reserved flag for future compile support in the torch backend. Must currently remain False.	DEFAULT_ENABLE_TORCH_COMPILE

validate

validate(numerics: NumericsConfig) -> None

Validate runtime controls against solver numerics.

Parameters:

Name	Type	Description	Default
numerics	NumericsConfig	Numerical parameter set used by the solver.	required

Raises:

Type	Description
ConfigurationError	If runtime controls are inconsistent with solver numerics or backend requirements.

SimulationConfig dataclass

Top-level solver config composed of runtime and numerics.

Parameters:

Name	Type	Description	Default
runtime	RuntimeConfig	Scenario and runtime controls, independent of physical car data.	required
numerics	NumericsConfig	Discretization and convergence controls for numerical solving.	required

validate

validate() -> None

Validate combined simulation settings.

Raises:

Type	Description
ConfigurationError	If runtime or numerical configuration values violate their bounds.

TorchSpeedProfileResult dataclass

Differentiable torch speed-profile output tensors.

Parameters:

Name	Type	Description	Default
speed	Any	Converged speed trace along track arc length [m/s].	required
longitudinal_accel	Any	Net longitudinal acceleration trace [m/s^2].	required
lateral_accel	Any	Lateral acceleration trace [m/s^2].	required
lateral_envelope_iterations	int	Number of fixed-point iterations used for lateral envelope convergence.	required
lap_time	Any	Integrated lap time over one track traversal [s].	required

to_numpy

to_numpy() -> SpeedProfileResult

Convert torch tensor result to SpeedProfileResult.

Returns:

Type	Description
SpeedProfileResult	NumPy-based speed-profile result detached from autograd graph.

VehicleModel

Bases: Protocol

Protocol required by the quasi-steady lap-time solver.

Any vehicle model (single-track, point-mass, twin-track, ...) can be used by the simulation pipeline as long as it implements this interface.

diagnostics

diagnostics(speed: float, longitudinal_accel: float, lateral_accel: float, curvature: float) -> ModelDiagnostics

Return diagnostic quantities used by analysis and plotting.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
longitudinal_accel	float	Net longitudinal acceleration along path tangent [m/s^2].	required
lateral_accel	float	Lateral acceleration [m/s^2].	required
curvature	float	Signed track curvature at the sample point [1/m].	required

Returns:

Type	Description
ModelDiagnostics	Diagnostic signals for post-processing and visualization.

lateral_accel_limit

lateral_accel_limit(speed: float, banking: float) -> float

Return lateral acceleration capability at the given operating point.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed at the queried operating point [m/s].	required
banking	float	Track banking angle at the queried point [rad].	required

Returns:

Type	Description
float	Maximum quasi-steady lateral acceleration magnitude [m/s^2].

max_longitudinal_accel

max_longitudinal_accel(speed: float, lateral_accel_required: float, grade: float, banking: float) -> float

Return net forward acceleration limit along the path tangent.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
lateral_accel_required	float	Required lateral acceleration magnitude [m/s^2].	required
grade	float	Track grade defined as dz/ds.	required
banking	float	Track banking angle [rad].	required

Returns:

Type	Description
float	Maximum net acceleration along the path tangent [m/s^2].

max_longitudinal_decel

max_longitudinal_decel(speed: float, lateral_accel_required: float, grade: float, banking: float) -> float

Return available deceleration magnitude along the path tangent.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
lateral_accel_required	float	Required lateral acceleration magnitude [m/s^2].	required
grade	float	Track grade defined as dz/ds.	required
banking	float	Track banking angle [rad].	required

Returns:

Type	Description
float	Maximum non-negative deceleration magnitude along path tangent [m/s^2].

validate

validate() -> None

Validate model parameters and configuration.

Raises:

Type	Description
ConfigurationError	If model parameters violate required physical or numerical constraints.

VehicleModelBase

Bases: ABC

Nominal OOP base class for solver-compatible vehicle models.

The solver continues to depend on :class:VehicleModel (Protocol) for structural flexibility. Concrete library backends can additionally subclass this abstract base class to make inheritance-based contracts and code sharing explicit.

diagnostics abstractmethod

diagnostics(speed: float, longitudinal_accel: float, lateral_accel: float, curvature: float) -> ModelDiagnostics

Return diagnostic quantities used by analysis and plotting.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
longitudinal_accel	float	Net longitudinal acceleration along path tangent [m/s^2].	required
lateral_accel	float	Lateral acceleration [m/s^2].	required
curvature	float	Signed track curvature at the sample point [1/m].	required

Returns:

Type	Description
ModelDiagnostics	Diagnostic signals for post-processing and visualization.

lateral_accel_limit abstractmethod

lateral_accel_limit(speed: float, banking: float) -> float

Return lateral acceleration capability at the given operating point.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed at the queried operating point [m/s].	required
banking	float	Track banking angle at the queried point [rad].	required

Returns:

Type	Description
float	Maximum quasi-steady lateral acceleration magnitude [m/s^2].

max_longitudinal_accel abstractmethod

max_longitudinal_accel(speed: float, lateral_accel_required: float, grade: float, banking: float) -> float

Return net forward acceleration limit along the path tangent.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
lateral_accel_required	float	Required lateral acceleration magnitude [m/s^2].	required
grade	float	Track grade defined as dz/ds.	required
banking	float	Track banking angle [rad].	required

Returns:

Type	Description
float	Maximum net acceleration along the path tangent [m/s^2].

max_longitudinal_decel abstractmethod

max_longitudinal_decel(speed: float, lateral_accel_required: float, grade: float, banking: float) -> float

Return available deceleration magnitude along the path tangent.

Parameters:

Name	Type	Description	Default
speed	float	Vehicle speed [m/s].	required
lateral_accel_required	float	Required lateral acceleration magnitude [m/s^2].	required
grade	float	Track grade defined as dz/ds.	required
banking	float	Track banking angle [rad].	required

Returns:

Type	Description
float	Maximum non-negative deceleration magnitude along path tangent [m/s^2].

validate abstractmethod

validate() -> None

Validate model parameters and configuration.

Raises:

Type	Description
ConfigurationError	If model parameters violate required physical or numerical constraints.

__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_simulation_config

build_simulation_config(max_speed: float = DEFAULT_MAX_SPEED, initial_speed: float | None = DEFAULT_INITIAL_SPEED, numerics: NumericsConfig | None = None, enable_transient_refinement: bool = DEFAULT_ENABLE_TRANSIENT_REFINEMENT, compute_backend: str = DEFAULT_COMPUTE_BACKEND, torch_device: str = DEFAULT_TORCH_DEVICE, torch_compile: bool = DEFAULT_ENABLE_TORCH_COMPILE) -> SimulationConfig

Build a validated simulation config with sensible numerical defaults.

Parameters:

Name	Type	Description	Default
max_speed	float	Runtime speed cap for the quasi-steady profile solver [m/s].	DEFAULT_MAX_SPEED
initial_speed	float | None	Optional initial speed at the first track sample [m/s]. If None, the solver keeps the legacy behavior and initializes from lateral/global speed limits.	DEFAULT_INITIAL_SPEED
numerics	NumericsConfig | None	Optional numerical settings. Defaults to :class:NumericsConfig.	None
enable_transient_refinement	bool	Flag for optional transient post-processing.	DEFAULT_ENABLE_TRANSIENT_REFINEMENT
compute_backend	str	Numerical backend identifier (numpy, numba, or torch).	DEFAULT_COMPUTE_BACKEND
torch_device	str	Torch device identifier. numpy and numba are CPU-only backends and therefore require torch_device='cpu'.	DEFAULT_TORCH_DEVICE
torch_compile	bool	Reserved flag for future compile support in the torch backend. Must currently remain False.	DEFAULT_ENABLE_TORCH_COMPILE

Returns:

Type	Description
SimulationConfig	Fully validated simulation configuration.

Raises:

Type	Description
ConfigurationError	If assembled runtime or numerical settings are inconsistent.