Movables

class stonesoup.movable.movable.Movable(states: MutableSequence[State], position_mapping: Sequence[int], velocity_mapping: Sequence[int] | None = None)[source]

Bases: StateMutableSequence, Actionable, ABC

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

states: MutableSequence[State]

A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

position_mapping: Sequence[int]

Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

velocity_mapping: Sequence[int] | None

Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

validate_timestamp()[source]

Method to validate the timestamp of the actionable.

Returns:

True if timestamp is valid, False otherwise.

Return type:

bool

property position: StateVector

Return the position of the platform.

Extracted from the state vector of the platform using the platform’s position_mapping. This property is settable for fixed platforms, but not for movable ones, where the position must be set by moving the model with a transition model.

property ndim: int

Convenience property to return the number of dimensions in which the platform operates.

Given by the length of the position_mapping

abstract property orientation: StateVector

Return the orientation of the platform.

Implementation is case dependent and left to the Fixed/Moving subclasses

abstract property velocity: StateVector

Return the velocity of the platform.

Implementation is case dependent and left to the Fixed/Moving subclasses

abstract property is_moving: bool

Return the True if the platform is moving, False otherwise.

abstractmethod move(timestamp: datetime, noise: bool = True, **kwargs) → None[source]

Update the platform position using the transition_model.

Parameters:

timestamp (datetime.datetime) – A timestamp signifying when the end of the maneuver

Notes

This methods updates the value of position.

Any provided kwargs are forwarded to the transition_model.

If transition_model or timestamp is None, the method has no effect, but will return successfully.

range_and_angles_to_other(other: Movable) → tuple[float, float, float][source]

Calculate the range, azimuth and elevation of a given Movable relative to current Movable.

Calculates the relative vector between the two Movables, and then converts this range, azimuth, elevation using cart2sphere()

Parameters:

other (Movable) – Another Movable. Only its position is relevant to this method.

Returns:

range, azimuth, elevation – The range azimuth and elevation of the target from the radar

Return type:

float, float, float

class stonesoup.movable.movable.FixedMovable(states: MutableSequence[State], position_mapping: Sequence[int], velocity_mapping: Sequence[int] | None = None, orientation: StateVector = None)[source]

Bases: Movable

Fixed platform base class

A platform represents a random object defined as a StateMutableSequence with fixed (but settable) position and orientation.

Note

Position and orientation are read/write properties in this class.

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

  • orientation (StateVector, optional) – A fixed orientation of the static platform. Defaults to the zero vector

orientation: StateVector

A fixed orientation of the static platform. Defaults to the zero vector

property velocity: StateVector

Return the velocity of the platform.

For a fixed platform this is always a zero vector of length ndim.

property is_moving: bool

Return the True if the platform is moving, False otherwise.

move(timestamp: datetime, **kwargs) → None[source]

For a fixed platform this method has no effect other than to update the timestamp.

class stonesoup.movable.movable.MovingMovable(states: MutableSequence[State], position_mapping: Sequence[int], transition_model: TransitionModel, velocity_mapping: Sequence[int] | None = None)[source]

Bases: Movable

Moving platform base class

A platform represents a random object defined as a State that moves according to a given TransitionModel.

Note

Position and orientation are a read only properties in this class.

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • transition_model (TransitionModel) – Transition model

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

transition_model: TransitionModel

Transition model

property velocity: StateVector

Return the velocity of the platform.

Extracted from the state vector of the platform using the platform’s velocity_mapping. If the state vector is too short and does not contain the elements specified in the velocity_mapping this raises an AttributeError

property orientation: StateVector

Return the orientation of the platform.

This is defined as a 3x1 StateVector of angles (rad), specifying the sensor orientation in terms of the counter-clockwise rotation around each Cartesian axis in the order \(x,y,z\). The x and z rotation angles are positive if the rotation is in the counter-clockwise direction when viewed by an observer looking along the respective rotation axis, towards the origin. The y rotation angle is the opposite (matching ‘elevation’).

The orientation of this platform is defined as along the direction of its velocity, with roll always set to zero (as this is the angle the platform is rotated about the velocity axis, which is not defined in this approximation).

Notes

