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 [N*m]. In quasi-static mode this is zero by model assumption. In transient mode this is reported as the dynamic yaw residual I_z * dr/dt.	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
solver_mode	str	Solver mode used for this lap result.	'quasi_static'
time	ndarray | None	Optional cumulative time trace [s] for transient solver mode.	None
vx	ndarray | None	Optional body-frame longitudinal speed trace [m/s].	None
vy	ndarray | None	Optional body-frame lateral speed trace [m/s].	None
yaw_rate	ndarray | None	Optional yaw-rate trace [rad/s].	None
steer_cmd	ndarray | None	Optional steering command trace [rad].	None
ax_cmd	ndarray | None	Optional longitudinal acceleration command trace [m/s^2].	None

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.

PidSpeedSchedule dataclass

Piecewise-linear speed-dependent gain schedule.

Parameters:

Name	Type	Description	Default
speed_nodes_mps	tuple[float, ...]	Monotonic speed nodes [m/s].	required
values	tuple[float, ...]	Gain values at speed_nodes_mps.	required

evaluate

evaluate(speed_mps: float) -> float

Evaluate schedule at one speed by linear interpolation with clamping.

Parameters:

Name	Type	Description	Default
speed_mps	float	Evaluation speed [m/s].	required

Returns:

Type	Description
float	Interpolated schedule value.

evaluate_many

evaluate_many(speeds_mps: ndarray) -> np.ndarray

Evaluate schedule at multiple speeds.

Parameters:

Name	Type	Description	Default
speeds_mps	ndarray	Evaluation speeds [m/s].	required

Returns:

Type	Description
ndarray	Interpolated values for each input speed.

validate

validate() -> None

Validate PWL node/value vectors.

Raises:

Type	Description
ConfigurationError	If nodes or values are inconsistent.

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	Deprecated transient enable flag retained for one compatibility cycle.	DEFAULT_ENABLE_TRANSIENT_REFINEMENT
solver_mode	str	Solver mode identifier ("quasi_static" or "transient_oc").	DEFAULT_SOLVER_MODE
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
transient	TransientConfig	Transient-solver numerical and runtime controls.	TransientConfig()

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.

TorchTransientProfileResult dataclass

Differentiable torch transient-lap result tensors.

Parameters:

Name	Type	Description	Default
speed	Any	Total speed trace [m/s].	required
longitudinal_accel	Any	Net longitudinal acceleration trace [m/s^2].	required
lateral_accel	Any	Lateral acceleration trace [m/s^2].	required
lap_time	Any	Integrated lap time [s].	required
time	Any	Cumulative time trace [s].	required
vx	Any	Body-frame longitudinal speed trace [m/s].	required
vy	Any	Body-frame lateral speed trace [m/s].	required
yaw_rate	Any	Yaw-rate trace [rad/s].	required
steer_cmd	Any	Steering command trace [rad].	required
ax_cmd	Any	Longitudinal acceleration command trace [m/s^2].	required
objective_value	Any	Final OC objective value.	required

to_numpy

to_numpy() -> TransientProfileResult

Convert differentiable tensors to NumPy arrays.

Returns:

Type	Description
TransientProfileResult	NumPy transient profile result detached from autograd graph.

TransientConfig dataclass

Top-level transient OC configuration container.

Parameters:

Name	Type	Description	Default
numerics	TransientNumericsConfig	Transient numerical controls.	TransientNumericsConfig()
runtime	TransientRuntimeConfig	Transient runtime controls.	TransientRuntimeConfig()

validate

validate() -> None

Validate transient configuration.

Raises:

Type	Description
ConfigurationError	If transient settings are inconsistent.

TransientNumericsConfig dataclass

Numerical controls for the transient OC lap-time solver.

Parameters:

