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, 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 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 forseed (
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
- 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 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.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.
- groundtruth_paths_gen(random_state=None)[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, seed: Optional[int] = None)[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.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
- 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 Nonegroundtruth – 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(random_state=None)[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, 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 modelclutter_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
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