# fireflyspectra/firefly_release architecture

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

- Interactive diagram: https://gitdiagram.com/fireflyspectra/firefly_release
- Repository: https://github.com/fireflyspectra/firefly_release

## Overview

##### Project type and purpose
- This is a scientific, command-line Python package (“FIREFLY”) for fitting stellar population spectral models to astronomical data (galaxies, star clusters).
- Purpose: read observed or simulated spectra, load template SSP (single-stellar-population) models and auxiliary files (dust maps, masks, mass-loss tables), perform iterative χ² minimisation fitting, and output stellar population properties (age, metallicity, E(B–V), mass, SFH, etc.).

##### File structure
Top-level directories:
- run/        → CLI entry-point scripts for different data sources (generic, SDSS, MaNGA) plus a reader for outputs
- python/     → core FIREFLY library modules (constants, dust handling, instrument setup, models, fitter, SF rate, estimations, setup)
- data/       → small auxiliary lookup files (dust maps, sky masks, mass-loss tables, resolution data)
- example_data/ → sample input spectra (ASCII, FITS) for testing
- stellar_population_models/ → heavyweight library of SSP templates (M11 Élodie, MILES, MARCS and MaStar)

##### README for additional insights
- Dependencies: numpy, scipy, matplotlib, astropy
- Usage: set environment variables (FF_DIR, PYTHONPATH, STELLARPOPMODELS_DIR) or rely on default relative paths
- Run commands:
- python run/firefly.py  (generic)
- python run/firefly_sdss.py
- python run/firefly_manga.py
- Output reading: python run/read_firefly.py

