# uataq/x-stilt architecture

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

- Interactive diagram: https://gitdiagram.com/uataq/x-stilt
- Repository: https://github.com/uataq/x-stilt

## Overview

This repository is for a specialized atmospheric transport model called X‐STILT, which extends the traditional STILT system to simulate vertically integrated column concentrations of trace gases (e.g., XCO₂, CH₄, CO, NO₂) by processing both satellite observations and ideal simulated datasets. The design of this system is complex, integrating trajectory modeling, error estimation, data input/output management, and visualization components.

##### Project Type and Purpose
- The project is a scientific modeling tool used for atmospheric tracer simulation, column footprint generation, and error estimation in greenhouse gases, used in inversion studies.
- Primary goals include running backward and forward trajectories, processing satellite observations (OCO, TROPOMI, TCCON), and performing uncertainty/error analyses.
- Technologies include R scripts for numerical modeling, Fortran binaries (e.g., the HYSPLIT executable in the “exe” folder), and support for geospatial file formats (GeoTIFF, shapefiles).

##### File Structure
- Core Codebase (r/): Contains most of the R-source files structured into logical modules. Subdirectories like “background”, “chem_lifetime”, “column_obs”, “plotting”, “recp_trajec_foot”, and “error_functions” indicate modular design based on functional areas (e.g., chromatographic error calculations, trajectory simulations, plotting, and data loading).
- Data Directory (data/): Holds input datasets including remote sensing data (ODIAC, EDGAR inventories), shapefiles (world borders), and preprocessed RDS files. This is the input layer for simulation and post-processing.
- Executable Directory (exe/): Contains key binaries like the HYSPLIT/ STILT model executable (hymodelc.aer)—critical for simulation of trajectories.
- Supportive Files: README.md, HISTORY.md, and dependency/setup files (e.g., r/dependencies.r) provide installation instructions and version changes, while files like receptor_demo.csv offer example input data.

##### Main Components
A. Frontend / User Input:
- Scripts for Running Simulations: Files like run_xstilt.r, run_sim_multi.r, run_xstilt_tccon.r, and compute_bg.r are the primary entry points.
- Receptor and Observation Data: A CSV file (receptor_demo.csv) and satellite observation files are provided as user inputs.

B. Core Simulation Engine:
- Trajectory Generation: Incorporate modules from r/src/background and r/src/recp_trajec_foot that handle backward and forward trajectory simulations.
- Atmospheric Chemical & Error Processing: Represent the “chem_lifetime” and “error_functions” modules, which compute background signals, propagate transport errors (wind/PBL uncertainties), and simulate differences in tracer columns.
- Data Loading and Preprocessing: Include components in r/src/column_obs (for OCO, TROPOMI, and TCCON data retrieval) to capture observation data and pre-process it.

C. External Engine Interaction:

D. Data and Configuration Management:
- Data Files and Inventories: The “data” directory holds critical inputs like emission inventories (ODIAC, EDGARv6), geographical boundaries (shapefiles), and supplemental data (e.g., nox_curves, tau data).
- Configuration and Dependency Scripts: Files in r/dependencies.r, r/src/config_xstilt.r, and numerous parameter settings in the main scripts indicate how simulation parameters and model configuration are managed.

E. Output / Visualization:
- Plotting and Post-Processing: The “figs” folder along with r/src/plotting scripts are used to generate maps, plume plots, and uncertainty visualizations.

##### Relationships and Interactions
- Data Flow: Start from user inputs (receptor CSVs, satellite data, met fields) → configuration and parameter setup → trajectory simulation (via R scripts calling Fortran executable) → processing of column footprints and tracer concentrations → error estimation modules → visualization and reporting (in the figs and plotting modules).
- Dependencies: Show that the R modules depend on external meteorological and inventory datasets, and the Fortran binary is a core dependency invoked by R.

##### Architectural Patterns and Design Principles
- Data Processing Pipeline: Illustrate the flow from raw input (satellite and meteorological data) through simulation, error propagation, and final visualization.
- Integration of Legacy Code: Note the integration of Fortran-based models with R scripts, suggesting a mixed-language architecture.

