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:
Base
,BufferedGenerator
Simulator base class
- class stonesoup.simulator.base.DetectionSimulator[source]
Bases:
Simulator
,DetectionReader
Detection Simulator base class
- class stonesoup.simulator.base.GroundTruthSimulator[source]
Bases:
Simulator
,GroundTruthReader
Ground truth simulator
- class stonesoup.simulator.base.SensorSimulator[source]
Bases:
Simulator
,SensorDataReader
Sensor Simulator base class
Simple Simulators
- class stonesoup.simulator.simple.SingleTargetGroundTruthSimulator(transition_model: TransitionModel, initial_state: State, timestep: timedelta = datetime.timedelta(seconds=1), number_steps: int = 100)[source]
Bases:
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: TransitionModel
Transition Model used as propagator for track.
- 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: ndarray, timestep: timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, seed: int | None = None)[source]
Bases:
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 (
Optional[int]
, optional) – Seed for random number generation. Default None
- transition_models: Sequence[TransitionModel]
List of transition models to be used, ensure that they all have the same dimensions.
- model_probs: 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: timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, birth_rate: float = 1.0, death_probability: Probability = 0.1, seed: int | None = None, preexisting_states: Collection[StateVector] = [], initial_number_targets: int = 0)[source]
Bases:
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 (
Optional[int]
, optional) – Seed for random number generation. Default Nonepreexisting_states (
Collection[StateVector]
, optional) – State vectors at time 0 for groundtruths which should exist at the start of simulation.initial_number_targets (
int
, optional) – Initial number of targets to be simulated. These simulated targets will be made in addition to those defined bypreexisting_states
.
- transition_model: TransitionModel
Transition Model used as propagator for track.
- initial_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: Probability
Probability of track dying in each time step. Default 0.1.
- preexisting_states: Collection[StateVector]
State vectors at time 0 for groundtruths which should exist at the start of simulation.
- initial_number_targets: int
Initial number of targets to be simulated. These simulated targets will be made in addition to those defined by
preexisting_states
.
- 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: ndarray, timestep: timedelta = datetime.timedelta(seconds=1), number_steps: int = 100, birth_rate: float = 1.0, death_probability: Probability = 0.1, seed: int | None = None, preexisting_states: Collection[StateVector] = [], initial_number_targets: int = 0)[source]
Bases:
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 (
Optional[int]
, optional) – Seed for random number generation. Default Nonepreexisting_states (
Collection[StateVector]
, optional) – State vectors at time 0 for groundtruths which should exist at the start of simulation.initial_number_targets (
int
, optional) – Initial number of targets to be simulated. These simulated targets will be made in addition to those defined bypreexisting_states
.
- transition_models: Sequence[TransitionModel]
List of transition models to be used, ensure that they all have the same dimensions.
- model_probs: 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: ndarray, detection_probability: Probability = 0.9, clutter_rate: float = 2.0, seed: int | None = None)[source]
Bases:
DetectionSimulator
A simple detection simulator.
- Parameters:
groundtruth (GroundTruthReader) –
measurement_model (MeasurementModel) –
meas_range (
numpy.ndarray
) –detection_probability (
Probability
, optional) –clutter_rate (
float
, optional) –seed (
Optional[int]
, 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: ndarray, detection_probabilities: Sequence[Probability], clutter_rate: float = 2.0, seed: int | None = None)[source]
Bases:
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 (
Optional[int]
, optional) – Seed for random number generation. Default None
- detection_probabilities: Sequence[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])[source]
Bases:
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
- 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:
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: GroundTruthReader
Source of ground truth tracks used to generate detections for.
- 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
KnownTurnRate
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, \dot{x}, y, \dot{y})\). It returns transition models for 2 cartesian coordinates and their corresponding velocities.
- class stonesoup.simulator.transition.Point2PointConstantAcceleration(state: State, destination: Tuple[float, float], duration: timedelta)[source]
Bases:
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
- 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:
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)
- 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.ConstantJerkSimulator(position_mapping: Sequence[int], init_state: State, final_state: State, velocity_mapping: Sequence[int] = None)[source]
Bases:
TransitionModel
Constant, noiseless, jerk transition model for cartesian space.
The state space has no acceleration or jerk elements. I.E. the only kinematic components are position and velocity.
Solution given by \(\vec{\ddddot{x}} = \vec{0}\)
The user will provide an initial and final state, each of which containing initial cartesian position and velocities. For example, \((x, \dot{x}, y, \dot{y})\).
Components of the state vector that are not position or velocity are kept constant. Initial and final accelerations are uniquely defined by this input.
Notes
Acceleration instantaneously changes at each target state
- Parameters:
position_mapping (
Sequence[int]
) – Mapping between platform position and state vector.init_state (
State
) – Initial state to move from. Must be ndim_state dimensions.final_state (
State
) – Final state to move to. Must be ndim_state dimensions.velocity_mapping (
Sequence[int]
, optional) – Mapping between platform velocity and state vector. Defaults to [m+1 for m in position_mapping]
- velocity_mapping: Sequence[int]
Mapping between platform velocity and state vector. Defaults to [m+1 for m in position_mapping]
- property ndim_state
Number of state space dimensions.
- function(state, time_interval, **kwargs)[source]
Apply a constant jerk transition to state, for time_interval duration, keeping elements of state vector that are not position or velocity constant.
- static calculate_pos(init_x, init_v, init_a, jerk, T)[source]
Calculate position, along a particular axis.
- Parameters:
- Returns:
New position along axis, given by: \(X' = \frac{J_0 T^3}{6} + \frac{A_0 T^2}{2} + V_0 T + X_0\)
- Return type:
- classmethod create_models(states: Sequence[State], position_mapping, velocity_mapping=None)[source]
Generate a list of
ConstantJerkSimulator
and transition durations, given a list of states.