##### Main components and their interactions
a. Components
1) CLI layer (“run/”)
2) Core library (“python/” modules)
3) Auxiliary data (“data/”)
4) Model templates (“stellar_population_models/”)
5) Example inputs (“example_data/”)
6) External libraries (NumPy, SciPy, Astropy, Matplotlib)
b. Relationships & data flow
- User invokes a script in run/ → it sets up environment & parameters → imports python/ modules
- python/firefly_setup.py locates data/ and stellar_population_models/
- python/firefly_instrument.py and python/firefly_dust.py load instrument resolution files and dust filter procedures from data/
- python/firefly_models.py loads SSP templates from stellar_population_models/
- python/firefly_fitter.py orchestrates the iterative χ² minimisation, calling constants, dust, instrument, models, library, estimations, SF rate modules
- python/firefly_estimations_3d.py and python/firefly_star_formation_rate.py compute derived properties and SFH
- Output files written (ASCII or FITS) to working directory
- run/read_firefly.py reads and parses output for analysis/plotting
c. Architectural patterns/principles
- Layered CLI → library → data
- Single-responsibility modules (dust, instrument, models, fitter, estimations)
- Directory-based configuration (environment variables or defaults)
- No external services; all local file I/O
d. Key technologies/frameworks
- Python 3 modular package
- Astro-specific I/O via Astropy (FITS)
- Numerical work via NumPy/SciPy
- Visualization via Matplotlib

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User / CLI"]:::user

    %% CLI Entry Points
    subgraph "CLI Entry Points" 
        direction TB
        FIRE["firefly.py"]:::cli
        FIRE_SDSS["firefly_sdss.py"]:::cli
        FIRE_MANGA["firefly_manga.py"]:::cli
        READ_OUT["read_firefly.py"]:::cli
    end

    %% Core Library Modules
    subgraph "Core Library Modules"
        direction TB
        SETUP["firefly_setup.py"]:::core
        INSTRUMENT["firefly_instrument.py"]:::core
        DUST["firefly_dust.py"]:::core
        CONST["firefly_constants.py"]:::core
        MODELS["firefly_models.py"]:::core
        LIB["firefly_library.py"]:::core
        FITTER["firefly_fitter.py\n(iterative χ² loop)"]:::core
        EST["firefly_estimations_3d.py"]:::core
        SFR["firefly_star_formation_rate.py"]:::core
    end

    %% Data Assets
    subgraph "Auxiliary Data" 
        direction TB
        RES["MaNGA_spectral_resolution.txt"]:::data
        DUST1["SFD_dust_4096_ngp.fits"]:::data
        DUST2["SFD_dust_4096_sgp.fits"]:::data
        MASK1["dr12-sky-mask.txt"]:::data
        MASK2["dr12-sky-mask.readme"]:::data
        ML1["massloss_chabrier.txt"]:::data
        ML2["massloss_kroupa.txt"]:::data
        ML3["massloss_salpeter.txt"]:::data
    end

    subgraph "Example Input Spectra"
        direction TB
        SPEC_ASCII["spec-0266-51602-0001.dat"]:::data
        SPEC_FITS["spec-0266-51602-0001.fits"]:::data
        SPEC_MANGA["manga/*.fits\n*.fits.gz"]:::data
    end

    %% Model Templates
    subgraph "Stellar Population Models"
        direction TB
        EMILES["EMILES_SSP/"]:::models
        MASTAR02["MaStar_SSP_v0.2.fits.gz"]:::models
        MASTAR11["MaStar_SSP_v1.1.fits.gz"]:::models
        ELODIE["SSP_M11_ELODIE/"]:::models
        MARCS["SSP_M11_MARCS/"]:::models
        MILES["SSP_M11_MILES/"]:::models
        MILES_SG["SSP_M11_MILES_SG/"]:::models
        STELIB["SSP_M11_STELIB/"]:::models
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        NUMPY["NumPy"]:::external
        SCIPY["SciPy"]:::external
        ASTROPY["Astropy"]:::external
        MPL["Matplotlib"]:::external
    end

    %% Output
    OUTPUT["Output Files\n(ASCII / FITS)"]:::output

    %% Flows
    User --> FIRE
    User --> FIRE_SDSS
    User --> FIRE_MANGA
    FIRE --> SETUP
    FIRE_SDSS --> SETUP
    FIRE_MANGA --> SETUP
    SETUP -.-> RES
    SETUP -.-> DUST1
    SETUP -.-> DUST2
    SETUP --> INSTRUMENT
    SETUP --> DUST
    SETUP --> CONST

    INSTRUMENT --> RES
    DUST --> DUST1
    DUST --> DUST2
    MODELS --> EMILES
    MODELS --> MASTAR02
    MODELS --> MASTAR11
    MODELS --> ELODIE
    MODELS --> MARCS
    MODELS --> MILES
    MODELS --> MILES_SG
    MODELS --> STELIB

    FIRE --> SPEC_ASCII
    FIRE --> SPEC_FITS
    FIRE_MANGA --> SPEC_MANGA

    INSTRUMENT --> FITTER
    DUST --> FITTER
    CONST --> FITTER
    MODELS --> FITTER
    LIB --> FITTER
    EST --> FITTER
    SFR --> FITTER

    FITTER --> OUTPUT
    OUTPUT --> READ_OUT
    User --> READ_OUT

    %% External libs to core
    NUMPY --> FITTER
    SCIPY --> FITTER
    ASTROPY --> SETUP
    ASTROPY --> FITTER
    MPL --> READ_OUT

    %% Click events
    click FIRE "https://github.com/fireflyspectra/firefly_release/blob/master/run/firefly.py"
    click FIRE_SDSS "https://github.com/fireflyspectra/firefly_release/blob/master/run/firefly_sdss.py"
    click FIRE_MANGA "https://github.com/fireflyspectra/firefly_release/blob/master/run/firefly_manga.py"
    click READ_OUT "https://github.com/fireflyspectra/firefly_release/blob/master/run/read_firefly.py"

    click SETUP "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_setup.py"
    click INSTRUMENT "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_instrument.py"
    click DUST "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_dust.py"
    click CONST "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_constants.py"
    click MODELS "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_models.py"
    click LIB "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_library.py"
    click FITTER "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_fitter.py"
    click EST "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_estimations_3d.py"
    click SFR "https://github.com/fireflyspectra/firefly_release/blob/master/python/firefly_star_formation_rate.py"

    click RES "https://github.com/fireflyspectra/firefly_release/blob/master/data/MaNGA_spectral_resolution.txt"
    click DUST1 "https://github.com/fireflyspectra/firefly_release/blob/master/data/SFD_dust_4096_ngp.fits"
    click DUST2 "https://github.com/fireflyspectra/firefly_release/blob/master/data/SFD_dust_4096_sgp.fits"
    click MASK1 "https://github.com/fireflyspectra/firefly_release/blob/master/data/dr12-sky-mask.txt"
    click MASK2 "https://github.com/fireflyspectra/firefly_release/blob/master/data/dr12-sky-mask.readme"
    click ML1 "https://github.com/fireflyspectra/firefly_release/blob/master/data/massloss_chabrier.txt"
    click ML2 "https://github.com/fireflyspectra/firefly_release/blob/master/data/massloss_kroupa.txt"
    click ML3 "https://github.com/fireflyspectra/firefly_release/blob/master/data/massloss_salpeter.txt"

    click SPEC_ASCII "https://github.com/fireflyspectra/firefly_release/blob/master/example_data/spec-0266-51602-0001.dat"
    click SPEC_FITS "https://github.com/fireflyspectra/firefly_release/blob/master/example_data/spec-0266-51602-0001.fits"
    click SPEC_MANGA "https://github.com/fireflyspectra/firefly_release/tree/master/example_data/"

    click EMILES "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/EMILES_SSP/"
    click MASTAR02 "https://github.com/fireflyspectra/firefly_release/blob/master/stellar_population_models/MaStar_SSP_v0.2.fits.gz"
    click MASTAR11 "https://github.com/fireflyspectra/firefly_release/blob/master/stellar_population_models/MaStar_SSP_v1.1.fits.gz"
    click ELODIE "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/SSP_M11_ELODIE/"
    click MARCS "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/SSP_M11_MARCS/"
    click MILES "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/SSP_M11_MILES/"
    click MILES_SG "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/SSP_M11_MILES_SG/"
    click STELIB "https://github.com/fireflyspectra/firefly_release/tree/master/stellar_population_models/SSP_M11_STELIB/"

    %% Styles
    classDef user fill:#A0D3E8,stroke:#333,stroke-width:1px
    classDef cli fill:#9AC8EB,stroke:#333,stroke-width:1px
    classDef core fill:#A8E6A3,stroke:#333,stroke-width:1px
    classDef data fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef models fill:#F5B041,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef output fill:#D2B4DE,stroke:#333,stroke-width:1px
```
