<?xml version="1.0"?>
<api>
  <query-continue>
    <allpages gapcontinue="Regridding_with_GAMAP" />
  </query-continue>
  <query>
    <pages>
      <page pageid="1890" ns="0" title="Receiving updates (aka pulling)">
        <revisions>
          <rev contentformat="text/x-wiki" contentmodel="wikitext" xml:space="preserve">'''''[[Merging|Previous]] | [[Using patches to share your updates with others|Next]] | [[Guide to using Git with GEOS-Chem]]'''''

#[[Introduction to Git]]
#[[Installing Git]]
#[[First-time Git setup]]
#[[Cloning (i.e. downloading for the first time)]]
#[[Ignoring files]]
#[[Viewing the revision history]]
#[[Using Git GUI]]
#[[Branching]]
#[[Committing]]
#[[Tagging]]
#[[Merging]]
#&lt;span style=&quot;color:blue&quot;&gt;'''Receiving updates (aka pulling)'''&lt;/span&gt;
#[[Using patches to share your updates with others]]
#[[Advanced Git usage]]
#[[Git and Github tutorials]]


== Overview ==

On this page, we provide information about how you can get &quot;pull&quot; updates from the GEOS-Chem repository, or any other Git repository.

== Getting updates from the GEOS-Chem repository on Github ==

When a new GEOS-Chem version is released, we recommend that you [[#Downloading a new GEOS-Chem version|download it from our GEOS-Chem Github repository]] into a new source code folder in your disk space.

However, there may be times when patches and/or minor GEOS-Chem versions are released.  These are typically done in order to fix issues in an prior GEOS-Chem version.  If you already have an existing GEOS-Chem source code directory, you can receive these updates into your source code folder by using the '''git pull'' command, as described below.

=== Get all updated branches and tags from the GEOS-Chem remote repository ===

(1) '''Change''' into your local GEOS-Chem code directory.

 cd /path/to/my/GEOS-Chem/Code

(2) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history with Gitk''']].  You will see something similar to this:

[[Image:GitPullStep1.png]]

In this example, the '''master''' branch is checked out, which corresponds to GEOS-Chem version 12.3.2.

(3) Let's say that you need to add a new feature off of a development branch (say, '''dev/12.4.0''').  '''Pull all remote branch references''' into your local directory by typing:

 git pull

(4) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You should now see something like this:

[[Image:GitPullStep2.png]]

Note that several pointers to remote branches (beginning with '''remotes/origin''') have been added to your repository.  These remote branch references &quot;point&quot; to branches that are present at the GEOS-Chem remote repository on Github.  However, you cannot use any of these branches in your local code directory until you create local branches for them.

(5) [[Branching#Switching_between_.28aka_.22checking_out.22.29_branches|'''Create a local branch''']] for '''dev/12.4.0''' in your code directory.  Type:

 git checkout dev/12.4.0

You will see output similar to this:

 git checkout dev/12.4.0
 Checking out files: 100% (173/173), done.
 Branch 'dev/12.4.0' set up to track remote branch 'dev/12.4.0' from 'origin'.
 Switched to a new branch 'dev/12.4.0'

(6) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  Now you will see that you have a '''dev/12.4.0''' local branch&amp;mdash;which is current with the state of the code at the remote repository&amp;mdash;checked out.

[[Image:GitPullStep3.png]]

(7) [[Branching#Creating_branches|'''Create a new branch''']] off of '''dev/12.4.0''' and start adding your code updates there.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:36, 21 June 2019 (UTC)

=== Getting updates from the GEOS-Chem repository in to a particular branch ===

In the previous example, we demonstrated how to pull all remote branch references into your local source code folder.  However, this is often not necessary.  Very often you will just want to pull updates into a single branch, as demonstrated below.

(1) '''Change''' into your local GEOS-Chem code directory.

 cd /path/to/my/GEOS-Chem/Code

(2) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history with Gitk''']].  You will see something similar to this:

[[Image:GitPullStep1.png]]

