Merge branch 'docs/dev' into dev/3.6.0

CHANGELOG.md

@@ -8,13 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased 3.6.0]
 ### Added
   - Added MAPL_ESMF compiler option for use with GCHP and GEOS
+  - New "Parallelize GEOS-Chem and HEMCO source code" guide on ReadTheDocs
+  - Updated documentation describing a masking error that can happen when performing simulations with cropped horizontal grids
 
 ### Changed
   - Set HCO_MISSVAL to MAPL missing value (1e15) if using GCHP or GEOS
   - Use fraction surface type inputs instead of ExtState%WLI
+  - The version number in docs/source/conf.py is now 3.6.0
+  - Updated compilation output splash screen in compiling.rst ReadTheDocs file
 
 ### Fixed
-  - placeholder
+  - Bug fix for inserting hard breaks in hemco-config.rst ReadTheDocs file
 
 ### Removed
   - Removed old kludge for MAPL missing data if applying mask

docs/source/conf.py

@@ -23,7 +23,7 @@
 author = 'GEOS-Chem Support Team'
 
 # The full version, including alpha/beta/rc tags
-release = '3.5.2'
+release = '3.6.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/hco-ref-guide/extensions.rst

@@ -587,3 +587,63 @@ Extensions supporting built-in scaling/masking
 
 The following extensions currently support the built-in scaling/masking
 tools: :option:`SoilNOx`, :option:`GFED`, :option:`FINN`.
+
+===========================
+Adding new HEMCO extensions
+===========================
+
+All HEMCO extensions are called through the extension interface
+routines in :file:`HEMCO/Extensions/hcox_driver_mod.F90`:
+:code:`HCOX_INIT`, :code:`HCOX_RUN`, :code:`HCOX_FINAL`. For
+every new extension, a corresponding subroutine call needs to be added
+to those three routines.  You will quickly see that these calls only
+take a few arguments, most importantly the HEMCO state object
+:code:`HcoState` and the extensions state object :code:`ExtState`.
+
+:code:`ExtState` is defined in
+:file:`HEMCO/src/Extensions/hcox_state_mod.F90`. It contains logical
+switches for each extension as well as pointers to any external data
+(such as met fields). For a new extension, you'll have to add a new
+logical switch to the Ext_State object. If you need external data that
+is not yet included in ExtState, you will also have to add those
+(including the pointer associations in subroutine
+:code:`SET_EXTOPT_FIELDS` in
+:file:`GeosCore/hco_interface_gc_mod.F90`.
+
+The initialization call (:code:`HCOX_XXX_INIT`) should be used to
+initialize all extension variables and to read all settings from the
+HEMCO configuration file. There are a number of helper routines in
+:file:`HEMCO/src/Extensions/hco_extlist_mod.F90` to do this:
+
+- :code:`GetExtNr( ExtName )` returns the extension number for the
+  given extension name. Will return –1 if extension is turned off!
+
+- :code:`GetExtOpt( ExtNr, Attribute, Value, RC )` can be used to read
+  any additional extension options (logical switches, path and names
+  of csv-tables, etc.). Note that value can be of various types
+  (:code:`logical`, :code:`character`, :code:`double`,...).
+
+- :code:`GetExtHcoID( HcoState, ExtNr, HcoIDs, SpcNames, nSpc, RC )`
+  matches the extension species names (as defined in the configuration
+  file) to the species defined in HEMCO state (i.e. to all available
+  HEMCO species). A value of –1 is returned if the given species is
+  not defined in HEMCO.
+
+All :code:`ExtState` variables used by this extension should be
+updated. This includes the logical switch and all external data needed
+by the extension. For example, if the extension needs temperature
+data, this pointer should be activated by setting
+:code:`ExtState%TK%DoUse = .TRUE.`
+
+The run call (:code:`HCOX_XXX_RUN`) calculates the 2D fluxes and
+passes them to HcoState via subroutine :code:`HCO_EmisAdd( HcoState,
+Flux, HcoID, RC)`. External data is assessed through :code:`ExtState`
+(e.g. :code:`ExtState%TX%Arr%Val(I,J,L)`), and any data automatically
+read from netCDF files (through the HEMCO interface) can be obtained
+through :code:`EmisList_GetDataArr( am_I_Root, FieldName, Pointer,
+RC )` The body of the run routine is typically just the code of the
+original module.
+
+It's probably easiest to start from an existing extension (or the
+:file:`Custom` extension template) and to add any modifications as is
+needed.

docs/source/hco-ref-guide/hemco-config.rst

@@ -1,4 +1,4 @@
-.. |br| raw:: html:
+.. |br| raw:: html
 
    <br />
 
