openstb.simulator.plugin.abc

Abstract base classes for the openSTB simulator.

These classes define the expected interface for plugins. Note that it is not required for plugin classes to derive from an abstract base class; the simulator does not check for this at runtime, and so any class which meets the specification will work.

Having said that, deriving from a base class has some benefits. If an attempt is made to instantiate an incomplete class (e.g., if you forgot to implement a method), an exception will be raised immediately. This may be easier and less frustrating to debug than an error which occurs during the simulation. Deriving from a base class also allows static type checkers (such as the mypy checker used on the core code) to do more detailed checking.

Classes:

Name	Description
ConfigLoader	A plugin which can load simulation configuration from somewhere.
Controller	Controller to run a simulation.
DaskCluster	Interface to a Dask cluster to perform computations.
Distortion	An effect which distorts the echo signal.
Environment	Properties of the environment the sonar is operating in.
PingTimes	Times that the sonar starts transmitting a ping.
PointTargets	An object made up of simple point targets.
ResultConverter	Convert a simulator result from its internal format to a desired format.
ResultFormat	Standard formats the simulation type plugins may use for storing results.
Signal	The signal transmitted by the sonar.
SignalWindow	A window which can be applied to a signal.
System	A collection of other plugins representing a sonar system.
Target	A target in the scene being simulated.
Trajectory	The trajectory followed by the sonar.
Transducer	A single transducer within the sonar system.
TravelTime	Calculates the time taken for a pulse to travel to a target and back.
TravelTimeResult	Results of a travel time calculation.

ConfigLoader

Bases: Plugin

A plugin which can load simulation configuration from somewhere.

Methods:

Name	Description
could_handle	Guess if this plugin could load a given configuration source.
load	Load the configuration.

could_handle abstractmethod classmethod

could_handle(source)

Guess if this plugin could load a given configuration source.

This is intended for use in user interfaces where a configuration source, such as a filename, is given by the user. This method should guess if it would be able to load a configuration from the source. This check should be quick and without side-effects; false positives and false negatives are acceptable. In the former case, the subsequent attempt to load will result in an error and the user being told to specify a config loader plugin. If no plugins return True, then the user will again be told to specify a plugin.

Parameters:

Name	Type	Description	Default
source	str	The provided configuration source.	required

Returns:

Type	Description
bool

Source code in openstb/simulator/plugin/abc.py

@classmethod
@abstractmethod
def could_handle(cls, source: str) -> bool:
    """Guess if this plugin could load a given configuration source.

    This is intended for use in user interfaces where a configuration source, such
    as a filename, is given by the user. This method should guess if it would be
    able to load a configuration from the source. This check should be quick and
    without side-effects; false positives and false negatives are acceptable. In the
    former case, the subsequent attempt to load will result in an error and the user
    being told to specify a config loader plugin. If no plugins return True, then
    the user will again be told to specify a plugin.

    Parameters
    ----------
    source : str
        The provided configuration source.

    Returns
    -------
    bool

    """
    pass

load abstractmethod

load()

Load the configuration.

Returns:

Type	Description
dict	A dictionary containing the configuration.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def load(self) -> dict:
    """Load the configuration.

    Returns
    -------
    dict
        A dictionary containing the configuration.

    """
    pass

Controller

Bases: Plugin, Generic[SimulationConfig]

Controller to run a simulation.

Methods:

Name	Description
run	Run the simulation.

Attributes:

Name	Type	Description
config_class	type[SimulationConfig]	The configuration class for this controller.

config_class abstractmethod property

config_class

The configuration class for this controller.

Note that this is the class, not an instance of the class.

run abstractmethod

run(config)

Run the simulation.

Parameters:

Name	Type	Description	Default
config	mapping	A mapping configuring the simulation. The specific structure will be defined by each plugin.	required

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def run(self, config: SimulationConfig):
    """Run the simulation.

    Parameters
    ----------
    config : mapping
        A mapping configuring the simulation. The specific structure will be defined
        by each plugin.

    """
    pass

DaskCluster

Bases: Plugin

Interface to a Dask cluster to perform computations.

A DaskCluster plugin is responsible for configuring Dask to use the desired computing environment, whether that is a collection of processes on the local computer or within a high performance computing (HPC) system.

Methods:

Name	Description
initialise	Initialise the cluster for use.
initialise_worker	Initialise a worker for this cluster.
terminate	Terminate use of the cluster.

Attributes:

Name	Type	Description
client	Client	Get a Client to use the cluster with.

client abstractmethod property

client

Get a Client to use the cluster with.

This should raise an exception if the cluster has not been initialised.

initialise abstractmethod

initialise()

