wiki:Documentation/UserGuide/InstallingORCHIDEE

Version 25 (modified by mmcgrath, 22 months ago) (diff)

--

How to install ORCHIDEE on a Linux PC (Ubuntu or Fedora distribution)

Author: D: Solyga Last revision: 2020/02/28, M. McGrath?

This installation guide has been tested on a laptop computer using Ubuntu 16.04 version. Software used : mpicc (C compiler with mpi libraries wrapped into it), mpifort (or mpif90) (Fortran 90 compiler with mpi libraries wrapped on it), subversion (version control system), netcdf 4.6.1
Follow the steps below and you should be able to compile and launch ORCHIDEE on a single processor for a single site.

ORCHIDEE can be installed in serial (single processor) or parallel (multiple processors) mode. This installation is oriented for parallel installation, which is the default, and MPI libraries are mature enough that they typically install easily. One can always run ORCHIDEE with a single processor even if the compilation was done for a parallel mode, but the opposite is not true (a serial executable cannot be run on multiple processors). The installation requires a few packages to be installed on the system before starting installation of ORCHIDEE. These are:

  • szlib
  • curl
  • zlib
  • openmpi
  • hdf5
  • netcdf-c
  • netcdf-fortran

The list of packages should be installed in the order listed above. note that many of these packages come pre-installed on many Linux distributions. A common way to check can be done by checking if the netcdf installation has links to the other packages.

> nc-config --has-szlib
> nc-config --has-hdf5
> nc-config --has-parallel
> nc-config --has-fortran

If you do not have nc-config, then you must install the NetCDF library:

1. Installing NetCDF library

NOTE : It is no longer possible to use NetCDF 3 with ORCHIDEE due to the tagged version of IOIPSL v2_2_4 which requires NetCDF 4.

1.a Package installation (not tested)

NetCDF is currently available as a package for many Linux distributions. For Ubuntu, for example, a package exists. Make sure that the netcdf is compiled with the same compiler as with you'll compile ORCHIDEE (here, gfortan). This installation has not yet been tested, but try it (with apt-get or whatever package manager exists on your distribution). If it works, go to step 2.

1.b Manual installation

Installing NetCDF without a package manager is a bit tricky, since it requires linking to libraries in other packages. A library is a set files comprising functions inside packages (for example, the NetCDF library has a function that enables you to read the information in a NetCDF file). A package is a compressed file archive containing all of the files that come with a particular application (e.g., libraries, files with pre-defined variables). Current programs (in this case ORCHIDEE) rely on many packages working together, and therefore we need to link these packages to ORCHIDEE during installation.

Installation of a package requires: 1) downloading the source code, 2) unpacking it from the compressed form, 3) configuring the package, 4) compiling the package, and 5) putting executable and library files into standard locations on your computer.

Download netcdf-c : Open a terminal and type the following command (> represents the command prompt and should not be typed) to download netcdf version X.Y.Z (as of the time of writing, 4.7.3 is the most recent) :

    >   wget https://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf-c-X.Y.Z.tar.gz

Extract the archive :

    >    tar -xvzf netcdf-c-X.Y.Z.tar.gz

A directory called netcdf-c-X.Y.Z will be created. Go inside it :

    >    cd  netcdf-c-X.Y.Z

The netcdf package should be linked to previously installed packages (szlib, openmpi, hdf5) during configuration before compilation. Different options for build configurations of the netcdf-c package installation are given at https://www.unidata.ucar.edu/software/netcdf/docs/getting_and_building_netcdf.html.

To be able to see different configuration options, we can command

      >  ./configure  --help

This 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:

HDF5 Support

This can be checked by configuring the installation folder once by:

> ./configure

Which returns a table like this:

# NetCDF C Configuration Summary
==============================

# General
-------
NetCDF Version:		4.7.0
Configured On:		Mon Aug  5 15:55:30 CEST 2019
Host System:		x86_64-pc-linux-gnu
Build Directory: 	/home/#USERNAME#/Téléchargements/libs/netcdf-c-4.7.0
Install Prefix:         /usr/local

# Compiling Options
-----------------
C Compiler:		/usr/bin/gcc
CFLAGS:			
CPPFLAGS:		
LDFLAGS:		
AM_CFLAGS:		
AM_CPPFLAGS:		
AM_LDFLAGS:		
Shared Library:		yes
Static Library:		yes
Extra libraries:	-lhdf5_hl -lhdf5 -lm -ldl -lz -lcurl 

