rtrs

3D Underwater acoustic ray tracing with arbitrary Cartesian receiver coordinates, geometry independent broadband beam tracing, and Python bindings. It is used in Blue Pebble: sonar signal processing plugin for Stone Soup.

Features

• Exclusively 3D ray / beam tracing
• Efficient wideband beam tracing using Gaussian beams (ray geometry is traced as frequency independent, then the beam influence is calculated at receiver coordinates for each frequency)
• Python bindings via pyo3 (No IO files)
• Cartesian receiver representation for grids and arrays
• Surface (vacuum) and bottom (rigid, lossy acoustic, lossy elastic) reflections
• 3D sound speed profiles ( $c(x,y,z)$ )
• 2D bathymetry ( $b(x,y)$ )
• Optional IO with json files
• Parallel processing over the number of rays / beams with rayon
• Optional no-ray-path mode to reduce memory and output size
• Euler and RK2 integration methods
• Input validation

Installing, Building, and Running

There are 3 main ways to use rtrs: directly with Rust and Cargo, with Python bindings, or using CLI with the pre-built binary and JSON input files (Not covered here). The first step is to clone the repository and navigate to the project directory:

git clone https://github.com/fincb/rtrs.git
cd rtrs

Rust, Cargo, and are required for all methods, Python is also required for the Python bindings. The recommended way (for linux and macos) to install Rust and Cargo is with rustup:

curl https://sh.rustup.rs -sSf | sh

Then check:

rustc --version
cargo --version
rustup --version

Building the Docs

• Primary docs via cargo doc (guides and API together)
• JSON schema: docs/schema/simulation-config.schema.json

The primary documentation is built with cargo doc (guides and API together). To build the docs locally, run:

cargo doc --no-deps --features python

Or to open the docs in the browser after building:

cargo doc --no-deps --features python --open

The generated docs include user-facing guide pages under rtrs::guides:

• rtrs::guides::install_and_build
• rtrs::guides::input_reference
• rtrs::guides::output_reference
• rtrs::guides::python_usage

The json schema can be found here docs/schema/simulation-config.schema.json.

Rust & Cargo Build and Run

Build with cargo (the resulting binary will be in target/release/):

cargo build --release

Run with a JSON input file (compiles and runs in release mode):

cargo run --release <path_to_input_file>.json

Python Bindings Normal Build and Run

Set up a virtual environment and install dependencies:

python -m venv --prompt rtrs .venv
source .venv/bin/activate
pip install -e .

or with conda:

conda activate <env_name>
pip install -e .

Then in a Python script the package can be imported and used:

import rtrs

env = # <Dictionary with environment parameters>
result = rtrs.run_simulation(env)

Python Bindings with plotting for examples

For running the examples with plotting, install the viz extra dependencies:

python -m venv --prompt rtrs .venv
source .venv/bin/activate
pip install -e ".[viz]"

or with conda:

conda activate <env_name>
pip install -e ".[viz]"

Python Bindings with Development Mode

Useful for testing changes to the Rust code without needing to reinstall the package after every change. The dev extra also includes maturin as a dependency for building the Rust extension.

Set up a virtual environment and install dependencies:

python -m venv --prompt rtrs .venv
source .venv/bin/activate
pip install -e ".[dev]"

or with conda:

conda activate <env_name>
pip install -e ".[dev]"

For plotting and development, install both extras:

pip install -e ".[dev,viz]"

Build the Rust extension into the active environment and to rebuild after any changes to the Rust code:

maturin develop --release

See examples/ for usage with and without python bindings. Note that in the examples which do not use the python bindings, the program is compiled and run in release mode with cargo from within a python script.

PyPI Release

Pre-built python wheels can be downloaded from pypi:

pip install rtrs

Hopefully, pre-built wheels are distributed per platform and Python version via GitHub Actions using maturin-action, so no Rust toolchain is required.

Possible Future Features

• Low frequency correction
• Performance improvements
• Multiple sources and Source directivity patterns
• Delay and amplitude output

Name

The name "rtrs" means ray tracing rust (rs after the rust file extension .rs). The name in text is always all in lower case matching the name in code rtrs.

Citation

If you use rtrs in academic work, please cite the associated conference paper and the software release (via DOI when available).

@inproceedings{wakefield2026sonar,
  title={A Sonar Signal Processing Plugin for Stone Soup},
  author={Wakefield, Joshua J and Boulton, Finley and Colquitt, Daniel J. and Ralph, Jason F. and Williams, Duncan P.},
  booktitle={2026 29th International Conference on Information Fusion (FUSION)},
  pages={1--8},
  year={2026},
  organization={IEEE}
}

License

MIT License. See LICENSE file for details.