Simulators

Simulators for data input into Stone Soup.

Stone Soup can make use of simulators to generate ground truth tracks, sensor data and detections. These are similar to reader.Reader, but data is generated, rather than read from a file, etc. They should come with various configuration options to allow customisation of the simulation.

class stonesoup.simulator.base.Simulator[source]

Bases: stonesoup.base.Base, stonesoup.buffered_generator.BufferedGenerator

Simulator base class

class stonesoup.simulator.base.DetectionSimulator[source]

Bases: stonesoup.simulator.base.Simulator, stonesoup.reader.base.DetectionReader

Detection Simulator base class

class stonesoup.simulator.base.GroundTruthSimulator[source]

Bases: stonesoup.simulator.base.Simulator, stonesoup.reader.base.GroundTruthReader

Ground truth simulator

class stonesoup.simulator.base.SensorSimulator[source]

Bases: stonesoup.simulator.base.Simulator, stonesoup.reader.base.SensorDataReader

Sensor Simulator base class

Simple Simulators

class stonesoup.simulator.simple.SingleTargetGroundTruthSimulator(transition_model: TransitionModel, initial_state: State, timestep: datetime.timedelta = datetime.timedelta(seconds=1), number_steps: int = 100)[source]

Bases: stonesoup.simulator.base.GroundTruthSimulator

Target simulator that produces a single target

Parameters
  • transition_model (TransitionModel) – Transition Model used as propagator for track.

  • initial_state (State) – Initial state to use to generate ground truth

  • timestep (datetime.timedelta, optional) – Time step between each state. Default one second.

  • number_steps (int, optional) – Number of time steps to run for

transition_model: stonesoup.models.transition.base.TransitionModel

Transition Model used as propagator for track.

initial_state: stonesoup.types.state.State

Initial state to use to generate ground truth

timestep: datetime.timedelta

Time step between each state. Default one second.

number_steps: int

Number of time steps to run for

groundtruth_paths_gen()[source]

Returns a generator of ground truth paths for each time step.

Yields
class stonesoup.simulator.simple.SwitchOneTargetGroundTruthSimulator(initial_state: State, transition_models: Sequence[TransitionModel], model_probs: numpy.ndarray, timestep: datetime.timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, seed: Optional[int] = None)[source]

Bases: stonesoup.simulator.simple.SingleTargetGroundTruthSimulator

Target simulator that produces a single target. This target switches between multiple transition models based on a markov matrix (model_probs)

Parameters
  • initial_state (State) – Initial state to use to generate ground truth

  • transition_models (Sequence[TransitionModel]) – List of transition models to be used, ensure that they all have the same dimensions.

  • model_probs (numpy.ndarray) – A matrix of probabilities. The element in the ith row and the jth column is the probability of switching from the ith transition model in transition_models to the jth

  • timestep (datetime.timedelta, optional) – Time step between each state. Default one second.

  • number_steps (int, optional) – Number of time steps to run for

  • seed (Union[int, NoneType], optional) – Seed for random number generation. Default None

transition_models: Sequence[stonesoup.models.transition.base.TransitionModel]

List of transition models to be used, ensure that they all have the same dimensions.

model_probs: numpy.ndarray

A matrix of probabilities. The element in the ith row and the jth column is the probability of switching from the ith transition model in transition_models to the jth

seed: Optional[int]

Seed for random number generation. Default None

property transition_model

Transition Model used as propagator for track.

class stonesoup.simulator.simple.MultiTargetGroundTruthSimulator(transition_model: TransitionModel, initial_state: GaussianState, timestep: datetime.timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, birth_rate: float = 1.0, death_probability: Probability = 0.1, seed: Optional[int] = None)[source]

Bases: stonesoup.simulator.simple.SingleTargetGroundTruthSimulator

Target simulator that produces multiple targets.

Targets are created and destroyed randomly, as defined by the birth rate and death probability.

Parameters
  • transition_model (TransitionModel) – Transition Model used as propagator for track.

  • initial_state (GaussianState) – Initial state to use to generate states

  • timestep (datetime.timedelta, optional) – Time step between each state. Default one second.

  • number_steps (int, optional) – Number of time steps to run for

  • birth_rate (float, optional) – Rate at which tracks are born. Expected number of occurrences (λ) in Poisson distribution. Default 1.0.

  • death_probability (Probability, optional) – Probability of track dying in each time step. Default 0.1.

  • seed (Union[int, NoneType], optional) – Seed for random number generation. Default None

transition_model: stonesoup.models.transition.base.TransitionModel

