oalib-at-py 0.3.3

Python interfaces for Acoustics Toolbox models via at-runner (no local file I/O).

at-py

Python interfaces for the Acoustics Toolbox (AT) models (BELLHOP, KRAKEN, SCOOTER, SPARC, and related tools) via at-runner gRPC, plus in-memory read/write helpers for common AT file formats.

Stability: this is 0.x software (Alpha on PyPI). The API may evolve; numeric parity with Fortran and Matlab is best-effort and validated against in-repo fixtures and tests, not a formal verification guarantee.

Install

Core parsing and formatting depends only on NumPy:

python -m pip install oalib-at-py

The PyPI distribution is named oalib-at-py; the Python import package remains at_py.

To run AT models through ATClient, also install the pinned Python gRPC client from the public at-runner tag:

python -m pip install "at-runner @ git+https://github.com/jgebbie/at-runner.git@v0.3.0#subdirectory=client/python"

From a checkout, use a virtualenv and install the development extras:

python -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

Optional extras:

python -m pip install -e ".[mat]"     # MATLAB .mat support

The runner client pin matches the at-runner tag used by at_py.DEFAULT_AT_RUNNER_IMAGE.

Quickstart

Read and write helpers use in-memory str or bytes:

from at_py import format_env_kraken, parse_env_kraken

pekeris_env = """'Pekeris problem'
10.0
1
'NVF'
500  0.0  5000.0
     0.0  1500.0 /
  5000.0  1500.0 /
'A'  0.0
  5000.0  2000.0  0.0  2.0 /
1400.0  2000.0
1000.0
1
500.0 /
1
2500
"""

parsed = parse_env_kraken(pekeris_env)
round_tripped = parse_env_kraken(format_env_kraken(parsed))

print(round_tripped.core.title)
print(round_tripped.tail.r_max_km)

Run AT models through an existing at-runner endpoint:

from at_py import ATClient, read_shd_bin

client = ATClient(target="localhost:50051")
result = client.kraken(file_root="pekeris", inputs={"pekeris.env": pekeris_env})

if "pekeris.shd" in result.files:
    shd = read_shd_bin(result.files["pekeris.shd"])
    print(shd.pressure.shape)

For a local endpoint, start the pinned runner container in another shell:

docker run --rm -p 50051:50051 \
  --tmpfs /workspace:rw,noexec,nosuid,size=512m \
  ghcr.io/jgebbie/at-runner:v0.3.0

Or let ATClient start the pinned Docker image on demand:

from at_py import ATClient

with ATClient(runner_mode="docker", docker_host_port=50051) as client:
    result = client.kraken(file_root="pekeris", inputs={"pekeris.env": pekeris_env})

Docker mode requires the docker CLI on PATH; private GHCR access may require authentication depending on package visibility.

Documentation

The Sphinx docs are split by task:

• Installation
• Runner Usage
• Read/Write Examples
• Validation
• Port Status
• API Stability
• Release and Publishing
• Troubleshooting
• License and Attribution
• API Reference

Build them locally with:

python -m pip install -e ".[dev]"
sphinx-build -W -b html docs docs/_build

Open docs/_build/index.html.

Package Layout

• at_py: curated public exports for typical applications, including ATClient, common read_* / parse_* entry points, matching format_* writers where ported, MAT helpers, and runtime constants.
• at_py.readwrite: full parser/formatter surface, extra result types, and lower-level helpers such as load_mat_normalized_path and parse_readvector_lines.

Scope

This repository focuses on Python interfaces, file-format compatibility, testing, and CI.

• It does not re-implement AT numerical kernels.
• It executes models through at-runner, not by shelling out to local *.exe binaries.
• It parses and formats AT driver/output data in memory. Runtime APIs avoid path-based file I/O; optional convenience helpers such as load_mat_normalized_path read local files into memory before parsing.
• It intentionally keeps MATLAB .mat support in explicit entry points such as load_mat_normalized, read_shd_from_mat, read_modes_from_mat, and read_ts_from_mat.

Current Status

The Matlab ReadWrite reader matrix is implemented, and writer-style format_* ports cover the Matlab Matlab/ReadWrite/write*.m helpers, including environment files, FIELD/FIELD3D drivers, 2D and 3D boundaries, Fortran vector blocks, SSPFIL grids, RAM ram.in, and MAT SHD merge output.

Known caveats are tracked in Port Status. The remaining development work is mostly polish: demand-driven MAT v7.3 coverage, API stabilization, hosted docs, release packaging, and broader end-to-end validation.

Contributing

See CONTRIBUTING.md for development setup, integration tests, release workflow, and maintainer checks. Security reports should follow SECURITY.md.

License

at-py is released under the GNU General Public License v3 only; see LICENSE. Acoustics Toolbox itself is GPLv3-or-later, and at-py documents file formats and runner interoperability without embedding AT Fortran sources. See License and Attribution for the full project notes.