How to install ORCHIDEE on a Linux PC (Ubuntu or Fedora distribution)
Mostly obsolete
Author: D: Solyga
Last revision: 2020/02/28, M. McGrath
- It's best to install XIOS (the routines which manage input and output of the whole IPSL suite of models) first on your computer, and then compile ORCHIDEE with the same options. Advice on installing XIOS on a personal computer is found here: https://forge.ipsl.fr/igcmg_doc/wiki/Doc/ComputingCenters/LocalPC
- If you have an account at LSCE, IDRIS or the TGCC computers, follow the procedure to download and compile ORCHIDEE as described here: Documentation/UserGuide/InstallingORCHIDEEBasic
- The text below contains more details about installing libraries and ORCHIDEE with gfortran on a personal Linux computer. If the libraries already exist on your computer, you can use the above pages.
This installation guide has been tested on a laptop computer using Ubuntu 16.04 version.
Software used : mpicc (C compiler with MPI libraries wrapped around it), mpifort (or mpif90) (Fortran 90 compiler with MPI libraries wrapped around 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 possible (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 and if links between packages is needed it is generally done by default. 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 already 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 to download the latest NetCDF version (as of the time of writing, 4.7.3 is the most recent) :
wget https://www.unidata.ucar.edu/downloads/netcdf/ftp/netcdf-c-4.7.3.tar.gz
Older versions can be download with:
wget https://github.com/Unidata/netcdf-c/archive/X.Y.Z.tar.gz
(where X, Y, and Z are 4.6.1, for example, or 4.7.0).
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 type
./configure --help
This command returns rather a long list of options that we can use to build (compile and link) the package. The 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:
./configure
Which outputs a large number of "Checking" lines and finishes with a table like this:
# NetCDF C Configuration Summary ============================== # General ------- NetCDF Version: 4.7.3 Dispatch Version: 1 Configured On: Fri Feb 28 11:01:24 CET 2020 Host System: x86_64-pc-linux-gnu Build Directory: /home/jgipsl/netcdf-c-4.7.3 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 -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 location of these libraries, in particular 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 specified at "./configure" step by "--prefix" option. If this is missing, the package will be installed at a default location (found by looking for the "Install Prefix:" line after running the configure command above).
To complete the installation, type :
sudo su
On Fedora :
su
Enter your password then execute the following commands in order:
make
( compiles NetCDF on your computer) Then
make check
( tests the compilation )
and finally the installation :
make install
(copies the files to their final destination)
If your installation was successful, the following message will appear:
+-------------------------------------------------------------+ | 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 | +-------------------------------------------------------------+
Afterwards, you can delete the directory netcdf-c-X.Y.Z if you want to (this is optional).
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 the same netcdf library version, and with the same compiler that compiled NetCDF, hdf5, and MPI).
- The paths to "lib" and "include" directories of hdf5, gcc, and netcdf-c are needed to make modifications in installation files of ORCHIDEE so that ORCHIDEE can find them. These packages are usually installed in "/usr/local/". When in doubt, check with your system administrator, or type "nc-config --libdir" in the command prompt (terminal window).
- Configuration files for installation of ORCHIDEE are by default setup for the clusters used by IPSL. These configuration files work well for their environments, however, we need to modify the configuration files and make them suitable for our system, after which we can install without problems.
- You may install ORCHIDEE with gfortran and XIOS using gcc compilers, but I would like to suggest to use mpifort (or mpif90) and mpicc (i.e. the mpi wrapped 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. As mentioned above, you can still run ORCHIDEE on a single processor even if it's been compiled in parallel mode.
Step 1: Download ORCHIDEE
ORCHIDEE forms part of the IPSL Earth System Model. As such, it sits within a collection of scripts that allow for coupling different components of the Earth system together, known as the modipsl environment. An overview of the modipsl environment can be found here.
The first step to installing ORCHIDEE is thus to install the modipsl environment into a folder. This folder will eventually hold your ORCHIDEE model source code and the configuration files to run the simulation:
svn co http://forge.ipsl.fr/igcmg/svn/modipsl/trunk MYDIRECTORY
MYDIRECTORY can be named whatever you find useful to remember what is special about this version of ORCHIDEE.
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 (tagged versions are major releases):
cd MYDIRECTORY/util
./model ORCHIDEE_trunk
To install older tagged version (e.g., 2.1 or 2.0):
cd MYDIRECTORY/util
./model ORCHIDEE_2_1
or
./model ORCHIDEE_2_0
You will likely see this at the end:
Target_Host linux not supported
This is what we will set up in the next section.
Step 2: Modification of configuration files
At this point, you have downloaded the modipsl environment and the ORCHIDEE model into MYDIRECTORY. You should now modify the configuration files that declare the locations of libraries and header (include) folders so we can establish the link between the packages we have installed in first part of the tutorial and ORCHIDEE.
General compilation instructions for ORCHIDEE are found here.
ORCHIDEE uses configurations (folders with files that define some model behavior and features) that are predefined for various systems. The 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 by:
cd modipsl/util/ 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, delete the line with – and add the line with + )
@@ -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.
To modify them, go through the steps below.
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.
