potamides

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)

pip install potamides

From source

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

Requirements

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

Citation

If you use potamides in your research, please cite the JOSS paper:

@article{potamides,
  author = {Wu, Sirui and Starkman, Nathaniel and Nibauer, Jacob and Pearson, Sarah},
  title = {Potamides: JAX tools for curvature-based inference from stellar streams},
  journal = {Journal of Open Source Software},
  year = {2026},
  volume = {11},
  number = {126},
  pages = {10712},
  doi = {10.21105/joss.10712},
  url = {https://doi.org/10.21105/joss.10712}
}

Citation metadata is also available in CITATION.cff (GitHub's "Cite this repository" button).

Contributing

potamides is made for its users, so contributions of all kinds are welcome and encouraged. You do not need to write code to help: reporting a bug, suggesting a feature, improving the documentation, or sharing a scientific use case are all valuable.

See CONTRIBUTING.md for a full guide, including how to set up a development environment and run the tests. The easiest ways to get involved are through GitHub:

• Found a bug or have a feature request? Open an issue. Please include enough detail (a minimal example, error messages, and your environment) for us to reproduce the problem.
• Have a question or an idea to discuss? Start a thread in Discussions.
• Want to contribute code or documentation? Fork the repository, create a branch for your change, and open a pull request. If you are new to this workflow, GitHub's guide to contributing to projects is a good place to start, and we are happy to help you through the process.

By contributing, you agree to abide by our Code of Conduct.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This package builds upon excellent open-source scientific software:

• JAX: High-performance numerical computing with automatic differentiation
• galax: Galactic dynamics in JAX
• interpax: Interpolation library for JAX
• Astropy: Community Python library for astronomy
• 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.

---