Transition Model used as propagator for track.

initial_state: stonesoup.types.state.GaussianState

Initial state to use to generate states

birth_rate: float

Rate at which tracks are born. Expected number of occurrences (λ) in Poisson distribution. Default 1.0.

death_probability: stonesoup.types.numeric.Probability

Probability of track dying in each time step. Default 0.1.

seed: Optional[int]

Seed for random number generation. Default None

groundtruth_paths_gen(random_state=None)[source]

Returns a generator of ground truth paths for each time step.

Yields
class stonesoup.simulator.simple.SwitchMultiTargetGroundTruthSimulator(initial_state: GaussianState, transition_models: Sequence[TransitionModel], model_probs: numpy.ndarray, timestep: datetime.timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, birth_rate: float = 1.0, death_probability: Probability = 0.1, seed: Optional[int] = None)[source]

Bases: stonesoup.simulator.simple.MultiTargetGroundTruthSimulator

Functions identically to MultiTargetGroundTruthSimulator, but has the transition model switching ability from SwitchOneTargetGroundTruthSimulator

Parameters
  • initial_state (GaussianState) – Initial state to use to generate states

  • transition_models (Sequence[TransitionModel]) – List of transition models to be used, ensure that they all have the same dimensions.

  • model_probs (numpy.ndarray) – A matrix of probabilities. The element in the ith row and the jth column is the probability of switching from the ith transition model in transition_models to the jth

  • timestep (datetime.timedelta, optional) – Time step between each state. Default one second.

  • number_steps (int, optional) – Number of time steps to run for

  • birth_rate (float, optional) – Rate at which tracks are born. Expected number of occurrences (λ) in Poisson distribution. Default 1.0.

  • death_probability (Probability, optional) – Probability of track dying in each time step. Default 0.1.

  • seed (Union[int, NoneType], optional) – Seed for random number generation. Default None

transition_models: Sequence[stonesoup.models.transition.base.TransitionModel]

List of transition models to be used, ensure that they all have the same dimensions.

model_probs: numpy.ndarray

A matrix of probabilities. The element in the ith row and the jth column is the probability of switching from the ith transition model in transition_models to the jth

seed: Optional[int]

Seed for random number generation. Default None

property transition_model

Transition Model used as propagator for track.

class stonesoup.simulator.simple.SimpleDetectionSimulator(groundtruth: GroundTruthReader, measurement_model: MeasurementModel, meas_range: numpy.ndarray, detection_probability: Probability = 0.9, clutter_rate: float = 2.0, seed: Optional[int] = None)[source]

Bases: stonesoup.simulator.base.DetectionSimulator

A simple detection simulator.

Parameters
  • groundtruth (GroundTruthReader) –

  • measurement_model (MeasurementModel) –

  • meas_range (numpy.ndarray) –

  • detection_probability (Probability, optional) –

  • clutter_rate (float, optional) –

  • seed (Union[int, NoneType], optional) – Seed for random number generation. Default None

  • groundtruth – Source of ground truth tracks used to generate detections for.

  • measurement_model – Measurement model used in generating detections.

seed: Optional[int]

Seed for random number generation. Default None

property clutter_spatial_density

returns the clutter spatial density of the measurement space - num clutter detections per unit volume per timestep

detections_gen(random_state=None)[source]

Returns a generator of detections for each time step.

Yields
class stonesoup.simulator.simple.SwitchDetectionSimulator(groundtruth: GroundTruthReader, measurement_model: MeasurementModel, meas_range: numpy.ndarray, detection_probabilities: Sequence[Probability], clutter_rate: float = 2.0, seed: Optional[int] = None)[source]

Bases: stonesoup.simulator.simple.SimpleDetectionSimulator

Functions identically as the SimpleDetectionSimulator, but for ground truth paths formed using multiple transition models it allows the user to assign a detection probability to each transition models. For example, if you wanted a higher detection probability when the simulated object makes a turn

Parameters
  • groundtruth (GroundTruthReader) –

  • measurement_model (MeasurementModel) –

  • meas_range (numpy.ndarray) –

  • detection_probabilities (Sequence[Probability]) – List of probabilities that correspond to the detection probability of the simulated object while undergoing each transition model

  • clutter_rate (float, optional) –

  • seed (Union[int, NoneType], optional) – Seed for random number generation. Default None

detection_probabilities: Sequence[stonesoup.types.numeric.Probability]

List of probabilities that correspond to the detection probability of the simulated object while undergoing each transition model

