Changes between Version 1 and Version 2 of doc/app/cpp_options

Timestamp:

Jul 19, 2018 12:51:45 PM (7 years ago)

Author:

raasch

Comment:

--

doc/app/cpp_options

@@ -4 +4 @@
 = PALM preprocessor options / define strings
 
-PALM uses so-called preprocessor define strings for conditional compilation of the code. Additionally, some preprocessor options are used to replace specific character strings. The following list gives a complete overview of the define strings used in the PALM code, and of additional preprocessor options that are used to replace strings in the FORTRAN code.
+PALM uses so-called preprocessor define strings for conditional compilation of the code. These compile switches are mainly used for activating calls to external libraries like MPI or NetCDF. Additionally, some preprocessor options are used to replace specific character strings. Define strings and other preprocessor options need to be given in the configuration file {{{.palm.config.<host_identifier>}}} in the line starting with {{{%cpp_options}}}.
 
-The define strings are used to activate specific parts of the code. For activation, compiler option {{{-Dactivation_string}}} has to be used. All activation strings used in PALM start with two underscores, e.g. {{{__parallel}}} 
+The following list gives a complete overview of the define strings used in the PALM code, and of additional preprocessor options that are used to replace strings in the FORTRAN code.
+
+
+== '''Define strings''' ==
+
+The define strings are used to activate specific parts of the code. For activation, compiler option {{{-Dactivation_string}}} has to be used. All activation strings used in PALM start with two underscores, e.g. {{{__parallel}}}. Be aware to add respective include- and library-paths to the compiler options with respect to the specific define strings that has been set, e.g. if you have set {{{-D__netcdf}}} you need to provide the path to the NetCDF library.
 
 
 ||='''activation_string''' =||='''meaning''' =||
 |-----------
-||__dvrp_graphics     ||      ||
-||__fftw              ||      ||
-||__ibm               ||      ||
-||__intel_compiler    ||      ||
-||__logging           ||      ||
-||__mpifh             ||      ||
-||__nec               ||      ||
-||__netcdf            ||      ||
-||__netcdf4           ||      ||
-||__netcdf4_parallel  ||      ||
-||__nopointer         ||      ||
-||__parallel          ||test  ||
-||__rrtmg             ||      ||
+||{{{__dvrp_graphics}}}     ||Enables usage of the DVR graphic software from Univ. of Hamburg      ||
+||{{{__fftw}}}              ||Enables usage of the FFTW library.      ||
+||{{{__ibm}}}               ||Enables usage of specific IBM FFT. This additionally requires to set the initialization parameter [wiki:/doc/app/inipar#fft_method fft_method] = 'system-specific'. Do not use {{{-D__nec}}} at the same time. ||
+||{{{__intel_compiler}}}    ||May be used in case of the Intel FORTRAN compiler to guarantee correct formatting of the progress bar, which is output to the terminal in case of interactive PALM runs.  ||
+||{{{__logging}}}           ||Used by PALM developers to activate additional and extensive debug output.   ||
+||{{{__mpifh}}}             ||Needs to be set in case of old MPI-libraries (using FORTRAN77 standard) which only support INCLUDE files (instead of FORTRAN modules). Is only effective if {{{-D__parallel}}} is set too.  ||
+||{{{__nec}}}               ||Enables usage of specific NEC FFT. This additionally requires to set the initialization parameter [wiki:/doc/app/inipar#fft_method fft_method] = 'system-specific'. Do not use {{{-D__ibm}}} at the same time. ||
+||{{{__netcdf}}}            ||Enables NetCDF I/O. If this activation string is not set, PALM does not read or write any NetCDF data. ASCII I/O files are not affected. You may omit {{{-D__netcdf}}} in order to test PALM without having a NetCDF library available on your system.    ||
+||{{{__netcdf4}}}           ||Enables to use the NetCDF4/HDF5 data format. {{{-D__netcdf}}} has to be set too. See initialization parameter [wiki:/doc/app/d3par#netcdf_data_format netcdf_data_format] about how to choose the NetCDF data format. ||
+||{{{__netcdf4_parallel}}}  ||Enables to use NetCDF4/HDF5 parallel I/O. {{{-D__netcdf}}} '''and''' {{{-D__netcdf4}}} have to be set too. See initialization parameter [wiki:/doc/app/d3par#netcdf_data_format netcdf_data_format] about how to choose the NetCDF data format.     ||
+||{{{__nopointer}}}         ||Enables a pointer-free version of the PALM code. This is currently (July 2018) required to run PALM on GPUs.      ||
+||{{{__parallel}}}          ||Enables usage of MPI. If you do '''not set''' {{{-D__parallel}}}, PALM runs in non-parallel mode on a single core.  ||
+||{{{__rrtmg}}}             ||Enables usage of the Rapid Radiation Transfer Model library. See [wiki:/doc/tec/radiation#RRTMG] for further details.   ||
 
 
-Preprocessor options used for string replacement:
+== '''Other preprocessor options''' ==
+
+Preprocessor options are used for string replacement. By default, two options are required to compile the PALM code:
 
 ||='''option''' =||='''meaning''' =||
 |-----------
-||-DMPI_REAL=MPI_DOUBLE_PRECISION    ||      ||
-||-DMPI_2REAL=MPI_2DOUBLE_PRECISION  ||      ||
+||{{{-DMPI_REAL=MPI_DOUBLE_PRECISION}}}    ||Replaces strings {{{MPI_REAL}}} by {{{MPI_DOUBLE_PRECISION}}} wherever they appear in the code.   ||
+||{{{-DMPI_2REAL=MPI_2DOUBLE_PRECISION}}}  ||Replaces strings {{{MPI_2REAL}}} by {{{MPI_2DOUBLE_PRECISION}}} wherever they appear in the code.   ||
 
+These preprocessor options are required, because by default the precision of {{{REAL}}} quantities in PALM is set to 64bit. You may define 32bit as the working precision (see routine [source:palm/trunk/SOURCE/mod_kinds.f90@3151#L69]). In such a case, you must omit the above preprocessor options.