(3) [[Branching#Creating_branches|'''Create a new branch''']] off of '''master''' (let's call it '''feature/MyFeature''').

(4) [[Branching#Switching_between_.28aka_.22checking_out.22.29_branches|'''Check out''']] the '''feature/MyFeature''' branch (or whatever you named it).

(5) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You should see something similar to this:

[[Image:GitPullStep4.png]]

(6) '''Pull a branch from the remote GEOS_Chem repository into the '''feature/MyFeature''' branch:

 git pull origin dev/12.4.0

You will see text similar to this:

 From github.com:geoschem/geos-chem
  * branch              dev/12.4.0 -&gt; FETCH_HEAD
 Updating 8577e970..93e8ad81
 Checking out files: 100% (173/173), done.
 Fast-forward
  GeosCore/Makefile                          |   14 +-
  GeosCore/RnPbBe_mod.F                      |   33 +-
  ...etc. -- this is the list of files that are being modified ...
 173 files changed, 12105 insertions(+), 17449 deletions(-)
 
Here, '''git pull origin''' means to pull the updates from the same repository that your GEOS-Chem source code folder was cloned from.  This will almost always be the GEOS-Chem Github repository.

(7) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You will see that the '''feature/MyFeature''' branch is now at the same commit as the '''dev/12.4.0''' branch.

[[Image:GitPullStep5.png]]

(8) At this point you can make further code edits into the '''feature/MyFeature''' branch.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:35, 21 June 2019 (UTC)

== Getting updates from a directory other than the remote GEOS-Chem Github repository ==

In some cases, you might need to pull updates from another user's GEOS-Chem source code directory.  To do this, [[#Getting updates from the GEOS-Chem repository in to a particular branch|follow Steps 1-4 in the previous section]].

Then type:

 git pull /path/to/other/Git/repository BRANCH-NAME

This will copy the updates from BRANCH-NAME in the other user's repository into your currently checked-out branch.

--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:08, 21 June 2019 (UTC)

== Further reading ==

#[https://git-scm.com/docs/git-pull ''Git pull'' (Git documentation)]
#[https://www.atlassian.com/git/tutorials/syncing/git-pull ''Git pull'' (Atlassian Git tutorial)]
#[https://guide.freecodecamp.org/git/git-pull/ ''Git pull'' (FreeCodeCamp)]


----
'''''[[Merging|Previous]] | [[Using patches to share your updates with others|Next]] | [[Guide to using Git with GEOS-Chem]]'''''</rev>
        </revisions>
      </page>
      <page pageid="571" ns="0" title="Regridding in GEOS-Chem">
        <revisions>
          <rev contentformat="text/x-wiki" contentmodel="wikitext" xml:space="preserve">On this page, we shall describe how GEOS-Chem regrids data from one resolution to another.

== The MAP_A2A algorithm ==

GEOS-Chem uses the regridding software &lt;tt&gt;MAP_A2A&lt;/tt&gt; from S-J Lin.  MAP_A2A is an area-preserving mapping scheme.  For example, if you have a quantity such as kg/m2/s or W/m2, &lt;tt&gt;MAP_A2A&lt;/tt&gt; will multiply by the area on the input grid, then regrid, and divide by the area on the output grid,  such that the total quantity is preserved.  

=== MAP_A2A was originally used to regrid GMAO met fields ===

Bob Yantosca obtained the &lt;tt&gt;MAP_A2A&lt;/tt&gt; regridding package from S-J Lin.  We have since used &lt;tt&gt;MAP_A2A&lt;/tt&gt; to regrid all of the GMAO met data products from GEOS-3 to present.

Claire Carouge tested the &lt;tt&gt;MAP_A2A&lt;/tt&gt; algorithm to ensure that it would work properly when we regrid the &quot;raw&quot; GMAO met field data.  Her comments follow:

'''''Claire Carouge wrote:'''''

&lt;blockquote&gt;
There are two types of physical quantities:

;Intensive: A quantity whose value doesn't change with the grid cell size.
;Extensive: A quantity whose value changes with the grid cell size. 

For example, if you have a uniformly distributed atmosphere and a grid and you increase the resolution by 2 (grid cells are 4 times smaller), then temperature, velocities, concentrations, pressure won't change at each grid cell but the mass will be smaller for each grid cell. So mass is an extensive variable and the others are intensives.

The &lt;tt&gt;MAP_A2A&lt;/tt&gt; algorithm is set up to regrid extensive quantities.  So in order for us to use it to regrid winds, we must first multiply the winds by the pressure on the input grid in order to create an extensive uantity (e.g. a &quot;mass flux&quot;).  Then we must divide by the pressure on the output grid to convert back to a wind.

In other regridding routines, (e.g. &lt;tt&gt;NCREGRID&lt;/tt&gt;), you can specify if the quantity you are regridding is intensive or extensive, and it will do the regridding accordingly.  I've been looking at the &lt;tt&gt;MAP_A2A&lt;/tt&gt; regridding algorithm to answer two different questions:

#&lt;p&gt;'''''Why does it look so complicated?'''''  Apparently we are using a more elaborate regridding algorithm than &lt;tt&gt;NCREGRID&lt;/tt&gt;.  It probably has some nice qualities that &lt;tt&gt;NCREGRID&lt;/tt&gt; hasn't.&lt;/p&gt;
#&lt;p&gt;'''''Is the treatment of the poles coherent with the &lt;tt&gt;TPCORE&lt;/tt&gt; advection scheme?'''''   In the regridding algorithm, there is some special treatment on the poles.  This is due to the fact, the algorithm is based on the calculation of the slopes between neighbor grid cells.  So we need different values from neighbor grid cells.  The problem with the poles is to define the grid cells &lt;tt&gt;j-1&lt;/tt&gt; (resp. &lt;tt&gt;j+1&lt;/tt&gt;) at the South Pole (resp. North Pole).  The method used in the regridding algorithm is the same than the one used in &lt;tt&gt;TPCORE&lt;/tt&gt;: to access the grid cell &lt;tt&gt;j-1&lt;/tt&gt; at South Pole you need to go southward. If you start from the cell, &lt;tt&gt;i=1&lt;/tt&gt; then you arrive in the cell &lt;tt&gt;i=im/2+1&lt;/tt&gt; (sphere). So in the code the values are &quot;crossed&quot; at the poles.  Also, they don't take the &lt;tt&gt;j=1&lt;/tt&gt; grid cells but the &lt;tt&gt;j=2&lt;/tt&gt; because the poles are supposed to be only one circular grid cell, so the points &lt;tt&gt;(i=1, j=1)&lt;/tt&gt; and &lt;tt&gt;(i=im/2+1, j=1)&lt;/tt&gt; are supposed to be the same grid cell.  So the cell &lt;tt&gt;j-1&lt;/tt&gt; is the cell &lt;tt&gt;(i=im/2+1, j=2)&lt;/tt&gt; ...&lt;br&gt;In addition, the wind values for the pole grid cells are averaged at the end. This is also coherent with tpcore as we consider the poles are one circular grid cell.&lt;/p&gt;

So I think everything is done correctly in the regridding.  The differences we see (between &lt;tt&gt;NCREGRID&lt;/tt&gt; and &lt;tt&gt;MAP_A2A&lt;/tt&gt;) are explained by the differences in algorithms used but we can't say one is better than the other.
&lt;/blockquote&gt;

--[[User:Bmy|Bob Y.]] 16:01, 28 August 2012 (EDT)

=== Modification of MAP_A2A for use within GEOS-Chem ===

'''[mailto:COOPERM2@dal.ca Matt Cooper]''' has replaced the previous GEOS-Chem regridding routines with an algorithm adapted from the [[Regridding in GEOS-Chem#The_MAP_A2A_algorithm|&lt;tt&gt;MAP_A2A&lt;/tt&gt; regridding package]] (developed by S.-J. Lin and refined by Bob Yantosca).  The previous GEOS-Chem regridding routines sometimes involved two separate regridding processes, passing through the [[GEOS-Chem_horizontal_grids#Generic_1_x_1_grid|GEOS 1&amp;deg; x 1&amp;deg; grid]], which could lead to loss of information.  The &lt;tt&gt;MAP_A2A&lt;/tt&gt; algorithm regrids emissions from any arbitrary horizontal grid to the current model resolution.

&lt;tt&gt;MAP_A2A&lt;/tt&gt; was introduced into GEOS-Chem v9-01-03 (and tested with 1-month benchmark [[GEOS-Chem v9-01-03 benchmark history#v9-01-03k|'''v9-01-03k''']], which was approved on 27 Apr 2012.

'''''[mailto:psk9@duke.edu Prasad Kasibhatla] wrote:'''''

&lt;blockquote&gt;
I discovered that the MAP_A2A gridding algorithm was smearing emissions incorrectly (though not in a major way) - seems to arise from mapping based on some sort of piecewise polynomial interpolation between grids, rather than simply using area-overlap fractions to apportion grid-average fluxes from old to new grid.

I put in a pretty simple fix.  I basically modified the &lt;tt&gt;XMAP&lt;/tt&gt; and &lt;tt&gt;YMAP&lt;/tt&gt; routines and got rid of all the other subroutine calls - the calling sequence is the same so I suspect it should be pretty easy for you to modify &lt;tt&gt;MAP_A2A&lt;/tt&gt;.

A couple of words of caution:

#&lt;p&gt;My fix only works for regular lat-lon grids because it uses &amp;Delta;( longitude ) and &amp;Delta;( SIN(latitude) ) to do the regridding&lt;/p&gt;
#&lt;p&gt;My fix is exact for cases where you are regridding grid-average quantities (eg gridded emission fields), but I would do it differenty if I were regridding quantities that implicitly had sub-grid variation (eg if one assumes that a variable represents the center of a grid box and that there is a linear variation from one grid box center to another.&lt;/p&gt;
#&lt;p&gt;You might also be interested in how I set it up so it handles nested grids correctly. I created new functions called &lt;tt&gt;GET_IIIPAR&lt;/tt&gt; and &lt;tt&gt;GET_JJJPAR&lt;/tt&gt; (in &lt;tt&gt;GeosUtil/global_grid_mod.F90&lt;/tt&gt; that I use in regridding on a global grid, and then use &lt;tt&gt;GET_XOFFSET&lt;/tt&gt; and &lt;tt&gt;GET_YOFFSET&lt;/tt&gt; to cut out the nested grid portion.&lt;/p&gt;
&lt;/blockquote&gt;

--[[User:Bmy|Bob Y.]] 15:50, 28 August 2012 (EDT)</rev>
        </revisions>
      </page>
    </pages>
  </query>
</api>