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 |
backend |
str
|
The backend for the simulation. The default value is |
__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'
|
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:
- The traffic participant is operating in a 2D plane (x-y).
- The left and right wheels always have the same steering angle and speed, so they can be regarded as a single wheel.
- The traffic participant is a rigid body, so its geometry does not change during the simulation.
- 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.
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.
|
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$).
|
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 |
__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.
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.
|
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.
|
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$).
|
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 |
__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.
|
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$).
|
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. |