|
|
| (60 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | '''''[[Setting Up the GCHP Environment|Previous]] | [[GCHP_Basic_Example_Run|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]''''' | + | ---- |
| | + | <span style="color:crimson;font-size:120%">'''The GCHP documentation has moved to https://gchp.readthedocs.io/.''' The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!</span> |
| | + | ---- |
| | + | |
| | + | '''''[[Downloading_GCHP|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]''''' |
| | #[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]] | | #[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]] |
| − | #[[Downloading_GCHP|Downloading Source Code]]
| |
| − | #[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]]
| |
| | #[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]] | | #[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]] |
| | + | #[[Downloading_GCHP|Downloading Source Code and Data Directories]] |
| | #<span style="color:blue">'''Compiling'''</span> | | #<span style="color:blue">'''Compiling'''</span> |
| − | #[[GCHP_Basic_Example_Run|Basic Example Run]] | + | #[[Obtaining_a_GCHP_Run_Directory|Obtaining a Run Directory]] |
| − | #[[Running_GCHP|Configuring a Run]] | + | #[[Running_GCHP:_Basics|Running GCHP: Basics]] |
| − | #[[GEOS-Chem_HP_Output_Data|Output Data]] | + | #[[Running_GCHP:_Configuration|Running GCHP: Configuration]] |
| | + | #[[GCHP_Output_Data|Output Data]] |
| | #[[Developing_GCHP|Developing GCHP]] | | #[[Developing_GCHP|Developing GCHP]] |
| | #[[GCHP_Run_Configuration_Files|Run Configuration Files]] | | #[[GCHP_Run_Configuration_Files|Run Configuration Files]] |
| | <br> | | <br> |
| | | | |
| − | == Overview ==
| + | Compiling GCHP is the same procedure as compiling GEOS-Chem Classic. Please see [http://wiki.seas.harvard.edu/geos-chem/index.php/Compiling_with_CMake Compiling with CMake] for instructions. |
| − | | + | |
| − | 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.
| + | |
| − | | + | |
| − | You are ready to compile GCHP after you have obtained the GCHP source code, set up your run directory, and set your environment. First time compilation can take a while (30 minutes or more) because it requires building large modules, including [https://www.earthsystemcog.org/projects/esmf/ ESMF], [https://geos5.org/wiki/index.php?title=MAPL_software MAPL], [https://www.gfdl.noaa.gov/fv3/ 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.
| + | |
| − | | + | |
| − | == Initial Compilation ==
| + | |
| − | | + | |
| − | To compile GCHP from scratch, navigate to your run directory and check that your <tt>gchp.env</tt> symbolic link is pointing to the environment file you wish to use. Next, type the following within the run directory:
| + | |
| − | | + | |
| − | make clean
| + | |
| − | make build
| + | |
| − | | + | |
| − | These command will execute <tt>./build.sh clean</tt> and <tt>./build.sh build</tt>. All build information is sent to both the terminal window and to a log file called <tt>compile.log</tt>. Git information for both source code repositories at compile time are recorded in a separate file called <tt>lastbuild</tt> for future reference. Upon successful compilation, the following empty files are created in your GCHP source code directories:
| + | |
| − | * <tt>GCHP/ESMF/esmf.install</tt>
| + | |
| − | * <tt>GCHP/Shared/mapl.install</tt>
| + | |
| − | * <tt>GCHP/FVdycoreCubed_GridComp/fvdycore.install</tt>
| + | |
| − | | + | |
| − | These files indicate successful compilation per module and their presence prompts the GCHP source code <tt>Makefile</tt> to skip compiling each component during future builds unless you explicitly clean the source code. If you are ever uncertain on whether your ESMF, MAPL, and FV3 dycore were previously build, check if these files exist.
| + | |
| − | | + | |
| − | == Subsequent Compilation ==
| + | |
| − | | + | |
| − | For subsequent GCHP compilations you have several options. You can see all options by typing the following at the prompt from within your run directory:
| + | |
| − | | + | |
| − | make help
| + | |
| − | | + | |
| − | This will display all make options to your screen. For compilation the make targets you are interested in are clean, clean_mapl, clean_gc, build, build_mapl, and build_gc. Here is a brief summary of these options.
| + | |
| − | | + | |
| − | Clean/compile ALL source code, including ESMF, MAPL, and FV3:
| + | |
| − | make clean
| + | |
| − | make build
| + | |
| − | | + | |
| − | Clean/compile all source code except ESMF:
| + | |
| − | make clean_mapl
| + | |
| − | make build_mapl
| + | |
| − | | + | |
| − | Clean/compile all source code except ESMF, MAPL, and FV3:
| + | |
| − | make clean_gc
| + | |
| − | make build_gc
| + | |
| − | | + | |
| − | Same as above but compile GEOS-Chem with debug flags turned on (note that this will slow down the model)
| + | |
| − | make build_gc_debug
| + | |
| − | | + | |
| − | A typical workflow would look like you getting a run directory, compiling from scratch (make clean; make compile), editing GEOS-Chem code in GeosCore, and then recompiling without cleaning (make build_gc). Since this workflow is the most common the default make target, meaning the target used when none is specified, is set to build_gc. Therefore to rebuild GEOS-Chem after changing GEOS-Chem files or any high-level files in the GCHP directory you can simply type this:
| + | |
| − | | + | |
| − | make
| + | |
| − | | + | |
| − | Note that if you change your underlying libraries set in your environment you MUST do a full source code clean before rebuilding. Otherwise you will likely encounter a segmentation fault when running the model. For this reason it is recommended that you create a new run directory for each new environment you want to run in, e.g. if you want to test with both Intel and GNU fortran compilers.
| + | |
| − | | + | |
| − | Also note that these build targets were added in GCHP version 12.2.0. If you are using an earlier version type <tt>make help</tt> to view your make options.
| + | |
| − | | + | |
| − | == Checking for Successful Compilation ==
| + | |
| − | | + | |
| − | If GCHP compiled without issues, you should see:
| + | |
| − | | + | |
| − | ###################################
| + | |
| − | ### GCHP compiled successfully! ###
| + | |
| − | ###################################
| + | |
| − | | + | |
| − | | + | |
| − | Compiling GCHP produces a GCHP executable called <tt>geos</tt> that is stored in the <tt>bin/</tt> subdirectory of your GEOS-Chem source code directory. Compiling within the run directory makes a copy of the executable locally for use within your run directory.
| + | |
| − | | + | |
| − | Compiler output, including warnings and error messages, will be stored in a log file called <tt>compile.log</tt>. 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.
| + | |
| − | | + | |
| − | Beware that MAPL will continue to compile even if a compile error occurs. This is because 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. Here are strategies that typically hone in immediately on the original MAPL error:
| + | |
| − | | + | |
| − | # Search for string "making install". This will take you through the compilation starts of all major components within MAPL. If there was a compile problem in any of the components you will see messages about it directly above the start of compilation of the next component. In other words, look at the code above all results of your keyword search.
| + | |
| − | # Search for string "error". Ignore results where error is in a filename or in a source code string that triggered a warning.
| + | |
| − | | + | |
| − | Another thing to be wary about is if you edit a file in MAPL and your last build was a successful, your new build may appear successful when there was an actual problem. This would be the case because of the relaxed build rules and the fact that the previous build produced a binary. While an initial build after cleaning would end up with a dependency error later in the build process that would halt production of a final GCHP executable, a rebuild without cleaning would not. An indication that you have this sort of problem would if you reran the model after recompiling with your MAPL update but your update does not appear to have executed.
| + | |
| − | | + | |
| − | Here are some tips for troubleshooting this sort of problem.
| + | |
| − | | + | |
| − | # 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.
| + | |
| − | # Check your compilation log file for errors using the guidelines presented above.
| + | |
| − | # When editing MAPL it is usually a good idea to add in one or more print statements on what you are doing so you can verify in your run log that it executed.
| + | |
| − | | + | |
| − | == Additional Makefile Options ==
| + | |
| − | | + | |
| − | The GCHP run directory <tt>Makefile</tt> contains several utility options beyond cleaning and compiling GCHP. Options are printed out by typing the following at the command line:
| + | |
| − | | + | |
| − | make help
| + | |
| − | | + | |
| − | We encourage you to 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.
| + | |
| − | | + | |
| − | == Advanced Compilation Topics ==
| + | |
| − | | + | |
| − | The <tt>Makefile</tt> in the run directory invokes a bash shell script called <tt>build.sh</tt> 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 <tt>HPC=yes</tt> if cleaning and <tt>hpc</tt> 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 <tt>make</tt> commands used for all options provided in the run directory <tt>Makefile</tt>, see the commands defined in <tt>build.sh</tt>. You can then trace the build sequence by looking at the Makefiles in the GEOS-Chem and GCHP repositories. Note that calling <tt>make</tt> always invokes the <tt>Makefile</tt> in the directory you are in and changing into the GEOS-Chem and GCHP source code directories occurs within <tt>build.sh</tt>. Also note that the <tt>GRID=4x5</tt> argument has no effect on the resolution at which the model runs since GCHP functions on the cubed-sphere grid. However, passing <tt>GRID</tt> 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 <tt>ESMA_base.mk</tt>, <tt>ESMA_arch.mk</tt>, and <tt>GMAO_base.mk</tt> in <tt>GCHP/Shared/Config</tt> as well as <tt>GNUMakefile</tt> within <tt>GCHP/Shared</tt> and all its subdirectories. Also see <tt>GIGC.mk</tt> 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.
| + | |
| | | | |
| | -------------------------------------- | | -------------------------------------- |
| | | | |
| − | '''''[[Setting Up the GCHP Environment|Previous]] | [[GCHP_Basic_Example_Run|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]''''' | + | '''''[[Downloading_GCHP|Previous]] | [[Obtaining_a_GCHP_Run_Directory|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]''''' |
