Difference between revisions of "Compiling GCHP"

Revision as of 16:37, 26 April 2019

Previous | Next | User Manual Home | GCHP Home

1. Hardware and Software Requirements
2. Downloading Source Code and Data Directories
3. Obtaining a Run Directory
4. Setting Up the GCHP Environment
5. Compiling
6. Running GCHP: Basics
7. Running GCHP: Configuration
8. Output Data
9. Developing GCHP
10. Run Configuration Files

Overview

This section provides instructions on how to clean and compile GCHP. There are several options for cleaning and compiling which allow clean and compilation of subsets of modules, thereby minimizing recompilation to only modules you have modified. This is a very big time-saver so please pay attention to the build options. You can always see all of your options, along with tips on which option you should use based on your changes, by typing make or make help at the command line within your run directory.

First time compilation can take 30 minutes or more because it requires building large modules from scratch, including ESMF, MAPL, FV3 dycore advection, and GEOS-Chem. MAPL, which is short for Modeling, Analysis and Prediction Layer, is built on ESMF, aka the Earth System Modeling Framework. Both systems are highly flexible but highly complex, with significant compilation times. Fortunately, MAPL and ESMF do not need to be recompiled unless parts of their code have been modified which is usually not necessary. Subsequent compile times will therefore be significantly shorter, on the same order of magnitude as compiling GEOS-Chem Classic.

If you run into problems compiling GCHP and cannot figure out why, please create an issue on the GCHP issue tracker located at https://github.com/geoschem/gchp/issues.

Run Directory Makefile

The GCHP run directory Makefile contains several options for cleaning and compiling source code, as well as utility options you might find useful. Options are printed out by typing the following at the command line:

make help

It is important that you do this and browse the options available. Several options are particularly useful for cleaning up files in your run directory and displaying the status of your source code. Knowing which build options to use based on what you changed in the model or your libraries is important for saving yourself time.

Initial Compile

To compile GCHP from scratch, including ESMF, MAPL, FV3 advection, and GEOS-Chem core files, navigate to your run directory. Then type the followng:

make clean_all
make build_all

When you first download source code the directories will already be clean, so doing make clean_all technically is not necessary. However, it is recommended to be in the habit of including clean for fresh builds. It will be necessary if you change compiler or other libraries.

All build information is sent to both the terminal window and to a log file called compile.log. Git information for source code at compile time are recorded in a separate file called lastbuild for future reference, similar to GEOS-Chem Classic.

Upon successful compilation, the following empty files are created in your GCHP source code directories:

• GCHP/ESMF/esmf.install
• GCHP/Shared/mapl.install
• GCHP/FVdycoreCubed_GridComp/fvdycore.install

These files indicate successful compilation per module. If you are ever uncertain on whether your ESMF, MAPL, and FV3 dycore were previously built, check if these files exist.

Recompile

For subsequent GCHP compilations you have several options. You can remind yourself of all options by typing make or make help at the command prompt. Here is a summary of the compile options.

make build_all  # Compile all source code (slow)
make build_mapl # Compile MAPL, FV3, and GEOS-chem core (skip ESMF)
make build_core # Compile GEOS-Chem core only (fast)

Same as above but compile GEOS-Chem with debug flags turned on (note that this will slow down the model)

make build_core_debug

None of these compile options clean the source code. To save time, we recommend not cleaning source code as you are developing GEOS-Chem. However, if you change libraries are upgrade versions you must always do a fresh build from scratch. In these instances we also recommend creating a fresh run directory.

A typical workflow would be:

1. Create a run directory
2. Compile from scratch (make clean_all; make build_all)
3. Edit GEOS-Chem code in GeosCore
4. Recompile with debug flags on (make build_core_debug)
5. Do a short test run to see if any of the debug flags trigger a problem
6. Repeat as needed
7. Recompile with debug flags off (make build_core) for longer runs after debugging

If you find yourself editing files in the GCHP/Shared, GCHP/Registry, or FVdycoreCubed_GridComp folders then you will need to recompile with option make build_mapl. Editing these files is advanced. If you are attempting to fix a MAPL error that appears during run-time you may be headed in the wrong direction since most MAPL errors are caused by bad configuration in the run directory. If you are unsure of what you are doing please create a GitHub GCHP issue and we will respond. Even if your question is not a true issue, having it on the GitHub issue tracker allows sharing the question and answer with the wider GCHP community, something we strongly encourage.