##### Elements
- User input → parameter configuration → simulation engine (both backward and forward trajectory modules).
- Simulation engine → error estimation → visualization.
- External calls from R scripts to the Fortran engine and back.
- Notes indicating key technologies (R, Fortran) and important libraries (e.g., ggplot2 for plotting, spatial libraries for geospatial data).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Subgraph: User Input & Configuration
    subgraph "User Input & Configuration"
        UI1["run_xstilt.r"]:::rmodule
        UI2["run_sim_multi.r"]:::rmodule
        UI3["run_xstilt_tccon.r"]:::rmodule
        UI4["compute_bg.r"]:::rmodule
        UI5["receptor_demo.csv"]:::rmodule
        UI6["r/dependencies.r"]:::rmodule
        UI7["r/src/config_xstilt.r"]:::rmodule
    end

    %% Subgraph: Trajectory Simulation Engine
    subgraph "Trajectory Simulation Engine"
        TS1["r/src/background"]:::rmodule
        TS2["r/src/recp_trajec_foot"]:::rmodule
    end

    %% Subgraph: Atmospheric Chemical & Error Processing
    subgraph "Atmospheric Chemical & Error Processing"
        AC1["r/src/chem_lifetime"]:::rmodule
        AC2["r/src/error_functions"]:::rmodule
    end

    %% Subgraph: Data Loading & Preprocessing (Column Observations)
    subgraph "Data Loading & Preprocessing"
        DL1["r/src/column_obs"]:::rmodule
    end

    %% Subgraph: External Fortran Executable Integration
    subgraph "External Fortran Executable"
        EX1["exe/hymodelc.aer"]:::external
    end

    %% Subgraph: Data and Inventory Management
    subgraph "Data and Inventory Management"
        DM1["data"]:::data
    end

    %% Subgraph: Output & Visualization
    subgraph "Output & Visualization"
        OV1["r/src/plotting"]:::rmodule
        OV2["r/src/chem_lifetime/plotting_functions"]:::rmodule
        OV3["figs"]:::data
    end

    %% Data Flow Connections
    UI1 -->|"sets parameters"| TS1
    UI2 -->|"sets parameters"| TS1
    UI3 -->|"sets parameters"| TS1
    UI4 -->|"sets parameters"| TS1
    UI5 -->|"provides receptor data"| TS1
    UI5 -->|"provides receptor data"| DL1
    UI6 -->|"configures simulation"| TS1
    UI7 -->|"configures simulation"| TS1

    DM1 -->|"supplies inventories & geodata"| TS1
    DM1 -->|"supplies inventories & geodata"| DL1

    TS1 -->|"trigger trajectories"| EX1
    TS1 -->|"passes simulation output"| AC1
    TS1 -->|"passes simulation output"| DL1

    AC1 -->|"error estimation"| AC2
    AC2 -->|"refines data"| OV1

    DL1 -->|"preprocessed observations"| OV1

    TS1 -->|"simulation results"| OV1
    EX1 -->|"trajectory data"| TS1

    OV1 -->|"visual plots"| OV3
    OV2 -->|"visual plots"| OV3

    %% Click Events for User Input & Configuration
    click UI1 "https://github.com/uataq/x-stilt/blob/master/run_xstilt.r"
    click UI2 "https://github.com/uataq/x-stilt/blob/master/run_sim_multi.r"
    click UI3 "https://github.com/uataq/x-stilt/blob/master/run_xstilt_tccon.r"
    click UI4 "https://github.com/uataq/x-stilt/blob/master/compute_bg.r"
    click UI5 "https://github.com/uataq/x-stilt/blob/master/receptor_demo.csv"
    click UI6 "https://github.com/uataq/x-stilt/blob/master/r/dependencies.r"
    click UI7 "https://github.com/uataq/x-stilt/blob/master/r/src/config_xstilt.r"

    %% Click Events for Trajectory Simulation Engine
    click TS1 "https://github.com/uataq/x-stilt/tree/master/r/src/background"
    click TS2 "https://github.com/uataq/x-stilt/tree/master/r/src/recp_trajec_foot"

    %% Click Events for Atmospheric Chemical & Error Processing
    click AC1 "https://github.com/uataq/x-stilt/tree/master/r/src/chem_lifetime"
    click AC2 "https://github.com/uataq/x-stilt/tree/master/r/src/error_functions"

    %% Click Events for Data Loading & Preprocessing
    click DL1 "https://github.com/uataq/x-stilt/tree/master/r/src/column_obs"

    %% Click Events for External Fortran Executable Integration
    click EX1 "https://github.com/uataq/x-stilt/blob/master/exe/hymodelc.aer"

    %% Click Events for Data and Inventory Management
    click DM1 "https://github.com/uataq/x-stilt/tree/master/data"

    %% Click Events for Output & Visualization
    click OV1 "https://github.com/uataq/x-stilt/tree/master/r/src/plotting"
    click OV2 "https://github.com/uataq/x-stilt/tree/master/r/src/chem_lifetime/plotting_functions"
    click OV3 "https://github.com/uataq/x-stilt/tree/master/figs"

    %% Styles
    classDef rmodule fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef data fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
```
