HEMCO_CESM: CESM/CAM interface to modular HEMCO chemistry emissions module

This is the official repository for the HEMCO-CESM interface, coupling the Harmonized Emissions Component (HEMCO) to the Community Earth System Model version 2 (CESM2) via the Community Atmosphere Model (CAM).

:bulb: HEMCO documentation: https://hemco.readthedocs.io

:bulb: HEMCO on the CAM-chem Wiki: https://wiki.ucar.edu/display/camchem/HEMCO

:book: Reference: Lin et al., 2021

:envelope: Maintainer: Haipeng Lin (hplin@seas.harvard.edu). Please post an issue or pull request in this repository if your request is code-related.

How to checkout

HEMCO is fully implemented as an emissions component for GEOS-Chem and CAM-chem chemistry within CAM for MUSICA.

This repository, HEMCO_CESM, is included as an external in CAM (src/hemco) and contains the interface for HEMCO to communicate with CAM. This repository then includes HEMCO itself as an external (src/hemco/HEMCO) which is model independent and shared by all models implementing HEMCO (GEOS-Chem, GEOS, CESM, WRF, etc.)

Main components:

• /HEMCO/src/: Contains the source for the HEMCO emissions component, imported using manage_externals (see Externals_HCO.cfg)
• /hemco_interface.F90: Main entry point for modular HEMCO emissions module; contains dummy ESMF gridded component used for regridding between CAM and HEMCO lat-lon.
• /hco_esmf_grid.F90: HEMCO internal lat-lon grid computation and ESMF regrid wrapper.
• /hco_cam_exports.F90: Utilities for HEMCO to export its computed results via the CAM history component (diagnostic output) and the CAM physics buffer (feeding into the chemistry components).
• /hco_cam_convert_state_mod.F90: State conversion module between CAM meteorology and chemistry variables into HEMCO extensions format.

Auxiliary components:

• /hco_esmf_wrappers.F90: Helper routines

Configuration files

...are available in the HEMCO_CESM_configs repository with instructions on how to translate GEOS-Chem emission species to CAM-chem.

Contribution Guide/Branches

• main will always represent the latest code merged into cam_development.
• development is the development trunk, where latest code and features are available but not yet available in cam_development. Releases are tagged from this branch.
• dev/* are feature branches where development happens. The contents of these branches are submitted to development via pull requests.

Releases are named in the format hemco-cesmX_Y_Z_hemco3_9_0 where X.Y.Z is the semantic versioning of the HEMCO-CESM interface release (See CHANGELOG.md) and the suffix is the accompanying HEMCO version.

• X represents breaking, backwards-incompatible changes.
• Y represents backwards-compatible major releases.
• Z represents backwards-compatible bug fixes, including minor releases with changes only in the HEMCO external.

License

Copyright (c) 2019-2024, Haipeng Lin and Harvard University Atmospheric Chemistry Modeling Group.
All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License version 2.1 as published by the Free Software Foundation;

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA