openstb-simulator 0.5.0__py3-none-any.whl

openstb/simulator/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import typing
+
+# The underlying array type of a quaternionic array is not fixed (it can be different
+# dtypes, or even other array classes like a SymPy array for symbolic quaternion
+# analysis). As such, the types are dynamically created. For static typing, we have a
+# stub (see utils/typing_stubs/quaternionic.pyi) specifying the pieces of the interface
+# we use. This uses a shorthand type QArray; we need to make that available in the
+# runtime interface so normal interpreters can access it.
+if not typing.TYPE_CHECKING:  # pragma:no cover
+    import quaternionic
+
+    quaternionic.QArray = quaternionic.array

openstb/simulator/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+from openstb.simulator.cli import openstb_sim
+
+if __name__ == "__main__":
+    openstb_sim()

openstb/simulator/cli/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import click
+
+from openstb.simulator.cli.run import run
+
+
+@click.group(
+    context_settings=dict(help_option_names=("-h", "--help"), show_default=True)
+)
+def openstb_sim():
+    """The openSTB sonar simulator."""
+    pass
+
+
+openstb_sim.add_command(run)

openstb/simulator/cli/run.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import click
+
+from openstb.simulator.plugin import loader, util
+
+
+@click.command
+@click.argument("config_source", nargs=1, type=str)
+@click.option(
+    "-c",
+    "--config-plugin",
+    type=str,
+    default=None,
+    metavar="PLUGIN",
+    help=(
+        "The name of the configuration loading plugin needed to parse the "
+        "configuration source. This can be the name of a registered plugin, a "
+        "'ClassName:package.module' reference to a class in an installed module, or a "
+        "'ClassName:path/to/file.py' reference to a class in a Python file."
+    ),
+)
+@click.option(
+    "--dask-worker",
+    type=str,
+    default=None,
+    metavar="PLUGIN",
+    help=(
+        "For use with Dask cluster plugins which support independently starting the "
+        "workers, such as clusters using MPI. This allows the workers to wait for "
+        "configuration details from the main process instead of each worker parsing "
+        "the configuration. Not all Dask cluster plugins will support this. The value "
+        "can be the name of a registered plugin, a 'ClassName:package.module' "
+        "reference to a class in an installed module, or a 'ClassName:path/to/file.py' "
+        "reference to a class in a Python file."
+    ),
+)
+def run(config_plugin, config_source, dask_worker):
+    """Run a simulation.
+
+    The configuration of the simulation is loaded from the source given by
+    CONFIG_SOURCE. This may be the path to a configuration file, or another type of
+    source handled by a suitable configuration loading plugin.
+
+    """
+    loader_cls = None
+
+    # Given a Dask cluster plugin which supports independent worker spawning.
+    if dask_worker is not None:
+        cls = loader.load_plugin_class("openstb.simulator.dask_cluster", dask_worker)
+        if not cls.initialise_worker():
+            return
+
+    # Loader plugin specified; get it.
+    if config_plugin is not None:
+        loader_cls = loader.load_plugin_class(
+            "openstb.simulator.config_loader", config_plugin
+        )
+
+    # Not specified; try to guess it.
+    else:
+        name, loader_cls = util.find_config_loader(config_source)
+        if loader_cls is None:
+            raise click.ClickException(
+                "could not automatically determine the config loader; please specify "
+                "the appropriate loader."
+            )
+
+    # Create an instance and get the configuration dictionary.
+    config_loader = loader_cls(config_source)
+    config = config_loader.load()
+
+    # Get the simulation plugin.
+    simulation = loader.simulation(config.pop("simulation"))
+
+    # Load all the other plugins, and check it conforms to the configuration required by
+    # the simulation plugin.
+    util.load_config_plugins(simulation.config_class, config)
+
+    # And then we can run the simulation.
+    simulation.run(config)

