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, initial_state, timestep=datetime.timedelta(seconds=1), number_steps=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, transition_models, model_probs, timestep=datetime.timedelta(seconds=1), number_steps=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, initial_state, timestep=datetime.timedelta(seconds=1), number_steps=100, birth_rate=1.0, death_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, transition_models, model_probs, timestep=datetime.timedelta(seconds=1), number_steps=100, birth_rate=1.0, death_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, measurement_model, meas_range, detection_probability=0.9, clutter_rate=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, measurement_model, meas_range, detection_probabilities, clutter_rate=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)[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, platforms)[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 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
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, destination, duration)[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
-
class
stonesoup.simulator.transition.
Point2PointStop
(state, destination)[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