GEOS-Chem basics

From Geos-chem
Jump to: navigation, search

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
A computer system with a Unix distribution
  • One of the many "flavors" of the Unix operating system is necessary to run GEOS-Chem on multiple CPUs.
    • e.g. CentOS, Ubuntu, Fedora, etc.
  • GEOS-Chem cannot run on a Microsoft Windows machine.
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.
  • GNU Make usually comes already packaged with your Unix distribution.
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.
  • New GEOS-Chem features are checked in and tracked via Git.
  • Git is used to download both the GEOS-Chem source code and GEOS-Chem Unit Tester
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.
  • In GEOS-Chem v11-01 and later, the Fortran compiler environment variables must be set.
A netCDF library installation
  • GEOS-Chem uses the netCDF file format for I/O.
A GEOS-Chem source code directory
  • Contains the code used to generate a GEOS-Chem executable.
  • Can be downloaded via Git from our repository on Bitbucket.org.
The GEOS-Chem Unit Tester
  • The GEOS-Chem Unit Tester can run tests on the various GEOS-Chem simulations to check for common coding errors.
  • Can be downloaded via Git from our repository on Bitbucket.org.
  • GEOS-Chem run directories can be generated by the Unit Tester.
  • GEOS-Chem difference test directories can be generated by the Unit Tester.
The GEOS-Chem shared data directories
  • Directory structure containing the meteorology and emissions data that GEOS-Chem reads as input.
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
  • This is software that is used to read and plot output from GEOS-Chem simulations.
  • GAMAP (IDL-based) is commonly used, but there are other options available.

Please also see our GEOS-Chem User's Guide for complete information about how to set up a GEOS-Chem simulation.

--Bob Yantosca (talk) 14:56, 3 November 2016 (UTC)

GEOS-Chem documentation and support

We have compiled a list of online GEOS-Chem documentation.

Item Description
The GEOS-Chem Support Team (aka GCST)
  • Responsible for GEOS-Chem software development, user support, and documentation.
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.
The GEOS-Chem User's Guide
(manual.geos-chem.org)
  • The user manual for GEOS-Chem. Contains instructions on how to install, download, compile, and run GEOS-Chem on your system.
The GEOS-Chem FAQ
  • Answers to the most commonly-asked questions about GEOS-Chem.
GEOS-Chem licensing
  • Information about the public license under which GEOS-Chem (and related software) are distributed.
GEOS-Chem tutorial presentations
  • Several online tutorial presentations about how to use GEOS-Chem
Coding and debugging tips
  • Helpful hints for writing and debugging new GEOS-Chem source code.

--Bob Yantosca (talk) 15:36, 22 September 2017 (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.

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)

Perl scripting

Perl is a language that is often used for writing scripts. A Perl parser comes pre-installed with your Unix distribution. Perl provides many of the same features as do Unix shell scripts, but also make it very easy to do text comparison and manipulations.

For more information about writing Perl scripts, please see:

--Bob Yantosca (talk) 21:14, 2 November 2016 (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

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.

There are several useful online resources for Git. We recommend starting with:

--Bob Yantosca (talk) 20:38, 2 November 2016 (UTC)

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 our list of supported compiler versions.

Online tutorials

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:

--Bob Yantosca (talk) 19:12, 2 November 2016 (UTC)

The Intel Fortran compiler

The majority of GEOS-Chem users use the Intel Fortran compiler (aka ifort) to compile GEOS-Chem. This is our recommended compiler, and the one that we have the most experience with.

--Bob Yantosca (talk) 19:12, 2 November 2016 (UTC)

The GNU Fortran compiler

GEOS-Chem v11-01 and newer versions are compatible with the GNU Fortran compiler, aka gfortran. This is a free and open-source compiler that comes pre-installed on many modern computer systems.

--Bob Yantosca (talk) 14:02, 29 June 2017 (UTC)

The PGI Fortran compiler

The Portland Group International (PGI) Fortran compiler is another alternative to Intel Fortran.

NOTE: GEOS-Chem v11-01 will compile with PGI Fortran. But we have not yet performed a rigorous validation of GEOS-Chem with PGI Fortran.

--Bob Yantosca (talk) 15:46, 22 September 2017 (UTC)

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"—the information describing each data field— in the same file. This makes it very easy to share GEOS-Chem output with other researchers.

We recommend that you ask your IT staff 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). You may be able to load a netCDF library version with the module command, i.e.

  module load netcdf

