Created by X. Wang in 02/2021 following the request of ORCHIDEE group.

Part of information from a previous web page.

Updated in 03/2021, 09/2021

Drivers in ORCHIDEE

We have two drivers available, src_driver/dim2driver and src_driver/orchideedriver. We would like to have only one standard driver for ORCHIDEE in the end. The new driver is hoped to be the default one in the future.

I) The old driver (src_driver/dim2driver)

This driver assumes that scalar variables (Tair,Qair,Psurf,Wind) are instantaneous values at the timestamp, while flux variables (Rainf,Snowf, SWdown, LWdown) are mean values over the interval ending at the timestamp. This driver also requires that the first value of the annual files corresponds to 00UTC+dt_forcing (for instance 03UTC for a 3hourly forcing), and that the last value is for Dec 31st at 24UTC = 00UTC on Jan 1st of the following year. Your files must be prepared accordingly.

• Cell-method time attribute:
  • The time attributes are optional but recommended, so the files can also be used by the new driver.
  • This time attributes should be "time: instantaneous" for the scalars (Tair,Qair,Psurf,Wind), and "time: mean(end)" for the fluxes (Rainf,Snowf, SWdown, LWdown). If the physical definitions of your forcing variables do not fit this scheme, then you should avoid using this forcing with dim2driver, unless you manage to adapt your files to these constraints.

• SPRED_PREC: By default, we spread the precipitation over half the forcing time step (1.5h and 3h respectively for 3-hourly and 6-hourly files). but for high-temporal forcing data (such as fluxnet), it is the same as the forcing time step.

II) The new driver (src_driver/orchideedriver.f90)

This driver is expected to be more flexible and to deal with any temporal structure of the forcing datasets, provided the required attributes are inserted in the forcing files. This document Description_Forcing_Files.pdf​ provides details of how forcing files need to be prepared. It addresses in particular the issues one may face when the fluxes are averaged and scalar variables are instantaneous. The driver needs to take this into account,otherwise the diurnal cycle can be misplaced. Some data providers have different conventions for representing averaged fluxes, and such information is important to know.

• cell_methods time attribute: you need to add a time attribute to each variable, e.g. "time: instantaneous" our "time: mean(end)", further details in Description_Forcing_Files.pdf​. The new driver can work with forcing files of various cell methods, while the old driver works with specific forcing data (CRU).

• SPRED_PREC: In the driver files precipitation is the accumulated value over the time step of the driver file (e.g. 6 hours). In ORCHIDEE it needs to be decided whether over which time period (in seconds) this precip will come down. Short periods make rain storms, long periods make drizzel. In the new driver, we have SPRED_PREC_SEC in PARAM/run.def with a relative small value, ie., 3600 (ie., 1hour) by default.

• restart file: The new driver does not need the restart file in the orchideedriver.card, while the old driver does have restart file in the orchidee_ol.card.

The structure and the organisation of the new driver code is quite different from the older driver. While the older driver has the main code dim2_driver.f90 by calling readdim2.f90, the main code of new driver is orchideedriver.f90 by calling globgrd.f90, forcing_tools.f90, forcingdaily_tools etc.

• The organisation and the structure of orchideedriver.f90 are improved compared to dim2_driver.f90, with more comments in the codes.

• forcing_tools.f90: deals with forcing files, open, interpolation, writing. The most important routines of foring_tools are forcing_open and forcing_getvalues.

• globgrd.f90: manage the spatial grid of the forcing. It can either read a file containing the grid information, as is the case for WRF forcing, or obtain the grid from the forcing files.

Previous discussion and recent efforts about the new driver

The new driver was initially developed by Jan in the branch Routing, and then it was included in ORCHIDEE by Josefine. A long discussion on the differences between the two drivers (dated in 2016) can be found on ​https://forge.ipsl.fr/orchidee/wiki/Branches/Driver_Improvements.

I) Recent progress

Recently, the work on the new driver has been picked up by X. Wang since July 2020. A short report summarizes the first part of this efforts and can be found on ​https://forge.ipsl.fr/orchidee/attachment/wiki/Documentation/Forcings/nouveau_driver_doc.2.pdf. The continued efforts are summarized below.

