Skip to content

tactics2d.physics

PhysicsModelBase

Bases: ABC

This abstract class defines the essential interfaces required to specify a physics kinematics/dynamics model for a traffic participant.

Please feel free to inherent this class to implement your own physics model.

Attributes:

Name Type Description
_DELTA_T int

The default time interval between the current state and the new state, 5 milliseconds (ms).

_MIN_DELTA_T int

The minimum time interval between the current state and the new state, 1 millisecond (ms).

_G float

The gravitational acceleration, 9.81 m/s^2.

step(state, action, interval=None) abstractmethod

This abstract function defines an interface to update the state of the traffic participant based on the physics model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
action tuple

The action to be applied to the traffic participant.

required
interval int

The time interval between the current state and the new state. The unit is millisecond.

None

Returns:

Type Description
State

A new state of the traffic participant.

verify_state(state, last_state, interval=None) abstractmethod

This abstract function defines an interface to verify the validity of the new state based on the physics model.

Parameters:

Name Type Description Default
state State

The new state of the traffic participant.

required
last_state State

The last state of the traffic participant.

required
interval int

The time interval between the last state and the new state. The unit is millisecond.

None

Returns:

Type Description
bool

True if the new state is valid, False otherwise.

verify_states(trajectory)

This function verifies a sequence of states over time based on the physics model. The default implementation calls verify_state() for each state in the sequence. However, this function is expected to be overridden to implement more efficient verification.

Parameters:

Name Type Description Default
trajectory Trajectory

The trajectory of the traffic participant.

required

Returns:

Type Description
bool

True if the trajectory is valid, False otherwise.

PointMass

Bases: PhysicsModelBase

This class implements a point mass model for a traffic participant. The point mass model supposes that the mass of the object is concentrated at the center of the object. The state of the object is represented by its center position, velocity, and heading. The object is assumed to be operating in a 2D plane (x-y).

Warning

This model is recommended to be used for pedestrians. Because the point mass model ignores that vehicles have a minimum turning circle, if this model is used for bicycle and vehicles, the results will not be accurate.

Attributes:

Name Type Description
speed_range Union[float, Tuple[float, float]]

The range of speed. The valid input is a float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s). The default value is None, which means no constraint on the speed. When the speed_range is negative or the min speed is not less than the max speed, the speed_range is set to None.

accel_range Union[float, Tuple[float, float]]

The range of acceleration. The valid input is a float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$). The default value is None, which means no constraint on the acceleration. When the accel_range is negative or the min acceleration is not less than the max acceleration, the accel_range is set to None.

interval int

The time interval between the current state and the new state. The unit is millisecond. Defaults to None.

delta_t int

The discrete time step for the simulation. The unit is millisecond. Defaults to _DELTA_T(5 ms). The expected value is between _MIN_DELTA_T(1 ms) and interval. It is recommended to keep delta_t smaller than 5 ms.

backend str

The backend for the simulation. The default value is newton. The available choices are newton and euler. The newton backend is recommended because it is faster. The euler backend is used for comparison and testing purposes at currently. We plan to improve the euler backend in the future (maybe in version 1.1.0)

__init__(speed_range=None, accel_range=None, interval=100, delta_t=None, backend='newton')

Initialize the point mass model.

Parameters:

Name Type Description Default
speed_range Union[float, Tuple[float, float]]

The range of speed. The valid input is a positive float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s).

None
accel_range Union[float, Tuple[float, float]]

The range of acceleration. The valid input is a positive float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

None
interval int

The time interval between the current state and the new state. The unit is millisecond.

100
delta_t int

The discrete time step for the simulation. The unit is millisecond.

None
backend str

The backend for the simulation. The available choices are newton and euler.

'newton'

step(state, accel, interval=None)

This function updates the state of the traffic participant based on the point mass model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
accel Tuple[float, float]

The acceleration vector ($a_x$, $a_y$). The unit of the acceleration is meter per second squared (m/s$^2$).

required
interval int

The time interval between the current state and the new state. The unit is millisecond.

None

Returns:

Name Type Description
next_state State

A new state of the traffic participant.

