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