How uataq/x-stilt works
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).