wiki:DevelopmentActivities/OasisDriver

Version 14 (modified by nvuilsce, 5 years ago) (diff)

--

Introduction

Today ORCHIDEE is designed to be called by a subroutine independently on each processor. This is implemented for instance in the traditional off-line driver (dim2_driver.f90) :

Driving ORCHIDEE from a subroutine

This assumes that the domain decomposition of the atmospheric model (or the driver) and ORCHIDEE are the same. It also means that the processors which have no land point to deal with are waiting for the others to finish.

In order to avoid these issues and generalise the coupling of ORCHIDEE with other atmospheric components, the OASIS-MCT coupler can be used. In this case the atmosphere can work on any number of processors and ORCHIDEE on a distinct set of processors. This is exemplified in the driver2oasis presented below. Here, the driver (driver2oasis.f90) which mimics the atmosphere, is a single processor code which just reads some forcing files and provides that data to OASIS. It is a prototype for any atmospheric model which would send the same fields from its n processors to OASIS.

A model for driving ORCHIDEE through OASIS

In the OASIS approach to coupling, a number of advantages are gained :

  • The atmosphere can run on a different set of processors than the land surface and have its own domain decomposition.
  • ORCHIDEE will only execute on the processors attributed to it and only treat land surface points.
  • After the atmosphere has sent its data to OASIS it can continue to work on processes which do not require the input of the land surface.
  • In the same way, once the land surface has returned the variables needed by the atmosphere (i.e. after solving the surface energy balance) it can continue to work and prepare the next time step.
  • The land surface model is an independent executable which has its own restart mechanism and history system and can thus be developed in a more autonomous way.

The driver for OASIS : driver2oasis.f90

This code simulates an atmospheric model which would provide data for ORCHIDEE through OASIS-MCT.

As the original ORCHIDEE driver (dim2_driver.f90) is outdated and inflexible it has been redeveloped here.

For the moment this code only reads compressed by gathering forcing files which contain a sufficient amount of meta-data (Description_Forcing_Files.pdf).

The code is designed to run only on one processor. It should not be a limiting factor in the execution time as it only reads once the forcing and then only does some simple time interpolations. Furthermore these interpolations are done while ORCHIDEE runs, i.e. it is not blocked by an oasis_get call.

The fields which OASIS exchanges between the atmosphere and the surface

From the atmosphere to ORCHIDEE

Name units ID on driver side ID on ORCHIDEE side
Height of T and Q m ZLTQDRIV HEIGHTTQ
Height of wind m ZLUVDRIV HEIGHTUV
Atmospheric temperature at lowest atmsophric level K TAIRDRIV TEMPLEV1
Atmospheric moisture at lowest atmsophric level kg/kg QAIRDRIV HUMILEV1
Rainfall kg/m2/dt RAINDRIV RAINFALL
Snowfall kg/m2/dt SNOWDRIV SNOWFALL
Downward solar radiation W/m2 SWDODRIV SHOWDOWN
Downward longwave radiation W/m2 LWDODRIV LONWDOWN
Solar angle ?? SOLADRIV SOLARANG
Eastward atmsopheric wind m/s UWINDRIV EASTWIND
Northward wind m/s VWINDRIV NORTWIND
Surface pressure Pa PRESDRIV SURFPRES
Surface drag s/m

From the surface to the atmosphere

Name units ID on driver side ID on ORCHIDEE side
Surface evaporation kg/m2/dt EVAPDRIV TOTEVAPS
Sensible heat flux W/m2 SENSDRIV FLUXSENS
Latent heat flux W/m2 LATEDRIV FLUXLATE
Diffuse freshwater flux to the oceans m3/dt COASDRIV COASTFLO
River flux into the ocean m3/dt RIVEDRIV RIVERFLO
Net CO2 flux ?? NECODRIV FLUNECO2
?? ?? LUCODRIV FLULUCO2
Surface radiative temperature K TRADDRIV TSURFRAD
Surface temperature K TNEWDRIV TSURFNEW
Surface humidity kg/kg QSURDRIV QSURFNEW
Near Infra-red albedo - ANIRDRIV ALBEDNIR
Visible albedo - AVISDRIV ALBEDVIS
Surface emissivity - EMISDRIV EMISLONW
Surface roughness m ROUGDRIV ROUGNESS

dt : is the time step used by the models. We do not expect ORCHIDEE and the atmospheric model to use different time steps.

The "main" which controls the ORCHIDEE execution : orchideeoasis.f90

The main, in the FORTRAN sense is very similar to the intersurf.f90 which as been used up to now. The main difference is that it obtains the atmospheric data by issuing the needed OASIS_get calls. It will perform the following actions :

  • Read the grid description in a netCDF file.
  • Set-up the domain decomposition for the grid.
  • Set-up the restart and history mechanisms.
  • Start the OASIS exchanges and obtain the atmospheric data.
  • Call sechiba_main
  • Send to the atmosphere (or the driver) the computed fluxes.
  • Write to the history files
  • return to the next call to OASIS in order to obtain the atmospheric data for the next time step.

Configuration of this ORCHIDEE version

As OASIS does not provide a mechanism to exchange time and grid descriptions between two coupled models, some extra information needed to be added to the run.def and read from other files. Obviously the coupling mechanism itself also needs to be documented in the namcouple of OASIS.

Added information in the run.def

  • The information on the length of the simulation which has been provided previously in run.def is insufficient to ensure that the driver and ORCHIDEE run over the same period. In order to solve this the run.def now needs to include a start and an end date for the simulation. The two keywords are (The dates provided need to be in the ISO format and be exact (include hour, minutes and seconds).) :
    • START_DATE = 1990-01-01 0:0:0
    • END_DATE = 1990-03-01 0:0:0
  • The time step is not any more provided as a decomposition of forcing time step but rather in actual seconds to be used (driver2oasis.f90 takes care of doing the right temporal interpolation) :
    • TIME_STEP = 900
  • In the same way, the distribution of the average rainfall, provided by the forcing, over the finer time stepping of the model is given in seconds :
    • SPRED_PREC_SEC = 3600
  • The time interval to be simulated can cover more than one forcing file. Thus the option which names the forcing file accepts a list of files :
    • FORCING_FILE = WFDEI_CRU_2008.nc WFDEI_CRU_2009.nc
  • The description of the region over which to run has been simplified as well (this is only read by the driver2oasis.f90 in the initialisation pahse (when run with the -init option) as after this step all this information is in the grid file) :
    • WEST_EAST = -19.3, 62.3
    • SOUTH_NORTH = -6.3, 62.3
  • A file containing the grid description is needed to ensure that the driver and the model use the same geographical domain :
    • GRID_FILE = EuroMed_grid.nc

The grid description file

The grid file (in netCDF format) is generated by the driver2oasis or by the atmospheric model. In the case of an off-line simulation this file is generated in an initialisation call (driver2oasis -init) based on the forcing file. The program will read the forcing file, compute the land/ocean mask and other ancillary information.

We will ensure that orchideeoasis.f90 (the main program for ORCHIDEE) will be able to read also grid description files of other atmospheric models it is coupled to. WRF will be the first case implemented.

This file needs to provide the following information to ORCHIDEE :

  • Longitude of all points
  • Latitude of all points
  • land/sea mask (1 over land O over oceans)
  • area of each grid box
  • corners in lon and lat of the corners of the grid box
  • Index of land point in the global grid
  • neighbours
  • ...

As more models are integrated in the coupling model the information to be provided by the grid file will be refined.

The namcouple

The namcouple is a configuration file of OASIS and it needs to provide some basic information for the coupling process :

OASIS key word Description Values used for the ORCHIDEE coupling
$NFIELDS The number of fields described in the second part of the namcouple 27
$NBMODEL The number of models in this experiment + their names (6 characters) 2 driver orchid
$RUNTIME The total simulated time for this run in seconds To be filled out by the script launching the simulation and computed from the start and end fdates provided in run.def
$NLOGPRT Amount of information written to OASIS3-MCT log files (see User Guide) 0
$STRINGS Description of fields being exchanged ... detailed below
1) Symbolic names for the field as found in the sending model See table above
2) Symbolic names for the field as found in the receiving model See table above
3) Index of field in cf_name_table.txt 1 ... not used ?
4) Exchange frequency for the field in seconds completed by a script and using information from the run.def
5) Number of analysis to be performed 1 ... is it used ?
6) Restart input NetCDF file names Name of the file where the data could be written
7) Field status: EXPORTED, EXPOUT, INPUT, OUTPUT EXPORTED in all cases

A sample namcouple is provided .

Execution of the model coupled to the driver

As OASIS-MCT is linked into both models (driver2oasis and orchideeoasis) the execution of the coupled model is simply achieved by one mpirun command. It can have the following structure :

mpirun -n $PEDRIV driver2oasis : -n $PEORCH orchideeoasis

where : PEDRIV=1 and PEORCH=$(($NSLOTS-$PEDRIV)), i.e. only one processor is dedicated to the driver and all others work on ORCHIDEE.

In the execution directory the 3 configuration files presented above need to be present :

  • run.def
  • Grid file with the name given in run.def
  • namcouple

As in previous version of the off-line version of ORCHIDEE the following files are needed :

  • forcing files as named in run.def
  • Restart files if available
  • Surface description files as needed for the model configuration specified in the run.def

Execution of the model coupled to WRF

Attachments (2)

Download all attachments as: .zip