# 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]

Detection Simulator base class

class stonesoup.simulator.base.GroundTruthSimulator[source]

Ground truth simulator

class stonesoup.simulator.base.SensorSimulator[source]

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]

Target simulator that produces a single target

Parameters
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.

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
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]

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 (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

seed: Optional[int]

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: 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]

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

seed: Optional[int]

Seed for random number generation. Default None

groundtruth_paths_gen(random_state=None)[source]

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

Yields
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]

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 (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

seed: Optional[int]

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: numpy.ndarray, detection_probability: Probability = 0.9, clutter_rate: float = 2.0, seed: Optional[int] = None)[source]

A simple detection simulator.

Parameters

• 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 None

• groundtruth – Source of ground truth tracks used to generate detections for.

• measurement_model – Measurement model used in generating detections.

seed: Optional[int]

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
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]

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 (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]

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

## Platform Simulator

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

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

## 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

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.

exception stonesoup.simulator.transition.OvershootError[source]

Bases: Exception

class stonesoup.simulator.transition.Point2PointConstantAcceleration(state: State, destination: Tuple[float, float], duration: datetime.timedelta)[source]

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: stonesoup.types.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

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
Returns

The likelihood of state1, given state2

Return type
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
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]

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: stonesoup.types.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
Returns

The likelihood of state1, given state2

Return type
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
Returns

The StateVector(s) with the model function evaluated.

Return type

StateVector or StateVectors