# Features
--------
NetCDF-2 API:		yes
HDF4 Support:		no
HDF5 Support:		yes
NetCDF-4 API:		yes
NC-4 Parallel Support:	no
PnetCDF Support:	no
DAP2 Support:		yes
DAP4 Support:		yes
Byte-Range Support:	no
Diskless Support:	yes
MMap Support:		no
JNA Support:		no
CDF5 Support:		yes
ERANGE Fill Support:	no
Relaxed Boundary Check:	yes

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

To complete installation, type :

      >  sudo su

On Fedora :

      >  su

Enter your password then execute in the following order :

      > make

( compile netcdf on your computer.) Then

      > make check

( Test the buiding ) and finally the installation :

      > make install

If your installation was successful, the following message will appears :

+-------------------------------------------------------------+
| Congratulations! You have successfully installed netCDF!    |
|                                                             |
| CAUTION:                                                    |
|                                                             |
| If you have not already run "make check", then we strongly  |
| recommend you do so. It does not take very long.            |
|                                                             |
| Before using netCDF to store important data, test your      |
| build with "make check".                                    |
|                                                             |
| NetCDF is tested nightly on many platforms at Unidata       |
| but your platform is probably different in some ways.       |
|                                                             |
| If any tests fail, please see the netCDF web site:          |
| http://www.unidata.ucar.edu/software/netcdf/                |
|                                                             |
| NetCDF is developed and maintained at the Unidata Program   |
| Center. Unidata provides a broad array of data and software |
| tools for use in geoscience education and research.         |
| http://www.unidata.ucar.edu                                 |
+-------------------------------------------------------------+

After, you can delete the directory netcdf-c-X.Y.Z (still in root) :

     >  rm -rf netcdf-c-X.Y.Z.tar.gz netcdf-c-X.Y.Z

2. Installing ORCHIDEE

