Difference between revisions of "Downloading GCHP"

From Geos-chem
Jump to: navigation, search
(→‎Step 4: Download Shared Data Directories)
m
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
----
 +
<span style="color:crimson;font-size:120%">'''The GCHP documentation has moved to https://gchp.readthedocs.io/.''' The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!</span>
 +
----
 +
 
__FORCETOC__
 
__FORCETOC__
−
'''''[[GCHP_Hardware_and_Software_Requirements|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]'''''
+
'''''[[Setting Up the GCHP Environment|Previous]] | [[Compiling_GCHP|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 +
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
#<span style="color:blue">'''Downloading Source Code and Data Directories'''</span>
 
#<span style="color:blue">'''Downloading Source Code and Data Directories'''</span>
 +
#[[Compiling_GCHP|Compiling]]
 
#[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
 
#[[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:_Basics|Running GCHP: Basics]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
Line 13: Line 17:
 
<br>
 
<br>
  
−
== Overview ==
+
==Download GCHP==
−
 
+
−
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. <tt>Code.12.0.0_gchp</tt> and <tt>Code.12.0.0_gcclassic</tt>. This avoids confusion and extra work since each requires separate compilation. Using git you can exchange GEOS-Chem code between the two <tt>geoschem</tt> repository clones even when the <tt>GCHP</tt> 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 <tt>main.F</tt> in the <tt>GeosCore</tt> directory; much of the functionality of this file is done instead in the <tt>GCHP/Chem_GridCompMod.F90</tt> and <tt>GCHP/gigc_chunk_mod.F90</tt>. Other GEOS-Chem components ignored by GCHP are GEOS-Chem advection and History, which is the component that handles diagnostics.
+
−
 
+
−
==Step 1: Download GEOS-Chem==
+
−
 
+
−
Clone the GEOS-Chem repository on Github to a directory name of your choosing.
+
−
 
+
−
git clone https://github.com/geoschem/geos-chem.git Code.GCHP
+
−
 
+
−
Take note of the path where the code was downloaded. In this example let's say the source code is stored at <tt>/mypath/GCHP/Code.GCHP</tt>.
+
−
 
+
−
<b>Note for advanced git users:</b> If you plan on developing GEOS-Chem updates to submit for inclusion in the model we recommend that you fork the repository on Github and clone it from your own account. You can then make pull requests when you are ready to submit updates to the GEOS-Chem Support Team. See [[GEOS-Chem_coding_and_debugging#Submitting_updates_for_inclusion_into_GEOS-Chem|these instructions]] for more information or contact the GEOS-Chem Support Team for guidance.
+
−
 
+
−
==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:
+
GCHP source code is downloadable from GitHub at [https://github.com/geoschem/gchpctm https://github.com/geoschem/gchpctm]. As with any repository on GitHub, you can fork the project to your own GitHub account and then clone your fork to your local machine, or you may clone directly from the GCHP GitHub page. Assuming you are doing the latter, clone GCHP with the following command:
  
−
cd /mypath/GCHP/Code.GCHP
+
  git clone https://github.com/geoschem/gchpctm.git Code.GCHP
−
  git clone https://github.com/geoschem/gchp.git GCHP
+
  
−
==Step 3: Choose version==
+
When cloning GCHP you will get the main branch by default.
  
−
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 "git log" 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.
+
==Fill git submodules==
  
−
[[File:gchp Gittag.png|800px|thumb|Example output of git log. Notice tag name at top indicating what version this is.]]
+
GCHP includes many subdirectories that are themselves separate repositories on GitHub with their own version histories. These are stored in GCHP as git submodules and all of the git submodule folders will be empty when you first clone GCHP. To populate them you must enter a git command to update all submodules recursively, as follows:
  
−
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 "git tag". To checkout a tagged version type "git checkout tags/tagname".
+
cd Code.GCHP
 +
git submodule update --init --recursive
  
−
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: "git checkout -b mybranch". 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.
+
This command accesses the submodule repository and commit information stored in GCHP and then populates the submodule directories by accessing GitHub. See file <tt>.gitmodules</tt> within the top-level GCHP directory for a list of git submodules within GCHP.
  
−
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.  
+
Please note that each GCHP commit may point to a different collection of git submodule commits. If you change GCHP versions, therefore, you should always reapply the git submodule update command.
  
−
==Step 4: Download Shared Data Directories==
+
==Download data directories==
  
−
Steps for downloading data directories used in GCHP are the same as for GEOS-Chem Classic. Please see the [http://acmg.seas.harvard.edu/geos/doc/man/chapter_4.html GEOS-Chem User Manual Chapter 4] 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.2.0 are located [[GEOS-Chem_12#New_data_directories_in_12.2.0|here]].
+
GCHP uses the same collection of input files as GEOS-Chem Classic. See the [[Downloading_GEOS-Chem_data_directories | downloading GEOS-Chem data directories wiki page]] for more information.
  
−
Beyond downloading the data directories you would typically use for GEOS-Chem Classic, GCHP requires 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>. Please note that the need for tile files will be retired in an upcoming version when we update the version of MAPL, likely GEOS-Chem 12.5.0. At that time all regridding weights will be generated by ESMF at run-time.
+
Please be aware that new GEOS-Chem versions often require new input data as newer inventories become available. GEOS-Chem version wiki pages, e.g. [[GEOS-Chem_13.0.0|GEOS-Chem 13.0.0]], list new data directories in the version overview section at the top of the page. Pages for all versions can be accessed from the [[GEOS-Chem_versions|GEOS-Chem versions wiki page]].
  
 
--------------------------------------
 
--------------------------------------
  
−
'''''[[GCHP_Hardware_and_Software_Requirements|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]'''''
+
'''''[[Setting Up the GCHP Environment|Previous]] | [[Compiling_GCHP|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''

Latest revision as of 15:40, 8 December 2020

The GCHP documentation has moved to https://gchp.readthedocs.io/. The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!


Previous | Next | Getting Started with GCHP | GCHP Main Page

  1. Hardware and Software Requirements
  2. Setting Up the GCHP Environment
  3. Downloading Source Code and Data Directories
  4. Compiling
  5. Obtaining a Run Directory
  6. Running GCHP: Basics
  7. Running GCHP: Configuration
  8. Output Data
  9. Developing GCHP
  10. Run Configuration Files


Download GCHP

GCHP source code is downloadable from GitHub at https://github.com/geoschem/gchpctm. As with any repository on GitHub, you can fork the project to your own GitHub account and then clone your fork to your local machine, or you may clone directly from the GCHP GitHub page. Assuming you are doing the latter, clone GCHP with the following command: 

git clone https://github.com/geoschem/gchpctm.git Code.GCHP

When cloning GCHP you will get the main branch by default.

Fill git submodules

GCHP includes many subdirectories that are themselves separate repositories on GitHub with their own version histories. These are stored in GCHP as git submodules and all of the git submodule folders will be empty when you first clone GCHP. To populate them you must enter a git command to update all submodules recursively, as follows: 

cd Code.GCHP
git submodule update --init --recursive

This command accesses the submodule repository and commit information stored in GCHP and then populates the submodule directories by accessing GitHub. See file .gitmodules within the top-level GCHP directory for a list of git submodules within GCHP.

Please note that each GCHP commit may point to a different collection of git submodule commits. If you change GCHP versions, therefore, you should always reapply the git submodule update command.

Download data directories

GCHP uses the same collection of input files as GEOS-Chem Classic. See the downloading GEOS-Chem data directories wiki page for more information.

Please be aware that new GEOS-Chem versions often require new input data as newer inventories become available. GEOS-Chem version wiki pages, e.g. GEOS-Chem 13.0.0, list new data directories in the version overview section at the top of the page. Pages for all versions can be accessed from the GEOS-Chem versions wiki page.

Previous | Next | Getting Started with GCHP | GCHP Main Page

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=Downloading_GCHP&oldid=48670"