Difference between revisions of "GEOS-Chem basics"

From Geos-chem
Jump to: navigation, search
(The GEOS-Chem source code)
(GEOS-Chem tutorials)
 
(45 intermediate revisions by 2 users not shown)
Line 43: Line 43:
 
|-valign="top"
 
|-valign="top"
 
|[[#The Git source code management system|Git (a source code management system)]]
 
|[[#The Git source code management system|Git (a source code management system)]]
|The Git source-code management software is a free and open-source package that we use to enforce strict version control.  You will also Git to download the GEOS-Chem source code and the GEOS-Chem Unit Teseter.
+
|Please see our ''[[Guide to using Git with GEOS-Chem]]'' for more information about how to use Git with GEOS-Chem.
 
+
Git is usually installed by default with most Unix distributions.  It will also be available for you on the Amazon cloud.
+
  
 
|-valign="top"
 
|-valign="top"
 
|[[#Fortran resources|A Fortran compiler]]
 
|[[#Fortran resources|A Fortran compiler]]
|GEOS-Chem is written in the Fortran language.  A Fortran compiler is used to create an executable file from the GEOS-Chem source code.  You can use either the [[GNU Fortran compiler|GNU Fortran Compiler (aka gfortran)]] or the [[Intel Fortran Compiler|Intel Fortran Compiler (aka ifort)]] to compile GEOS-Chem.
+
|Please see our ''[[Guide to compilers for GEOS-Chem]]'' for more information about the Fortran compilers that you can use to build GEOS-Chem.
 
+
If you have an account on a shared computer cluster at your institution, chances are that you will at least have a GNU Fortran Compiler version installed, and maybe a version of Intel Fortran installed as well.  Ask your IT staff for more information.
+
 
+
You will need the GNU Fortran Compiler to compile GEOS-Chem on the Amazon cloud.  This will already be available for you, so you won't have to install it manually.
+
  
 
|-valign="top"
 
|-valign="top"
 
|[[#The netCDF library|A netCDF library installation]]
 
|[[#The netCDF library|A netCDF library installation]]
|GEOS-Chem uses the netCDF file format for I/O.  Many GEOS-Chem restart and diagnostic output files are written to netCDF format.
+
|Please see our ''[[Guide to netCDF in GEOS-Chem]]'' for more information about the netCDF file format and software ibrary.
 
+
If you are using GEOS-Chem on a local computer cluster, then you (or your IT staff) will need to install a version of netCDF.  Chances are there might be one or more netCDF versions pre-installed for you.  Ask your IT staff for assistance.
+
 
+
If you are using GEOS-Chem on the Amazon cloud, then a netCDF library will already be available for you to use.
+
  
 
|-valign="top"
 
|-valign="top"
 
|[[#The GEOS-Chem source code|A GEOS-Chem source code directory]]
 
|[[#The GEOS-Chem source code|A GEOS-Chem source code directory]]
|This directory contains the GEOS-Chem source code, which the compiler will assemble into an executable file.
+
|This directory contains the GEOS-Chem source code, which the compiler will assemble into an executable file. Please see our ''[[Downloading GEOS-Chem source code]]'' wiki page for detailed instructions.
 
+
The GEOS-Chem source code can be downloaded from Github.
+
  
 
|-valign="top"
 
|-valign="top"
Line 75: Line 63:
 
|-valign="top"
 
|-valign="top"
 
|[[#The GEOS-Chem shared data directories|The GEOS-Chem shared data directories]]
 
|[[#The GEOS-Chem shared data directories|The GEOS-Chem shared data directories]]
|Directory structure containing the meteorology and emissions data that GEOS-Chem reads as input.
+
|This is the directory structure containing the meteorology and emissions data that GEOS-Chem reads as input. For more information, please see our ''[[Downloading GEOS-Chem data directories]]'' wiki page.
If you are using GEOS-Chem on a local computational cluster, then you will need to download these data manually.  We recommend to:
+
*Download the meteorological fields from the Dalhousie data archive
+
*Download the emissions data for HEMCO from the Harvard data archive.
+
 
+
The shared data directories for GEOS-Chem are already available on the Amazon cloud platform.
+
  
 
|-valign="top"
 
|-valign="top"
Line 89: Line 72:
 
|-valign="top"
 
|-valign="top"
 
|[[#Visualization packages|A visualization package]]
 
|[[#Visualization packages|A visualization package]]
|This is software that is used to read and plot output from GEOS-Chem simulations.
+
|Please see our ''[[Guide to visualization and analysis tools for GEOS-Chem]]'' for information about software packages that you can use to analyze or plot GEOS-Chem output.
  
Traditionally, the IDL-based GAMAP has been used for plotting GEOS-Chem-generated data.  Starting with [[GEOS-Chem 12]], you will have the option to save diagnostic output directly to netCDF data.  This will give you the option to open-source plotting packages based in the Python language.
 
 
|}
 
|}
  
Please also see our [http://manual.geos-chem.org GEOS-Chem User's Guide] for complete information about how to set up a GEOS-Chem simulation.
+
Please also see our ''[[Getting Started with GEOS-Chem]]'' for complete information about how to set up a GEOS-Chem simulation.
  
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 21:48, 2 January 2019 (UTC)
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 21:48, 2 January 2019 (UTC)
Line 118: Line 100:
  
 
|-valign="top"
 
|-valign="top"
|[http://manual.geos-chem.org ''The GEOS-Chem User's Guide''<br>('''manual.geos-chem.org''')]
+
|[[Getting Started with GEOS-Chem]]<br>[[Getting Started With GCHP]]
 
|
 
|
*The user manual for GEOS-Chem.  Contains instructions on how to install, download, compile, and run GEOS-Chem on your system.
+
*Our guides to getting started with GEOS-Chem and GCHP.
  
 
|-valign="top"
 
|-valign="top"
Line 126: Line 108:
 
|
 
|
 
*Answers to the most commonly-asked questions about GEOS-Chem.
 
*Answers to the most commonly-asked questions about GEOS-Chem.
 
|-valign="top"
 
|[http://www.geos-chem.org/geos_licensing.html GEOS-Chem licensing]
 
|
 
*Information about the public license under which GEOS-Chem (and related software) are distributed.
 
  
 
|-valign="top"
 
|-valign="top"
Line 138: Line 115:
  
 
|-valign="top"
 
|-valign="top"
|[[GEOS-Chem coding and debugging|Coding and debugging tips]]
+
|[[Getting_Started_with_GEOS-Chem#Getting_help|Getting help with GEOS-Chem]]
 
|
 
|
 
*Helpful hints for writing and debugging new GEOS-Chem source code.
 
*Helpful hints for writing and debugging new GEOS-Chem source code.
 +
*Instructions on contacting the [[GEOS-Chem Support Team]] for assistance. 
  
 
|-valign="top"
 
|-valign="top"
|[[GEOS-Chem Support Team|The GEOS-Chem Support Team]] (aka GCST)
+
|[http://www.geos-chem.org/geos_licensing.html GEOS-Chem licensing]
 
|
 
|
*Responsible for GEOS-Chem software development, user support, and documentation.
+
*Information about the public license under which GEOS-Chem (and related software) are distributed.
 
+
|-valign="top"
+
|[[Submitting GEOS-Chem support requests]]
+
|
+
*Describes how you can contact the [[GEOS-Chem Support Team]] for assistance. 
+
*Also provides [[Submitting_GEOS-Chem_support_requests#What_do_I_need_to_include_in_my_support_request.3F|a handy checklist of items]] that you should include in your request.
+
  
 
|}
 
|}
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:28, 21 December 2018 (UTC)
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 18:19, 14 June 2019 (UTC)
  
 
== Unix resources ==
 
== Unix resources ==
Line 210: Line 182:
 
For specific information about compiling GEOS-Chem, see:
 
For specific information about compiling GEOS-Chem, see:
  
*GEOS-Chem User's Guide: [http://acmg.seas.harvard.edu/geos/doc/man/chapter_7.html Chapter 7: Compiling GEOS-Chem]
+
*[[Compiling GEOS-Chem]]
*GEOS-Chem wiki: [[GEOS-Chem Makefile Structure]]
+
*''[[Guide to compilers for GEOS-Chem]]''
  
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:40, 19 December 2016 (UTC)
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:40, 19 December 2016 (UTC)
Line 217: Line 189:
 
== The Git source code management system ==
 
== The Git source code management system ==
  
Given the large number of user code submissions, robust source code management techniques must be employed in order to ensure the integrity of the GEOS–Chem code. The [[GEOS-Chem Support Team]] has selected the Git version control software for GEOS–Chem source code management.
+
Please see our ''[[Guide to using Git with GEOS-Chem]]'' for more information about how to use Git with GEOS-Chem.
  
There are several useful online resources for Git.  We recommend starting with:
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:28, 21 June 2019 (UTC)
 
+
*GEOS-Chem wiki: [[Version control with Git]]
+
*GEOS-Chem wiki: [[Using Git with GEOS-Chem]]
+
*[[Version_control_with_Git#Tutorials_about_Git|Our list of tutorials about Git]]
+
*[http://git-scm.com ''git-scm.com''&mdash;The official Git site]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:38, 2 November 2016 (UTC)
+
  
 
== Fortran resources ==
 
== Fortran resources ==
  
GEOS-Chem is written in the Fortran computer language, and relies upon of the new features that were introduced with the Fortran-90 standard.  We list below several useful resources for your reference.  Please also see [[Minimum_system_requirements_for_GEOS-Chem#Supported_compilers|our list of supported compiler versions]].
+
Please see our ''[[Guide to compilers for GEOS-Chem]]'' wiki page for more information about the compilers that you can use to build GEOS-Chem, as well as some Fortran-language resources.
  
=== Online tutorials ===
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:58, 14 June 2019 (UTC)
 
+
If you are new to Fortran (or are familiar with the older Fortran-77 standard but not Fortran-90), then we invite you to take one or more of these tutorials:
+
 
+
*[http://www.fortrantutorial.com/ FortranTutorial.com]
+
*[http://people.ds.cam.ac.uk/nmm1/Fortran/index.html Introduction to Modern Fortran (Cambridge Univ, UK)]
+
*[http://exodus.physics.ucla.edu/Fortran95/PSTIResearchLecSeries1.html Victor Decyk (UCLA) Fortran tutorial]
+
*[https://www.nsc.liu.se/~boein/f77to90/f77to90.html Fortran 90 for the Fortran 77 programmer]
+
*[http://openmp.org/wp/2008/11/sc08-openmp-hands-on-tutorial-available/ Using OpenMP parallelization with Fortran]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:12, 2 November 2016 (UTC)
+
 
+
=== The GNU Fortran compiler ===
+
 
+
'''''GNU Fortran is our recommended open-source compiler for GEOS-Chem.'''''
+
 
+
[[GEOS-Chem v11-01]] and newer versions are compatible with the [[GNU Fortran compiler]], aka <tt>gfortran</tt>.  This is a free and open-source compiler that comes pre-installed on many modern computer systems.  As such, GNU Fortran allows GEOS-Chem to be highly portable across a wide variety of platforms.  For more information see:
+
 
+
*[[GNU Fortran compiler|''GNU Fortran compiler'' page on the GEOS-Chem wiki]]
+
*[https://gcc.gnu.org/wiki/GFortran ''Gfortran home'' at GNU.org]
+
 
+
If you will be running GEOS-Chem on the Amazon Web Services cloud computing environment, then you will need to use the GNU Fortran compiler.  Please see our cloud computing tutorial [http://cloud.geos-chem.org '''cloud.geos-chem.org'''] for more information.
+
 
+
'''A note on performance:''' When GEOS-Chem is compiled with the GNU Fortran compiler, it runs slower than when compiled with the proprietary Intel Fortran compiler, especially when running on Intel CPUs.  This is because GNU Fortran, as an open-source software product, lacks the ability to take advantage of some proprietary Intel CPU optimizations.  If performance matters to you, and your institution has an Intel Fortran site license, then you might want to consider using [[#The Intel Fortran compiler|the Intel Fortran Compiler]] instead. 
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:10, 10 January 2019 (UTC)
+
 
+
=== The Intel Fortran compiler ===
+
 
+
'''''Intel Fortran is our recommended proprietary compiler for GEOS-Chem.'''''
+
 
+
Many users compile GEOS-Chem with the Intel Fortran compiler (aka <tt>ifort</tt>). In general, you will always obtain the best performance when compiling GEOS-Chem using Intel Fortran AND running GEOS-Chem on a system with Intel CPUs.  For more information, please see [[Intel Fortran Compiler|our ''Intel Fortran compiler'' page on the GEOS-Chem wiki]].
+
 
+
'''''NOTE:''''' The Intel Fortran compiiler is proprietary software, and requires the purchase of an expensive site license.  If your institution does not have the resources to purchase the Intel Fortran Compiler, then we recommend that you use the [[#GNU Fortran Compiler|GNU Fortran compiler]]&mdash;which is free and open source&mdash;instead.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:13, 10 January 2019 (UTC)
+
  
 
== The netCDF library ==
 
== The netCDF library ==
  
GEOS-Chem reads and writes data in the netCDF file format.  NetCDF is a self-describing format, which means that it can keep data fields together with "metadata"&mdash;the information describing each data field&mdash; in the same file.  This makes it very easy to share GEOS-Chem output with other researchers.
+
Please see our ''[[Guide to netCDF in GEOS-Chem]]'' for more information about how to install netCDF on your system (or check if it is already installed).
 
+
=== netCDF on Amazon cloud ===
+
 
+
If you are running GEOS-Chem on the Amazon Web Services cloud, then you will initialize your Unix environment with a machine image (or a container) that contains a pre-built netCDF library. So you will not need to build the netCDF library yourself.
+
 
+
To learn more about using GEOS-Chem on the Amazon Web Services Cloud, please see our tutorial: [http://cloud.geos-chem.org '''cloud.geos-chem.org'''].
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:19, 2 January 2019 (UTC)
+
 
+
=== netCDF on your system ===
+
 
+
Ask your IT staff [[Installing libraries for GEOS-Chem#Check to see if netCDF is already installed on your system|if a version of netCDF has already been pre-built on your system]].  On many systems, the IT staff will create several different builds of netCDF to accommodate different compilers (and sometimes MPI versions). 
+
 
+
If your system uses the [[Installing libraries for GEOS-Chem#Using modules|the Lmod module manager]], then you will be able to load a netCDF library version with a command such as:
+
 
+
  module load netcdf
+
 
+
If your system does not already have a netCDF installation, [[Installing_libraries_for_GEOS-Chem#If_you_do_not_have_netCDF_on_your_system.2C_use_Spack_to_install_it|you can use the Spack package manager to install netCDF and its dependent libraries]] on your own.
+
 
+
Depending on your system, you might also be able to run GEOS-Chem within a container (e.g. Docker, Singularity) that has a pre-built Unix environment with all of the necessary libraries. Ask your IT staff.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:47, 10 January 2019 (UTC)
+
 
+
=== netCDF references ===
+
 
+
We have also collated the following references about netCDF, which you might find useful.
+
 
+
* [[Working with netCDF data files|Our ''Working with netCDF data files'' wiki page]]
+
* [http://www.unidata.ucar.edu/software/netcdf/ netCDF Home Page]
+
* [http://www.unidata.ucar.edu/software/netcdf/docs.html netCDF Documentation]
+
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:19, 2 January 2019 (UTC)
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:58, 13 June 2019 (UTC)
  
 
== The GEOS-Chem source code ==
 
== The GEOS-Chem source code ==
Line 309: Line 209:
 
The '''GEOS-Chem model source code''' is kept in a publicly-accessible [[#The Git source code management system|Git repository]].  You must '''compile''' the source code into an '''executable file''' with one of the [[#Fortran resources|supported Fortran compilers]].  The compilation is managed by the [[#GNU Make|GNU Make]] utility,  which reads the various [[GEOS-Chem Makefile Structure|GEOS-Chem makefiles]] to produce the executable with the desired options.
 
The '''GEOS-Chem model source code''' is kept in a publicly-accessible [[#The Git source code management system|Git repository]].  You must '''compile''' the source code into an '''executable file''' with one of the [[#Fortran resources|supported Fortran compilers]].  The compilation is managed by the [[#GNU Make|GNU Make]] utility,  which reads the various [[GEOS-Chem Makefile Structure|GEOS-Chem makefiles]] to produce the executable with the desired options.
  
You can download the source code for the latest GEOS-Chem version if you have Git installed on your system.  For more information and detailed downloading instructions, please see:
+
For more information and detailed downloading instructions, please see our ''[[Downloading GEOS-Chem source code]]'' wiki page.
 
+
* [[Getting Started with GEOS-Chem]]
+
** [[Minimum system requirements for GEOS-Chem]]
+
** [[Downloading GEOS-Chem source code]]
+
** [[Compiling GEOS-Chem]]
+
  
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 13:56, 12 June 2019 (UTC)
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 13:56, 12 June 2019 (UTC)
Line 320: Line 215:
 
== The GEOS-Chem Unit Tester ==
 
== The GEOS-Chem Unit Tester ==
  
The '''GEOS-Chem Unit Tester''' is a package of scripts and Makefiles that will compile and run several GEOS-Chem with a set of standard debugging flags.  The Unit Tester is one of our best GEOS-Chem debugging tools.  For more information, please see:
+
The '''GEOS-Chem Unit Tester''' is a package of scripts and Makefiles that will compile and run several GEOS-Chem with a set of standard debugging flags.  The Unit Tester is one of our best GEOS-Chem debugging tools.  For more information, please see our ''[[GEOS-Chem Unit Tester]]'' wiki page.
 
+
* GEOS-Chem wiki: [[GEOS-Chem Unit Tester]]
+
  
 
=== Creating run directories with the Unit Tester ===
 
=== Creating run directories with the Unit Tester ===
Line 330: Line 223:
 
* To specify start and end dates of simulation
 
* To specify start and end dates of simulation
 
* To specify which GEOS-Chem options to turn on/off
 
* To specify which GEOS-Chem options to turn on/off
* To specify the species/reactions/cross-sections in the [[Photolysis mechanism|photolysis mechanism]]
 
 
* To specify diagnostic output options
 
* To specify diagnostic output options
  
 
For more information, please see the following resources:
 
For more information, please see the following resources:
  
* GEOS-Chem wiki: [[Creating GEOS-Chem run directories]]
+
*[[Getting Started with GEOS-Chem]]
* GEOS-Chem wiki: [[Downloading GEOS-Chem source code and data]]
+
*[[Creating GEOS-Chem run directories]]
* GEOS-Chem wiki: [[HEMCO data directories]]
+
* GEOS-Chem wiki: [[Setting up the ExtData directory]]
+
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 14:40, 3 November 2016 (UTC)
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 14:12, 12 June 2019 (UTC)
  
 
== The GEOS-Chem shared data directories ==
 
== The GEOS-Chem shared data directories ==
  
In addition to the files contained in the run directories, GEOS-Chem also needs to access '''data directories''' containing:
+
For more information, please see our ''[[Downloading GEOS-Chem data directories]]'' wiki page.
 
+
* [[Overview of GMAO met data products|Meteorological data]] (a.k.a. the "met fields) used to drive GEOS–Chem
+
* [[Emissions overview|Emissions inventories]] used by GEOS-Chem
+
* Scale factors used to scale emissions from a base year to a given year
+
* Oxidant (OH, O3) concentrations for both full-chemistry and offline simulations
+
* IPCC future scenarios (for GCAP simulatons)
+
* Other GEOS–Chem specific data files.
+
 
+
These files are often too large to store in a single user's disk space.  Therefore, they are meant to be stored in shared disk space where all GEOS-Chem users in your group can have access to them. 
+
 
+
The GEOS-Chem shared data directories can be downloaded from archives at Harvard University and Dalhousie University.  Unlike the source code and run directories, the data directory download can be done either by anonymous FTP or by the freely-available [http://www.gnu.org/software/wget/ GNU wget utility].  (We recommend wget because it is much more flexible and can be used to download several directories recursively.)
+
 
+
'''NOTE:''' If you are using GEOS-Chem on the Amazon Web Services cloud computing platform, then you can access the GEOS-Chem shared data directories as an S3 bucket (<tt>s3://gcgrid</tt>).  Please see our cloud computing tutorial ([http://cloud.geos-chem.org '''cloud.geos-chem.org''']) for more details.
+
 
+
For more information and detailed downloading instructions, please see:
+
 
+
* GEOS-Chem wiki: [[Downloading GEOS-Chem source code and data]]
+
* GEOS-Chem wiki: [[HEMCO data directories]]
+
* GEOS-Chem wiki: [[GEOS-Chem basics#Restart files|Restart files]]
+
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 19:42, 9 December 2016 (UTC)
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:15, 14 June 2019 (UTC)
  
 
== Restart files ==
 
== Restart files ==
Line 373: Line 244:
 
# [[HEMCO]] restart file containing values needed for some of the HEMCO extensions '''(Optional)'''
 
# [[HEMCO]] restart file containing values needed for some of the HEMCO extensions '''(Optional)'''
  
When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the intervals you specify in <tt>input.geos</tt>. New HEMCO restart files are written with frequency configured in <tt>HEMCO_Config.rc</tt> if HEMCO is used in your simulation.
+
When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the intervals you specify in <tt>HISTORY.rc</tt>. New HEMCO restart files are written with frequency configured in <tt>HEMCO_Config.rc</tt> if HEMCO is used in your simulation.
  
[[GEOS-Chem v11-01]] run directories are configured to use initial GEOS-Chem restart files in [[GEOS-Chem_Output_Files#NetCDF_File_Format|netCDF format]]. These files are available for download at:
+
You can read more about restart files at the [[GEOS-Chem_restart_files|''GEOS-Chem restart files'' wiki page]].
  
ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/SPC_RESTARTS/
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 12:21, 16 July 2019 (UTC)
 
+
<span style="color:red">'''''CAVEAT: The initial restart files  do not reflect the actual atmospheric state and should only be used to "spin up" the model. In other words, they should be used as initial values in an initialization simulation to generate more accurate initial conditions for your production runs.'''''</span>
+
 
+
Doing a one year spin up is usually sufficient; however, we recommend ten years for ozone, carbon dioxide, and methane simulations, and four years for radon-lead-beryllium simulations. If you are in doubt about how long your spin up should be for your simulation, we recommend contacting the [http://acmg.seas.harvard.edu/geos/geos_working_groups.html GEOS-Chem Working Group] that specializes in your area of research.
+
+
You may spin up the model starting at any year for which there is met data, but you should always start your simulations at the month and day corresponding to the restart file to more accurately capture seasonal variation. If you want to start your production run at a specific date, we recommend doing a spin up for the appropriate number of years plus the number of days needed to reach your ultimate start date. For example, if you want to do a production simulation starting on 12/1/13, you could spin up the model for one year using the initial GEOS-FP restart file dated 7/1/13 and then use the new restart file to spin up the model for five additional months, from 7/1/13 to 12/1/13. 
+
 
+
To determine the date of a netCDF restart file, you may use <tt>ncdump</tt> For example:
+
 
+
ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc
+
 
+
The <tt>-t</tt> option will return the time value in human-readable date-time strings rather than numerical values in unit such as "hours since 1985-1-1 00:00:0.0." The date of a binary punch restart file can be determined by opening the file in GAMAP.
+
 
+
Using a HEMCO restart file for your initial spin up run is optional. The HEMCO restart file contains fields for initializing variables required for [[Soil NOx emissions]], [[MEGAN biogenic emissions]], and the [[UCX chemistry mechanism]]. The HEMCO restart file that comes with a run directory may only be used for the date and time indicated in the filename. HEMCO will automatically recognize when a restart file is not available for the date and time required, and in that case HEMCO will use default values to initialize those fields. You can also force HEMCO to use the default initialization values by setting "HEMCO_RESTART" to false in <tt>HEMCO_Config.rc</tt>. For more information, see the [[The_HEMCO_User's_Guide#Restart_variables|HEMCO User's Guide]].
+
 
+
You can read more about restart files at the [[GEOS-Chem_Output_Files|''GEOS-Chem output files'' wiki page]].
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 16:03, 12 January 2017 (UTC)
+
  
 
== Visualization packages ==
 
== Visualization packages ==
  
In this section we provide information about software packages that you can use to analyze and plot [[GEOS-Chem_Output_Files|GEOS-Chem output]].
+
Please see our ''[[Guide to visualization and analysis tools for GEOS-Chem]]'' for information about software packages that you can use to analyze or plot GEOS-Chem output.
  
=== Python software ===
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:59, 14 June 2019 (UTC)
 
+
Several developers have started creating Python-based visualization software for GEOS-Chem.  Please see the following page for more information:
+
 
+
*GEOS-Chem wiki: [[Python code for GEOS-Chem]]
+
*[https://github.com/geoschem/gcpy GCPy: Python powered GEOS-Chem data analysis/visualization] '''(Currently under development)'''
+
 
+
If you are new to programming in Python, you may find these tutorials useful:
+
 
+
*[https://developers.google.com/edu/python/ Google's Python course]
+
*[http://docs.python.org/3/tutorial/ Python 3 tutorial]
+
*[http://learnpythonthehardway.org/book/ ''Learn Python the hard way'' book]
+
 
+
For the most part, you don't need to use a lot of Python packages to read and plot GEOS-Chem data.  For example, GCPy package mostly relies on [http://xarray.pydata.org/en/stable/ xarray] (to read netCDF data), [https://matplotlib.org/ matplotlib] and [https://scitools.org.uk/cartopy/docs/latest/ cartopy] (to plot data), [http://www.numpy.org/ numpy] (for math operations) and [https://xesmf.readthedocs.io/en/latest/ xESMF] (to regrid between cubed-sphere to lat-lon grids).
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 21:55, 2 January 2019 (UTC)
+
 
+
=== GAMAP and other IDL software ===
+
 
+
<span style="color:red">'''''NOTE: IDL, which is proprietary software, can be very expensive.  For this reason, the [[GEOS-Chem Support Team]] and other GEOS-Chem developers are currently developing several open-source software packages (mostly based on Python) for GEOS-Chem data analysis and visualization. Please see our [[#Python software|Python software]] section above.'''''</span>
+
 
+
The traditional GEOS-Chem visualization software is GAMAP.  This package was customized to GEOS-Chem and is still heavily used today.  GAMAP requires the Interactive Data Language (a proprietary package).  For more information about GAMAP, please see:
+
 
+
*[http://acmg.seas.harvard.edu/gamap/ GAMAP web page]
+
*[http://acmg.seas.harvard.edu/gamap/doc/index.html GAMAP online manual]
+
*[http://acmg.seas.harvard.edu/gamap/doc/Chapter_5.html Documentation for individual GAMAP routines]
+
*GEOS-Chem wiki: [[GAMAP tips and tricks]]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:50, 10 January 2019 (UTC)
+
  
 
== The GEOS-Chem website ==
 
== The GEOS-Chem website ==
Line 438: Line 263:
  
 
* [http://acmg.seas.harvard.edu/geos/geos_welcome.html Read a welcome letter which outlines user responsibilities]
 
* [http://acmg.seas.harvard.edu/geos/geos_welcome.html Read a welcome letter which outlines user responsibilities]
* [http://acmg.seas.harvard.edu/geos/doc/man Read the online '''GEOS-Chem User's Guide''']
 
 
* [http://acmg.seas.harvard.edu/geos/geos_pub.html Access GEOS-Chem-related publications]
 
* [http://acmg.seas.harvard.edu/geos/geos_pub.html Access GEOS-Chem-related publications]
 
* [http://acmg.seas.harvard.edu/geos/meetings/2015/index.html View online presentations from '''GEOS-Chem user meetings''']
 
* [http://acmg.seas.harvard.edu/geos/meetings/2015/index.html View online presentations from '''GEOS-Chem user meetings''']
Line 445: Line 269:
  
 
Also, please take a minute to read the [http://acmg.seas.harvard.edu/geos/geos_overview.html '''GEOS-Chem overview page'''.]  This document outlines the responsibilities for all GEOS-Chem users.
 
Also, please take a minute to read the [http://acmg.seas.harvard.edu/geos/geos_overview.html '''GEOS-Chem overview page'''.]  This document outlines the responsibilities for all GEOS-Chem users.
 
'''''PLEASE NOTE: At this time, the GEOS-Chem User's Guide is only viewable in HTML.'''''
 
  
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:08, 11 January 2019 (UTC)
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:08, 11 January 2019 (UTC)
Line 470: Line 292:
 
== GEOS-Chem tutorials ==
 
== GEOS-Chem tutorials ==
  
Please see the following GEOS-Chem tutorials, mostly taken from previous GEOS-Chem meetings:
+
Please see the following GEOS-Chem tutorials:
  
 +
*[http://youtube.geos-chem.org GEOS-Chem video tutorials ('''youtube.geos-chem.org''')]
 
*[http://cloud.geos-chem.org Using GEOS-Chem on the Amazon Web Services Cloud computing environment ('''cloud.geos-chem.org''')]
 
*[http://cloud.geos-chem.org Using GEOS-Chem on the Amazon Web Services Cloud computing environment ('''cloud.geos-chem.org''')]
*[http://acmg.seas.harvard.edu/presentations/IGC8/talks/MonC_Clinics_sulprizio_melissa.pdf GEOS-Chem for beginners (IGC8 model clinic)]
+
*[https://github.com/geoschem/GEOSChem-python-tutorial GEOS-Chem Python Tutorial]
*[http://acmg.seas.harvard.edu/presentations/IGC8/talks/MonC_Clinics_yantosca_bob.pdf GEOS-Chem for advanced users (IGC8 model clinic)]
+
*IGC9 model clinics:
*[https://prezi.com/g1hlt6u1pr8u/adjoint-clinic-2017/?utm_campaign=share&utm_medium=copy GEOS-Chem adjoint (IGC8 model clinic)]
+
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/MonD_Clinics_yantosca_bob_1_pc.pdf Working with GEOS-Chem]
*[http://acmg.seas.harvard.edu/presentations/IGC7/talks/MonE_Model_long_mike_1.pdf GEOS-Chem in massively parallel and ESM environments (IGC7 model clinic)]
+
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/MonD_Clinics_lundgren_lizzie_2_mac.pptx High-performance GEOS-Chem (GCHP)]
 +
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/MonD_Clinics_lin_haipeng_1_pc.pdf WRF-GC: GEOS-Chem in WRF]
 +
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/ThuB_Clinics_zhuang_jiawei_1_mac.pdf GEOS-Chem on the AWS Cloud]
 +
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/ThuB_Clinics_keller_christoph_1_mac.pdf GEOS-Chem in Earth System Models]
 +
**[http://acmg.seas.harvard.edu/presentations/IGC9/talks/ThuB_Clinics_wang_yuxuan_1_mac.pdf GEOS-Chem nested model]
 +
**[https://prezi.com/iut9jtq9muas/?utm_campaign=share&utm_medium=copy&rc=ex0share GEOS-Chem adjoint model]; [http://acmg.seas.harvard.edu/presentations/IGC9/talks/ThuB_Clinics_GCAdjoint_Handout.pdf Handout]
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:35, 21 December 2018 (UTC)
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 14:12, 12 June 2019 (UTC)
  
 
== For more information ==
 
== For more information ==
Line 484: Line 312:
 
You can find much more information about GEOS-Chem on our website and wiki.  We invite you to consult the following resources:
 
You can find much more information about GEOS-Chem on our website and wiki.  We invite you to consult the following resources:
  
*[http://acmg.seas.harvard.edu/geos/doc/man/index.html GEOS-Chem User's Guide]
+
*[[Getting Started with GEOS-Chem]]
 +
*[[Getting Started With GCHP|Getting Started with GCHP]]
 
*[[The HEMCO User's Guide]]
 
*[[The HEMCO User's Guide]]
 +
*[[GEOS-Chem overview#GEOS-Chem Guides|GEOS-Chem Guides]]
 
*[[Frequently asked questions about GEOS-Chem]]
 
*[[Frequently asked questions about GEOS-Chem]]
*[[Common_GEOS-Chem_error_messages|What should I do if my GEOS-Chem simulation dies with an error?]]
+
*[[Guide to GEOS-Chem error messages|What should I do if my GEOS-Chem simulation dies with an error?]]
*Where can I find information about [[GEOS-Chem performance]] and [[GEOS-Chem performance|GEOS-Chem Scalability]]?
+
 
*[[Bugs_and_fixes|Is there a comprehensive list of bugs and when they were fixed?]]
 
*[[Bugs_and_fixes|Is there a comprehensive list of bugs and when they were fixed?]]
 
*[[Debugging GEOS-Chem|Do you have any debugging tips?]]
 
*[[Debugging GEOS-Chem|Do you have any debugging tips?]]
 
*[[Submitting GEOS-Chem support requests|How can I contact the GEOS-Chem Support Team for assistance?  What should I include in my request?]]
 
*[[Submitting GEOS-Chem support requests|How can I contact the GEOS-Chem Support Team for assistance?  What should I include in my request?]]
  
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 22:36, 21 December 2018 (UTC)
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 14:12, 12 June 2019 (UTC)

Latest revision as of 16:42, 13 January 2020

The GEOS-Chem Support Team has created this page to assist new GEOS-Chem users to download and run GEOS-Chem on their computer systems.

Overview

GEOS-Chem requirements

Before you can run GEOS-Chem, you will need to have the following items. Some of these will be already pre-installed on your computer system.

Item Description
EITHER

A Unix-based computer system

OR

An account on the Amazon Web Services cloud

You will need a Unix operating system environment in order to run GEOS-Chem. Any flavor of Unix (e.g. CentOS, Ubuntu, Fedora, etc.) should work just fine.

If your institution has computational resources (e.g. a shared computer cluster with many cores, sufficient disk storage and memory), then you can run GEOS-Chem there. Contact your IT staff for assistance.

If your institution lacks computational resources (or if you need additional computational resources beyond what is available), then you should consider signing up for access to the Amazon Web Services cloud. Using the cloud has the following advantages:

  • You can run GEOS-Chem without having to invest in local hardware and maintenance personnel.
  • You won't have to download any meteorological fields or emissions data. All of the necessary data input for GEOS-Chem will be available on the cloud.
  • You can initialize your computational environment with all of the required software (e.g. compilers, libraries, utilities) that you need for GEOS-Chem.
  • Your GEOS-Chem runs will be 100% reproducible, because you will initialize your computational environment the same way every time.
  • You will avoid GEOS-Chem compilation errors due to library incompatibilities.
  • You will be charged for the computational time that you use, and if you download data off the cloud.

GEOS-Chem 12.0.0 and later versions can be used on the Amazon Web Services cloud computing platform. You can learn more about how to use GEOS-Chem on the cloud by visiting this tutorial (cloud.geos-chem.org).

GNU Make GNU Make directs the compilation sequence. It tells the compiler the order in which files should be compiled, which compilation options to use.

You probably won't have to install GNU Make, since it comes with most Unix distributions by default. GNU Make will also be available for you on the Amazon cloud.

Git (a source code management system) Please see our Guide to using Git with GEOS-Chem for more information about how to use Git with GEOS-Chem.
A Fortran compiler Please see our Guide to compilers for GEOS-Chem for more information about the Fortran compilers that you can use to build GEOS-Chem.
A netCDF library installation Please see our Guide to netCDF in GEOS-Chem for more information about the netCDF file format and software ibrary.
A GEOS-Chem source code directory This directory contains the GEOS-Chem source code, which the compiler will assemble into an executable file. Please see our Downloading GEOS-Chem source code wiki page for detailed instructions.
The GEOS-Chem Unit Tester The GEOS-Chem Unit Tester is used to error-check all of the GEOS-Chem simulations. It is also needed to construct GEOS-Chem run directories, in which the compiled executable file will run.
The GEOS-Chem shared data directories This is the directory structure containing the meteorology and emissions data that GEOS-Chem reads as input. For more information, please see our Downloading GEOS-Chem data directories wiki page.
Restart files for GEOS-Chem These are the files containing the initial conditions for a GEOS-Chem simulation. They can be downloaded from our data archive via FTP.
  • GEOS-Chem v11-01 and higher versions only reads and writes restart files in netCDF format.
A visualization package Please see our Guide to visualization and analysis tools for GEOS-Chem for information about software packages that you can use to analyze or plot GEOS-Chem output.

Please also see our Getting Started with GEOS-Chem for complete information about how to set up a GEOS-Chem simulation.

--Bob Yantosca (talk) 21:48, 2 January 2019 (UTC)

GEOS-Chem documentation and support

We have compiled a list of resources that will help you get started with GEOS-Chem:

Item Description
The GEOS-Chem website (geos-chem.org)
  • The main GEOS-Chem website, which links to many other resources.
The GEOS-Chem wiki (wiki.geos-chem.org)
  • The GEOS-Chem wiki (i.e. this wiki), which is now the main knowledge base for GEOS-Chem.
Getting Started with GEOS-Chem
Getting Started With GCHP
  • Our guides to getting started with GEOS-Chem and GCHP.
The GEOS-Chem FAQ
  • Answers to the most commonly-asked questions about GEOS-Chem.
GEOS-Chem tutorial presentations
  • Several online tutorial presentations about how to use GEOS-Chem
Getting help with GEOS-Chem
  • Helpful hints for writing and debugging new GEOS-Chem source code.
  • Instructions on contacting the GEOS-Chem Support Team for assistance.
GEOS-Chem licensing
  • Information about the public license under which GEOS-Chem (and related software) are distributed.

--Melissa Sulprizio (talk) 18:19, 14 June 2019 (UTC)

Unix resources

GEOS-Chem is designed to run on computers with the Unix operating system. There is no single version of Unix; rather, Unix comes packaged in several different distributions. Many modern computer clusters use CentOS, which is an open-source Unix implementation. Other systems may use a proprietary Unix distribution, such as Red Hat Enterprise. GEOS-Chem will perform in the same way regardless of the specific Unix implementation on your system.

If you require assistance setting up or customizing your Unix login environment, please contact your local IT staff. The GEOS-Chem Support Team can only provide support for GEOS-Chem-related issues.

You can now run GEOS-Chem on the Amazon Web Services cloud infrastructure. See our cloud computing tutorial (cloud.geos-chem.org) for more details.

IMPORTANT! Please make sure that your computer system meets the minimum system requirements for memory and disk space in order to run GEOS-Chem.

Common Unix commands

The resources below cover many common Unix commands. You will find these useful, particularly if you have never worked on a Unix machine before.

Unix shells and shell scripting

One of the nice features of Unix is that you can highly customize your environment. You can also write scripts to perform several commands (such as copying files or running programs) sequentially. This will save you the trouble of having to type the same commands over and over at the command-line prompt.

There are several Unix shells that you can use, but we recommend using bash. Here are some resources that you can use to learn more about the bash shell:

--Bob Yantosca (talk) 20:11, 19 September 2017 (UTC)

The GNU Make utility

The GNU Make utility is used to compile GEOS-Chem—that is, to create an executable file from source code. GNU Make usually comes pre-packaged with your Unix distribution (e.g. CentOS, Linux, Ubuntu, Fedora, etc.), so you will probably not need to install it yourself.

GEOS-Chem contains several Makefiles. A Makefile contains several commands in the GNU Make language direct how the Fortran compiler will build GEOS-Chem. Makefiles determine the sequence in which individual files are compiled, as well as the options that will be activated.

Unless you are going to be adding a significant amount of new code into GEOS-Chem, you will probably not need to know the nitty-gritty details of how to create or modify Makefiles. But if you do have to change an existing Makefile, you can contact the GEOS-Chem Support Team, who will be happy to assist you.

If you are interested in learning more about the GNU Make utility, we invite you to consult the following resources:

For specific information about compiling GEOS-Chem, see:

--Bob Yantosca (talk) 19:40, 19 December 2016 (UTC)

The Git source code management system

Please see our Guide to using Git with GEOS-Chem for more information about how to use Git with GEOS-Chem.

--Bob Yantosca (talk) 17:28, 21 June 2019 (UTC)

Fortran resources

Please see our Guide to compilers for GEOS-Chem wiki page for more information about the compilers that you can use to build GEOS-Chem, as well as some Fortran-language resources.

--Bob Yantosca (talk) 14:58, 14 June 2019 (UTC)

The netCDF library

Please see our Guide to netCDF in GEOS-Chem for more information about how to install netCDF on your system (or check if it is already installed).

--Bob Yantosca (talk) 15:58, 13 June 2019 (UTC)

The GEOS-Chem source code

The GEOS-Chem model source code is kept in a publicly-accessible Git repository. You must compile the source code into an executable file with one of the supported Fortran compilers. The compilation is managed by the GNU Make utility, which reads the various GEOS-Chem makefiles to produce the executable with the desired options.

For more information and detailed downloading instructions, please see our Downloading GEOS-Chem source code wiki page.

--Melissa Sulprizio (talk) 13:56, 12 June 2019 (UTC)

The GEOS-Chem Unit Tester

The GEOS-Chem Unit Tester is a package of scripts and Makefiles that will compile and run several GEOS-Chem with a set of standard debugging flags. The Unit Tester is one of our best GEOS-Chem debugging tools. For more information, please see our GEOS-Chem Unit Tester wiki page.

Creating run directories with the Unit Tester

You can use the GEOS-Chem Unit Tester to create a run directory specific to the GEOS-Chem simulation that you want to perform. A run directory is where the GEOS-Chem executable file will be placed. You will normally keep GEOS-Chem run directories in your own disk space. The run directories contain several input files which are used to "customize" the GEOS-Chem simulation as follows:

  • To specify start and end dates of simulation
  • To specify which GEOS-Chem options to turn on/off
  • To specify diagnostic output options

For more information, please see the following resources:

--Melissa Sulprizio (talk) 14:12, 12 June 2019 (UTC)

The GEOS-Chem shared data directories

For more information, please see our Downloading GEOS-Chem data directories wiki page.

--Bob Yantosca (talk) 15:15, 14 June 2019 (UTC)

Restart files

You will need a restart file before you can start your GEOS-Chem simulation. A restart file contains the initial conditions for a GEOS-Chem simulation. There are two restart files for GEOS-Chem:

  1. GEOS-Chem restart file containing instantaneous species concentrations (Required)
  2. HEMCO restart file containing values needed for some of the HEMCO extensions (Optional)

When you run a GEOS-Chem simulation, it will write new GEOS-Chem restart files at the intervals you specify in HISTORY.rc. New HEMCO restart files are written with frequency configured in HEMCO_Config.rc if HEMCO is used in your simulation.

You can read more about restart files at the GEOS-Chem restart files wiki page.

--Melissa Sulprizio (talk) 12:21, 16 July 2019 (UTC)

Visualization packages

Please see our Guide to visualization and analysis tools for GEOS-Chem for information about software packages that you can use to analyze or plot GEOS-Chem output.

--Bob Yantosca (talk) 16:59, 14 June 2019 (UTC)

The GEOS-Chem website

The GEOS-Chem website is located at geos-chem.org.

From this website you may:

Also, please take a minute to read the GEOS-Chem overview page. This document outlines the responsibilities for all GEOS-Chem users.

--Bob Yantosca (talk) 22:08, 11 January 2019 (UTC)

The GEOS-Chem wiki

The GEOS-Chem wiki (i.e. this wiki) is located at: wiki.geos-chem.org.

The wiki has many features that are designed to facilitate communication between GEOS-Chem users and developers. The Main Page of the wiki contains links to several commonly-read pages. If you can't find your desired topic, the best way to search for information on the wiki is by using the Search Box located in the upper right corner of each wiki page.

We encourage all GEOS-Chem code developers and users to check the wiki frequently, as this is the place where the latest information about GEOS-Chem will be posted. The wiki is designed to be a two-way street of communication. Users should feel free to add content to the wiki pages that are most closely related to their research.

In particular, the GEOS-Chem Support Team has begun an effort to make sure that all 3rd-party code and data that is submitted into GEOS-Chem has a corresponding wiki page. This will ensure that all information can be shared transparently.

Logistics

All GEOS-Chem wiki posts can be read by anyone. However, to add or modify wiki pages, you will need to register for a wiki account. Simply click on the "Log In/Create Account" link at the top right of your browser window. The GEOS-Chem support team will confirm your account request (this is an anti-spamming measure).

The best way to find information on the GEOS-Chem wiki is to use the Search Box located in the upper right corner of each wiki page. You can also let the GEOS-Chem wiki inform you of recent updates to the site via RSS. Click here to find out how.

--Bob Yantosca (talk) 22:08, 11 January 2019 (UTC)

GEOS-Chem tutorials

Please see the following GEOS-Chem tutorials:

--Melissa Sulprizio (talk) 14:12, 12 June 2019 (UTC)

For more information

You can find much more information about GEOS-Chem on our website and wiki. We invite you to consult the following resources:

--Melissa Sulprizio (talk) 14:12, 12 June 2019 (UTC)