.. _cfg-hco-cfg: ############### HEMCO_Config.rc ############### GEOS-Chem Classic relies on the `Harmonized Emissions Component (aka HEMCO) `_ for file I/O, regridding, and computing emissions fluxes. Settings for HEMCO can be updated in the `HEMCO configuration file `_, which is named :file:`HEMCO_Config.rc`. The HEMCO online manual at `hemco.readthedocs.io `_ contains detailed instructions about the structure and contents of :file:`HEMCO_Config.rc`, so we will not replicate that content in this Guide. Instead, we will provide a short summary with links to the relevant documentation. .. _cfg-hco-cfg-settings: ====================== General HEMCO settings ====================== Define general simulation parameters in the `Settings section `_ of :file:`HEMCO_Config.rc`. This includes data paths, global diagnostic options, and verbose output options. .. code-block:: kconfig ############################################################################### ### BEGIN SECTION SETTINGS ############################################################################### ROOT: /path/to/hemco/data/dir METDIR: /path/to/hemco/met/dir GCAPSCENARIO: not_used GCAPVERTRES: 47 Logfile: * DiagnFile: HEMCO_Diagn.rc DiagnPrefix: ./OutputDir/HEMCO_diagnostics DiagnFreq: 00000000 010000 Wildcard: * Separator: / Unit tolerance: 1 Negative values: 0 Only unitless scale factors: false Verbose: false VerboseOnCores: root # Accepted values: root all ### END SECTION SETTINGS ### .. _cfg-hco-cfg-extswitches: ================== Extension switches ================== Turn individual emissions inventories on/off in the `Extension Switches section `_ of :file:`HEMCO_Config.rc`. Emission inventories are specified as either `Base Emissions `_ (i.e. read from files on disk) or `Extensions `_ (i.e. computed using meteorological inputs). .. code-block:: kconfig ############################################################################### ### BEGIN SECTION EXTENSION SWITCHES ############################################################################### # ExtNr ExtName on/off Species Years avail. 0 Base : on * # ----- MAIN SWITCHES --------------------------------------------------------- --> EMISSIONS : true --> METEOROLOGY : true --> CHEMISTRY_INPUT : true # ----- RESTART FIELDS -------------------------------------------------------- --> GC_RESTART : true --> HEMCO_RESTART : true # ----- NESTED GRID FIELDS ---------------------------------------------------- --> GC_BCs : false # ----- REGIONAL INVENTORIES -------------------------------------------------- --> APEI : false # 1989-2014 --> NEI2016_MONMEAN : false # 2002-2020 --> DICE_Africa : false # 2013 # ----- GLOBAL INVENTORIES ---------------------------------------------------- --> CEDSv2 : true # 1750-2019 --> CEDS_GBDMAPS : false # 1970-2017 --> CEDS_GBDMAPS_byFuelType: false # 1970-2017 ... etc ... # ----------------------------------------------------------------------------- 100 Custom : off - 101 SeaFlux : on DMS/ACET/ALD2/MENO3/ETNO3/MOH 102 ParaNOx : on NO/NO2/O3/HNO3 --> LUT data format : nc --> LUT source dir : $ROOT/PARANOX/v2015-02 103 LightNOx : on NO --> CDF table : $ROOT/LIGHTNOX/v2014-07/light_dist.ott2010.dat 104 SoilNOx : on NO --> Use fertilizer NOx : true ... etc ... ### END SECTION EXTENSION SWITCHES ### .. _cfg-hco-base: ============== Base emissions ============== .. note:: You do not have to edit this section if you just wish to run GEOS-Chem Classic with its default emissions configuration. But if your simulation start date does not match the date of the :ref:`restart file `, or if you simulation contains species not found in the restart file, then you must edit the restart file entry :ref:`as described below `. Specify how emissions and other data sets will be read from disk in the `Base Emissions section `_ of :file:`HEMCO_Config.rc`. .. code-block:: kconfig ############################################################################### ### BEGIN SECTION BASE EMISSIONS ############################################################################### # ExtNrName sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Species ScalIDs Cat Hier (((EMISSIONS ... etc ... #============================================================================== # --- CEDS_01x01 --- # # %%% This is the default global inventory. %%% # %%% You may select either CEDS, EDGAR, HTAP or CMIP6_SFC_LAND_ANTHRO %%% # %%% for the global base emissions. %%% #============================================================================== (((CEDS_01x01 0 CEDS_NO_AGR $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_agr 1980-2019/1-12/1/0 C xy kg/m2/s NO 2401 1 5 0 CEDS_NO_ENE $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_ene 1980-2019/1-12/1/0 C xyL* kg/m2/s NO 2401/706/315 1 5 0 CEDS_NO_IND $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_ind 1980-2019/1-12/1/0 C xyL* kg/m2/s NO 2407/707/316 1 5 0 CEDS_NO_TRA $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_tra 1980-2019/1-12/1/0 C xy kg/m2/s NO 2411/711 1 5 0 CEDS_NO_RCO $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_rco 1980-2019/1-12/1/0 C xy kg/m2/s NO 2409/709 1 5 0 CEDS_NO_SLV $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_slv 1980-2019/1-12/1/0 C xy kg/m2/s NO 2407/707 1 5 0 CEDS_NO_WST $ROOT/CEDS/v2024-06/$YYYY/CEDS_NO_0.1x0.1_$YYYY.nc NO_wst 1980-2019/1-12/1/0 C xy kg/m2/s NO 25 1 5 ... etc ... ### END SECTION BASE EMISSIONS ### .. _cfg-hco-base-gcc-rst: GEOS-Chem Classic restart input via HEMCO ----------------------------------------- If your GEOS-Chem Classic simulation is configured to `read the restart file via HEMCO `_, then your simulation will stop by default if: #. The start date of your simulation does not match the restart file's internal timestamp (as specified by the :literal:`time:units` netCDF attribute). #. The restart file does not contain all of the species used by your simulation. But you may force the simulation to proceed as follows. First, for the :literal:`SPC_` entry in your :file:`HEMCO_Config.rc` file. This may be found in the NON-EMISSIONS DATA subsection under the BASE EMISSIONS section: .. code-block:: kconfig * SPC_ ./Restarts/GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL? $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1 Next, change the :literal:`EFYO` to either :literal:`CYS` or :literal:`EY` (both will work). .. code-block:: kconfig * SPC_ ./Restarts/GEOSChem.Restart.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesRst_?ALL? $YYYY/$MM/$DD/$HH CYS xyz 1 * - 1 1 This will allow your simulation to proceed without stopping. .. _cfg-hco-scalefac: ============= Scale factors ============= Define scale factors for emissions inventories and other data sets in the `Scale Factors section `_ of :file:`HEMCO_Config.rc`. .. code-block:: kconfig #============================================================================== # --- Scale factors used for species conversions --- #============================================================================== # Units carbon to species conversions # Factor = # carbon atoms * MW carbon) / MW species 40 CtoACET MATH:58.09/(3.0*12.0) - - - xy unitless 1 41 CtoALD2 MATH:44.06/(2.0*12.0) - - - xy unitless 1 42 CtoALK4 MATH:58.12/(4.3*12.0) - - - xy unitless 1 ... etc ... # VOC speciations (((RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 50 KET2MEK 0.25 - - - xy unitless 1 51 KET2ACET 0.75 - - - xy unitless 1 )))RCP_3PD.or.RCP_45.or.RCP_60.or.RCP_85 ... etc ... ### END SECTION SCALE FACTORS ### .. _masks: ===== Masks ===== Define masks for emissions and other data sets in the `Masks section `_ of :file:`HEMCO_Config.rc` .. code-block:: kconfig ############################################################################### ### BEGIN SECTION MASKS ############################################################################### # ScalID Name sourceFile sourceVar sourceTime C/R/E SrcDim SrcUnit Oper Lon1/Lat1/Lon2/Lat2 (((EMISSIONS #============================================================================== # Country/region masks #============================================================================== (((APEI 1002 CANADA_MASK $ROOT/MASKS/v2018-09/Canada_mask.geos.1x1.nc MASK 2000/1/1/0 C xy 1 1 -141/40/-52/85 )))APEI (((NEI2016_MONMEAN 1007 CONUS_MASK $ROOT/MASKS/v2018-09/CONUS_Mask.01x01.nc MASK 2000/1/1/0 C xy 1 1 -140/20/-50/60 )))NEI2016_MONMEAN ... etc ... )))EMISSIONS ### END SECTION MASKS ### ### END OF HEMCO INPUT FILE ### .. _cfg-hco-gchp-gcc: ==================================================== Usage differences between GCHP and GEOS-Chem Classic ==================================================== :file:`HEMCO_Config.rc` is used in GCHP for masking and scaling within HEMCO. The input file and read frequency information is not used because MAPL ExtData handles file input rather than HEMCO in GCHP. Items at the top of the file that are ignored include: * :literal:`ROOT` data directory path * :literal:`METDIR` path * :literal:`DiagnPrefix` * :literal:`DiagnFreq` * :literal:`Wildcard` The :literal:`ROOT` data directory and :literal:`METDIR` paths are instead specified by the symbolic links in the run directory. Diagnostic filename and frequency information are specified in :file:`HISTORY.rc`. Emissions diagnostics in GCHP are output in the same way and with the same file format as other diagnostic collections in GCHP. Please note, however, that all emissions diagnostics are vertically flipped relative to other diagnostics, with level 1 corresponding to top-of-atmosphere. In the :ref:`cfg-hco-base` section and beyond, columns that are ignored include: * :literal:`sourceFile` * :literal:`sourceVar` * :literal:`sourceTime` * :literal:`C/R/E` * :literal:`SrcDim` * :literal:`SrcUnit` Because GCHP uses NASA MAPL code to read and regrid input files the file path, variable name, and data frequency are specified in GCHP config file :file:`ExtData.rc`. Input data dimensions and units are not needed since they are taken directly from the file during read. Note that some GEOS-Chem simulations require that all species be present in the restart file. For GEOS-Chem Classic you can get around this by updating the :literal:`C/R/E` flags in :file:`HEMCO_Config.rc`. In GCHP that part of :file:`HEMCO_Config.rc` is not used. To configure your run to allow missing species in the restart file you instead need to flip a switch in config file :file:`setCommonRunSettings.sh`. Search for string :literal:`Require_Species_in_Restart` in the file. If set to 1 it will require species, and if set to 0 it will not. Also beware that one entry in :file:`HEMCO_Config.rc` is changed when script :file:`setCommonRunSettings.sh` is executed in the run script prior to running GCHP. The online dust mass tuning factor gets replaced by a value specific to your configured grid resolution. One entry also gets propagated to another configuration file by :file:`setCommonRunSettings.sh`. Lightning entries in :file:`ExtData.rc` get commented or uncommented depending on whether lightning climatology is turned on in :file:`HEMCO_Config.rc`.