Implementation of the general interface at IPSL
Last modified: Mon May 15 18:06:38 WET 2000
This short note describes the implementation of the general interface
(Polcher et al. 1998) in the IPSL models.
The driver programs (dim2_driver.f90, readdim2.f90) and the interface routine (intersurf.f90) which is used by ORCHIDEE are made
available to illustrate the implementation. This driver now reads in
directly netCDF files which comply with the ALMA
The driver is the code which reads the forcing data and prepares it
for use by the land-surface scheme (LSS). The interface routine on the
other hand contains information on the LSS and adapts the forcing data
to the LSS.It will thus change from one LSS to the other.
It would be much better to provide these two routines with a
functional LSS which would allow to see much better how the interface works. I do
not have a Bucket model ready to be coupled to the driver but perhaps
somebody can help.
The driver which is provided (dim2_driver.f90) should run with any
forcing data from the point scale to the globe. This is achieved
through F90 allocate statements and a general data format : netCDF.
The only requirement is that the forcing data is stored in NetCDF
files. On the ORCHIDEE web
pages you will find code to generate these forcing files for a few
data sets. We provide the code you will need to transform the data
from the ISLSCP CD-ROMs and the Cabauw data. In the month to come new
data sets will be made available. If you have any data set you would
like to distribute this way do not hesitate to contact us.
The following general ideas have guided the development of the interface :
- The interface links two models and has thus two components :
- The atmospheric model or the driver has a call to the interface routine. In
either one of these codes we do not wish to have any assumption on the
LSS so that we can switch from one scheme to another without changing
a single line of code. It is also an important point if one wishes to be able
to drive the LSS from either atmospheric model or from observed data without
changing the LSS.
- The interface routine which does all the conversions from the atmospheric model
conventions to the LSS conventions. This can affect the structure of
the forcing data, the ordering of the element and the units of the
variables. In this subroutine we go from the general atmospheric
forcing to the variables as they are needed by the LSS. As these
transformations are LSS specific, this subroutine belongs to the LSS
code and should be independent of the type of forcing data.
- The interface works on the grid of the atmosphere. This means
that no information on the land-surface sub-grid or other details need
to be transfered. If on the other hand, the atmosphere has a sub-grid
representation of the physics or planetary boundary layer then each of
these points will go independently into the interface. It only means
that a number of data points passed through the interface will have
the same physical coordinates and perhaps the same value for some
atmospheric forcing variables.
- The data format used by the driver and the LSS is netCDF with the GDT
convention. Examples of forcing data can be found on the ORCHIDEE web
The current limitations of the interface
The implementation of the general interface meant that a number of
assumptions had to be made on the data management in the land-surface
scheme and the atmospheric model. To over come these assumptions more work is needed
but they are difficult to do for us as we do not know how other atmospheric models
of LSSs manage their data. Thus, if the data management is a problem
for your implementation of the interface you should contact us and see
how we can improve the interface.
All the input/output of the interface routine and the driver are done
with the public domain package IOIPSL which is being
developed at IPSL. This package is used by all models of the IPSL. If
you find our way of dealing with the data issues interesting do not
hesitate to download IOIPSL.
- We have chosen to have only a single call to the interface. The
first call will do all initializations of the interface and the LSS
without any computation.This allows to retrieve from the LSS variables
which are needed for the first calculation of the atmosphere (Albedo or
surface roughness for instance).
- The output of the diagnostic variables from the LSS is managed by
the LSS itself. This simplifies the interface as none of the
diagnostics need to transit through the interface. In the present
implementation it is done with the HIST module of IOIPSL which
produces netCDF files.
- Prognostic variables which need to be written into the restart
files are not passed out of the LSS. This means that the LSS will have
its own restart file and restart mechanism. This is a huge
simplification for the interface as we do not have to pass through
the calls all the prognostic variables. This list is strongly model
dependent and would kill any attempt of building an interface common
to a number of LSSs and atmospheric models. It is true that a flexible
restart mechanism which can manage separately and independently the
AGCM, OGCM and LSS variable is not a trivial thing but if you are
looking for inspiration you can take a look at how it is done in
- The sign convention used is historical and thus not logical. It
would be good to discuss it and establish a standard.
- Thanks to a F90 interface we made it possible to call the
land-surface interface with either 2D fields or vectors. Still we have
the limitation that the data should be on a rectangular grid. This
will need to be changed soon as we can not expect all atmospheric
models to run on rectangular grids.
- No attempt has been made here to ensure that universal constants
are consistent on either side of the interface. It is especially
important for the latent energy of evaporation that the same values
are used in the atmosphere and for the land-surface processes.
- The orography is not yet passed to the LSS. This will be needed
in the future either for surface roughness computations or snow
- The carbon flux is not yet included in the interface. Some work
is needed but it should not have a big impact on the interface as it
will be handled in the same way as the water flux.
Description of this implementation of the interface
In the following the different variables which are passed in the
driver dim2_driver.f90 to the interface
subroutine are presented.The call remains the same weather the driver
is used for a PILPS type or GSWP type experiment. It is only the size
of the variables which changes.
CALL intersurf_main &
& (istp, iim, jjm, nbindex, kindex, &
& dt, first_call, last_call, coupling, lon, lat, date0, &
! first level conditions
& zlev_vec, zlflu_vec, for_u, for_v, &
& for_qair, for_tair, for_eair, for_ccanopy, &
! Variables for the implicit coupling
& for_cdrag, petAcoef, peqAcoef, petBcoef, peqBcoef, &
! Rain, snow, radiation and surface pressure
& for_rain, for_snowf, &
& for_lwdown, for_swnet, for_swdown, for_psurf, &
! Output : Fluxes
& vevapp, fluxsens, fluxlat, run_off_tot, &
! Surface temperatures and surface properties
& tsol_rad, temp_sol_NEW, albedo, emis, z0)
- The time step of the
call. The LSS will go from istp to istp+1
- Julian date of the time at which istp was equal to
- The time interval in seconds between two values of
the time step (istp).
- Size of the grid in the longitude direction.
- Size of the grid in the latitude direction.
- Number of land points over which the LSS will
- This integer vector contains the list of land points over
which the LSS will have to run. This allows to pass through the
interface the entire forcing fields even if they contain ocean
or sea-ice points. The gathering of the input data and the
scattering of the output will be performed by the interface
- This flag (logical) says to the LSS that this
is the first call. This controls for instance the
initialization of the scheme.
- This flag
(logical) will tell the LSS that it will not be called again
during this run. It leads to the dumping of a restart file for
- This string
(CHARACTER(LEN=10)) will tell the LSS how it is being coupled to
the PBL. With this flag the solving of the energy balance can be
adapted to either an implicit, explicit or any other coupling
- The longitude of all
data points which are given to the LSS. The values are in
degrees. It is not the call to the interface which uses the
assumption of a rectangular grid, but the the interface
subroutine itself.It is caused by the transformation of the data
from a vector (iim*jjm) to a 2D matrix (iim,jjm).
- The latitude in degrees of all data points.
- The height in meters at which the atmospheric
forcing variables are provided. This variable has the same rank
and dimension as the forcing data. Thus we do not assume that
all forcing values are provided at the same height.
- The height in meters at which the fluxes will
be computed in the LSS and used in the atmosphere..
- The Eastward component of the wind in m/s at the
zlev_vec height. The forcing data can either be provided as a 2D
matrix (iim,jjm) or a vector (iim*jjm).
- The northward component of the wind at the zlev_vec level.
- Specific air moisture in g/g at the atmospheric reference level provided by zlev_vec.
- Air temperature in Kelvin at the hight given by zlev_vec.
- Enthalpy of the air.
- Carbon concentration (in ppmv) at the lower level of the atmosphere.
These variables are described in detail in the paper Polcher et al (1998).
- This variables
allows the atmospheric model or driver to impose a surface drag
for the temperature and moisture diffusion in the LSS. If the
largest value of this variable is zero then it is assumed that
the surface drag needs to be computed by the land-surface
scheme. Else the LSS will assume that the atmosphere computes
the surface drag using the surface roughness it provided at the
- The A coefficient explained in the appendix of the paper for temperature.
- The B coefficient for temperature.
- The A coefficient humidity.
- The B coefficient humidity.
- Rainfall in kg/m^2 per time step. (positive downward)
- Snowfall in kg/m^2 per time step.(positive downward)
- Incoming long-wave radiation in W/m^2.(positive downward)
- Net surface short-wave radiation at the
surface in W/m^2. This is the energy which the radiation scheme
has put into the surface and has to be used as is in the surface
energy balance. The albedo provided by the LSS is used for this
computation. (positive downward)
- This is downward radiation (W/m^2) which
should only be used to compute surface albedo. This is a purely
diagnostic variable and should not be used in place of for_swnet
else energy conservation through the interface can not be
guaranteed anymore.(positive downward)
- Surface pressure in Pa.
- The Evaporation in Kg/m^2 per time-step which takes
us from istp to istp+1. It is the total flux of water which goes
from the surface to the atmosphere. If the LSS has a surface
tiling then it is the average of the fluxes of all tiles as the
sub-grid information is not relevant for the atmosphere.(positive upward)
- The flux of sensible heat in W/m^2.(positive upward)
- The flux of
latent heat in W/m^2. In case of sublimation the relation
between evaporation and latent heat flux can be quite
complex. Here there is a potential for problems if the
atmosphere and the land do not use the same values for latent
heat of evaporation and sublimation. Work is needed as this
problem may cause loss of energy conservation at the
- The runoff along the coastline. Thus flux
will goes out of the LSS as it is needed by the ocean. The
grid-box runoff is LSS internal variable as it is not relevant
for the other components of the climate system. In other words
if the LSS does not contain a river routing scheme this field is
zero !(positive upward)
temperature of the surface in Kelvin. It does not have
necessarily the same value as temp_sol_NEW. It depends how the
LSS computes the outgoing long-wave radiation in its surface
energy balance. Its computation in the LSS will have to take
into account all the sub-grid information as the radiation
scheme of the atmospheric model will use it to compute a grid-box
averaged flux. The atmospheric model will have to apply an
time-averaging process on it if the radiation and LSS time-steps
- The albedo of the surface for the time-step
starting at istp+1. It will be used in the radiation scheme of
the atmospheric model which will return the net short-wave flux at the
- Surface emissivity of
the grid-box. This value has probably already been used in the
LSS for the computation of the outgoing long-wave radiation and
it will be needed by the atmospheric model so that it can
recompute the outgoing long-wave radiation correctly.
- The new
surface temperature. This is the value which is valid for the
time-step istp+1. The atmospheric model will probably only use
it for diagnostic purposes ( atmospheric stability for
- Surface roughness for
the grid-box. It will be needed by the atmospheric model to
compute the surface drag for temperature and moisture which will
be handed back at the next call of the interface. The
atmospheric may use it also for computing its own surface drag
Polcher, J., McAvaney, B., Viterbo, P., Gaertner, M.-A., Hahmann, A.,
Mahfouf, J.-F., Noilhan, J., Phillips, T., Pitman, A., Schlosser,
C.A. , Schulz, J.-P., Timbal, B., Verseghy, D. and Xue Y. (1998)
A proposal for a general interface between land-surface schemes and general circulation models.
Global and Planetary Change, 19, pp:263-278
Last modified: Thu Sep 21 13:50:26 CEST 2000