Skip to content
/ X-STILT Public

Source codes for X-STILT(NOx) [Wu et al., 2018, 2023] based on STILT-R version 2 [Fasoli et al., 2018] and STILT [Lin et al., 2003].

Notifications You must be signed in to change notification settings

uataq/X-STILT

Repository files navigation

X-STILT: Column-Stochastic Time-Inverted Lagrangian Transport model

X-STILT is an atmospheric transport model that deals with vertically integrated column concentrations of various trace gases (Wu et al., 2018, 2023). The model code was built upon the Stochastic Time-Inverted Lagrangian Transport (STILT) model (Lin et al., 2003) and its latest version 2 (Fasoli et al., 2018).

The model framework can now work with

  1. OCO-2&3 XCO2;
  2. TROPOMI column CO (Wu et al., 2022), CH4 (Li et al., 2024); and NO2 (Wu et al., 2023: STILT-NOx);
  3. TCCON column CO2, CO, N2O, CH4 (check out run_xstilt_tccon.r);
  4. EM27/SUN (under construction...);
  5. ideal column simulations without involving a specific satellite is doable (though no satellite AK applied to footprint calculation). 😎

This GitHub repo includes built-in scripts/functions for

  1. running backward trajectories from an atmospheric column and column footprint (start with run_xstilt.r for either initial X-STILT or updated STILT-NOx);
  2. running forward-time trajectories from a box around the site and compute background from satellite observations (start with compute_bg.r);
  3. estimating wind and PBL uncertainties and translating those into XCO2 uncertainties (start with run_xstilt.r)
  4. simulating column CO2, CO, CH4, and NO2 abundances at OCO-2/3 and TROPOMI soundings (STILT-NOx, start with run_sim_multi.r)

Bugs are preferred to be reported by submitting a pull request. Please check out Tips for debugging section first. If no luck, please describe your error message and provide insights on any changes you made for your specific receptor location/time/type of obs/species chosen. Model developments are ongoing and contributions are welcomed/appreciated. 💫

X-STILT Features

Table of Contents

Download and install model

  • As STILT-R version 2 now serves as a submodule of X-STILT, you will need to use the git command to download the entire model packages including the underlying STILTv2 and HYSPLITv5:
git clone --recursive https://github.com/uataq/X-STILT.git
  • To automatically install all R packages (requiring R > 3.5.0) and the STILTv2 model with the fortran program for HYSPLITv5, start with the first few lines of run_xstilt.r.

  • Required datasets and methodologies are described in prerequisites and Wu et al., 2018. Please refer to the reference section if you plan to publish any study using the (X-)STILT model.

Prerequisites

  1. For SATELLITE-dependent column simulation -

    • download OCO-2 Lite or TROPOMI Level 2 files and modify the corresponding parameters including obs_sensor, obs_ver, obs_species, oco_path, or trp_path.
    • X-STILT reads in averaging kernels from satellite files but calculates its own pressure weighting functions to perform vertical weighting on footprint values for air parcels that releases from different altitudes and then provide the vertically compressed column footprints.
  2. For IDEAL column simulation WITHOUT satellite dependence -

    • prepare a csv file for receptor lon, lat, and time. An example is provided as in receptor_demo.csv. Check out instructions in recent commit.
  3. Meteorological fields in ARL format, e.g., ones provided by NOAA ARL, and modify the section on ARL format meteo params. One need to perform ARL conversion, e.g., when using WRF as the met fields.

  4. (OPTIONAL) For calculating column enhancements [in ppm] -

    • choose your favourite emission inventories. The default is to use ODIAC for fossil fuel emission representation; so download 1 km ODIAC files in tif format and modify odiac_path.
  5. (OPTIONAL) For performing transport error analyses -

  6. (OPTIONAL) For performing emission error analyses -

    • Bottom-up emission inventories ensemble FFDAS and EDGAR.

Obtain column footprint