If you do not have a netCDF library already installed on your system, then you can use our installer to build netCDF yourself. Please see:

We have also collated the following references about netCDF, which you might find useful.

--Bob Yantosca (talk) 21:24, 2 November 2016 (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.

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:

--Bob Yantosca (talk) 21:10, 10 March 2017 (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:

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 the species/reactions/cross-sections in the photolysis mechanism
  • To specify diagnostic output options

For more information, please see the following resources:

--Bob Yantosca (talk) 14:40, 3 November 2016 (UTC)

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:

  • Meteorological data (a.k.a. the "met fields) used to drive GEOS–Chem
  • 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 GNU wget utility. (We recommend wget because it is much more flexible and can be used to download several directories recursively.)

For more information and detailed downloading instructions, please see:

--Bob Yantosca (talk) 19:42, 9 December 2016 (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 input.geos. New HEMCO restart files are written with frequency configured in HEMCO_Config.rc if HEMCO is used in your simulation.

GEOS-Chem v11-01 run directories are configured to use initial GEOS-Chem restart files in netCDF format. These files are available for download at:

ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/SPC_RESTARTS/

GEOS-Chem v10-01 and prior versions read and write GEOS-Chem restart files in binary punch (bpch) format. You can download a set of sample binary restart files here:

ftp://ftp.as.harvard.edu/gcgrid/data/ExtData/BPCH_RESTARTS/ 

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.

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 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 ncdump For example:

ncdump -v time -t initial_GEOSChem_rst.4x5_standard.nc

The -t 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 HEMCO_Config.rc. For more information, see the HEMCO User's Guide.

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

--Melissa Sulprizio (talk) 16:03, 12 January 2017 (UTC)

Visualization packages

In this section we provide information about software packages that you can use to analyze and plot GEOS-Chem output.

GAMAP and other IDL software

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 section below.

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:

We have also compiled a list of other useful IDL software sites.

--Bob Yantosca (talk) 15:51, 22 September 2017 (UTC)

Python software

Several developers have started creating Python-based visualization software for GEOS-Chem. Please see the following page for more information:

If you are new to programming in Python, you may find these tutorials useful:

--Bob Yantosca (talk) 15:48, 22 September 2017 (UTC)

The GEOS-Chem website

The GEOS-Chem website is located at http://www.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.

PLEASE NOTE: At this time, the GEOS-Chem User's Guide is only viewable in HTML.

--Bob Yantosca (talk) 18:02, 1 December 2016 (UTC)

The GEOS-Chem wiki

Overview

The GEOS-Chem wiki (i.e. this wiki) is located at: http://wiki.seas.harvard.edu/geos-chem/. The alias http://wiki.geos-chem.org also links to the wiki.

The wiki has many features that are designed to facilitate communication between GEOS-Chem users and developers. The following informaton is posted on the wiki:

  • The latest public version and current version in development
  • Getting started with GEOS-Chem
  • Technical Information
  • Information about the specifics of:
    • Chemistry mechanisms and specialty simulations
    • Emissions
    • Aerosols
    • Diagnostics
  • A list of bugs and when they were fixed
  • Information about meteorology used as input to GEOS-Chem
  • Information about data visualization and analysis

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.

Wiki Philosophy

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

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. The Main Page has links to several topics on the wiki but it does not link to every single page.

You can let the GEOS-Chem wiki inform you of recent updates to the site via RSS. Click here to find out how. You will never miss a discussion!

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).

We invite all GEOS-Chem users to read our post about wiki user culture.

--Bob Yantosca (talk) 15:44, 3 November 2016 (UTC)

GEOS-Chem tutorials

Please see the following GEOS-Chem tutorials, mostly taken from previous GEOS-Chem meetings:

--Melissa Sulprizio (talk) 19:32, 12 May 2017 (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:

--Bob Yantosca (talk) 17:20, 3 November 2016 (UTC)