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
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, mostly taken from previous GEOS-Chem meetings:

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