Unicycle

The control input is forward speed and angular turn rate in radians per second. The turn rate is independent of the vehicle width W. For left and right wheel-speed inputs, use roboticstoolbox.mobile.DiffSteer instead.

class Unicycle(W=1, steer_max=inf, **kwargs)[source]

Bases: VehicleBase

Unicycle kinematic model

__init__(W=1, steer_max=inf, **kwargs)[source]

Create unicycle kinematic model

Parameters:

W (float) – vehicle width, defaults to 1
steer_max (float) – maximum turn rate
kwargs (Any) – additional arguments passed to VehicleBase constructor

Model the motion of a unicycle model with equations of motion given by:

\[\begin{split}\dot{x} &= v \cos \theta \\ \dot{y} &= v \sin \theta \\ \dot{\theta} &= \omega\end{split}\]

where \(v\) is the velocity in body frame x-direction, and \(\omega\) is the turn rate.

deriv(x, u, limits=True)[source]

Time derivative of state

Parameters:

x (ndarray | Sequence[float]) – vehicle state \((x, y, \theta)\)
u (ndarray | Sequence[float]) – control input \((v, \omega)\)
limits (bool) – limits are applied to input, default True

Returns:

state derivative \((\dot{x}, \dot{y}, \dot{\theta})\)

Return type:

ndarray

Returns the time derivative of state (3x1) at the state x with velocity \(v\) and turn rate \(\omega\)

\[\begin{split}\dot{x} &= v \cos \theta \\ \dot{y} &= v \sin \theta \\ \dot{\theta} &= \omega\end{split}\]

The turn rate is an angular velocity in radians per second, independent of the vehicle width W. If limits is True then speed, acceleration and turn-rate limits are applied to u.

See also

f()

u_limited(u)[source]

Apply vehicle velocity, acceleration and steering limits

Parameters:: u (ndarray | Sequence[float]) – Desired vehicle inputs \((v, \omega)\)
Returns:: Allowable vehicle inputs \((v, \omega)\)
Return type:: ndarray

Velocity and acceleration limits are applied to \(v\) and turn rate limits are applied to \(\omega\).

Fv(x, odo)

Jacobian of state transition function df/dv

Parameters:

x (ndarray | Sequence[float]) – vehicle state \((x, y, \theta)\)
odo (ndarray | Sequence[float]) – vehicle odometry \((\delta_d, \delta_\theta)\)

Returns:

Jacobian matrix

Return type:

ndarray

Returns the Jacobian matrix \(\frac{\partial \vec{f}}{\partial \vec{v}}\) for the given state and odometry.

See also

f() deriv() Fx()

Fx(x, odo)

Jacobian of state transition function df/dx

Parameters:

x (ndarray | Sequence[float]) – vehicle state \((x, y, \theta)\)
odo (ndarray | Sequence[float]) – vehicle odometry \((\delta_d, \delta_\theta)\)

Returns:

Jacobian matrix

Return type:

ndarray

Returns the Jacobian matrix \(\frac{\partial \vec{f}}{\partial \vec{x}}\) for the given state and odometry.

See also

f() deriv() Fv()

__repr__()

Convert to string, same as __str__()

Return type:: str
Returns:: String representation of vehicle object

property accel_max: float

Get maximum acceleration of vehicle (superclass)

Returns:: maximum acceleration
Return type:: float

Set by VehicleBase() subclass constructor.

See also

speed_max() steer_max u_limited()

add_driver(driver)

Add a driver agent (superclass)

Parameters:: driver (VehicleDriverBase) – a driver agent object
Return type:: None

Warning

Deprecated. Use vehicle.control = driver instead.

See also

VehicleDriverBase control()

property control: Union[ndarray, Sequence[float], Callable[..., ndarray | Sequence[float]], interp1d, VehicleDriverBase, None]

Get/set vehicle control (superclass)

Getter:: Returns vehicle’s control
Setter:: Sets the vehicle’s control
Type:: 2-tuple, callable, interp1d or VehicleDriver

This is the input to the vehicle during a simulation performed by run(). The control input can be:

a constant tuple as the control inputs to the vehicle

a function called as f(vehicle, t, x) that returns a tuple

an interpolator called as f(t) that returns a tuple

a driver agent, subclass of VehicleDriverBase

Example:

>>> from roboticstoolbox import Bicycle, RandomPath
>>> bike = Bicycle()
>>> bike.control = RandomPath(workspace=10)
>>> print(bike)
Bicycle: x = [ 0, 0, 0 ]
  L=1, steer_max=1.41372, speed_max=inf, accel_max=inf