class stonesoup.simulator.simple.DummyGroundTruthSimulator(times: Sequence[datetime.datetime])[source]

Bases: stonesoup.simulator.base.GroundTruthSimulator

A Dummy Ground Truth Simulator which allows simulations to be built where platform, rather than ground truth objects, motions are simulated.

It returns an empty set at each time step.

Parameters

times (Sequence[datetime.datetime]) – list of times to return

times: Sequence[datetime.datetime]

list of times to return

groundtruth_paths_gen()[source]

Returns a generator of ground truth paths for each time step.

Yields

Platform Simulator

class stonesoup.simulator.platform.PlatformDetectionSimulator(groundtruth: GroundTruthReader, platforms: Sequence[Platform])[source]

Bases: stonesoup.simulator.base.DetectionSimulator

A simple platform detection simulator.

Processes ground truth data and generates Detection data according to a list of platforms by calling each sensor in these platforms.

Parameters
  • groundtruth (GroundTruthReader) – Source of ground truth tracks used to generate detections for.

  • platforms (Sequence[Platform]) – List of platforms in Platform to generate sensor detections from.

groundtruth: stonesoup.reader.base.GroundTruthReader

Source of ground truth tracks used to generate detections for.

platforms: Sequence[stonesoup.platform.base.Platform]

List of platforms in Platform to generate sensor detections from.

detections_gen()[source]

Returns a generator of detections for each time step.

Yields

Transition Simulator

stonesoup.simulator.transition.create_smooth_transition_models(initial_state, x_coords, y_coords, times, turn_rate)[source]

Generate a list of constant-turn and constant acceleration transition models alongside a list of transition times to provide smooth transitions between 2D cartesian coordinates and time pairs. An assumption is that the initial_state’s x, y coordinates are the first elements of x_ccords and y_coords respectively. Ie. The platform starts at the first coordinates.

Parameters
  • initial_state (State) – The initial state of the platform.

  • x_coords – A list of int/float x-coordinates (cartesian) in the order that the target must follow.

  • y_coords – A list of int/float y-coordinates (cartesian) in the order that the target must follow.

  • times – A list of datetime dictating the times at which the target must be at each corresponding coordinate.

  • turn_rate (Float) – Angular turn rate (radians/second) measured anti-clockwise from positive x-axis.

Returns

Notes

x_coords, y_coords and times must be of same length. This method assumes a cartesian state space with velocities eg. \((x, \dot{x}, y, \dot{y})\). It returns transition models for 2 cartesian coordinates and their corresponding velocities.

exception stonesoup.simulator.transition.OvershootError[source]

Bases: Exception

class stonesoup.simulator.transition.Point2PointConstantAcceleration(state: State, destination: Tuple[float, float], duration: datetime.timedelta)[source]

Bases: stonesoup.models.transition.base.TransitionModel

Constant acceleration transition model for 2D cartesian coordinates

The platform is assumed to move with constant acceleration between two given cartesian coordinates. Motion is determined by the kinematic formulae:

\[\begin{split}v &= u + at \\ s &= ut + \frac{1}{2} at^2\end{split}\]

Where \(u, v, a, t, s\) are initial speed, final speed, acceleration, transition time and distance travelled respectively.

Parameters
  • state (State) – The initial state, assumed to have x and y cartesian position andvelocities

  • destination (Tuple[float, float]) – Destination coordinates in 2D cartesiancoordinates (x, y)

  • duration (datetime.timedelta) – Duration of transition in seconds

state: stonesoup.types.state.State

The initial state, assumed to have x and y cartesian position andvelocities

destination: Tuple[float, float]

Destination coordinates in 2D cartesiancoordinates (x, y)

duration: datetime.timedelta

Duration of transition in seconds

property ndim_state

Number of state dimensions

pdf(state1, state2, **kwargs)[source]

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters
Returns

The likelihood of state1, given state2

Return type

Probability or ndarray of Probability

rvs(num_samples=1, **kwargs)[source]

Model noise/sample generation function

Generates noise samples from the model.

Parameters

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns

noise – A set of Np samples, generated from the model’s noise distribution.

Return type

2-D array of shape (ndim, num_samples)

function(state, time_interval, **kwargs)[source]

Model function \(f_k(x(k),w(k))\)

Parameters
  • state (State) – An input state

  • noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns

The StateVector(s) with the model function evaluated.

Return type

StateVector or StateVectors

class stonesoup.simulator.transition.Point2PointStop(state: State, destination: Tuple[float, float])[source]

Bases: stonesoup.models.transition.base.TransitionModel

