-
Notifications
You must be signed in to change notification settings - Fork 112
Compiler instructions (aka the include.mk files)
These files are located in directory ED2/ED/build/make
. In case you are part of a group that already uses ED2, the correct configuration file may be already included in the ED2 distribution:
- include.mk.bnl. Brookhaven National Labs.
- include.mk.bu_geo. Boston University.
- include.mk.cannon. Harvard's Cannon cluster (formerly known as Odyssey).
- include.mk.sdumont. Santos Dumont Cluster (LNCC).
- include.mk.ugent. Ghent University.
Otherwise, copy include.mk.gfortran
or include.mk.intel
to a unique file (e.g. include.mk.mylab
). Below is a list of variables that must be set. You can add other variables for convenience (for example, create variables that define paths to HDF5 and other libraries).
Name | Description |
---|---|
MAKE |
The location of the make command. This is system-dependent, but typically it is set to /usr/bin/make . Consider changing this only if you get messages on make command not being found. |
BASE |
The base path where ED2 compiling instructions are located. The default value $(ED_ROOT)/build should work for virtually all cases. |
HDF5_INCS |
The path where the HDF5 include files are located. If the include files are located in a standard directory (e.g., /usr/include ), it is fine to leave this variable empty (i.e., HDF5_INCS= ). |
HDF5_LIBS |
The path where to find HDF5 libraries and dependencies. A few examples:
|
USE_COLLECTIVE_MPIO |
If you have a version of HDF5 compiled in parallel, and you are planning to use parallel runs (i.e., a gridded, multi-polygon simulation, or a coupled ED2-BRAMS simulation), then you may benefit from collective I/O. In this case, you may set this variable to 1. For single-site runs, or in case your HDF5 file is not compiled with parallel, you can set this variable to 0. |
CMACH |
This informs the compiler of which system you are using. Possible options include:
Note. It is unlikely, but depending on the system and compiler options, you may need to edit rsys.F90 and utils_c.c and provide new, system-specific, settings. |
FC_TYPE |
The type of Fortran/C compilers being used. Options are:
Note. In case you are using mpi compilers (mpif90 and mpicc), you must set |
F_COMP |
The Fortran compiler. Typical options are:
|
C_COMP |
The C compiler. Typical options are:
Note.Do not mix different families of Fortran and C compilers. For example, if |
LOADER |
The Fortran compiler used to generate the executable. Unless otherwise instructed by system administrators, this variable should be set with the same value as F_COMP . |
MOD_EXT |
The extension of module files compiled with Fortran. Unless otherwise instructed by system administrators, use the default option (MOD_EXT=mod ). |
KIND_COMP |
This sets compiler flags in case your include.mk file is derived from include.mk.gfortran or include.mk.intel.
Note. Options |
F_OPTS |
The list of compilation options for Fortran. Check the sections on Fortran compilation flags for ifort and gfortran for suggestions. Note>/br>If using include.mk based on include.mk.gfortran or include.mk.intel, we recommend keeping the default options and set the type of compilation through KIND_COMP .
|
C_OPTS |
The list of compilation options for C. Note>/br>If using include.mk based on include.mk.gfortran or include.mk.intel, we recommend keeping the default options and set the type of compilation through KIND_COMP .
|
LOADER_OPTS |
The list of compilation options for the step that generates the executable file. This is almost always the same options as F_OPTS , except that LOADER_OPTS rarely has the -static option.Note>/br>If using include.mk based on include.mk.gfortran or include.mk.intel, we recommend keeping the default options and set the type of compilation through KIND_COMP .
|
F_LOWO_OPTS |
Optional variable, that allows compiling a few Fortran subroutines with slightly lower optimisation level. This is useful when compiling the code with ifort. Note>/br>If using include.mk based on include.mk.gfortran or include.mk.intel, we recommend keeping the default options and set the type of compilation through KIND_COMP .
|
PAR_DEFS |
This flag defines whether or not the code will be compiled with MPI support. In case you want MPI support, set PAR_DEFS=-DRAMS_MPI , otherwise, leave it blank (PAR_DEFS= ).Note. In case you want MPI support, you should also set the Fortran and C compilers to mpif90 and mpicc, respectively. Check variables F_COMP , C_COMP , and LOADER_COMP . |
ARCHIVE |
Command to create the ED2 library. Unless otherwise instructed by system administrators, this variable should be set toARCHIVE=ar rs . |
This provides a short summary of compilation options. Most of the descriptions were taken directly from the Intel compiler manual. For additional information, type man ifort
in the computer you plan to run ED2.
Flag | Description |
---|---|
-assume byterecl | Specifies that the units for the OPEN statement RECL specifier (record length) value are in bytes for unformatted data files, not longwords (four-byte units). This is the case in ED2. |
-FR | Specifies source files are in free format (as opposed to F77 format). All code in ED2 uses free format. |
-qopenmp | Generates multithreaded code based on OpenMP directives. This is very useful to speed up simulations as it allows patches to be solved in parallel. In some ifort systems, the option may be -openmp instead of -qopenmp . |
-recursive | Ensures that subroutines can call themselves recursively (ED2 contains a few recursive subroutines). |
-static | This prevents linking with shared libraries. Use this in F_OPTS only (the ED2 library compilation), not LOADER_OPTS (the ED2 executable compilation). |
-traceback | Displays the source file traceback information (e.g., line numbers and the tree of calls) at run time when a severe error occurs. |
Flag | Description |
---|---|
-check all,noarg_temp_created | Enables all check options, with the exception of whether arguments were copied to temporary storage. This option will check the following:
|
-debug extended. | This will produce enhanced debug information useful for breakpoints and stepping, and information useful in finding scalar local variables. |
-debug-parameters all | Generates debug information for all parameters defined in the program. |
-fpe0 | This will issue errors whenever a floating point exception occurs. This includes: invalid values, division by zero, overflow, and underflow (the latter only if -no-ftz is set). |
-fp-stack-check | Generates extra code after every function call to ensure that the floating-point variables are all in the expected state. In some systems, the option is -fpstkchk
|
-ftrapuv | This assigns non-sensical initial values to all local variables, which helps identifying variables that were not properly initialised. |
-g | Produces symbolic debug information in the object file. Useful when running a debugger with the model (idb , gdb , TotalView , ddd ) |
-gen-interface | Tells the compiler to generate an interface block for each routine (that is, for each SUBROUTINE and FUNCTION statement) defined in the source file, even if they are not inside modules. |
-implicitnone | Sets the default type of a variable to undefined (IMPLICIT NONE). |
-O0 | Disables all optimisations. Debugger works much better when the code optimisation is disabled |
-no-ftz | Prevents the code to flush very small values to zero. This can be useful to spot incorrectly set variables. |
-warn declarations | Enables warnings about any undeclared names. The compiler will use the default implicit data typing rules for such undeclared names. The IMPLICIT and IMPLICIT NONE statements override this option. |
-warn errors | Tells the compiler to change all warning-level messages to error-level messages; this includes warnings about Fortran standards violations. |
-warn interfaces | Tells the compiler to check the interfaces of all subroutines called and functions invoked in your compilation against a set of interface blocks stored separately from the source being compiled. |
-warn uncalled | Enables warnings when a statement function is never called. |
-warn unused | Enables warnings about variables that are declared but never used. |
-warn usage | Enables warnings about questionable programming practices. |
Flag | Description |
---|---|
-O2 | This option is the default for optimisations. The main distribution of ED2 is routinely tested for bugs that would prevent using the aggressive optimisation; therefore, you can take advantage of option -O3 (see below) for most sub-routines. |
-O3 | Enables -O2 optimizations plus more aggressive optimisations, such as prefetching, scalar replacement, and loop transformations. Enables optimisations for maximum speed, but does not guarantee higher performance. Note. In case the compilation is taking extraordinarily long (several hours), you may want to set an additional variable F_LOWO_OPTS in your include.mk file and use -O2 instead of -O3 (plus the other options used in F_OPTS ). This will compile the files known to take notoriously long to compile with -O3 at lower optimisation level, whilst compiling most subroutines with the most aggressive optimisation. |
This provides a short summary of compilation options. Most of the descriptions were taken directly from the GNU compiler manual. For additional information, type man gfortran
in the computer you plan to run ED2.
Flag | Description |
---|---|
-fbacktrace | Displays the source file traceback information (e.g., line numbers and the tree of calls) at run time when a severe error occurs. |
-ffree-line-length-none | Specifies source files are in free format (as opposed to F77 format), with no line length limit. All code in ED2 uses free format. |
-fopenmp | Generates multithreaded code based on OpenMP directives. This is very useful to speed up simulations as it allows patches to be solved in parallel. |
-frecursive | Ensures that subroutines can call themselves recursively (ED2 contains a few recursive subroutines). |
-static | This prevents linking with shared libraries. Use this in F_OPTS only (the ED2 library compilation), not LOADER_OPTS (the ED2 executable compilation). |
Flag | Description |
---|---|
-fcheck=all,no-array-temps | Enables all check options, with the exception of whether arguments were copied to temporary storage. This option will check the following:
|
-ffpe-trap=invalid,zero,overflow,underflow | This will issue errors whenever a floating point exception occurs. This includes: invalid values, division by zero, overflow, and underflow. |
-fimplicit-none | Sets the default type of a variable to undefined (IMPLICIT NONE). |
-finit-integer=-2147483648 | This assigns nearly NaN initial values to all integer variables, which helps identifying variables that were not properly initialised. |
-finit-real=snan | This assigns NaN initial values to all real variables, which helps identifying variables that were not properly initialised. |
-Wall | Enables commonly used warning options pertaining to questionable programming practices that we believe are easy to avoid. This currently includes (but is not limited to):
|
-Werror | Turns all warnings into errors. |
Flag | Description |
---|---|
-O2 | This option is the default for optimisations. The main distribution of ED2 is routinely tested for bugs that would prevent using the aggressive optimisation; therefore, you can take advantage of option -O3 (see below) for most sub-routines. |
-O3 | Enables -O2 optimizations plus more aggressive optimisations, such as prefetching, scalar replacement, and loop transformations. Enables optimisations for maximum speed, but does not guarantee higher performance. |
Flag | Description |
---|---|
-DLITTLE | Not a native icc option, but this must be provided to compilation instructions, to ensure the code assumes little endian variables. |
-g | Produces symbolic debug information in the object file. Useful only if compiling the code for debugging, especially if you plan to use debuggers (idb , gdb , TotalView , ddd ). |
-O0 or -O3 | Optimisation level: the recommended option depends on the intent.
|
-qopenmp | Generates multithreaded code based on OpenMP directives. This is very useful to speed up simulations as it allows patches to be solved in parallel. In some ifort systems, the option may be -openmp instead of -qopenmp . |
-static | This prevents linking with shared libraries. |
-traceback | Displays the source file traceback information (e.g., line numbers and the tree of calls) at run time when a severe error occurs. |
Flag | Description |
---|---|
-DLITTLE | Not a native gcc option, but this must be provided to compilation instructions, to ensure the code assumes little endian variables. |
-g | Produces symbolic debug information in the object file. Useful only if compiling the code for debugging, especially if you plan to use debuggers (idb , gdb , TotalView , ddd ). |
-fopenmp | Generates multithreaded code based on OpenMP directives. This is very useful to speed up simulations as it allows patches to be solved in parallel. In some ifort systems, the option may be -openmp instead of -qopenmp . |
-mtraceback=full | Displays the source file traceback information (e.g., line numbers and the tree of calls) at run time when a severe error occurs. |
-O0 or -O3 | Optimisation level: the recommended option depends on the intent.
|
-static | This prevents linking with shared libraries. |
It is possible that your system has multiple compilers available. This list has a few points to consider when choosing which compiler to use based on previous experience. Please mind that things can change over time and some of these remarks may need to be revisited.
- Speed From former comparisons at the Harvard Cluster, the model takes considerably longer to compile when using ifort and icc, but the simulation runtime is generally faster compared to gfortran/gcc.
-
Debugging None of the compiler settings catch all the bugs or warnings. When developing the code, it is advisable to compile the code with both ifort/icc and gfortran/gcc using the debugging flags.
- One feature that is unique to ifort is the possibility of generating interfaces. This capability is very useful when the code development involves changing the list of arguments in functions and subroutines, especially when these functions and subroutine are not contained inside a module.
- Portability The GNU compilers (gfortran/gcc) are free, and therefore it is a good practice to ensure that the model can compile and run using these compilers, even when your preferred compilers are ifort/icc. Whenever a pull request is submitted, GitHub will try to compile the pull request with gfortran, so it is advisable to run tests in gfortran before submitting the pull request.