Single Track Augmented¶

Single track (bicycle model) vehicle dynamics with augmented parameters.

Notes

Extends the single-track model with additional scaling parameters for delta, velocity, yaw rate, and slip angle. Registers a ModelSpec for integration with the optimization stack.

Param ¶

Jittable params for augmented single-track dynamics.

Supports both scalar and batched parameters. When batched, each field should be a 1D array of shape [batch_size]; otherwise each field is a scalar.

Attributes:

Name	Type	Description
`mu`	`float or Array`	Surface friction coefficient.
`C_Sf, C_Sr`	`float or Array`	Cornering stiffness coefficients (front/rear).
`lf, lr`	`float or Array`	Distances from center of gravity to front/rear axles.
`h`	`float or Array`	Height of center of gravity.
`m`	`float or Array`	Vehicle mass.
`I`	`float or Array`	Moment of inertia about the z axis.
`alpha_delta, beta_delta`	`float or Array`	Steering angle gain and bias.
`alpha_v, beta_v`	`float or Array`	Longitudinal acceleration gain and bias.
`alpha_yaw_rate, beta_yaw_rate`	`float or Array`	Yaw rate gain and bias.
`alpha_slip_angle, beta_slip_angle`	`float or Array`	Slip angle gain and bias.
`s_min, s_max`	`float or Array`	Steering angle limits.
`sv_min, sv_max`	`float or Array`	Steering velocity limits.
`v_switch`	`float or Array`	Velocity above which acceleration is reduced.
`a_max`	`float or Array`	Maximum longitudinal acceleration.
`v_min, v_max`	`float or Array`	Velocity limits.
`width, length`	`float or Array`	Vehicle dimensions in meters.
`timestep`	`float or Array`	Physics integration timestep.
`timestep_ratio`	`int or Array`	Simulation steps per control step (static field).

State ¶

Container for augmented single-track state batches.

Attributes:

Name	Type	Description
`cartesian_states`	`Array`	Array shaped `[n_agent, [x, y, delta, v, psi, (psi_dot, beta)]]`.

vehicle_dynamics_st_switching ¶

vehicle_dynamics_st_switching(x_and_u, params)

Single-track vehicle dynamics with augmentation gains.

Based on https://gitlab.lrz.de/tum-cps/commonroad-vehicle-models/-/blob/master/vehicleModels_commonRoad.pdf, section 7.

Parameters:

Name	Type	Description	Default
`x_and_u`	`Array`	Vehicle state vector with control inputs, shape `(9,)`: x0: x position (global) x1: y position (global) x2: steering angle of front wheels x3: velocity in x direction x4: yaw angle x5: yaw rate x6: slip angle u0: steering angle velocity of front wheels u1: longitudinal acceleration	required
`params`	`Param`	Jittable dataclass of vehicle parameters and augmentation gains.	required

Returns:

Type	Description
`Array`	Right-hand side of the differential equations, shape `(7,)`.

yaw_normalized_loss ¶

yaw_normalized_loss(
    output_states, target_states, *, include_auxiliary=True
)

Yaw-normalized loss between output and target states.

Handles angular differences by wrapping them to [-pi, pi] and uses L1 loss for non-angular components.

Parameters:

Name	Type	Description	Default
`output_states`	`Array`	Predicted states of shape `(..., 7)`.	required
`target_states`	`Array`	Target states of shape `(..., 7)`.	required
`include_auxiliary`	`bool`	When True, include auxiliary dimensions (psi_dot, beta) in the loss.	`True`

Returns:

Type	Description
`float`	Total loss summed over all elements.

yaw_normalized_loss_per_element ¶

yaw_normalized_loss_per_element(
    output_states, target_states, *, include_auxiliary=True
)

Yaw-normalized loss per state dimension.

Parameters:

Name	Type	Description	Default
`output_states`	`Array`	Predicted states of shape `(B, T, 7)`.	required
`target_states`	`Array`	Target states of shape `(B, T, 7)`.	required
`include_auxiliary`	`bool`	Include auxiliary dimensions when True.	`True`

Returns:

Type	Description
`Array`	Loss per dimension of shape `(B, 7)`.

yaw_normalized_loss_per_item ¶

yaw_normalized_loss_per_item(
    output_states, target_states, *, include_auxiliary=True
)

Yaw-normalized loss per item in the batch.

Assumes input shape is (B, T, D) where D=7.

Parameters:

Name	Type	Description	Default
`output_states`	`Array`	Predicted states of shape `(B, T, 7)`.	required
`target_states`	`Array`	Target states of shape `(B, T, 7)`.	required
`include_auxiliary`	`bool`	Include auxiliary dimensions when True.	`True`

Returns:

Type	Description
`Array`	Loss per batch item of shape `(B,)`.

yaw_normalized_loss_weighted ¶

yaw_normalized_loss_weighted(
    output_states,
    target_states,
    weights=None,
    *,
    include_auxiliary=True,
)

Weighted yaw-normalized loss for state dimensions.

Parameters:

Name	Type	Description	Default
`output_states`	`Array`	Predicted states of shape `(..., 7)`.	required
`target_states`	`Array`	Target states of shape `(..., 7)`.	required
`weights`	`Array`	Per-dimension weights of shape `(7,)`. Defaults to ones.	`None`
`include_auxiliary`	`bool`	Include auxiliary dimensions when True.	`True`

Returns:

Type	Description
`float`	Weighted loss value.

Raises:

Type	Description
`ValueError`	If `weights` has an unexpected shape.