Column Footprints [ppm / (umol m-2 s-1)] are the source-receptor sensivities or essentially the Jacobian Matrics between concentration (enhancements) and fluxes (for a given source/sink). Users can start with run_xstilt.r for model and parameter initializations.

  1. Select a satellite overpass. Either by a manual insertion Or an automatic search. By default, STEP 1 searches for all overpasses that have soundings falling into a spatial domain (e.g., 2 deg x 2 deg) as well as a near-field domain (i.e., 0.6 deg x 0.6 deg).

  2. Select the kind of simulation one would like to conduct in STEP 2. One needs to modify logical flags which included:

    • run_trajec = T or run_foot = T: Backward trajectories + vertically weighted column footprints;
    • run_hor_err = T: Horizontal transport error analysis (one needs to calculate wind error statistics first, see below);
    • run_wind_err = T: Modeled wind error estimates against radiosonde data (one need to download them from NOAA webpage first);
    • run_ver_err = T: Vertical transport error analysis (via scaling mixed layer height up and down with scaling factors stated in STEP 4);
    • run_sim = T: Simulate FFCO2 XCO2 enhancements (requires footprint), remember to turn off run_trajec and run_foot;
    • run_emiss_err = T: Prior emission error analysis (requires footprint).
  3. Modify parameters for placing column receptors (e.g., max height and vertical spacing between two vertical levels in meters, # of particles per level, receptor locations). By default, X-STILT chooses more receptors within NEAR-FIELD area, see STEP 3.

  4. Modify meteorological fields, STEP 4. See STILT documentation for more explanations.

  5. Modify horizontal resolution and spatial extent of footprint, STEP 5.

    • X-STILT can generate multiple sets of footprints based on the same set of trajectory in one simulation (hourly-integrated or hourly-explicit footprints). For generating a second or third set of footprints, modify these params.
  6. Set up SLURM parallel computing, STEP 6.

Determine background XCO2

Start with main script of compute_bg.r. M3 is the overpass specific background [ppm] by releasing air parcels in a forward fashion from a city and determining urban plume and background region using 2D kernel density. Please refer to details described in Sect. 2.3 in Wu et al. (2018).

  • run_trajec = T: calculate forward-time trajectories from a small box around the site (see parameter box.len and other parameters in STEP 2) no matter if those trajectories had been calculated previously. In this mode, air parcels are released continuously for every dtime.sep hours (see parameter dtime.*);
  • run_trajec = T & run_for_err = T: add a wind error component (controlled by parameter siguverr) while calculating forward-time trajectories;
  • run_wind_err = T: calculate modeled wind errors against radiosonde data (one need to download them first);
  • run_bg = T: calculate the background values based on OCO-2/3 or TROPOMI data (see parameters in STEP 4); the inner functions will generate plots of plumes and observed enhancements by assuming background region to the north/south/east/west outside the plume. The final estimated background values will be stored in file.path(store_path, fn) if writeTF = T.

Estimate horizontal and vertical transport errors

Instead of using model ensembles for estimating errors, X-STILT propagates real-world random u-v- wind errors (with correlation length scale and timescale) into errors in XCO2. The fundamental approach is proposed and documented in Lin and Gerbig, 2005, which is now extended to column CO2. We calculate and propagate XCO2 errors from release levels, to receptor locations, and finally to overpasses.

Briefly speaking, users need to first generate another set of trajectories with wind error statistics (i.e., blue dots in Fig. S4) by turning on run_hor_err. Once trajectories with wind errors have been generated, one need to turn on run_sim to let X-STILT calculate the errors in XCO2 based on two sets of trajectories (with/without wind errors). Hard to explain all the steps here, but feel free to contact Dien if one is interested in performing such error estimates. Please also refer to details described in Sect. 2.6 in Wu et al. (2018).

Atmospheric inversion

As discussed in Sect. 4.2 in Wu et al. (2018), we could come up the posterior scaling factor for anthropogenic emissions based on 5 overpasses over Riyadh, via a simple Bayesian Inversion. We treated the entire city as a whole and solve for one scaling factor, given biases in near-field wind direction. So, we did not solve for posterior emissions for every grid cell within a city. Codes are not included in this repo.

Example figures of column footprints and XCO2.ff

Figure - Latitude integrated map of weighted column footprints [umol m-2 s-1] on 12/29/2014 from 70+ selected sounding/receptor over Riyadh.

Figure - Latitude integrated XCO2.ff contribution maps [ppm] on 12/29/2014 from 70+ selected sounding/receptor over Riyadh.

Tips for debugging

Q1. How do I know the model runs smoothly?

A: Go to your output directory -> /site -> /out_* -> /by-id -> /YYYYMMDDHH_LON_LAT_X and see if _X_traj.rds or _X_foot.nc were generated.

Q2: What if there are nothing in that folder?

A: Look for error messages under XSTILT/rslurm_XSTILT folder. Then go back to the output folder and run STILT at Fortran level by ./hycs_std, where hycs_std is the compiled fortran program of HYSPLIT-STILT. Look for error messages - Usually your receptors are outside the met fields or missing met fields for the backward time duration.

Reference

Model development

Initial X-STILTv1 paper: Wu, D., Lin, J. C., Fasoli, B., Oda, T., Ye, X., Lauvaux, T., Yang, E. G., and Kort, E. A.: A Lagrangian approach towards extracting signals of urban CO2 emissions from satellite observations of atmospheric column CO2 (XCO2): X-Stochastic Time-Inverted Lagrangian Transport model (“X-STILT v1”), Geosci. Model Dev., 11, 4843-4871, https://doi.org/10.5194/gmd-11-4843-2018, 2018.

STILTv2 paper: Fasoli, B., Lin, J. C., Bowling, D. R., Mitchell, L., and Mendoza, D.: Simulating atmospheric tracer concentrations for spatially distributed receptors: updates to the Stochastic Time-Inverted Lagrangian Transport model's R interface (STILT-R version 2), Geosci. Model Dev., 11, 2813-2824, https://doi.org/10.5194/gmd-11-2813-2018, 2018.

Initial STILTv1 paper: Lin, J.C., Gerbig, C., Wofsy, S.C., Andrews, A.E., Daube, B.C., Davis, K.J. and Grainger, C.A.: A near‐field tool for simulating the upstream influence of atmospheric observations: The Stochastic Time‐Inverted Lagrangian Transport (STILT) model. Journal of Geophysical Research: Atmospheres, 108(D16), https://doi.org/10.1029/2002JD003161. 2003.

STILT error uncertainties: Lin, J. C., and Gerbig, C., Accounting for the effect of transport errors on tracer inversions, Geophys. Res. Lett., 32, L01802, https://doi.org/10.1029/2004GL021127, 2005.

STILT-NOx: Wu, D., Laughner, J. L., Liu, J., Palmer, P. I., Lin, J. C., and Wennberg, P. O.: A simplified non-linear chemistry transport model for analyzing NO2 column observations: STILT–NOx, Geosci. Model Dev., 16, 6161–6185, https://doi.org/10.5194/gmd-16-6161-2023, 2023.

Model applications

X-STILT for TROPOMI XCO: Wu, D., Liu, J., Wennberg, P. O., Palmer, P. I., Nelson, R. R., Kiel, M., and Eldering, A.: Towards sector-based attribution using intra-city variations in satellite-based emission ratios between CO2 and CO, Atmos. Chem. Phys. Discuss. [preprint], https://doi.org/10.5194/acp-2021-1029, in review, 2022.

About

Source codes for X-STILT(NOx) [Wu et al., 2018, 2023] based on STILT-R version 2 [Fasoli et al., 2018] and STILT [Lin et al., 2003].

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages