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

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

Simulator base class

class stonesoup.simulator.base.DetectionSimulator

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

Detection Simulator base class

class stonesoup.simulator.base.GroundTruthSimulator

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

Ground truth simulator

class stonesoup.simulator.base.SensorSimulator

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)

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()

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

Yields

• datetime.datetime – Datetime of current time step

• set of GroundTruthPath – Ground truth paths existing in the time step

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)

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

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

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)

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.

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.

groundtruth_paths_gen()

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

Yields

• datetime.datetime – Datetime of current time step

• set of GroundTruthPath – Ground truth paths existing in the time step

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)

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.

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

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)

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) –

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

• measurement_model – Measurement model used in generating detections.

property clutter_spatial_density

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

detections_gen()

Returns a generator of detections for each time step.

Yields

• datetime.datetime – Datetime of current time step

• set of Detection – Detections generate in the time step

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

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) –

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])

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()

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

Yields

• datetime.datetime – Datetime of current time step

• set of GroundTruthPath – Ground truth paths existing in the time step

Platform Simulator

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

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()

Returns a generator of detections for each time step.

Yields

• datetime.datetime – Datetime of current time step

• set of Detection – Detections generate in the time step

Transition Simulator

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

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

• transition_models – A list of ConstantTurn and Point2PointConstantAcceleration transition models.

• transition_times – A list of timedelta dictating the transition time for each corresponding transition model in transition_models.

Notes

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

exception stonesoup.simulator.transition.OvershootError

Bases: Exception

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

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)

Model pdf/likelihood evaluation function

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

Parameters

• state1 (State) –

• state2 (State) –

Returns

The likelihood of state1, given state2

Return type

Probability or ndarray of Probability

rvs(num_samples=1, **kwargs)

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)

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])

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)

Model pdf/likelihood evaluation function

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

Parameters

• state1 (State) –

• state2 (State) –

Returns

The likelihood of state1, given state2

Return type

Probability or ndarray of Probability

rvs(num_samples=1, **kwargs)

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)

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