Where the velocity of the platform is small, the orientation is calculated based on the direction it travelled from its previous position. Where the platform has only moved a small distance, and for a non-moving platform (self.is_moving == False) the orientation from the previous time step is used.

property is_moving: bool

Return the True if the platform is moving, False otherwise.

Equivalent (for this class) to all(v == 0 for v in self.velocity)

move(timestamp=None, noise=True, **kwargs) → None[source]

Propagate the platform position using the transition_model.

Parameters:

timestamp (datetime.datetime, optional) – A timestamp signifying when the end of the maneuver (the default is None)

Notes

This methods updates the value of position.

Any provided kwargs are forwarded to the transition_model.

If timestamp` is None, the method has no effect, but will return successfully.

class stonesoup.movable.movable.MultiTransitionMovable(states: MutableSequence[State], position_mapping: Sequence[int], transition_models: Sequence[TransitionModel], transition_times: Sequence[timedelta], velocity_mapping: Sequence[int] | None = None)[source]

Bases: MovingMovable

Moving platform with multiple transition models

A list of transition models are given with corresponding transition times, dictating the movement behaviour of the platform for given durations.

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • transition_models (collections.abc.Sequence) – list of transition models

  • transition_times (collections.abc.Sequence) – Durations for each listed transition model

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

transition_models: Sequence[TransitionModel]

list of transition models

transition_times: Sequence[timedelta]

Durations for each listed transition model

property transition_model

Transition model

move(timestamp=None, noise=True, **kwargs) → None[source]

Propagate the platform position using the transition_model.

Parameters:

timestamp (datetime.datetime, optional) – A timestamp signifying the end of the maneuver (the default is None)

Notes

This methods updates the value of position.

Any provided kwargs are forwarded to the transition_model.

If transition_model or timestamp is None, the method has no effect, but will return successfully.

This method updates transition_model, transition_index and current_interval: If the timestamp provided gives a time delta greater than current_interval the transition_model is called for the rest of its corresponding duration, and the move method is called again on the next transition model (by incrementing transition_index) in transition_models with the residue time delta. If the time delta is less than current_interval the transition_model is called for that duration and current_interval is reduced accordingly.

Grid-based Movables

class stonesoup.movable.grid.NStepDirectionalGridMovable(states: MutableSequence[State], position_mapping: Sequence[int], velocity_mapping: Sequence[int] | None = None, orientation: StateVector = None, action_space: ndarray = None, action_mapping: Sequence[int] = (0, 1), resolution: float = 1, n_steps: int = 1, step_size: int = 1)[source]

Bases: _GridActionableMovable

This is a movable that enables movement in a grid like fashion according to a number of steps and step sizes. Actions are applied symmetrically on the action space allowing for movement in both positive and negative directions of each axis. This movable implements the NStepDirectionalGridActionGenerator

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

  • orientation (StateVector, optional) – A fixed orientation of the static platform. Defaults to the zero vector

  • action_space (numpy.ndarray, optional) – The bounds of the action space that should not be exceeded. Of shape (ndim, 2) where ndim is the length of the action_mapping. For example, np.array([[xmin, xmax], [ymin, ymax]]).

  • action_mapping (collections.abc.Sequence, optional) – The state dimensions that actions are applied to.

  • resolution (float, optional) – The size of each grid cell. Cells are assumed square.

  • n_steps (int, optional) – The number of steps that can be moved in either direction along specified dimensions

  • step_size (int, optional) – The number of grid cells per step

generator

alias of NStepDirectionalGridActionGenerator

n_steps: int

The number of steps that can be moved in either direction along specified dimensions

step_size: int

The number of grid cells per step

Sample-based Movables

class stonesoup.movable.sample.CircleSampleActionableMovable(states: MutableSequence[State], position_mapping: Sequence[int], velocity_mapping: Sequence[int] | None = None, orientation: StateVector = None, action_space: ndarray = None, action_mapping: Sequence[int] = (0, 1), n_samples: int = 10, maximum_travel: float = 1.0)[source]

Bases: _SampleActionableMovable

This movable implements sampling based movement according to a circle around the current position, defined by the maximum travel defined by the user. Samples are uniformly generated within the circle. To be used with CircleSamplePositionActionGenerator

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

  • orientation (StateVector, optional) – A fixed orientation of the static platform. Defaults to the zero vector

  • action_space (numpy.ndarray, optional) – The bounds of the action space that should not be exceeded. Of shape (ndim, 2) where ndim is the length of the action_mapping. For example, np.array([[xmin, xmax], [ymin, ymax]]).

  • action_mapping (collections.abc.Sequence, optional) – The state dimensions that actions are applied to.

  • n_samples (int, optional) – Number of samples to generate. This does not include the action to remain at the current position, meaning n_samples +1 actions will be generated.

  • maximum_travel (float, optional) – Maximum possible travel distance. Specifies the radius of sampling area.

generator

alias of CircleSamplePositionActionGenerator

maximum_travel: float

Maximum possible travel distance. Specifies the radius of sampling area.

Maximum Speed Movables

class stonesoup.movable.max_speed.MaxSpeedActionableMovable(states: MutableSequence[State], position_mapping: Sequence[int], velocity_mapping: Sequence[int] | None = None, orientation: StateVector = None, action_space: ndarray = None, action_mapping: Sequence[int] = (0, 1), resolution: float = 1, angle_resolution: float = 1.5707963267948966, max_speed: float = 1)[source]

Bases: FixedMovable

Class for movables that can move in any direction. To be used with MoveToActionGenerator.

Parameters:

  • states (collections.abc.MutableSequence) – A list of States which enables the platform’s history to be accessed in simulators and for plotting. Initiated as a state, for a static platform, this would usually contain its position coordinates in the form [x, y, z]. For a moving platform it would contain position and velocity interleaved: [x, vx, y, vy, z, vz]

  • position_mapping (collections.abc.Sequence) – Mapping between platform position and state vector. For a position-only 3d platform this might be [0, 1, 2]. For a position and velocity platform: [0, 2, 4]

  • velocity_mapping (Optional[collections.abc.Sequence[int]], optional) – Mapping between platform velocity and state dims. If not set, it will default to [m+1 for m in position_mapping]

  • orientation (StateVector, optional) – A fixed orientation of the static platform. Defaults to the zero vector

  • action_space (numpy.ndarray, optional) – The bounds of the action space that should not be exceeded. Of shape (ndim, 2) where ndim is the length of the action_mapping. For example, np.array([[xmin, xmax], [ymin, ymax]]).

  • action_mapping (collections.abc.Sequence, optional) – The state dimensions that actions are applied to.

  • resolution (float, optional) – The interval in distance travelled for each action.

  • angle_resolution (float, optional) – The interval in angle for each action.

  • max_speed (float, optional) – The maximum speed that the movable can travel at.

generator

alias of MaxSpeedPositionActionGenerator

action_space: ndarray

The bounds of the action space that should not be exceeded. Of shape (ndim, 2) where ndim is the length of the action_mapping. For example, np.array([[xmin, xmax], [ymin, ymax]]).

action_mapping: Sequence[int]

The state dimensions that actions are applied to.

resolution: float

The interval in distance travelled for each action.

angle_resolution: float

The interval in angle for each action.

max_speed: float

The maximum speed that the movable can travel at.

actions(timestamp, start_timestamp=None)[source]

Method to return a set of action generators available up to a provided timestamp.

A generator is returned for each actionable property that the sensor has.

Parameters:
Returns:

Set of action generators, that describe the bounds of each action space.

Return type:

set of MoveToActionGenerator

move(timestamp, *args, **kwargs)[source]

For a fixed platform this method has no effect other than to update the timestamp.

add_actions(actions)[source]

Add actions to the sensor

Parameters:

actions (sequence of Action) – Sequence of actions that will be executed in order

Returns:

Return True if actions accepted. False if rejected. Returns neither if timestamp is invalid.

Return type:

bool

Raises:

NotImplementedError – If sensor cannot be tasked.

Notes

Base class returns True

act(timestamp, *args, **kwargs)[source]

Carry out actions up to a timestamp.

Parameters:

timestamp (datetime.datetime) – Carry out actions up to this timestamp.