View source for Downloading GCHP v12

__FORCETOC__
'''''[[GCHP_Hardware_and_Software_Requirements|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started With GCHP]] | [[GCHP Main Page]]'''''
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
#<span style="color:blue">'''Downloading Source Code and Data Directories'''</span>
#[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
#[[Compiling_GCHP|Compiling]]
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
#[[GCHP_Output_Data|Output Data]]
#[[Developing_GCHP|Developing GCHP]]
#[[GCHP_Run_Configuration_Files|Run Configuration Files]]
<br>

Please note that documentation on this page primarily reflects the latest GCHP public release which is currently the GCHP 12 series. The documentation will be updated for the GCHP 13.0.0 release over the coming months.

== Overview ==

GCHP is built to wrap around a standard GEOS-Chem Classic installation. The first step to obtaining GCHP is therefore to clone the standard GEOS-Chem source code repository. Enabling GCHP functionality simply involves the added step of cloning the GCHP source code repository to store as a subdirectory within GEOS-Chem.

Acquiring the GCHP subdirectory does not change anything in the standard GEOS-Chem code; you can use the same source code to run regular non-GCHP GEOS-Chem simulations. However, we recommend that you keep separate GEOS-Chem source code directories for use with GCHP and GEOS-Chem Classic, e.g. <code>Code.gchp</code> and <code>Code.gcc</code>. This avoids confusion and extra work since each requires separate compilation. Using git, you can exchange GEOS-Chem code between the two GEOS-Chem repository clones even when the GCHP clone is in one and not the other.

Please note that certain files in GEOS-Chem Classic source code will be present but ignored when running GCHP. Most notably this includes <code>GeosCore/main.F</code>, all advection code, and everything in the <code>History</code> folder.

==Step 1: Download GEOS-Chem==

Clone or fork ('''recommended''') the GEOS-Chem repository located at [https://github.com/geoschem/geos-chem https://github.com/geoschem/geos-chem]. Forking is a simple tool to acquire a copy of the repository in your own GitHub account. You can then clone that copy from your own account rather than from the GEOS-Chem GitHub. The advantage of this is that you have push permissions to send updates to GitHub for back-up storage, you can access and share your code publicly, and you can do pull requests to transfer your updates to the GEOS-Chem Support Team for inclusion in the standard model. Create a fork by simply clicking <code>fork</code> in the upper right corner of the GEOS-Chem GitHub page while logged into your account.

If you are cloning from the GEOS-Chem GitHub directly:

 git clone https://github.com/geoschem/geos-chem.git Code.gchp

If you are cloning a fork from your own GitHub account you must give the path to your fork by replacing username below with your GitHub username:

 git clone https://github.com/username/geos-chem.git Code.gchp

Take note of the path where the code was downloaded. You can name your cloned repository anything you would like.

==Step 2: Download GCHP within GEOS-Chem==

Navigate to your GEOS-Chem code directory that you just downloaded and clone the GCHP repository from Github located at [https://github.com/geoschem/gchp https://github.com/geoschem/gchp]. As with GEOS-Chem, you can fork the GCHP repository and clone it from your GitHub account if you wish. Below is an example of cloning from the GEOS-Chem GitHub.

 cd Code.gchp
 git clone https://github.com/geoschem/gchp.git GCHP

While you can name your GEOS-Chem source code directory whatever you like, you must name the GCHP directory <code>GCHP</code>.

==Step 3: Choose version==

When you clone GEOS-Chem and GCHP you will always get the master branch. This is always the [[GEOS-Chem_12#Current_stable_version|current stable version of GEOS-Chem]]. You can determine the version label by typing <tt>git log --decorate</tt> within each repository and looking at the git tag string printed for the top-most commit. Always be sure that the versions you have in the two repositories are compatible. 

[[File:gchp Gittag.png|800px|thumb|Example output of git log. Notice tag name at top indicating what version this is.]]

If you would like an earlier version you can checkout the version tag for that specific version in both the <tt>GEOS-Chem</tt> and <tt>GCHP</tt> repositories. To see a list of available tags for a repository type <tt>git tag</tt>. To checkout a tagged version type <tt>git checkout tags/tagname</tt>.

When you checkout a tag beware that you will be in what is called a detached HEAD status. This means you are not officially on a git branch. Committing in this state risks losing your changes since they are not associated with an actual git branch. If you plan on developing code in the version you checkout you should therefore create a branch to work in: <tt>git checkout -b mybranch</tt>. However, we request that new updates always be built off of the master branch that is current at the time you begin work. We further recommend that you pull in future version updates as they are released.

If you are in doubt about how to use git with GEOS-Chem please contact the [[GEOS-Chem_Support_Team|GEOS-Chem Support Team]] for help.

==Step 4: Download Shared Data Directories==

Steps for downloading data directories used in GCHP are the same as for GEOS-Chem Classic. Please see [[Downloading GEOS-Chem data directories]] for instructions and resources. See also the GEOS-Chem version information on the wiki for a list of new data directories required per version. For example, new data directories added for GEOS-Chem 12.5.0 are located [[GEOS-Chem_12#New_data_directories_in_12.5.0|here]].

'''Note on GCHP versions prior to 12.5.0'''
GCHP versions prior to 12.5.0 require that you also download directory <tt>ExtData/GCHP/TileFiles</tt>. This contains files for mapping between lat-lon and cubed sphere grids and is available from the Harvard ftp server (<tt>ftp.as.harvard.edu</tt>) at <tt>gcgrid/geos-chem/data/ExtData/GCHP/TileFiles</tt>. Starting in 12.5.0, all regridding weights will be generated online by ESMF at run-time and external tile files are not needed.

--------------------------------------

'''''[[GCHP_Hardware_and_Software_Requirements|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started With GCHP]] | [[GCHP Main Page]]'''''