easypyram 2.0.0__tar.gz

easypyram-2.0.0/LICENSE.md

@@ -0,0 +1,31 @@
+Copyright © 2000 Dr. Michael D. Collins  
+Copyright © 2017 Marcus Donnelly  
+Copyright © 2026 Per A. Brodtkorb
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+- 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.
+
+- Neither the name of the copyright holder nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+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 HOLDER 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.

easypyram-2.0.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: easypyram
+Version: 2.0.0
+Summary: User-friendly Python implementation of the Range-dependent Acoustic Model (RAM) for underwater acoustics
+Keywords: acoustics,underwater acoustics,ocean acoustics,acoustic propagation,sound propagation,parabolic equation,RAM,PyRAM
+Author-Email: "Per A. Brodtkorb" <per.andreas.brodtkorb@gmail.com>
+Maintainer-Email: "Per A. Brodtkorb" <per.andreas.brodtkorb@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Homepage, https://github.com/pbrod/easypyram
+Project-URL: Repository, https://github.com/pbrod/easypyram
+Project-URL: Issues, https://github.com/pbrod/easypyram/issues
+Project-URL: Changelog, https://github.com/pbrod/easypyram/blob/master/CHANGELOG.md
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.25
+Requires-Dist: numba>=0.58
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8.0; extra == "plot"
+Description-Content-Type: text/markdown
+
+# EasyPyRAM
+
+**EasyPyRAM** is a user-friendly Python implementation of the
+Range-dependent Acoustic Model (RAM) for underwater acoustic propagation.
+
+The project builds on PyRAM while placing additional emphasis on ease of use,
+sensible defaults, structured results, documentation, examples, testing, and
+modern Python development practices.
+
+EasyPyRAM aims to lower the barrier to using RAM without hiding the numerical
+parameters that experienced users may need to control.
+
+## Background
+
+RAM was created by Michael D. Collins at the U.S. Naval Research Laboratory.
+The Python implementation is based on RAM v1.5, available from the
+Ocean Acoustics Library:
+
+https://oalib-acoustics.org/models-and-software/parabolic-equation
+
+PyRAM was developed by Marcus Donnelly to provide a version of RAM that can be
+used directly within a Python environment, such as IPython, Spyder, or Jupyter,
+and that is easier to understand, extend, and integrate into other applications
+than the original Fortran implementation.
+
+The implementation is written in Python and uses Numba JIT compilation for the
+computationally intensive numerical routines, providing performance comparable
+to compiled native code while retaining a Python interface.
+
+The `PyRAM` class largely follows the structure of the original RAM Fortran
+implementation. Many methods correspond directly to the original Fortran
+subroutines and functions and retain similar names and variable conventions.
+Some Fortran routines that are unnecessary in Python have been replaced by
+functionality provided by NumPy and other standard scientific Python tools.
+
+As in PyRAM, sound-speed profile updates with range are decoupled from seabed
+parameter updates. This provides greater flexibility when environmental data
+come from different sources or have different horizontal sampling intervals.
+
+## Why EasyPyRAM?
+
+EasyPyRAM retains the RAM numerical model and the core design of PyRAM while
+providing a more accessible interface for both new and experienced users.
+
+In particular, EasyPyRAM provides:
+
+- sensible default numerical parameters that allow users to get started
+  without first having to tune the RAM computational grid;
+- structured, typed results with convenient access to transmission loss,
+  complex pressure, ranges, depths, and model metadata;
+- built-in sound-speed profile helpers, including Munk and idealized Arctic
+  profiles;
+- practical examples demonstrating typical underwater-acoustic propagation
+  problems;
+- expanded documentation covering model configuration, numerical accuracy,
+  stability, and parameter selection;
+- NumPy-based inputs and outputs for straightforward integration with the
+  scientific Python ecosystem;
+- multiprocessing support for running multiple frequencies or acoustic
+  environments in parallel;
+- modern Python packaging, testing, static type checking, and continuous
+  integration.
+
+The default range and depth steps are automatically selected from the acoustic
+wavelength, providing a practical starting point for new users. Experienced
+users can override these and the other numerical parameters when finer control
+is required.
+
+## Installation
+
+EasyPyRAM requires Python 3.10 or later.
+
+Install the latest release from PyPI:
+
+```bash
+python -m pip install easypyram
+```
+
+To include the optional plotting dependencies used by the examples:
+
+```bash
+python -m pip install "easypyram[plot]"
+```
+
+To install the latest development version directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/pbrod/easypyram.git"
+```
+
+## Quick Start
+
+The following example calculates transmission loss for a simple
+range-independent environment:
+
+```python
+import numpy as np
+
+from easypyram import PyRAM
+
+pyram = PyRAM(
+    freq=50.0,
+    zs=50.0,
+    zr=50.0,
+    z_ss=np.array([0.0, 100.0, 400.0]),
+    rp_ss=np.array([0.0]),
+    cw=np.array(
+        [
+            [1480.0],
+            [1520.0],
+            [1530.0],
+        ]
+    ),
+    z_sb=np.array([0.0]),
+    rp_sb=np.array([0.0]),
+    cb=np.array([[1700.0]]),
+    rhob=np.array([[1.5]]),
+    attn=np.array([[0.5]]),
+    rbzb=np.array(
+        [
+            [0.0, 400.0],
+            [50_000.0, 400.0],
+        ]
+    ),
+    rmax=50_000.0,
+)
+
+result = pyram.run()
+```
+
+EasyPyRAM returns a structured `PyRAMResults` object. Model outputs are
+therefore directly available as attributes:
+
+```python
+result.ranges
+result.depths
+
+result.loss_line
+result.loss_grid
+
+result.pressure_line
+result.pressure_grid
+
+result.c0
+result.proc_time
+```
+
+For example, transmission loss at the receiver depth can be plotted with:
+
+```python
+import matplotlib.pyplot as plt
+
+plt.plot(result.ranges / 1000.0, result.loss_line)
+plt.xlabel("Range [km]")
+plt.ylabel("Transmission loss [dB]")
+plt.grid()
+plt.show()
+```
+
+## Sound-Speed Profiles
+
+EasyPyRAM provides helpers for constructing representative sound-speed
+profiles.
+
+### Munk profile
+
+The canonical Munk deep-ocean sound-speed profile can be evaluated at arbitrary
+depths:
+
+```python
+import numpy as np
+
+from easypyram import munk_profile
+
+depth = np.arange(0.0, 5000.0, 10.0)
+sound_speed = munk_profile(depth)
+```
+
+### Arctic profile
+
+An idealized Arctic profile is also provided:
+
+```python
+from easypyram import arctic_profile
+
+sound_speed = arctic_profile(depth)
+```
+
+The profiles can be compared directly:
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+from easypyram import arctic_profile, munk_profile
+
+depth = np.arange(0.0, 2000.0)
+
+plt.plot(munk_profile(depth), depth, label="Munk")
+plt.plot(arctic_profile(depth), depth, label="Arctic")
+
+plt.xlabel("Sound speed [m/s]")
+plt.ylabel("Depth [m]")
+plt.gca().invert_yaxis()
+plt.legend()
+plt.show()
+```
+
+## Relationship to RAM and PyRAM
+
+RAM was developed by Michael D. Collins at the U.S. Naval Research Laboratory.
+
+PyRAM was developed by Marcus Donnelly as a Python adaptation of RAM. 
+
+EasyPyRAM is derived from PyRAM and is independently maintained, with an
+emphasis on ease of use, sensible defaults, structured results, documentation,
+examples, and modern Python development practices.
+ 
+EasyPyRAM is not an official version of RAM or PyRAM.

easypyram-2.0.0/README.md

@@ -0,0 +1,219 @@
+# EasyPyRAM
+
+**EasyPyRAM** is a user-friendly Python implementation of the
+Range-dependent Acoustic Model (RAM) for underwater acoustic propagation.
+
+The project builds on PyRAM while placing additional emphasis on ease of use,
+sensible defaults, structured results, documentation, examples, testing, and
+modern Python development practices.
+
+EasyPyRAM aims to lower the barrier to using RAM without hiding the numerical
+parameters that experienced users may need to control.
+
+## Background
+
+RAM was created by Michael D. Collins at the U.S. Naval Research Laboratory.
+The Python implementation is based on RAM v1.5, available from the
+Ocean Acoustics Library:
+
+https://oalib-acoustics.org/models-and-software/parabolic-equation
+
+PyRAM was developed by Marcus Donnelly to provide a version of RAM that can be
+used directly within a Python environment, such as IPython, Spyder, or Jupyter,
+and that is easier to understand, extend, and integrate into other applications
+than the original Fortran implementation.
+
+The implementation is written in Python and uses Numba JIT compilation for the
+computationally intensive numerical routines, providing performance comparable
+to compiled native code while retaining a Python interface.
+
+The `PyRAM` class largely follows the structure of the original RAM Fortran
+implementation. Many methods correspond directly to the original Fortran
+subroutines and functions and retain similar names and variable conventions.
+Some Fortran routines that are unnecessary in Python have been replaced by
+functionality provided by NumPy and other standard scientific Python tools.
+
+As in PyRAM, sound-speed profile updates with range are decoupled from seabed
+parameter updates. This provides greater flexibility when environmental data
+come from different sources or have different horizontal sampling intervals.
+
+## Why EasyPyRAM?
+
+EasyPyRAM retains the RAM numerical model and the core design of PyRAM while
+providing a more accessible interface for both new and experienced users.
+
+In particular, EasyPyRAM provides:
+
+- sensible default numerical parameters that allow users to get started
+  without first having to tune the RAM computational grid;
+- structured, typed results with convenient access to transmission loss,
+  complex pressure, ranges, depths, and model metadata;
+- built-in sound-speed profile helpers, including Munk and idealized Arctic
+  profiles;
+- practical examples demonstrating typical underwater-acoustic propagation
+  problems;
+- expanded documentation covering model configuration, numerical accuracy,
+  stability, and parameter selection;
+- NumPy-based inputs and outputs for straightforward integration with the
+  scientific Python ecosystem;
+- multiprocessing support for running multiple frequencies or acoustic
+  environments in parallel;
+- modern Python packaging, testing, static type checking, and continuous
+  integration.
+
+The default range and depth steps are automatically selected from the acoustic
+wavelength, providing a practical starting point for new users. Experienced
+users can override these and the other numerical parameters when finer control
+is required.
+
+## Installation
+
+EasyPyRAM requires Python 3.10 or later.
+
+Install the latest release from PyPI:
+
+```bash
+python -m pip install easypyram
+```
+
+To include the optional plotting dependencies used by the examples:
+
+```bash
+python -m pip install "easypyram[plot]"
+```
+
+To install the latest development version directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/pbrod/easypyram.git"
+```
+
+## Quick Start
+
+The following example calculates transmission loss for a simple
+range-independent environment:
+
+```python
+import numpy as np
+
+from easypyram import PyRAM
+
+pyram = PyRAM(
+    freq=50.0,
+    zs=50.0,
+    zr=50.0,
+    z_ss=np.array([0.0, 100.0, 400.0]),
+    rp_ss=np.array([0.0]),
+    cw=np.array(
+        [
+            [1480.0],
+            [1520.0],
+            [1530.0],
+        ]
+    ),
+    z_sb=np.array([0.0]),
+    rp_sb=np.array([0.0]),
+    cb=np.array([[1700.0]]),
+    rhob=np.array([[1.5]]),
+    attn=np.array([[0.5]]),
+    rbzb=np.array(
+        [
+            [0.0, 400.0],
+            [50_000.0, 400.0],
+        ]
+    ),
+    rmax=50_000.0,
+)
+
+result = pyram.run()
+```
+
+EasyPyRAM returns a structured `PyRAMResults` object. Model outputs are
+therefore directly available as attributes:
+
+```python
+result.ranges
+result.depths
+
+result.loss_line
+result.loss_grid
+
+result.pressure_line
+result.pressure_grid
+
+result.c0
+result.proc_time
+```
+
+For example, transmission loss at the receiver depth can be plotted with:
+
+```python
+import matplotlib.pyplot as plt
+
+plt.plot(result.ranges / 1000.0, result.loss_line)
+plt.xlabel("Range [km]")
+plt.ylabel("Transmission loss [dB]")
+plt.grid()
+plt.show()
+```
+
+## Sound-Speed Profiles
+
+EasyPyRAM provides helpers for constructing representative sound-speed
+profiles.
+
+### Munk profile
+
+The canonical Munk deep-ocean sound-speed profile can be evaluated at arbitrary
+depths:
+
+```python
+import numpy as np
+
+from easypyram import munk_profile
+
+depth = np.arange(0.0, 5000.0, 10.0)
+sound_speed = munk_profile(depth)
+```
+
+### Arctic profile
+
+An idealized Arctic profile is also provided:
+
+```python
+from easypyram import arctic_profile
+
+sound_speed = arctic_profile(depth)
+```
+
+The profiles can be compared directly:
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+from easypyram import arctic_profile, munk_profile
+
+depth = np.arange(0.0, 2000.0)
+
+plt.plot(munk_profile(depth), depth, label="Munk")
+plt.plot(arctic_profile(depth), depth, label="Arctic")
+
+plt.xlabel("Sound speed [m/s]")
+plt.ylabel("Depth [m]")
+plt.gca().invert_yaxis()
+plt.legend()
+plt.show()
+```
+
+## Relationship to RAM and PyRAM
+
+RAM was developed by Michael D. Collins at the U.S. Naval Research Laboratory.
+
+PyRAM was developed by Marcus Donnelly as a Python adaptation of RAM. 
+
+EasyPyRAM is derived from PyRAM and is independently maintained, with an
+emphasis on ease of use, sensible defaults, structured results, documentation,
+examples, and modern Python development practices.
+ 
+EasyPyRAM is not an official version of RAM or PyRAM.

