Difference between revisions of "Compiling GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(Specifying compiler flags)
 
(196 intermediate revisions by 3 users not shown)
Line 1: Line 1:
On this page we list information about the makefiles used to build the GEOS-Chem executable.  Please also see [http://acmg.seas.harvard.edu/geos/doc/man/chapter_3.html#3.3 Chapter 3.3: GEOS-Chem Makefiles] of the GEOS-Chem Online User's Guide.
+
__FORCETOC__
 +
'''''[[HISTORY.rc_and_other_configuration_files|Previous]] | [[Compiling with CMake|Next]] | [[Getting Started with GEOS-Chem]]'''''
 +
#[[Minimum system requirements for GEOS-Chem|Minimum system requirements (and software installation)]]
 +
#[[Configuring your computational environment]]
 +
#[[Downloading GEOS-Chem source code|Downloading source code]]
 +
#[[Downloading GEOS-Chem data directories|Downloading data directories]]
 +
#[[Creating GEOS-Chem run directories|Creating run directories]]
 +
#[[GEOS-Chem configuration files|Configuring runs]]
 +
#<span style="color:blue">'''Compiling'''</span>
 +
#*[[Compiling with CMake|... with CMake]]
 +
#*[[Compiling with GNU Make|... with GNU Make]]
 +
#[[Running GEOS-Chem|Running]]
 +
#[[GEOS-Chem output files|Output files]]
 +
#[[Python tools for use with GEOS-Chem]]
 +
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
 +
#[[GEOS-Chem_overview#Further_reading|Further reading]]
 +
 
  
 
== Overview ==
 
== Overview ==
  
Starting with [[GEOS-Chem v8-02-03]], we have modified the directory structure of GEOS-Chem.  Rather than keeping all source code files in a single directory, we now have partitioned source code files into several subdirectories with most subdirectories having their own Makefile. This was done for the following reasons:
+
GEOS-Chem and GCHP use two build systems to compile source code files into an executable file:
  
:1. To facilitate the installation of 3rd-party software packages such as:
+
#[[Compiling with GNU Make|GNU Make]]
:* [[HEMCO]]
+
#[[Compiling with CMake|CMake]]
:* [[Coupling_GEOS-Chem_with_RRTMG|RRTMG radiative transfer model]]
+
:* [[KPP solvers FAQ|KPP chemical solver]]
+
:* Aerosol microphysics codes (e.g. [[APM_aerosol_microphysics|APM]])
+
:* [[ISORROPIA II]]
+
:* Terrestrial models (e.g. CASA, [[Global Terrestrial Mercury Model|GTMM]])
+
:into GEOS-Chem.  Our guiding principle is that all 3rd-party software packages should be cleanly separable from the main-line GEOS-Chem code.  This will allow the 3rd-party software packages to be updated without having an impact on the rest of the GEOS-Chem source code files.
+
  
:2. To simplify the maintenance of the GEOS–Chem code files. Without subdirectories, there would have been hundreds of source code files in a single directory, and it would have been very difficult to keep track of them all.
+
Starting in 13.0.0 both GEOS-Chem "Classic" and GCHP use CMake exclusively.
  
== Directory Structure ==
+
== Which versions can use GNU Make and which can use CMake? ==
  
Here we list the directory structure for recent model versions.
+
=== GEOS-Chem "Classic" compatibility matrix ===
  
=== GEOS-Chem v10-01 ===
+
Some GEOS-Chem "Classic" versions are compatible with both [[Compiling with CMake|CMake]] and [[Compiling with GNU Make|GNU Make]], as shown below.
  
The table below lists the directory structure in [[GEOS-Chem v10-01]] along with descriptions of each subdirectory and its Makefile (if one is present).
+
{| border=1 cellpadding=5 cellspacing=0
 +
|-bgcolor="#CCCCCC" valign="top"                 
 +
!width="230px"|GEOS-Chem "Classic" version
 +
!width="150px"|Uses GNU Make?
 +
!width="150px"|Uses CMake?
  
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" align="center"
|- bgcolor="#CCCCCC"
+
|[[GEOS-Chem 12#12.5.0|12.5.0]] and prior
!width="150px"|Directory
+
|bgcolor="#00FF00"|'''YES'''
!width="550px"|Description
+
|bgcolor="#FF0000"|'''NO'''
!width="350px"|Is there a Makefile here?
+
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code</tt>
+
|12.6.*
|Main-level directory for GEOS-Chem
+
|bgcolor="#00FF00"|'''YES'''
|Yes, there are two:
+
|bgcolor="#00FF00"|'''YES'''
*<tt>Makefile</tt> is the main-level router makefile and it calls down to the makefile in <tt>GeosCore</tt>.
+
*<tt>Makefile_header.mk</tt> defines compilation and linking commands for the Fortran-90 compilers. These commands are common to the makefiles in all subdirectories.
+
  
 +
|-valign="top" align="center"
 +
|12.7.*
 +
|bgcolor="#00FF00"|'''YES'''
 +
|bgcolor="#00FF00"|'''YES'''
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/GTMM</tt>
+
|12.8.*
|Directory containing source code files for the [[Global_Terrestrial_Mercury_Model|Global Terrestrial Mercury Model (GTMM)]] simulation
+
|bgcolor="#00FF00"|'''YES'''
|Yes, it compiles the code in <tt>GTMM</tt> and creates library file <tt>lib/libHg.a</tt>
+
|bgcolor="#00FF00"|'''YES'''
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/GeosApm</tt>
+
|12.9.*
|Directory containing parallel copied of GEOS-Chem source code files that were modified for the [[APM aerosol microphysics]] package
+
|bgcolor="#00FF00"|'''YES'''
|Yes, this is the main makefile for GEOS-Chem with APM. It calls down to the makefiles in the other subdirectories. It then compiles the code in <tt>GeosApm</tt> and <tt>GeosCore</tt> and creates the <tt>geosapm</tt> executable.
+
|bgcolor="#00FF00"|'''YES'''
  
'''NOTE: Due to the many wide-sweeping updates (e.g. HEMCO, UCX, SOA) made in recent versions of GEOS-Chem, the APM package is now no longer compatible with [[GEOS-Chem v10-01]].  The APM team is currently working on bringing APM up to date.'''
+
|-valign="top" align="center"
 +
|13.0.0 and later
 +
|bgcolor="#FF0000"|'''NO'''
 +
|bgcolor="#00FF00"|'''YES'''
  
|-valign="top"
 
|<tt>Code/GeosCore</tt>
 
|Directory containing most GEOS-Chem modules and routines
 
|Yes, this is the main makefile for GEOS-Chem. It calls down to the makefiles in the other subdirectories. It then compiles the code in the <tt>GeosCore</tt> directory and creates the <tt>geos</tt> executable.
 
 
|-valign="top"
 
|<tt>Code/GeosRad</tt>
 
|Directory containing source code files for the [[Coupling_GEOS-Chem_with_RRTMG|RRTMG radiative transfer model]]
 
|Yes, it compiles the code in <tt>GeosRad</tt> and creates library file <tt>lib/librad.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/GeosUtil</tt>
 
|Directory containing GEOS-Chem utility modules
 
|Yes, it compiles the code in <tt>GeosUtil</tt> and creates library file <tt>lib/libGeosUtil.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/HEMCO</tt>
 
|Main-level directory for [[HEMCO]]
 
|Yes, it calls down to the makefiles in the other HEMCO subdirectories.
 
 
|-valign="top"
 
|<tt>Code/HEMCO/Core</tt>
 
|Directory containing HEMCO modules and routines for reading, storing, and updating data used for calculating emissions
 
|Yes, it compiles the code in <tt>HEMCO/Core</tt> and creates library file <tt>lib/libHCO.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/HEMCO/Extensions</tt>
 
|Directory containing HEMCO modules and routines for calculating emissions that depend on meteorological input variables and/or non-linear parameterizations
 
|Yes, it compiles the code in <tt>HEMCO/Extensions</tt> and creates library file <tt>lib/libHCOX.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/HEMCO/Interfaces</tt>
 
|Directory containing HEMCO modules and routines that provide the link between HEMCO and the model environment
 
|Yes, it compiles the code in <tt>HEMCO/Interfaces</tt> and creates library file <tt>lib/libHCOI.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/Headers</tt>
 
|Directory containing module files with fixed parameters and derived-type definitions
 
*NOTE: In previous versions, these files were header files that were inlined via the <tt>#include</tt> statement.  These have since been converted to F90 modules in order to facilitate [[Grid-Independent GEOS-Chem]] development.
 
|Yes, it compiles the code in <tt>Headers</tt> and creates library file <tt>lib/libHeaders.a</tt>
 
 
|-valign="top"
 
|<tt>Code/ISOROPIA</tt>
 
|Directory containing the unmodified [[ISORROPIA_II|ISORROPIA II]] source code files from Thanos Nenes and Havala Pye:
 
* <tt>isoropiaIIcode.F</tt>
 
* <tt>isrpia.inc</tt>
 
|Yes, it compiles the code in <tt>ISOROPIA</tt> and creates library file <tt>lib/libIsoropia.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/KPP</tt>
 
|Main-level directory for the [[KPP_solvers_FAQ|KPP chemical solver]]
 
|Yes, it calls down to the makefiles in the other KPP subdirectories.
 
 
|-valign="top"
 
|<tt>Code/KPP/standard</tt>
 
|Directory containing KPP source code files for the [[NOx-Ox-HC-aerosol|standard chemistry mechanism]]
 
|Yes, it compiles the code in <tt>KPP/standard</tt> and creates library file <tt>lib/libKpp.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/KPP/SOA</tt>
 
|Directory containing KPP source code files for the [[Secondary_organic_aerosols|SOA chemistry mechanism]]
 
|Yes, it compiles the code in <tt>KPP/standard</tt> and creates library file <tt>lib/libKpp.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/KPP/UCX</tt>
 
|Directory containing KPP source code files for the [[UCX_chemistry_mechanism|UCX chemistry mechanism]]
 
|Yes, it compiles the code in <tt>KPP/standard</tt> and creates library file <tt>lib/libKpp.a</tt>.
 
 
|-valign="top"
 
|<tt>Code/KPP/int</tt>
 
|Directory containing the integrators (rosenbrock, runge-kutta, lsodes, etc.) for KPP
 
|No
 
 
|-valign="top"
 
|<tt>Code/NcdfUtil</tt>
 
|Directory containing source code files for netCDF I/O. This code is from Bob Yantosca's NcdfUtilities package
 
|Yes, it compiles the code in <tt>NcdfUtil</tt> and creates library file <tt>lib/libNcUtils.a</tt>.
 
 
 
|-valign="top"
 
|<tt>Code/NcdfUtil/perl</tt>
 
|Directory containing perl scripts from the NcdfUtilities package that can be used to generate Fortran code for defining, writing, and reading a netCDF file
 
|No
 
 
|-valign="top"
 
|<tt>Code/bin</tt>
 
|Directory where executable (<tt>geos</tt>, <tt>geostomas</tt>, <tt>geosapm</tt>) files will be sent
 
|No
 
 
|-valign="top"
 
|<tt>Code/doc</tt>
 
|Directory where automatic documentation is built
 
|Yes, it calls the ProTeX script to create reference manuals (in PS and PDF formats) from the comments in GEOS-Chem module and routine headers.
 
 
|-valign="top"
 
|<tt>Code/help</tt>
 
|Directory containing GEOS-Chem help screen
 
|Yes, it prints the GEOS-Chem help screen to stdout
 
 
|-valign="top"
 
|<tt>Code/lib</tt>
 
|Directory where library (<tt>*.a</tt>) files will be created
 
|No
 
 
|-valign="top"
 
|<tt>Code/mod</tt>
 
|Directory where module (<tt>*.mod</tt>) files will be sent
 
|No
 
 
|-valign="top"
 
|<tt>Code/obsolete</tt>
 
|Directory where obsolete source code files are placed for reference if needed
 
|No
 
 
|}
 
|}
  
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 13:46, 15 April 2015 (EDT)
+
=== GCHP compatibility matrix ===
  
=== GEOS-Chem v9-02 ===
+
Unlike GEOS-Chem "Classic", GCHP had a "hard" transition from GNU Make to CMake in 13.0.0:
  
The table below lists the directory structure in [[GEOS-Chem v9-02]] along with a description of each subdirectory and its Makefile (if one is present).
+
{| border=1 cellpadding=5 cellspacing=0
 +
|-bgcolor="#CCCCCC" valign="top"                 
 +
!width="230px"|GCHP version
 +
!width="150px"|Uses GNU Make?
 +
!width="150px"|Uses CMake?
  
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" align="center"
|- bgcolor="#CCCCCC"
+
|[[GEOS-Chem 12#12.5.0|12.5.0]] and prior
!width="150px"|Directory
+
|bgcolor="#00FF00"|'''YES'''
!width="550px"|Description
+
|bgcolor="#FF0000"|'''NO'''
!width="350px"|Is there a Makefile here?
+
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code</tt>
+
|12.6.*
|Main level GEOS-Chem directory
+
|bgcolor="#00FF00"|'''YES'''
|Yes, there are two:
+
|bgcolor="#FF0000"|'''NO'''
*<tt>Makefile</tt> is the main-level router makefile and it calls down to the makefile in <tt>GeosCore</tt>.
+
*<tt>Makefile_header.mk</tt> defines compilation and linking commands for the Fortran-90 compilers. These commands are common to the makefiles in all subdirectories.
+
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/Headers</tt>
+
|12.7.*
|Directory containing module files with fixed parameters and derived-type definitions
+
|bgcolor="#00FF00"|'''YES'''
*NOTE: In previous versions, these files were header files that were inlined via the <tt>#include</tt> statement.  These have since been converted to F90 modules in order to facilitate [[Grid-Independent GEOS-Chem]] development.
+
|bgcolor="#FF0000"|'''NO'''
|Yes, it compiles the code in <tt>Headers</tt> and creates library file <tt>lib/libHeaders.a</tt>
+
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/GeosUtil</tt>
+
|12.8.*
|Directory containing GEOS-Chem utility modules
+
|bgcolor="#00FF00"|'''YES'''
|Yes, it compiles the code in <tt>GeosUtil</tt> and creates library file <tt>lib/libGeosUtil.a</tt>
+
|bgcolor="#FF0000"|'''NO'''
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/GeosCore</tt>
+
|12.9.*
|Directory containing most GEOS-Chem modules and routines
+
|bgcolor="#00FF00"|'''YES'''
|Yes, this is the main Makefile for GEOS-Chem.  It calls down to the makefiles in the other subdirectories.
+
|bgcolor="#FF0000"|'''NO'''
  
|-valign="top"
+
|-valign="top" align="center"
|<tt>Code/ISOROPIA</tt>
+
|13.0.0 and later
|Directory containing the unmodified ISORROPIA II source code files from Thanos Nenes and Havala Pye:
+
|bgcolor="#FF0000"|'''NO'''
* <tt>isorropiaIIcode.F</tt>
+
|bgcolor="#00FF00"|'''YES'''
* <tt>isrpia.inc</tt>
+
|Yes, it compiles the code in <tt>ISOROPIA</tt> and creates library file <tt>lib/libIsoropia.a</tt>
+
  
|-valign="top"
 
|<tt>Code/KPP</tt>
 
|Main-level directory for KPP solver
 
|Yes, it calls down to the makefiles in the other KPP subdirectories.
 
 
|-valign="top"
 
|<tt>Code/KPP/standard</tt>
 
|Directory containing KPP source code files for the standard chemistry mechanism
 
|Yes, it compiles the code in <tt>KPP/standard</tt> and creates library file <tt>lib/libKpp.a</tt>
 
 
|-valign="top"
 
|<tt>Code/KPP/SOA</tt>
 
|Directory containing KPP source code files for SOA chemistry mechanism
 
|Yes, it compiles the code in <tt>KPP/standard</tt> and creates library file <tt>lib/libKpp.a</tt>
 
 
|-valign="top"
 
|<tt>Code/KPP/int</tt>
 
|Contains the integrators (rosenbrock, runge-kutta, lsodes, etc.) for KPP.
 
|No
 
 
|-valign="top"
 
|<tt>Code/doc</tt>
 
|Directory where automatic documentation is built
 
|Yes, it calls the ProTeX script to create reference manuals (in PS and PDF formats) from the comments in GEOS-Chem module and routine headers.
 
 
|-valign="top"
 
|<tt>Code/lib</tt>
 
|Directory where library (<tt>*.a</tt>) files will be created
 
|No
 
 
|-valign="top"
 
|<tt>Code/mod</tt>
 
|Directory where module (<tt>*.mod</tt>) files will be sent
 
|No
 
 
|-valign="top"
 
|<tt>Code/bin</tt>
 
|Directory where executable (<tt>geos</tt>) files will be sent
 
|No
 
 
|-valign="top"
 
|<tt>Code/help</tt>
 
|Directory containing GEOS-Chem help screen
 
|Yes, it prints the GEOS-Chem help screen to stdout
 
 
|-valign="top"
 
|<tt>Code/obsolete</tt>
 
|Directory where obsolete source code files are placed for future reference if need be
 
|No
 
 
|}
 
|}
 
 
'''''NOTE: Starting with [[GEOS-Chem v9-02]], the <tt>GeosTomas</tt> subdirectory has been removed and code for the TOMAS aerosol microphysics package has been inlined into the <tt>GeosCore</tt> directory using C-preprocessor statements. See the [[TOMAS_aerosol_microphysics#Update_April_2013"|TOMAS Aerosol Microphysics]] wiki page for more information.'''''
 
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 13:47, 15 April 2015 (EDT)
 
 
== Compilation sequence ==
 
 
GEOS-Chem's makefiles compile source code files in the following order:
 
#Files in <tt>NcdfUtil/</tt> (if [[Global_Terrestrial_Mercury_Model|GTMM]] is enabled for the [[Mercury|mercury simulation]])
 
#Files in <tt>Headers/</tt>
 
#Files in <tt>KPP/</tt>
 
#Files in <tt>GeosUtil/</tt>
 
#Files in <tt>HEMCO/Core/</tt>
 
#Files in <tt>HEMCO/Extensions/</tt>
 
#Files in <tt>HEMCO/Interfaces/</tt>
 
#Files in <tt>ISOROPIA/</tt>
 
#Files in <tt>GeosRad/</tt> (if [[Coupling_GEOS-Chem_with_RRTMG|RRTMG]] is enabled)
 
#Files in <tt>GeosCore/</tt>
 
 
Each of theses directories has its own makefile that contains a list of all of the source code files within the directory, plus dependent routines (a.k.a. the &quot;dependencies&quot; list). Source code files that do not refer to any modules have a dependencies list such as:
 
 
    decomp.o                    : decomp.F
 
 
Whereas a source code file that refers to several modules (in this case, <tt>GeosCore/aerosol_mod.F</tt>) has a dependencies list like this:
 
 
    aerosol_mod.o              : aerosol_mod.F                                  \
 
                                  chemgrid_mod.o          comode_mod.o          \
 
                                  dao_mod.o              diag_mod.o            \
 
                                  tracerid_mod.o          ucx_mod.o
 
 
Examination of <tt>GeosCore/aerosol_mod.F</tt> reveals that this module refers to many other modules not listed above. However, many of those modules are found in different directories (such as <tt>Headers/</tt> and <tt>GeosUtil/</tt>), which are compiled prior to <tt>GeosCore/</tt>. Therefore you do not need to list those modules when creating the dependencies listing. In the example above, we have only specified the 6 modules that are located in the same directory as <tt>aerosol_mod.F</tt>.
 
 
The order of modules in the dependencies list does not matter. The [http://www.gnu.org/software/make/ GNU Make] utility will define the order of compilation from the list of files (and their dependencies) that you have specified in each Makefile. You will not have to worry about this unless you add new source code files. If you have questions about how to add dependency lists to makefiles, please let us know.
 
 
--[[User:Melissa Payer|Melissa Sulprizio]] 12:54, 14 April 2015 (EDT)
 
 
== Compiling GEOS-Chem ==
 
 
=== Makefile Options ===
 
 
To compile GEOS-Chem, you must be in the top-level code directory or use a router Makefile that calls make within the top-level code directory. This section will describe make options when compiling from within the GEOS-Chem code directory. Information about using a router Makefile, such as the one included in run directories copied from the Unit Tester, is detailed in the [[GEOS-Chem Makefile Structure#Advanced compilation techniques|Advanced Compilation Techniques]] section of this page.
 
 
The GEOS-Chem Makefiles allow you to choose from several different options.  The best way to learn about these options is to type:
 
 
make help
 
 
at the Unix prompt.  You will then get a screen similar to this:
 
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
%%%      GEOS-Chem Help Screen      %%%
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
Usage: make -jN TARGET REQUIRED-FLAGS [ OPTIONAL-FLAGS ]
 
 
-jN            Compiles N files at a time (to reduce compilation time)
 
 
--------------------------------------------------------
 
TARGET may be one of the following:
 
--------------------------------------------------------
 
all            Default target (synonym for "lib exe")
 
lib            Builds GEOS-Chem source code
 
libcore        Builds GEOS-Chem objs & libs only in GeosCore/
 
libheaders      Builds GEOS-Chem objs & libs only in Headers/
 
libiso          Builds GEOS-Chem objs & libs only in ISOROPIA/
 
libkpp          Builds GEOS-Chem objs & libs only in KPP/
 
libnc          Builds GEOS-Chem objs & libs only in NcdfUtil/
 
librad          Builds GEOS-Chem objs & libs only in GeosRad/
 
libutil        Builds GEOS-Chem objs & libs only in GeosUtil/
 
ncdfcheck      Determines if the netCDF library installation works
 
exe            Creates GEOS-Chem executable
 
clean          Removes *.o, *.mod files in source code subdirs only
 
realclean      Removes all *.o, *mod, *.lib *.a, *.tex, *ps, *pdf files everywhere
 
distclean      Synonym for "make realclean"
 
doc            Builds GEOS-Chem documentation (*.ps, *.pdf) in doc/
 
docclean        Removes *.tex, *.pdf, *,ps from doc/
 
tauclean        Removes *.pdb, *.inst, *.pp, and *.continue.* files produced by TAU
 
help            Displays this help screen
 
 
Special targets for [[Global_Terrestrial_Mercury_Model|mercury simulation]]:
 
allhg          Default target for Hg simulation (synonym for "libhg exehg")
 
libhg          Builds GEOS-Chem code for Hg simulation
 
libgtmm        Builds GEOS-Chem + GTMM code for Hg simulation
 
exehg          Creates GEOS-Chem executable for Hg simulation
 
 
Special targets  for [[APM aerosol microphysics]]:
 
apm            Builds GEOS-Chem + APM (synonym for libapm exeapm)
 
libapm          Builds GEOS-Chem + APM objs & libs in GeosApm/ subdir
 
exeapm          Creates GEOS-Chem + APM executable in GeosApm/
 
cleanapm        Removes *.o *.mod files only in GeosApm/
 
 
--------------------------------------------------------
 
REQUIRED-FLAGS include:
 
--------------------------------------------------------
 
MET=____        Specifies the met field type
 
                --> Options: geosfp geos5 geos4 merra gcap
 
GRID=___        Specifies the horizontal grid
 
                --> Options: 4x5 2x25 05x0666 025x03125
 
 
--------------------------------------------------------
 
OPTIONAL-FLAGS may be one or more of the following:
 
--------------------------------------------------------
 
COMPILER=___    Specifies the compiler
 
                --> Options: ifort pgi (default is ifort)
 
NEST=___        Specifies the nested-grid domain
 
                  --> Options: CH NA EU SE
 
NO_REDUCED=yes  Compiles GEOS-Chem with the full vertical grid
 
                --> Default is to use the reduced vertical grid (i.e. NO_REDUCED=no)
 
 
Parallelization and optimization flags:
 
OMP=no          Turns off OpenMP parallelization (default is yes)
 
NONUMA=yes      Turns on -mp=nonuma option (pgi only, default is no)
 
IPO=yes        Turns on optmization options -ipo -static (ifort only, default is no)
 
OPT=___        Specifies the optimization level (default is -O2)
 
 
KPP chemistry solver flags:
 
CHEM=___        Specifies which chemistry mechanism is used
 
                --> Options: standard SOA UCX (default is standard)
 
KPPSOLVER=___  Specifies the integrator used with KPP
 
                --> Options: lsodes radau5 rosenbrock runge_kutta (default is rosenbrock)
 
 
Debug flags:
 
TRACEBACK=yes  Turns on -traceback option (ifort only, default is no)
 
DEBUG=yes      Turns on debugging options -g -O0 for running GEOS-Chem in a debugger (default is no)
 
BOUNDS=yes      Turns on subscript-array checking (default is no)
 
FPE=yes        Turns on checking for floating-point exceptions (default is no)
 
 
[[UCX_chemistry_mechanism|UCX trop-strat chemistry]] flags:
 
UCX=yes        Turns on the UCX chemistry mechanism and sets CHEM=UCX NO_REDUCED=yes (default is no)
 
 
[[Coupling_GEOS-Chem_with_RRTMG|RRTMG radiative transfer]] flags:
 
RRTMG=yes      Turns on online radiative transfer using the RRTMG model (default is no)
 
 
[[TOMAS aerosol microphysics]] flags:
 
TOMAS=yes      Turns on 30-bin TOMAS aerosol microphysics (default is no)
 
TOMAS12=yes    Turns on 12-bin TOMAS aerosol microphysics (default is no)
 
TOMAS15=yes    Turns on 15-bin TOMAS aerosol microphysics (default is no)
 
TOMAS40=yes    Turns on 40-bin TOMAS aerosol microphysics (default is no)
 
 
--[[User:Melissa Payer|Melissa Sulprizio]] 12:43, 8 April 2015 (EDT)
 
 
=== Specifying compiler flags ===
 
 
GEOS–Chem relies on several different C–preprocessor switches to inform the Fortran–90 compiler which options to include in the executable file. The C–preprocesor (or CPP for short) is a feature of the C and C++ programming languages that allows you to compile blocks of code only if certain conditions are met. All modern Fortran compilers have inherited the C–preprocessor feature. Therefore, even though GEOS–Chem is written in Fortran–90, we can still incorporate C–preprocesor commands into the source code.
 
 
The C-preprocessor switches used by GEOS-Chem include:
 
 
*Meteorological fields
 
*Horizontal and vertical grid information
 
*Compiler type
 
*Chemistry mechanism
 
*Options for special simulations (e.g. mercury)
 
*Debugging options
 
 
Switches are set with Makefile options from the command line by specifying compiler flags (e.g. UCX=y). Options that are not relevant to your system will be ignored. See the top-level GEOS-Chem router makefile for a complete list of compiler flag options (excerpted above).
 
 
Please keep the following items in mind when specifying compiler flags.
 
 
*When starting with a new version of GEOS-Chem or a new simulation type you should always issue the following command:
 
      make realclean
 
:This is especially important if you are changing the met field type or horizontal grid settings. The command will remove all previously-created compiler output files (e.g. *.a, *.o, *.mod) and executables. After doing <tt>make realclean</tt>, you can recompile GEOS–Chem again with your new options.
 
* You can speed up compilation by specifying <tt>make -j4</tt> to compile four files at a time. If you have more CPUs available you can change this number.
 
* You must specify a value for <tt>MET</tt>. Please see out [[Overview_of_GMAO_met_data_products|''Overview of GMAO met data products'' wiki page]] for more information on the meteorology fields. Note that the Makefile in run directories copied from the Unit Tester automatically extract MET from input.geos and do not need to be passed in the make command.
 
** Allowable values are: <tt>geosfp</tt>, <tt>geos5</tt>, <tt>geos4</tt>, <tt>merra</tt>, <tt>gcap</tt>
 
* You must specify a value for <tt>GRID</tt>. Please see [http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html Appendix 2 of the GEOS-Chem User's Guide] for more information on the horizontal grids. Note that the Makefile in run directories copied from the Unit Tester automatically extract GRID from input.geos and do not need to be passed in the make command.
 
** Allowable values are: <tt>4x5</tt>, <tt>2x25</tt>, <tt>05x0666</tt>, <tt>025x03125</tt>
 
* If you select <tt>GRID=05x0666</tt> or <tt>GRID=025x03125</tt>, then you must select a [[GEOS-Chem_nested_grid_simulations|nested-grid]] option. Note that the Makefile in run directories copied from the Unit Tester automatically extract NEST from input.geos and do not need to be passed in the make command. Options for NEST include:
 
**<tt>NEST=ch</tt> for the China nested grid
 
**<tt>NEST=na</tt> for the North America nested grid
 
**<tt>NEST=eu</tt> for the Europe nested grid
 
**<tt>NEST=se</tt> for the SE Asia nested grid (GEOS-FP only)
 
* Makefile target names are case-sensitive. For example, you should type <tt>make all</tt>, not <tt>make ALL</tt>.
 
* Makefile flags will accept case-insensitive output. You may omit dashes from met field names. Each of the following is acceptable:
 
**<tt>MET=geos5</tt>, <tt>MET=GEOS5</tt>, <tt>MET=Geos5</tt>, <tt>MET=geos-5</tt>, etc.
 
* Makefile flags that require a simple yes/no answer will accept case-insensitive input. For example:
 
**<tt>DEBUG=yes</tt>, <tt>DEBUG=Yes</tt>, <tt>DEBUG=y</tt>, <tt>DEBUG=No</tt>, <tt>DEBUG=NO</tt>, etc.
 
* Some debug compiler flags may slow down your simulation, so we recommend using them for short test simulations only. For more information, see [[#Compile-time_options_that_can_slow_down_GEOS-Chem|this wiki post]].
 
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 14:31, 15 April 2015 (EDT)
 
 
=== Setting default flags ===
 
 
The REQUIRED-FLAGS and OPTIONAL-FLAGS can be specified in one of two ways:
 
 
:1. '''As a command-line argument to the GNU Make utility'''
 
::For example, if you wanted to build the GEOS-Chem executable using the [[KPP_solvers_FAQ#Which_KPP_solvers_can_I_use.3F|KPP solver with Rosenbrock integrator]] and the [[Secondary_organic_aerosols|SOA mechanism]] you could type:
 
        make -j4 MET=geosfp GRID=4x5 KPPSOLVER=rosenbrock CHEM=SOA
 
 
:2. '''As an environment variable'''
 
::If you don't wish to keep typing KPPSOLVER=rosenbrock CHEM=SOA every time, you could instead use:
 
 
        setenv KPPSOLVER rosenbrock
 
        setenv CHEM      SOA
 
        make -j4 MET=geosfp GRID=4x5
 
 
::Specifying options as environment variables allows you to predefine settings so that you don't have to physically type them on the command line every time you build GEOS-Chem.  The environment variables can also be placed in your <tt>~/.cshrc</tt> or <tt>.bashrc</tt> so that they are initialized when you log in.
 
 
--[[User:Melissa Payer|Melissa Sulprizio]] 18:04, 7 April 2015 (EDT)
 
 
=== Compiling examples ===
 
 
(1) To build GEOS-Chem executable for the 4x5 grid with [[GEOS-FP]] meteorology, one can simply type:
 
 
    make -j4 MET=geosfp GRID=4x5
 
 
(2) To select a different compiler (e.g. PGI), type:
 
 
    make -j4 MET=geosfp GRID=4x5 COMPILER=pgi
 
 
<blockquote>
 
* Depending on your PGI compiler setup, you may also have to add the option <tt>NONUMA=yes</tt>.
 
</blockquote>
 
 
(3) The default is to compile for multi-processor.  To turn off the parallelization and build the executable for a single-processor, type:
 
 
    make -j4 MET=geosfp GRID=4x5 OMP=no
 
 
(4) To compile GEOS-Chem (multi-processor) for use with a debugger (e.g. Totalview), type:
 
 
    make -j4 MET=geosfp GRID=4x5 DEBUG=yes FPE=yes OMP=yes
 
 
(5) To compile GEOS-Chem (single-processor) with the same debugging options, type:
 
 
    make -j4 MET=geosfp GRID=4x5 DEBUG=yes FPE=yes OMP=no
 
 
(6) To test for [[Common_GEOS-Chem_error_messages#Array-out-of-bounds_error|array-out-of-bounds errors]], type:
 
 
    make -j4 MET=geosfp GRID=4x5 BOUNDS=yes
 
 
(7) If you wish to compile the code but not make the executable, you may type:
 
 
    make -j4 MET=geosfp GRID=4x5 BOUNDS=yes lib
 
 
(8) To print the GEOS-Chem help screen, type::
 
 
    make help
 
 
(9) To generate [http://acmg.seas.harvard.edu/geos/doc/man/chapter_9.html#Reference GEOS-Chem Reference Guide documentation] in PostScript and PDF formats, type:
 
 
    make doc
 
 
(10) To remove all <tt>*.o</tt>, <tt>*.mod</tt>, and executable files from the source code directories (but not from the <tt>mod</tt>, <tt>lib</tt>, or <tt>bin</tt> directories), type:
 
 
    make clean
 
 
(11) And to remove everything and start over from scratch, type:
 
 
    make realclean
 
 
--[[User:Melissa Payer|Melissa Sulprizio]] 18:19, 7 April 2015 (EDT)
 
 
=== Advanced compilation techniques ===
 
 
==== Compiling with Unix shell scripts ====
 
 
It is possible to write a shell script to compile the GEOS–Chem code, such as the following:
 
 
    #!/bin/tcsh -f                      # Script definition line
 
    cd Code.v9-02                        # your code dir
 
    rm -f log                            # clear log file
 
    make -j4 MET=geos5 GRID=4x5 > log    # build the code
 
    exit(0)                              # exit normally
 
 
You can then run this script interactively, or submit it to the queue system on your computational cluster.
 
 
==== Compiling with a run-directory Makefile ====
 
 
The GNU Make utility is a powerful and flexible software development tool. With a little effort, you can design a Makefile that can be placed into your GEOS–Chem run directory that will create a GEOS–Chem executable and start a simulation. Here is an example:
 
 
# This makefile is a "router" makefile.  It calls the Makefile
 
# in the GEOS-Chem code directory (with various user-supplied options)
 
# to build and run the GEOS-Chem model.
 
 
# Define variables
 
SHELL  = /bin/bash
 
 
# Make the development version "Code" the default directory
 
ifndef GEOSDIR
 
GEOSDIR = /home/bmy/Code.v10-01
 
endif
 
 
# Date string DDDHHMM
 
DATE = `date +%j%H%M`
 
 
#=============================================================================
 
# Makefile targets: type "make help" for a complete list!
 
#=============================================================================
 
 
.PHONY: all geos clean realclean fileclean doc docclean help logclean
 
 
all: geos
 
 
geos:
 
@$(MAKE) -C $(GEOSDIR)
 
cp -f $(GEOSDIR)/bin/geos .
 
@$(MAKE) logclean
 
  ./geos > log.$(DATE) &
 
tail -f log.$(DATE)
 
 
clean:
 
@$(MAKE) -C $(GEOSDIR) clean
 
@$(MAKE) logclean
 
 
realclean:
 
@$(MAKE) -C $(GEOSDIR) realclean
 
@$(MAKE) fileclean
 
rm -f geos
 
 
fileclean:
 
@$(MAKE) logclean
 
rm -f ctm.bpch*
 
rm -f Ox.mass.*
 
rm -f *2013080100*
 
rm -f *.run.*o*
 
 
doc:
 
@$(MAKE) -C $(GEOSDIR) doc
 
 
docclean:
 
@$(MAKE) -C $(GEOSDIR) docclean
 
 
help:
 
@$(MAKE) -C $(GEOSDIR) help
 
 
logclean:
 
rm -f *.log
 
 
At the heart of this Makefile are two important blocks of code, the first being:
 
 
# Make the development version "Code" the default directory
 
ifndef GEOSDIR
 
GEOSDIR = /home/bmy/Code.v10-01
 
endif
 
 
# Date string DDDHHMM
 
DATE = `date +%j%H%M`
 
 
This block defines the location of the GEOS–Chem source code directory, which is saved in a variable called <tt>GEOSDIR</tt>. If a value for <tt>GEOSDIR</tt> is not passed as a command-line argument, then <tt>GEOSDIR</tt> will be set to <tt>/home/bmy/Code.v10-01</tt> (you can edit this location for your own setup). Also, a default date/time string is saved in the variable <tt>DATE</tt>. This date/time string will be appended to the GEOS–Chem log file output.
 
 
The second block of code is used to compile and run the GEOS–Chem code:
 
 
geos:
 
@$(MAKE) -C $(GEOSDIR)
 
cp -f $(GEOSDIR)/bin/geos .
 
@$(MAKE) logclean
 
  ./geos > log.$(DATE) &
 
tail -f log.$(DATE)
 
 
The lines:
 
 
@$(MAKE) -C $(GEOSDIR)
 
cp -f $(GEOSDIR)/bin/geos .
 
 
tell GNU Make to call down to the router makefile in the GEOS–Chem source code directory <tt>/home/bmy/Code.v10-01</tt>. GNU Make will compile GEOS–Chem and create the executable file <tt>/home/bmy/Code.v10-01/bin/geos</tt>. This file is then copied to the run directory.
 
 
The next 3 lines:
 
 
@$(MAKE) logclean
 
./geos > log.$(DATE) &
 
tail -f log.$(DATE)
 
 
removes the log file if it already exists, runs the GEOS–Chem executable (thus starting the simulation), and follows the log file output with the Unix <tt>tail -f</tt> command.
 
 
--[[User:Melissa Payer|Melissa Sulprizio]] 13:46, 8 April 2015 (EDT)
 
 
== Technical Issues ==
 
 
=== GNU Make is required ===
 
 
The makefiles described above are designed to be used with [http://www.gnu.org/software/make/ GNU Make].  This is free, open-source software and is bundled with most of the popular Unix versions today (e.g. various Linux builds, Ubuntu, Fedora, etc.). 
 
 
It is recommended to use GNU Make because not all Unix make utilities are compatible with each other.  GNU Make is probably the most flexible make utility available. 
 
 
If GNU Make is not already installed on your system, then you (or your IT guru) will have to install it.  You can check to see if GNU Make is already installed by typing:
 
 
make --version
 
 
at the Unix prompt.  GNU Make will display a version screen similar to this:
 
 
GNU Make 3.81
 
Copyright (C) 2006  Free Software Foundation, Inc.
 
This is free software; see the source for copying conditions.
 
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
 
PARTICULAR PURPOSE.
 
 
This program built for x86_64-redhat-linux-gnu
 
 
Please also read the [http://acmg.seas.harvard.edu/geos/wiki_docs/GNU_Make.pdf GNU Make Reference Document] for more detailed information.
 
 
=== Install LaTeX utilities for auto documentation ===
 
 
Many of the updated GEOS-Chem source code files now use the [[Automatic documentation with protex|ProTeX documentation headers]].  The <tt>protex</tt> script (included in the <tt>Code/doc</tt> subdirectory) strips the information from the documentation headers located in GEOS-Chem
 
 
* Modules
 
* Subroutines
 
* Functions
 
* Include files
 
 
and creates a LaTeX format <tt>(*.tex)</tt> file.  The <tt>latex</tt> utility can then be used to produce output in PDF (<tt>*.pdf</tt>) and PostScript (<tt>*.ps</tt>) formats from the LaTeX file.  This all happens automatically when you type:
 
 
make doc
 
 
at the Unix prompt.  However, you must make sure to have the LaTeX utilities installed on your machine in order to be able to generate this automatic documentation.  The LaTeX utilities include:
 
 
;latex  : Converts LaTeX format files to Device-Independent format (<tt>*.dvi</tt>)
 
;dvips  : Converts Device-Independent format to PostScript format
 
;dvipdf : Converts Device-Independent format to PDF format
 
 
The LaTeX utilities may be packaged with your version of Unix.  Ask your IT guru for more information.
 
 
You may also want to install the following packages:
 
 
;ghostview : Reader for PostScript files
 
;acroread  : Adobe Acrobat Reader for PDF files
 
 
--[[User:Bmy|Bob Y.]] 09:48, 24 September 2009 (EDT)
 
 
=== Backup files not excluded from compilation ===
 
 
'''''[mailto:mzatko@u.washington.edu Maria Zatko] wrote:'''''
 
 
:During compilation using [[GEOS-Chem v8-02-04|version v8-02-04]], the compilation cannot be completed because the <tt>.f~</tt> file type is not recognized.  The model runs successfully once I manually remove the <tt>.f~</tt> files from the code.
 
 
:Is there a way to run v8-02-04 while keeping the backup files in the code as done in v8-03-01 and v8-02-01?
 
 
'''''[mailto:yantosca@seas.harvard.edu Bob Yantosca] wrote:'''''
 
 
:Yes...I think in some v8-02-xx versions of the code we may have had a wildcard that grepped for <tt>*.f*</tt> in the Makefile.  This would have tried to compile the <tt>*.f~</tt> files that are generated when you use Emacs to edit the code.
 
 
:In the GeosCore/Makefile you can replace any lines that look like:
 
 
    # Source and object files
 
    SRC  = $(wildcard *.F*)
 
 
:with
 
 
    # Source and object files
 
    SRC  = $(wildcard *.F) $(wildcard *.F90)
 
 
:and this should exclude all <tt>*.f~</tt> and <tt>*.f90~</tt> files from the compilation.  This fix has since been standardized in [[GEOS-Chem v8-03-01]].
 
 
--[[User:Bmy|Bob Y.]] 13:58, 27 August 2010 (EDT)
 
 
=== Compile-time options that can slow down GEOS-Chem ===
 
 
The following compile-time options can cause a GEOS-Chem job to run more slowly than usual:
 
 
;DEBUG=yes: This is required for running GEOS-Chem in a debugger such as idb or Totalview.  This will invoke the <tt>-g -O0</tt> compiler options, which turn off all optimization.
 
;BOUNDS=yes: This option turns on runtime [[Common GEOS-Chem error messages#Array out-of-bounds error|array-out-of-bounds]] checking, which looks for instances of invalid array indices (i.e. If the <tt>A</tt> array only has 10 elements but you try to reference <tt>A(11)</tt>.)
 
;FPE=yes: This option turns on error checking for floating-point exceptions (i.e. div-by-zero, NaN, floating-invalid, and similar errors).
 
;OMP=no: This option turns off the OpenMP parallelization (which is turned on by default).
 
 
If you have selected any of the above options, then try compiling GEOS-Chem from scratch, i.e.,
 
 
make realclean
 
make -j4 MET=____ GRID=____
 
 
and then re-run your GEOS-Chem job.
 
 
--[[User:Bmy|Bob Y.]] 15:47, 2 October 2013 (EDT)
 
 
== Known issues ==
 
 
=== Compiler cannot find certain files ===
 
 
This issue can occur in [[GEOS-Chem v9-01-01]] and older versions.  We have added this fix into [[GEOS-Chem v9-01-02]] and higher versions.
 
 
'''''[mailto:matthew.s.johnson@nasa.gov Matthew Johnson] wrote:'''''
 
 
:When looking into the core files I get error output such as this:
 
 
    Symbol file not found for main
 
    Core was generated by `./geos'.
 
    Program terminated with signal 11, Segmentation fault.
 
    #0  0x0000000000733bde in pjc_pfix_mod_mp_init_press_fix_ ()
 
 
:Have you seen this portion of the code causing a seg fault before?
 
 
'''''[mailto:yantosca@seas.harvard.edu Bob Yantosca] replied:'''''
 
 
:Try reordering the lines in <tt>GeosCore/Makefile</tt> from:
 
 
    lib: libkpp libutil libiso libcore
 
 
:to:
 
 
    lib:                                              # Build all G-C libraries                 
 
        @$(MAKE) libkpp                       
 
        @$(MAKE) libutil                 
 
        @$(MAKE) libiso                 
 
        @$(MAKE) libcore                 
 
 
:''NOTE: All indented lines begin with a TAB!''
 
 
:This ordering will force GNU Make to compile all of the files in <tt>KPP/</tt> first, then all of the files in <tt>GeosUtil/</tt>, etc.  This ought to prevent the build sequence from referencing files that haven't yet been compiled.
 
 
--[[User:Bmy|Bob Y.]] 14:02, 3 January 2013 (EST)
 
  
 
== References ==
 
== References ==
Line 759: Line 116:
 
#[http://www.gnu.org/software/make/manual/make.html GNU Make Manual]
 
#[http://www.gnu.org/software/make/manual/make.html GNU Make Manual]
 
#[http://oreilly.com/catalog/make3/book/index.csp Mecklenburg, Robert, ''Managing Projects with GNU Make, Third Edition'',, <u>O'Reilly and Associates</u>, 2004.]
 
#[http://oreilly.com/catalog/make3/book/index.csp Mecklenburg, Robert, ''Managing Projects with GNU Make, Third Edition'',, <u>O'Reilly and Associates</u>, 2004.]
 +
#''[[CMake FAQ]]'' by Liam Bindle
 +
#[https://cmake.org/cmake/help/latest/guide/tutorial/index.html ''CMake tutorial'' (cmake.org)]
 +
#[https://learnxinyminutes.com/docs/cmake/ ''Learn X in Y minutes (where X is CMake)'']
 +
  
--[[User:Bmy|Bob Y.]] 12:07, 19 July 2011 (EDT)
+
----
 +
'''''[[HISTORY.rc_and_other_configuration_files|Previous]] | [[Compiling with CMake|Next]] | [[Getting Started with GEOS-Chem]]'''''

Latest revision as of 15:22, 4 August 2022

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements (and software installation)
  2. Configuring your computational environment
  3. Downloading source code
  4. Downloading data directories
  5. Creating run directories
  6. Configuring runs
  7. Compiling
  8. Running
  9. Output files
  10. Python tools for use with GEOS-Chem
  11. Coding and debugging
  12. Further reading


Overview

GEOS-Chem and GCHP use two build systems to compile source code files into an executable file:

  1. GNU Make
  2. CMake

Starting in 13.0.0 both GEOS-Chem "Classic" and GCHP use CMake exclusively.

Which versions can use GNU Make and which can use CMake?

GEOS-Chem "Classic" compatibility matrix

Some GEOS-Chem "Classic" versions are compatible with both CMake and GNU Make, as shown below.

GEOS-Chem "Classic" version Uses GNU Make? Uses CMake?
12.5.0 and prior YES NO
12.6.* YES YES
12.7.* YES YES
12.8.* YES YES
12.9.* YES YES
13.0.0 and later NO YES

GCHP compatibility matrix

Unlike GEOS-Chem "Classic", GCHP had a "hard" transition from GNU Make to CMake in 13.0.0:

GCHP version Uses GNU Make? Uses CMake?
12.5.0 and prior YES NO
12.6.* YES NO
12.7.* YES NO
12.8.* YES NO
12.9.* YES NO
13.0.0 and later NO YES

References

  1. GNU Make Manual
  2. Mecklenburg, Robert, Managing Projects with GNU Make, Third Edition,, O'Reilly and Associates, 2004.
  3. CMake FAQ by Liam Bindle
  4. CMake tutorial (cmake.org)
  5. Learn X in Y minutes (where X is CMake)



Previous | Next | Getting Started with GEOS-Chem