Constant acceleration transition model for 2D cartesian coordinates

The platform is assumed to move with constant acceleration between two given cartesian coordinates. Motion is determined by the kinematic formulae:

\[\begin{split}v &= u + at \\ v^2 &= u^2 + 2as\end{split}\]

Where \(u, v, a, t, s\) are initial speed, final speed, acceleration, transition time and distance travelled respectively. The platform is decelerated to 0 velocity at the destination point and waits for the remaining duration.

Parameters
  • state (State) – The initial state, assumed to have x and y cartesian position andvelocities

  • destination (Tuple[float, float]) – Destination coordinates in 2D cartesiancoordinates (x, y)

state: stonesoup.types.state.State

The initial state, assumed to have x and y cartesian position andvelocities

destination: Tuple[float, float]

Destination coordinates in 2D cartesiancoordinates (x, y)

property ndim_state

Number of state dimensions

pdf(state1, state2, **kwargs)[source]

Model pdf/likelihood evaluation function

Evaluates the pdf/likelihood of state1, given the state state2 which is passed to function().

Parameters
Returns

The likelihood of state1, given state2

Return type

Probability or ndarray of Probability

rvs(num_samples=1, **kwargs)[source]

Model noise/sample generation function

Generates noise samples from the model.

Parameters

num_samples (scalar, optional) – The number of samples to be generated (the default is 1)

Returns

noise – A set of Np samples, generated from the model’s noise distribution.

Return type

2-D array of shape (ndim, num_samples)

function(state, time_interval, **kwargs)[source]

Model function \(f_k(x(k),w(k))\)

Parameters
  • state (State) – An input state

  • noise (numpy.ndarray or bool) – An externally generated random process noise sample (the default is False, in which case no noise will be added if ‘True’, the output of rvs() is used)

Returns

The StateVector(s) with the model function evaluated.

Return type

StateVector or StateVectors

class stonesoup.simulator.transition.ConstantJerkSimulator(position_mapping: Sequence[int], init_state: State, final_state: State, velocity_mapping: Sequence[int] = None)[source]

Bases: stonesoup.models.transition.base.TransitionModel

Constant, noiseless, jerk transition model for cartesian space.

The state space has no acceleration or jerk elements. I.E. the only kinematic components are position and velocity.

Solution given by \(\vec{\ddddot{x}} = \vec{0}\)

The user will provide an initial and final state, each of which containing initial cartesian position and velocities. For example, \((x, \dot{x}, y, \dot{y})\).

Components of the state vector that are not position or velocity are kept constant. Initial and final accelerations are uniquely defined by this input.

Notes

Acceleration instantaneously changes at each target state

Parameters
  • position_mapping (Sequence[int]) – Mapping between platform position and state vector.

  • init_state (State) – Initial state to move from. Must be ndim_state dimensions.

  • final_state (State) – Final state to move to. Must be ndim_state dimensions.

  • velocity_mapping (Sequence[int], optional) – Mapping between platform velocity and state vector. Defaults to [m+1 for m in position_mapping]

position_mapping: Sequence[int]

Mapping between platform position and state vector.

init_state: stonesoup.types.state.State

Initial state to move from. Must be ndim_state dimensions.

final_state: stonesoup.types.state.State

Final state to move to. Must be ndim_state dimensions.

velocity_mapping: Sequence[int]

Mapping between platform velocity and state vector. Defaults to [m+1 for m in position_mapping]

property ndim_state

Number of state space dimensions.

covar(**kwargs)[source]

Must be added due to inheritance.

pdf(state1, state2, **kwargs)[source]

Must be added due to inheritance.

rvs(num_samples=1, **kwargs)[source]

Must be added due to inheritance.

function(state, time_interval, **kwargs)[source]

Apply a constant jerk transition to state, for time_interval duration, keeping elements of state vector that are not position or velocity constant.

static calculate_pos(init_x, init_v, init_a, jerk, T)[source]

Calculate position, along a particular axis.

Parameters
  • init_x (float) – Initial position along axis

  • init_v (float) – Initial velocity along axis

  • init_a (float) – Initial acceleration along axis

  • jerk (float) – Constant jerk value along axis

  • T (float) – Number for seconds to carry-out jerk transition

Returns

New position along axis, given by: \(X' = \frac{J_0 T^3}{6} + \frac{A_0 T^2}{2} + V_0 T + X_0\)

Return type

float

classmethod create_models(states: Sequence[State], position_mapping, velocity_mapping=None)[source]

Generate a list of ConstantJerkSimulator and transition durations, given a list of states.