Initialise the cluster for use.

This must be able to be called multiple times without problems.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def initialise(self):
    """Initialise the cluster for use.

    This must be able to be called multiple times without problems.

    """
    pass

initialise_worker classmethod

initialise_worker()

Initialise a worker for this cluster.

This is intended for cluster environments where each worker runs in a separate process, such as MPI, and some configuration or connection parameters need to be passed to workers. This class method should arrange for this to happen, and for the worker processes to join the cluster.

It is not required for plugins to implement this method if it is not appropriate for their environment.

Returns:

Type	Description
boolean	If True, the caller is the main simulation controller process and should proceed with the simulation on return. If False, the caller was a worker process and should exit on return.

Source code in openstb/simulator/plugin/abc.py

@classmethod
def initialise_worker(cls) -> bool:
    """Initialise a worker for this cluster.

    This is intended for cluster environments where each worker runs in a separate
    process, such as MPI, and some configuration or connection parameters need to be
    passed to workers. This class method should arrange for this to happen, and for
    the worker processes to join the cluster.

    It is not required for plugins to implement this method if it is not appropriate
    for their environment.

    Returns
    -------
    boolean
        If True, the caller is the main simulation controller process and should
        proceed with the simulation on return. If False, the caller was a worker
        process and should exit on return.

    """
    raise NotImplementedError(
        _("this cluster does not support separate worker initialisation")
    )

terminate

terminate()

Terminate use of the cluster.

This must be able to be called on an uninitialised cluster or a previously-terminated cluster.

The default implementation does nothing. Plugins should implement this function if needed to cleanly stop the cluster. Note that there is no guarantee that this function will be called; if a clean-up step is required, the plugin should implement __del__ or use something like weakref.finalize to ensure this is run before the instance is garbage collected.

Source code in openstb/simulator/plugin/abc.py

def terminate(self):
    """Terminate use of the cluster.

    This must be able to be called on an uninitialised cluster or a
    previously-terminated cluster.

    The default implementation does nothing. Plugins should implement this function
    if needed to cleanly stop the cluster. Note that there is no guarantee that this
    function will be called; if a clean-up step is required, the plugin should
    implement `__del__` or use something like `weakref.finalize` to ensure this is
    run before the instance is garbage collected.

    """
    pass

Distortion

Bases: Plugin

An effect which distorts the echo signal.

Methods:

Name	Description
apply	Parameters

apply abstractmethod

apply(ping_time, f, S, baseband_frequency, environment, signal_frequency_bounds, tt_result)

Parameters:

Name	Type	Description	Default
ping_time	float	The time, in seconds relative to the start of the trajectory, that the ping transmission was started.	required
f	array - like	A one-dimensional array of the frequencies (in Hertz) that the simulation is being performed at. Note that these are the real frequencies, but the simulation is performed in the complex baseband.	required
S	array - like	The Fourier coefficients of the current echo signal in the complex baseband. This will be a three-dimensional array with dimensions (receiver, f, target). The first and last dimensions may have size 1 if there is currently no variation in the signal over that dimension.	required
baseband_frequency	float	The carrier frequency used to shift the signal into the baseband.	required
environment	Environment	Parameters of the environment the system is operating in.	required
signal_frequency_bounds	tuple	A tuple of floats (minimum frequency, maximum frequency) giving the frequency bounds of the transmitted signal.	required
tt_result	TravelTimeResult	The results of the travel time calculations for this piece of the simulation.	required

Returns:

Name	Type	Description
modified_S	ndarray	The complex Fourier coefficients of the modified signals at the frequencies in f. This should be the same dimensions as the input S, potentially with the receiver and target dimensions expanded to full size if the distortion is receiver- and/or target-dependent.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def apply(
    self,
    ping_time: float,
    f: ArrayLike,
    S: ArrayLike,
    baseband_frequency: float,
    environment: Environment,
    signal_frequency_bounds: tuple[float, float],
    tt_result: TravelTimeResult,
) -> np.ndarray:
    """
    Parameters
    ----------
    ping_time : float
        The time, in seconds relative to the start of the trajectory, that the ping
        transmission was started.
    f : array-like
        A one-dimensional array of the frequencies (in Hertz) that the simulation is
        being performed at. Note that these are the real frequencies, but the
        simulation is performed in the complex baseband.
    S : array-like
        The Fourier coefficients of the current echo signal in the complex baseband.
        This will be a three-dimensional array with dimensions (receiver, f,
        target). The first and last dimensions may have size 1 if there is currently
        no variation in the signal over that dimension.
    baseband_frequency : float
        The carrier frequency used to shift the signal into the baseband.
    environment : openstb.simulator.abc.Environment
        Parameters of the environment the system is operating in.
    signal_frequency_bounds : tuple
        A tuple of floats (minimum frequency, maximum frequency) giving the
        frequency bounds of the transmitted signal.
    tt_result : openstb.simulator.abc.TravelTimeResult
        The results of the travel time calculations for this piece of the
        simulation.

    Returns
    -------
    modified_S : numpy.ndarray
        The complex Fourier coefficients of the modified signals at the frequencies
        in ``f``. This should be the same dimensions as the input ``S``, potentially
        with the ``receiver`` and ``target`` dimensions expanded to full size if the
        distortion is receiver- and/or target-dependent.

    """
    pass

Environment

Bases: Plugin

Properties of the environment the sonar is operating in.

Methods:

Name	Description
salinity	Get the salinity of the water.
sound_speed	Get the speed of sound.
temperature	Get the temperature of the water.

salinity abstractmethod

salinity(t, position)

Get the salinity of the water.

Parameters:

Name	Type	Description	Default
t	array - like	The times of interest in seconds since the start of the trajectory.	required
position	array - like	The positions of interest in global coordinates. This must have a final axis of size 3 containing the coordinates. All other axes must be broadcastable with t.	required

Returns:

Name	Type	Description
salinity	ndarray	The salinity of the water in parts per thousand at the requested times and positions. This will be compatible with the broadcast shape of t and position (ignoring the final axis of position). Some axes may have size one if the salinity is constant along them.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def salinity(self, t: ArrayLike, position: ArrayLike) -> np.ndarray:
    """Get the salinity of the water.

    Parameters
    ----------
    t : array-like
        The times of interest in seconds since the start of the trajectory.
    position : array-like
        The positions of interest in global coordinates. This must have a final axis
        of size 3 containing the coordinates. All other axes must be broadcastable
        with ``t``.

    Returns
    -------
    salinity : numpy.ndarray
        The salinity of the water in parts per thousand at the requested times and
        positions. This will be compatible with the broadcast shape of ``t`` and
        ``position`` (ignoring the final axis of ``position``). Some axes may have
        size one if the salinity is constant along them.

    """
    pass

sound_speed abstractmethod

sound_speed(t, position)

Get the speed of sound.

Parameters:

Name	Type	Description	Default
t	array - like	The times of interest in seconds since the start of the trajectory.	required
position	array - like	The positions of interest in global coordinates. This must have a final axis of size 3 containing the coordinates. All other axes must be broadcastable with t.	required

Returns:

Name	Type	Description
sound_speed	ndarray	The speed of sound in metres per second at the requested times and positions. This will be compatible with the broadcast shape of t and position (ignoring the final axis of position). Some axes may have size one if the sound speed is constant along them.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def sound_speed(self, t: ArrayLike, position: ArrayLike) -> np.ndarray:
    """Get the speed of sound.

    Parameters
    ----------
    t : array-like
        The times of interest in seconds since the start of the trajectory.
    position : array-like
        The positions of interest in global coordinates. This must have a final axis
        of size 3 containing the coordinates. All other axes must be broadcastable
        with ``t``.

    Returns
    -------
    sound_speed : numpy.ndarray
        The speed of sound in metres per second at the requested times and
        positions. This will be compatible with the broadcast shape of ``t`` and
        ``position`` (ignoring the final axis of ``position``). Some axes may have
        size one if the sound speed is constant along them.

    """
    pass

temperature abstractmethod

temperature(t, position)

Get the temperature of the water.

Parameters:

Name	Type	Description	Default
t	array - like	The times of interest in seconds since the start of the trajectory.	required
position	array - like	The positions of interest in global coordinates. This must have a final axis of size 3 containing the coordinates. All other axes must be broadcastable with t.	required

Returns:

Name	Type	Description
sound_speed	ndarray	The temperature in degrees Celsius at the requested times and positions. This will be compatible with the broadcast shape of t and position (ignoring the final axis of position). Some axes may have size one if the temperature is constant along them.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def temperature(self, t: ArrayLike, position: ArrayLike) -> np.ndarray:
    """Get the temperature of the water.

    Parameters
    ----------
    t : array-like
        The times of interest in seconds since the start of the trajectory.
    position : array-like
        The positions of interest in global coordinates. This must have a final axis
        of size 3 containing the coordinates. All other axes must be broadcastable
        with ``t``.

    Returns
    -------
    sound_speed : numpy.ndarray
        The temperature in degrees Celsius at the requested times and positions.
        This will be compatible with the broadcast shape of ``t`` and ``position``
        (ignoring the final axis of ``position``). Some axes may have size one if
        the temperature is constant along them.

    """
    pass

