Metadata-Version: 2.4
Name: oalib-at-py
Version: 0.3.3
Summary: Python interfaces for Acoustics Toolbox models via at-runner (no local file I/O).
Author: AT Python Port Contributors
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/jgebbie/at-py
Project-URL: Repository, https://github.com/jgebbie/at-py
Project-URL: Documentation, https://jgebbie.github.io/at-py/
Keywords: acoustics,ocean,bellhop,kraken,scooter,sparc,at-runner
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2
Provides-Extra: mat
Requires-Dist: scipy>=1.11; extra == "mat"
Requires-Dist: h5py>=3; extra == "mat"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: prek>=0.3.8; extra == "dev"
Requires-Dist: commitizen>=4.13; extra == "dev"
Requires-Dist: scipy>=1.11; extra == "dev"
Requires-Dist: h5py>=3; extra == "dev"
Requires-Dist: sphinx>=7; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=2; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```bash
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:

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

Optional extras:

```bash
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`:

```python
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:

```python
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:

```bash
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:

```python
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](docs/installation.rst)
- [Runner Usage](docs/runner_usage.rst)
- [Read/Write Examples](docs/readwrite_examples.rst)
- [Validation](docs/validation.rst)
- [Port Status](docs/port_status.rst)
- [API Stability](docs/api_stability.rst)
- [Release and Publishing](docs/release.rst)
- [Troubleshooting](docs/troubleshooting.rst)
- [License and Attribution](docs/license_attribution.rst)
- [API Reference](docs/api.rst)

Build them locally with:

```bash
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](docs/port_status.rst). 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](CONTRIBUTING.md) for development setup, integration tests,
release workflow, and maintainer checks. Security reports should follow
[SECURITY.md](SECURITY.md).

## License

**at-py** is released under the **GNU General Public License v3** only; see
[LICENSE](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](docs/license_attribution.rst) for the full
project notes.
