# benmsanderson/meteor architecture

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

- Interactive diagram: https://gitdiagram.com/benmsanderson/meteor
- Repository: https://github.com/benmsanderson/meteor

## Overview

##### Project type and purpose
- METEOR is a Python-based scientific library (“package”) for multivariate emulation of time-evolving climate responses.
- It provides core emulation functionality plus data-retrieval from CMIP6, a simple-climate-model wrapper, pattern-fitting routines, and plotting utilities.
- Users interact via Python scripts, CLI-style entry points (e.g., `meteor.py`), and Jupyter notebooks for demonstrations and figure generation.

##### File structure
- Top-level:
- src/meteor – core library modules
- notebooks/ – demonstration and paper-figure notebooks
- scripts/ – standalone example scripts
- tests/ – unit and integration tests, test data
- docs/ – documentation build files
- Makefile, setup.py, requirements.txt – build, install, and CI config
- Key modules in src/meteor:
- cmip6_meteor_data_getter.py – external CMIP6 data interface
- scm_forcer_engine.py – simple climate model wrapper for forcings
- prpatt.py – pattern fitting and convolution routines
- meteor.py – main control logic (entry point)
- meteor_plot_utils.py – plotting helpers
- default_scm_data/ – built-in data files for certain scenarios
- CI/CD: GitHub Actions workflows under .github/workflows.

##### README for additional insights
- Describes installation, development flow, testing commands, and high-level “General code flow”:
- meteor.py orchestrates control
- prpatt.py fits parameters & processes PDRMIP output
- scm_forcer_engine.py wraps simple climate model for forcing strength
- meteor_plot_utils.py for plots
- cmip6_meteor_data_getter.py for Xarray-backed CMIP6 access