PingTimes

Bases: Plugin

Times that the sonar starts transmitting a ping.

Methods:

Name	Description
calculate	Calculate the ping times.

calculate abstractmethod

calculate(trajectory)

Calculate the ping times.

Parameters:

Name	Type	Description	Default
trajectory	Trajectory	The trajectory being followed by the system.	required

Returns:

Name	Type	Description
ping_times	ndarray	A one-dimensional array of floats giving the ping start times in seconds since the start of the trajectory.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def calculate(self, trajectory: Trajectory) -> np.ndarray:
    """Calculate the ping times.

    Parameters
    ----------
    trajectory : openstb.simulator.abc.Trajectory
        The trajectory being followed by the system.

    Returns
    -------
    ping_times : numpy.ndarray
        A one-dimensional array of floats giving the ping start times in seconds
        since the start of the trajectory.

    """
    pass

PointTargets

Bases: Target

An object made up of simple point targets.

Note that these targets have no directional or material information, and so only simple scattering with a constant amplitude scaling of the incident pulse is possible.

Methods:

Name	Description
get_chunk	Get a chunk of the point targets.

get_chunk abstractmethod

get_chunk(start_index, count)

Get a chunk of the point targets.

For efficiency, the point targets can be accessed in chunks. This access may be in random order (a user could request targets 10 to 20 and then 0 to 10), may request the same chunk multiple times, and may use different size chunks for different requests.

An implementation of this plugin may decide to cache the values. This should only be performed for relatively small sets of targets.

Parameters:

Name	Type	Description	Default
start_index	int	The zero-based index of the first point target to be retrieved. An IndexError should be raised if this is less than zero, or if it is not less than the total number of point targets in the object.	required
count	int	The number of point targets to be retrieved. A value of -1 requests all targets from start_index to the final target. A value of zero, any value less than -1, or a positive number such that the sum of start_index and count is not less than the total number of point targets in the object should result in an IndexError.	required

Returns:

Name	Type	Description
position	ndarray	An (N, 3) array with the position of each of the targets.
reflectivity	ndarray	An (N, 1) array with the amplitude scale factor for the scattering.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def get_chunk(self, start_index: int, count: int) -> tuple[np.ndarray, np.ndarray]:
    """Get a chunk of the point targets.

    For efficiency, the point targets can be accessed in chunks. This access may be
    in random order (a user could request targets 10 to 20 and then 0 to 10), may
    request the same chunk multiple times, and may use different size chunks for
    different requests.

    An implementation of this plugin may decide to cache the values. This should
    only be performed for relatively small sets of targets.

    Parameters
    ----------
    start_index
        The zero-based index of the first point target to be retrieved. An
        [IndexError][] should be raised if this is less than zero, or if it is not
        less than the total number of point targets in the object.
    count
        The number of point targets to be retrieved. A value of -1 requests all
        targets from start_index to the final target. A value of zero, any value
        less than -1, or a positive number such that the sum of `start_index` and
        `count` is not less than the total number of point targets in the object
        should result in an [IndexError][].

    Returns
    -------
    position : np.ndarray
        An (N, 3) array with the position of each of the targets.
    reflectivity : np.ndarray
        An (N, 1) array with the amplitude scale factor for the scattering.

    """
    pass

ResultConverter

Bases: Plugin

Convert a simulator result from its internal format to a desired format.

Methods:

Name	Description
can_handle	Check if this plugin will be able to convert a simulation result.
convert	Convert a simulation result.

can_handle abstractmethod

can_handle(format, config)

Check if this plugin will be able to convert a simulation result.

Parameters:

Name	Type	Description	Default
format	(ResultFormat, str)	The format of the simulation result. Simulation type plugins provided by the main package will use one of the values from the ResultFormat enum. Those from external plugins may still use a standard format, or may use a string to refer to a custom format.	required
config	SimulationConfig	The simulation configuration. The SimulationConfigt type represents a mapping with string keys that will vary based on the type of simulation being run.	required

Returns:

Type	Description
Boolean	If this plugin expects to be able to convert the simulation result to its desired final format.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def can_handle(self, format: ResultFormat | str, config: SimulationConfig) -> bool:
    """Check if this plugin will be able to convert a simulation result.

    Parameters
    ----------
    format : ResultFormat, str
        The format of the simulation result. Simulation type plugins provided by the
        main package will use one of the values from the `ResultFormat` enum. Those
        from external plugins may still use a standard format, or may use a string
        to refer to a custom format.
    config : SimulationConfig
        The simulation configuration. The `SimulationConfigt` type represents a
        mapping with string keys that will vary based on the type of simulation
        being run.

    Returns
    -------
    Boolean
        If this plugin expects to be able to convert the simulation result to its
        desired final format.

    """
    pass

