Metadata-Version: 2.4
Name: cupyram
Version: 0.1.1
Summary: GPU-accelerated Range-dependent Acoustic Model (RAM) using CuPy
Project-URL: Homepage, https://github.com/clapeyre/cupyram
Project-URL: Repository, https://github.com/clapeyre/cupyram
Project-URL: Issues, https://github.com/clapeyre/cupyram/issues
Author-email: "Dr. Corentin J. Lapeyre" <corentin.lapeyre@gmail.com>
License: BSD-3-Clause
License-File: LICENSE
Keywords: acoustics,cuda,gpu,parabolic-equation,ram,underwater
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Requires-Dist: numba-cuda>=0.23.0
Requires-Dist: numba>=0.59.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: nvtx>=0.2.14
Requires-Dist: tqdm>=4.67.1
Provides-Extra: cuda11
Requires-Dist: cupy-cuda11x>=13.0.0; extra == 'cuda11'
Provides-Extra: cuda12
Requires-Dist: cupy-cuda12x>=13.0.0; extra == 'cuda12'
Provides-Extra: cuda13
Requires-Dist: cupy-cuda13x>=13.0.0; extra == 'cuda13'
Provides-Extra: test
Requires-Dist: matplotlib; extra == 'test'
Requires-Dist: pyram; extra == 'test'
Requires-Dist: pytest-cov>=3.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: scipy; extra == 'test'
Description-Content-Type: text/markdown

# CuPyRAM

GPU-accelerated Range-dependent Acoustic Model (RAM)

## Overview

CuPyRAM is a high-performance GPU implementation of the Range-dependent Acoustic Model (RAM).

This project is a GPU port of
[PyRAM](https://github.com/marcuskd/pyram), which itself is a Python
adaptation of the original RAM model created by Dr. Michael D. Collins at the
US Naval Research Laboratory. RAM is available from the [Ocean Acoustics
Library](https://oalib-acoustics.org/models-and-software/parabolic-equation).

## Features

- **GPU Acceleration**: Leverages Numba CUDA and CuPy for GPU acceleration
- **Compatible API**: Maintains similar interface to PyRAM for easy migration
- **Validated**: Extensive test suite comparing results against reference implementations

## Requirements

- Python >= 3.8
- NVIDIA GPU with CUDA support
- CUDA Toolkit 11.x, 12.x, or 13.x
- CuPy (matching your CUDA version)

## Installation

CuPyRAM requires CuPy, which must match your CUDA version. Install based on your CUDA toolkit version:

```bash
# For CUDA 11.x
pip install cupyram[cuda11]

# For CUDA 12.x
pip install cupyram[cuda12]

# For CUDA 13.x
pip install cupyram[cuda13]

# Or install CuPy separately first, then cupyram
pip install cupy-cuda12x  # or cupy-cuda11x, cupy-cuda13x
pip install cupyram
```

**Check your CUDA version**: Run `nvcc --version` or `nvidia-smi` to determine your CUDA version.

### Optional Dependencies

For running tests (includes PyRAM for validation):

```bash
pip install cupyram[test]
```

**Note**: The test suite compares CuPyRAM results against the original PyRAM
implementation to ensure accuracy.

## Quick Start

```python
from cupyram import CuPyRAM

# Initialize the model
model = CuPyRAM(
    freq=100.0,        # Frequency in Hz
    zs=10.0,           # Source depth in meters
    zr=50.0,           # Receiver depth in meters
    rmax=10000.0,      # Maximum range in meters
    dr=10.0,           # Range step in meters
    # ... other parameters
)

# Run the model
tl = model.run()  # Returns transmission loss array
```

## Performance

Performance testing is ongoing. Initial tests suggest that one data-center
class GPU runs about 30x faster than 1 CPU core.

To leverage GPUs, it is important to maximize your batch size. The only limit
is the system's VRAM. Typically, data-center class GPUs can handle 50,000
concurrent acoustic rays (the equivalent of one PyRAM class implementation)
in parallel before saturating VRAM.

## Testing

Tests require a CUDA-capable GPU and include validation against the original PyRAM implementation:

```bash
# Install with test dependencies (includes PyRAM for validation)
pip install cupyram[test]

# Run tests
pytest tests/
```

On first run, tests will automatically generate baseline data from PyRAM for
comparison. This ensures CuPyRAM results match the ground truth CPU
implementation.

**Note**: GitHub Actions and standard CI services do not provide GPU support.
If you encounter issues, please include your GPU model and CUDA version when
reporting.

## Differences from PyRAM

CuPyRAM maintains API compatibility where possible, but includes several optimizations:
- Most heavy computations performed on GPU
- Some CPU computations parallelized (Padé coefficients)
- Memory-efficient implementations to maximize batch size

## Citation

If you use CuPyRAM in your research, please cite both this implementation and the original PyRAM:

- PyRAM: https://github.com/marcuskd/pyram
- Original RAM: Collins, M. D. (1993). A split-step Padé solution for the parabolic equation method. Journal of the Acoustical Society of America, 93(4), 1736-1742.

## License

BSD 3-Clause License. See LICENSE file for details.

This project is based on PyRAM by Marcus Donnelly, which adapted the original RAM code by Dr. Michael D. Collins.

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Acknowledgments

- Dr. Michael D. Collins for the original RAM implementation
- Marcus Donnelly for the PyRAM Python adaptation
- The Numba CUDA and CuPy development teams for the excellent GPU array library