If at any time you forget what the make options are, simply type:

make help

Compilation Tips

Basics

If a GCHP executable exists in the GEOS-Chem bin/ folder to be copied to your run directory, then you should see the following message at the end of compilation:

###################################
### GCHP compiled successfully! ###
###################################

If you did a clean compile of your code and you see this message then you know that GCHP compiled without error. Compiler output, including warnings and error messages, will be stored in a log file called compile.log. If you inspect your log file or watch the compile output real-time, you will notice that there are many warnings and error messages. Many of these errors are due to leftover components in MAPL which are no longer used but which still try to compile. As long as the compilation continues, these errors can almost always be ignored and they will have no effect on the operation of GCHP.

Advanced

If you are recompiling MAPL and see the "GCHP compiled successfully!" message then your compilation may not actually have been successful. This is because failure during compilation of different MAPL sub-components does not trigger the entire build to fail. It will continue and the old binary files for whatever component failed will be used instead. Only if you cleaned first and those files were deleted and needed later in the build would the end result be a build failure.

The general rule-of-thumb is if you clean and then compile, or if you rebuild using make build_core, then you can trust the "GCHP compiled successfully!" message. However, if you recompile using make build_mapl without cleaning first, then you will need to dig a little deeper to ensure a successful rebuild. The best way to do this is to do keyword search for "making install" in compile.log and scan the few lines directly above all instances of it. If there was a problem with MAPL compilation you will spot it immediately in one of these areas, and that is where you should look for clues on how to fix it.

If you plan on developing within MAPL please make sure you fully understand this approach to debugging since it will save you a lot of time and frustration. Repeat: if you are developing MAPL and recompiling be aware you need to check your compile.log for keyword "making install" to ensure success.

Why is this necessary? Again, it is because MAPL will continue to compile even if a compile error occurs. MAPL compilation involves compiling a series of components, many of them dependent on components that came before, and compilation rules are relaxed to allow minor problems. One component may fail compilation but the compilation will not crash until the built file is needed later on in the build sequence. It is therefore necessary to search your log file for errors high above the final error in the event of compile failure. The log file will be long so this should be done by keyword search.

While this has already been stated, we will state it again since it is so useful. Here are strategies that typically hone in immediately on the original MAPL error:

1. Search for string "making install", and look at the lines immediately above all results of your keyword search.
2. A second and more tedious option is to search for string "error". Ignore results where error is in a filename or in a source code string that triggered a warning.

If in doubt, check the source code directory to see the file times. If the binary for the file you updated is older than the other binaries then it encountered a compile error in your update.

Advanced Compilation Topics

The Makefile in the run directory invokes a bash shell script called build.sh that includes changing into the source code directory and invoking source code Makefiles. At its core, building GCHP simply requires the inclusion of additional target HPC=yes if cleaning and hpc if compiling when invoking make in the GEOS-Chem repository. Cleaning GCHP also requires changing into the GCHP directory explicitly to clean ESMF, MAPL, and FV3 dycore.

If you are interested in seeing the core make commands used for all options provided in the run directory Makefile, see the commands defined in build.sh. You can then trace the build sequence by looking at the Makefiles in the GEOS-Chem and GCHP repositories. Note that calling make always invokes the Makefile in the directory you are in and changing into the GEOS-Chem and GCHP source code directories occurs within build.sh. Also note that the GRID=4x5 argument has no effect on the resolution at which the model runs since GCHP functions on the cubed-sphere grid. However, passing GRID is required so that components of GEOS-Chem Classic are functional.

If you are interested in the build sequence for MAPL, look at the various *.mk files ESMA_base.mk, ESMA_arch.mk, and GMAO_base.mk in GCHP/Shared/Config as well as GNUMakefile within GCHP/Shared and all its subdirectories. Also see GIGC.mk in the highest level of the GCHP repository for the include dependencies between GCHP modules.

Currently GCHP does not compile with cmake but work is in progress to make this possible in the future.

Previous | Next | User Manual Home | GCHP Home