@@ -1229,6 +1229,84 @@ degrees east, latitudes in degrees north. Only grid boxes whose mid
 points are within the specified mask boundaries.  You may also specify
 a single grid point (:literal:`Lon1/Lat1/Lon1/Lat1/`).
 
+.. _hco-cfg-masks-caveat:
+
+Caveat for simulations using cropped horizontal grids
+-----------------------------------------------------
+
+Consider the following combination of global and regional
+emissions inventories:
+
+In the :ref:`Base Emissions <hco-cfg-base>` section:
+
+.. code-block:: kconfig
+
+   0 GLOBAL_INV_SPC1   ...  SPC1 -     1 5
+   0 INVENTORY_1_SPC1  ...  SPC1 1001  1 56
+   0 INVENTORY_2_SPC1  ...  SPC1 1002  1 55
+
+In the :ref:`Masks <hco-cfg-masks>` section:
+
+.. code-block:: kconfig
+
+   1001 REGION_1_MASK ... 1 1 70/10/140/60
+   1002 REGION_2_MASK ... 1 1 46/-12/180/82
+
+For clarity, we have omitted the various elements in these entries of
+:file:`HEMCO_Config.rc` that are irrelevant to this issue.
+
+With this setup, we should expect the following behavior:
+
+   #. Species :literal:`SPC1` should be emitted globally from inventory
+      :literal:`GLOBAL_INV` (hierarchy = 5). |br|
+      |br|
+
+   #. Regional emissions of :literal:`SPC1` from
+      :literal:`INVENTORY_1` (hierarchy = 56) should overwrite global
+      emissions in the region specified by :literal:`REGION_1_MASK`. |br|
+      |br|
+
+   #. Likewise, regional emissions of :literal:`SPC1` from
+      :literal:`INVENTORY_2` (hierarchy = 55) should overwrite global
+      emissions in the region specified by :literal:`REGION_2_MASK`. |br|
+      |br|
+
+   #. In the locations where :literal:`REGION_2_MASK` intersects
+      :literal:`REGION_1_MASK`, emissions from
+      :literal:`INVENTORY_1` will be applied. This is because
+      :literal:`INVENTORY_1` has a higher hierarchy (56) than
+      :literal:`INVENTORY_2` (55).
+
+When running simulations that use cropped grids, one or both of the
+boundaries specified for the masks (:literal:`70/10/140/60` and
+:literal:`46/-12/180/82`) in :file:`HEMCO_Config.rc` can potentially
+extend beyond the bounds of the simulation domain.  If this should
+happen, HEMCO would treat the regional inventories as if they were
+global, the emissions for the highest hierarchy (i.e.,
+:literal:`INVENTORY_1`) would be applied globally. Inventories with
+lower hierarchies would be ignored.
+
+.. tip::
+
+   Check the HEMCO log output for messages to make sure that none of
+   your desired emissions have been skipped.
+
+The solution is to make the boundaries of each defined mask region at least
+a little bit smaller than the boundaries of the nested domain. This
+involves inspecting the mask itself to make sure that no relevant
+gridboxes will be excluded.
+
+For example, assuming the simulation domain extends from 70E to 140E
+in longitude, using this mask definition:
+
+.. code-block:: kconfig
+
+   1001 REGION_1_MASK ... 1 1 70/10/136/60
+
+would prevent :literal:`INVENTORY_1` from being mistakely treated as a
+global inventory. We hope to add improved error checking for this
+condition into a future HEMCO version.
+
 .. _hco-cfg-data-coll:
 
 ================

docs/source/hco-sa-guide/compiling.rst

@@ -107,7 +107,7 @@ You will see output similar to this:
    -- Checking whether /path/to/gfortran supports Fortran 90 - yes
    =================================================================
    HEMCO X.Y.Z
-   Current status: X.Y.Z-g54e2b03
+   Current status: X.Y.Z
    =================================================================
    -- Found OpenMP_Fortran: -fopenmp (found version "4.5")
    -- Found OpenMP: TRUE (found version "4.5")

docs/source/index.rst

@@ -68,6 +68,7 @@ HEMCO is given in :cite:t:`Keller_et_al._2014` and
 
    geos-chem-shared-docs/supplemental-guides/libraries.rst
    geos-chem-shared-docs/supplemental-guides/spack.rst
+   geos-chem-shared-docs/supplemental-guides/parallel-guide.rst
    geos-chem-shared-docs/supplemental-guides/debug-guide.rst
    geos-chem-shared-docs/supplemental-guides/bashdatacatalog.rst
    geos-chem-shared-docs/supplemental-guides/netcdf-guide.rst