openstb-simulator 0.5.0__tar.gz

openstb_simulator-0.5.0/.editorconfig

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: CC0-1.0
+
+# Editor configuration settings.
+#
+# https://editorconfig.org/
+#
+# See the documentation for details on plugins for your editor.
+
+root = true
+
+[*]
+charset = utf-8
+indent_size = 4
+indent_style = space
+insert_final_newline = false
+max_line_length = 88
+trim_trailing_whitespace = true
+
+[*.yaml]
+indent_size = 2

openstb_simulator-0.5.0/.gitignore

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: openSTB contributors
+# SPDX-License-Identifier: CC0-1.0
+
+# Compiled Python files.
+__pycache__/
+*.py[cod]
+
+# Packaging artifacts.
+build/
+dist/
+src/openstb/locale
+
+# mypy cache of type information.
+.mypy_cache/
+
+# Test coverage reports.
+.coverage*
+tests/coverage
+
+# Scratch space which Dask may create during testing or running examples.
+dask-scratch-space/
+
+# Output of example simulations.
+*.mat
+*.npz
+*.zarr

openstb_simulator-0.5.0/.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yaml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc

openstb_simulator-0.5.0/LICENSES/BSD-2-Clause-Patent.txt

@@ -0,0 +1,19 @@
+Copyright (c) <YEAR> <COPYRIGHT HOLDERS>
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

openstb_simulator-0.5.0/LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

openstb_simulator-0.5.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: openstb-simulator
+Version: 0.5.0
+Summary: SONAR simulator
+Project-URL: Homepage, https://openstb.dev
+Project-URL: Documentation, https://docs.openstb.dev
+Project-URL: Repository, https://github.com/openstb/simulator.git
+Project-URL: Issues, https://github.com/openstb/simulator/issues
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: cryptography
+Requires-Dist: dask[distributed]
+Requires-Dist: numpy
+Requires-Dist: openstb-i18n
+Requires-Dist: quaternionic
+Requires-Dist: scipy
+Requires-Dist: zarr<4,>=3
+Provides-Extra: dask-diagnostics
+Requires-Dist: dask[diagnostics]; extra == 'dask-diagnostics'
+Provides-Extra: dev
+Requires-Dist: dask[diagnostics]; extra == 'dev'
+Requires-Dist: mkdocs; extra == 'dev'
+Requires-Dist: mkdocs-api-autonav; extra == 'dev'
+Requires-Dist: mkdocs-material; extra == 'dev'
+Requires-Dist: mkdocstrings[python]; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: mkdocs; extra == 'doc'
+Requires-Dist: mkdocs-api-autonav; extra == 'doc'
+Requires-Dist: mkdocs-material; extra == 'doc'
+Requires-Dist: mkdocstrings[python]; extra == 'doc'
+Provides-Extra: mpi
+Requires-Dist: dask-mpi; extra == 'mpi'
+Requires-Dist: mpi4py; extra == 'mpi'
+Provides-Extra: tests
+Requires-Dist: pytest; extra == 'tests'
+Requires-Dist: pytest-cov; extra == 'tests'
+Requires-Dist: requests; extra == 'tests'

openstb_simulator-0.5.0/README.md