openstb/simulator/cluster/dask_local.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+from dask.system import CPU_COUNT
+import distributed
+from distributed.system import MEMORY_LIMIT
+import numpy as np
+
+from openstb.i18n.support import translations
+from openstb.simulator.plugin.abc import DaskCluster
+
+_ = translations.load("openstb.simulator").gettext
+
+
+class DaskLocalCluster(DaskCluster):
+    """A Dask cluster running on the local machine."""
+
+    def __init__(
+        self,
+        workers: int | float,
+        worker_memory: int | float | None = None,
+        total_memory: int | float | None = None,
+        security: bool = True,
+        dashboard_address: str | None = None,
+    ):
+        """
+        Parameters
+        ----------
+        workers : int, float
+            Number of workers to add to the cluster. If a float, this is interpreted as
+            a fraction of the available CPUs. If -1, use all available CPUs. Any other
+            value is taken to be the number of CPUs to use.
+        worker_memory, total_memory : int, float
+            The desired memory limit for the cluster. This can be specified per worker
+            or for all workers; only one may be given (and one must be given). A float
+            indicates a fraction of the total system memory, and an integer the number
+            of bytes. Note that this limit is enforced on a best-effort basis and some
+            workers may exceed it.
+        security : boolean
+            If True, self-signed temporary credentials are used to secure communications
+            within the cluster. If False, communications are unencrypted.
+        dashboard_address : str, optional
+            Address the Dask diagnostic dashboard server will listen on, e.g.,
+            "localhost:8787" or "0.0.0.0:8787". If not given, the server will be
+            disabled. Note that the logs may still print a dashboard address if
+            disabled, but there will be nothing at that address. This is a known bug in
+            dask.distributed: https://github.com/dask/distributed/issues/7994
+
+        """
+        if isinstance(workers, float):
+            self.workers = int(np.fix(workers * CPU_COUNT))
+        elif workers == -1:
+            self.workers = CPU_COUNT
+        else:
+            self.workers = workers
+
+        # The distributed LocalCluster takes memory per worker as an integer number of
+        # bytes. Convert our inputs.
+        if worker_memory is not None and total_memory is not None:
+            raise ValueError(
+                _("only one of worker_memory and total_memory can be given")
+            )
+        elif worker_memory is not None:
+            if isinstance(worker_memory, float):
+                worker_memory = int(np.fix(worker_memory * MEMORY_LIMIT))
+            self.memory = worker_memory
+        elif total_memory is not None:
+            if isinstance(total_memory, float):
+                total_memory = int(np.fix(total_memory * MEMORY_LIMIT))
+            self.memory = total_memory // self.workers
+        else:
+            raise ValueError(_("worker_memory or total_memory must be given"))
+
+        self.security = security
+        self.dashboard_address = dashboard_address
+
+        self._cluster: distributed.LocalCluster | None = None
+        self._client: distributed.Client | None = None
+
+    def initialise(self):
+        if self._cluster is not None:
+            return
+
+        self._cluster = distributed.LocalCluster(
+            n_workers=self.workers,
+            processes=True,
+            threads_per_worker=1,
+            memory_limit=self.memory,
+            dashboard_address=self.dashboard_address,
+            security=self.security,
+        )
+
+    @property
+    def client(self) -> distributed.Client:
+        if self._cluster is None:
+            raise RuntimeError(_("must initialise the cluster before getting a client"))
+
+        if self._client is None:
+            self._client = self._cluster.get_client()
+        return self._client
+
+    def terminate(self):
+        if self._client is not None:
+            self._client.shutdown()
+            self._client = None
+        if self._cluster is not None:
+            self._cluster.close()
+            self._cluster = None

openstb/simulator/cluster/dask_mpi.py

@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import dask_mpi
+import distributed
+from mpi4py import MPI
+
+from openstb.i18n.support import translations
+from openstb.simulator.plugin.abc import DaskCluster
+
+_ = translations.load("openstb.simulator").gettext
+
+
+class DaskMPICluster(DaskCluster):
+    """A cluster of Dask nodes communicating via MPI.
+
+    This requires the ``dask_mpi`` package to be installed. This uses the ``mpi4py``
+    library to communicate via MPI. The process running with MPI rank 0 is used for the
+    Dask scheduler, and the process running with MPI rank 1 is used for the main
+    simulation controller. All other processes are used as computation workers.
+
+    """
+
+    def __init__(
+        self,
+        interface: str | None = None,
+        dashboard_address: str | None = None,
+        separate_workers: bool = True,
+        local_directory: str | None = None,
+    ):
+        """
+        Parameters
+        ----------
+        interface : str
+            The network interface to use for communication, e.g., "eth0" or "ib0". If
+            not specified, the scheduler will attempt to determine the appropriate
+            interface.
+        dashboard_address : str, optional
+            Address the Dask diagnostic dashboard server will listen on, e.g.,
+            "localhost:8787" or "0.0.0.0:8787". If not given, the server will be
+            disabled.
+        separate_workers : boolean, default True
+            If True, the worker processes (all processes with a rank other than 1) will
+            use the initialise_workers() method. If False, all processes will read the
+            configuration and proceed as normal. Setting this to True is recommended so
+            that only the main controller process will have to read and parse the
+            configuration.
+        local_directory : str, optional
+            The path to a local scratch directory for Dask to use. This should be local
+            to each node, not on a network drive. If not given, Dask will fall back to
+            an internal default path.
+
+        """
+        self.interface = interface
+        self.dashboard_address = dashboard_address
+        self._initialised = False
+        self._client: distributed.Client | None = None
+        self.separate_workers = separate_workers
+        self.local_directory = local_directory
+
+    def initialise(self):
+        if self._initialised:
+            return
+
+        # Settings for dask_mpi.initialize().
+        settings = dict(
+            interface=self.interface,
+            dashboard=self.dashboard_address is not None,
+            dashboard_address=self.dashboard_address or "",
+            local_directory=self.local_directory,
+        )
+
+        if self.separate_workers:
+            comm = MPI.COMM_WORLD
+
+            # Avoid a misconfiguration with a clear error message.
+            rank = comm.Get_rank()
+            if rank != 1:
+                raise RuntimeError(
+                    _(
+                        "when using separate workers, the simulation controller should "
+                        "only be run on MPI rank 1"
+                    )
+                )
+
+            # Broadcast the settings to the scheduler and worker processes. Note that
+            # MPI inserts a synchronisation barrier with a broadcast.
+            comm.bcast(settings, root=1)
+
+        dask_mpi.initialize(**settings)
+        self._initialised = True
+
+    @classmethod
+    def initialise_worker(cls):
+        comm = MPI.COMM_WORLD
+
+        # Avoid misconfigurations with a clear error message.
+        rank = comm.Get_rank()
+        if rank == 1:
+            return True
+
+        # The controller will broadcast the settings when available (after the
+        # configuration has been loaded and parsed, and the main DaskCluster plugin is
+        # initialised).
+        settings = comm.bcast(None, root=1)
+        dask_mpi.initialize(**settings)
+        return False
+
+    @property
+    def client(self) -> distributed.Client:
+        if not self._initialised:
+            raise RuntimeError(_("must initialise the cluster before getting a client"))
+        if self._client is None:
+            self._client = distributed.Client()
+        return self._client

openstb/simulator/config_loader/toml.py