verify_state(state, last_state, interval=None)

This function provides a very rough check for the state transition. It checks whether the acceleration and the steering angle are within the range.

Parameters:

Name Type Description Default
state State

The new state of the traffic participant.

required
last_state State

The last state of the traffic participant.

required
interval int

The time interval between the last state and the new state. The unit is millisecond.

None

Returns:

Type Description
bool

True if the new state is valid, False otherwise.

SingleTrackKinematics

Bases: PhysicsModelBase

This class implements a kinematic single-track bicycle model for a traffic participant.

The is a simplified model to simulate the traffic participant's physics. The assumptions in this implementation include:

  1. The traffic participant is operating in a 2D plane (x-y).
  2. The left and right wheels always have the same steering angle and speed, so they can be regarded as a single wheel.
  3. The traffic participant is a rigid body, so its geometry does not change during the simulation.
  4. The traffic participant is Front-Wheel Drive (FWD).

This implementation version is based on the following paper. It regard the geometry center as the reference point.

Kinematic Single Track Model

Demo of the implementation (interval=100 ms, $\Delta t$=5 ms)

Reference

Kong, Jason, et al. "Kinematic and dynamic vehicle models for autonomous driving control design." 2015 IEEE intelligent vehicles symposium (IV). IEEE, 2015.

Warning

This model will lose its accuracy when the time step is set too large or the traffic participant is made to travel at a high speed.

Attributes:

Name Type Description
lf float

The distance from the geometry center to the front axle center. The unit is meter.

lr float

The distance from the geometry center to the rear axle center. The unit is meter.

steer_range Union[float, Tuple[float, float]]

The steering angle range. The valid input is a float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

  • When the steer_range is a non-negative float, the steering angle is constrained to be within the range [-steer_range, steer_range].
  • When the steer_range is a tuple, the steering angle is constrained to be within the range [min steering angle, max steering angle].
  • When the steer_range is negative or the min steering angle is not less than the max steering angle, the steer_range is set to None.
speed_range Union[float, Tuple[float, float]]

The speed range. The valid input is a float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s). - When the speed_range is a non-negative float, the speed is constrained to be within the range [-speed_range, speed_range]. - When the speed_range is a tuple, the speed is constrained to be within the range [min speed, max speed]. - When the speed_range is negative or the min speed is not less than the max speed, the speed_range is set to None.

accel_range Union[float, Tuple[float, float]]

The acceleration range. The valid input is a float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

  • When the accel_range is a non-negative float, the acceleration is constrained to be within the range [-accel_range, accel_range].
  • When the accel_range is a tuple, the acceleration is constrained to be within the range [min acceleration, max acceleration].
  • When the accel_range is negative or the min acceleration is not less than the max acceleration, the accel_range is set to None.
interval int

The time interval between the current state and the new state. The unit is millisecond. Defaults to None.

delta_t int

The time step for the simulation. The unit is millisecond. Defaults to _DELTA_T(5 ms). The expected value is between _MIN_DELTA_T(1 ms) and interval. It is recommended to keep delta_t smaller than 5 ms.

__init__(lf, lr, steer_range=None, speed_range=None, accel_range=None, interval=100, delta_t=None)

Initialize the kinematic single-track model.

Parameters:

Name Type Description Default
lf float

The distance from the center of mass to the front axle center. The unit is meter.

required
lr float

The distance from the center of mass to the rear axle center. The unit is meter.

required
steer_range Union[float, Tuple[float, float]]

The range of steering angle. The valid input is a positive float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

None
speed_range Union[float, Tuple[float, float]]

The range of speed. The valid input is a positive float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s).

None
accel_range Union[float, Tuple[float, float]]

The range of acceleration. The valid input is a positive float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

None
interval int

The time interval between the current state and the new state. The unit is millisecond.

100
delta_t int

The discrete time step for the simulation. The unit is millisecond.

None

step(state, accel, delta, interval=None)

This function updates the state of the traffic participant with the Kinematic Single-Track Model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
accel float

The acceleration of the traffic participant. The unit is meter per second squared (m/s$^2$).

required
delta float

