Single Track¶

Single track (bicycle model) vehicle dynamics.

Provides dataclasses for vehicle parameters/state, switching single-track dynamics, constraint helpers, and yaw-normalized loss functions.

Examples:

>>> import pct.dynamics.singletrack as st
>>> params = st.Param(m=9.44, lf=0.3626, lr=0.2615, mu=0.3695)
>>> next_state = st.vehicle_dynamics_st_switching(state_and_control, params)
>>> loss = st.yaw_normalized_loss(predictions, targets)

Param ¶

Jittable params for 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.
`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 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 (bicycle) vehicle dynamics with switching model.

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 (friction, stiffness, geometry, limits).	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.