Welcome to CHEEREIO!
Welcome to the CHEEREIO website and documentation! The GEOS-Chem CHEmistry and Emissions REanalysis Interface with Observations (CHEEREIO) is a tool that allows scientists to use observations of pollutants or gases in the atmosphere, such as from satellites or surface stations, to update supercomputer models that simulate the Earth. Other scientists have assembled estimates of emissions of various pollutants from around the world, but our emissions estimates are very uncertain. CHEEREIO uses a model called GEOS-Chem to simulate what the atmosphere would look like if those emissions estimates were correct, and then compares those estimates to the real atmosphere as observed by satellites or equipment on the Earth’s surface. CHEEREIO uses the difference between the model simulation and the real world to update our maps of emissions.
More formally, CHEEREIO is a set of Python and shell scripts that support data assimilation and emissions inversions for arbitrary runs of the GEOS-Chem chemical transport model via an ensemble approach (i.e. without the model adjoint).
This site provides a manual for the installation, use, and modification of CHEEREIO for a variety of scientific applications. You can download CHEEREIO from the Github page and install by following the instructions on the Installing CHEEREIO page later in the documentation.
CHEEREIO development status: We will officially release a CHEEREIO beta when we publish our model description paper, which is currently in prep. We are not yet on a formal release schedule because CHEEREIO is still in active initial development — though again, we are close (aiming for January 2023). In plain English, you are welcome to download CHEEREIO now but at this time the main branch is not guaranteed to be functional. This documentation is also not yet fully written but will be complete by the time we submit the model description paper. Check back often, or email me at pendergrass [AT] g [DOT] harvard [DOT] edu to be notified when CHEEREIO is released.
CHEEREIO follows four design principles:
Easy to customize: Assimilate anything, in any GEOS-Chem configuration or simulation.
Easy to maintain: Science automatically aligned with latest model version.
Easy to deploy: One configuration file controls installation and settings
Easy to link observations: Object-oriented observation operator implementation in Python allows the user to rapidly add new kinds of data with minimal programming required.
This manual assumes that you are familiar with setting up and running the GEOS-Chem chemical transport model. For more information and background, please see the GEOS-Chem Wiki. Although this manual offers an intuitive explanation of CHEEREIO’s data assimilation algorithm in the How CHEEREIO works section, you should probably consider the original algorithm paper Hunt. et. al.,  as a prerequisite to using CHEEREIO. Don’t worry, it’s quite readable!
I am more than happy to collaborate with you, however you choose to use CHEEREIO: just send an email to me at pendergrass [AT] g [DOT] harvard [DOT] edu. Questions of any kind are also more than welcome. This can be on anything from interpreting results to getting the ensemble installed on your machine. However, these questions along with any bugs should be reported by opening an issue on Github, as this will allow all users to see the solution.
- About CHEEREIO
- Installing CHEEREIO
- Overview of CHEEREIO’s capabilities
- Debugging CHEEREIO
- Configuring your simulation
- The structure of the ensemble directory
- Running the ensemble
- The two ensemble spinup approaches
- Amplifying the ensemble spread
- Scaling GEOS-Chem to match observations
- The burn in period
- Starting the run
- Monitoring the run progress
- About the Run Ensemble Simulations script
- Guide to CHEEREIO core files
- Installation and spinup scripts
- Run management scripts
- Assimilation support scripts
- LETKF classes
- Observation operators
- Utilities for the user
- Deprecated scripts
- The CHEEREIO LETKF implementation
- What is a CHEEREIO observation operator?
- The observation operator toolkit
- The produceSuperObservationFunction function
- The apply_filters function
- The nearest_loc function
- The getGCCols function
- The averageByGC function
- The ObsData class
- The Observation_Translator class
- Existing observation toolkits
- Workflow to add a new observation operator
- (1) Create a class inheriting from Observation_Translator
- (2) Implement getObservations() function
- (3) Implement gcCompare() function
- (4) Update operators.json
- (5) Link observational files from ens_config.json
- (6) [optional] Add observation filters via an extension
- (7) [optional] Add a new super observation error function
- (8) Share your operator with the CHEEREIO community
- The postprocessing workflow
- How to run the default postprocessing workflow
- The postprocessing API
- Functions in postprocess_tools
- Functions in map_tools
- Adding a new observation field to the postprocessing workflow