@@ -0,0 +1,182 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import os
+from pathlib import Path
+import tomllib
+
+from openstb.i18n.support import translations
+from openstb.simulator.plugin.abc import ConfigLoader
+from openstb.simulator.types import PluginSpec
+
+_ = translations.load("openstb.simulator").gettext
+
+
+class TOMLLoader(ConfigLoader):
+    """Load simulation configuration from a TOML file.
+
+    The file may contain an entry ``include giving a list of other filenames to
+    parse and merge into its configuration. This include behaviour is nested, i.e., any
+    included file may also specify an `include` list. Any relative filenames are
+    evaluated from the directory containing the file currently being processed.
+
+    Included files may not overwrite values that have already been set. An exception is
+    made for values from an array of tables; in this case, included tables are appended
+    to the end of the current array.
+
+    """
+
+    def __init__(self, filename: os.PathLike[str] | str):
+        """
+        Parameters
+        ----------
+        filename
+            The path to the configuration file.
+
+        """
+        self.filename = Path(filename)
+        self._who_defined: dict[str, Path] = {}
+
+    @classmethod
+    def could_handle(cls, source: str) -> bool:
+        # Assume any file ending with .toml could be loadable.
+        return source.endswith(".toml")
+
+    def load(self) -> dict:
+        self._who_defined = {}
+        return self._load_file(self.filename)
+
+    def _load_file(self, filename: Path, current: dict | None = None) -> dict:
+        """Load a file and update the current configuration.
+
+        Parameters
+        ----------
+        filename : Path
+            The path to the file to load.
+        current : dict, optional
+            The current configuration to update. If None, a new configuration will be
+            started.
+
+        Returns
+        -------
+        dict
+            The current configuration after the file was loaded. If `current` was given
+            to the method, it is both modified in-place and returned.
+
+        """
+        if current is None:
+            self._who_defined = {}
+            current = {}
+
+        # Load this file.
+        with filename.open("rb") as fp:
+            config = tomllib.load(fp)
+
+        # Extract any includes.
+        includes = config.pop("include", [])
+        if not isinstance(includes, list):
+            raise ValueError(
+                _("{filename}: value of include must be a list").format(
+                    filename=str(filename)
+                )
+            )
+
+        # Try to merge our config into the current.
+        for entry, values in config.items():
+            # We don't expect any other top-level entries. All values should be tables
+            # (dicts) or arrays (lists) of tables. Collect the names and parameters into
+            # a proper PluginSpec dictionary.
+            if isinstance(values, dict):
+                values = self._collect_parameters(filename, entry, values)
+            elif isinstance(values, list):
+                values = [
+                    self._collect_parameters(filename, f"{entry}[{i}]", value)
+                    for i, value in enumerate(values)
+                ]
+            else:
+                raise ValueError(
+                    _("{filename}: unexpected top-level entry {name}").format(
+                        filename=filename, name=entry
+                    )
+                )
+
+            # New key => easy.
+            if entry not in current:
+                current[entry] = values
+                continue
+
+            # Existing key is a list. We allow another list or a single table.
+            if isinstance(current[entry], list):
+                if isinstance(values, list):
+                    current[entry].extend(values)
+                elif isinstance(values, dict):
+                    current[entry].append(values)
+                else:
+                    raise ValueError(
+                        _("{filename}: {name} must be a table").format(
+                            filename=filename, name=entry
+                        )
+                    )
+                continue
+
+            # Don't allow overwriting.
+            msg = _("{filename} tried to overwrite value of {table} set by {original}")
+            raise ValueError(
+                msg.format(
+                    filename=filename, original=self._who_defined[entry], table=entry
+                )
+            )
+
+        # Update which tables came from which files. This will overwrite the source of
+        # lists, but we don't need those.
+        for entry in config.keys():
+            self._who_defined[entry] = filename
+
+        # Process any includes.
+        for include in includes:
+            includefn = Path(include)
+            if not includefn.is_absolute():
+                includefn = filename.parent / includefn
+            self._load_file(includefn, current)
+
+        return current
+
+    def _collect_parameters(self, filename: Path, entry: str, spec: dict) -> PluginSpec:
+        """Collect names and parameters into a PluginSpec dictionary.
+
+        Parameters
+        ----------
+        filename : Path
+            Filename the entry was loaded from. Used for error reporting and to set the
+            source of the PluginSpec.
+        entry : str
+            Name of the table. Used for error reporting.
+        spec : dict
+            The values of the table loaded from the file.
+
+        Returns
+        -------
+        dict
+            A PluginSpec dictionary. The ``name`` entry from ``spec`` will be copied,
+            and all other items will be placed into a dictionary under the
+            ``parameters`` key.
+
+        """
+        name = spec.pop("name", None)
+        if name is None:
+            raise ValueError(
+                _("{filename}: no plugin name given for entry {name}").format(
+                    filename=filename, name=entry
+                )
+            )
+
+        # Handle nested plugin specs (e.g., transducer beampatterns, signal windows).
+        for k in spec.keys():
+            if isinstance(spec[k], dict):
+                spec[k] = self._collect_parameters(filename, f"{entry}.{k}", spec[k])
+
+        return {
+            "name": name,
+            "parameters": spec,
+            "spec_source": filename,
+        }

openstb/simulator/distortion/beampattern.py

