wiki:Documentation/UserGuide/InstallingORCHIDEE

Version 20 (modified by jgipsl, 2 years ago) (diff)

--

How to install ORCHIDEE on an linux pc (Ubuntu or Fedora distribution)

See here https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv#HowtousetheIPSLmodelsandtoolswithalocalPC

STOP : It is not longer possible to use netcdf 3 with ORCHIDEE due to the tag IOIPSL v2_2_4 which requires netcdf 4!!!

NOTE : If you have an account on LSCE, IDRIS or TGCC computers, please follow the procedure to compile on a know computer as described here : Documentation/UserGuide/InstallingORCHIDEEBasic
NOTE : This guide is not updated to install with XIOS

This installation guide has been tested on a laptop computer using Ubuntu 16.04 version. Softwares 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
Follow the steps and you will be able to compile and launch ORCHIDEE in sequential on a point to test it !

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

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

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

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

1.a Installing netcdf library (package installation) (not tested)

Now, netcdf is available as a package for linux distribution. For Ubuntu, a package exists. Make sure that the netcdf is compiled with the same compiler as you'll compile ORCHIDEE (here gfotran compiler). This installation was not tested, but it is OK, go to step 2 !

1.b Installing netcdf library (manual installation)

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

Download netcdf-c : Open a terminal and type the following command (> represents the prompt) to download netcdf version X.Y.Z :

    >   wget http://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) 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.

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:

  • 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).
  • 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.
  • 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 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.

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 303-328 for "gfortran" in AA_make.gdef (for the modipsl tag: 4448)

The modifications are given

Create makefiles with the specific target for compiler gfortran, first modify if necessary the path to netcdf :

    > 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 configuration 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
     > cp ORCHIDEE/arch/arch-GCC_LINUX.fcm ORCHIDEE/arch/arch-gfortran.fcm
     > cp ORCHIDEE/arch/arch-GCC_LINUX.path 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:

  • 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).
  • 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.
  • ORCHIDEE model does not comprise a ".env" folder, the library and include directories will be defined in ".path" file.

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:

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

CONGRATULATIONS, it's done !

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.

3. Installing ORCHIDEE on a MAC (thanks to Matthew McGrath)

You can install ORCHIDEE on a Mac if you modify AA_make.gdef file in the following way :

#-Q- Darwin   NCDF_INC = /Users/mcgrathlib/netcdf-3.6.3/f90
#-Q- Darwin   NCDF_LIB = -L/Users/mcgrath/lib/netcdf-3.6.3/libsrc/.libs/ -lnetcdf 

You have to indicate the correct path to your netcdf library like Matthew did. Then execute the script ins_make like that :

./ins_make -t Darwin