1) User Interface Layer
– Jupyter Notebooks
– Scripts/CLI entry points (e.g., meteor.py, scripts/*.py)
2) Core Emulation Library
– Meteor Control Module (meteor.py)
– Pattern Fitting Module (prpatt.py)
– Forcing Engine Module (scm_forcer_engine.py)
– Plot Utilities Module (meteor_plot_utils.py)
3) Data Access Layer
– CMIP6 Data Getter (cmip6_meteor_data_getter.py) → external Zarr store
– Default SCM Data (built-in text files)
4) Testing & CI
– Unit Tests (tests/unit)
– Integration Tests (tests/integration)
– GitHub Actions (ci-cd-workflow.yml)
5) Build & Deployment
– Makefile targets & virtual-environment
– setup.py / setup.cfg for packaging
– User Interface Layer → invokes Core Emulation Library APIs
– Core Emulation Library → calls Data Access Layer for input datasets
– Forcing Engine may call external simple climate model code (via wrapper)
– Core modules produce outputs (time-series, patterns) → handed to Plot Utilities
– Plot Utilities → generate figures in notebooks or scripts
– Tests invoke modules to validate functionality
– CI workflow triggers build, tests, linting on GitHub push
c. Architectural patterns & design principles:
– Modular separation: data retrieval, computation, plotting, orchestration
– Layered architecture: UI → API → Data
– Dependency inversion: core modules depend on interfaces for data access
– Packaging best practices: setup.py, versioneer, continuous integration
d. Relevant technologies & libraries:
– Python ecosystem: Xarray, NumPy, SciPy, Matplotlib (via meteor_plot_utils)
– CMIP6 Zarr cloud storage API
– pytest for tests, versioneer for versioning, GitHub Actions for CI
– Makefile for environment management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        Notebook["Jupyter Notebooks"]:::ui
        ScriptCLI["CLI Entry (meteor.py)"]:::ui
        ExampleScripts["Example Scripts"]:::ui
    end

    %% Core Emulation Library
    subgraph "Core Emulation Library"
        MeteorControl["Meteor Control Module"]:::core
        PatternFitting["Pattern Fitting Module"]:::core
        ForcingEngine["Forcing Engine Module"]:::core
        PlotUtils["Plot Utilities Module"]:::core
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        CMIP6Getter["CMIP6 Data Getter"]:::data
        DefaultSCM["Default SCM Data"]:::data
        ExternalZarr["CMIP6 Zarr Store"]:::external
        ExternalSCMCode["External Simple Climate Model"]:::external
    end

    %% Testing & CI
    subgraph "Testing & CI"
        UnitTests["Unit Tests"]:::test
        IntegrationTests["Integration Tests"]:::test
        CIWorkflow["GitHub Actions Workflow"]:::test
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        MakefileNode["Makefile"]:::build
        Packaging["Packaging Config (setup.py, setup.cfg)"]:::build
    end

    %% Relationships
    Notebook -->|invokes| MeteorControl
    ScriptCLI -->|invokes| MeteorControl
    ExampleScripts -->|invokes| MeteorControl

    MeteorControl -->|calls| PatternFitting
    MeteorControl -->|calls| ForcingEngine
    MeteorControl -->|calls| PlotUtils
    MeteorControl -->|retrieves data via| CMIP6Getter
    MeteorControl -->|uses| DefaultSCM

    PatternFitting -->|outputs to| PlotUtils
    ForcingEngine -->|wraps| ExternalSCMCode
    ForcingEngine -->|outputs to| PlotUtils

    CMIP6Getter -->|fetches from| ExternalZarr
    DefaultSCM -->|built-in files| DefaultSCM

    UnitTests -->|tests| MeteorControl
    UnitTests -->|tests| PatternFitting
    UnitTests -->|tests| ForcingEngine
    UnitTests -->|tests| PlotUtils
    UnitTests -->|tests| CMIP6Getter

    IntegrationTests -->|validates| MeteorControl
    IntegrationTests -->|validates| PatternFitting
    IntegrationTests -->|validates| ForcingEngine

    CIWorkflow -->|runs| UnitTests
    CIWorkflow -->|runs| IntegrationTests
    CIWorkflow -->|triggers| MakefileNode
    CIWorkflow -->|triggers| Packaging

    MakefileNode -->|manages venv & targets| Packaging

    %% Click Events
    click Notebook "https://github.com/benmsanderson/meteor/tree/base/notebooks/"
    click ScriptCLI "https://github.com/benmsanderson/meteor/blob/base/src/meteor/meteor.py"
    click ExampleScripts "https://github.com/benmsanderson/meteor/tree/base/scripts/"
    click MeteorControl "https://github.com/benmsanderson/meteor/blob/base/src/meteor/meteor.py"
    click PatternFitting "https://github.com/benmsanderson/meteor/blob/base/src/meteor/prpatt.py"
    click ForcingEngine "https://github.com/benmsanderson/meteor/blob/base/src/meteor/scm_forcer_engine.py"
    click PlotUtils "https://github.com/benmsanderson/meteor/blob/base/src/meteor/meteor_plot_utils.py"
    click CMIP6Getter "https://github.com/benmsanderson/meteor/blob/base/src/meteor/cmip6_meteor_data_getter.py"
    click DefaultSCM "https://github.com/benmsanderson/meteor/tree/base/src/meteor/default_scm_data/"
    click UnitTests "https://github.com/benmsanderson/meteor/tree/base/tests/unit/"
    click IntegrationTests "https://github.com/benmsanderson/meteor/tree/base/tests/integration/"
    click CIWorkflow "https://github.com/benmsanderson/meteor/blob/base/.github/workflows/ci-cd-workflow.yml"
    click MakefileNode "https://github.com/benmsanderson/meteor/tree/base/Makefile"
    click Packaging "https://github.com/benmsanderson/meteor/blob/base/setup.py"

    %% Styles
    classDef ui fill:#b3e5fc,stroke:#0288d1,color:#0d47a1
    classDef core fill:#bbdefb,stroke:#1976d2,color:#0d47a1
    classDef data fill:#fff9c4,stroke:#f9a825,color:#f57f17
    classDef external fill:#ffcdd2,stroke:#e53935,color:#b71c1c
    classDef test fill:#e0e0e0,stroke:#757575,color:#424242
    classDef build fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
```
