Interfacing HEMCO into GEOS-Chem

From Geos-chem
Jump to: navigation, search

This page is intended for advanced HEMCO developers. Most GEOS-Chem users will not have to use these commands, as the latest HEMCO updates will be included when you clone or pull from the standard GEOS-Chem repository.

HEMCO is implemented into GEOS-Chem as a git subtree

Christoph Keller wrote:

GEOS-Chem now contains the HEMCO folder as a git subtree. This means that I "outsourced" the HEMCO code into an own git repo and added this repository as a subtree to GEOS-Chem. There are no changes for people working on GEOS-Chem. It is still possible to modify, commit, pull, etc. the entire GC repository including the HEMCO subtree. However, it is now easily possible to update the HEMCO subtree with changes made in the HEMCO source repository, and to synchronize changes made from within the external HEMCO repository. Some more details on the subtree are given below.

Creating a subtree for HEMCO in the GEOS-Chem source code directory

Christoph Keller used the following procedure to create the HEMCO subtree in GEOS-Chem. He also stored the HEMCO source code in an external repository (public location TBD).

Christoph Keller wrote:

1. Create subtree of HEMCO code in GC repo
   cd Code.v10-01                        # or whatever your GEOS-Chem code dir is named
   git subtree split -P HEMCO -b export
2. Import subtree into new repo (this is the new HEMCO source code)
   cd /home/ckeller/HEMCO/src/
   git init
   git fetch ../Code.v10-01 export
   git checkout -b master FETCH_HEAD
3. Add HEMCO code as new remote to GC
   cd Code.v10-01
   git remote add hemco /home/ckeller/HEMCO/src/.git
   git fetch hemco
4. Remove existing HEMCO code from GC repo
   git rm -r HEMCO
   git commit -m "Remove HEMCO from GEOS-Chem. Will be imported as subtree"
5. Add HEMCO as subtree
   git subtree add -P HEMCO -m "Readded HEMCO as subtree"  hemco/master
Done!

--Bob Y. 14:05, 28 July 2014 (EDT)

Pulling updates from the external HEMCO repository into GEOS-Chem

To pull the newest changes from the external HEMCO repository into GEOS-Chem, follow these instructions:

cd Code.v10-01    # or whatever your GEOS-Chem code dir is named
git fetch hemco
git subtree merge -P HEMCO --squash -m "merged changes from HEMCO" hemco/master

NOTES:

  1. The -P option specifies the subdirectory of Code.v10-01 into which to pull the updates from the separate HEMCO repository.
  2. The --squash option "squashes" the git history of the source code into a single commit. Otherwise, the full history will be imported.
  3. The -m option specifies the commit message that will show up in the revision history.

--Bob Y. 13:52, 28 July 2014 (EDT)

Pushing changes made to HEMCO in GEOS-Chem back to the external HEMCO repository

If you updated the HEMCO code in GEOS-Chem, and want to send those updates back to the external HEMCO repository, follow this procedure:

To bring changes made in GEOS-Chem (/home/ckeller/geosChem/v10-01c/hemco/Code.v10-01c/HEMCO) into the source code (/home/ckeller/HEMCO/src/):

cd /home/ckeller/geosChem/v10-01c/hemco/Code.v10-01c/
git subtree split -P HEMCO -b update
git push hemco update:master

NOTES:

  1. The -P option specifies the subdirectory of Code.v10-01 into which to pull the updates from the separate HEMCO repository.
  2. The -b lets you specify the branch name in the remote HEMCO repository into which the updates will be sent.

--Bob Y. 13:52, 28 July 2014 (EDT)

References

Here are some helpful articles that describe how the Git subtree process works:

  1. http://psionides.eu/2010/02/04/sharing-code-between-projects-with-git-subtree/
  2. http://makingsoftware.wordpress.com/2013/02/16/using-git-subtrees-for-repository-separation/
  3. http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/
  4. https://help.github.com/articles/about-subtree-merges
  5. https://hpc.uni.lu/blog/2014/understanding-git-subtree/
  6. http://blog.charlescy.com/blog/2013/08/17/git-subtree-tutorial/
  7. https://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html

--Bob Y. 14:03, 28 July 2014 (EDT)

Adding new HEMCO extensions into GEOS-Chem

Here is a quick guide on how to add new HEMCO extensions into GEOS-Chem:

Christoph Keller wrote:

All HEMCO extensions are called through the extension interface routines in HEMCO/Extensions/hcox_driver_mod.F90: HCOX_INIT, HCOX_RUN, 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 HcoState and the extensions state object ExtState.
ExtState is defined in HEMCO/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 SET_EXTOPT_FIELDS in GeosCore/hcoi_gc_main_mod.F90).
The initialization call (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 HEMCO/Extensions/hco_extlist_mod.F90 to do this:
  1. GetExtNr( ExtName ) returns the extension number for the given extension name. Will return –1 if extension is turned off!
  2. 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 (logical, character, double, …).
  3. 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.
  4. All 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 ExtState%TK%DoUse = .TRUE.
The run call (HCOX_XXX_RUN) calculates the 2D fluxes and passes them to HcoState via subroutine HCO_EmisAdd( HcoState, Flux, HcoID, RC). External data is assessed through ExtState (e.g. ExtState%TX%Arr%Val(I,J,L)), and any data automatically read from netCDF files (through the HEMCO interface) can be obtained through EmisList_GetDataArr( am_I_Root, FieldName, Pointer, RC ). The body of the run routine is typically just the code of the original module.
This may all sound a little bit complicated, but I hope it's pretty straightforward once you get used to the concept! It's probably easiest to start from an existing extension.

--Bob Y. 17:40, 28 July 2014 (EDT)