• the recent version of new driver is included in the trunk. This is committed in r7082.
• fixed a bug when using the forcing file of coarse resolution: corresponding to the ticket ​https://forge.ipsl.fr/orchidee/ticket/575
• in order to use new driver for spinup and fg1trans as well, we modified src_driver/forcing_tools.f90, libIGCM/libIGCM_config/libIGCM_config.ksh, run.def and orchideedriver.driver etc. These changes are committed into r7082.
• in order to prepare the forcing file when using the new driver, we added a new script AddYears? in TOOLS/Utilitaire/newdriver for ORCHIDEE. This is committed in r7112.
• in order to faciliate users, we have created necessary forcing files for using new driver and added them into the IGCM repository.
• in order to be consistent with the recent version of FG2, we created FG2nd configuration files for using the new driver. Updated all the configuration files (spinup analystique, fg1trans, fg2, fg8) in the recent version of trunk by using the new driver. After testing them for a few years, these updates are committed in r7119 of trunk. Fixed the ticket ​http://forge.ipsl.fr/orchidee/ticket/730
• identified that the old and the new drivers have the reversed order of latitude when writing the restart file
• Global spinup simulations over 400 years are done by using the new driver in spring 2021 (thanks to Matt)
• In spring 2021, Matt mentioned the speed of simulation by using the new driver, compared to the old one. Some profiling tests were applied to the simulations by using new and old drivers. In PARAM/run.def, dt_sechiba =1200 was found to be responsible for most of the slowness of the new driver. The value of this parameter depends on user's need. The smaller value, the slower computation, but with more time steps during the simulation.
• In summer 2021, a new ticket ​http://forge.ipsl.fr/orchidee/ticket/786 was submitted concerning a problem of the new driver when using the compressed forcing file. By using the latest version of compressed forcing file CRU JRA v2.2, small modification were applied and tested. The new driver now works with the compressed forcing file such as CRU JRA 0.5 degree. But it does not work with the older version of CRU JRA v2.1 0.5 degree , due to some inconsistency between land variable and contfrac in the forcing data.
• The new driver in Tag 2.2 is updated by Agnes in summer 2021.
• Simulation tests were made with trunk (spinup 50 years, fg1trans and fg2 10 years) by using CRU JRA v2.2 and new driver. Identified a few minor errors about : 1) the format of 1900-year forcing file in 0.5deg and 2deg CRU JRA v2.2, 2) libIGCM version in mod.def, 3) config.card for spinup, 4) dt_sechiba=1800 in run.def. The corrections were committed to r7296. The ticket ​​http://forge.ipsl.fr/orchidee/ticket/730 is closed.
• Complete simulation were made with trunk rev 7706, by using new and old drivers, with spinup, fg1trans and fg2. The comparisons show consistency by using the two drivers. rev 7706 is now the tagged 4_1 in orchidee.
• In rev 7503, Lucia R included modified codes into the new driver in Tag2.2, in order to deal with safran forcing files. The corresponding codes was integrated into trunk in rev 7596 by Josefine J. with Routing=N by default in orchidee.def.
• In rev 7714, Xiaoni W included modified codes into trunk in order to implement pixel-level simulation by using the safran forcing. Tests work in prod mode for multiple tests as summarized in ticked 845. In debug mode, there are two small concerns found in ticket 858.
• In rev 7715, the configuration files for safran simulation were updated in trunk.
• In ticket 854, Jan P reported several problems in the current safran forcing files. Nicolas Viovy is working on it.

II) Useful information for the users of the new driver:

1) After users download the recent ORCHIDEE trunk, the default simulation configurations are already prepared and are ready to be used. they are in config/ORCHIDEE_OL/, with 'nd' in the folder names as for new driver.

2) The new driver need the forcing files of previous, current, and next year.

Suppose that we have forcing files over 1901-1910, we need forcing files for 1900 and 1911 when using the new driver. The script AddYears? is to prepare for such forcing files.

• Most recent forcing files now have extra forcing files in the default IGCM repository: the users do not need run this script, or modify the data path in .card. Running a simulation with new driver will be the same as the old one, since the good configuration files .card are already included in the experiment folder.
• If a user need older version of forcing files, he/she may need to: a) run the script AddYears? firstly, b) then modify the forcing path in the orchideedriver.card by using the right path to the forcing files before launching simulation.c) be careful about the calendar type for different forcing files. This script has been tested with CRUJRA (two deg and half deg of of recent version), WFDEI, CRU-NCEP (two deg and one deg).

3) in PARAM/orchidee.def: if we use forcing file of coarse resolution, it would be better to set RIVER_ROUTING = n to avoid possible routing errors. This is already included in the default configurations of simulation when using the new driver.

4) In PARAM/run.def, dt_sechiba = 1800. The larger value, the faster simulation. It is up to users to define the value of this parameter according to their specific need.

5) The number of MPI is 64 in the config.card by default if using WFDEI 0.5 degree, and it is 32 if using CRU 2degree. The users should choose the right forcing files for their simulation firstly, and then use a good MPI number according to their need and their computing resource.

6) The users might need to update libIGCM before running the new driver in other Tags than trunk.

III) A few more things on going:

• to test the new driver in the recent version of trunk by running spinup analytic, fg1transnd and fg2nd.

The previous comparisons of FG1 can be found at ​https://orchidas.lsce.ipsl.fr/mapper/?set=Milestone-4.1&mode=FG1 (thanks to Vlad)