Remarks about installation:

  • Above mentioned 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).
  • The paths to libraries and include directories of hdf5, gcc, and netcdf-c are needed to make necessary modifications in installation files of ORCHIDEE. These packages are usually installed in "/usr/local/". When in doubt, check with your system administrator, or pass "nc-config --libdir" in command prompt.
  • 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.
  • You may install ORCHIDEE with gfortran and XIOS with gcc compilers, but I would like to suggest to use mpifort (or mpif90) and mpicc (i.e. 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.

Step 1: Download ORCHIDEE

You need to install modipsl environment into a modipsl folder (you can change the name of this directory) :

      >  svn co http://forge.ipsl.jussieu.fr/igcmg/svn/modipsl/trunk modipsl

You can install a public or a private version of ORCHIDEE. Read more about installing different versions of ORCHIDEE. To install the latest tagged version :

      > cd modipsl/util
      > ./model ORCHIDEE_trunk
      > cd modipsl/util
      > ./model ORCHIDEE_2_1
      or
      > ./model ORCHIDEE_2_0

Step 2: Modification of configuration files

At 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:

ORCHIDEE 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.

The target architecture will be: gfortran

You may see the various environment configurations for ORCHIDEE in "modipsl/util/" by:

    > vi AA_make.gdef

The configuration is declared between lines 325-349 for "gfortran" in AA_make.gdef using modipsl revision 4448.

Create makefiles with the specific target for compiler gfortran, first modify if necessary the path to netcdf and then use the command ./ins_make -t gfortran to create makefiles :

    > vi AA_make.gdef   # modify eventually following lines ( The modifications can be seen by + and - at the left column of the text below )
         @@ -304,16 +304,16 @@
 #-Q- gfortran  M_K = make
 #-Q- gfortran  P_C = cpp
 #-Q- gfortran  FCM_ARCH = gfortran 
-#-Q- gfortran  F_C = gfortran -c -cpp
+#-Q- gfortran  F_C = mpifort -c
 #-Q- gfortran  #-D- MD    F_D = -g -Wall -fbounds-check -pedantic -finit-real=nan
 #-Q- gfortran  #-D- MN    F_D =
 #-Q- gfortran  #-P- I4R4  F_P =
 #-Q- gfortran  #-P- I4R8  F_P = -fdefault-real-8
 #-Q- gfortran  #-P- I8R8  F_P = -fdefault-integer-8 -fdefault-real-8
-#-Q- gfortran  w_w = -O3 -funroll-all-loops $(F_D) $(F_P) -I$(MODDIR)
+#-Q- gfortran  w_w = -O3 -cpp -funroll-all-loops $(F_D) $(F_P) -I$(MODDIR)
 #-Q- gfortran  F_O = $(w_w) -J$(MODDIR)
-#-Q- gfortran  F_L = gfortran
+#-Q- gfortran  F_L = mpifort
 #-Q- gfortran  M_M = 0
 #-Q- gfortran  L_X = 0
 #-Q- gfortran  L_O =
@@ -323,8 +323,8 @@
 #-Q- gfortran  C_O =
 #-Q- gfortran  C_L = cc
 #-Q- gfortran  #-
-#-Q- gfortran  NCDF_INC = /usr/local/include
-#-Q- gfortran  NCDF_LIB = -L/usr/local/lib -lnetcdf
+#-Q- gfortran  NCDF_INC = /cm/shared/apps/netcdf/4.6.1/include
+#-Q- gfortran  NCDF_LIB = -L/cm/shared/apps/netcdf/4.6.1/lib -lnetcdf
 #-Q- gfortran  #-
 #-Q- lxiv8    #- Global definitions for Intel compiler (ifort) with MPI at obelix/LSCE
 #-Q- lxiv8    FCM_ARCH=ifort_LSCE
   
    > ./ins_make -t gfortran    # This step is where you define thee target architecture that you want to use for installation ( in our case gfortran)

The second modification needed is to change the compile options and paths to libraries that ORCHIDEE uses (netcdf, openmpi, hdf5) in model folders. To do this following changes should be made:

     > cd modipsl/modeles
     > cp XIOS/arch/arch-GCC_LINUX.env XIOS/arch/arch-gfortran.env
     > cp XIOS/arch/arch-GCC_LINUX.fcm XIOS/arch/arch-gfortran.fcm
     > cp XIOS/arch/arch-GCC_LINUX.path XIOS/arch/arch-gfortran.path
     > touch ORCHIDEE/arch/arch-gfortran.fcm
     > touch ORCHIDEE/arch/arch-gfortran.path

Once these files are copied, now we can build our configuration files for the system we have under the architecture name "gfortran".

Remark before we make changes:

  • We copied 3 files for XIOS and created 2 files for ORCHIDEE. These files have certain goals, namely: .env file to describe the destination of libraries we will use for compilation (although this is optional, and these destinations can be defined in .path file), .fcm file to declare the compiler required flags (settings) for installation of packages, and .path file define the libraries to the compiler which we will use for installation.
  • ORCHIDEE model does not contain ".env" files, the library and include directories are defined in the ".path" files. Nevertheless, if the corresponding .env file exist, the compile script makeorchidee_fcm will take into count the file and execute the settings.
  • Therefore, we should modify these files for the library and include directories of MPI, NETCDF, HDF5 that we are using.
  • 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.

In the XIOS folder:

arch-gfortran.env file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script):

export HDF5_INC_DIR=/cm/shared/apps/hdf5/1.10.2/include  # This should be modified for your include directory of HDF5 package
export HDF5_LIB_DIR=/cm/shared/apps/hdf5/1.10.2/lib  # This should be modified for your library directory of HDF5 package

export NETCDF_INC_DIR=/cm/shared/apps/netcdf/4.6.1/include   # This should be modified for your include directory of NETCDF package
export NETCDF_LIB_DIR=/cm/shared/apps/netcdf/4.6.1/libs       # This should be modified for your library directory of NETCDF package

export BOOST_INC_DIR=$HOME/boost
export BOOST_LIB_DIR=$HOME/boost

arch-gfortran.fcm file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script):

%CCOMPILER      mpicc       # the mpi wrappers of gcc compilers are inserted here, 
#you may use gcc as well
%FCOMPILER      mpif90      # the mpi wrappers of gcc compilers are inserted here, 
#you may use gfortran as well
%LINKER         mpif90     # the mpi wrappers of gcc compilers are inserted here, 
#you may use gfortran as well

# This part gives compiler the necessary flags, thus the compiler understands under 
#which configurations it is compiling ORCHIDEE

