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
- OCO-2&3 XCO2;
- TROPOMI column CO (Wu et al., 2022), CH4 (Li et al., 2024); and NO2 (Wu et al., 2023: STILT-NOx);
- TCCON column CO2, CO, N2O, CH4 (check out
run_xstilt_tccon.r
); - EM27/SUN (under construction...);
- 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
- running backward trajectories from an atmospheric column and column footprint (start with
run_xstilt.r
for either initial X-STILT or updated STILT-NOx); - running forward-time trajectories from a box around the site and compute background from satellite observations (start with
compute_bg.r
); - estimating wind and PBL uncertainties and translating those into XCO2 uncertainties (start with
run_xstilt.r
) - 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. 💫
- Recent commits
- Download and install model
- Prerequisites
- Obtain column footprint
- Determine background XCO2
- Estimate horizontal and vertical transport errors
- Atmospheric inversion on XCO2
- Example figures of column footprints and XCO2.ff
- Tips for debugging
- Reference
- 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.
-
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
, ortrp_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.
- download OCO-2 Lite or TROPOMI Level 2 files and modify the corresponding parameters including
-
For IDEAL column simulation WITHOUT satellite dependence -
- prepare a csv file for receptor
lon
,lat
, andtime
. An example is provided as inreceptor_demo.csv
. Check out instructions in recent commit.
- prepare a csv file for receptor
-
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.
-
(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
.
- 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
-
(OPTIONAL) For performing transport error analyses -
- NOAA radiosonde data for computing model-data wind errors; please choose wind speed unit of tenths of m s-1 and FSL format; Users could download RAOB stations within a spatial area around
site
; - Carbon-Tracker mole fraction data, e.g., CT-NRT for getting the total XCO2 in addition to FF XCO2.
- NOAA radiosonde data for computing model-data wind errors; please choose wind speed unit of tenths of m s-1 and FSL format; Users could download RAOB stations within a spatial area around
-
(OPTIONAL) For performing emission error analyses -
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.
-
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).
-
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 offrun_trajec
andrun_foot
;
run_emiss_err = T
: Prior emission error analysis (requires footprint).
-
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.
-
Modify meteorological fields, STEP 4. See STILT documentation for more explanations.
-
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.
-
Set up SLURM parallel computing, STEP 6.
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 parameterbox.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 everydtime.sep
hours (see parameterdtime.*
);
run_trajec = T & run_for_err = T
: add a wind error component (controlled by parametersiguverr
) 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 infile.path(store_path, fn)
ifwriteTF = T
.
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).
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.
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.
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.
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.
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.
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.