Compiling GEOS-Chem

From Geos-chem
Jump to: navigation, search

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Downloading source code
  3. Downloading data directories
  4. Creating run directories
  5. Configuring runs
  6. Compiling
  7. Running
  8. Output files
  9. Visualizing and processing output
  10. Coding and debugging
  11. Further reading


Overview

On this page we provide information about how to compile the GEOS-Chem source code into an executable file (geos) that you can run.

Setting the proper environment variables

IMPORTANT: Before you compile GEOS-Chem, please take a moment to make sure that you have defined the proper Unix environment variables that tell GEOS-Chem which compiler you are using, and where the netCDF library has been installed. For complete information, please see our our Setting Unix environment variables for GEOS-Chem wiki page.

Ways to compile GEOS-Chem

There are two basic ways to compile GEOS-Chem:

  1. Execute make commands in the run directory (RECOMMENDED)
  2. Execute make commands in the top-level code directory

NOTE: Starting in 12.6.0, you can compile GEOS-Chem using CMake instead of GNU Make. Please see our Building GEOS-Chem with CMake wiki page for more information.

Compiling in a run directory

*** RECOMMENDED COMPILING APPROACH ***

All run directories downloaded from the GEOS-Chem Unit Tester come with a router Makefile that enables you to easily compile and run GEOS-Chem from the run directory. Using this feature enables you to eliminate certain compile options from the make command that are always the same for a given run directory (e.g. MET and GRID) and thereby avoid common mistakes. It also creates and stores compile logs locally for easy reference.

Please see the Creating GEOS-Chem run directories wiki page for instructions on how to create a GEOS-Chem run directory from the GEOS-Chem Unit Tester.

Setting up the run directory Makefile

Once you have a run directory, open the Makefile in a text editor and edit the following three configurable variables with your preferences:

# Source code location
ifndef CODE_DIR
 CODE_DIR :=/home/$(USER)/GC/Code.v11-01
endif

# Output log file destination (default is run directory) 
ifndef LOG_DIR 
 LOG_DIR :=.
endif

# GEOS-Chem run log filename prefix
ifndef VERSION
 VERSION :=v11-01
endif

Each of these three variables are automatically passed to the make command using the default values you define in this file. Alternatively, you may define them at the terminal within the make call. For example, if you want to override your default CODE_DIR, you can include CODE_DIR=/GC/Code.Ref to compile Code.Ref rather than Code.Dev.

Makefile options

The compiler flags required for compiling GEOS-Chem, specifically MET and GRID, and in some cases NEST, TOMAS, RRTMG, or UCX, are automatically passed when you compile using the run directory Makefile. The flags are set using the getRunInfo perl script located in the run directory which reads the simulation information from the input.geos configuration file. If you wish to change any of these options you must create a new run directory.

There are two processing modes available for compiling GEOS-Chem:

  1. Single processor ("sp")
  2. Multi-processor ("mp"), which uses OpenMP parallelization

Output files, including the GEOS-Chem executable geos, have a .sp or .mp suffix depending on what processing mode is used.

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 Run Directory Makefile Help Screen    %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Usage: make -jN TARGET [OPTIONAL-FLAGS]

-jN               Compiles N files at a time (reduces compile time)

----------------------------------------------------------
TARGET may be one of the following:
----------------------------------------------------------
all               Default target (synonym for "unittest")

%%% COMPILE AND RUN %%%
unittest          Runs a GEOS-Chem unit test:
                  (1) Builds & runs GEOS-Chem with parallelization OFF;
                  (2) Builds & runs GEOS-Chem with parallelzation ON;
                  (3) Checks to see if the output is identical.
sp                Builds and runs GEOS-Chem with parallelization OFF.
mp                Builds and runs GEOS-Chem with parallelization ON.

%%% BUILD ONLY %%%
spbuild           Just builds GEOS-Chem with parallelization OFF.
mpbuild           Just builds GEOS-Chem with parallelization ON.

%%% RUN ONLY %%%
sprun             Just runs GEOS-Chem with parallelization OFF.
mprun             Just runs GEOS_Chem with parallelization ON.

%%% REMOVE DATA FILES %%%
dataclean         Removes ALL GEOS-Chem diagnostic and restart files
spdataclean       Removes diagnostic and restart files from GEOS-Chem
                    simulations with parallelization turned OFF.
mpdataclean       Removes diagnostic and restart files from GEOS-Chem
                    simulations with parallelization turned ON.

%%% REMOVE LOG FILES %%%
logclean          Removes all GEOS-Chem and HEMCO output log files.
splogclean        Removes GEOS-Chem and HEMCO log files from GEOS-Chem
                    simulations with parallelization turned OFF.
mplogclean        Removes GEOS-Chem and HEMCO log files from GEOS-Chems
                    simulations with parallelization turned ON.

%%% REMOVE EXECUTABLE FILES %%%
execlean          Removes all GEOS-Chem executable files
spexeclean        Removes GEOS-Chem executable files for which the
                    parallelization has been turned OFF.
mpexeclean        Removes GEOS-Chem executable files for which the
                    parallelization has been turned ON.

%%% REMOVE ALL FILES %%%
fileclean         Synonym for: dataclean   logclean   execlean
spclean           Synonym for: spdataclean splogclean spexeclean
mpclean           Synonym for: mpdataclean mplogclean mpexeclean

%%% REMOVE CONFIG FILES %%%
extrafileclean  Removes input.geos and HEMCO_Config.rc files

%%% CLEAN SOURCE CODE %%%
clean             Makes "clean" in source code directory ODE_DIR
realclean         Makes "realclean" in the source code directory ODE_DIR
tauclean          Removes all TAU files in the source code directory ODE_DIR

%%% CLEAN AND REMOVE ALL %%%
superclean        Synonym for: fileclean realclean

...

To compile only, type the following at the command line, including any optional compiler flags as needed:

make -j4 mpbuild

Prior to compiling, geos.mp, lastbuild.mp, and all .mp log files will be removed from the directory by calling other make targets mpexeclean and mplogclean. All standard output generated while building the new executable will be displayed in your terminal window. The executable created will reside in the /bin directory within CODE_DIR and a copy will be placed in the run directory with name geos.mp. Finally, your compile settings will be stored in log lastbuild.mp and will also be printed to the terminal window. The unix commands for each of these steps is stored under various targets in the Makefile. Note that you make call any of the make targets from the command line (e.g. make mplogclean to remove all .mp logs). You can then submit your GEOS-Chem simulation to your local cluster's queue using a simple script.

For testing purposes, you may also compile and run GEOS-Chem interactively, by typing the following at the command line:

make -j4 mp

With this option, output data files are appended with the .mp suffix except for restart and HEMCO diagnostic files that do not correspond to the simulation end date.

The GNU Make utility is a powerful and flexible software development tool and we encourage you to explore the existing Makefile options and to customize the Makefile to optimize your own needs.

--Lizzie Lundgren 10:59, 22 April 2015 (EDT)

Information from the last time GEOS-Chem was compiled

When compiling from the run directory Makefile, a file called lastbuild.mp or lastbuild.sp will be created. This file contains the settings that were used to compile GEOS-Chem, for your reference.

LAST BUILD INFORMATION:
 CODE_DIR     : ./CodeDir
 CODE_BRANCH  : dev/12.5.0
 LAST_COMMIT  : Merge branch GC_12.2.1_clddiag into dev/12.5.0 
 COMMIT_DATE  : Thu Jun 27 09:20:20 2019 -0400 
 VERSION      : 12.5.0
 VERSION_TAG  : GC_12.5.0
 MET          : geosfp
 GRID         : 4x5
 SIM          : benchmark
 NEST         : n
 TRACEBACK    : y
 BOUNDS       : n
 DEBUG        : n
 FPE          : n
 NO_ISO       : n
 NO_REDUCED   : y
 CHEM         : Standard
 TOMAS12      : n
 TOMAS15      : n
 TOMAS30      : n
 TOMAS40      : n
 RRTMG        : n
 MASSCONS     : n
 TIMERS       : 1
 TAU_PROF     : n
 BPCH_DIAG    : y
 COMPILER     : ifort 17.0.4
 Datetime     : 2019/06/28 08:47

Compiling in the top-level code directory

*** Please see Compiling in a run directory for the recommended compiling approach ***

Makefile Options

This section will describe make options when compiling from within the GEOS-Chem code directory. Note that starting in v11-01, we recommend that users compile from within the run directory by using the Makefile that comes with all run directories copied from the GEOS-Chem Unit Tester. Information about using a router Makefile, such as the one included in run directories copied from the Unit Tester, is detailed in the 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/
libhistory      Builds GEOS-Chem objs & libs only in History/
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


--------------------------------------------------------
OPTIONAL-FLAGS may be one or more of the following:
--------------------------------------------------------

Parallelization and optimization flags:
---------------------------------------
OMP=no          Turns off OpenMP parallelization
                --> Default: OMP=y

NONUMA=yes      Turns on -mp=nonuma option (pgi only)
                --> Default: OMP=n

IPO=yes         Turns on optmization options -ipo -static (ifort only)
                --> Default: IPO=n

OPT=___         Specifies the optimization level
                --> Defaults OPT=-O2 (ifort and pgi)
                             OPT=-O3 (gfortran)

M_ARCH=___      Specifies the CPU architecture (gfortran only)


Chemistry options:
------------------
CHEM=___        Specifies which chemistry mechanism is used
                --> Options: Standard Tropchem UCX SOA SOA_SVPOA
                --> Default: Standard

KPPSOLVER=___   Specifies the integrator used with KPP
                --> Options: lsodes radau5 rosenbrock runge_kutta
                --> Default: rosenbrock

RRTMG=y         Turns on online radiative transfer using the RRTMG model
                --> Default: RRTMG=n


Diagnostics options:
--------------------
BPCH_DIAG=n     Disable binary-punch output for diagnostics
                --> Default: BPCH_DIAG=y

BPCH_TPBC=n     Disable binary-punch I/O for nested-grid boundary
                condition files for TPCORE.
                --> Default: BPCH_TPBC=y (if NEST is specified)

BPCH_TIMESER=n  Disable binary-punch output for timeseries diagnostics
                (i.e. to maintain backwards compatibility until these
                diagnostics are available in netCDF format)
                --> Default: BPCH_TIMESER=y

NC_DIAG=y       Enable netCDF output for diagnostics
                --> Default: NC_DIAG=n

NC_NODEFLATE=y  Disable netCDF file compression when writing
                diagnostic or restart files to disk.  This may
                be necessary for debugging, in order to ensure
                that file compression does not cause problems
                when comparing netCDF files for identicality.
                --> Default: NC_NODEFLATE=n


Debugging flags:
----------------
BOUNDS=y        Turns on subscript-array checking
                --> Default: BOUNDS=n

DEBUG=y         Turns on options -g -O0 for running GEOS-Chem in a debugger
                --> Default: DEBUG=n

FPEX=y          Turns on checking for floating-point exceptions
                --> Default: FPEX=nn

FPE=y           Synonym for FPEX=y
                --> Default: FPE=n

TIMERS=___      Turn on GEOS-Chem timers (Use 1 for GEOS-Chem "Classic")
                --> Default: TIMERS=0

TRACEBACK=y     Print out a list of called routines if the run dies with an error
                --> Default: TRACEBACK=y
                --> To disable: TRACEBACK=n

GPROF=y         Compiles GEOS-Chem for use with the GNU profiler (aka gprof)
                --> Default: GPROF=n

TAU_PROF=y      Compiles GEOS-Chem for use with the TAU performance profiler
                --> Default: TAU_PROF=n

TAU_SF=___      Specifies the TAU selectfile for removing throttled files


Aerosol microphysics flags:
---------------------------------------
TOMAS=y         Turns on 30-bin TOMAS aerosol microphysics
                --> Default: TOMAS=n

TOMAS12=y       Turns on 12-bin TOMAS aerosol microphysics
                --> Default: TOMAS12=n

TOMAS15=y       Turns on 15-bin TOMAS aerosol microphysics
                --> Default: TOMAS15=n

TOMAS40=y       Turns on 40-bin TOMAS aerosol microphysics
                --> Default: TOMAS40=n


GCHP (GEOS-Chem "High Peformance") flags:
---------------------------------------
HPC=y           Compile GEOS-Chem for HPC environments (with ESMF & MAPL)
               --> Default: HPC=n

--Bob Yantosca (talk) 18:56, 16 May 2018 (UTC)

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 (removed in GEOS-Chem 12.4.0)
  • Horizontal and vertical grid information (removed in GEOS-Chem 12.4.0)
  • 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. NO_ISO=y). Options that are not relevant to your system will be ignored. Type make help at the command line while in the top-level GEOS-Chem source code directory 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
The command will remove all previously-created compiler output files (e.g. *.a, *.o, *.mod) and executables. After doing make realclean, you can recompile GEOS–Chem again with your new options. This is especially important if you are changing the met field type or horizontal grid settings in GEOS-Chem 12.3.2 and earlier versions. In GEOS-Chem 12.4.0 changing the met field or grid resolution does not require recompilation because those are set at run time in input.geos.
  • You can speed up compilation by specifying make -j4 to compile four files at a time. If you have more CPUs available you can change this number.
  • In GEOS-Chem 12.3.2 and earlier versions, you must specify a value for MET. Please see out 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: merra2, merrageosfp, geos5, geos4, and gcap
  • In GEOS-Chem 12.3.2 and earlier versions, you must specify a value for GRID. Please see GEOS-Chem horizontal grids for more information. 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: 4x5, 2x25, 05x0666, 025x03125
  • In GEOS-Chem 12.3.2 and earlier versions, if you select GRID=05x0666 or GRID=025x03125, then you must select a 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:
    • NEST=as for the Asia nested grid (MERRA-2 only)
    • NEST=ch for the China nested grid
    • NEST=na for the North America nested grid
    • NEST=eu for the Europe nested grid
  • Makefile target names are case-sensitive. For example, you should type make all, not make ALL.
  • Makefile flags will accept case-insensitive output. You may omit dashes from met field names. Each of the following is acceptable:
    • MET=geosfp, MET=GEOSFP, MET=GeosFp, MET=geos-fp, etc.
  • Makefile flags that require a simple yes/no answer will accept case-insensitive input. For example:
    • DEBUG=yes, DEBUG=Yes, DEBUG=y, DEBUG=No, DEBUG=NO, etc.
  • Some debug compiler flags may slow down your simulation, so we recommend using them for short test simulations only. For more information, see this wiki post.

--Melissa Sulprizio (talk) 19:05, 11 July 2019 (UTC)

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 solver with Rosenbrock integrator and the SOA mechanism you could type:
       make -j4 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 
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 ~/.cshrc or .bashrc so that they are initialized when you log in.

--Melissa Sulprizio (talk) 19:05, 11 July 2019 (UTC)

Compiling examples

All examples below are for compiling from the top-level GEOS-Chem source code directory. Note that starting in v11-01, we recommend that users compile from within the run directory by using the Makefile that comes with all run directories copied from the GEOS-Chem Unit Tester. The run directory router Makefile invokes the top-level code directory Makefile to execute any of the commands in the examples below but creates and stores log files locally in the run directory. See Compile with a run-directory Makefile section below for instructions.

Example of compiling with Make:

(1) To build GEOS-Chem executable, one can simply type:

   make -j4 

(2) To select a different compiler (e.g. PGI), type:

   make -j4 COMPILER=pgi
  • Depending on your PGI compiler setup, you may also have to add the option NONUMA=yes.

(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 OMP=no

(4) To compile GEOS-Chem (multi-processor) for use with a debugger (e.g. Totalview), type:

   make -j4 DEBUG=yes FPE=yes OMP=yes

(5) To compile GEOS-Chem (single-processor) with the same debugging options, type:

   make -j4 DEBUG=yes FPE=yes OMP=no

(6) To test for array-out-of-bounds errors, type:

   make -j4 BOUNDS=yes

(7) If you wish to compile the code but not make the executable, you may type:

   make -j4 BOUNDS=yes lib

(8) To print the GEOS-Chem help screen, type::

   make help

(9) To generate GEOS-Chem Reference Guide documentation in PostScript and PDF formats, type:

   make doc

(10) To remove all *.o, *.mod, and executable files from the source code directories (but not from the mod, lib, or bin directories), type:

   make clean

(11) And to remove everything and start over from scratch, type:

   make realclean

--Melissa Sulprizio (talk) 19:06, 11 July 2019 (UTC)

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

Technical Issues

GNU Make is required

The makefiles described above are designed to be used with 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 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 ProTeX documentation headers. The protex script (included in the Code/doc subdirectory) strips the information from the documentation headers located in GEOS-Chem

  • Modules
  • Subroutines
  • Functions
  • Include files

and creates a LaTeX format (*.tex) file. The latex utility can then be used to produce output in PDF (*.pdf) and PostScript (*.ps) 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:

Utility Description
latex Converts LaTeX format files to Device-Independent format (*.dvi)
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:

Utility Description
ghostview Reader for PostScript files
acroread Adobe Acrobat Reader for PDF files

--Bob Yantosca (talk) 18:29, 5 December 2016 (UTC)

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:

Command Description
DEBUG=y This is required for running GEOS-Chem in a debugger such as idb or Totalview. This will invoke the -g -O0 compiler options, which turn off all optimization.
BOUNDS=yes This option turns on runtime array-out-of-bounds checking, which looks for instances of invalid array indices (i.e. If the A array only has 10 elements but you try to reference A(11).)
FPEX=y or
FPE=y
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 with the above options off, i.e.,

make realclean
make -j4 mpbuild

and then re-run your GEOS-Chem job.

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

Compilation sequence

GEOS-Chem's makefiles compile source code files in the following order:

  1. Files in NcdfUtil/
  2. Files in KPP (first pass)
  3. Files in Headers/
  4. Files in GeosUtil/
  5. Files in KPP/ (second pass)
  6. Files in History/
  7. Files in HEMCO/Core/
  8. Files in HEMCO/Extensions/
  9. Files in HEMCO/Interfaces/
  10. Files in ISOROPIA/
  11. Files in GeosRad/ (if RRTMG is enabled)
  12. Files in GeosCore/

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 "dependencies" list). Source code files that do not refer to any modules have a dependencies list such as:

dao_mod.o                   : dao_mod.F                              

Whereas a source code file that refers to several modules (in this case, GeosCore/chemistry_mod.F) has a dependencies list like this:

chemistry_mod.o             : chemistry_mod.F90                              \
                              aerosol_mod.o           isoropiaII_mod.o       \
                              c2h6_mod.o              carbon_mod.o           \
                              dust_mod.o              drydep_mod.o           \
                              global_ch4_mod.o        mercury_mod.o          \
                              pops_mod.o                                     \
                              rpmares_mod.o           RnPbBe_mod.o           \
                              seasalt_mod.o           strat_chem_mod.o       \
                              sulfate_mod.o           tagged_co_mod.o        \
                              tagged_o3_mod.o         tomas_mod.o            \
                              flexchem_mod.o

Examination of GeosCore/chemistry_mod.F90 reveals that this module refers to many other modules not listed above. However, many of those modules are found in different directories (such as Headers/ and GeosUtil/), which are compiled prior to GeosCore/. 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 aerosol_mod.F.

The order of modules in the dependencies list does not matter. The 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.

Previous issues that have now been resolved

Add a more robust test for netCDF-Fortran in Makefile_header.mk

This update (a4d55055) was included in GEOS-Chem 12.0.1, which was released on 24 Aug 2018.

We have rewritten the test that determines if the netCDF-Fortran library file (libnetcdff.a) is in the same folder or a different folder than the netCDF-C library file (libnetcdf.a). The new test should be more robust and forgiving of user error.

Some users had reported an issue with the GEOS-Chem environment variable GC_F_INCLUDE was being added to the build sequence even if there is no netCDF-Fortran library. The new test will only add GC_F_INCLUDE to the build sequence if the netCDF-Fortran library is found on disk.

--Bob Yantosca (talk) 16:44, 24 August 2018 (UTC)

Removed the COMPILER variable from Makefile_header.mk for a cleaner build sequence

This update was included in v11-02a and approved on 12 May 2017.

Farid Amid wrote:

I was trying to compile the model v11.01 with for the nested domain using PGI compiler and following command:
     make -j4 MET=GEOS-FP GRID=025x03125 NEST=NA
The issue was that mod dir remained empty and I had compiler had difficulty finding mod files, the problem was resolved by changing line 1317 of Makefile_header.mk from pgfortran to pgi.

Bob Yantosca replied:

We have made a fix to v11-02a (under development) to remove the COMPILER variable in the Makefile. We now test the value of the FC environment variable with a regular expression to determine if it is the Intel, PGI, or GNU compiler family. (On most Unix software builds, the environment variable FC is the standard name for the Fortran compiler.) Sometimes the PGI compiler on a system is called pgf90, or else pgfortran, or sometimes pgi. The new Makefile test should be more robust and accept all of these alternatives.

--Bob Yantosca (talk) 20:31, 8 March 2017 (UTC)

Bug fix: Specifying NO_REDUCED=no now compiles GEOS-Chem for reduced grids

This fix was included in v11-02a and approved on 12 May 2017.

Jiawei Zhang wrote:

I found a small but annoying bug in Makefile_header.mk. The problem is that if I use NO_REDUCED=n (i.e. use 47 levels) as a compile option, then the makefile will treat it as NO_REDUCED=yes (i.e. use 72 levels). The LLPAR parameter will then be set to 72 instead of 47, leading to unexpected behavior. That's because Makefile_header.mk contains something like:
      # %%%%% REDUCED VERTICAL GRID (default, unless specified otherwise) %%%%
      ifndef NO_REDUCED
        USER_DEFS        += -DGRIDREDUCED
      else
        REGEXP           :=(^[Yy]|^[Yy][Ee][Ss])
        ifeq ($(shell [[ "$(NO_REDUCED)" =~ $(REGEXP) ]] && echo true),true)
        endif
      endif
The GRIDREDUCED C-preprocessor switch will only be activated if NO_REDUCED is not provided. The following "yes" or "no" just doesn't matter because the nested ifeq statement doesn't do anything. With this problem, the only way to compile a 47L model is NOT providing the NO_REDUCED option. It also affects compiling GEOS-Chem from the geosfp_4x5_tropchem rundir, because NO_REDUCED=n is one of the default options.

We have now fixed this issue by setting the NO_REDUCED Makefile variable to "no" by default, and then evaluating its value in a separate IF statement. This code has now been added to the Makefile_header.mk.

  # %%%%% REDUCED VERTICAL GRID (default, unless specified otherwise) %%%%
  ifndef NO_REDUCED
    NO_REDUCED       :=no
  endif
  REGEXP              :=(^[Nn]|^[Nn][Oo])
  ifeq ($(shell [[ "$(NO_REDUCED)" =~ $(REGEXP) ]] && echo true),true)
    USER_DEFS        += -DGRIDREDUCED
  endif

This fix now will compile GEOS-Chem for 47 levels when NO_REDUCED=no is specified, or if NO_REDUCED is omitted.

--Bob Yantosca (talk) 16:09, 1 March 2017 (UTC)

TRACEBACK=y is now the default setting

This update was included in GEOS-Chem v11-01 public release

Seb Eastham (Harvard) suggested that all GEOS-Chem simulations should use the traceback option by default. An example of traceback output generated by the Intel Fortran Compiler is shown below:

Image              PC                Routine            Line        Source             
libifcoremt.so.5   00002B9EFA2188D3  Unknown               Unknown  Unknown
geos.mp            00000000011FCE35  regrid_a2a_mod_mp        1914  regrid_a2a_mod.F90
libiomp5.so        00002B9EFB70A8A3  Unknown               Unknown  Unknown

The above example shows that the GEOS-Chem simulation exited abnormally at line 1914 of module regrid_a2a_mod.F90. We believe that having this information available will help GEOS-Chem users to better diagnose and report issues.

We have modified the Makefile_header.mk file in the GEOS-Chem v11-01 public release to set the Makefile option TRACEBACK=y if it is not already passed as an argument. To disable the traceback output, you will now have to compile with TRACEBACK=n.

It should be noted that the traceback option will increase the size of the GEOS-Chem executable, but will not have any impact on execution speeds.

--Bob Yantosca (talk) 22:27, 3 January 2017 (UTC)

References

  1. GNU Make Manual
  2. Mecklenburg, Robert, Managing Projects with GNU Make, Third Edition,, O'Reilly and Associates, 2004.

--Bob Y. 12:07, 19 July 2011 (EDT)


Previous | Next | Getting Started with GEOS-Chem