property dt: float

Get sample time (superclass)

Returns:: discrete time step for simulation
Return type:: float

Set by VehicleBase() subclass constructor. Used by step() to update state.

See also

run()

eval_control(control, x)

Evaluate vehicle control input (superclass method)

Parameters:

control (Union[ndarray, Sequence[float], Callable[..., ndarray | Sequence[float]], interp1d, VehicleDriverBase, None]) – vehicle control
x (ndarray | Sequence[float]) – vehicle state \((x, y, heta)\)

Raises:

ValueError – bad control

Returns:

vehicle control inputs

Return type:

ndarray

Evaluates the control for this time step and state. Control is set by the control() property to:

a constant tuple as the control inputs to the vehicle

a function called as f(vehicle, t, x) that returns a tuple

an interpolator called as f(t) that returns a tuple

a driver agent, subclass of VehicleDriverBase

Vehicle steering, speed and acceleration limits are applied to the result before being input to the vehicle model.

See also

run() control() scipy.interpolate.interp1d()

f(x, odo, v=None)

State transition function

Parameters:

x (ndarray | Sequence[float]) – vehicle state \((x, y, \theta)\)
odo (ndarray | Sequence[float]) – vehicle odometry \((\delta_d, \delta_\theta)\)
v (ndarray | Sequence[float] | None) – additive odometry noise, defaults to (0,0)

Returns:

predicted vehicle state

Return type:

ndarray

Predict the next state based on current state and odometry value. v is a random variable that represents additive odometry noise for simulation purposes.

\[f: \vec{x}_k, \delta_d, \delta_\theta \mapsto \vec{x}_{k+1}\]

For particle filters it is useful to apply the odometry to the states of all particles and this can be achieved if x is a 2D array with one state per row. v is ignored in this case.

Note

This is the state update equation used for EKF localization.

See also

deriv() Fx() Fv()

init(x0=None, control=None, animate=True)

Initialize for simulation (superclass)

Parameters:: x0 (ndarray | Sequence[float] | None) – Initial state, defaults to value given to Vehicle constructor
Return type:: None

Performs the following initializations:

Clears the state history

Set the private random number generator to initial value

Sets state \(x = x_0\)

Sets previous velocity to zero

If a driver is attached, initialize it

If animation is enabled, initialize that

If animation is enabled by constructor and no animation object is given, use a default VehiclePolygon("car")

See also

VehicleAnimationBase run()

limits_va(v, v_prev)

Apply velocity and acceleration limits (superclass)

Parameters:

v (float) – desired velocity
v_prev (list[float]) – previous velocity, reference to list

Returns:

allowed velocity

Return type:

float

Determine allowable velocity given desired velocity, speed and acceleration limits.

Note

This function requires previous velocity, v_prev to enable acceleration limiting. This is passed as a reference to a mutable value, a single-element list. This is reset to zero at the start of each simulation.

plot(x)

Return type:: None

plot_xy(*args, block=None, **kwargs)

Plot xy-path from history

Parameters:

block (bool | None) – None leaves showing the figure to the environment (no plt.show call), False shows it and returns at once, True shows it and waits until it is closed; ignored by notebook backends, defaults to None
args (Any) – positional arguments passed to plot()
kwargs (Any) – keyword arguments passed to plot()

Return type:

None

The \((x,y)\) trajectory from the simulation history is plotted as \(x\) vs \(y\).

See also

run() plot_xyt()

plot_xyt(block=None, **kwargs)

Plot configuration vs time from history

Parameters:

block (bool | None) – None leaves showing the figure to the environment (no plt.show call), False shows it and returns at once, True shows it and waits until it is closed; ignored by notebook backends, defaults to None
kwargs (Any) – keyword arguments passed to plot()

Return type:

None

The \((x,y, heta)\) trajectory from the simulation history is plotted against time.

See also

run() plot_xy()

polygon(q)

Bounding polygon at vehicle configuration

Parameters:: q (ndarray | Sequence[float]) – vehicle configuration \((x, y, heta)\)
Returns:: bounding polygon of vehicle at configuration q
Return type:: Polygon2
Raises:: ValueError – the vehicle has no bounding polygon

The bounding polygon of the vehicle is returned for the configuration q. Can be used for collision checking using the intersects() method.

See also

Polygon2

property q: ndarray

Get vehicle state/configuration (superclass)

Returns:: Vehicle state \((x, y, \theta)\)
Return type:: ndarray(3)

See also

x()

property random: Generator

Get private random number generator