@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from openstb.i18n.support import translations
+from openstb.simulator.plugin.abc import Distortion, Environment, TravelTimeResult
+from openstb.simulator.util import rotate_elementwise
+
+_ = translations.load("openstb.simulator").gettext
+
+
+class RectangularBeampattern(Distortion):
+    """Scaling due to the beampattern of an ideal rectangular aperture."""
+
+    def __init__(
+        self,
+        width: float,
+        height: float,
+        transmit: bool,
+        receive: bool,
+        frequency: str,
+        horizontal: bool = True,
+        vertical: bool = True,
+    ):
+        """
+        Parameters
+        ----------
+        width, height : float
+            The size of the aperture in metres.
+        transmit, receive: Boolean
+            Whether to apply this for the transmited and/or received signal. At least
+            one of these must be True.
+        frequency : {"min", "centre", "max", "all}
+            Which frequency or frequencies to calculate the attenuation at. If "min" or
+            "max", use the minimum or maximum frequency in the signal, respectively.
+            When "centre", use the centre frequency, i.e., (min + max) / 2. If "all",
+            calculate the attenuation at each frequency being sampled in the simulation.
+        horizontal, vertical : Boolean, default True
+            Whether to include the horizontal and/or vertical components of the
+            beampattern in the scaling. At least one of these must be true.
+
+
+        """
+        # Check the size.
+        if not width > 0:
+            raise ValueError(_("width of aperture must be positive"))
+        if not height > 0:
+            raise ValueError(_("height of aperture must be positive"))
+        self.width = width
+        self.height = height
+
+        # Check when to apply.
+        self.transmit = transmit
+        self.receive = receive
+        if not self.transmit and not self.receive:
+            raise ValueError(_("at least one of transmit and receive must be true"))
+
+        # Which frequency to evaluate at.
+        if frequency == "min":
+            self._freqmode = 0
+        elif frequency == "max":
+            self._freqmode = 1
+        elif frequency == "centre":
+            self._freqmode = 2
+        elif frequency == "all":
+            self._freqmode = 3
+        else:
+            raise ValueError(
+                _("unknown value for frequency: {value}").format(value=frequency)
+            )
+
+        # Components to include.
+        self.horizontal = horizontal
+        self.vertical = vertical
+        if not self.horizontal and not self.vertical:
+            raise ValueError(_("at least one of horizontal and vertical must be true"))
+
+    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:
+        # Use the sound speed at transmit.
+        sound_speed = environment.sound_speed(ping_time, tt_result.tx_position)
+        sound_speed = np.array(sound_speed).reshape(1, 1, 1)
+
+        # Generate a wavelength array depending on the frequency mode.
+        if self._freqmode == 0:
+            # Minimum signal frequency.
+            wl = sound_speed / signal_frequency_bounds[0]
+        elif self._freqmode == 1:
+            # Maximum signal frequency:
+            wl = sound_speed / signal_frequency_bounds[1]
+        elif self._freqmode == 2:
+            # Centre signal frequency
+            wl = sound_speed / (np.sum(signal_frequency_bounds) / 2)
+        else:
+            # All frequencies being sampled.
+            wl = sound_speed / np.array(f)[np.newaxis, :, np.newaxis]
+
+        # In the following, we rotate the vectors back into the transducer coordinate
+        # system (so x is the transducer normal). In the case of the receiver, we also
+        # negate the components: the vector points into the transducer in this case, and
+        # we want it to point away from it.
+
+        distorted = np.array(S)
+
+        # Evaluate for the transmitter.
+        if self.transmit:
+            tx_vector = rotate_elementwise(
+                ~tt_result.tx_orientation,
+                tt_result.tx_vector[np.newaxis, np.newaxis, :],
+            )
+            distorted = distorted * self._eval(wl, tx_vector)
+
+        # And for the receivers.
+        if self.receive:
+            rx_vector = rotate_elementwise(
+                ~tt_result.rx_orientation, -tt_result.rx_vector[:, np.newaxis, ...]
+            )
+            distorted = distorted * self._eval(wl, rx_vector)
+
+        return distorted
+
+    def _eval(self, wavelength: np.ndarray, direction: np.ndarray) -> np.ndarray:
+        if self.horizontal and self.vertical:
+            return np.sinc(self.width * direction[..., 1] / wavelength) * np.sinc(
+                self.height * direction[..., 2] / wavelength
+            )
+
+        if self.horizontal:
+            return np.sinc(self.width * direction[..., 1] / wavelength)
+
+        return np.sinc(self.height * direction[..., 2] / wavelength)