# adrn/gala architecture

> Architecture diagram of the GitHub repository adrn/gala, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adrn/gala
- Repository: https://github.com/adrn/gala

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layers
    PublicAPI["gala/__init__.py"]:::python
    subgraph "Sub-packages"
        Coordinates["gala.coordinates"]:::python
        Dynamics["gala.dynamics"]:::python
        Integrate["gala.integrate"]:::python
        Potential["gala.potential"]:::python
    end
    PublicAPI --> Coordinates
    PublicAPI --> Dynamics
    PublicAPI --> Integrate
    PublicAPI --> Potential
    Dynamics --> Potential
    Integrate --> Dynamics

    %% Performance Extension Layer
    subgraph "Cython/C++ Extension Layer"
        CConfig["cconfig (Cython)"]:::cython
        IntExt["Integrators (Cython)"]:::cython
        PFExt["Potential/Frame (Cython)"]:::cython
        PHExt["Potential/Hamiltonian (Cython)"]:::cython
        PBExt["Potential/Builtin (Cython)"]:::cython
        SCFExt["Potential/SCF (Cython)"]:::cython

        CConfig_SRC["cconfig src (C/C++)"]:::ccode
        IntExt_SRC["integrate/cyintegrators/src (C/C++)"]:::ccode
        PFExt_SRC["potential/frame/src (C/C++)"]:::ccode
        PHExt_SRC["potential/hamiltonian/src (C/C++)"]:::ccode
        PBExt_SRC["potential/potential/src (C/C++)"]:::ccode
        SCFExt_SRC["potential/scf/src (C/C++)"]:::ccode
    end
    Integrate --> IntExt
    Potential --> PFExt
    Potential --> PHExt
    Potential --> PBExt
    Potential --> SCFExt

    CConfig --> CConfig_SRC
    IntExt --> IntExt_SRC
    PFExt --> PFExt_SRC
    PHExt --> PHExt_SRC
    PBExt --> PBExt_SRC
    SCFExt --> SCFExt_SRC

    %% Common Utilities
    subgraph "Common Utilities"
        Units["gala/units.py"]:::python
        IO["gala/io.py"]:::python
        Logging["gala/logging.py"]:::python
        Util["gala/util.py & _compat_utils.py"]:::python
    end
    Coordinates --> Units
    Dynamics --> Units
    Integrate --> Units
    Potential --> Units
    Coordinates --> IO
    Dynamics --> Logging

    %% Tools & Infrastructure
    subgraph "Tools & Infrastructure"
        Packaging["Packaging"]:::external
        CI["Continuous Integration"]:::external
        DocsSrc["Documentation Source"]:::external
        PyPI["PyPI/Conda Distribution"]:::external
        ReadTheDocs["ReadTheDocs"]:::external
        Tests["Test Suites"]:::external
    end
    CI --> Tests
    Tests --> Coordinates
    Tests --> Dynamics
    Tests --> Integrate
    Tests --> Potential
    CI --> DocsSrc
    DocsSrc --> ReadTheDocs
    Packaging --> PyPI
    CI --> Packaging

    %% Click Events
    click PublicAPI "https://github.com/adrn/gala/blob/main/gala/__init__.py"
    click Coordinates "https://github.com/adrn/gala/tree/main/gala/coordinates/"
    click Dynamics "https://github.com/adrn/gala/tree/main/gala/dynamics/"
    click Integrate "https://github.com/adrn/gala/tree/main/gala/integrate/"
    click Potential "https://github.com/adrn/gala/tree/main/gala/potential/"
    click Units "https://github.com/adrn/gala/blob/main/gala/units.py"
    click IO "https://github.com/adrn/gala/blob/main/gala/io.py"
    click Logging "https://github.com/adrn/gala/blob/main/gala/logging.py"
    click CConfig "https://github.com/adrn/gala/blob/main/gala/cconfig.pyx"
    click CConfig "https://github.com/adrn/gala/blob/main/gala/_cconfig.pxd"
    click IntExt "https://github.com/adrn/gala/tree/main/gala/integrate/cyintegrators/"
    click PFExt "https://github.com/adrn/gala/tree/main/gala/potential/frame/"
    click PFExt_SRC "https://github.com/adrn/gala/tree/main/gala/potential/frame/src/"
    click PHExt "https://github.com/adrn/gala/blob/main/gala/potential/hamiltonian/chamiltonian.pyx"
    click PHExt_SRC "https://github.com/adrn/gala/tree/main/gala/potential/hamiltonian/src/"
    click PBExt "https://github.com/adrn/gala/tree/main/gala/potential/potential/"
    click PBExt_SRC "https://github.com/adrn/gala/tree/main/gala/potential/potential/src/"
    click SCFExt "https://github.com/adrn/gala/tree/main/gala/potential/scf/"
    click SCFExt_SRC "https://github.com/adrn/gala/tree/main/gala/potential/scf/src/"
    click Util "https://github.com/adrn/gala/blob/main/gala/util.py"
    click Util "https://github.com/adrn/gala/blob/main/gala/_compat_utils.py"
    click Packaging "https://github.com/adrn/gala/blob/main/setup.py"
    click Packaging "https://github.com/adrn/gala/blob/main/pyproject.toml"
    click CI "https://github.com/adrn/gala/tree/main/.github/workflows/"
    click DocsSrc "https://github.com/adrn/gala/tree/main/docs/"
    click DocsSrc "https://github.com/adrn/gala/blob/main/.readthedocs.yml"

    %% Styles
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cython fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ccode fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
```
