# ebupi/astroariadne architecture

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

- Interactive diagram: https://gitdiagram.com/ebupi/astroariadne
- Repository: https://github.com/ebupi/astroariadne

## Overview

##### Project type and purpose
- astroARIADNE is an open-source Python library (package) whose primary purpose is to fit stellar spectral energy distributions (SEDs) using Bayesian model averaging over multiple atmosphere-model grids. It provides both a programmable API (importable modules) and command-line entry points via `setup.py`.

##### File structure
- Top-level files:
- `setup.py`, `requirements.txt`, `MANIFEST.in` – packaging and dependency specification
- `README.md`, `citations.md`, `customization.md`, `filters.md`, `LICENSE` – documentation & licensing
- `test_bma.py` – example/test script
- Core package directory `astroARIADNE/`:
- Data access & configuration: `config.py`, `error.py`, `utils.py`
- Datafiles subfolder: precomputed priors, model grids, lookup tables
- Domain modules:
– `star.py` (photometry retrieval, external catalog queries)
– `phot_utils.py` (filter definitions, photometric conversions)
– `sed_library.py` & `librarian.py` (model-grid loading and indexing)
– `fitter.py` (orchestration of nested sampling engines like `dynesty`/`PyMultiNest`, prior setup, likelihood evaluation)

##### External dependencies & services
- External services/APIs: Gaia cone‐search via `astroquery`, dust maps via `dustmaps`.
- Numerical & sampling libraries: `numpy`, `scipy`, `pandas`, `numba`, `dynesty` (optional `PyMultiNest`), `isochrones`.
- Visualization: `matplotlib`, `corner`, `tqdm`, `termcolor`.
- Data files: large model grids stored under `astroARIADNE/Datafiles/model_grids`.

##### Main components & their interactions
a. User/API entry point (script or REPL) → imports `astroARIADNE.star.Star`; sets RA/DEC/g_id → invokes photometry retrieval
b. Star object aggregates photometry, stellar priors (via Datafiles: `Template_prior.dat`, KDE/PPF pickles)
c. User configures `fitter.Fitter` with the Star instance, nested‐sampling settings, selected models, priors
d. Fitter calls `librarian`/`sed_library` to load atmosphere model grids from `Datafiles/model_grids` → synthesizes photometry through `phot_utils`
e. Likelihood evaluation and sampling: `dynesty` or optional `PyMultiNest` invoked inside `fitter`
f. Results I/O: Fitter writes out pickle files, `best_fit.dat`, `prior.dat`, `mags.dat`

##### Architectural patterns & design principles
- Layered modular design:
- Data‐Access Layer (Star, Librarian, Datafiles)
- Domain Logic Layer (Fitter, Isochrone)
- Presentation Layer (Plotter)
- Configuration & Utilities (config, utils, error)
- Pipeline / orchestrator pattern in `fitter.py`: orchestrates data retrieval, model evaluation, sampling
- Separation of concerns: photometry vs. modeling vs. plotting vs. I/O

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Entry
    User["User / Script Entry"]:::external

    %% astroARIADNE Package Boundary
    subgraph "astroARIADNE"
        direction TB

        subgraph "Data Access Layer"
            direction TB
            Star["Star & Photometry Retrieval"]:::coreBlue
            PhotUtils["Photometry Utilities"]:::coreBlue
            Librarian["Librarian (Grid Indexing)"]:::coreBlue
            SedLib["SED Library Loader"]:::coreBlue
            Isochrone["Isochrone Retrieval"]:::coreBlue
        end

        subgraph "Domain Logic Layer"
            direction TB
            Fitter["Fitter (Nested Sampling Orchestrator)"]:::coreBlue
        end

        subgraph "Presentation Layer"
            direction TB
            Plotter["Plotter (SED, Corner, HR)"]:::coreBlue
        end

        subgraph "Config & Utilities"
            direction TB
            Config["Configuration & Defaults"]:::coreBlue
            Utils["Utilities & Helpers"]:::coreBlue
            Error["Error Handling & Exceptions"]:::coreBlue
        end
    end

    %% External Services & Libraries
    Gaia["Gaia Cone-Search"]:::external
    Dustmaps["Dustmaps Service"]:::external
    IsoPkg["Isochrones Package"]:::external
    SamplingEng["dynesty / PyMultiNest"]:::external

    %% Datafiles
    subgraph "Datafiles" 
        direction TB
        TemplatePrior["Template_prior.dat"]:::data
        PriorsPKL["KDE/PPF Priors (*.pkl)"]:::data
        ModelGridPKL["Model Grids Pickles (*.pkl)"]:::data
        ModelGridDAT["Model Grids Tables (*.dat)"]:::data
        PlotSettings["Plot Settings (plot_settings.dat)"]:::data
    end

    %% File System I/O
    ResultsFS["Results Folder (.pkl/.dat)"]:::io
    PlotsFS["Plots Folder (images)"]:::io

    %% Connections
    User -->|"import Star; set RA/DEC"| Star
    Star -->|"cone-search"| Gaia
    Star -->|"dust query"| Dustmaps
    Star -->|"aggregate photometry & priors"| Fitter

    Fitter -->|"load grids"| Librarian
    Librarian -->|"index grids"| SedLib
    SedLib -->|"read pickles/dat"| ModelGridPKL
    SedLib -->|"read pickles/dat"| ModelGridDAT
    SedLib -->|"synthesize photometry"| PhotUtils
    PhotUtils -->|"pass synthetic photometry"| Fitter

    Fitter -->|"run sampling"| SamplingEng
    SamplingEng -->|"samples & likelihood"| Fitter

    Fitter -->|"write results"| ResultsFS
    Plotter -->|"read results & grids"| ResultsFS
    Plotter -->|"generate plots"| PlotsFS

    %% Isochrone external
    Star -->|"isochrone query"| IsoPkg
    IsoPkg -->|"isochrone data"| Isochrone
    Isochrone -->|"provide isochrones"| Fitter

    %% Config & Utils usage
    Fitter -->|"use defaults"| Config
    Star -->|"use utils & error"| Utils
    Fitter -->|"error handling"| Error

    %% Click Events
    click Star "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/star.py"
    click SedLib "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/sed_library.py"
    click Librarian "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/librarian.py"
    click Fitter "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/fitter.py"
    click Plotter "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/plotter.py"
    click Isochrone "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/isochrone.py"
    click PhotUtils "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/phot_utils.py"
    click Config "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/config.py"
    click Utils "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/utils.py"
    click Error "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/error.py"
    click TemplatePrior "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/Datafiles/Template_prior.dat"
    click PriorsPKL "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/Datafiles/prior/*.pkl"
    click ModelGridPKL "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/Datafiles/model_grids/*.pkl"
    click ModelGridDAT "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/Datafiles/model_grids/*.dat"
    click PlotSettings "https://github.com/ebupi/astroariadne/blob/master/astroARIADNE/Datafiles/plot_settings.dat"

    %% Styles
    classDef coreBlue fill:#DDEEFF,stroke:#0000FF
    classDef external fill:#DDFFDD,stroke:#00AA00
    classDef data fill:#FFE5CC,stroke:#CC6600
    classDef io fill:#F0F0F0,stroke:#999999
```
