Metadata-Version: 2.4
Name: potamides
Version: 1.0.0
Summary: Constrain gravitational potential with stream curvature
Project-URL: Homepage, https://github.com/xggs-dev/potamides
Project-URL: Bug Tracker, https://github.com/xggs-dev/potamides/issues
Project-URL: Discussions, https://github.com/xggs-dev/potamides/discussions
Project-URL: Changelog, https://github.com/xggs-dev/potamides/releases
Author-email: Jacob Nibauer <jnibauer@princeton.edu>, Nathaniel Starkman <starkman@mit.edu>, Sirui Wu <sirui.wu@nbi.ku.dk>
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: astropy>=7.0
Requires-Dist: galax
Requires-Dist: interpax>=0.3.8
Requires-Dist: jax>=0.5.3
Requires-Dist: jaxtyping>=0.3.1
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: numpy>=2.2.3
Requires-Dist: optax>=0.2.4
Requires-Dist: scipy>=1.15.2
Requires-Dist: typing-extensions>=4.13.2
Requires-Dist: unxt>=1.6.2
Requires-Dist: xmmutablemap>=0.1
Description-Content-Type: text/markdown

# potamides

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]

[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]

<!-- SPHINX-START -->

## About

**potamides** is a Python package for constraining gravitational potentials
using stellar stream curvature analysis. The name is inspired by Greek ποταμίδες
("potamídes", meaning "river streams"), with the initial "P" representing
$\Phi$, the conventional symbol for gravitational potential in astronomy.

### Key Features

- 🌊 **Spline-based stream modeling**: Smooth parametric representation of
  stellar streams with cubic spline interpolation
- 📐 **Curvature analysis**: Compute geometric properties including tangent
  vectors, curvature, principal normals, and arc-length
- 🌌 **Gravitational field fitting**: Match stream curvature to potential models
  with customizable halo and disk components
- ⚡ **JAX-accelerated**: Fast, GPU-compatible computations with automatic
  differentiation and JIT compilation
- 📊 **Likelihood framework**: Bayesian inference for potential parameters using
  curvature-acceleration alignment
- 📈 **Visualization tools**: Built-in plotting methods for tracks, geometry
  vectors, and gravitational fields

## Installation

### Using pip (recommended)

```bash
pip install potamides
```

### From source

```bash
git clone https://github.com/xggs-dev/potamides.git
cd potamides
uv pip install -e .
```

### Requirements

- Python >= 3.11
- JAX >= 0.5.3
- For GPU support, install JAX with CUDA support separately
- See `pyproject.toml` for full dependency list

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
for details.

## Acknowledgments

This package builds upon excellent open-source scientific software:

- **[JAX](https://github.com/google/jax)**: High-performance numerical computing
  with automatic differentiation
- **[galax](https://github.com/GalacticDynamics/galax)**: Galactic dynamics in
  JAX
- **[interpax](https://github.com/f0uriest/interpax)**: Interpolation library
  for JAX
- **[Astropy](https://www.astropy.org/)**: Community Python library for
  astronomy
- **[unxt](https://github.com/GalacticDynamics/unxt)**: Unitful quantities for
  JAX

## AI Usage Disclosure

Portions of this codebase (including tests and documentation) were refactored and generated with the assistance of Language Models. All AI contributions have been and will continue to be reviewed and verified by the human maintainers.

---

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/xggs-dev/potamides/workflows/CI/badge.svg
[actions-link]:             https://github.com/xggs-dev/potamides/actions
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/xggs-dev/potamides/discussions
[pypi-link]:                https://pypi.org/project/potamides/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/potamides
[pypi-version]:             https://img.shields.io/pypi/v/potamides
[rtd-badge]:                https://readthedocs.org/projects/potamides/badge/?version=latest
[rtd-link]:                 https://potamides.readthedocs.io/en/latest/?badge=latest

<!-- prettier-ignore-end -->
