Difference between revisions of "Interfacing HEMCO into GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(How HEMCO connects to GEOS-Chem)
(Replaced content with "This content has been migrated to the [https://hemco.readthedocs.io/en/latest/coupling/intro.html '''Coupling HEMCO to other models''' chapter of <tt>hemco.readthedocs.io<...")
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
<div style="color: #aa0000; background: #eeeeee;border: 3px solid red; padding: 1em; margin: auto; width: 90%; ">'''<p>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.</p><p>&mdash; Bob Yantosca, 28 May 2014</p>'''</div>
+
This content has been migrated to the [https://hemco.readthedocs.io/en/latest/coupling/intro.html '''Coupling HEMCO to other models''' chapter of <tt>hemco.readthedocs.io</tt>].
 
+
 
+
== HEMCO is implemented into GEOS-Chem as a git subtree ==
+
 
+
'''''[[User:Christoph_Keller|Christoph Keller]] wrote:'''''
+
 
+
<blockquote>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.</blockquote>
+
 
+
=== 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).
+
 
+
'''''[[User:Christoph_Keller|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!
+
 
+
--[[User:Bmy|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:
+
#The <tt>-P</tt> option specifies the subdirectory of <tt>Code.v10-01</tt> into which to pull the updates from the separate HEMCO repository.
+
#The <tt>--squash</tt> option "squashes" the git history of the source code into a single commit.  Otherwise, the full history will be imported.
+
#The <tt>-m</tt> option specifies the commit message that will show up in the revision history.
+
 
+
--[[User:Bmy|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:
+
#The <tt>-P</tt> option specifies the subdirectory of <tt>Code.v10-01</tt> into which to pull the updates from the separate HEMCO repository.
+
#The <tt>-b</tt> lets you specify the branch name in the remote HEMCO repository into which the updates will be sent.
+
 
+
--[[User:Bmy|Bob Y.]] 13:52, 28 July 2014 (EDT)
+
 
+
=== References ===
+
 
+
Here are some helpful articles that describe how the Git subtree process works:
+
 
+
#http://psionides.eu/2010/02/04/sharing-code-between-projects-with-git-subtree/
+
#http://makingsoftware.wordpress.com/2013/02/16/using-git-subtrees-for-repository-separation/
+
#http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/
+
#https://help.github.com/articles/about-subtree-merges
+
#https://hpc.uni.lu/blog/2014/understanding-git-subtree/
+
#http://blog.charlescy.com/blog/2013/08/17/git-subtree-tutorial/
+
#https://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html
+
 
+
--[[User:Bmy|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.
+
 
+
'''''[[User:Christoph_Keller|Christoph Keller]] wrote:'''''
+
 
+
<blockquote>All HEMCO extensions are called through the extension interface routines in <tt>HEMCO/Extensions/hcox_driver_mod.F90</tt>: <tt>HCOX_INIT</tt>, <tt>HCOX_RUN</tt>, <tt>HCOX_FINAL</tt>. 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 <tt>HcoState</tt> and the extensions state object <tt>ExtState</tt>.</blockquote>
+
 
+
<blockquote><tt>ExtState</tt> is defined in <tt>HEMCO/Extensions/hcox_state_mod.F90</tt>. 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 <tt>SET_EXTOPT_FIELDS</tt> in <tt>GeosCore/hcoi_gc_main_mod.F90</tt>).</blockquote>
+
 
+
<blockquote>The initialization call (<tt>HCOX_XXX_INIT</tt>) 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 <tt>HEMCO/Extensions/hco_extlist_mod.F90</tt> to do this:</blockquote>
+
 
+
:#<tt>GetExtNr( ExtName )</tt> returns the extension number for the given extension name. Will return –1 if extension is turned off!
+
:#<tt>GetExtOpt( ExtNr, Attribute, Value, RC )</tt> 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, …).
+
:#<tt>GetExtHcoID( HcoState, ExtNr, HcoIDs, SpcNames, nSpc, RC )</tt> 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 <tt>ExtState</tt> 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 <tt>ExtState%TK%DoUse = .TRUE.</tt>
+
 
+
<blockquote>The run call (<tt>HCOX_XXX_RUN</tt>) calculates the 2D fluxes and passes them to HcoState via subroutine <tt>HCO_EmisAdd( HcoState, Flux, HcoID, RC)</tt>. External data is assessed through <tt>ExtState</tt> (e.g. <tt>ExtState%TX%Arr%Val(I,J,L)</tt>), and any data automatically read from netCDF files (through the HEMCO interface) can be obtained through <tt>EmisList_GetDataArr( am_I_Root, FieldName, Pointer, RC )</tt>. The body of the run routine is typically just the code of the original module.</blockquote>
+
 
+
<blockquote>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.</blockquote>
+
 
+
--[[User:Bmy|Bob Y.]] 17:40, 28 July 2014 (EDT)
+

Latest revision as of 18:23, 10 August 2022

This content has been migrated to the Coupling HEMCO to other models chapter of hemco.readthedocs.io.