ORCHIDEE

2017-09-28T18:20:19Z

Sorensson: /* Model description */

= ORCHIDEE =

This manual provides the information about the land-surface model ORCHIDEE ([http://forge.ipsl.jussieu.fr/orchidee orchidee]) from ''Institute Pierre Simone Laplace'' ([https://www.ipsl.fr/en IPSL]). Its installation on the HPC of the CIMA called <code>hydra</code>

= Model description =

* ORCHIDEE: sechiba & stomate
* Two major modes of simulations: Off-line (no feedback) / on-line (LMDZ, WRF)
* Off-line atmospheric forcings: [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/Forcings ORforcings]
** Atmoshperic variables required by ORCHIDEE: <code>LWdown, PSurf, Qair, Rainf, SWdown, Snowf, Tair, Wind_E, Wind_N</code>
** CRU-NCEP (v5.4, 0.5°): mixing CRU with NCEP: <code>cruncep_halfdeg_[YYYY].nc</code> at <code>hydra</code> (taking <code>${ORforcing}=/share/ORCHIDEE/data/IGCM/SRF</code>):
<pre>${ORforcing}/METEO/CRU-NCEP/v5.4/halfdeg</pre>
* Morphological forcings as data-base:
** To be interpolated to the domain of simulation (region and resolution) at the first time step (done by ORCHIDEE)
** Mandatory:
*** '''PFT map''':
**** 13 PFT, percentage of each by grid-point (<code>maxvegetfrac</code>, see table for equivalencies of PFT)
{| class="wikitable"
! num
! description
|-
| 1 || bare ground
|-
| 2 || tropical broad-leaved evergreen
|-
| 3 || tropical broad-leaved raingreen
|-
| 4 || temperate needleleaf evergreen
|-
| 5 || temperate broad-leaved evergreen
|-
| 6 || temperate broad-leaved summergreen
|-
| 7 || boreal needleleaf evergreen
|-
| 8 || boreal broad-leaved summergreen
|-
| 9 || boreal needleleaf summergreen
|-
| 10 || C3 grass
|-
| 11 || C4 grass
|-
| 12 || C3 agriculture
|-
| 13 || C4 agriculture
|}
**** <code>PFTmap_IPCC_[YYYY].nc</code> (0.5°, basic), a file per/year ESA-LUH2, historical, v1.2 at:
<pre>${ORforcing}/PFTMAPS/CMIP6/ESA-LUH2/historical/v1.2/</pre>
**** <code>carteveg5km.nc</code> (Olson's global classification of 94 PFT, 5km transformation to 13 PFT) No temporal evolution at:
<pre>${ORforcing}/PFTMAPS/</pre>
[[File:Olson_vegetmap.png|frame|50px|Global Olson vegetation at 5 km of resolution Homolosine projection]]

*** '''Soil characterisitcs'''
**** <code>soilcolor</code> used to define background-albedo: albedowet, albedodry (using values from 1 to 8). To be find in <code>soils_param.nc, soils_param_zobler.nc</code>
**** <code>soiltexture</code> to define soil type, to be grouped as 3 types: corse, medium, fine (from 7 values). 3 different sources:
***** <code>soils_param.nc</code> (1.°, basic)
***** <code>soils_param_zobler.nc</code>: 7 types (1°)
***** <code>soils_param_usda.nc</code>: 12 types (0.08331404°)
** Additional:
*** LAI: on runs without <code>stomate</code> (otherwise, LAI is dynamic), one needs to provide climatologies of the LAI: 13 LAI values which evolves along time (monthly climatology) <code>lai2D_[00/01/03].nc</code>
*** Albedo: on runs without <code>stomate</code> (otherwise, albedo is dynamic) new maps only for the bare soil albedo at higher resolution to avoid the use of <code>soilcolor</code> from <code>soils_param.nc</code>. Fixed values for wet/dry background albedo. Or a new file
**** <code>alb_bg_jrctip.nc</code>: albedos climatologies retrieved from MODIS satellite JRC-TIP package
**** <code>alb_bg_modisopt_2D.nc</code>: Another non.climatological albedo from MODIS
<pre>${ORforcing}/albedo</pre>
*** Routing: <code>routing.nc</code>: worldwide data-base of river basins at 0.5°: 1-8 direction, <89 point at the sea, ... (<code>trip</code>), riverID (<code>basins</code>), water retention (<code>topoind</code>), etc..., <code>cartepente2d_15min.nc</code> topography slope (0.25°)
*** Floodplains: <code>floodplain.nc</code> To account for maximum flooded area: <code>lake, dam, swamp, saline, pond, irrig</code>
*** Chemistry: <code>orchidee_fertilizer_1995.nc</code> with fertilization (for N<sub>2</sub>) for rice and the others
*** Reference Temperature: To be used as a reference temperature for the soil (<code>reftemp.nc</code>)

* All ORCHIDEE configuration is controlled by <code>run.def</code>.: Domain, period, physics activation, sechiba/stomate, routing, floodplains, ... [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/OrchideeParameters ORparameters]
* I/O controlled by <code>*.xml</code> files from [http://forge.ipsl.jussieu.fr/ioserver/ XIOS] libraries
** <code>iodef.xml</code>: main XIOS configuration
** <code>context_orchidee.xml</code>: I/O global configuration for ORCHIDEE
** <code>field_def_orchidee.xml</code>: definition of I/O variables (names, units, dimensions, long-name, ...)
** <code>file_def_orchidee.xml</code>: definition of variables at each file (output frequency, level of output, ...)

= Instalation =
This installation guide is based on the installation in <code>hydra</code>, which it must have pre-installed: netCDF libraries, MPI libraries, Fortan and C compilers, pre-processing tools, subversion repository code tool

== Installation steps using modipsl ==
* Go to the installation directory <code>[INSTALLDIR]</code> (for hydra <code>[INSTALLDIR]=/share</code>)
<pre>$ cd [INSTALLDIR]</pre>
* Getting the IPSL-models suite
<pre>$ svn co https://forge.ipsl.jussieu.fr/igcmg/svn/modipsl/trunk modipsl</pre>
* Going to the <code>util</code> folder:
<pre>$ cd modipsl/util</pre>
* Getting the off-line version of ORCHIDEE
<pre>$ ./model ORCHIDEE_trunk >& run_get_model.log</pre>
* We got some issues with the ports, thus, it needs to be manually done:
<pre>$ cd ../modeles</pre>
* Getting IOIPSL:
<pre>$ mkdir -p IOIPSL/src
$ svn co https://forge.ipsl.jussieu.fr/igcmg/svn/IOIPSL/tags/v2_2_2/src IOIPSL/src</pre>
* Getting XIOS library
<pre>$ svn co -r 1043 https://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/trunk XIOS</pre>
* By the end one should have:
<pre>$ ls
IOIPSL ORCHIDEE XIOS</pre>
* Going back to <code>util</code> to proceed
<pre>$ cd ../util</pre>

* These are the final versions of the codes
** ORCHIDEE: 4622
** ORCHIDEE_OL: 4622
** IOIPSL: 3379
** XIOS: 1043
* Preparing compilation environment for <code>hydra</code>. One need to add into <code>AA_make.gdef</code> specifications for <code>hydra</code> (at the end of file):
<pre>
#-Q- ifort_hydra #- Global definitions for hydra, ifort
#-Q- ifort_hydra LIB_MPI = MPI1
#-Q- ifort_hydra LIB_MPI_BIS = MPI1
#-Q- ifort_hydra FCM_ARCH = ifort_hydra
#-Q- ifort_hydra M_K = make
#-Q- ifort_hydra P_C = cpp
#-Q- ifort_hydra P_O = -P -C -traditional $(P_P)
#-Q- ifort_hydra F_C = /usr/local/bin/mpif90 -c -cpp
#-Q- ifort_hydra #-D- MD F_D = -g
#-Q- ifort_hydra #-D- MN F_D =
#-Q- ifort_hydra #-P- I4R4 F_P = -i4
#-Q- ifort_hydra #-P- I4R8 F_P = -i4 -r8
#-Q- ifort_hydra #-P- I8R8 F_P = -i8 -r8
#-Q- ifort_hydra F_O = -DCPP_PARA -O3 $(F_D) $(F_P) -I$(MODDIR) -module $(MODDIR) -fp-model precise
#-Q- ifort_hydra F_L = /usr/local/bin/mpif90
#-Q- ifort_hydra M_M = 0
#-Q- ifort_hydra L_X = 0
#-Q- ifort_hydra L_O =
#-Q- ifort_hydra A_C = ar -rs
#-Q- ifort_hydra A_G = ar -x
#-Q- ifort_hydra C_C = cc -c
#-Q- ifort_hydra C_O =
#-Q- ifort_hydra C_L = cc
#-Q- ifort_hydra #-
#-Q- ifort_hydra NCDF_INC = /usr/local/include
#-Q- ifort_hydra NCDF_LIB = -L/usr/local/lib -lnetcdf -lnetcdff
#-Q- ifort_hydra #-
</pre>
* Creation of the configuration \verb+arch+ files for the compilation of each component
* XIOS
** going there:
<pre>$ cd ../modeles/XIOS/arch</pre>
** Using CICLAD's ifort compilation as reference
<pre>$ cp arch-ifort_CICLAD.fcm arch-ifort_hydra.fcm</pre>
** Adapting values (following ifort bug issue for version 12.0.3, [https://software.intel.com/en-us/forums/intel-c-compiler/topic/289446 ifort bug]):
<pre>%CCOMPILER /usr/local/bin/mpicc
%FCOMPILER /usr/local/bin/mpif90
%LINKER /usr/local/bin/mpif90 -nofor-main

%BASE_CFLAGS -std=c++0x
%PROD_CFLAGS -O3 -D BOOST_DISABLE_ASSERTS
%DEV_CFLAGS -g -traceback
%DEBUG_CFLAGS -DBZ_DEBUG -g -traceback -fno-inline

%BASE_FFLAGS -D__NONE__
%PROD_FFLAGS -O3
%DEV_FFLAGS -g -O2 -traceback
%DEBUG_FFLAGS -g -traceback

%BASE_INC -D__NONE__
%BASE_LD -lstdc++

%CPP /usr/local/bin/mpicc -EP
%FPP cpp -P
%MAKE gmake</pre>
** Getting paths:
<pre>$ cp arch-ifort_CICLAD.path arch-ifort_hydra.path</pre>
** Adapting values:
<pre>NETCDF_INCDIR="-I/usr/local/include"
NETCDF_LIBDIR="-L/usr/local/lib"
NETCDF_LIB="-lnetcdf -lnetcdff"
MPI_INCDIR=""
MPI_LIBDIR=""
MPI_LIB=""
HDF5_INCDIR=""
HDF5_LIBDIR=""
HDF5_LIB=""</pre>
* ORCHIDEE
** Going there
<pre>$ cd ../../ORCHIDEE/arch</pre>
** Using CICLAD's ifort compilation as reference
<pre>$ cp arch-ifort_CICLAD.fcm arch-ifort_hydra.fcm</pre>
** Adapting values:
<pre>%COMPILER /usr/local/bin/mpif90
%LINK /usr/local/bin/mpif90
%AR ar
%MAKE gmake
%FPP_FLAGS -P -traditional
%FPP_DEF
%BASE_FFLAGS -i4 -r8 -fp-model precise
%PROD_FFLAGS -O3
%DEV_FFLAGS -g -O2 -traceback -fp-stack-check -ftrapuv -check bounds
%DEBUG_FFLAGS -fpe0 -O0 -g -traceback -fp-stack-check -ftrapuv -check bounds -check all
%MPI_FFLAGS
%OMP_FFLAGS -openmp -openmp-threadprivate compat
%BASE_LD -i4 -r8
%MPI_LD
%OMP_LD -openmp</pre>
** getting paths
<pre>$ cp arch-ifort_CICLAD.path arch-ifort_hydra.path</pre>
** Adapting values:
<pre>NETCDF_LIBDIR="/usr/local/lib -lnetcdf -lnetcdff -lstdc++"
NETCDF_INCDIR=/usr/local/include
IOIPSL_INCDIR=../../../lib
IOIPSL_LIBDIR=../../../lib
XIOS_INCDIR=${ORCHDIR}/../XIOS/inc
XIOS_LIBDIR="${ORCHDIR}/../XIOS/lib -lxios"</pre>
\end{enumerate}
** Going back to <code>util</code> to proceed
<pre>$ cd ../../../util</pre>
** Installing the code:
<pre>$ ./ins_make -t ifort_hydra >& run_ins_make.log</pre>
** Going there:
<pre>$ cd ../config/ORCHIDEE_OL</pre>
** No need to loading the right environment since in <code>hydra</code> its by default
** Compiling XIOS in sequential (in <code>Makefile</Code>, adding no-parallel compilation):
<pre>./make_xios --netcdf_lib netcdf4_seq (...)</pre>
** Compiling:
<pre>$ gmake >& run_gmake.log</pre>
** Checking if everything went fine:
<pre>$ cat -n run_gmake.log | grep Error
$ cat -n run_gmake.log | grep undefined
$ ls ../../bin/
orchidee_ol xios_server.exe</pre>

= Running the model =
ORCHDEE can run in a large variety of forms. Here is desribed a simple way to run a year of simulation
* Assuming a working directory <code>${WORKDIR}</code> (e.g.: <code>/home/lluis.fita/estudios/LUPA</code>). Creation of the running folder
<pre>$ mkdir -p tests/control
$ cd tests/control</pre>
* Writting of a simple <code>run.def</code> with stomate and routing activated for the 1977 year
<pre>
# Use XIOS for writing diagnostics file
# defulat = n
XIOS_ORCHIDEE_OK = y
#
START_DATE = 1977-01-01_00
END_DATE = 1978-01-01_00
TIME_LENGTH = 1Y
DT_SECHIBA = 1800

# Atmospheric forcing file
FORCING_FILE = atmos_forcing.nc

#
# South America
#
#WEST_EAST = -85., -31.
#SOUTH_NORTH = -57, 14.
LIMIT_WEST = -85.
LIMIT_EAST = -31.
LIMIT_SOUTH = -57.
LIMIT_NORTH = 14.
MERID_RES = 0.5
ZONAL_RES = 0.5

VEGET_YEAR=1

# Activation of stomate
STOMATE_OK_CO2= y
STOMATE_OK_STOMATE= y

# For routing
RIVER_ROUTING = y
ROUTING_FILE = routing.nc
HYDROL_CWRR = y
DT_ROUTING = 86400
RIVER_DESC = y
RIVER_DESC_FILE = river_desc.nc
ROUTING_RIVERS = 50

# Debug standard output printing level
PRINTLEV = 0</pre>
* Linking atomspheric forcing files (0.5° CRU-NCEP v5.4 files)
<pre>$ ln -s /share/ORCHIDEE/data/IGCM/SRF/METEO/CRU-NCEP/v5.4/halfdeg/cruncep_halfdeg_1977.nc ./atmos_forcing.nc</pre>
* Linking the routing data-base
<pre>$ ln -s /share/ORCHIDEE/data/IGCM/SRF/routing.nc ./</pre>
* Linking the topographical slope
<pre>$ ln -s /share/ORCHIDEE/data/IGCM/SRF/cartepente2d_15min.nc ./</pre>
* Linking the morphological files
<pre>$ ln -s /share/ORCHIDEE/data/IGCM/SRF/soils_param.nc ./
$ ln -s /share/ORCHIDEE/data/IGCM/SRF/PFTmap_IPCC_1850.nc ./PFTmap.nc</pre>
* Getting the XIOS files
<pre>$ cp /share/modipsl/modeles/ORCHIDEE/src_xml/*xml ./</pre>
* Edit the <code>file_def_orchidee.xml</code> to define output frequency and level of of output (remove all the <code>_AUTO_</code>)
<pre>$ vim file_def_orchidee.xml</pre>
* The final configuration gets:
<pre>$ cat file_def_orchidee.xml | grep 'file id'
<file id="sechiba1" name="sechiba_history" output_level="11" output_freq="1d" enabled=".TRUE.">
<file id="sechiba2" name="sechiba_out_2" output_level="2" output_freq="1mo" enabled=".FALSE.">
<file id="sechiba3" name="sechiba_history_4dim" output_level="11" output_freq="1d" enabled=".TRUE.">
<file id="sechiba1_alma" name="sechiba_history_alma" output_level="10" output_freq="1mo" enabled=".FALSE.">
<file id="sechiba2_alma" name="sechiba_out_2_alma" output_level="10" output_freq="1d" enabled=".FALSE.">
<file id="stomate1" name="stomate_history" output_level="10" output_freq="1d" enabled=".TRUE.">
<file id="stomate2" name="stomate_ipcc_history" output_level="1" output_freq="1mo" enabled=".FALSE."></pre>
* Linking the ORCHIDEE executable
<pre>$ ln -s /share/modipsl/bin/orchidee_ol ./</pre>
* Getting the PBS scheduling job to run ORCHIDEE
<pre>$ cp /share/ORCHIDEE/run_or.pbs ./</pre>
* Launching the model
<pre>$ qsub run_or.pbs</pre>
* If everything went fine, one should have (at least)
<pre>orout/sechiba_history.nc orout/sechiba_history_4dim.nc stomate_history.nc</pre>
** <code>sechiba_history.nc</code>, <code>sechiba_history_4dim.nc</code>, <code>stomate_history.nc</code>: Outputs (optional, only when stomate is activated)
** <code>sechiba_rest_out.nc</code>, <code>stomate_restart.nc</code>: restarts for <code>sechiba<code> and <code>stomate</code> (optional, only when stomate is activated)
** <code>out_orchidee_[nnnn]</code>: standard output files for each process
** <code>river_desc.nc</code>: output with river description (optional, only when routing is activated)

= Compiling rebuild =

Due to the fact that <code>hydra</code> does not have the netcdf libraries compiled in parallel, ORCHDEE output is written with multiple files being a file for each process. In order to overcome this output. IPSL does prepare a tool to join the files and provide the expected output. This tool is called <code>rebuild</code> (a Kornshell script which encapsulates de exacutable <code>flio_rbld</code>) and it comes with the <code>IOIPSL</code> libraries. The IOIPSL libraries, are a set of old libraries developed by the IPSL (M. A. Foujuls, J. Polcher among others) to deal with the netCDF data access for all the models developed at the IOIPSL. Compiling IOIPSL (following [http://lmdz.lmd.jussieu.fr/utilisateurs/faq-en/installation/comment-installer-ioipsl-et-loutil-rebuild install rebuild]. It has to be compiled independently. Here it is explained how it has to be done.

* Go to the instalation directory <code>[INSTALLDIR]</code> (at hydra <code>share</code>)
<pre>$ cd [INSTALLDIR]</pre>
* getting the last version of the code
<pre>$ svn co https://forge.ipsl.jussieu.fr/igcmg/svn/modipsl/trunk modipsl_IOIPSLtools</pre>
* going to prepare compilation/installation
<pre>$ cd modipsl_IOIPSLtools/util</pre>
* preparing environment
<pre>./model IOIPSL_PLUS</pre>
* We got some issues with the ports, thus, it needs to be manually done:
<pre>$ cd ../modeles</pre>
* Getting IOIPSL ('''NOTE:''' notice the difference in library's version from the previous one):
<pre>$ svn co https://forge.ipsl.jussieu.fr/igcmg/svn/IOIPSL/tags/v2_2_3 IOIPSL</pre>
* Comming back to the <code>util</code> folder
<pre>$ cd ../util</pre>
* Creation of the compilation environment for <code>`hydra'</code> using <code>'ifort'</code> inside <code>AA_make.gdef</code> as in the full compilation
<pre>$ cp ../../modipsl/util/AA_make.gdef ./</pre>
* Preparing makefiles
<pre>$ ./ins_make -t "ifort_hydra" -p I4R8</pre>
* going to src folder to compile
<pre>$ cd ../modeles/IOIPSL/src</pre>
* cleaning (you never know...)
<pre>$ make clean</pre>
* compiling
<pre>$ make >& run_make.log</pre>
* Checking no errors:
<pre>$ cat -n run_make.log | grep Error</pre>
* compilation of tools (file concatenation)
<pre>$ cd ../tools </pre>
* cleaning (you never know...)
<pre>$ make clean</pre>
* compiling
<pre>$ make >& run_make.log</pre>
* Checking no errors:
<pre>$ cat -n run_make.log | grep Error</pre>
* One should have:
<pre>$ ls ../../../bin/
flio_rbld rebuild</pre>

= debug Instalation =
Getting a debugging copy for test purposes

== Instalation steps using modipsl ==
* Go to the instalation directory <code>[INSTALLDIR]</code> (<code>/share</code> in <code>hydra</code>)
<pre>$ cd [INSTALLDIR]</pre>
* Getting the IPSL-models suite (r 3379)
<pre>$ svn co https://forge.ipsl.jussieu.fr/igcmg/svn/modipsl/trunk modipsl_dbg</pre>
* Once we got the codes, we need to copy the specificities of the installation for <code>hydra</code>
<pre>$ cp ../../modipsl/util/AA_make.gdef ./
$ cp ../../modipsl/modeles/XIOS/arch/*hydra* ../modeles/XIOS/arch/
$ cp ../../modipsl/modeles/ORCHIDEE/arch/*hydra* ../modeles/ORCHIDEE/arch/</pre>
* Everything is the same as for the installation, except that we need to indicate debugging compilation:
<pre>./ins_make -t ifort_hydra -d >& run_ins_make.log</pre>
* And on <code>Makefile</code> from <code>config/ORCHIDEE_OL</code>, change all the <code>-prod</code> by <code>-debug</code>
<pre>(...)
xios :
(cd ../../modeles/XIOS ; ./make_xios --netcdf_lib netcdf4_seq \
--debug --arch ${FCM_ARCH} --job 8 ; cp bin/xios_server.exe ../../bin/. ; )
(...)
driver :
(cd ../../modeles/ORCHIDEE ; ./makeorchidee_fcm -j 8 -parallel mpi -debug -arch ${FCM_ARCH} -driver ; )
(...)
driver_xios :
(cd ../../modeles/ORCHIDEE ; ./makeorchidee_fcm -xios2 -j 8 -parallel mpi -debug -arch ${FCM_ARCH} -driver ; )
(...)</pre>
* Compiling:
<pre>$ gmake >& run_gmake.log</pre>
* Checking if everything went fine:
<pre>$ cat -n run_gmake.log | grep Error
$ cat -n run_gmake.log | grep undefined
$ ls ../../bin/
orchidee_ol xios_server.exe</pre>

Wikicima - Contribuciones del usuario [es]

ORCHIDEE