easypyram-2.0.0/pyproject.toml

@@ -0,0 +1,163 @@
+[project]
+name = "easypyram"
+dynamic = []
+description = "User-friendly Python implementation of the Range-dependent Acoustic Model (RAM) for underwater acoustics"
+authors = [
+    { name = "Per A. Brodtkorb", email = "per.andreas.brodtkorb@gmail.com" },
+]
+maintainers = [
+    { name = "Per A. Brodtkorb", email = "per.andreas.brodtkorb@gmail.com" },
+]
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = [
+    "LICENSE.md",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+keywords = [
+    "acoustics",
+    "underwater acoustics",
+    "ocean acoustics",
+    "acoustic propagation",
+    "sound propagation",
+    "parabolic equation",
+    "RAM",
+    "PyRAM",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.25",
+    "numba>=0.58",
+]
+version = "2.0.0"
+
+[project.urls]
+Homepage = "https://github.com/pbrod/easypyram"
+Repository = "https://github.com/pbrod/easypyram"
+Issues = "https://github.com/pbrod/easypyram/issues"
+Changelog = "https://github.com/pbrod/easypyram/blob/master/CHANGELOG.md"
+
+[project.optional-dependencies]
+plot = [
+    "matplotlib>=3.8.0",
+]
+
+[dependency-groups]
+test = [
+    "matplotlib>=3.8.0",
+    "mypy>=1.11.2",
+    "pytest>=8.0",
+    "ruff>=0.12",
+]
+release = [
+    "git-cliff>=2.6.1",
+    "pdm-bump>=0.9.8",
+]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E4",
+    "E7",
+    "E9",
+    "E501",
+    "F",
+    "I",
+    "Q",
+    "UP",
+]
+ignore = [
+    "D417",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.format]
+docstring-code-line-length = 100
+
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow (time-consuming)",
+    "benchmark: marks tests used for benchmarking",
+]
+doctest_optionflags = [
+    "NORMALIZE_WHITESPACE",
+    "IGNORE_EXCEPTION_DETAIL",
+    "ELLIPSIS",
+]
+addopts = "-rsxXf"
+testpaths = [
+    "src",
+]
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.resolution]
+allow-prereleases = true
+
+[tool.pdm.version]
+source = "file"
+path = "src/easypyram/__init__.py"
+
+[tool.pdm.scripts]
+lock = "pdm lock -dG all"
+lock-py314 = "pdm lock -L pdm.lock314 --python 3.14 --strategy no_direct_minimal_versions -dG all"
+format = "ruff format ./src/"
+check-format = "ruff format --check ./src/"
+check-style = "ruff check ./src/"
+check-types = "mypy ./src/"
+show-next-version = "git-cliff --bumped-version"
+show-next-changelog = "git-cliff"
+append-changelog = "git-cliff --unreleased --prepend CHANGELOG.md"
+
+[tool.pdm.scripts.lock-all]
+composite = [
+    "lock",
+    "lock-py314",
+]
+
+[tool.pdm.scripts.test]
+cmd = "pytest"
+
+[tool.pdm.scripts.test.env]
+MPLBACKEND = "Agg"
+
+[tool.pdm.scripts.all-tests]
+composite = [
+    "check-format",
+    "check-style",
+    "check-types",
+    "test",
+]
+
+[tool.pdm.scripts.prepare-release]
+composite = [
+    "append-changelog",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"