The steering angle of the traffic participant. The unit is radian.

required
interval int

The time interval between the current state and the new state. The unit is millisecond.

None

Returns:

Name Type Description
next_state State

The new state of the traffic participant.

accel float

The acceleration that is applied to the traffic participant.

delta float

The steering angle that is applied to the traffic participant.

verify_state(state, last_state, interval=None)

This function provides a very rough check for the state transition.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
last_state State

The last state of the traffic participant.

required
interval int

The time interval between the last state and the new state. The unit is millisecond.

None

Returns:

Type Description
bool

True if the new state is valid, False otherwise.

SingleTrackDynamics

Bases: PhysicsModelBase

This class implements a dynamic single-track model for a vehicle.

The dynamic single-track model is a simplified model to simulate the vehicle dynamics. It combines the front and rear wheels into a single wheel, and the vehicle is assumed to be a point mass.

Demo of the implementation (interval=100 ms, $\Delta t$=5 ms)

Reference

The dynamic single-track model is based on Chapter 7 of the following reference: CommonRoad: Vehicle Models (2020a)

Attributes:

Name Type Description
lf float

The distance from the geometry center to the front axle center. The unit is meter.

lr float

The distance from the geometry center to the rear axle center. The unit is meter.

steer_range Union[float, Tuple[float, float]]

The steering angle range. The valid input is a float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

  • When the steer_range is a non-negative float, the steering angle is constrained to be within the range [-steer_range, steer_range].
  • When the steer_range is a tuple, the steering angle is constrained to be within the range [min steering angle, max steering angle].
  • When the steer_range is negative or the min steering angle is not less than the max steering angle, the steer_range is set to None.
mass float

The mass of the vehicle. The unit is kilogram.

mass_height float

The height of the center of mass from the ground. The unit is meter.

mu float

The friction coefficient. It is a dimensionless quantity. Defaults to 0.7.

I_z float

The moment of inertia of the vehicle. The unit is kilogram per meter squared (kg/m$^2$). Defaults to 1500.

cf float

The cornering stiffness of the front wheel. The unit is 1/rad. Defaults to 20.89.

cr float

The cornering stiffness of the rear wheel. The unit is 1/rad. Defaults to 20.89.

steer_range Union[float, Tuple[float, float]]

The steering angle range. The valid input is a float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

  • When the steer_range is a non-negative float, the steering angle is constrained to be within the range [-steer_range, steer_range].
  • When the steer_range is a tuple, the steering angle is constrained to be within the range [min steering angle, max steering angle].
  • When the steer_range is negative or the min steering angle is not less than the max steering angle, the steer_range is set to None.
speed_range Union[float, Tuple[float, float]]

The speed range. The valid input is a float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s). - When the speed_range is a non-negative float, the speed is constrained to be within the range [-speed_range, speed_range]. - When the speed_range is a tuple, the speed is constrained to be within the range [min speed, max speed]. - When the speed_range is negative or the min speed is not less than the max speed, the speed_range is set to None.

accel_range Union[float, Tuple[float, float]]

The acceleration range. The valid input is a float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

  • When the accel_range is a non-negative float, the acceleration is constrained to be within the range [-accel_range, accel_range].
  • When the accel_range is a tuple, the acceleration is constrained to be within the range [min acceleration, max acceleration].
  • When the accel_range is negative or the min acceleration is not less than the max acceleration, the accel_range is set to None.
interval int

The time interval between the current state and the new state. The unit is millisecond. Defaults to None.

delta_t int

The time step for the simulation. The unit is millisecond. Defaults to _DELTA_T(5 ms). The expected value is between _MIN_DELTA_T(1 ms) and interval. It is recommended to keep delta_t smaller than 5 ms.

__init__(lf, lr, mass, mass_height, mu=0.7, I_z=1500, cf=20.89, cr=20.89, steer_range=None, speed_range=None, accel_range=None, interval=100, delta_t=None)

Initializes the single-track dynamics model.

Parameters:

Name Type Description Default
lf float

The distance from the center of mass to the front axle center. The unit is meter.

required
lr float

The distance from the center of mass to the rear axle center. The unit is meter.