@@ -0,0 +1,47 @@
+<!--
+
+SPDX-FileCopyrightText: openSTB contributors
+SPDX-License-Identifier: BSD-2-Clause-Patent
+
+-->
+
+openSTB sonar simulation framework
+==================================
+
+The openSTB sonar simulation is a modular framework for simulating the signals received
+by a sonar system. It is currently in the early stages of development, so bugs are to be
+expected.
+
+
+License
+-------
+
+The simulator is available under the BSD-2-Clause plus patent license, the text of which
+can be found in the `LICENSES/` directory or
+[online](https://spdx.org/licenses/BSD-2-Clause-Patent.html). Some of the supporting
+files are under the Creative Commons Zero v1.0 Universal license (effectively public
+domain). Again, the license is available in the `LICENSES/` directory or
+[online](https://spdx.org/licenses/CC0-1.0.html).
+
+
+Installation
+------------
+
+The openSTB tools are not yet published on PyPI (but will be in the near future). Before
+installing the simulator, you will need to have the companion [internationalisation
+support package](https://github.com/openSTB/i18n) installed in your environment, as well
+as the [hatchling build backend](https://pypi.org/project/hatchling/). You can then run
+`python -m pip install --no-build-isolation .` from the top level of a clone of this
+repository (the `--no-build-isolation` prevents pip trying to build it in a clean
+environment without access to the support packages). Some optional packages may also
+need to be installed for your use case. If you want to use MPI-based parallelisation,
+add the `MPI` option to the install: `python -m pip install --no-build-isolation
+".[MPI]"`. To also install tools to help develop code for the framework, add the `dev`
+option: `python -m pip install --no-build-isolation ".[dev]"`. You can give both options
+separated by a comma, i.e., `python -m pip install --no-build-isolation ".[MPI,dev]"`.
+
+
+Running the simulator
+---------------------
+
+See the `examples/` directory for various examples of how to run the simulator.

openstb_simulator-0.5.0/docs/examples/simple_points.md

@@ -0,0 +1,247 @@
+# Simple point simulation
+
+For this example, we will configure a simple simulation of some point targets. The
+first part of the configuration needs to specify the type of simulation to run. Here we
+want a point target simulation. We will divide the scene into chunks of 500 targets
+each, allowing us to split the work across multiple CPUs. We set the sampling rate and
+frequency used for basebanding, and finally set a filename for the simulator to store
+its results under.
+
+```toml
+[simulation]
+name = "points"
+result_filename = "simple_points.zarr"
+targets_per_chunk = 500
+sample_rate = 30e3
+baseband_frequency = 110e3
+```
+
+We want to convert the results into a more familiar format for us to use. The simulator
+will store the results in the file named above, but we can configure a result converter
+plugin which is run at the end of the simulation to convert to our desired format (the
+original results file the simulator used will then be removed). We could ask for the
+results to be stored in a NumPy `.npz` file:
+
+``` toml
+[result_converter]
+name = "numpy"
+filename = "simple_points.npz"
+compress = false
+```
+
+Or we could store them in a MATLAB file.
+
+``` toml
+[result_converter]
+name = "matlab"
+filename = "simple_points.mat"
+```
+
+We then need to tell the simulator to use an ad-hoc Dask cluster on our local computer.
+Here we want to use a maximum of 8 workers and up to 40% of the total system memory
+(note that the memory limit is best-effort, not strictly enforced). By default,
+the Dask dashboard is not started, so we have to explicitly state an address it will
+listen on -- in this case port 8787 on the local computer, i.e., http://127.0.0.1:8787.
+
+```toml
+[dask_cluster]
+name = "local"
+workers = 8
+total_memory = 0.4
+dashboard_address = ":8787"
+```
+
+Next, lets specify the details of the transmitter. The coordinate system is x forwards,
+y starboard and z down.  The orientation is a quaternion defining how to rotate the
+transducer from its original pose of pointing along the x axis. The value here results
+in it pointing to starboard and 15 degrees below horizontal. We can also specify the
+beampattern of the transducer via a signal distorting plugin.
+
+```toml
+[transmitter]
+name = "generic"
+position = [0, 1.2, 0.3]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+
+[transmitter.beampattern]
+name = "rectangular_beampattern"
+width = 0.015
+height = 0.03
+transmit = true
+receive = false
+frequency = "centre"  # only calculate the scale factor at the centre frequency
+```
+
+The transmitter will also need a signal to send, in this case an LFM up-chirp.
+
+```toml
+[signal]
+name = "lfm_chirp"
+f_start = 100e3
+f_stop = 120e3
+duration = 0.015
+rms_spl = 190
+window = {name="tukey", alpha=0.2}
+```
+
+We want to use multiple receivers to form a linear array. These are specified with the
+same options as the transmitter, but we use double square brackets around the header to
+indicate there are multiple values (an *array of tables* in TOML terms). Channel 0 of
+the results will correspond to the first receiver defined in the configuration file and
+so forth.
+
+Here we use a 5-element receiver array positioned above the transmitter (remember z is
+down) and with the same orientation.
+
+```toml
+[[receivers]]
+name = "generic"
+position = [-0.1, 1.2, 0.0]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+
+[[receivers]]
+name = "generic"
+position = [-0.05, 1.2, 0.0]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+
+[[receivers]]
+name = "generic"
+position = [0, 1.2, 0.0]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+
+[[receivers]]
+name = "generic"
+position = [0.05, 1.2, 0.0]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+
+[[receivers]]
+name = "generic"
+position = [0.1, 1.2, 0.0]
+orientation = [0.70105738, 0.09229596, -0.09229596, 0.70105738]
+```
+
+The simulator also needs to know the trajectory the system followed. For our purposes,
+an ideal linear trajectory is sufficient.
+
+```toml
+[trajectory]
+name = "linear"
+start_position = [0, 0, 0]
+end_position = [10, 0, 0]
+speed = 1.5
+```
+
+Next we have to specify when the sonar emits pings. Here, we say it will ping every
+0.2s, starting at the start of the trajectory and with the final ping being at least
+0.5s before the end of the trajectory.
+
+```toml
+[ping_times]
+name = "constant_interval"
+interval = 0.2
+start_delay = 0
+end_delay = 0.5
+```
+
+Some environmental parameters are needed to perform the simulation. For simplicity, we
+use an invariant (constant) environment with fixed values.
+
+```toml
+[environment]
+name = "invariant"
+salinity = 14.5
+sound_speed = 1480
+temperature = 11.2
+```
+
+Now lets define some targets to simulate. Like with the receivers, this is an array of
+tables.
+
+First, a rectangle with points randomly scattered within it to achieve a desired
+density. Remember that z is down, so a normal with a negative z component means the
+normal is pointing up. The reflectivity is the fraction of the incident amplitude that
+is reflected back to the sonar.
+
+```toml
+[[targets]]
+name = "random_point_rectangle"
+seed = 10671
+Dx = 5
+Dy = 120
+centre = [5, 75, 10]
+normal = [0, 0, -1]
+point_density = 10
+reflectivity = 0.06
+```
+
+And then lets add a single target at a specific position with a much stronger echo.
+
+```toml
+[[targets]]
+name = "single_point"
+position = [5, 40, 10]
+reflectivity = 10
+```
+
+One of the key parts of a simulation is to calculate the two-way travel times, i.e., the
+time it takes the acoustic wave to reach a target and scatter back to a receiver. Here,
+we want to use the stop-and-hop approximation to simplify the calculation.
+
+```toml
+[travel_time]
+name = "stop_and_hop"
+```
+
+Various distortions can be applied to the acoustic waves. This is also an array of
+plugins. Lets start by adding some energy loss due to geometric spreading (here we set
+the power parameter for spherical spreading) and also due to acoustic attenuation.
+
+```toml
+[[distortion]]
+name = "geometric_spreading"
+power = 1
+
+[[distortion]]
+name = "anslie_mccolm_attenuation"
+frequency = "centre"
+```
+
+Finally, lets configure the beampattern of the receivers. We could have included this
+with each receiver definition above, but since we want the same for all receivers it is
+easier to define this as a general plugin.
+
+```toml
+[[distortion]]
+name = "rectangular_beampattern"
+width = 0.015
+height = 0.03
+transmit = false
+receive = true
+frequency = "centre"
+```
+
+## Running the simulation
+
+!!! Note
+    The full configuration file described above can be found in the
+    `examples/cli/simple_points` directory of the source code ([or viewed on
+    GitHub](https://github.com/openSTB/simulator/tree/main/examples/cli/simple_points)).
+
+This configuration file can now be passed to the simulator CLI to perform the
+simulation. This is a simple CLI to use:
+
+```console
+openstb-sim run simple_points.toml
+```
+
+While the simulation is in progress, you can view the Dask diagnostic dashboard to view
+the progress (assuming you added the `dask-diagnostics` set of optional dependencies
+when installing) by going to [http://127.0.0.1:8787](http://127.0.0.1:8787).
+
+
+## Viewing the results
+
+When the simulation is complete, a NumPy file (or MATLAB file if you picked that option)
+with the results will be in the same directory as the configuration file. For the NumPy
+option, a simple Python script can be found in the `examples/cli/simple_points`
+directory of the source code to plot the results.

openstb_simulator-0.5.0/docs/getting_started/install.md

@@ -0,0 +1,37 @@
+# Installation
+
+
+## From PyPI
+
+The simulator is published on [PyPI](https://pypi.org) as
+[`openstb-simulator`](https://pypi.org/project/openstb-simulator). You can use your
+preferred Python environment management tool to install it. For example, with pip:
+
+```console
+pip install openstb-simulator
+```
+
+## Optional dependencies
+
+There are a number of sets of optional dependencies you may wish to add to the
+installation:
+
+* `dask-diagnostics`: support for Dask's [interactice diagnostic
+  dashboard](https://docs.dask.org/en/stable/dashboard.html) to visualise performance.
+
+* `mpi`: required for using the simulator on an MPI-based cluster
+
+* `doc`: tools for building the documentation
+
+* `tests`: tools for running the unit tests in the source repository
+
+* `dev`: tools useful for helping to develop the simulator. This automatically includes
+  the `dask-diagnotics`, `doc` and `tests` dependencies.
+
+These options can be specified when installing the simulator. For example, if you use
+pip to install from PyPI, you can just add your desired set of dependencies in square
+brackets:
+
+```console
+pip install openstb-simulator[dask-diagnostics,mpi]
+```