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 truthtimestep (
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.

groundtruth_paths_gen
()[source]¶ Returns a generator of ground truth paths for each time step.
 Yields
datetime.datetime
– Datetime of current time stepset 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)[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 truthtransition_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 intransition_models
to the jthtimestep (
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)[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 statestimestep (
datetime.timedelta
, optional) – Time step between each state. Default one second.number_steps (
int
, optional) – Number of time steps to run forbirth_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
()[source]¶ Returns a generator of ground truth paths for each time step.
 Yields
datetime.datetime
– Datetime of current time stepset 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)[source]¶ Bases:
stonesoup.simulator.simple.MultiTargetGroundTruthSimulator
Functions identically to
MultiTargetGroundTruthSimulator
, but has the transition model switching ability fromSwitchOneTargetGroundTruthSimulator
 Parameters
initial_state (
GaussianState
) – Initial state to use to generate statestransition_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 intransition_models
to the jthtimestep (
datetime.timedelta
, optional) – Time step between each state. Default one second.number_steps (
int
, optional) – Number of time steps to run forbirth_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)[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) –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
()[source]¶ Returns a generator of detections for each time step.
 Yields
datetime.datetime
– Datetime of current time stepset 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)[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 modelclutter_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])[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
datetime.datetime
– Datetime of current time stepset of
GroundTruthPath
– Ground truth paths existing in the time step
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 inPlatform
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
datetime.datetime
– Datetime of current time stepset 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)[source]¶ Generate a list of constantturn 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 xcoordinates (cartesian) in the order that the target must follow.
y_coords – A list of int/float ycoordinates (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 anticlockwise from positive xaxis.
 Returns
transition_models – A list of
ConstantTurn
andPoint2PointConstantAcceleration
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.

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

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 statestate2
which is passed tofunction()
. Parameters
 Returns
The likelihood of
state1
, givenstate2
 Return type
Probability
orndarray
ofProbability

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
2D 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 ofrvs()
is used)
 Returns
The StateVector(s) with the model function evaluated.
 Return type
StateVector
orStateVectors

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

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 statestate2
which is passed tofunction()
. Parameters
 Returns
The likelihood of
state1
, givenstate2
 Return type
Probability
orndarray
ofProbability

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
2D 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 ofrvs()
is used)
 Returns
The StateVector(s) with the model function evaluated.
 Return type
StateVector
orStateVectors