required
mass float

The mass of the vehicle. The unit is kilogram. You can use the curb weight of the vehicle as an approximation.

required
mass_height float

The height of the center of mass from the ground. The unit is meter. You can use half of the vehicle height as an approximation.

required
mu float

The friction coefficient. It is a dimensionless quantity.

0.7
I_z float

The moment of inertia of the vehicle. The unit is kilogram per meter squared (kg/m$^2$).

1500
cf float

The cornering stiffness of the front wheel. The unit is 1/rad.

20.89
cr float

The cornering stiffness of the rear wheel. The unit is 1/rad.

20.89
steer_range Union[float, Tuple[float, float]]

The range of steering angle. The valid input is a positive float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

None
speed_range Union[float, Tuple[float, float]]

The range of speed. The valid input is a positive float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s).

None
accel_range Union[float, Tuple[float, float]]

The range of acceleration. The valid input is a positive float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

None
interval int

The time interval between the current state and the new state. The unit is millisecond.

100
delta_t int

The discrete time step for the simulation. The unit is millisecond.

None

step(state, accel, delta, interval=None)

This function updates the state of the vehicle based on the dynamics single-track model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
accel float

The acceleration of the traffic participant. The unit is meter per second squared (m/s$^2$).

required
delta float

The steering angle of the traffic participant. The unit is radian.

required
interval int

The time interval between the current state and the new state. The unit is millisecond.

None

Returns:

Name Type Description
next_state State

The new state of the traffic participant.

accel float

The acceleration that is applied to the traffic participant.

delta float

The steering angle that is applied to the traffic participant.

verify_state(state, last_state, interval=None)

This function provides a very rough check for the state transition.

Info

Uses the same rough check as the single track kinematics model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
last_state State

The last state of the traffic participant.

required
interval int

The time interval between the last state and the new state. The unit is millisecond.

None

Returns:

Type Description
bool

True if the new state is valid, False otherwise.

SingleTrackDrift

Bases: PhysicsModelBase

This class implements a dynamic single-track model for a vehicle.

Warning

This class was designed "as a simplification of the multi-body" model. Theoretically, it is applicable to the All-Wheel-Drive (AWD) vehicle. However, the tire model is so complicated that it is not fully tested in tactics2d v1.0.0. The current implementation is based on the MATLAB code provided by the CommonRoad project. Please use it with caution.

Reference

The dynamic single-track model is based on Chapter 8 of the following reference: CommonRoad: Vehicle Models (2020a)

Pacejka, Hans. Tire and vehicle dynamics. Elsevier, 2005.

Attributes:

Name Type Description
lf float

The distance from the center of mass to the front axle. The unit is meter (m).

lr float

The distance from the center of mass to the rear axle. The unit is meter (m).

mass float

The mass of the vehicle. The unit is kilogram (kg).

mass_height float

The height of the center of mass. The unit is meter (m).

radius float

The effective radius of the wheel. The unit is meter (m). Defaults to 0.344.

T_sb float

The split parameter between the front and rear axles for the braking torque. Defaults to 0.76.

T_se float

The split parameter between the front and rear axles for the engine torque. Defaults to 1.

tire Any

The tire model. Default to the in-built tire model.

I_z float

The moment of inertia of the vehicle. The unit is kilogram meter squared (kg m^2). Defaults to 1500.

I_yw float

The moment of inertia of the wheel. The unit is kilogram meter squared (kg m^2). Defaults to 1.7.

steer_range Union[float, Tuple[float, float]]

The steering angle range. The valid input is a float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

  • When the steer_range is a non-negative float, the steering angle is constrained to be within the range [-steer_range, steer_range].
  • When the steer_range is a tuple, the steering angle is constrained to be within the range [min steering angle, max steering angle].
  • When the steer_range is negative or the min steering angle is not less than the max steering angle, the steer_range is set to None.
speed_range Union[float, Tuple[float, float]]

The speed range. The valid input is a float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s). - When the speed_range is a non-negative float, the speed is constrained to be within the range [-speed_range, speed_range]. - When the speed_range is a tuple, the speed is constrained to be within the range [min speed, max speed]. - When the speed_range is negative or the min speed is not less than the max speed, the speed_range is set to None.