Returns:: NumPy random number generator
Return type:: numpy.random.Generator

Has methods including:

integers(low, high, size, endpoint)

random(size)

uniform(low, high, size)

normal(mean, std, size)

multivariate_normal(mean, covar, size)

The generator is initialized with the seed provided at constructor time every time init() is called.

See also

init() numpy.random.default_rng()

run(T=10, x0=None, control=None, animate=True)

Simulate motion of vehicle (superclass)

Parameters:

T (float) – Simulation time in seconds, defaults to 10
x0 (ndarray | Sequence[float] | None) – Initial state, defaults to value given to Vehicle constructor
control (Union[ndarray, Sequence[float], Callable[..., ndarray | Sequence[float]], interp1d, VehicleDriverBase, None]) – vehicle control inputs, defaults to None
animate (bool) – Enable graphical animation of vehicle, defaults to True

Returns:

State trajectory, each row is \((x,y,\theta)\).

Return type:

ndarray

Runs the vehicle simulation for T seconds and optionally plots an animation. The method step() performs each time step.

The control inputs are provided by control which can be:

a constant tuple as the control inputs to the vehicle

a function called as f(vehicle, t, x) that returns a tuple

an interpolator called as f(t) that returns a tuple, see SciPy interp1d

a driver agent, subclass of VehicleDriverBase

This is evaluated by eval_control() which applies velocity, acceleration and steering limits.

The simulation can be stopped prematurely by the control function calling stopsim().

Note

the simulation is fixed-time step with the step given by the dt attribute set by the constructor.
integration uses rectangular integration.

run_animation(T=10, x0=None, control=None, format=None, file=None)

Animate motion of vehicle (superclass)

Parameters:

T (float) – Simulation time in seconds, defaults to 10
x0 (ndarray | Sequence[float] | None) – Initial state, defaults to value given to Vehicle constructor
control (Union[ndarray, Sequence[float], Callable[..., ndarray | Sequence[float]], interp1d, VehicleDriverBase, None]) – vehicle control inputs, defaults to None
format (str | None) – Output format
file (str | None) – File name

Raises:

ValueError – file is None for format "gif" or "mp4", or format is not recognised

Returns:

Matplotlib animation object

Return type:

FuncAnimation | str | None

Runs the vehicle simulation for T seconds and returns an animation in various formats:

``format``    ``file``   description
============  =========  ============================
``"html"``    str, None  return HTML5 video
``"jshtml"``  str, None  return JS+HTML video
``"gif"``     str        return animated GIF
``"mp4"``     str        return MP4/H264 video
``None``                 return a ``FuncAnimation`` object

The allowables types for file are given in the second column. A str value is the file name. If None is an option then return the video as a string.

For the last case, a reference to the animation object must be held if used for animation in a Jupyter cell:

anim = robot.run_animation(T=20)

The control inputs are provided by control which can be:

a constant tuple as the control inputs to the vehicle

a function called as f(vehicle, t, x) that returns a tuple

an interpolator called as f(t) that returns a tuple, see SciPy interp1d

a driver agent, subclass of VehicleDriverBase

This is evaluated by eval_control() which applies velocity, acceleration and steering limits.

The simulation can be stopped prematurely by the control function calling stopsim().

Note

the simulation is fixed-time step with the step given by the dt attribute set by the constructor.
integration uses rectangular integration.

See also

init() step() control() run()

property speed_max: float

Get maximum speed of vehicle (superclass)

Returns:: maximum speed
Return type:: float

Set by VehicleBase() subclass constructor.

See also

accel_max() steer_max u_limited()

step(u=None, animate=True, pause=True)

Step simulator by one time step (superclass)

Returns:: odometry \((\delta_d, \delta_\theta)\)
Return type:: ndarray

Obtain the vehicle control inputs
Integrate the vehicle state forward one timestep
Updates the stored state and state history
Update animation if enabled.
Returns the odometry

veh.step((vel, steer)) for a Bicycle vehicle model
veh.step((vel, turn_rate)) for a Unicycle vehicle model
veh.step() as above but control is taken from the control attribute which might be a function or driver agent.

Example:

>>> from roboticstoolbox import Bicycle
>>> bike = Bicycle()  # default bicycle model
>>> bike.step((1, 0.2))  # one step: v=1, γ=0.2
array([0.1   , 0.0203])
>>> bike.x
array([0.1   , 0.    , 0.0203])
>>> bike.step((1, 0.2))  # another step: v=1, γ=0.2
array([0.1   , 0.0203])
>>> bike.x
array([0.2   , 0.002 , 0.0405])