How adrn/gala works
Project type and purpose
• Gala is a Python package for galactic and gravitational dynamics.
• It provides coordinate transforms, dynamical solvers, orbit integrators, and potential evaluators.
File structure
• Top-level “gala/” directory contains the Python API and sub-packages:
• coordinates
• dynamics
• integrate
• potential
• units, io, logging, util
• Many sub-packages include Cython wrappers (.pyx/.pxd) around C/C++ code in “src/” folders.
• There are “tests/” folders under each sub-package for unit tests.
• Project tooling: setup.py, pyproject.toml, CI workflows in .github/workflows, documentation in docs/, Read the Docs integration.
README
• Describes installation, dependencies (numpy, astropy, etc.), docs location on Read the Docs.
a. Main components
• Public API Layer (gala/__init__.py)
• Sub-packages (modules):
– Coordinates
– Dynamics
– Integrate
– Potential
– Units, IO, Logging, Util
• Cython/C++ extension modules under each sub-package
• Third-party dependencies (NumPy, Astropy)
• Packaging & Distribution (setup.py, PyPI/Conda)
• Documentation Site (Read the Docs)
• Continuous Integration (GitHub Actions, Codecov)
b. Relationships & data flow
• User code → imports gala API → calls coordinate transforms
• API delegates to pure-Python routines or Cython wrappers → which call underlying C/C++ kernels → return NumPy arrays
• Dynamics module depends on Potential module (to compute forces)
• Integrate module uses Dynamics (to get derivatives)
• Units module underpins all numeric sub-packages for quantity support
• IO/logging modules provide data persistence and diagnostics
• Tests invoke each component in isolation
• CI pipelines run tests, coverage, and documentation builds
• Publishing pipelines push packages to PyPI and conda-forge
c. Architectural patterns and design principles
• Layered architecture (API → core Python logic → C/C++ kernels)
• Modular separation (each physical concept in its own sub-package)
• Wrapping critical performance kernels via Cython
• Dependency injection via standardized interfaces (e.g., passing potentials into dynamics)
d. Key technologies & frameworks
• Python 3.x
• Cython for performance wrappers
• C/C++ code for numerics
• NumPy & Astropy for core data structures
• setuptools & pyproject.toml for packaging
• Sphinx/ReadTheDocs for docs
• GitHub Actions for CI