diff --git a/docs/requirements.txt b/docs/requirements.txt index 860e3a23..cbdc524a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,10 @@ -# Requirements for building the GCHP documentation -sphinx -sphinx_rtd_theme -sphinxcontrib-bibtex +# Requirements for building the HEMCO documentation +# +# NOTE: There are issues with sphinx 4.0.0+ and sphinx-rtd-theme 1.0.0 +# so we'll use older versions (Bob Yantosca, 28 Feb 2022) +# +sphinx<4.0.0 +sphinx_rtd_theme<1.0.0 +sphinxcontrib-bibtex==2.2.0 recommonmark +docutils==0.16 diff --git a/docs/source/conf.py b/docs/source/conf.py index e316a016..40c43e3a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -69,7 +69,7 @@ def format_web_refs(self, e): bibtex_bibliography_header = ".. rubric:: References" bibtex_footbibliography_header = bibtex_bibliography_header -bibtex_bibfiles = ['geos-chem-shared-docs/geos-chem.bib'] +bibtex_bibfiles = ['hemco.bib', 'geos-chem-shared-docs/geos-chem.bib'] # List of patterns, relative to source directory, that match files and diff --git a/docs/source/coupling/intro.rst b/docs/source/coupling/intro.rst new file mode 100644 index 00000000..e7fc17b3 --- /dev/null +++ b/docs/source/coupling/intro.rst @@ -0,0 +1,331 @@ + +Coupling HEMCO to other models +=============================== + +This page details technical information useful for developers who wish to couple the HEMCO ("Harmonized" Emissions Component) emissions component to other models. + +The description of HEMCO coupling to other models is available in :cite:`Lin_et_al._2021`, which describes coupling to GEOS-Chem "Classic", GCHP, WRF-GC, CESM2-GC, and future NOAA models. + + +********* +Overview +********* + +This work is made possible by a restructuring of HEMCO, named HEMCO 3.0. HEMCO 3.0 separates model-specific components such as I/O, Regridding and the model speciation interface, into modular components, and isolate the HEMCO emissions Core. + +This work is currently being actively worked on by the GEOS-Chem Support Team and Haipeng Lin (Harvard) as part of coupling GEOS-Chem with the CESM model. + +**************** +Useful resources +**************** + +* HEMCO Repository: `geoschem/HEMCO <https://github.com/geoschem/HEMCO geoschem/HEMCO>`__ on GitHub. +* Original description paper: :cite:`Keller_et_al._2014`. +* Coupling and HEMCO 3.0 description paper: :cite:`Lin_et_al._2021`. +* `The HEMCO User's Guide <http://wiki.seas.harvard.edu/geos-chem/index.php/The_HEMCO_User%27s_Guide>`__ +* `HEMCO versions <http://wiki.seas.harvard.edu/geos-chem/index.php/HEMCO_versions>`__ + +*********** +Terminology +*********** + +As part of the HEMCO 3.0 restructuring, "HEMCO" is now divided into three pieces depending on their function: + +* **The HEMCO Core.** Emissions calculations logic, containers, data types, etc. +* **Data Input Layer.** I/O (previously ``HCOIO_Read/Write_*_Mod``), Regridding (``HCO_MESSY_REGRID``, ``HCO_INTERP_MOD``), ... This will be rearranged into ``Regrid/`` and ``IO/`` folders in a future version. Right now due to dependencies, some of these files still live in the ``Core/``. +* **Model Interface Layer.** Code that couples HEMCO with other models. There are common utilities available at ``Interfaces/HCO_Interface_Common.F90``. + +.. note:: + Note that not all code pertinent to model coupling actually lives inside of HEMCO; this is by design, as data types that are external to HEMCO (i.e. GEOS-Chem types such as ``State_Met``, CESM types such as ``physics_state``, WRF types such as ``domain``) must be maintained with the model and not inside HEMCO. Some code lives in :file:`Interfaces/`, and some will live inside the model. + +********************************** +Technical Notes (Data Input Layer) +********************************** + +TBD + +**************************************** +Technical Notes (Model Interface Layer) +**************************************** + +HEMCO 3.0 Model Interface Layer Overview +----------------------------------------- + +In order to interface HEMCO with the target model, there are a few primary tasks that need to be performed as outlined below. + +Data/code that needs to be provided to HEMCO based on the target model's data structures include: + +* The clock and time-step of the target model +* List of species and physical properties (molecular weight required; other properties such as Henry's law constants are optional, only for extensions such as SeaFlux) +* Grid information (``I``, ``J``, ``L`` atmospheric '0-D box' dimensions required; if using HEMCO built-in regrid, then specifics are needed. See below) + +Data/code that needs to be **retrieved from HEMCO** into the target model's data structures (i.e. state object for constituent flux/concentrations) include: + +* Emissions fluxes (kg/m2/s format) retrieved from HEMCO, aggregated per species ID, for current time step +* Other data retrieved from HEMCO (using ``HCO_GetPtr`` or ``HCO_EvalFld``) + +.. note:: + Avoid calling HEMCO functions directly from outside of a specific module designed to interface HEMCO with the model. This is so the interface can be updated more easily if subroutines within HEMCO such as ``HCO_GetPtr`` change, and the HEMCO state (``HcoState``) doesn't need to be passed to everywhere in your model that needs to retrieve data from HEMCO. **It is also useful so regridding to/from HEMCO can be performed in a centralized location, if so needed by the model.** For example, GEOS-Chem wraps ``HCO_GetPtr`` and ``HCO_EvalFld`` into its own interface, ``HCO_GC_GetPtr``, ``HCO_GC_EvalFld``, which will auto-magically add the ``HcoState`` argument, in addition to handling regridding if necessary. + +Things that come out-of-the-box and generally do not require customization to a specific model: + +* Reading configuration file (:file:`HEMCO_Config.rc`), although the path needs to be specified +* HEMCO "driver" (run) routines +* Managing HEMCO memory (initializing HEMCO state in ``HcoState``, extensions state in ``ExtState``, etc.) + +Reading the HEMCO configuration file and defining species list +--------------------------------------------------------------- + +This is a three-step process. First initialize the configuration object (``HcoConfig``): + +.. code-block:: fortran + + call ConfigInit(HcoConfig, HMRC, nModelSpecies=nSpc) + +You have to register the species first in addition to some other HcoConfig properties: + +.. code-block:: fortran + + HcoConfig%amIRoot = masterproc + HcoConfig%MetField = 'MERRA2' + HcoConfig%GridRes = '' + HcoConfig%nModelSpc = nHcoSpc + HcoConfig%nModelAdv = nHcoSpc ! # of adv spc? + + do N = 1, nHcoSpc + HcoConfig%ModelSpc(N)%ModID = N ! model id + HcoConfig%ModelSpc(N)%SpcName = trim(solsym(N)) + enddo + +Then open the configuration file in two phases; after phase 1, initialize the log file on the MPI root process: + +.. code-block:: fortran + + call Config_ReadFile(HcoConfig%amIRoot, HcoConfig, HcoConfigFile, 1, HMRC, IsDryRun=.false.) + + ! Open the log file + if(masterproc) then + call HCO_LOGFILE_OPEN(HcoConfig%Err, RC=HMRC) + endif + + call Config_ReadFile(HcoConfig%amIRoot, HcoConfig, HcoConfigFile, 2, HMRC, IsDryRun=.false.) + +.. warning:: + **Note that the species count has to be populated three times.** Once above at ``ConfigInit``, and twice inside the *initialized HEMCO Config object*. + +Some species physical properties need to be defined for HEMCO extensions, such as molecular weight and henry's law constants: + +.. code-block:: fortran + + !----------------------------------------------------------------------- + ! Register HEMCO species information (HEMCO state object) + !----------------------------------------------------------------------- + do N = 1, nHcoSpc + HcoState%Spc(N)%ModID = N ! model id + HcoState%Spc(N)%SpcName = trim(solsym(N)) ! species name + HcoState%Spc(N)%MW_g = adv_mass(N) ! mol. weight [g/mol] + + ! HcoState%Spc(N)%HenryK0 ! [M/atm] + ! HcoState%Spc(N)%HenryCR ! [K] + ! HcoState%Spc(N)%HenryPKA ! [1] + enddo + +.. note:: + If you are not using HEMCO extensions, only ``ModID``, ``SpcName`` and ``MW_g`` need to be defined. + +Defining Grid +------------- + +Define atmospheric column numbers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: fortran + + HcoState%NX = my_IM + HcoState%NY = my_JM + HcoState%NZ = LM + +Define the vertical grid +^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are many ways of defining the vertical discretization. Check ``HCO_VertGrid_Define``. + +.. code-block:: fortran + + ! Pass Ap, Bp values, units [Pa], [unitless] + call HCO_VertGrid_Define(HcoState%Config, & + zGrid = HcoState%Grid%zGrid, & + nz = HcoState%NZ, & + Ap = Ap, & + Bp = Bp, & + RC = HMRC) + +Define horizontal grid parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + HEMCO **requires HORIZONTAL grid information only if it is using internal regridding routines**, i.e. ``MAP_A2A`` or MESSy. Otherwise, this can be filled with dummy information. + +.. warning:: + If HEMCO internal regridding (``MAP_A2A``) regridding routines are used, **only rectilinear grids are supported.** + + This is because ``XMid``, ``YMid``, ... arrays are **1-dimensional** and thus curvilinear coordinates cannot be stored. The underlying ``MAP_A2A`` algorithm **can** handle curvilinear; it is just due to the data structure. This will be fixed in a future HEMCO version. + +.. code-block:: fortran + + ! Point to grid variables + HcoState%Grid%XMID%Val => XMid (my_IS:my_IE , my_JS:my_JE ) + HcoState%Grid%YMID%Val => YMid (my_IS:my_IE , my_JS:my_JE ) + HcoState%Grid%XEdge%Val => XEdge (my_IS:my_IE+1, my_JS:my_JE ) + HcoState%Grid%YEdge%Val => YEdge (my_IS:my_IE , my_JS:my_JE+1) + HcoState%Grid%YSin%Val => YSin (my_IS:my_IE , my_JS:my_JE+1) + HcoState%Grid%AREA_M2%Val => AREA_M2(my_IS:my_IE , my_JS:my_JE ) + +Here we point HEMCO's variables to structures we have created in the model. Examples in how to create these structures are available `in the HEMCO-CESM interface <https://github.com/jimmielin/HEMCO_CESM/blob/development/hco_esmf_grid.F90>`__. + +Defining Met Fields for HEMCO Extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An example to translate and define meteorological quantities such as temperature, humidity, etc. is available `in the HEMCO-CESM interface <https://github.com/jimmielin/HEMCO_CESM/blob/development/hco_cam_convert_state_mod.F90>`__. + +Running HEMCO +-------------- + +Prerequisites: + +.. code-block:: fortran + + ! HEMCO + use HCO_Interface_Common, only: GetHcoVal, GetHcoDiagn + use HCO_Clock_Mod, only: HcoClock_Set, HcoClock_Get + use HCO_Clock_Mod, only: HcoClock_EmissionsDone + use HCO_Diagn_Mod, only: HcoDiagn_AutoUpdate + use HCO_Driver_Mod, only: HCO_Run + use HCO_EmisList_Mod, only: Hco_GetPtr + use HCO_FluxArr_Mod, only: HCO_FluxArrReset + use HCO_GeoTools_Mod, only: HCO_CalcVertGrid, HCO_SetPBLm + +Update the HEMCO clock +^^^^^^^^^^^^^^^^^^^^^^ + +Also make sure the time steps are set correctly. +Use from the common utilities: + +.. code-block:: fortran + + call HCOClock_Set(HcoState, year, month, day, & + hour, minute, second, IsEmisTime=.true., RC=HMRC) + + +Reset fluxes for new timestep +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: fortran + + call HCO_FluxArrReset(HcoState, HMRC) + +Update vertical grid parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +HEMCO needs an updated vertical grid at each time step. Data passed into ``HCO_CalcVertGrid`` can vary and the definition can be checked for acceptable parameters. + +.. code-block:: fortran + + call HCO_CalcVertGrid(HcoState, PSFC, ZSFC, TK, BXHEIGHT, PEDGE, HMRC) + + call HCO_SetPBLm(HcoState, PBLM=State_HCO_PBLH, & + DefVal=1000.0_hp, & ! default value + RC=HMRC) + +Some dummy setup (advanced) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To document. + +.. code-block:: fortran + + ! Range of species and emission categories. + ! Set Extension number ExtNr to 0, indicating that the core + ! module shall be executed. + HcoState%Options%SpcMin = 1 + HcoState%Options%SpcMax = -1 + HcoState%Options%CatMin = 1 + HcoState%Options%CatMax = -1 + HcoState%Options%ExtNr = 0 + + ! Use temporary array? + HcoState%Options%FillBuffer = .FALSE. + +Run HEMCO driver +^^^^^^^^^^^^^^^^^^ + +.. code-block:: fortran + + call HCO_Run( HcoState, 1, HMRC, IsEndStep=.false. ) + call HCO_Run( HcoState, 2, HMRC, IsEndStep=.false. ) + +Run HEMCO extensions driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Necessary only if you are using HEMCO extensions. + +.. code-block:: fortran + + call HCOX_Run(HcoState, ExtState, HMRC) + +Close timestep +^^^^^^^^^^^^^^^ + +.. code-block:: fortran + + !----------------------------------------------------------------------- + ! Update "autofill" diagnostics. + ! Update all 'AutoFill' diagnostics. This makes sure that all + ! diagnostics fields with the 'AutoFill' flag are up-to-date. The + ! AutoFill flag is specified when creating a diagnostics container + ! (Diagn_Create). + !----------------------------------------------------------------------- + call HcoDiagn_AutoUpdate(HcoState, HMRC) + + !----------------------------------------------------------------------- + ! Tell HEMCO we are done for this timestep... + !----------------------------------------------------------------------- + call HcoClock_EmissionsDone(HcoState%Clock, HMRC) + +Retrieving emissions data from HEMCO +-------------------------------------- +You can either use the common utilities, where data is retrieved using ``GetHcoValEmis``, or tap into the arrays directly. + +For generic data containers, pass the container name like so: + +.. code-block:: fortran + + ! For grabbing data from HEMCO Ptrs (uses HEMCO single-precision) + real(sp), pointer :: Ptr2D(:,:) + real(sp), pointer :: Ptr3D(:,:,:) + + logical :: FND + + call HCO_GetPtr(HcoState, 'CONTAINER_NAME', Ptr2D, HMRC, FOUND=FND) + +Retrieving deposition velocities (depv) from HEMCO +--------------------------------------------------- + +.. warning:: + **Important:** Note that deposition (sink terms) fluxes are handled separately from emissions in HEMCO. This is particularly important if you use HEMCO to calculate deposition terms, e.g. the sink term in ``SeaFlux`` (sea-air exchange). The standard in HEMCO is that the sink terms are stored as deposition velocities (``depv``, unit 1/s) so HEMCO generally does not need to be aware of concentrations. + +A thorough discussion of this is in `the HEMCO GitHub issue tracker <https://github.com/geoschem/HEMCO/issues/72#issuecomment-789409266>`_. The code to handle deposition velocities from HEMCO is generally as follows: + +.. code-block:: fortran + + !------------------------------------------------------------------ + ! Also add drydep frequencies calculated by HEMCO (e.g. from the + ! air-sea exchange module) to DFLX. These values are stored + ! in 1/s. They are added in the same manner as the drydep freq values + ! from drydep_mod.F90. DFLX will be converted to kg/m2/s later. + ! (ckeller, 04/01/2014) + !------------------------------------------------------------------ + CALL GetHcoValDep( NA, I, J, L, found, dep ) + IF ( found ) THEN + dflx(I,J,NA) = dflx(I,J,NA) & + + ( dep * spc(I,J,NA) / (AIRMW / ThisSpc%MW_g) ) + ENDIF \ No newline at end of file diff --git a/docs/source/getting-started/key-references.rst b/docs/source/getting-started/key-references.rst index 9eb14c74..248f1dba 100644 --- a/docs/source/getting-started/key-references.rst +++ b/docs/source/getting-started/key-references.rst @@ -2,6 +2,8 @@ Key References ============== * GEOS-Chem was first described in :cite:`Bey_et_al._2001`. -* HEMCO is described in :cite:`Keller_et_al._2014`. +* HEMCO is described in :cite:`Keller_et_al._2014` and :cite:`Lin_et_al._2021`. + +Other references for GEOS-Chem are available on `the GEOS-Chem website <https://geos-chem.seas.harvard.edu/narrative>`_ and a list of references for current HEMCO emission inventories is available in `Table 1 of Lin et al., 2021 <https://gmd.copernicus.org/articles/14/5487/2021/#section2>`_. .. bibliography:: diff --git a/docs/source/getting-started/requirements.rst b/docs/source/getting-started/requirements.rst index 6ff9e12c..514d101d 100644 --- a/docs/source/getting-started/requirements.rst +++ b/docs/source/getting-started/requirements.rst @@ -111,7 +111,7 @@ netCDF) on your system. | `Intel | **The Intel | | `Install from | | Compiler Suite | Compiler Suite | | Intel <http | | (icc, icpc, | is our | The GCST | s://software.i | -| ifort) | recommended | has tested | ntel.com/conte | +| ifort)` | recommended | has tested | ntel.com/conte | | | proprietary | with these | nt/www/us/en/d | | | compiler | versions (but | evelop/tools/o | | | collection.** | others may | neapi/componen | diff --git a/docs/source/hemco.bib b/docs/source/hemco.bib new file mode 100644 index 00000000..51442dbb --- /dev/null +++ b/docs/source/hemco.bib @@ -0,0 +1,114 @@ + +@article{Bey_et_al._2001, + title = {Global modeling of tropospheric chemistry with assimilated meteorology: {Model} description and evaluation}, + volume = {106}, + issn = {01480227}, + shorttitle = {Global modeling of tropospheric chemistry with assimilated meteorology}, + url = {http://doi.wiley.com/10.1029/2001JD000807}, + doi = {10.1029/2001JD000807}, + language = {en}, + number = {D19}, + urldate = {2020-07-06}, + journal = {Journal of Geophysical Research: Atmospheres}, + author = {Bey, Isabelle and Jacob, Daniel J. and Yantosca, Robert M. and Logan, Jennifer A. and Field, Brendan D. and Fiore, Arlene M. and Li, Qinbin and Liu, Honguy Y. and Mickley, Loretta J. and Schultz, Martin G.}, + month = oct, + year = {2001}, + pages = {23073--23095}, + file = {Full Text:/home/liam/Zotero/storage/QTE96HKV/Bey et al. - 2001 - Global modeling of tropospheric chemistry with ass.pdf:application/pdf} +} + +@article{Keller_et_al._2014, + title = {{HEMCO} v1.0: a versatile, {ESMF}-compliant component for calculating emissions in atmospheric models}, + volume = {7}, + issn = {1991-9603}, + shorttitle = {{HEMCO} v1.0}, + url = {https://www.geosci-model-dev.net/7/1409/2014/}, + doi = {10.5194/gmd-7-1409-2014}, + language = {en}, + number = {4}, + urldate = {2020-05-25}, + journal = {Geoscientific Model Development}, + author = {Keller, C. A. and Long, M. S. and Yantosca, R. M. and Da Silva, A. M. and Pawson, S. and Jacob, D. J.}, + month = jul, + year = {2014}, + pages = {1409--1417}, + file = {Full Text:/home/liam/Zotero/storage/KBL3EWKN/Keller et al. - 2014 - HEMCO v1.0 a versatile, ESMF-compliant component .pdf:application/pdf} +} + +@article{Long_et_al._2015, + title = {Development of a grid-independent {GEOS}-{Chem} chemical transport model (v9-02) as an atmospheric chemistry module for {Earth} system models}, + volume = {8}, + issn = {1991-9603}, + url = {https://gmd.copernicus.org/articles/8/595/2015/}, + doi = {10.5194/gmd-8-595-2015}, + language = {en}, + number = {3}, + urldate = {2020-07-24}, + journal = {Geoscientific Model Development}, + author = {Long, M. S. and Yantosca, R. and Nielsen, J. E. and Keller, C. A. and da Silva, A. and Sulprizio, M. P. and Pawson, S. and Jacob, D. J.}, + month = mar, + year = {2015}, + pages = {595--602}, + file = {Full Text:/home/liam/Zotero/storage/82Y79TB3/Long et al. - 2015 - Development of a grid-independent GEOS-Chem chemic.pdf:application/pdf} +} + +@article{Eastham_et_al._2018, + title = {{GEOS}-{Chem} {High} {Performance} ({GCHP} v11-02c): a next-generation implementation of the {GEOS}-{Chem} chemical transport model for massively parallel applications}, + volume = {11}, + issn = {1991-9603}, + shorttitle = {{GEOS}-{Chem} {High} {Performance} ({GCHP} v11-02c)}, + url = {https://www.geosci-model-dev.net/11/2941/2018/}, + doi = {10.5194/gmd-11-2941-2018}, + language = {en}, + number = {7}, + urldate = {2019-11-14}, + journal = {Geoscientific Model Development}, + author = {Eastham, Sebastian D. and Long, Michael S. and Keller, Christoph A. and Lundgren, Elizabeth and Yantosca, Robert M. and Zhuang, Jiawei and Li, Chi and Lee, Colin J. and Yannetti, Matthew and Auer, Benjamin M. and Clune, Thomas L. and Kouatchou, Jules and Putman, William M. and Thompson, Matthew A. and Trayanov, Atanas L. and Molod, Andrea M. and Martin, Randall V. and Jacob, Daniel J.}, + month = jul, + year = {2018}, + pages = {2941--2953}, + file = {Full Text:/home/liam/Zotero/storage/4WKVN3YV/Eastham et al. - 2018 - GEOS-Chem High Performance (GCHP v11-02c) a next-.pdf:application/pdf} +} + +@article{Zhuang_et_al._2020, + title = {Enabling {High}‐{Performance} {Cloud} {Computing} for {Earth} {Science} {Modeling} on {Over} a {Thousand} {Cores}: {Application} to the {GEOS}‐{Chem} {Atmospheric} {Chemistry} {Model}}, + volume = {12}, + issn = {1942-2466, 1942-2466}, + shorttitle = {Enabling {High}‐{Performance} {Cloud} {Computing} for {Earth} {Science} {Modeling} on {Over} a {Thousand} {Cores}}, + url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2020MS002064}, + doi = {10.1029/2020MS002064}, + language = {en}, + number = {5}, + urldate = {2020-07-06}, + journal = {Journal of Advances in Modeling Earth Systems}, + author = {Zhuang, Jiawei and Jacob, Daniel J. and Lin, Haipeng and Lundgren, Elizabeth W. and Yantosca, Robert M. and Gaya, Judit Flo and Sulprizio, Melissa P. and Eastham, Sebastian D.}, + month = may, + year = {2020}, + file = {Full Text:/home/liam/Zotero/storage/F3S8SAZM/Zhuang et al. - 2020 - Enabling High‐Performance Cloud Computing for Eart.pdf:application/pdf} +} + +@article{Bindle_et_al._2020, + author = {Bindle, L. and Martin, R. V. and Cooper, M. J. and Lundgren, E. W. and Eastham, S. D. and Auer, B. M. and Clune, T. L. and Weng, H. and Lin, J. and Murray, L. T. and Meng, J. and Keller, C. A. and Putman, W. M. and Pawson, S. and Jacob, D. J.}, + title = {Grid-stretching capability for the GEOS-Chem 13.0.0 atmospheric chemistry model}, + journal = {Geoscientific Model Development}, + volume = {14}, + year = {2021}, + number = {10}, + pages = {5977--5997}, + url = {https://gmd.copernicus.org/articles/14/5977/2021/}, + doi = {10.5194/gmd-14-5977-2021} +} + +@Article{Lin_et_al._2021, +AUTHOR = {Lin, H. and Jacob, D. J. and Lundgren, E. W. and Sulprizio, M. P. and Keller, C. A. and Fritz, T. M. and Eastham, S. D. and Emmons, L. K. and Campbell, P. C. and Baker, B. and Saylor, R. D. and Montuoro, R.}, +TITLE = {Harmonized Emissions Component (HEMCO) 3.0 as a versatile emissions +component for atmospheric models: application in the GEOS-Chem, NASA GEOS, +WRF-GC, CESM2, NOAA GEFS-Aerosol, and NOAA UFS models}, +JOURNAL = {Geoscientific Model Development}, +VOLUME = {14}, +YEAR = {2021}, +NUMBER = {9}, +PAGES = {5487--5506}, +URL = {https://gmd.copernicus.org/articles/14/5487/2021/}, +DOI = {10.5194/gmd-14-5487-2021} +} \ No newline at end of file diff --git a/docs/source/images/lin-et-al-2021-fig2.png b/docs/source/images/lin-et-al-2021-fig2.png new file mode 100644 index 00000000..8f48330c Binary files /dev/null and b/docs/source/images/lin-et-al-2021-fig2.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 1898db21..f23f8c14 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ HEMCO .. toctree:: :maxdepth: 2 - :caption: User Guide + :caption: User Guide (HEMCO Standalone) user-guide/downloading.rst user-guide/compiling.rst @@ -27,6 +27,18 @@ HEMCO user-guide/rundir-config.rst user-guide/running.rst +.. toctree:: + :maxdepth: 2 + :caption: User Guide (GEOS-Chem) + + user-guide-gc/intro.rst + +.. toctree:: + :maxdepth: 2 + :caption: Coupling HEMCO + + coupling/intro.rst + .. toctree:: :maxdepth: 1 diff --git a/docs/source/user-guide-gc/intro.rst b/docs/source/user-guide-gc/intro.rst new file mode 100644 index 00000000..910e1b86 --- /dev/null +++ b/docs/source/user-guide-gc/intro.rst @@ -0,0 +1,9 @@ +Configuring HEMCO +================== + +Usage of HEMCO within GEOS-Chem is documented at the GEOS-Chem Wiki, in `The HEMCO User's Guide <http://wiki.seas.harvard.edu/geos-chem/index.php/The_HEMCO_User%27s_Guide>`__. + +You may also find Figure 2 in :cite:`Lin_et_al._2021` useful to understand the structure of the HEMCO configuration file, :file:`HEMCO_Config.rc`: + +.. image:: ../images/lin-et-al-2021-fig2.png + :width: 600 \ No newline at end of file diff --git a/docs/source/user-guide/rundir-config.rst b/docs/source/user-guide/rundir-config.rst index 275d1b53..26f74dc4 100644 --- a/docs/source/user-guide/rundir-config.rst +++ b/docs/source/user-guide/rundir-config.rst @@ -1,6 +1,6 @@ -Configuring a run directory +Configuring a Run Directory =========================== .. note:: @@ -30,6 +30,9 @@ HEMCO_Config.rc Contains emissions settings. This file is typically obtained from another model (e.g. GEOS-Chem). +.. note:: + An older version of the HEMCO User's Guide is available `on the GEOS-Chem Wiki <http://wiki.seas.harvard.edu/geos-chem/index.php/The_HEMCO_User%27s_Guide>`_, which includes more detailed information on configuring HEMCO emission inventories using the HEMCO configuration file, :file:`HEMCO_Config.rc`. + HEMCO_Diagn.rc Specifies which fields to save out to the HEMCO diagnostics file saved in :file:`OutputDir` by default. The frequency to save out diagnostics is controlled