Implementing the ECOCLIMAP database in HIRLAM

First Step towards a Well Structured Surface Scheme Source Code

Han The

ECOCLIMAP: structure

landuse dataset

parameters per landuse class

LAI* Equations Parameter fields

*LAI implemented as a fixed parameter per land use class (10-days avg.)

ECOCLIMAP

Quick Implementation: Use the ECOCLIMAP software to create the

parameter fields to replace the Climate script

Disadvantages: Current HIRLAM code not suitable to handle all

parameters Future implementation of assimilated LAI not

possible

New Structure (F77-based; provisional) purpose

To cluster single fields into logical multi-dimensional arrays to:

reduce the number of function arguments simplify the global structure simplify the introduction of new fields and

layers

New Structure: storage (mostly) constant surface fields:REAL TOPO(NX,NY,NFLD)roughness lengths, tile fractions, LAI etc.

index fields:INTEGER ITOPO(NX,NY,MFLD)soil type and vegetation type index

soil physical quantities stored as 3-D arrays:soil moisture, soil temperature:SWI(NX,NY,NSOIL,NTYPE)

New Structure: access to separate fields

Field names are stored in include file TOPO.inc as parameters

TOPO.inc (provisional)

integer NFLD

c fields in TOPO array integer _LAI, _VEG, _ROOT, _RSMIN, _ALB, _SALB, + _Z0VEG, _Z0H, _SAND, _CLAY, _FIS, _TILE, + _SEA, _ICE, _BAR, _LOW, _HIGH, + _Z0ORO, _LAKE, _LAND, _Z0SEA, _TSCL, _SWCL

parameter (_SEA = 1, ! sea fraction + _ICE = 2, ! ice fraction... + _ALB = 8, ! grid albedo + _Z0H = 15, ! z0 for heat + NFLD = 15) ! total number of climate fields

c fields in ITOPO array integer MFLD parameter (MFLD = 1) integer _SOIL parameter (_SOIL = 1) ! soil type

integer NSOIL parameter (NSOIL = 2) ! number of soil layers<EOF>

New Structure: rules Never use the parameter value, e.g.:TOPO(1,1,_ALB) instead of TOPO(1,1,8)

At lowest level pass the required field and not TOPO as an argument, e.g.: CALL SURCOF_LAND(KSTART,KSTOP,NHOR,NLEV,JTYP,LHIRSN,+ TOPO(1,_Z0VEG),TOPO(1,_Z0ORO),ZWS,ZWSMX,ZWFC,+ ZITM,ZSNS,ZTS,ZVEG0,…

First five fields in TOPO(:,:,:) correspond to the tile fractions FRACI(:,:,:), i.e. you can pass TOPO as a function argument for the tile fractions (FRACI) instead of TOPO(1,1,1)

New Structure: storage

ITOPO replaces constructions like:

JQQ=NINT(((PFRACI(JL,JTYP)-RFRLIM)/(ZEPS+ABS(PFRACI(JL,JTYP)

& -RFRLIM))+1.)*0.5)

JSOL=NINT(PSOILI(JL,JTYP))*JQQ+1-JQQ

JSOL=MAX(1,MIN(JSOL,11))

by: JSOL = ITOPO(JL,_SOIL)

New Structure: code Modifications based on version 6.3.7 Numbers of files affected: 40

Other points of discussion concerning the recoding

Naming conventions Currently, there are no strict directions Many different names for the same variable Unclear coding and Reduncancy (unnecessary temporary arrays

and variables)

Naming conventionsGenerally, semantic-related naming conventions do not

improve coding except for external/global variables: where to find the variable declaration/initialisation

(e.g. reference to an include file) type (parameter, index, structure, etc.) usage (Hirlam code)

Generally, there is a need for stricter definitions of variable names e.g.: fixed names for global variables (passed through as function arguments) throughout the code

Naming conventions: examples

In SAPP.f:Land fraction is defined twice:FRLAND (function argument; not used)ZFRLAND (local variable; initialised and used

instead)

Constant parameter fields

Constant parameter fields: initialisation TXT.DAT: saturation point, field capacity,

wilting point INIISBA: fractions of sand and clay INI_VEG: veg parameters + WROUS, WVEG, WLAI INIPHY: tile fraction, vegetation type SUR2RAD: albedo

Constant parameter fields: checks INIPHY: most fields, tile fractions, vegetation

type ISBAH4: soil type and vegetation type, z0veg

JSOL=MAX(1,MIN(JSOL,11))

JVEG=MAX(1,MIN(JVEG,18))

TQUV: roughness length DO I=1,NHOR

Z0(I)=MAX(Z0(I),5.E-4)

Z0(I)=MIN(Z0(I),3.)

ENDDO

SAPP: land fraction SUR2RAD: vegetation type

Constant parameter fields: tile fractions

Constant parameter fields: tile fractions

In HDF-file: sum of fraction equals 1 (within single precision)With conversion to GRIB precision is lost. Internal check is always required before usageCurrently, this happens in INIPHYIn the surface analysis routines there is no check. As a result the land masks in AN en FC differ

Constant parameter fields: tile fractionsin ANALYSIS:

FIELD PARAMETER INDEX LONG. LAT. AVERAGE STD. DEV.

FRACTION OF LAND (1=LAND; 1 -41.61 11.95 0.461639 0.475845

in FORECAST:

FIELD PARAMETER INDEX LONG. LAT. AVERAGE STD. DEV.

FRACTION OF LAND (1=LAND; 179 -13.63 26.51 0.449246 0.479794

Constant parameter fields: I/OThere must be a single API routine to read/write for both Hirlam and Hirvda:

GETDAT/PUTDAT

All consistancy checks must do done within GETDAT

The user must have the guarantee that the fields throughout the code is obtained from GETDAT

Function declarations and calls

Function declarations and argument lists: examplesNot readable (representative):C----------------------------------------------------------------------- SUBROUTINE ACVEG ( KIDIA,KFDIA,KLON,KLEV,C-----------------------------------------------------------------------C - INPUT 2D . * PAPRSF,clrb PFRSO, * SSWNET, PQ,PQSAT,PT,clreC - INPUT 1D . * PD2,PITM,PIVEG,clr PALB, * PLAI,PNEIJ,PVEG,PRSMIN, * PCHROV,PGWDCS,PWFC,PWSAT,PWL,PWWILT,PWP,PQSATS,C - OUTPUT 1D . * PHQ,PHTR,PHU,PHV,PWLMX,C - TEMPORAIRE 1D . * PZDELTA,PZRSTO )

Function declarations and calls: examplesNot useful (I: integer; R real):

SUBROUTINE LNDTQ2( KMONTH, KDAY,

I KLON , KLAT , KLEV , KTYP

R , PAHYB , PBHYB

...

Random:

SUBROUTINE POSTPP(MYPE

$ ,NLON_GLOBAL ,NLAT_GLOBAL

X ,NLEVML, LTYPML,ALEVML,NWMOML,IWMOML

X ,NSL , LTYPSL, IWMOSL, ALEVSL

X ,LPHYS , LOMEGA

$ ,NLEV , NLON , NLAT , NTYP

...

Function declarations and calls: proposed format SUBROUTINE ACVEG ( r KIDIA, KFDIA, KLON, KLEV, PAPRSF, r SSWNET, PQ, PQSAT, PT, PD2, PITM, PIVEG, r PLAI, PNEIJ, PVEG, PRSMIN, r PCHROV, PGWDCS, PWFC, PWSAT, PWL, PWWILT, PWP, PQSATS, w PHQ, PHTR, PHU, PHV, PWLMX, m PZDELTA, PZRSTO)

r input (constant/readable): must be initialised before call; no local copy needed;

w output (writable): no initialisation needed; making a local copy in calling function depends on usage;

m input/output (modified): initialised; local copy depending on usage;

Implementation of the above rules

Example of variable life cycle: Original codeSWI: surface layer soil water indexDSWI: surface layer soil water tendencyCALL PHYS(...,SWI,...,DSWI,...) WSWI = SWI ! WSWI: local variable DSWI = 0 CALL ISBAH4(...,SWI [PSWI],...,DSWI [PDSWI],...) PSWI = MIN(PSWI, 0.5) ZWS = PSWI*RD1*GCONV ! unit conv PSWI; ZWS: local variable ZDWS = 0 ! local variable CALL SURTEND_LAND(...,ZWS [PWS],...,ZDWS [PDWS],...) ZSWP = PWS + calculated change ! local variable ZDSW = ZSWP - PWS ! local variable PDWS = ZDSW*ZRDT/ZCONS10 ! unit conversion of tendency END SURTEND_LAND PDSWI = ZDWS END ISBAH4 WSWI = WSWI + DTVDIF*DSWI DSWI = (WSWI - SWI)/ZDTIMEEND PHYS

Improved codem/c SWI: surface layer soil water index

w DTSWI: surface layer soil water tendency

CALL PHYS(...,SWI,...,DTSWI,...)

CALL ISBAH4(...,SWI,...,DSWI,...)

SWI = MIN(SWI, 0.5)

CALL SURTEND_LAND(...,SWI,...,DWSI,...)

DSWI = calculated change ! in correct units

END SURTEND_LAND

END ISBAH4

DTSWI = DSWI/ZDTIME

END PHYS

Gain: removal of 12 temporary fields:WSWI(NHOR,NTYP), DSWI(NHOR,NTYP), ZWS(NHOR), ZDWS(NHOR)

similarly for second soil water layer simplified code

Life cycle of variables where are the variables initialised where are the variables modified what are the modifications pathways of the variables

Summary 2D fields are clustered into 3-dimensional arrays

to improve structure and enhance future flexibility Documented naming conventions based on

functionality rather than semantic meaning of the variable

Well structured I/O of climate fields is required (GETDAT)

Description of the life cycle of the time-dependent variables must be included in the documentation