convert abstractmethod

convert(format, result, config)

Convert a simulation result.

Parameters:

Name	Type	Description	Default
format	(ResultFormat, str)	The format of the simulation result. Simulation types provided by the main package will use one of the values from the ResultFormat enum. Simulation types from external plugins may still use a standard format, or may use a string to refer to a custom format.	required
result	Any	The simulation result. Simulation type plugins provided by the main package will use a zarr.Group instance. Other plugins may use different structures to hold the result.	required
config	SimulationConfig	The simulation configuration. The SimulationConfig type represents a mapping with string keys that will vary based on the type of simulation being run.	required

Returns:

Name	Type	Description
success	Boolean	True if the result was successfully converted. The simulator may choose to delete the initial result in this case. False if the conversion failed and the initial result should be retained.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def convert(
    self, format: ResultFormat | str, result: Any, config: SimulationConfig
) -> bool:
    """Convert a simulation result.

    Parameters
    ----------
    format : ResultFormat, str
        The format of the simulation result. Simulation types provided by the main
        package will use one of the values from the `ResultFormat` enum. Simulation
        types from external plugins may still use a standard format, or may use a
        string to refer to a custom format.
    result
        The simulation result. Simulation type plugins provided by the main package
        will use a `zarr.Group` instance. Other plugins may use different structures
        to hold the result.
    config : SimulationConfig
        The simulation configuration. The `SimulationConfig` type represents a
        mapping with string keys that will vary based on the type of simulation
        being run.

    Returns
    -------
    success : Boolean
        True if the result was successfully converted. The simulator may choose to
        delete the initial result in this case. False if the conversion failed and
        the initial result should be retained.

    """
    pass

ResultFormat

Bases: Enum

Standard formats the simulation type plugins may use for storing results.

Signal

Bases: Plugin

The signal transmitted by the sonar.

Methods:

Name	Description
sample	Sample the signal in the baseband.

Attributes:

Name	Type	Description
duration	float	The duration of the signal in seconds.
maximum_frequency	float	The minimum frequency of the signal in Hertz.
minimum_frequency	float	The minimum frequency of the signal in Hertz.

duration abstractmethod property

duration

The duration of the signal in seconds.

maximum_frequency abstractmethod property

maximum_frequency

The minimum frequency of the signal in Hertz.

minimum_frequency abstractmethod property

minimum_frequency

The minimum frequency of the signal in Hertz.

sample abstractmethod

sample(t, baseband_frequency)

Sample the signal in the baseband.

Parameters:

Name	Type	Description	Default
t	array - like	A one-dimensional array with the times (in seconds) to sample the signal at with t=0 corresponding to the start of transmission.	required
baseband_frequency	float	The reference frequency (in Hz) used to downconvert the signal to the analytic baseband.	required

Returns:

Name	Type	Description
samples	ndarray	Complex baseband samples of the signal. Values corresponding to times before transmission starts (t < 0) or after transmission finished (t > duration) should be set to zero.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def sample(self, t: ArrayLike, baseband_frequency: float) -> np.ndarray:
    """Sample the signal in the baseband.

    Parameters
    ----------
    t : array-like
        A one-dimensional array with the times (in seconds) to sample the signal at
        with t=0 corresponding to the start of transmission.
    baseband_frequency : float
        The reference frequency (in Hz) used to downconvert the signal to the
        analytic baseband.

    Returns
    -------
    samples : numpy.ndarray
        Complex baseband samples of the signal. Values corresponding to times before
        transmission starts (t < 0) or after transmission finished (t > duration)
        should be set to zero.

    """
    pass

SignalWindow

Bases: Plugin

A window which can be applied to a signal.

Methods:

Name	Description
get_samples	Get the samples of the window.

get_samples abstractmethod

get_samples(t, duration, fill_value=0)

Get the samples of the window.

Parameters:

Name	Type	Description	Default
t	array - like	The times (in seconds) to get window samples for, with t=0 corresponding to the start of the window.	required
duration	float	The length of the window in seconds.	required
fill_value	float	The value to use for samples outside the window.	0

Returns:

Name	Type	Description
samples	ndarray	The samples of the window as an array of floats. Values outside the window should be set to fill_value.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def get_samples(
    self, t: ArrayLike, duration: float, fill_value: float = 0
) -> np.ndarray:
    """Get the samples of the window.

    Parameters
    ----------
    t : array-like
        The times (in seconds) to get window samples for, with t=0 corresponding to
        the start of the window.
    duration : float
        The length of the window in seconds.
    fill_value : float
        The value to use for samples outside the window.

    Returns
    -------
    samples : numpy.ndarray
        The samples of the window as an array of floats. Values outside the window
        should be set to ``fill_value``.

    """
    pass