Name	Type	Description	Default
integration_method	str	Integration method used in state propagation ("euler" or "rk4").	DEFAULT_TRANSIENT_INTEGRATION_METHOD
max_iterations	int	Maximum optimization iterations.	DEFAULT_TRANSIENT_MAX_ITERATIONS
tolerance	float	Optimization convergence tolerance.	DEFAULT_TRANSIENT_TOLERANCE
min_time_step	float	Minimum integration step used during arc-length to time conversion [s].	DEFAULT_TRANSIENT_MIN_TIME_STEP
max_time_step	float	Maximum integration step used during arc-length to time conversion [s].	DEFAULT_TRANSIENT_MAX_TIME_STEP
lateral_constraint_weight	float	Penalty weight for lateral feasibility violations.	DEFAULT_TRANSIENT_LATERAL_CONSTRAINT_WEIGHT
tracking_weight	float	Penalty weight for transient path-tracking terms.	DEFAULT_TRANSIENT_TRACKING_WEIGHT
control_smoothness_weight	float	Penalty weight for control variation between neighboring samples.	DEFAULT_TRANSIENT_CONTROL_SMOOTHNESS_WEIGHT
control_interval	int	Arc-length sample interval used for optimization controls before interpolation to full track resolution.	DEFAULT_TRANSIENT_CONTROL_INTERVAL
optimizer_learning_rate	float	Initial optimizer learning rate.	DEFAULT_TRANSIENT_OPTIMIZER_LEARNING_RATE
optimizer_lbfgs_max_iter	int	Maximum iterations for one LBFGS step.	DEFAULT_TRANSIENT_OPTIMIZER_LBFGS_MAX_ITER
optimizer_adam_steps	int	Number of Adam fallback steps.	DEFAULT_TRANSIENT_OPTIMIZER_ADAM_STEPS
pid_longitudinal_kp	float	Proportional gain for longitudinal speed tracking.	DEFAULT_TRANSIENT_PID_LONGITUDINAL_KP
pid_longitudinal_ki	float	Integral gain for longitudinal speed tracking.	DEFAULT_TRANSIENT_PID_LONGITUDINAL_KI
pid_longitudinal_kd	float	Derivative gain for longitudinal speed tracking.	DEFAULT_TRANSIENT_PID_LONGITUDINAL_KD
pid_steer_kp	float	Proportional gain for yaw-rate steering feedback.	DEFAULT_TRANSIENT_PID_STEER_KP
pid_steer_ki	float	Integral gain for yaw-rate steering feedback.	DEFAULT_TRANSIENT_PID_STEER_KI
pid_steer_kd	float	Derivative gain for yaw-rate steering feedback.	DEFAULT_TRANSIENT_PID_STEER_KD
pid_steer_vy_damping	float	Damping term on lateral velocity for steering stabilization.	DEFAULT_TRANSIENT_PID_STEER_VY_DAMPING
pid_longitudinal_integral_limit	float	Absolute clamp for longitudinal PID integrator state.	DEFAULT_TRANSIENT_PID_LONGITUDINAL_INTEGRAL_LIMIT
pid_steer_integral_limit	float	Absolute clamp for steering PID integrator state.	DEFAULT_TRANSIENT_PID_STEER_INTEGRAL_LIMIT
pid_gain_scheduling_mode	str	PID gain scheduling mode: "off", "physics_informed", or "custom".	DEFAULT_TRANSIENT_PID_GAIN_SCHEDULING_MODE
pid_gain_scheduling	TransientPidGainSchedulingConfig | None	Optional custom schedule table set used when pid_gain_scheduling_mode="custom".	None

validate

validate() -> None

Validate transient numerical controls.

Raises:

Type	Description
ConfigurationError	If numerical controls violate required bounds.

TransientPidGainSchedulingConfig dataclass

Speed-dependent PID gain schedules.

Longitudinal schedules are used by point-mass and single-track PID drivers. Steering schedules are used by single-track PID drivers.

has_longitudinal_schedules

has_longitudinal_schedules() -> bool

Return whether all longitudinal schedules are present.

Returns:

Type	Description
bool	True when longitudinal kp, ki, and kd schedules are
bool	all configured.

has_steering_schedules

has_steering_schedules() -> bool

Return whether all steering schedules are present.

Returns:

Type	Description
bool	True when steering kp, ki, kd, and lateral-velocity
bool	damping schedules are all configured.

validate

validate() -> None

Validate scheduling config and node-grid consistency.

Raises:

Type	Description
ConfigurationError	If schedules are inconsistent.

TransientProfileResult dataclass

Transient speed-profile and state traces in arc-length sample order.

Parameters:

Name	Type	Description	Default
speed	ndarray	Total speed trace [m/s].	required
longitudinal_accel	ndarray	Net longitudinal acceleration trace [m/s^2].	required
lateral_accel	ndarray	Lateral acceleration trace [m/s^2].	required
lap_time	float	Integrated lap time [s].	required
time	ndarray	Cumulative time trace [s].	required
vx	ndarray	Body-frame longitudinal speed trace [m/s].	required
vy	ndarray	Body-frame lateral speed trace [m/s].	required
yaw_rate	ndarray	Yaw-rate trace [rad/s].	required
steer_cmd	ndarray	Steering command trace [rad].	required
ax_cmd	ndarray	Longitudinal acceleration command trace [m/s^2].	required
objective_value	float	Final OC objective value.	required

TransientRuntimeConfig dataclass

Runtime controls for transient OC solve behavior.

Parameters:

Name	Type	Description	Default
ode_backend_policy	str	ODE-backend selection policy.	DEFAULT_TRANSIENT_ODE_BACKEND_POLICY
optimizer_backend_policy	str	Optimizer-backend selection policy.	DEFAULT_TRANSIENT_OPTIMIZER_BACKEND_POLICY
driver_model	str	Driver/control strategy used inside the transient solver. "pid" applies deterministic closed-loop PID control. "optimal_control" runs full control optimization.	DEFAULT_TRANSIENT_DRIVER_MODEL
deterministic_seed	int | None	Optional deterministic seed used by stochastic optimizer fallbacks.	None
verbosity	int	Verbosity level for transient solver logging.	DEFAULT_TRANSIENT_OPTIMIZER_VERBOSE

validate

validate() -> None

Validate transient runtime controls.

Raises:

Type	Description
ConfigurationError	If runtime controls violate required bounds.

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, solver_mode: str | None = None, transient: TransientConfig | None = None, 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	Deprecated transient enable flag retained for one compatibility cycle.	DEFAULT_ENABLE_TRANSIENT_REFINEMENT
solver_mode	str | None	Optional solver mode identifier. When omitted, defaults to "quasi_static". Allowed values are "quasi_static" and "transient_oc".	None
transient	TransientConfig | None	Optional transient solver settings.	None
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.