openstb.simulator.controller.simple_points

Classes:

Name	Description
SimplePointConfig	Specification for the SimplePointSimulation configuration dictionary.
SimplePointSimulation	Simulation using idealised point targets.

SimplePointConfig

Bases: TypedDict

Specification for the SimplePointSimulation configuration dictionary.

Attributes:

Name	Type	Description
dask_cluster	DaskCluster	Dask cluster to run the simulation on.
echo_distortion	NotRequired[list[Distortion]]	Plugins to apply distortion to the echoed signal.
emitted_distortion	NotRequired[list[Distortion]]	Plugins to apply distortion to the emitted signal.
environment	Environment	Plugin to provide details about the simulated environment.
ping_times	PingTimes	Plugin to calculate ping start times.
result_converter	NotRequired[ResultConverter]	Plugin to convert the simulation output into a desired format.
system	System	Details about the system to simulate.
targets	list[PointTargets]	A list of plugins giving the point targets to simulate.
trajectory	Trajectory	Plugin specifying the trajectory followed by the system.
travel_time	TravelTime	Plugin to calculate the travel times to and from each target.

dask_cluster instance-attribute

dask_cluster

Dask cluster to run the simulation on.

echo_distortion instance-attribute

echo_distortion

Plugins to apply distortion to the echoed signal.

These are applied to the signal after it has been scattered by a target and before it reaches the receiver. They are applied in the order they are given here.

emitted_distortion instance-attribute

emitted_distortion

Plugins to apply distortion to the emitted signal.

These are applied to the signal after it has been transmitted and before it reaches the target. They are applied in the order they are given here.

environment instance-attribute

environment

Plugin to provide details about the simulated environment.

ping_times instance-attribute

ping_times

Plugin to calculate ping start times.

result_converter instance-attribute

result_converter

Plugin to convert the simulation output into a desired format.

system instance-attribute

system

Details about the system to simulate.

targets instance-attribute

targets

A list of plugins giving the point targets to simulate.

trajectory instance-attribute

trajectory

Plugin specifying the trajectory followed by the system.

travel_time instance-attribute

travel_time

Plugin to calculate the travel times to and from each target.

SimplePointSimulation

SimplePointSimulation(result_filename, points_per_chunk, sample_rate, baseband_frequency, max_samples=None, task_lower_threshold=2.0, task_upper_threshold=3.0, reduction_node_count=4, reduction_levels=3)

Bases: Controller[SimplePointConfig]

Simulation using idealised point targets.

The echo from each point target is summed to get the final result. Occlusions are not modelled (the targets are infinitesimally small and so cannot cast shadows). The scattering strength of each target is a fixed value independent of aspect. The simulation is performed in the temporal frequency domain and the results are basebanded.

The targets are divided into chunks and submitted to the cluster for simulation. To combine the results from multiple chunks, a reduction tree is used. This sums the results from a small number of chunks, allowing the initial results to be freed from memory. Groups of these summed results are themselves recursively summed in the same manner until a single combined result remains. For eight chunks and a reduction node count of two, this means instead of computing the result as

result = r1 + r2 + r3 + r4 + r5 + r6 + f7 + r8

we might compute it as

result = ((r1 + r2) + (r3 + r4)) + ((r5 + r6) + (r7 + r8))

which has the same number of operations but allows memory to be freed earlier. Note that, since floating-point operations are generally not associative, these two results will differ by some small amount proportional to the machine precision and the number of operations.

This reduction will be performed for a few levels, after which the combined set of results will be written to disk. The number of chunks in each write is given by the reduction_node_count parameter raised to the power of the reduction_levels parameter.

Parameters:

Name	Type	Description	Default
result_filename	PathLike[str] | str	Filename to store the results under. If this already exists, an exception will be raised.	required
points_per_chunk	int	The maximum number of point targets to simulate in each chunk.	required
sample_rate	float	Sampling rate in Hertz of the results.	required
baseband_frequency	float	Frequency used for downconversion during basebanding (carrier frequency).	required
max_samples	int | None	The maximum number of samples each receiver will capture per ping. If not given, this is calculated from the maximum interval between pings and the sampling rate. The maximum length of the trace in seconds can be found by dividing max_samples by sample_rate.	None
task_lower_threshold	float	When the number of simulation tasks per worker in the scheduler drops below this value, add more tasks.	2.0
task_upper_threshold	float	When submitting simulation tasks to the scheduler, add enough to ensure there are at least this many per worker.	3.0
reduction_node_count	int	How many results to sum at each level of the reduction tree.	4
reduction_levels	int	How many levels to use in the reduction tree before writing the combined results to disk.	3

Source code in openstb/simulator/controller/simple_points.py

def __init__(
    self,
    result_filename: os.PathLike[str] | str,
    points_per_chunk: int,
    sample_rate: float,
    baseband_frequency: float,
    max_samples: int | None = None,
    task_lower_threshold: float = 2.0,
    task_upper_threshold: float = 3.0,
    reduction_node_count: int = 4,
    reduction_levels: int = 3,
):
    """
    Parameters
    ----------
    result_filename
        Filename to store the results under. If this already exists, an exception
        will be raised.
    points_per_chunk
        The maximum number of point targets to simulate in each chunk.
    sample_rate
        Sampling rate in Hertz of the results.
    baseband_frequency
        Frequency used for downconversion during basebanding (carrier frequency).
    max_samples
        The maximum number of samples each receiver will capture per ping. If not
        given, this is calculated from the maximum interval between pings and the
        sampling rate. The maximum length of the trace in seconds can be found by
        dividing `max_samples` by `sample_rate`.
    task_lower_threshold
        When the number of simulation tasks per worker in the scheduler drops below
        this value, add more tasks.
    task_upper_threshold
        When submitting simulation tasks to the scheduler, add enough to ensure
        there are at least this many per worker.
    reduction_node_count
        How many results to sum at each level of the reduction tree.
    reduction_levels
        How many levels to use in the reduction tree before writing the combined
        results to disk.

    """
    # Do not overwrite existing results.
    self.result_filename = Path(result_filename)
    if self.result_filename.exists():
        raise ValueError(_("specified output path already exists"))

    # Basic parameter checks.
    if points_per_chunk < 1:
        raise ValueError(_("points per chunk must be at least one"))
    if sample_rate < 1:
        raise ValueError(_("sample rate must be at least one"))
    if baseband_frequency < 0:
        raise ValueError(_("baseband frequency cannot be negative"))
    if reduction_node_count < 2:
        raise ValueError(_("reduction node count must be at least two"))
    if reduction_levels < 1:
        raise ValueError(_("reduction levels must be at least one"))

    # If given, max samples must be given.
    if max_samples is not None and max_samples < 1:
        raise ValueError(_("max samples must be at least one"))

    # Ensure thresholds are valid.
    if task_lower_threshold < 1:
        raise ValueError(_("task lower threshold must be at least one"))
    if task_upper_threshold < task_lower_threshold:
        raise ValueError(
            _("task upper threshold cannot be less than lower threshold")
        )

    self.points_per_chunk = points_per_chunk
    self.sample_rate = sample_rate
    self.baseband_frequency = baseband_frequency
    self.max_samples = max_samples
    self.task_lower_threshold = task_lower_threshold
    self.task_upper_threshold = task_upper_threshold
    self.reduction_node_count = reduction_node_count
    self.reduction_levels = reduction_levels