Difference between revisions of "GNU Fortran compiler"

From Geos-chem
Jump to: navigation, search
 
Line 1: Line 1:
 
[[Image:Page is under construction.jpg]]
 
[[Image:Page is under construction.jpg]]
 +
 +
== Compilation options ==
 +
 +
=== Optimization options ==
 +
 +
{| border=1 cellspacing=0 cellpadding=5
 +
|- bgcolor="#CCCCCC"
 +
!width="200px"|Option
 +
!width="650px"|Description
 +
!width="150px"|How invoked in GEOS-Chem?
 +
 +
|-valign="top"
 +
|
 +
|
 +
|
 +
 +
|}
 +
 +
=== List of commonly-used compilation options ===
 +
 +
Here are the IFORT compilation options currently used by GEOS-Chem:
 +
 +
{| border=1 cellspacing=0 cellpadding=5
 +
|- bgcolor="#CCCCCC"
 +
!width="200px"|Option
 +
!width="650px"|Description
 +
!width="150px"|How invoked in GEOS-Chem?
 +
 +
|- bgcolor="#CCFFFF"
 +
!width="200px"|
 +
!width="650px"|Normal compiler settings
 +
!width="150px"|
 +
 +
|-valign="top"
 +
|<tt>-cpp</tt>
 +
|Turns on the C-preprocessor, to evaluate <tt>#if</tt> and <tt>#define</tt> statements in the source code.
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-w</tt>
 +
|Suppresses all compiler warnings.  This is mainly a convenience to prevent excessive output to the screen or log file. 
 +
 +
''NOTE: Most compiler warnings are harmless.  Execution does not stop when a warning is displayed, unlike an error message, which causes program execution to halt at the point where the error occurred.''
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-O2</tt>
 +
|Optimizes the source code for speed, without taking too many liberties with numerical precision.  For more information, please see the [[#Optimization options|optimization options section above]].
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-auto</tt>
 +
|This option places local variables (scalars and arrays of all types), except those declared as SAVE, on the run-time stack.  It is as if the variables were declared with the AUTOMATIC attribute.  It does not affect variables that have the SAVE attribute or ALLOCATABLE attribute, or variables that appear in an EQUIVALENCE statement or in a common block.
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-noalign</tt>
 +
|Prevents the compiler from padding bytes anywhere in common blocks and structures.  Padding can affect numerical precision.
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-convert big_endian</tt>
 +
|Specifies that the format will be big endian for integer data and big endian IEEE floating-point for real and complex data.  This only affects file I/O to/from binary files (such as binary punch files) but not ASCII, netCDF, or other file formats.
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-vec-report0</tt>
 +
|Tells the compiler to suppress printing <tt>"LOOP HAS BEEN VECTORIZED"</tt> messages.  This reduces the amount of output that is sent to the screen and/or GEOS-Chem log file.
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-fp-model source</tt>
 +
|Rounds intermediate results to source-defined precision and enables value-safe optimizations.  Basically, this tells the compiler not to take too many liberties with how numerical expressions are evaluated.  For more information about this option, please see our [[#Precision-safe optimization|precision-safe optimization section]] below.  This option can be disabled by compiling GEOS-Chem with the <tt>PRECISE=no</tt> Makefile option.
 +
|Default setting
 +
 +
|- bgcolor="#CCFFFF"
 +
!width="200px"|
 +
!width="650px"|Special compiler settings
 +
!width="150px"|
 +
 +
|-valign="top"
 +
|<tt>-r8</tt>
 +
|This option tells the compiler to treat variables that are declared as <tt>REAL</tt> as <tt>REAL*8</tt> (as opposed to <tt>REAL*4</tt>.
 +
 +
''NOTE: This option is not used globally, but is only applied to certain indidvidual files (mostly from third-party codes like ISORROPIA.  Current GEOS-Chem programming practice is to use either <tt>REAL*4</tt> or <tt>REAL*8</tt> instead of <tt>REAL</tt>, which avoids confusion.''
 +
|Used as needed
 +
 +
|-valign="top"
 +
|<tt>-mcmodel=medium</tt>
 +
|This option is used to tell IFORT to use more than 2GB of static memory.  This avoids a [[#Relocation truncated to fit error|specific type of memory error]] that can occur if you compile GEOS-Chem for use with an extremely high-resolution grid (e.g. 0.25&deg; x 0.3125&deg; nested grid).
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-shared-intel</tt><br>(formerly <tt>-i-dynamic</tt>)
 +
|This option needs to be used in conjunction with <tt>-mcmodel=medium</tt>.  It causes Intel-provided libraries to be linked in dynamically instead of statically (which is the default).
 +
|Default setting
 +
 +
|-valign="top"
 +
|<tt>-ipo</tt>
 +
|This option enables interprocedural optimization between files.  This is also called multifile interprocedural optimization (multifile IPO) or Whole Program Optimization (WPO).  When you specify this option, the compiler performs inline function expansion for calls to functions defined in separate files. 
 +
 +
''NOTE: Yuxuan Wang found that this option was useful for certain nested-grid simulations.  See the [[#Optimization options for faster runs|this wiki post]] below for more information.''
 +
|<tt>IPO=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-static</tt>
 +
|This option prevents linking with shared libraries.  It causes the executable to link all libraries statically.
 +
 +
''NOTE: Yuxuan Wang found that this option was useful for certain nested-grid simulations.  See the [[#Optimization options for faster runs|this wiki post]] below for more information.''
 +
|<tt>IPO=yes</tt>
 +
 +
|- bgcolor="#CCFFFF"
 +
!width="200px"|
 +
!width="650px"|Settings only used for debugging
 +
!width="150px"|
 +
 +
|-valign="top"
 +
|<tt>-debug all</tt>
 +
|Tells the compiler turn on all debug error output.
 +
|<tt>DEBUG=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-g</tt>
 +
|Tells the compiler to generate full debugging information in the object file.  This will cause a debugger (like Totalview) to display the actual lines of source code, instead of hexadecimal addresses (which is gibberish to anyone except hardware engineers).
 +
|<tt>DEBUG=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-O0</tt>
 +
|Turns off all optmization.  Source code instructions (e.g. DO loops, IF blocks) and numerical expressions are evaluated in precisely the order in which they are listed, without being internally rewritten by the optimizer.  This is necessary for using a debugger (like Totalview).
 +
|<tt>DEBUG=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-check bounds</tt> (aka <tt>-CB</tt>)
 +
|Check for [[Common GEOS-Chem error messages#Array-out-of-bounds_error|array-out-of-bounds errors]].  This is invoked when you compile GEOS-Chem with the <tt>BOUNDS=yes</tt> Makefile option.  ''NOTE: Only use <tt>-CB</tt> for debugging, as this option will cause GEOS-Chem to execute more slowly!''
 +
|<tt>DEBUG=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-check arg_temp_created</tt>
 +
|Checks to see if any array temporaries are created.  Depending on how you write your subroutine and function calls, the compiler may need to create a temporary array to hold the values in the array before it passes them to the subroutine.  For detailed information, please see our [[Passing array arguments efficiently in GEOS-Chem]] wiki page.
 +
|<tt>DEBUG=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-traceback</tt>
 +
|This option tells the compiler to generate extra information in the object file to provide source file traceback information when a severe error occurs at run time.  When the severe error occurs, source file, routine name, and line number correlation information is displayed along with call stack hexadecimal addresses (program counter trace).  This option increases the size of the executable program, but has no impact on run-time execution speeds.  It functions independently of the debug option.
 +
|<tt>TRACEBACK=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-fpe0</tt>
 +
|This option will cause GEOS-Chem to halt if any type of floating-point error is encountered.  This can happen if an equation results in a denormal value, e.g. <tt>NaN</tt>, or <tt>+/-Infinity</tt>.  Common causes of floating-point errors are divisions where the denominator becomes zero.<br>''NOTE: The default compiler setting is <tt>-fpe3</tt>, which will convert many of these denormal values to zeros and then continue execution.''
 +
|<tt>FPE=yes</tt>
 +
 +
|-valign="top"
 +
|<tt>-ftrapuv</tt>
 +
|This option will assign a large numeric value to all local automatic variables.  This makes it easier to identify numerical errors caused by improper initialization.
 +
|<tt>FPE=yes</tt>
 +
 +
|}
 +
 +
--[[User:Bmy|Bob Y.]] 11:21, 3 October 2013 (EDT)
 +
 +
=== Typical settings for a GEOS-Chem simulation ===
 +
 +
The normal GEOS-Chem build uses the following IFORT compiler flags:
 +
 +
-cpp -w -O2 -auto -noalign -convert big_endian -vec-report0 -fp-model source -openmp
 +
 +
whereas a debugging run (meant to execute in a debugger such as TotalView) will typically use these flags:
 +
 +
-cpp -w -O0 -auto -noalign -convert big_endian -g -DDEBUG -check arg_temp_created -debug all -fp-model source -fpe0 -ftrapuv -check bounds
 +
 +
NOTE: In order to [[#Relocation truncated to fit error|avoid running out of memory]] if you compiling GEOS-Chem at extremely high resolution (e.g. the 0.25&deg; x 0.3125&deg; nested grids), we recommend adding the following flags:
 +
 +
-mcmodel=medium -shared-intel
 +
 +
These are automatically set when you compile with the <tt>NETCDF=yes</tt> or <tt>HDF=yes</tt> compiler options (in [[GEOS-Chem v9-01-03]] and higher).
 +
 +
--[[User:Bmy|Bob Y.]] 17:34, 29 February 2012 (EST)

Revision as of 20:45, 21 September 2016

Page is under construction.jpg

Compilation options

= Optimization options

Option Description How invoked in GEOS-Chem?

List of commonly-used compilation options

Here are the IFORT compilation options currently used by GEOS-Chem:

Option Description How invoked in GEOS-Chem?
Normal compiler settings
-cpp Turns on the C-preprocessor, to evaluate #if and #define statements in the source code. Default setting
-w Suppresses all compiler warnings. This is mainly a convenience to prevent excessive output to the screen or log file.

NOTE: Most compiler warnings are harmless. Execution does not stop when a warning is displayed, unlike an error message, which causes program execution to halt at the point where the error occurred.

Default setting
-O2 Optimizes the source code for speed, without taking too many liberties with numerical precision. For more information, please see the optimization options section above. Default setting
-auto This option places local variables (scalars and arrays of all types), except those declared as SAVE, on the run-time stack. It is as if the variables were declared with the AUTOMATIC attribute. It does not affect variables that have the SAVE attribute or ALLOCATABLE attribute, or variables that appear in an EQUIVALENCE statement or in a common block. Default setting
-noalign Prevents the compiler from padding bytes anywhere in common blocks and structures. Padding can affect numerical precision. Default setting
-convert big_endian Specifies that the format will be big endian for integer data and big endian IEEE floating-point for real and complex data. This only affects file I/O to/from binary files (such as binary punch files) but not ASCII, netCDF, or other file formats. Default setting
-vec-report0 Tells the compiler to suppress printing "LOOP HAS BEEN VECTORIZED" messages. This reduces the amount of output that is sent to the screen and/or GEOS-Chem log file. Default setting
-fp-model source Rounds intermediate results to source-defined precision and enables value-safe optimizations. Basically, this tells the compiler not to take too many liberties with how numerical expressions are evaluated. For more information about this option, please see our precision-safe optimization section below. This option can be disabled by compiling GEOS-Chem with the PRECISE=no Makefile option. Default setting
Special compiler settings
-r8 This option tells the compiler to treat variables that are declared as REAL as REAL*8 (as opposed to REAL*4.

NOTE: This option is not used globally, but is only applied to certain indidvidual files (mostly from third-party codes like ISORROPIA. Current GEOS-Chem programming practice is to use either REAL*4 or REAL*8 instead of REAL, which avoids confusion.

Used as needed
-mcmodel=medium This option is used to tell IFORT to use more than 2GB of static memory. This avoids a specific type of memory error that can occur if you compile GEOS-Chem for use with an extremely high-resolution grid (e.g. 0.25° x 0.3125° nested grid). Default setting
-shared-intel
(formerly -i-dynamic) 		This option needs to be used in conjunction with -mcmodel=medium. It causes Intel-provided libraries to be linked in dynamically instead of statically (which is the default). Default setting
-ipo This option enables interprocedural optimization between files. This is also called multifile interprocedural optimization (multifile IPO) or Whole Program Optimization (WPO). When you specify this option, the compiler performs inline function expansion for calls to functions defined in separate files.

NOTE: Yuxuan Wang found that this option was useful for certain nested-grid simulations. See the this wiki post below for more information.

IPO=yes
-static This option prevents linking with shared libraries. It causes the executable to link all libraries statically.

NOTE: Yuxuan Wang found that this option was useful for certain nested-grid simulations. See the this wiki post below for more information.

IPO=yes
Settings only used for debugging
-debug all Tells the compiler turn on all debug error output. DEBUG=yes
-g Tells the compiler to generate full debugging information in the object file. This will cause a debugger (like Totalview) to display the actual lines of source code, instead of hexadecimal addresses (which is gibberish to anyone except hardware engineers). DEBUG=yes
-O0 Turns off all optmization. Source code instructions (e.g. DO loops, IF blocks) and numerical expressions are evaluated in precisely the order in which they are listed, without being internally rewritten by the optimizer. This is necessary for using a debugger (like Totalview). DEBUG=yes
-check bounds (aka -CB) Check for array-out-of-bounds errors. This is invoked when you compile GEOS-Chem with the BOUNDS=yes Makefile option. NOTE: Only use -CB for debugging, as this option will cause GEOS-Chem to execute more slowly! DEBUG=yes
-check arg_temp_created Checks to see if any array temporaries are created. Depending on how you write your subroutine and function calls, the compiler may need to create a temporary array to hold the values in the array before it passes them to the subroutine. For detailed information, please see our Passing array arguments efficiently in GEOS-Chem wiki page. DEBUG=yes
-traceback This option tells the compiler to generate extra information in the object file to provide source file traceback information when a severe error occurs at run time. When the severe error occurs, source file, routine name, and line number correlation information is displayed along with call stack hexadecimal addresses (program counter trace). This option increases the size of the executable program, but has no impact on run-time execution speeds. It functions independently of the debug option. TRACEBACK=yes
-fpe0 This option will cause GEOS-Chem to halt if any type of floating-point error is encountered. This can happen if an equation results in a denormal value, e.g. NaN, or +/-Infinity. Common causes of floating-point errors are divisions where the denominator becomes zero.
NOTE: The default compiler setting is -fpe3, which will convert many of these denormal values to zeros and then continue execution. 		FPE=yes
-ftrapuv This option will assign a large numeric value to all local automatic variables. This makes it easier to identify numerical errors caused by improper initialization. FPE=yes

--Bob Y. 11:21, 3 October 2013 (EDT)

Typical settings for a GEOS-Chem simulation

The normal GEOS-Chem build uses the following IFORT compiler flags: 

-cpp -w -O2 -auto -noalign -convert big_endian -vec-report0 -fp-model source -openmp

whereas a debugging run (meant to execute in a debugger such as TotalView) will typically use these flags: 

-cpp -w -O0 -auto -noalign -convert big_endian -g -DDEBUG -check arg_temp_created -debug all -fp-model source -fpe0 -ftrapuv -check bounds

NOTE: In order to avoid running out of memory if you compiling GEOS-Chem at extremely high resolution (e.g. the 0.25° x 0.3125° nested grids), we recommend adding the following flags: 

-mcmodel=medium -shared-intel

These are automatically set when you compile with the NETCDF=yes or HDF=yes compiler options (in GEOS-Chem v9-01-03 and higher).

--Bob Y. 17:34, 29 February 2012 (EST)

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=GNU_Fortran_compiler&oldid=27354"