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 truth
timestep (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.

initial_state: State: Initial state to use to generate ground truth

timestep: timedelta: Time step between each state. Default one second.

number_steps: int: Number of time steps to run for

groundtruth_paths_gen()[source]

Returns a generator of ground truth paths for each time step.

Yields:

datetime.datetime – Datetime of current time step
set 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 truth
transition_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 in transition_models to the jth
timestep (datetime.timedelta, optional) – Time step between each state. Default one second.
number_steps (int, optional) – Number of time steps to run for
seed (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

seed: int | None: Seed for random number generation. Default None

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 states
timestep (datetime.timedelta, optional) – Time step between each state. Default one second.
number_steps (int, optional) – Number of time steps to run for
birth_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 None
preexisting_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 by preexisting_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.

seed: int | None: Seed for random number generation. Default None

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 step
set 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 from SwitchOneTargetGroundTruthSimulator

Parameters:

initial_state (GaussianState) – Initial state to use to generate states
transition_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 in transition_models to the jth
timestep (datetime.timedelta, optional) – Time step between each state. Default one second.
number_steps (int, optional) – Number of time steps to run for
birth_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 None
preexisting_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 by preexisting_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

seed: int | None: Seed for random number generation. Default None

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 None
groundtruth – Source of ground truth tracks used to generate detections for.
measurement_model – Measurement model used in generating detections.

seed: int | None: Seed for random number generation. Default None

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 step
set 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 model
clutter_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

times: Sequence[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 step
set 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 in Platform to generate sensor detections from.

groundtruth: GroundTruthReader: Source of ground truth tracks used to generate detections for.

platforms: Sequence[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 step
set 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 and Point2PointConstantAcceleration 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.

exception stonesoup.simulator.transition.OvershootError[source]: Bases: Exception

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 andvelocities
destination (Tuple[float, float]) – Destination coordinates in 2D cartesiancoordinates (x, y)
duration (datetime.timedelta) – Duration of transition in seconds

state: State: The initial state, assumed to have x and y cartesian position andvelocities

destination: Tuple[float, float]: Destination coordinates in 2D cartesiancoordinates (x, y)

duration: 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 state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

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 of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

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 andvelocities
destination (Tuple[float, float]) – Destination coordinates in 2D cartesiancoordinates (x, y)

state: State: The initial state, assumed to have x and y cartesian position andvelocities

destination: 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 state state2 which is passed to function().

Parameters:

state1 (State)
state2 (State)

Returns:

The likelihood of state1, given state2

Return type:

Probability or ndarray of Probability

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 of rvs() is used)

Returns:

The StateVector(s) with the model function evaluated.

Return type:

StateVector or StateVectors

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]

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]: Mapping between platform velocity and state vector. Defaults to [m+1 for m in position_mapping]

property ndim_state: Number of state space dimensions.

covar(**kwargs)[source]: Must be added due to inheritance.

pdf(state1, state2, **kwargs)[source]: Must be added due to inheritance.

rvs(num_samples=1, **kwargs)[source]: Must be added due to inheritance.

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:

init_x (float) – Initial position along axis
init_v (float) – Initial velocity along axis
init_a (float) – Initial acceleration along axis
jerk (float) – Constant jerk value along axis
T (float) – Number for seconds to carry-out jerk transition

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:

float

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.