%BASE_CFLAGS    -ansi -w -L/cm/apps/shared/openmpi/gcc/1.10.3/lib64
%PROD_CFLAGS    -O3 -DBOOST_DISABLE_ASSERTS
%DEV_CFLAGS     -g -O2 
%DEBUG_CFLAGS   -g 

%BASE_FFLAGS    -D__NONE__ -ffree-line-length-none -L/cm/apps/shared/openmpi/gcc/64/1.10.3/lib64 
%PROD_FFLAGS    -O3
%DEV_FFLAGS     -g -O2
%DEBUG_FFLAGS   -g 

%BASE_INC       -D__NONE__
%BASE_LD        -lstdc++

%CPP            cpp
%FPP            cpp -P
%MAKE           make

arch-gfortran.path file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script):

NETCDF_INCDIR="-I$NETCDF_INC_DIR"   ## these variables are imported from .env file
NETCDF_LIBDIR="-L$NETCDF_LIB_DIR"
NETCDF_LIB="-lnetcdff -lnetcdf"     ## declaration of libraries to be used

MPI_INCDIR="-I/cm/shared/apps/openmpi/gcc/64/1.10.3/include"
MPI_LIBDIR="-L/cm/shared/apps/openmpi/gcc/64/1.10.3/lib64"
MPI_LIB="-lcurl"

HDF5_INCDIR="-I$HDF5_INC_DIR"
HDF5_LIBDIR="-L$HDF5_LIB_DIR"
HDF5_LIB="-lhdf5_hl -lhdf5 -lz"

BOOST_INCDIR="-I $BOOST_INC_DIR"
BOOST_LIBDIR="-L $BOOST_LIB_DIR"
BOOST_LIB=""

OASIS_INCDIR="-I$PWD/../../oasis3-mct/BLD/build/lib/psmile.MPI1"
OASIS_LIBDIR="-L$PWD/../../oasis3-mct/BLD/lib"
OASIS_LIB="-lpsmile.MPI1 -lscrip -lmct -lmpeu"

Within ORCHIDEE folder: We have created these files with "touch" command. One option is to copy contents of option files from other files setup for different machines in LSCE ecosystem in ORCHIDEE/arch/ folder. Other option is to copy, ".fcm" and ".path" descriptions below into the respective files you have created. The options given below are set for gcc 6.3.0 compiler and openmpi 1.10.3 libraries. You have to change the destinations to library and include folders to make the files suitable for your system

arch-gfortran.path file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script):

NETCDF_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)
NETCDF_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)
IOIPSL_INCDIR="-I${ORCHDIR}/../../lib"
IOIPSL_LIBDIR="-L${ORCHDIR}/../../lib -lioipsl"
XIOS_INCDIR="-I${ORCHDIR}/../XIOS/inc"
XIOS_LIBDIR="-L${ORCHDIR}/../XIOS/lib -lxios"
MPI_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)
MPI_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)

arch-gfortran.fcm file should comprise ( lines after "#" are my comments, should be deleted if you want to use this script):

%COMPILER            mpifort   # the mpi wrappers of gcc compilers are inserted here, 
#you may use gcc as well
%LINK                mpifort   # the mpi wrappers of gcc compilers are inserted here, 
#you may use gcc as well

#declaration of flags for compiler
%AR                  ar
%MAKE                make
%FPP_FLAGS           -P -C -traditional
%FPP_DEF             
%BASE_FFLAGS         -fdefault-real-8 -cpp -L/cm/shared/apps/openmpi/gcc/64/1.10.3/lib64 
%PROD_FFLAGS         -O3 -funroll-all-loops
%DEV_FFLAGS          -O
%DEBUG_FFLAGS        -ffpe-trap=invalid,zero,overflow -Wall -fbounds-check -g3 -O0 -fstack-protector-all
%MPI_FFLAGS
%OMP_FFLAGS          
%BASE_LD      
%MPI_LD -lstdc++ -lmpi_cxx 
%OMP_LD 

Step 3: Compilation

Up 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:

   > cd modipsl/config/ORCHIDEE_OL
   > ./make with_xios
  • ./make can be ./gmake (or some other alias) in certain systems, you should verify what you have in your system, or ask to your system administrator about what they use.

CONGRATULATIONS, it's done! The ORCHIDEE executable should be in "modipsl/bin/" folder, you may create a symbolic link to that file to use ORCHIDEE, or use libIGCM framework for setting up simulations ( note that it requires ksh shell in /bin/).

This 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.

Installing 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.