System

Bases: Plugin

A collection of other plugins representing a sonar system.

Attributes:

Name	Type	Description
receivers	list[Transducer]	The receiving transducers for the system.
signal	Signal	The signal transmitted by the system.
transmitter	Transducer	The transmitting transducer for the system.

receivers abstractmethod property

receivers

The receiving transducers for the system.

Returns:

Type	Description
list of Transducer instances

signal abstractmethod property

signal

The signal transmitted by the system.

Returns:

Type	Description
Signal

transmitter abstractmethod property

transmitter

The transmitting transducer for the system.

Returns:

Type	Description
Transducer

Target

Bases: Plugin

A target in the scene being simulated.

The initialiser of a target plugin should only perform basic error checking. At the point when it is initialised, there may be other plugins not yet initialised that will subsequently fail initialisation. Expensive computations should be placed in the prepare method which will only be called once all plugins have successfully been initialised.

Note that any properties or methods defined by a plugin may not be usable until its prepare method has been run.

Methods:

Name	Description
prepare	Prepare the target for simulation.

prepare

prepare()

Prepare the target for simulation.

Source code in openstb/simulator/plugin/abc.py

def prepare(self) -> None:
    """Prepare the target for simulation."""
    pass

Trajectory

Bases: Plugin

The trajectory followed by the sonar.

Methods:

Name	Description
orientation	Calculate the orientation of the sonar at a given time.
position	Calculate the position of the sonar at a given time.
velocity	Calculate the velocity of the sonar at a given time.

Attributes:

Name	Type	Description
duration	float	The duration of the trajectory in seconds.
length	float	The length of the trajectory in metres.
start_time	datetime	The UTC time of the first sample in the trajectory.

duration abstractmethod property

duration

The duration of the trajectory in seconds.

length abstractmethod property

length

The length of the trajectory in metres.

start_time abstractmethod property

start_time

The UTC time of the first sample in the trajectory.

Note that this can be generated at first access (e.g., set to the current date and time), but this must return the same value for all subsequent accesses.

orientation abstractmethod

orientation(t)

Calculate the orientation of the sonar at a given time.

Parameters:

Name	Type	Description	Default
t	array-like of floats	The times of interest in seconds relative to the first sample of the trajectory.	required

Returns:

Name	Type	Description
orientation	ndarray	The orientation of the sonar at each requested time as quaternions representing the rotation of the global x axis to the vehicle's x axis. This will have a shape (..., 4) where ... is the shape of the input t. Values where the given time is less than zero or greater than the trajectory's duration will be set to np.nan.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def orientation(self, t: ArrayLike) -> quaternionic.QArray:
    """Calculate the orientation of the sonar at a given time.

    Parameters
    ----------
    t : array-like of floats
        The times of interest in seconds relative to the first sample of the
        trajectory.

    Returns
    -------
    orientation : numpy.ndarray
        The orientation of the sonar at each requested time as quaternions
        representing the rotation of the global x axis to the vehicle's x axis. This
        will have a shape (..., 4) where ``...`` is the shape of the input ``t``.
        Values where the given time is less than zero or greater than the
        trajectory's duration will be set to `np.nan`.

    """
    pass

position abstractmethod

position(t)

Calculate the position of the sonar at a given time.

Parameters:

Name	Type	Description	Default
t	array-like of floats	The times of interest in seconds relative to the first sample of the trajectory.	required

Returns:

Name	Type	Description
position	ndarray	The position of the sonar at each requested time. This will have a shape (..., 3) where ... is the shape of the input t. Values where the given time is less than zero or greater than the trajectory's duration will be set to np.nan.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def position(self, t: ArrayLike) -> np.ndarray:
    """Calculate the position of the sonar at a given time.

    Parameters
    ----------
    t : array-like of floats
        The times of interest in seconds relative to the first sample of the
        trajectory.

    Returns
    -------
    position : numpy.ndarray
        The position of the sonar at each requested time. This will have a shape
        (..., 3) where ``...`` is the shape of the input ``t``. Values where the
        given time is less than zero or greater than the trajectory's duration will
        be set to `np.nan`.

    """
    pass

velocity abstractmethod

velocity(t)

Calculate the velocity of the sonar at a given time.

Parameters:

Name	Type	Description	Default
t	array-like of floats	The times of interest in seconds relative to the first sample of the trajectory.	required

Returns:

Name	Type	Description
velocity	ndarray	The velocity of the sonar at each requested time. This will have a shape (..., 3) where ... is the shape of the input t. Values where the given time is less than zero or greater than the trajectory's duration will be set to np.nan.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def velocity(self, t: ArrayLike) -> np.ndarray:
    """Calculate the velocity of the sonar at a given time.

    Parameters
    ----------
    t : array-like of floats
        The times of interest in seconds relative to the first sample of the
        trajectory.

    Returns
    -------
    velocity : numpy.ndarray
        The velocity of the sonar at each requested time. This will have a shape
        (..., 3) where ``...`` is the shape of the input ``t``. Values where the
        given time is less than zero or greater than the trajectory's duration will
        be set to `np.nan`.

    """
    pass

Transducer

Bases: Plugin

A single transducer within the sonar system.

Attributes:

Name	Type	Description
distortion	list[Distortion]	Echo signal distortions associated with the transducer.
orientation	QArray	The orientation of the transducer in the vehicle coordinate system.
position	ndarray	The position of the transducer in the vehicle coordinate system.

distortion property

distortion

Echo signal distortions associated with the transducer.

Returns:

Type	Description
list of Distortion instances

orientation abstractmethod property

orientation

The orientation of the transducer in the vehicle coordinate system.

The origin of the vehicle coordinate system is the point at which the trajectory is recorded. The x axis points forward, the y axis to starboard and the z axis down.

An unrotated transducer has a normal parallel to the x axis. Rotating with this quaternion gives the orientation of the transducer.

Returns:

Type	Description
array	A single quaternion giving the orientation.

position abstractmethod property

position

The position of the transducer in the vehicle coordinate system.

The origin of the vehicle coordinate system is the point at which the trajectory is recorded. The x axis points forward, the y axis to starboard and the z axis down.

Returns:

Type	Description
ndarray	A 3-element vector containing the position.

TravelTime

Bases: Plugin

Calculates the time taken for a pulse to travel to a target and back.

Methods:

Name	Description
calculate	Calculate the two-way travel time.

calculate abstractmethod

calculate(trajectory, ping_time, environment, tx_position, tx_orientation, rx_positions, rx_orientations, target_positions)

Calculate the two-way travel time.

Parameters:

Name	Type	Description	Default
trajectory	Trajectory	A trajectory plugin instance representing the trajectory followed by the system carrying the sonar.	required
ping_time	float	The time, in seconds relative to the start of the trajectory, that the ping transmission was started.	required
environment	Environment	The environment that the sonar is operating in.	required
tx_position	ArrayLike	The position of the transmitter in the vehicle coordinate system. This must be a vector of length 3 containing the x, y and z components of the position.	required
tx_orientation	ArrayLike | QArray	The orientation of the transmitter. This is given as a quaternion representing the rotation from the x axis of the vehicle coordinate system to the normal of the transmitter.	required
rx_positions	ArrayLike	The positions of each receiver in the vehicle coordinate system. This must be an array of shape (Nr, 3) containing the x, y and z components of the position for all Nr receivers.	required
rx_orientations	ArrayLike | QArray	The orientation of each receiver. These are given as quaternions representing the rotation from the x axis of the vehicle coordinate system to the normal of each receiver.	required
target_positions	ArrayLike	The position of each target in the global coordinate system. This must be an array of shape (Nt, 3) containing the x, y and z components of all Nt targets.	required

Returns:

Name	Type	Description
result	TravelTimeResult	The result of the calculation.

Source code in openstb/simulator/plugin/abc.py

@abstractmethod
def calculate(
    self,
    trajectory: Trajectory,
    ping_time: float,
    environment: Environment,
    tx_position: ArrayLike,
    tx_orientation: ArrayLike | quaternionic.QArray,
    rx_positions: ArrayLike,
    rx_orientations: ArrayLike | quaternionic.QArray,
    target_positions: ArrayLike,
) -> TravelTimeResult:
    """Calculate the two-way travel time.

    Parameters
    ----------
    trajectory
        A trajectory plugin instance representing the trajectory followed by the
        system carrying the sonar.
    ping_time
        The time, in seconds relative to the start of the trajectory, that the ping
        transmission was started.
    environment
        The environment that the sonar is operating in.
    tx_position
        The position of the transmitter in the vehicle coordinate system. This must
        be a vector of length 3 containing the x, y and z components of the
        position.
    tx_orientation
        The orientation of the transmitter. This is given as a quaternion
        representing the rotation from the x axis of the vehicle coordinate system
        to the normal of the transmitter.
    rx_positions
        The positions of each receiver in the vehicle coordinate system. This must
        be an array of shape (Nr, 3) containing the x, y and z components of the
        position for all Nr receivers.
    rx_orientations
        The orientation of each receiver. These are given as quaternions
        representing the rotation from the x axis of the vehicle coordinate system
        to the normal of each receiver.
    target_positions
        The position of each target in the global coordinate system. This must be an
        array of shape (Nt, 3) containing the x, y and z components of all Nt
        targets.

    Returns
    -------
    result : TravelTimeResult
        The result of the calculation.

    """
    pass

