Changes between Version 18 and Version 19 of Documentation/UserGuide/InstallingORCHIDEE


Ignore:
Timestamp:
2019-08-05T17:40:25+02:00 (5 years ago)
Author:
dkilic
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/UserGuide/InstallingORCHIDEE

    v18 v19  
    1010 
    1111 
    12 This installation guide has been tested on a laptop computer using Ubuntu 12.04 version. 
    13 Softwares used : gcc (C compiler), gfortran (Fortran 90 compiler), subversion (version control system), netcdf 3.6.3 [[BR]] 
     12This installation guide has been tested on a laptop computer using Ubuntu 16.04 version. 
     13Softwares used : mpicc (C compiler with mpi libraries wrapped on it), mpifort (Fortran 90 compiler with mpi libraries wrapped on it), subversion (version control system), netcdf 4.6.1 [[BR]] 
    1414Follow the steps and you will be able to compile and launch ORCHIDEE in sequential on a point to test it ! 
     15 
     16ORCHIDEE can be installed on sequential or parallel mode. This installation is oriented for parallel installation. The installation requires few packages to be installed in the system before starting installation of ORCHIDEE. These are: 
     17 
     18szlib 
     19 
     20 
     21curl 
     22 
     23 
     24zlib 
     25 
     26 
     27openmpi 
     28 
     29 
     30hdf5 
     31 
     32 
     33netcdf-c 
     34 
     35 
     36netcdf-fortran 
     37 
     38The list of packages should be installed in the order of appearance, although these packages are usually available in many Linux distributions.  A common way to check can be done by checking if the netcdf installation has links to the other packages. 
     39 
     40{{{ 
     41> nc-config --has-szlib 
     42> nc-config --has-hdf5 
     43> nc-config --has-parallel 
     44> nc-config --has-fortran 
     45}}} 
     46 
     47 
    1548 
    1649== 1.a Installing netcdf library (package installation) (not tested) == 
     
    2255== 1.b Installing netcdf library (manual installation) == 
    2356 
    24 The most difficult part consists to install the netcdf library. The version chosen is netcdf 3.6.3 ; it is entirely sufficient  
    25 for your laptop.  
    26  
    27 Download netcdf : 
    28 Open a terminal and type the following command (> represents the prompt) to download netcdf 3.6.3 :  
    29 {{{ 
    30     >   wget http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf-3.6.3.tar.gz 
     57Installing netcdf is a bit tricky, since it requires link to libraries of other packages. A library is a set files comprising functions inside packages. Each package carry a set of functions defined in libraries. Current programs (in this case ORCHIDEE) rely on many packages working together, therefore, we need to link these packages during installation.  
     58 
     59Download netcdf-c : 
     60Open a terminal and type the following command (> represents the prompt) to download netcdf version X.Y.Z :  
     61{{{ 
     62    >   wget http://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf-c-X.Y.Z.tar.gz 
    3163}}} 
    3264Extract the archive : 
    3365{{{ 
    34     >    tar -xvzf netcdf-3.6.3.tar.gz 
    35 }}} 
    36 A directory called netcdf-3.6.3 will be created. Go inside it : 
    37 {{{ 
    38     >    cd  netcdf-3.6.3 
    39 }}} 
    40 If you type ls, you will find : 
    41 {{{ 
    42     > ls 
    43 acinclude.m4  config.guess  configure     cxx      dods.m4   fortran     libsrc     Makefile.am  man4      ncdump  nc_test   README 
    44 aclocal.m4    config.h.in   configure.ac  cxx4     examples  INSTALL     libsrc4    Makefile.in  missing   ncgen   nc_test4  RELEASE_NOTES 
    45 compile       config.sub    COPYRIGHT     depcomp  f90       install-sh  ltmain.sh  man          ncdap.m4  nctest  nf_test   win32 
    46  
    47 }}} 
    48 Now focus on the script called configure. To know more about this script and the different options available, look at [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf-install/Configure.html#Configure].[[BR]] 
    49 I execute this script like this : 
    50  
    51 {{{ 
    52       >  ./configure  --disable-largefile --disable-cxx 
    53 }}} 
    54 In my case, I deactivate the creation of large netcdf files (larger than 2 GB) with the option --disable-largefile. 
    55 I also deactivate the creation of netcdf libraries for C++ because I don't need it.  
    56 But to create netcdf libraries for FORTRAN, you have to create netcdf libraries for C. 
    57 If you have a C compiler and a FORTRAN compiler, you will have no problems. 
    58 Notice you may need to add --enable-separate-fortran to generate the netcdff library. 
    59  
    60 Now you need to be root user. If you are on Ubuntu system (or Debian), type : 
     66    >    tar -xvzf netcdf-c-X.Y.Z.tar.gz 
     67}}} 
     68A directory called netcdf-c-X.Y.Z will be created. Go inside it : 
     69{{{ 
     70    >    cd  netcdf-c-X.Y.Z 
     71}}} 
     72 
     73The netcdf package should be linked to previously installed packages (szlib, openmpi, hdf5) at the configuration of package before installation. Different options for build configuration of netcdf-c package installation is given at [https://www.unidata.ucar.edu/software/netcdf/docs/getting_and_building_netcdf.html].[[BR]] 
     74 
     75To be able to see different configuration options, we can command 
     76 
     77{{{ 
     78      >  ./configure  --help 
     79}}} 
     80 
     81This command returns rather a long list of options that we can use building our package in the system. Crucial point here is to make sure the netcdf-C package that we want to install has: 
     82 
     83HDF5 Support 
     84 
     85This can be checked by configuring the installation folder once by: 
     86 
     87 
     88{{{ 
     89> ./configure 
     90}}} 
     91 
     92Which returns a table like this: 
     93 
     94 
     95{{{ 
     96 
     97# NetCDF C Configuration Summary 
     98============================== 
     99 
     100# General 
     101------- 
     102NetCDF Version:         4.7.0 
     103Configured On:          Mon Aug  5 15:55:30 CEST 2019 
     104Host System:            x86_64-pc-linux-gnu 
     105Build Directory:        /home/#USERNAME#/Téléchargements/libs/netcdf-c-4.7.0 
     106Install Prefix:         /usr/local 
     107 
     108# Compiling Options 
     109----------------- 
     110C Compiler:             /usr/bin/gcc 
     111CFLAGS:                  
     112CPPFLAGS:                
     113LDFLAGS:                 
     114AM_CFLAGS:               
     115AM_CPPFLAGS:             
     116AM_LDFLAGS:              
     117Shared Library:         yes 
     118Static Library:         yes 
     119Extra libraries:        -lhdf5_hl -lhdf5 -lm -ldl -lz -lcurl  
     120 
     121# Features 
     122-------- 
     123NetCDF-2 API:           yes 
     124HDF4 Support:           no 
     125HDF5 Support:           yes 
     126NetCDF-4 API:           yes 
     127NC-4 Parallel Support:  no 
     128PnetCDF Support:        no 
     129DAP2 Support:           yes 
     130DAP4 Support:           yes 
     131Byte-Range Support:     no 
     132Diskless Support:       yes 
     133MMap Support:           no 
     134JNA Support:            no 
     135CDF5 Support:           yes 
     136ERANGE Fill Support:    no 
     137Relaxed Boundary Check: yes 
     138}}} 
     139 
     140''' Important:  Installation of ORCHIDEE requires us to know about the destination of these libraries, especially netcdf, the compiler, and HDF5. It is important to take note of the installation destination of each library, which will be used later. The installation destination can be imposed at "./configure" step by "--prefix" option''' 
     141 
     142To complete installation, type : 
    61143{{{ 
    62144      >  sudo su 
     
    111193}}} 
    112194 
    113 After, you can delete the directory netcdf-3.6.3 (still in root) : 
    114  
    115 {{{ 
    116      >  rm -rf netcdf-3.6.3.tar.gz netcdf-3.6.3 
     195After, you can delete the directory netcdf-c-X.Y.Z (still in root) : 
     196 
     197{{{ 
     198     >  rm -rf netcdf-c-X.Y.Z.tar.gz netcdf-c-X.Y.Z 
    117199}}} 
    118200 
    119201== 2. Installing ORCHIDEE == 
    120  
    121 After this hard task, you need to install modipsl environment into a modipsl folder (you can change the name of this directory) : 
     202Remarks about installation: 
     203 
     204- Abovementioned packages should be installed. These packages should be installed with same compiler to keep consistency and avoid problems later on. In the case of more than one package installation, make sure to keep consistency between packages and libraries used to install ORCHIDEE (example: XIOS and ORCHIDEE should be installed with same netcdf library, and with the compiler that compiled netcdf, hdf5, mpi). 
     205- Library and Include directory destinations of hdf5, gcc, and netcdf-c are needed to make neccessary modifications in installation files. These packages are usually installed in "/usr/local/". When in doubt, check with your system administrator, or pass "nc-config --libdir" in command prompt. 
     206- Configuration files for installation of ORCHIDEE is by default set for the clusters used by IPSL. The configuration files works well for their environments, however, we need to modify the configuration files and make them suitable for our system, then we can install without problem. 
     207- You may install ORCHIDEE with gcc compilers, but I would like to suggest mpicc ( the mpi wrapper versions of the compilers). mpicc and mpifort combines your compiler with the libraries of mpi, and makes it easier for ORCHIDEE to reach to mpi libraries during installation. 
     208  
     209Step 1:  Download ORCHIDEE 
     210You need to install modipsl environment into a modipsl folder (you can change the name of this directory) : 
    122211{{{ 
    123212      >  svn co http://forge.ipsl.jussieu.fr/igcmg/svn/modipsl/trunk modipsl 
     
    131220 
    132221 
     222{{{ 
     223      > cd modipsl/util 
     224      > ./model ORCHIDEE_2_1 
     225      or 
     226      > ./model ORCHIDEE_2_0 
     227}}} 
     228 
     229Step 2: Modification of configuration files 
     230At this point, you have downloaded modipsl directory, and ORCHIDEE. You should now modify the configuration files that declares the destination of library and include folders so we can establish link between the packages we have installed in first part of the tutorial: 
     231 
     232ORCHIDEE uses target configurations that are predefined for various systems. Main configuration file is located in "modipsl/utils/AA_make.gdef". Normally, the configurations are set for IPSL systems, and they do not require modification, but in our case we will select a target configuration and modify it for our needs. 
     233 
     234The target architecture will be: gfortran 
     235 
     236You may see the various environment configurations for ORCHIDEE in "modipsl/util/" by: 
     237{{{ 
     238    > vi AA_make.gdef 
     239}}} 
     240 
     241The configuration is declared between lines 303-328 for "gfortran" in AA_make.gdef (for the modipsl tag: 4448) 
     242 
     243The modifications are given  
     244 
    133245Create makefiles with the specific target for compiler gfortran, first modify if necessary the path to netcdf : 
    134 {{{ 
    135     > vi AA_make.gdef   # modify eventually following lines 
    136             #-Q- gfortran  NCDF_INC = /usr/local/include 
    137             #-Q- gfortran  NCDF_LIB = -L/usr/local/lib -lnetcdf 
    138     > ./ins_make -t gfortran 
    139 }}} 
    140  
    141 Adapt AA_make, recreate makefile and compile without XIOS : (read more about compilation here [wiki:Documentation/UserGuide/CompileMethods])  
    142 {{{ 
    143    >  cd ../config/ORCHIDEE_OL 
    144    >  vi AA_make # Edit the AA_make file to compile in sequential mode 
    145    >  ../../util/ins_make -t gfortran 
    146    >  gmake without_xios 
    147 }}} 
    148  
     246 
     247{{{ 
     248    > vi AA_make.gdef   # modify eventually following lines ( The modifications can be seen by + and - at the left column of the text below ) 
     249         @@ -304,16 +304,16 @@ 
     250 #-Q- gfortran  M_K = make 
     251 #-Q- gfortran  P_C = cpp 
     252 #-Q- gfortran  FCM_ARCH = gfortran  
     253-#-Q- gfortran  F_C = gfortran -c -cpp 
     254+#-Q- gfortran  F_C = mpifort -c 
     255 #-Q- gfortran  #-D- MD    F_D = -g -Wall -fbounds-check -pedantic -finit-real=nan 
     256 #-Q- gfortran  #-D- MN    F_D = 
     257 #-Q- gfortran  #-P- I4R4  F_P = 
     258 #-Q- gfortran  #-P- I4R8  F_P = -fdefault-real-8 
     259 #-Q- gfortran  #-P- I8R8  F_P = -fdefault-integer-8 -fdefault-real-8 
     260-#-Q- gfortran  w_w = -O3 -funroll-all-loops $(F_D) $(F_P) -I$(MODDIR) 
     261+#-Q- gfortran  w_w = -O3 -cpp -funroll-all-loops $(F_D) $(F_P) -I$(MODDIR) 
     262 #-Q- gfortran  F_O = $(w_w) -J$(MODDIR) 
     263-#-Q- gfortran  F_L = gfortran 
     264+#-Q- gfortran  F_L = mpifort 
     265 #-Q- gfortran  M_M = 0 
     266 #-Q- gfortran  L_X = 0 
     267 #-Q- gfortran  L_O = 
     268@@ -323,8 +323,8 @@ 
     269 #-Q- gfortran  C_O = 
     270 #-Q- gfortran  C_L = cc 
     271 #-Q- gfortran  #- 
     272-#-Q- gfortran  NCDF_INC = /usr/local/include 
     273-#-Q- gfortran  NCDF_LIB = -L/usr/local/lib -lnetcdf 
     274+#-Q- gfortran  NCDF_INC = /cm/shared/apps/netcdf/4.6.1/include 
     275+#-Q- gfortran  NCDF_LIB = -L/cm/shared/apps/netcdf/4.6.1/lib -lnetcdf 
     276 #-Q- gfortran  #- 
     277 #-Q- lxiv8    #- Global definitions for Intel compiler (ifort) with MPI at obelix/LSCE 
     278 #-Q- lxiv8    FCM_ARCH=ifort_LSCE 
     279    
     280    > ./ins_make -t gfortran    # This step is where you define thee target architecture that you want to use for installation ( in our case gfortran) 
     281}}} 
     282 
     283The second modification needed is to change the configuration in model folders. To do this following changes should be made: 
     284 
     285 
     286{{{ 
     287     > cd modipsl/modeles 
     288     > cp XIOS/arch/arch-GCC_LINUX.env XIOS/arch/arch-gfortran.env 
     289     > cp XIOS/arch/arch-GCC_LINUX.fcm XIOS/arch/arch-gfortran.fcm 
     290     > cp XIOS/arch/arch-GCC_LINUX.path XIOS/arch/arch-gfortran.path 
     291     > cp ORCHIDEE/arch/arch-GCC_LINUX.fcm ORCHIDEE/arch/arch-gfortran.fcm 
     292     > cp ORCHIDEE/arch/arch-GCC_LINUX.path ORCHIDEE/arch/arch-gfortran.path 
     293}}} 
     294 
     295 
     296Once these files are copied, now we can build our configuration files for the system we have under the architecture name "gfortran".  
     297 
     298Remark before we make changes: 
     299- Each of these files we copied has a goal to define the library destination for libraries we will use (.env file), give the compiler required flags (settings) for installation of packages ( .fcm file), and define the libraries we will use for installation (.path file).  
     300- Therefore, we should modify these files for the library and include directories of MPI, NETCDF, HDF5 that we are using. 
     301- In my case, installation gave an error where it did not read c++ type comments in fortran files, therefore, I needed to include a library in fortran part hence the compiler could read c++ type comments in fortran compilation.  
     302- ORCHIDEE model does not comprise a ".env" folder, the library and include directories will be defined in ".path" file. 
     303 
     304In the XIOS folder: 
     305 
     306arch-gfortran.env file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script): 
     307 
     308{{{ 
     309export HDF5_INC_DIR=/cm/shared/apps/hdf5/1.10.2/include  # This should be modified for your include directory of HDF5 package 
     310export HDF5_LIB_DIR=/cm/shared/apps/hdf5/1.10.2/lib  # This should be modified for your library directory of HDF5 package 
     311 
     312export NETCDF_INC_DIR=/cm/shared/apps/netcdf/4.6.1/include   # This should be modified for your include directory of NETCDF package 
     313export NETCDF_LIB_DIR=/cm/shared/apps/netcdf/4.6.1/libs       # This should be modified for your library directory of NETCDF package 
     314 
     315export BOOST_INC_DIR=$HOME/boost 
     316export BOOST_LIB_DIR=$HOME/boost 
     317 
     318}}} 
     319 
     320 
     321 
     322arch-gfortran.fcm file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script): 
     323 
     324{{{ 
     325%CCOMPILER      mpicc       # the mpi wrappers of gcc compilers are inserted here,  
     326#you may use gcc as well 
     327%FCOMPILER      mpif90      # the mpi wrappers of gcc compilers are inserted here,  
     328#you may use gfortran as well 
     329%LINKER         mpif90     # the mpi wrappers of gcc compilers are inserted here,  
     330#you may use gfortran as well 
     331 
     332# This part gives compiler the necessary flags, thus the compiler understands under  
     333#which configurations it is compiling ORCHIDEE 
     334 
     335%BASE_CFLAGS    -ansi -w -L/cm/apps/shared/openmpi/gcc/1.10.3/lib64 
     336%PROD_CFLAGS    -O3 -DBOOST_DISABLE_ASSERTS 
     337%DEV_CFLAGS     -g -O2  
     338%DEBUG_CFLAGS   -g  
     339 
     340%BASE_FFLAGS    -D__NONE__ -ffree-line-length-none -L/cm/apps/shared/openmpi/gcc/64/1.10.3/lib64  
     341%PROD_FFLAGS    -O3 
     342%DEV_FFLAGS     -g -O2 
     343%DEBUG_FFLAGS   -g  
     344 
     345%BASE_INC       -D__NONE__ 
     346%BASE_LD        -lstdc++ 
     347 
     348%CPP            cpp 
     349%FPP            cpp -P 
     350%MAKE           make 
     351}}} 
     352 
     353arch-gfortran.path file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script): 
     354 
     355{{{ 
     356NETCDF_INCDIR="-I$NETCDF_INC_DIR"   ## these variables are imported from .env file 
     357NETCDF_LIBDIR="-L$NETCDF_LIB_DIR" 
     358NETCDF_LIB="-lnetcdff -lnetcdf"     ## declaration of libraries to be used 
     359 
     360MPI_INCDIR="-I/cm/shared/apps/openmpi/gcc/64/1.10.3/include" 
     361MPI_LIBDIR="-L/cm/shared/apps/openmpi/gcc/64/1.10.3/lib64" 
     362MPI_LIB="-lcurl" 
     363 
     364HDF5_INCDIR="-I$HDF5_INC_DIR" 
     365HDF5_LIBDIR="-L$HDF5_LIB_DIR" 
     366HDF5_LIB="-lhdf5_hl -lhdf5 -lz" 
     367 
     368BOOST_INCDIR="-I $BOOST_INC_DIR" 
     369BOOST_LIBDIR="-L $BOOST_LIB_DIR" 
     370BOOST_LIB="" 
     371 
     372OASIS_INCDIR="-I$PWD/../../oasis3-mct/BLD/build/lib/psmile.MPI1" 
     373OASIS_LIBDIR="-L$PWD/../../oasis3-mct/BLD/lib" 
     374OASIS_LIB="-lpsmile.MPI1 -lscrip -lmct -lmpeu" 
     375}}} 
     376 
     377 
     378 
     379Within ORCHIDEE folder:  
     380 
     381 
     382arch-gfortran.path file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script): 
     383 
     384{{{ 
     385NETCDF_LIBDIR="-L/cm/shared/apps/netcdf/4.6.1/lib -lnetcdf -lnetcdff" #destinations for lib should be modified for your system (where you have installed the library) 
     386NETCDF_INCDIR="-I/cm/shared/apps/netcdf/4.6.1/include"  # destinations for inc should be modified for your system (where you have installed the library) 
     387IOIPSL_INCDIR="-I${ORCHDIR}/../../lib" 
     388IOIPSL_LIBDIR="-L${ORCHDIR}/../../lib -lioipsl" 
     389XIOS_INCDIR="-I${ORCHDIR}/../XIOS/inc" 
     390XIOS_LIBDIR="-L${ORCHDIR}/../XIOS/lib -lxios" 
     391MPI_INCDIR="-I/cm/shared/apps/openmpi/gcc/64/1.10.3/include"  # destinations for inc should be modified for your system (where you have installed the library) 
     392MPI_LIBDIR="-L/cm/shared/apps/openmpi/gcc/64/1.10.3/lib64" # destinations for lib should be modified for your system (where you have installed the library) 
     393}}} 
     394 
     395 
     396 
     397arch-gfortran.fcm file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script): 
     398 
     399{{{ 
     400 
     401%COMPILER            mpifort   # the mpi wrappers of gcc compilers are inserted here,  
     402#you may use gcc as well 
     403%LINK                mpifort   # the mpi wrappers of gcc compilers are inserted here,  
     404#you may use gcc as well 
     405 
     406#declaration of flags for compiler 
     407%AR                  ar 
     408%MAKE                make 
     409%FPP_FLAGS           -P -C -traditional 
     410%FPP_DEF              
     411%BASE_FFLAGS         -fdefault-real-8 -cpp -L/cm/shared/apps/openmpi/gcc/64/1.10.3/lib64  
     412%PROD_FFLAGS         -O3 -funroll-all-loops 
     413%DEV_FFLAGS          -O 
     414%DEBUG_FFLAGS        -ffpe-trap=invalid,zero,overflow -Wall -fbounds-check -g3 -O0 -fstack-protector-all 
     415%MPI_FFLAGS 
     416%OMP_FFLAGS           
     417%BASE_LD       
     418%MPI_LD -lstdc++ -lmpi_cxx  
     419%OMP_LD  
     420 
     421}}} 
     422 
     423Step 3: Compilation 
     424 
     425Up to this point, we have installed necessary packages required by ORCHIDEE, modipsl directory, ORCHIDEE libraries, and finally, we modified ORCHIDEE installation files for our system environment. From this point there is only the actual compilation left. Installation can be completed by: 
     426 
     427{{{ 
     428 
     429   > cd modipsl/config/ORCHIDEE_OL 
     430   > ./make with_xios 
     431}}} 
    149432 
    150433CONGRATULATIONS, it's done ! 
     434 
     435This step compiles ORCHIDEE with XIOS in parallel mode. however, there are other configurations such as without XIOS, or in sequential mode. You may see the settings and different configurations in the Makefile at the directory. 
     436 
     437Installing ORCHIDEE for a system outside IPSL ecosystem is quite hard, there are plenty of details where the procedure might go wrong. It is highly suggested to get help via your collaborator within IPSL. 
     438 
    151439 
    152440== 3. Installing ORCHIDEE on a MAC (thanks to Matthew !McGrath) ==