accel_range Union[float, Tuple[float, float]]

The acceleration range. The valid input is a float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

  • When the accel_range is a non-negative float, the acceleration is constrained to be within the range [-accel_range, accel_range].
  • When the accel_range is a tuple, the acceleration is constrained to be within the range [min acceleration, max acceleration].
  • When the accel_range is negative or the min acceleration is not less than the max acceleration, the accel_range is set to None.
interval int

The time interval between the current state and the new state. The unit is millisecond. Defaults to None.

delta_t int

The default time interval between the current state and the new state, 5 milliseconds (ms). Defaults to None.

__init__(lf, lr, mass, mass_height, radius=0.344, T_sb=0.76, T_se=1, tire=Tire(), I_z=1500, I_yw=1.7, steer_range=None, speed_range=None, accel_range=None, interval=100, delta_t=None)

Initializes the single-track drift model.

Parameters:

Name Type Description Default
lf float

The distance from the center of mass to the front axle center. The unit is meter.

required
lr float

The distance from the center of mass to the rear axle center. The unit is meter.

required
mass float

The mass of the vehicle. The unit is kilogram. You can use the curb weight of the vehicle as an approximation.

required
mass_height float

The height of the center of mass from the ground. The unit is meter. You can use half of the vehicle height as an approximation.

required
radius float

The effective radius of the wheel. The unit is meter.

0.344
T_sb float

The split parameter between the front and rear axles for the braking torque.

0.76
T_se float

The split parameter between the front and rear axles for the engine torque.

1
tire Any

The tire model. The current implementation refers to the parameters in CommonRoad: Vehicle Models (2020a). If you want to use a different tire model, you need to implement the tire model by yourself.

Tire()
I_z float

The moment of inertia of the vehicle. The unit is kilogram meter squared (kg m^2).

1500
I_yw float

The moment of inertia of the wheel. The unit is kilogram meter squared (kg m^2).

1.7
steer_range Union[float, Tuple[float, float]]

The range of steering angle. The valid input is a positive float or a tuple of two floats represents (min steering angle, max steering angle). The unit is radian.

None
speed_range Union[float, Tuple[float, float]]

The range of speed. The valid input is a positive float or a tuple of two floats represents (min speed, max speed). The unit is meter per second (m/s).

None
accel_range Union[float, Tuple[float, float]]

The range of acceleration. The valid input is a positive float or a tuple of two floats represents (min acceleration, max acceleration). The unit is meter per second squared (m/s$^2$).

None
interval int

The time interval between the current state and the new state. The unit is millisecond.

100
delta_t int

The discrete time step for the simulation. The unit is millisecond.

None

step(state, omega_wf, omega_wr, accel, delta, interval=None)

This function updates the state of the traffic participant based on the single-track drift model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
omega_wf float

The angular velocity of the front wheel. The unit is radian per second (rad/s).

required
omega_wr float

The angular velocity of the rear wheel. The unit is radian per second (rad/s).

required
accel float

The acceleration of the traffic participant. The unit is meter per second squared (m/s$^2$).

required
delta float

The steering angle of the traffic participant. The unit is radian.

required
interval int

The time interval between the current state and the new state. The unit is millisecond.

None

Returns:

Name Type Description
next_state State

The new state of the traffic participant.

next_omega_wf float

The new angular velocity of the front wheel. The unit is radian per second (rad/s).

next_omega_wr float

The new angular velocity of the rear wheel. The unit is radian per second (rad/s).

accel float

The acceleration that is applied to the traffic participant.

delta float

The steering angle that is applied to the traffic participant.

verify_state(state, last_state, interval=None)

This function provides a very rough check for the state transition.

Info

Uses the same rough check as the single track kinematics model.

Parameters:

Name Type Description Default
state State

The current state of the traffic participant.

required
last_state State

The last state of the traffic participant.

required
interval int

The time interval between the last state and the new state. The unit is millisecond.

None

Returns:

Type Description
bool

True if the new state is valid, False otherwise.