TravelTimeResult dataclass

TravelTimeResult(travel_time, tx_position, tx_orientation, tx_velocity, tx_vector, tx_path_length, incident_vector, scattering_vector, rx_position, rx_orientation, rx_velocity, rx_vector, rx_path_length)

Results of a travel time calculation.

Note that the arrays must have the expected number of dimensions, but any of the axes may be length 1 if the results are repeated along that axis. For example, rx_position may have shape (N_receivers, 1, 3) if the receivers are in the same position for all echoes.

Attributes:

Name	Type	Description
incident_vector	ndarray	Direction of incidence of the pulse.
rx_orientation	QArray	Orientation of the receivers when the echo returned.
rx_path_length	ndarray	Length of the reception acoustic path.
rx_position	ndarray	Position of the receivers when the echo returned.
rx_vector	ndarray	Direction of echo reception for each target.
rx_velocity	ndarray	Velocity of the receivers when the echo returned.
scattering_vector	ndarray	Scattering direction of the pulse.
travel_time	ndarray	Two-way travel time in seconds.
tx_orientation	QArray	Orientation of the transmitter when transmission started.
tx_path_length	ndarray	Length of the transmission acoustic path.
tx_position	ndarray	Position of the transmitter when transmission started.
tx_vector	ndarray	Direction of transmission for each target.
tx_velocity	ndarray	Velocity of the transmitter when transmission started.

incident_vector instance-attribute

incident_vector

Direction of incidence of the pulse.

This is a two-dimensional array of shape (N_targets, 3) with unit vectors in the global coordinate system. Each vector represents the direction the pulse was travelling when it reached the target.

rx_orientation instance-attribute

rx_orientation

Orientation of the receivers when the echo returned.

This is a three-dimensional quaternion array of shape (N_receivers, N_targets, 4). Each entry gives the rotation from the global x axis to the normal of the receiver when the echo from each target was received.

rx_path_length instance-attribute

rx_path_length

Length of the reception acoustic path.

This is a two-dimensional array of shape (N_receivers, N_targets) giving the total path length (in metres) that each echo followed from the target to the receiver.

rx_position instance-attribute

rx_position

Position of the receivers when the echo returned.

This is a three-dimensional array of shape (N_receivers, N_targets, 3) giving the position of each receiver at the time the echo returned from each target.

rx_vector instance-attribute

rx_vector

Direction of echo reception for each target.

This is a three-dimensional array of shape (N_receivers, N_targets, 3) with unit vectors in the global coordinate system. Each vector represents the direction the echo from a target was travelling when it reached the receiver.

rx_velocity instance-attribute

rx_velocity

Velocity of the receivers when the echo returned.

This is a three-dimensional array of shape (N_receivers, N_targets, 3) giving the velocity in global coordinates at the time the echo was received from each target.

scattering_vector instance-attribute

scattering_vector

Scattering direction of the pulse.

This is a three-dimensional array of shape (N_receivers, N_targets, 3) with unit vectors in the global coordinate system. Each vector represents the direction the echo was travelling when it left the target as it returned to each receiver.

travel_time instance-attribute

travel_time

Two-way travel time in seconds.

This is a two-dimensional array of shape (N_receivers, N_targets) containing the time taken for the pulse to travel from the transmitter to each target and then back to each receiver.

tx_orientation instance-attribute

tx_orientation

Orientation of the transmitter when transmission started.

This is a single quaternion (a vector of length 4) giving the rotation from the global x axis to the normal of the transmitter.

tx_path_length instance-attribute

tx_path_length

Length of the transmission acoustic path.

This is a vector of length targets giving the total path length (in metres) that the pulse followed from the transmitter to each target.

tx_position instance-attribute

tx_position

Position of the transmitter when transmission started.

This is a vector of length 3 with the position in global coordinates.

tx_vector instance-attribute

tx_vector

Direction of transmission for each target.

This is an array of shape (N_targets, 3) with unit vectors in the global coordinate system. Each vector represents the direction the pulse was travelling when it left the transmitter to reach each target.

tx_velocity instance-attribute

tx_velocity

Velocity of the transmitter when transmission started.

This is a vector of length 3 giving the velocity in global coordinates.