You are on page 1of 94

Météo-France

Centre National de Recherches Météorologiques

ARPEGE-Climat Version 5.2

User’s Guide

October 2011
Contents

1 Tools 3
1.1 Before we start . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Preparing an experiment . . . . . . . . . . . . . . . . . . . . . 6
1.3 Launching an experiment . . . . . . . . . . . . . . . . . . . . 8

2 Namelist settings 11
2.1 General principle . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2 Important atmophere namelists . . . . . . . . . . . . . . . . 11
2.2.1 NAERAD . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.2 NAMARPHY . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.3 NAMCT0 . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.4 NAMCT1 . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.5 NAMDIM . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2.6 NAMDPHY . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2.7 NAMDYN . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2.8 NAMFPC . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.9 NAMGEM . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.10 NAMMCC . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.11 NAMPAR0 . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.12 NAMPAR1 . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.13 NAMPHY . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.14 NAMPHY0 . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.15 NAMPHY1 . . . . . . . . . . . . . . . . . . . . . . . . 20
2 CONTENTS

2.2.16 NAMPHY2 . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.17 NAMRAD15 . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.18 NAMRGRI . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.19 NAMRIP . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.20 NAMSCEN . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.21 NAMTOPH . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2.22 NAMVV1 . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3 Important SURFEX namelists . . . . . . . . . . . . . . . . . 22
2.3.1 NAM_PGD_GRID . . . . . . . . . . . . . . . . . . . 22
2.3.2 NAMDIM . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.3 NAMRGRI . . . . . . . . . . . . . . . . . . . . . . . . 23
2.3.4 NAMGEM . . . . . . . . . . . . . . . . . . . . . . . . 23
2.3.5 NAM_ISBAn . . . . . . . . . . . . . . . . . . . . . . . 23
2.3.6 NAM_SGH_ISBAn . . . . . . . . . . . . . . . . . . . 23
2.3.7 NAM_SEAFLUXn . . . . . . . . . . . . . . . . . . . . 24
2.3.8 NAM_WATERFLUXn . . . . . . . . . . . . . . . . . 24
2.3.9 NAM_DIAG_SURF_ATMn . . . . . . . . . . . . . . 24
2.3.10 NAM_DIAG_SURFn . . . . . . . . . . . . . . . . . . 24
2.3.11 NAM_WRITE_DIAG_SURFn . . . . . . . . . . . . . 25
2.4 Modifying namelists . . . . . . . . . . . . . . . . . . . . . . . 25

3 Launching the model 27


3.1 General principle . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 Script content . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.2.1 Setting unix variables . . . . . . . . . . . . . . . . . . 28
3.2.2 Collecting the ingredients to run the model . . . . . . 30
3.2.3 Running the model . . . . . . . . . . . . . . . . . . . . 31
3.2.4 Saving the results on the silo . . . . . . . . . . . . . . 31
3.2.5 Preparing the next run . . . . . . . . . . . . . . . . . . 32
CONTENTS 3

4 Post-processing 33
4.1 The diagnostic monitor . . . . . . . . . . . . . . . . . . . . . . 33
4.2 Monthly means . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.3 Global time series . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.4 Hemispheric time series . . . . . . . . . . . . . . . . . . . . . 38
4.5 Local time series . . . . . . . . . . . . . . . . . . . . . . . . . 40

5 Pre-processing 43
5.1 Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.2 Climatology files . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.3 Initial conditions for the atmosphere . . . . . . . . . . . . . . 45
5.4 Initial conditions for the surface . . . . . . . . . . . . . . . . . 46

6 Coupling with the ocean 49


6.1 Basic script . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.2 Changing coupling frequency . . . . . . . . . . . . . . . . . . 51
6.3 Changing model resolution . . . . . . . . . . . . . . . . . . . 51

7 Compiling the model source 53


7.1 Description of the source code . . . . . . . . . . . . . . . . . . 53
7.1.1 Ancillary libraries packages . . . . . . . . . . . . . . . 53
7.1.2 GmkPack toolbox . . . . . . . . . . . . . . . . . . . . 54
7.1.3 Arpege-climat source code . . . . . . . . . . . . . . 54
7.2 Installation of the different tools and libraries . . . . . . . . . 55
7.2.1 Ancillary libraries packages . . . . . . . . . . . . . . . 55
7.2.2 GmkPack toolbox . . . . . . . . . . . . . . . . . . . . 60
7.3 Compiling Arpege-climat with GmkPack . . . . . . . . . . 62
7.3.1 User environment . . . . . . . . . . . . . . . . . . . . . 63
7.3.2 Creation of reference packs . . . . . . . . . . . . . . . 64
7.3.3 Creation of developer packs . . . . . . . . . . . . . . . 65
7.3.4 GmkPack commands . . . . . . . . . . . . . . . . . . . 67
7.4 Compilation of auxilliary binairies for SURFEX . . . . . . . 67
4 CONTENTS

7.4.1 Creation of PGD and PREP binaries . . . . . . . . . . 67


7.4.2 Creation of fa2gb_arp and xtrsfc binaries . . . . . . . 68
7.5 Source code and files . . . . . . . . . . . . . . . . . . . . . . 68
7.6 Other sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

8 Adding variables to the model 71


8.1 Adding a GFL variable . . . . . . . . . . . . . . . . . . . . . . 71
8.1.1 General presentation of GFL . . . . . . . . . . . . . . 72
8.1.2 Step-By-Step . . . . . . . . . . . . . . . . . . . . . . . 75
8.1.3 Step 1: definition and setup to read/write the GFL on
Arpege file . . . . . . . . . . . . . . . . . . . . . . . . 76
8.1.4 Step 2: definition and setup to add the GFL variable . 77
8.1.5 Step 3: passing a variable stored in GFL structure to
the physics . . . . . . . . . . . . . . . . . . . . . . . . 80
8.2 Adding a Surface variable . . . . . . . . . . . . . . . . . . . . 83
8.2.1 Looking at surface_fields.F90 . . . . . . . . . . . . 83
8.2.2 Looking at su_surf_flds.F90 . . . . . . . . . . . . . 84
8.3 Using Free-use Upper Air and Surface fields . . . . . . . . . . 86
1
Tools

1.1 Before we start

We describe in this guide the use of Arpege-climat on the computers of


Météo-France. In this guide, all programs except the model itself run on
Linux machines. However, the model can run on different IBMs or NECs as
well as on PCs, so the question of its portability is not a big issue.
Version 5 of Arpege-climat exists in 3 sub-versions. Version 5.1 has its
own user’s guide. It is designed to be used in non-coupled mode, in particular
for the Cordex regional experiment. Version 5.2 has been designed especially
for CMIP5 experiment and, in a lighter configuration, to the Météo-France
system 4 for Eurosip. For this reason, the present guide will focus on the
ocean-atmosphere coupled version. Information about the atmosphere-only
simulation can be found in Version 5.1 user’s guide. Version 5.3 is not coupled
and does not include Surfex. This version is as close as possible to the
operational NWP version (in 2011). It is designed to serve as a base version
for building Version 6, and thus is reserved for internal use in EAC team. For
this reason, only computer and climatological documentations are available.
For a basic use of Version 5.3, Version 5.1 user’s guide should be enough.
In addition, a short guide for Cordex simulations updates some aspects of
preprocessing no longer accurate in Version 5.1 and not dealt with in this
guide.
Model Arpege-climat is installed on the computer tori (NEC SX8) of
Météo-France. The model must be run there and the program libraries are
found there. The workstation dedicated to the pre- and post-processing of
the model model is sxclimat (a Linux server). On the other hand the mass
storage is done on the machine cougar (computer ORIGIN 3000 coupled to
6 1. Tools

silos STORAGETEK). The heavy part of the model output is stored there.
This machine has a restricted unix shell and is mostly accessed through ftp.
A particularity of tori which makes the scripts harder to read than with
the previous computers is that it contains two families of machines. The
family toritx is based on Linux servers and has interactive access. A job
submitted to tori is generally sent to it first. One can compile and do ftp
access, but not launch executable files. The family torisx is based on NEC
vector processors with possibility of parallel computation. The model and
other executable files run on it, but compilation or ftp access are not allowed.
The operating system is a NEC unix (very close to but not identical with
Linux). The two families share a permanent ($HOME) and a semi-permanent
($WORKDIR duration at least 24 h) disk space. A separate documentation (in
French) on the use of tori is available on the Arpege-climat web site.
To facilitate the preparation of multi-step scripts (typically one step on
toritx, one on torisx and one on toritx) a product named MTOOL has
been made available. It consists of a special syntax (#MTOOL...lines) and a
script pre-processor, which is used as:
mtool_filter.pl job
where job is the name of the script file. This command modifies a script on
toritx and submits it to toritx or torisx according to the lines inside the
script. In order to allow this operation, you must add to your configuration
file (e.g. .profile):

export MTOOL_ROOT=~mrpm631/public/mtool
PATH=${PATH}:$MTOOL_ROOT/bin
export PWD=$(pwd)

You must also create a tmp directory on your home directory.


Although most scripts on tori use only tori files and scripts on sxclimat
use only sxclimat files (both types access cougar files) it is useful to allow a
bridge between the two machines, by adding to the .rhosts file of sxclimat
the line:
tori.meteo.fr tori_user
and to the .rhosts file of tori the line:
sxclimat.cnrm.meteo.fr sxclimat_user
where machine_user is your login name (which may be different on the
two machines). The output of your job returns to the directory from which
you launched the submission, if everything is OK. If your job fails for some
reason, you will never receive any output where you expect it. This is a
specificity of the MTOOL environment. You have to go to:
/utmp/ftdir/tori_user /mtool/submit
1. Tools 7

where a directory corresponding to your job has been created and where you
can find the output of your different steps (until your job crashed). This
directory is cleaned up after a couple of days. For more details about MTOOL,
a specific documentation (in French) is available on the Arpege-climat
web site.
As far as transfers to or from cougar are concerned, you are firmly encour-
aged to use on tori the commands ftget and ftput which allows transfers
by ftp without giving the password. It is thus necessary to provide to tori
the password of cougar (and to update it). For that, it is necessary to be
connected on tori and type the command:
ftmotpasse - u user -h cougar-tori
This operation will create on tori a crypted file .ftuas. There is noth-
ing similar on sxclimat. Some scripts will work only if you have created a
.netrc file with the syntax:
machine cougar login user password pwd
It is very important, for security reasons, that your password on cougar is
different, because it is vulnerable (not crypted as in .ftuas). On the other
hand, an illegal access to cougar is less harmful, because this machine al-
lows only a restricted shell. In the worst case, the pirate will corrupt or
destroy your archives or saturate your quota. Note that you will never have
to change this password, and then never to edit either .ftuas or .netrc.
On tori and sxclimat you have to change your password regularly.
As version 5.2 is designed for century-long simulations, or for hundreds of 4-
to 6-month-long hindcast, you cannot avoid to install the automatic launch-
ing system. A (French) documentation of this software is available on the
Arpege-climat web site. Essentially, you must add the line in your tori
configuration file (.profile)

PATH=~mrga562/relances/procs/procs.v2.2c:${PATH}

You must have a $HOME/relances directory with one sub-directory by exper-


iment. In this sub-directory you must have a ${EXPID}_his which is named
the history file. The experiment is launched by:
relan $EXPID
A typical run of Arpege-climat is one month simulation. However, for
reasons of time spent in queueing, it might be interesting to loop inside the
script so that you can run several months once your job is in the machine.
You just need to add a file named substeps in your $HOME/relances/$EXPID
directory, based on one line per step (one step=one year typically), each line
containing NSTEP=nn (nn=12 typically). If you combine automatic launching
and variable step length in sub-steps file you must be careful, because the
automatic launching assumes that the current value of NSTEP was the same
8 1. Tools

in the previous runs. So you have to change the parameters in the history
file of your automatic launching each time you change NSTEP. The safest way
to work is to keep NSTEP constant. You must also be careful if you do not
start on January 1st. In order to keep the script as simple as possible, it
does not take into account the cases where variable MM is above 12.
To use the model, it is therefore first necessary to open an account on the
three machines referred to above. For the users outside of the domain
meteo.fr, it is necessary also that the network of Météo-France, through
the fire-wall parme, recognizes the machine from where connection is issued:
to this purpose, indicate in the authorization form the IP addresses of the
workstations you wish to use. The request for access authorization is to be
renewed every year spontaneously and the procedure takes a couple of weeks.
When all that precedes is carried out, you are ready to launch the model. In
Chapter 2, you will learn how to prepare a configuration file named namelist
and a surface configuration file named EXSEG1.nam. Then, in Chapter 3
you will edit and launch the script which produces the coupled integration of
the model. In Chapter 4 you will learn how to exploit the experiment that
you realized by preparing files for your favorite graphic software from the
various files created by Arpege-climat during integration. In Chapter 5
you will learn how to prepare files to run Arpege-climat in a different
geometry from the standard tl127l31r or from the few existing ones as well
as how to prepare the surface files. In Chapter 6, you will learn a little
more on ocean-atmosphere coupling. Note that the documentation on the
coupling software OASIS, the sea-ice model GELATO and the ocean model
NEMO are available on the web page of ASTER team. Finally, Chapter 7
will explain how to compile the model from scratch or to modify the model
with your own routines and Chapter 8 will teach you how to modify the
model to add extra variables or diagnostics. But before, let us see what you
will not learn in this handbook. Then a summary of what is at your disposal
for a basic use of the model is given.

1.2 Preparing an experiment

When one deals with user-friendly public software, one starts by downloading
a file in the format .tar.gz. Once the file expanded, one finds a README
file, a directory doc containing files in the format .ps, .pdf, .html or .tex
and other files about which one does not have to worry initially. Reading
the README file learns that it is necessary to modify and then to launch a
file Configure which will create a file Makefile automatically. Then one
launches in one or more steps the command make. And the software is
installed. One creates an icon on his desktop, and one is offered a beautiful
graphic interface with menus, buttons and input windows. There is nothing
1. Tools 9

any more to do, but to read the documentation if one wants to exploit more
than 10% of the possibilities of the software.
Model Arpege-climat does not obey this scheme. It is addressed to qual-
ified and tough researchers. First of all, a license agreement with Météo-
France is necessary to install Arpege-climat on a machine external to the
site. The model was compiled on IBM (at ECMWF). To compile it on an-
other machine, one needs the help of qualified computer specialists, because
the assistance of Arpege-climat team is limited to the supply of the source
code (once the agreement is signed) and standard tools for compilation which
you will have to adapt to your system. In addition to the library of the model
itself, you need an auxiliary library (xrd), a library of spectral transforms
(tfl), and a library of message passing (mpi/mpe). Although it has been
highly simplified in the present version, this kind of work may take weeks,
and possibly months if you want to implement parallel computations on an
odd machine.
It results from what precedes that the standard use of model Arpege-
climat consists of running an already existing executable file. Contrary
to the models designed in the 1980’s, no option requires recompiling the
model. The namelists authorize most configurations. Moreover, an average
user can, with a minimum of assistance from Arpege-climat team, create
a new executable file by modifying and recompiling some subroutines. You
can thus plan to replace a physical parametrization by another one, a work
taking between one day and six months according to the input-outputs of the
new parametrization. However these operations are not described in details
in this guide.
The model is not reduced to a single a.out and a namelist. You need
files of initial conditions for the four components (ocean, sea-ice, atmosphere
and land) of the system, plus initial files for the coupler. Here we focus
on the atmospheric component. In order to update each month boundary
conditions you need extra data (e.g. CO2 concentration, aerosols). The
standard geometry is spectral triangular truncation to wave-number 127 with
reduced linear Gaussian grid with 31 vertical levels1 which yields a uniform
resolution of about 160 km, but a few others are available from Arpege-
climat team, e.g. a regional version with 50 km horizontal resolution over
Europe and 300 km in the southern Pacific2 . In Chapter 5 you will learn
how to prepare the necessary files. However we do not explain here how to
run seasonal forecasts by preparing initial condition from ECMWF analyses.
This kind of expertise requires that you fully master the simulation and
validation of present climate. Nevertheless, for an occasional use, Arpege-
climat team can provide the necessary files. For example if you wish to
1
abridged to tl127l31r
2
named mediash_l31
10 1. Tools

start the run the day of your birth with a stretched geometry having for pole
your birthplace, you will be provided within a reasonable delay with the file
of initial conditions and the 12 files of boundary conditions.
Finally, we do not describe here how to plot your data. This is a long
operation if you want to get beautiful results. But from our experience,
every user has his favorite graphical software, which generally requires data
in a specific format (European standard as Grib or US-originated standard as
NetCdF). Arpege uses its own storage standard which is not compatible with
graphical softwares, so we provide tools to transform elaborated diagnostic
in universal standards (Ascii, ieee) and let people free of their choice.
However, if you are new-comer and lazy, do not re-invent the wheel: ask
your colleague (or the author of this documentation) to provide ready-to-
use but not-simple-to-customize scripts to get a first look at your data on
your Linux PC. The climatological documentation provides examples of plots
obtained with GMT software.

1.3 Launching an experiment

Once the passwords are validated (the first password is often an out-of-date
password to change at the first connection) and are crypted (by ftuas) or
simply entered (by netrc), you can use the tools below:

• the pdf files of documentation on:


sxclimat:/eac9/deque/V5.2/documentation/
All this information and more can also be accessed on-line at
http://www.cnrm.meteo.fr/gmgec/arpege-climat/ARPCLI-V5.2/index.html
In particular this site gives access to the model source as well as to the
model tree. The access to the original source is not public and requires
a license (see above).

• post-processing unix scripts (see Chapter 4) on:


sxclimat:/eac9/deque/V5.2/postprocessing
intended for the exploitation of an experiment. These files, like the
model script, contain an editable part located at the beginning.

• similarly pre-processing unix scripts (see Chapter 5) on:


sxclimat:/eac9/deque/V5.2/preprocessing

• the namelists (see Chapter 2) on:


tori:/cnrm/gc/mrga/mrga561/namelist/
which make it possible to specify the options for the execution of an
integration of the model.
1. Tools 11

• the model unix scripts (see chapter 3) on:


tori:/cnrm/gc/mrga/mrga561/V5.2/
These files carry out an integration of the model on tori in a given
geometry with or without automatic rerun.

• initial conditions files on:


tori:/cnrm/gc/mrga/mrga561/restart/

• boundary conditions files on:


tori:/cnrm/gc/mrga/mrga561/bcond/

• sources of the model on:


tori:/cnrm/gc/mrga/mrga561/compil/arp5.2/
tori:/cnrm/gc/mrga/mrga561/compil/aux/

• sources of some binaries (not the model itself):


tori:/cnrm/gc/mrga/mrga561/compil/misc/

There are other utilities developed by Arpege-climat team. They are


little documented, require a little edition to be used by another one than
their author, and are in general not public (in unix sense). For these three
reasons, a preliminary dialog is necessary with Arpege-climat team. But
before starting a work of more than one half-day (which in fact reveals to
take several weeks), it is better to ask whether something similar does not
already exist.
12 1. Tools
2
Namelist settings

2.1 General principle

There is one namelists file for the atmospheric setup and one namelists file for
the surface configuration. The file of namelists for the atmosphere makes it
possible to carry out simulations with Arpege in various configurations and
various resolutions without having to recompile anything. Each namelist
breaks up into a parameter list. One often says “the namelist” for “the file of
namelists” . There are 137 namelists read by the model in configuration 1
(direct model run), with 323 switches prescribed (amongst more than 2000).
Indeed all switches have a default value defined in the code before reading
the file. Thus if switches are missing in the file, the model runs nevertheless.
It is necessary however that the 137 namelists are present, even possibly
empty.
There exists a way of circumventing the edition of a namelist in the case
of simple modifications. It consists of passing as argument (in the line con-
taining the name of the executable file of the model) key words which take
precedence over the switches of the file. This approach is dis-advised for
climatic simulations. It is opposite to the founding principles of Arpege.
Indeed, if you save the namelist associated with your experiment, you are
sure to be able to start again, extend, or modify in a controlled way this
experiment. However it can be found in other configurations (e.g. 927, see
Chapter 5).

2.2 Important atmophere namelists

You will find hereafter comments on some switches present in the standard
file. For the others, it is necessary to browse the code documentation.
14 2. Namelist settings

2.2.1 NAERAD

LRRTM .T. if RRTM is used for radiation transfer

NRADLP Index for diagnosis of liquid cloud effective radius

NSW Number of shortwave spectral intervals.

RCCO2 Concentration in CO2.

RCFC11 Concentration in CFC11.

RCFC12 Concentration in CFC12.

RCH4 Concentration in CH4.

RN2O Concentration in N2O.

2.2.2 NAMARPHY

LMSE .T. when using SURFEX

CCOUPLING type of coupling with SURFEX : E for explicit coupling ,


I for implicit coupling

2.2.3 NAMCT0

LCORWAT Correction of precipitation for water conservation for long cli-


mate run.

LECMWF Running IFS instead of Arpege; changing it implies changing


many other switches.

LFBDAP If .T., diagnostics are written on the history file; in any case,
these diagnostics are backuped in other files.

LFDBOP If .T., diagnostics are written in MARS. For ECMWF only.

LFPOS Activation of Full-Pos post processing.

LREGETA Option for calculations on the half-levels in the semi-Lagrangian.

LSLAG Semi-Lagrangian advection.

LSPRT Virtual temperature is a spectral field (option for IFS only).

LTWOTL Discretization on two time levels instead of leapfrog. Only for


the semi-Lagrangian advection.
2. Namelist settings 15

NCONF Value 1 corresponds to an integration of the model in primitive


equations. Other values correspond to pre- or post processing of the
forecast, or simplified versions of the model; changing it implies chang-
ing many other switches.

NFRHIS Frequency for archiving history files, in time steps (if > 0) or
hours (if < 0). It is necessary to archive the last time step if one wants
to continue integration.

NFRSFXHIS Frequency for archiving SURFEX Full-pos files, in time steps


(if > 0) or hours (if < 0). It is necessary to archive the last time step
if one wants to continue integration.

NFRPOS Frequency for Full-Pos files archiving.

NHISTS Choice of specific time steps for saving the history files. The
backup takes place for all the multiples of NFRHIS (including 0) when
NHISTS(0)=0, which corresponds to the standard case. If you wish
to save only some occurrences, you will take NHISTS(0) different from
zero: then, you store only the time steps NFRHISxNHISTS(1), NFR-
HISxNHISTS(2), . . . , NFRHISxNHISTS(NHISTS(0)). This mecha-
nism is found in all frequencies of archiving or printing.

NSFXHISTS Choice of specific time steps for saving the SURFEX Full-pos
files, analogous to NHISTS

NPOSTS Choice of the time steps for saving the Full-Pos files.

NPRINTLEV Level of detail in the printed diagnostics.

NSTOP Number of time steps in the integration. It is to better take a


multiple of the day to obtain all the files of post-processing (e.g. if
∆t = 30 min take NSTOP multiple of 48). All the other periods
expressed in a number of time steps (for example NFRPOS) should be
divisors of NSTOP.

2.2.4 NAMCT1

LRFILAF If .T., stdout contains a description of all the FA files opened.

N1SFXHIS postprocessing of SURFEX files if 1 ( default 0)

2.2.5 NAMDIM

NCMAX Spectral truncation, see NSMAX.

NDGLG Number of latitudes.


16 2. Namelist settings

NDLON Number of longitudes.

NFLEVG Number of vertical levels.

NPROMA Number of grid points in the same task; allows vectorization of


the loops of physics. If < 0, it is recalculated.

NSMAX Spectral truncation. Parameters NCMAX, NTMAX and NX-


MAX take the same value in the climate version. Changing resolution
implies changing initial and boundary conditions files.

NTMAX Spectral truncation, see NSMAX.

NXMAX Spectral truncation, see NSMAX.

2.2.6 NAMDPHY

LTPROF When activated, two additional levels of deep soil temperature


are considered. Must be desactivated when SURFEX is used

NTOZ2D If you activate the parametrization of ozone, the pair (NTOZ2D,


NTOZ3D) is (1,0) if the fields 2d are in memory, or (0,1) if the fields are
3d in memory. The option 3d needs more memory, but it is necessary
in case of rotation of the poles. If no ozone, set (0,0).

NTOZ3D See NTOZ2D.

NVCLIS Number of ozone variables: 1 if you use an ozone 3D climatology,


7 if the parametrization of the photochemistry of ozone is activated.

2.2.7 NAMDYN

BETADT Coefficient given to the semi-implicit part (BETADT=0 is pure


leapfrog).

LADVF If .T., advection of the term of implicit Coriolis in the semi-


Lagrangian.

LFREIN Additional diffusion when the model becomes unstable.

LQM* Quasi-monotonous interpolation in the semi-Lagrangian.

LSETTLS Stable discretization of vertical interpolating semi-Lagrangian


scheme.

NITMP Number of iterations for the research of the medium point in the
semi-Lagrangian.
2. Namelist settings 17

N*LAG Option of interpolation in the semi-Lagrangian: (1) interpolation


of the member of right-hand side at the medium of the trajectory;
(2) average of the member of right-hand side along the trajectory, the
part corresponding to the origin point added at the t − ∆t term; (3)
average of the member of right-hand side along the trajectory, the part
corresponding to the origin point linearly interpolated.

NSREFDH Effective truncation in stratosphere for spectral horizontal dif-


fusion.

RCMSLP0 Tuning of the term of Tanguay-Ritchie for the continuity equa-


tion in the semi-Lagrangian.

RDAMP* Variable-dependent factor for horizontal diffusion (0 means no


diffusion for that variable).

REPS* Coefficients of the time filter.

REXPDH Exponent of the horizontal diffusion (typically 6).

RRDXTAU General coefficient of horizontal diffusion (0 means no diffu-


sion).

SITR Linearization temperature for the semi-implicit.

SLEVDH Transition between the tropospheric and the stratospheric diffu-


sion: dimensionless lower level.

SLEVDH2 Transition between the tropospheric and the stratospheric dif-


fusion: dimensionless upper level.

TSTEP Time step (in seconds). To be modified when resolution is changed


and the model becomes unstable. Its modification requires a modifi-
cation of the frequency of the outputs of the model (which is managed
by the script).

VESL Un-centering factor in the semi-Lagrangian.

XIDT New un-centering factor in the semi-Lagrangian.

2.2.8 NAMFPC

CFP2DF Names of the two-dimensional dynamic fields treated by Full-Pos.

CFP3DF Names of the three-dimensional dynamic fields treated by Full-


Pos.

CFPCFU Names of accumulated fluxes treated by Full-Pos.


18 2. Namelist settings

CFPFMT Type of output grid for Full-Pos. If GAUSS, one stores in grid
point. If MODEL, one stores in spectral coefficients.

CFPPHY Names of the surface fields treated by Full-Pos.

CFPXFU Names of the boundary layer fields treated by Full-Pos.

LFPSPEC Spectral fields processing.

NRFP3S Model levels treated by Full-Pos.

RFP3P Pressure levels treated by Full-Pos.

2.2.9 NAMGEM

NHTYP If = 0, you will use a rectangular grid; if = 2, you need to specify


a reduced grid in NRGRI.

NSTTYP NSTTYP=2 if the pole is moved. The default is 1 (no rotation).

RLOCEN Longitude of the pole.

REFLKUO Mesh size (m) below which moisture convergence is reduced


in the Bougeault convection scheme.

RMUCEN Sine of the latitude of the pole.

RNLGINC Is 0 with a linear grid, 1 with a Gauss grid.

RSTRET Stretching factor.

2.2.10 NAMMCC

LCURR If .T. Ocean currents used in the computation of wind stress

LGELATO If .T. Fluxes sent to GELATO

LMCC01 If .T. you read the boundary conditions on two monthly files.
Attempts to reproduce the behavior of versions 3 and before.

LMCC02 If .T., the sea-ice is considered as land and its temperature is


calculated at each time step.

LMCC03 If .T., the model calls the coupler Oasis.

NOACOMM Method of Oasis communication

NFRCPL Coupling frequency with the Ocean Model


2. Namelist settings 19

2.2.11 NAMPAR0

NOUTPUT Level of verbosity: nothing (0), one processor (1), all proces-
sors (2).

NPROC Total number of processors.

2.2.12 NAMPAR1

NSTRIN Number of processors which read the input files.

NSTROUT Number of processors which write the output files.

2.2.13 NAMPHY

LAERODES Key to use DESERT aerosols

LAEROLAN Key to use LAND aerosols

LAEROSEA Key to use SEA aerosols

LAEROSOO Key to use SOOT aerosols

LAEROSUL Key to use SULFATES aerosols

LAEROVOL Key to use VOLCANO aerosols

LCONDWT Prognostic liquid and solid water.

LCVPP Diffusion to mimic shallow convection.

LCVRA Deep convection (operational cycle 32).

LCVRAV3 Deep convection (frozen in climate versions 3 and 4).

LDIFCONS Vertical diffusion of Betts variables.

LECT Turbulent kinetic energy scheme one half-levels.

LFGEL Freezing in the total soil reservoir.

LGWD Orographic gravity wave drag.

LGWDC Convective gravity wave drag.

LHMTO Interpolations in the surface boundary layer.

LHUNEG Correction of negative moistures by borrowing in the lower lev-


els. It should be noted that all parametrizations tolerate negative
moistures in input (they introduce possibly max(, q)).
20 2. Namelist settings

LMLH quadratic mixing length profile in the PBL.

LMPHYS Activation of Météo-France physics (do not expect to run in


adiabatic mode just by switching it off).

LNEBCO Convective cloudiness.

LNEBN Total cloudiness by relative humidity.

LNEBR Total cloudiness by statistical scheme.

LNEIGE Ice phase in precipitations.

LOZONE Photo-chemistry of ozone.

LPBLE Top PBL entrainment (Grenier scheme).

LRAY ACRANEB radiation.

LRAYFM RRTM or FMR radiation (according to NAERAD)

LRAYFM15 RADINT15 radiation, version of FMR frozen to cycle 15.

LRNUMX Cloud overlap (maximum if .T., random otherwise); unused in


LRAYFM15.

LRRMES Mesospheric drag.

LSFHYD Hydrological budget.

LSNV Snow scheme (in addition to ISBA).

LSOLV Soil-vegetation scheme ISBA.

LSTRA Stratiform precipitation by supersaturation.

LSTRAS Stratiform precipitation by statistical scheme.

LTHERMO Thermodynamic state of the atmosphere.

LVDIF Vertical diffusion.

NDPSFI Variable mass option: if 1, one varies the atmospheric pressure


according to the water budget.
2. Namelist settings 21

2.2.14 NAMPHY0

AHCLPV Boundary layer depth for the calculation of mixing length; if


= 0, this depth is calculated.

ALMAV Asymptotic mixing length for the vertical diffusion.

ECMNP Minimum depth for precipitating convective cloud.

GWDCCO Coefficient for convective gravity wave drag.

GWDCD Form coefficient for the orographic gravity wave drag.

GWDLT Coefficient for the orographic lift effect.

GWDSE Coefficient of intensity for the orographic gravity wave drag.

HUCOE Coefficient for the cloud empirical scheme.

HUTIL Coefficient for the cloud empirical scheme.

QSNEBC Coefficient for the calculation of convective cloudiness.

RICRLM Parameter of the profile of mixing length.

SCO Precipitation threshold in the convection.

TENTR Parameter for the entrainment in the convective scheme (option


1).

TENTRVL Parameter for the entrainment in the convective scheme (op-


tion 2).

TENTRX Parameter for the entrainment in the convective scheme (option


1).

TRENTRV Parameter for the calculation of the convective transport of


momentum.

TVF Fall speed of solid water.

UHDIFV Inverse height for mixing length profile.

USUPRC Inverse of the maximum convective precipitation intercepted by


canopy.

USURIC Inverse of the maximum Richardson number in the stable case.

XMAXLM Parameter of the profile of mixing length.

XMINLM Parameter of the profile of mixing length.


22 2. Namelist settings

2.2.15 NAMPHY1

ALBMAX Maximum albedo of snow.

ALBMIN Minimum albedo of snow.

OMWPRO Relaxation of deep soil moisture.

RCGMAX Numerical security for the heat-storage capacity of the ground.

RCTVEG calorific capacity of the various types of vegetation.

SODELX Dimensionless depth of the layers in the soil for the heat diffusion.

2.2.16 NAMPHY2

FACFRAF coefficient for gust diagnostics.

LRAFTUR activation of gust diagnostics.

XMULAF Anti-fibrillation for the old turbulence scheme.

2.2.17 NAMRAD15

LERAD6H15 If .T., additional calls are done during the first 6 hours.

LERADHS15 If .T., calculations are done on a coarse grid, then interpo-


lation is performed.

NAER15 If 1, aerosols are used.

NMODE15 Configuration of RADINT15.

NOVLP15 Option of cloud overlap: maximum-random (1), maximum (2)


or random (3).

NRADFR15 Frequency of call of RADINT15 in time step (if positive) or


in hour (if negative).

NRINT15 Horizontal sampling of the calculation grid.

2.2.18 NAMRGRI

NRGRI Number of longitudes per latitude circle (starting from the pole).
Necessary if NHTYP=2.
2. Namelist settings 23

2.2.19 NAMRIP

NINDAT Starting date in format YYYYMMDD. To be modified only if


one changes initial conditions file. During an integration by successive
runs, this date is updated by the script.

NSSSSS Starting hour (in seconds since 0h).

LASTRF Keep insolation as for years around 2000, used to prevent any
drift due to the formulation of RET which is not correct unless over
the period 1980-2020

2.2.20 NAMSCEN

RI0 Solar constant.

2.2.21 NAMTOPH

ETCOEF Pressure below which ACCOEFK is active.

ETCVIM Pressure below which ACCVIMP is active. Must be higher than


or equal to ETQSAT.

ETDIFU Pressure below which ACDIFUS is active. Must be higher than


or equal to ETCOEF.

ETDRAG Pressure below which ACDRAG is active. Must be higher than


or equal to ETCOEF.

ETDRME Pressure below which ACDRME is active.

ETNEBU Pressure below which ACNEBT, ACNEBR and ACNEBC are


active. Must be higher than or equal to ETCVIM and ETQSAT.

ETOZON Pressure below which ACOZONE is active.

ETPLUI Pressure below which ACPLUIS is active. Must be higher than


or equal to ETQSAT.

ETQSAT Pressure below which ACQSAT is active.

ETRADI Pressure below which ACRANEB is active; this does not concern
RADINT or RADINT15.

RCLX Coefficient of effectiveness of chlorine in the destruction of ozone.


This coefficient, as well as all those of NAMSCEN may be updated by
the script.
24 2. Namelist settings

XDRMQK Coefficient of relaxation of moisture for mesospheric friction.

XDRMQP Pressure above which the mesospheric relaxation of moisture is


activated.

XDRMTK Coefficient of relaxation of the temperature for mesospheric


friction.

XDRMTP Pressure above which the mesospheric relaxation of the tem-


perature is activated.

XDRMUK Coefficient of relaxation of the wind for mesospheric friction.

XDRMUP Pressure above which mesospheric friction is activated for the


wind.

2.2.22 NAMVV1

DVALH Pressure of level i is DVALH(i)+ps DVBH(i). The top of the at-


mosphere is i=0, the surface is i=NFLEVG. A change of the levels of
the model implies a change of the initial and boundary conditions files
.

DVBH see above.

2.3 Important SURFEX namelists

You will find hereafter comments on some switches present in the standard
file for the Arpege grid (CGRID=”GAUSS”). For the others, it is necessary to
browse the Surfex User’s guide. The file of namelist for the surface model
is named EXSEG1.nam.

2.3.1 NAM_PGD_GRID

CGRID type of GRID and projection : “GAUSS”,”CONF PROJ ”,”CARTE-


SIAN ”,”LONLAT REG”,”IGN ”,”NONE”

2.3.2 NAMDIM

NDGLG number of rows of latitudes


2. Namelist settings 25

2.3.3 NAMRGRI

NRGRI : number of pseudo-longitudes on each pseudo-latitude circle start-


ing from the rotated pole

2.3.4 NAMGEM

RMUCEN sine of the latitude of the rotated pole

RLOCEN longitude of the rotated pole (radian)

RSTRET stretching factor (must be greater than or equal to 1)

2.3.5 NAM_ISBAn

CC1DRY type of C1 formulation for dry soils

CSCOND type of thermal conductivity.

CSOILFRZ type of soil freezing-physics option

CDIFSFCOND type of Mulch effects

CSNOWRES type of turbulent exchanges over snow

CALBEDO type of bare soil albedo

CROUGH type of orographic roughness length

CCPSURF type of specific heat at surface

LGLACIER If activated, specific treatment (as in Arpege) over perma-


nent snow/ice regions. Snow depth initialised to 10m and soil ice to
porosity. During the run, snow albedo ranges from 0.8 to 0.85

2.3.6 NAM_SGH_ISBAn

CRUNOFF type of subgrid runoff

CKSAT Activates the exponential profile for Ksat

CRAIN Activates the spatial distribution of rainfall intensity.

CHORT Activates the Horton runoff due to water infiltration excess


26 2. Namelist settings

2.3.7 NAM_SEAFLUXn

CSEA_FLUX type of flux computation physics : "ECUME " : iterative


method proposed by Belmari 2005

CSEA_ALB type of albedo formula : "TA96" : Taylor et al (1996) formula


for water direct albedo, depending on solar zenith angle

CINTERPOL_SST = ”MONTH” : interpolates monthly SST to daily


SST

XICHCE coefficient used in the Ecume formulation

2.3.8 NAM_WATERFLUXn

CWAT_ALB type of albedo formula used to set albedo over water : "TA96"
: Taylor et al (1996) formula for water direct albedo, depending on so-
lar zenith angle

CINTERPOL_TS ”MONTH” : interpolates monthly SST to daily SST

2.3.9 NAM_DIAG_SURF_ATMn

LFRAC flag to save in the output file the sea, inland water, natural covers
and town fractions

LDIAG_GRID flag for mean grid diagnostics

2.3.10 NAM_DIAG_SURFn

N2M flag to compute surface boundary layer characteristics

LSURF_BUDGET flag to save in the output file the terms of the surface
energy balance

LSURF_VARS flag to save in the output file the surface specific humid-
ity for each scheme (on the four separate tiles), on each patch of the
vegetation scheme if existing.

LCOEF flag to save in the output file the transfer coefficients used in the
computation of the surface energy fluxes, for each scheme (on the four
separate tiles) and aggregated for the whole surface

LRAD_BUDGET flag for radiative energy budget

LSURF_BUDGETC flag to save in the output file the time integrated


values of all budget terms that have been activated
2. Namelist settings 27

LRESET_BUDGETC flag to reset cumulatives variables at the begin-


ning of a run

2.3.11 NAM_WRITE_DIAG_SURFn

LPROVAR_TO_DIAG switch to write (or not) prognostic variable

LSELECT switch to control which fields are written

CSELECT Name of ouput fields if LSELECT=true

2.4 Modifying namelists

The file of namelists is designed to be modified. The management of the


duration of a run of the model (switches NSTOP and NFRHIS) and of the
frequency of post-processing (switches NFRPOS, NFRSFXHIS, NFRCORM
and NFRRAZ) is carried out automatically by the model script (see Chap-
ter 3). The update of greenhouse gases, solar constant, stratospheric chlorine
(NAERAD) may be done by the script (in the case of scenario runs). The
update of the date at the end of a run of the model (switches NINDAT and
NSSSSS) is carried out by the tool datnam.pl in the script.
One will find examples of namelists in tori in the directory quoted in
section 1.3. The standard fortran does not authorize the comments after a
semicolon, but some files may include comments which are removed before
use by the model script. The names of namelist and the switches appear
in alphabetical order. It is a very good idea to leave them in that order,
because one can compare and edit two files nam1 and nam2 by:
vim -d nam1 nam2
When changing geometry, it is easy to find by this way what must be changed
and what must be kept. Many model crashes come from an error in a
namelist: a quick check is recommended before asking for help. In case
of doubt about the value of a switch which is not in the namelists file,
the model output NODE.001 which is returned together with the standard
model output contains the print of most switches and their values (use grep
for example or vim to find it) for the atmospheric part. It is an Arpege
rule which is alas not always followed.
28 2. Namelist settings
3
Launching the model

3.1 General principle

The model is not launched just by calling an executable file. It is necessary to


prepare a temporary environment of files as a preliminary phase. Then, once
the model has run the required period (typically one month), it is necessary
to process and archive the result files. We need therefore a series of unix
instructions to be realized sequentially. They are gathered in a file in text
format called model script. After the file of namelists, this is the second
configurable file necessary to customize a climate simulation. In fact you
must in any case edit the default model script but you are not obliged to
edit the default file of namelists. A few model scripts are available on tori:
/cnrm/gc/mrga/mrga561/V5.2/
The script we describe here is mccV5.2.cmip5_cpl_auto . A simpler script
(no automatic launching, no coupling) is described in version 5.1 user’s guide.
It may be a good idea to look at it first if you are a new comer in the
Arpege-climat world.
By creating as a preliminary a history file, a calendar file and a sub-step
file, you let the system manage the rerun and you intervene only in case of
problem (breakdown or crash). The automatic launching utility has been in
place for almost 25 years at CNRM and proved reliable to ensure automation,
real time monitoring and historical archiving of long experiments in best
conditions of safety. In addition, the script includes an internal loop which
allows to perform several (typically 12) months in a single job. The reason
for this is the small number of processors on tori, given the total number
of jobs submitted to it. Each new job enters a queue and it is wise to gather
different months (the typical length of an elementary climate run) to queue
only once per simulation year. However, very expensive jobs (several elapsed
30 3. Launching the model

hours in the machine) are penalized in the queue by a lower priority. So,
according to the model resolution, you should optimize this gathering.

3.2 Script content

We examine here the model script mccV5.2.cmip5_cpl_auto. It allows to


launch a coupled simulation. It requires a minimum edition. Of course you
can change more lines if the choice of the monthly base does not satisfy you
or if you need to complexify the script for valuable reasons. Unless what
its name claims, it has not been used for CMIP5. ASTER resarch team
has developed its own scripts. Let us examine section by section how this
script works. In this chapter, the word section has nothing to do with the
sectioning of the script in three steps by MTOOL.
The first block of lines contains some information about the job profile. The
two variables nnp and nn define the number of processors per node and the
number of nodes. The product of the two, $NPROC is the total number of
processors in the parallelization. You are limited by the machine, but also
by the model resolution (with the standard version, the limit is 96 processors
because of fast Fourier transforms). Then some variables for the system are
defined. On tori, you should let them as they are. On another machine,
this is a different story.

3.2.1 Setting unix variables

The first part really editable by you starts here: variables specific to the
user are defined here. The script is self-explanatory. The name $EXPID is
to be changed every time you create a new experiment and do not want
to overwrite an existing one. The number $IPASS has to be incremented
each time you submit again your job, if you want to proceed in the calendar
(otherwise you redo exactly the same run). The file substeps contains the
size of the inner loop (12 months). If you attempt to run more passes that
its sized, you are exited. Variable $GEOM is very important. It defines the
geometry, i.e. the horizontal and vertical description of your grid. You
will encounter it in the post-processing as well as in the pre-processing. If
you intend to change it from the standard one, you have to create a new
namelist, but also many environment files (see Chapter 5). By default, the
model starts on 1st January 1989 00:00 UTC. Changing $YEAR0, $DATE0 and
the namelist (section NINDAT) is not sufficient. Here again, you need new
environment files.
The script indicates then where you will find the iniial namelists and the
initial conditions (atmosphere, surface, ocean, sea-ice, river routing and cou-
pler). In the case of the coupler, there are 3 initial files (atmosphere, ocean
3. Launching the model 31

and rivers). In the case of the surface, there are 2 initial files (Arpege file
and text file).
If you use your own monthly boundary conditions, you have to change
$BCOND. The five $PATH* variables correspond to directories you must cre-
ate on cougar. The script cannot create them for you. If you try to submit
the default script without taking any action, your run will fail because it
cannot archive the files. This is generally the first mistake done by a new
Arpege-climat user (sometimes by an experienced one too) who attempts
to press the button of his new toy before reading the guide. You are abso-
lutely free to name those five variables according to your fancy, but remember
them: you will need these names in the post-processing scripts.
As long as you use the standard geometry of tl127l31r, you will have no
file missing, except the restart if you decide to start at a date different from
1 January 1989. But if you decide to use another geometry, you should read
Chapter 5 first. However, you can create easily two files at a new geometry:

• LISTPP may remain /cnrm/gc/mrga/mrga561/arpege/pp_tl127l31r


• MSKF can contain a single line with 0. 0. 1

This is perhaps not what you want for your experiment, but the script
will not crash. The other fields containing $GEOM in their name must ab-
solutely be created and properly referenced in the script. For example, if
file lonlat_$GEOM does not exist you will run one month, but crash in the
post-processing with an obscure error diagnostic.
At this stage, old Arpege-climat users need to pay attention to a new
feature. A part of the post-processing which was done outside in previous
versions is now done here. By default, you do not archive the big amount of
model result (the former POST files). Instead, you save four types of products:

1. the monthly means


2. the global series
3. the “hemispheric” series: this means the first $NPE points of the model
grid, which can correspond to the northern hemisphere or simply a
polar cap in the standard case, or the area of high resolution in the
case of a stretched geometry
4. the local series: this means a list of points extracted from the model
grid provided by the $MSKF file; the default is France land points.

The selection of the fields to be extracted in each of the 4 cases is given by


file $LISTPP that you can edit at your convenience. More details are given
in Chapter 5.
32 3. Launching the model

The section ends by defining additional unix variables you do not really
need to modify. The current directory is now $PATHWRK which is a semi-
permanent place (duration at least 24 hours). In case of problem, you can
visit this directory post mortem, but not when you come back from long
holidays.

3.2.2 Collecting the ingredients to run the model

The second section recovers the data, using the indications provided in the
preceding section, and modifies them in order to run the model as you want.
Most of it works on toritx, and the last lines work on torisx.
You need to prepare your namelist. It is saved on file $NAMELIST$IPASS. If
you forget to create the corresponding directory (by default $HOME/namelist)
your experiment will not be able to run more than one month. In order to re-
spect the Gregorian calendar, the script needs a calendar file (calend_$EXPID)
with the initial date in the first line, and at least as many lines with NSTOP=nday
as months you want to process (nday is the duration of each month, e.g. 31
for January). If you have none, no harm! The model script is kind enough
to create one such file for you, starting at $DATE0 and finishing in December
2100. In principle, you should not bother with the calendar file, unless you
want to do something special. Then the model reads a few variables in the
namelist and calculates the different lengths in time step for integration
duration and archiving frequency. Finally the namelist is updated with the
switches which may have changed from the initial or previous namelist.
The second ingredient for the model is a bunch of restarts which contain
the state of the prognostic variables at the beginning of the run and also some
boundary forcings. This file is saved on $RESTART$IPASS for the atmosphere
(do not forget to create its directory). We will need first to update the
boundary conditions of the current month from Const.Clim. This is not
sufficient to update the atmosphere restart , and five files of aerosols and
one file of ozone will be needed.
Different executable files are recovered:

• updcli and updozo for pre-processing

• arpege for the model

• post* for post-processing

• nemo

• oasis

• trip
3. Launching the model 33

and a utility for mpi coupling mpisep.byte


Some variables for post-processing are calculated by compte_champ.pl and
exported by MTOOL-broadcast. The file defining the local domain is also
acquired.
We then change the magine and enter to torisx, because the inner loop on
the months will be executed on this machine. All operations which depend
on the calendar month must be executed there (this makes the script less
straightforward than the basic script of version 5.1).
Now we are in the second stage of MTOOL, and the loop of NSTEP iterations
starts. Some namelists are updated, because the number of days to run has
changed.
The aerosol files (5 types) are acquired with a file containing the constants
of the ozone linear scheme.
Finally the restart is updated by updcli (2D boundary conditions) and
updozo (3D boundary conditions).

3.2.3 Running the model

The third section is the model itself (configuration 1). When all runs properly
as well as when an error occurs, the standard output and standard error files
are printed, followed by the file NODE of the first processor (a large file as
it contains all prints made in parallel mode). The model uses mpiexec for
memory distribution. This is the only parallel part of the job.
The next lines are devoted to post-processing. Here we are still on torisx
because still in the loop on the months, and we have no access to the silo. The
output files from Arpege and Surfex, one every $NHH hour are merged and
renamed. Monthly means are calculated (postM), times series are extracted
for France (postF) globe (postG) and northern hemisphere/Europe (postE).
The namelist is updated: NINDAT is advanced by one month.

3.2.4 Saving the results on the silo

The loop on the months being finished, we are back to toritx. The sea-ice
restart file is archived (by security) on cougar. The monthly means are
also archived in the silo. The time series are temporarily saved on $PATHWRK.
Note that the treatment of the global and hemispheric time series includes
an explicit loop on the name of the fields extracted. If the file $LISTPP
has been modified, then the two loops with index $CFLD are to be modified
accordingly.
34 3. Launching the model

The other restart files are saved for the next launch (atmosphere, surface,
ocean, rivers, coupler).
At the end of the year, i.e. in each launch if NSTEP=12, the time series files
are gathered by tar into annual files which are sent to the silo. Here again
the two loops on $CFLD depend on the content of $LISTPP.

3.2.5 Preparing the next run

The purpose of the fifth part is to prepare the run on the next month. It
simply consists of renaming the atmosphere namelist, then lrelan launches
the model again for a next year. The last lines consist of erasing from tori
the old namelists and the old restarts.
4
Post-processing

4.1 The diagnostic monitor

The primary customization of the post-processing is the choice of the Full-


Pos variables in the namelist. The frequency of archiving is decided in the
script by setting the variable NHH to the number of hours between two archives
(typically 6). In NAMFPC, one chooses the 2D fields (CFP2DF, CFPCU,
CFPPHY and CFPXFU) and the 3D fields (CFP3DF). For 3D fields, one
selects the model levels (NRFP3S) and the pressure levels (RFP3P). There
exists in principle much more fields (see the Full-Pos documentation), but
all will not work with Arpege-climat specifications. Namelist NAMXFU
is also important because it decides when the calculation of minimum and
maximum temperature are reset. But in principle the model script sets the
right values.
Once the namelist is designed, the selected fields are written on separate
files, one file every $NHH hour. To control which field will be really kept, one
has to edit the file $LISTPP. This file has one line per field (plus one line
of header), and six columns. The first two columns should not be edited,
unless a field is added or suppressed. They contain the name of the field
in the Arpege file and 0/1 according to the fact that the field corresponds
to an instantaneous (0) or accumulated (1) value. The last four columns
contain a non-zero value if you wish this field to be saved in one of the four
types of output already mentioned in Chapter 3:

1. monthly means

2. global series

3. “hemispheric” series
36 4. Post-processing

4. local series

The non-zero value is generally 1, but in column four and five it may be 2.
This indicates that you wish daily series of daily averages (based on the
four 6-hourly values). Setting 1 means that you wish 6-hourly (or whatever
frequency you have decided with NHH) data. Local series are always saved at
the highest frequency, because they generally occupy less space.
At his stage, the model script will create the files corresponding to what you
asked for: one file per month for monthly means, one file per year and per
field for global and hemispheric series, one file per year for local series.
In the case of Aladin the global and hemispheric series cover the whole CI
domain (as the monthly means). You can choose the C domain or a smaller
one for local series.

4.2 Monthly means

By default, all variables calculated by Full Pos are saved as monthly means.
Some variables come from the Surfex postprocessing, but they have been
merged with the Arpege ones in the model script. Tables 4.1 and 4.2 list
what is available in a monthly mean file. Such a file is in Arpege format,
which means that you can directly access each field by its name in the first
column. In Table 4.1, the values of NN are 00000 (for 100000 P a), 92500,
85000, 70000, 60000, 50000, 40000, 30000, 25000, 20000, 15000, 10000, 7000,
5000, 3000 and 1000 P a; the value LL corresponds to the lowest level of the
model (by default 31).
A certain number of unix scripts are available on sxclimat:
/eac9/deque/V5.2/postprocessing/
First of all, you want to know about the climate of your model. You have run
a multi-year simulation and you want to create a monthly climatology from
your monthly files. The script you need is moychmens.sh. It calculates for
each calendar month the time average between year $YEAR1 and year $YEAR2
for experiment $EXPID. You must of course edit it to set where the input data
is (on cougar) and where you want to write your results (on sxclimat). You
can also edit fort.4 to select the fields you will average (by default all fields
are processed).
Seasonal means are often preferred to synthesize the model climate. The
script moychsais.sh is very similar to moychmens.sh. It calculates for each
calendar season the average of the three months. Of course, the multi-year
monthly means are assumed to already exist. The variables to edit in the
script are the same as in moychmens.sh.
4. Post-processing 37

name field unit


SURFTEMPERATURE surface temperature K
SURFRESERV.NEIGE snow amount kg m−2
PROFTEMPERATURE deep soil temperature K
SURFRESERV.EAU surface soil liquid water content kg m−2
PROFRESERV.EAU total soil liquid water content kg m−2
PROFRESERV.GLACE total soil ice content kg m−2
CLSTEMPERATURE 2 m temperature K
CLSMINI.TEMPERAT 2 m minimum temperature K
CLSMAXI.TEMPERAT 2 m maximum temperature K
CLSVENT.ZONAL 10 m zonal wind m s−1
CLSVENT.MERIDIEN 10 m meridional wind m s−1
CLSVENT.MODULE 10 m wind square speed m2 s−2
CLSRAFAL.MOD.XFU 10 m wind maximum speed m s−1
CLSHUMI.RELATIVE 2 m relative humidity -
CLSHUMI.SPECIFIQ 2 m specific humidity -
PNN VENT_ZONAL N N P a zonal wind m s−1
PNN VENT_MERID N N P a meridional wind m s−1
PNN TEMPERATUR N N P a temperature K
PNN HUMI.SPECI N N P a specific humidity -
PNN GEOPOTENTI N N P a geopotential J kg −1
MSLPRESSURE Mean sea level pressure Pa
SLL VENT_ZONAL level LL zonal wind m s−1
SLL VENT_MERIDIE level LL meridional wind m s−1
SLL TEMPERATURE level LL temperature K
SLL HUMI.SPECIFI level LL specific humidity -
SLL GEOPOTENTIEL level LL geopotential J kg −1
SURFTENS.DMOG.ZO gravity wave zonal stress N m−2
SURFTENS.DMOG.ME gravity waves meridional stress N m−2
SURFTENS.TURB.ZO turbulent zonal stress N m−2
SURFTENS.TURB.ME turbulent meridional stress N m−2

Table 4.1: Fields available in a monthly mean file


38 4. Post-processing

name field unit


SURFFLU.LAT.MEVA latent heat flux (liquid) W m−2
SURFFLU.LAT.MSUB latent heat flux (solid) W m−2
SURFPREC.EAU.CON convective rainfall kg m−2 s−1
SURFPREC.NEI.CON convective snowfall kg m−2 s−1
SURFPREC.EAU.GEC large-scale rainfall kg m−2 s−1
SURFPREC.NEI.GEC large-scale snowfall kg m−2 s−1
SOMMFLU.RAY.SOLA top solar radiation W m−2
SURFFLU.RAY.SOLA surface solar radiation W m−2
SOMMFLU.RAY.THER top thermal radiation W m−2
SURFFLU.RAY.THER surface thermal radiation W m−2
ATMONEBUL.TOTALE total cloud cover -
ATMONEBUL.CONVEC convective cloud cover -
ATMONEBUL.HAUTE top cloud cover -
ATMONEBUL.MOYENN middle cloud cover -
ATMONEBUL.BASSE bottom cloud cover -
PROFRUISSELLEMEN total run-off kg m−2 s−1
SURFFLU.MEVAP.EA evaporation (liquid) kg m−2 s−1
SURFFLU.MSUBL.NE evaporation (solid) kg m−2 s−1
SURFFLU.CHA.SENS sensible heat flux W m−2
ATMOHUMI TOTALE precipitable water kg m−2
SURFPRESSION surface pressure Pa
ATMOHUMI SOLIDE solid water atmospheric amount kg m−2
ATMOHUMI LIQUIDE liquid water atmospheric amount kg m−2
SURFRAYT DIR SUR surface direct solar radiation W m−2
TOPRAYT DIR SOM top direct solar radiation W m−2
SURFRAYT SOLA DE surface downward solar radiation W m−2
SURFRAYT THER DE surface downward thermal radiation W m−2
SOMMRAYT SOL CL clear-sky top solar W m−2
SOMMRAYT THER CL clear-sky top thermal W m−2

Table 4.2: Fields available in a monthly mean file (end).


4. Post-processing 39

At this stage, you have your material available, except that it is written in an
unusual format, sometimes in uncommon units, and some important fields
are missing. A first useful script is mmm_arp5a.sh. It calculates for each field
the global mean, the minimum and the maximum. The manual edition of
the script is similar to the last two scripts. In addition, the second column
of fort.4 contains a multiplicator of the fields. For example mean sea level
pressure is multiplied by 0.01 to transform P a into hP a. For temperature file,
one can wonder why a multiplier like 1.0001? This is a trick to indicate that
you want K to become ◦ C. With its multiplier, precipitation is transformed
into mm/day. A certain number of fields are added, which are simple and
useful combinations of the existing ones:

• PREC.TOTALE total precipitation

• CHAL LATENTE latent heat

• FLUX CHALEUR surface energy balance

• FLU.EVAPORAT evaporation

• FLUX HUMI surface water balance

• PLUIE TOTALE total rainfall (convective+large-scale)

• NEIGE TOTALE total snowfall (idem)

• RESERVOIR soil water content (solid+liquid)

• CRF.RAY.SOL top solar cloud forcing

• CRF.RAY.THER top thermal cloud forcing

The results are in a simple Ascii file named mmm (for mean minimum maxi-
mum). Because the wind is rotated and rescaled in the case of stretched grid
(and, to a lesser extent, with Aladin grid), you need a file named $COEFUV.
If you use a new geometry, you will have to create such a file. Edit and use
the script:
/eac9/deque/interpolation/coefuv.sh
If you use a new geometry, you have certainly already created the .grid file
you need. It is important that the U- and V- components of vectors appear
by pairs at the end of fort.4. The (even) number of such fields is $NCHV.
To go further than global means, you may want to plot maps of your results.
The script prich_arp5a.sh works in a similar way (multiplication, wind
rescaling, additional variables) but writes the full model grid in Ascii format.
In order to plot the individual fields, you have to unzip, split into files of
$NPT lines and paste with lonlat_$GEOM file ($NPT is the number of lines of
40 4. Post-processing

lonlat_$GEOM). To create this file from your $GEOM.grid file, use the filter
/eac9/deque/interpolation/grid2lonlat.pl
Many plotting software accept <lon,lat,value> text files as an input. One
of the best is the (free) gmt:
gmt.soest.hawaii.edu/gmt/doc/html/GMT_Docs/GMT_Docs.html .
If you wish to interpolate from the model grid to any type of grid (latitude-
longitude, Lambert, polar stereographic or list of cities) please read the doc-
umentation on interpolation in Arpege-climat.

4.3 Global time series

Time series are extracted from the Full Pos files for 3 types of domains.
The simplest domain is the global one, which contains all model grid points.
Because of the size, you will be certainly limited to a few fields. We propose
a default of five fields which are extensively used in climate analyses because
observation series over many parts of the globe are available for comparison.

• PREC total precipitation (kg m−2 s−1 )

• TMIN 2 m minimum temperature (K)

• TMAX 2 m maximum temperature (K)

• Z500 500 hP a geopotential ( J kg −1 )

• PMER mean sea level pressure (P a)

Minimum or maximum are calculated over a $NHH-hour or 24-hour period,


according to $LISTPP. Each field is written in a separate file. There is one
file per year (one file per month after expansion of the tar file). Each file can
be read in ieee 32-bit big-endian format with one record per unit time. The
script extra_jj_glo.sh extracts a domain (by default South West France)
and prints the daily (or 6-hourly) values of a list of fields. To define your
own domain, you can use domaine.sh which retains land points of a latitude-
longitude rectangle. But you can create any list of model grid points (e.g.
list of cities) in an Ascii file with lines in the form <longitude, latitude,
number of the point in the model grid>.

4.4 Hemispheric time series

The only difference in the case of “hemispheric” series versus global series is
that the grid is truncated to the first points. This allows to consider more
4. Post-processing 41

fields. Of course we avoid to select a second time the global fields, and
the proposed list corresponds to surface fields often encountered in regional
analyses (e.g. Prudence database):

• TSUR surface temperature (K)

• SMOI total soil solid+liquid water content (kg m−2 )

• SNOW snow amount (kg m−2 )

• TAUX zonal stress due to turbulence (N m−2 )

• TAUY meridional stress due to turbulence (N m−2 )

• CLFR total cloud cover (0-1)

• NSWR surface net solar radiation (W m−2 )

• NLWR surface net thermal radiation (W m−2 )

• DSWR surface downward solar radiation (W m−2 )

• DLWR surface downward thermal radiation (W m−2 )

• LATH surface latent heat (W m−2 )

• EVAP surface evaporation (kg m−2 s−1 )

• SENH surface sensible heat (W m−2 )

• RUNO total run-off (kg m−2 s−1 )

• UW10 10 m zonal wind (m s−1 )

• VW10 10 m meridional wind (m s−1 )

• TCLS 2 m temperature (K)

• RCLS 2 m relative moisture (P a/P a)

• QCLS 2 m specific moisture (kg/kg)

• WMAX 10 m maximum gust speed (m s−1 )

• PSUR surface pressure (P a)

The script extra_jj_hem.sh extracts a domain from your data. It is as-


sumed that this list of grid points is included in your “hemisphere” (there
are no extrapolations).
42 4. Post-processing

4.5 Local time series

You can save model fields on a small domain. This allows to store many fields
at high frequency. The domain is just a list of model grid points in an Ascii
file with lines in the form <longitude, latitude, number of the point in the
model grid>. You can generate such a file with the domaine.sh script. The
data is saved in a single file per year, contrary to the global or hemispheric
time series. So it is important to know the rank of each field for selection.
To read such a file, the external loop is on time and the internal loop is on
fields.

1. surface temperature (K)

2. deep soil temperature (K)

3. total soil liquid water content (kg m−2 )

4. total soil solid water content (kg m−2 )

5. snow amount (kg m−2 )

6. zonal stress due to turbulence (N m−2 )

7. meridional stress due to turbulence (N m−2 )

8. convective liquid precipitation (kg m−2 s−1 )

9. convective solid precipitation (kg m−2 s−1 )

10. large-scale liquid precipitation (kg m−2 s−1 )

11. large-scale solid precipitation (kg m−2 s−1 )

12. total cloud cover (0-1)

13. surface net solar radiation (W m−2 )

14. surface net thermal radiation (W m−2 )

15. surface downward solar radiation (W m−2 )

16. surface downward thermal radiation (W m−2 )

17. surface latent heat (W m−2 )

18. surface liquid evaporation (kg m−2 s−1 )

19. surface solid evaporation (kg m−2 s−1 )

20. surface sensible heat (W m−2 )


4. Post-processing 43

21. total run-off (kg m−2 s−1 )

22. 10 m zonal wind (m s−1 )

23. 10 m meridional wind (m s−1 )

24. 2 m temperature (K)

25. 2 m relative moisture (P a/P a)

26. 2 m specific moisture (kg/kg)

27. 2 m minimum temperature (K)

28. 2 m maximum temperature (K)

29. 10 m maximum gust speed (m s−1 )

30. model lowest level zonal wind (m s−1 )

31. model lowest level meridional wind (m s−1 )

32. model lowest level temperature (K)

33. model lowest level specific moisture (kg/kg)

34. model lowest level geopotential ( J kg −1 )

35. surface pressure (P a)

In this list some fields are already in the global or hemispheric series, but at
a higher frequency. This list is an accumulation of impact people demands in
the last 15 years, so it should cover many needs. The script extra_jj_loc.sh
extracts a sub-domain (assumed to be included in the local domain). You
can select the fields and apply a multiplicator through the fort.4 internal
file in the same way as with the seasonal means.
44 4. Post-processing
5
Pre-processing

5.1 Rationale

It may be strange that we deal with post-processing before dealing with


pre-processing. In fact pre-processing is only necessary if you wish to use a
geometry which does not exist yet. If you use the standard one (tl127l31r)
or a few others (e.g. mediash_l31) all files exist on tori to run the model.
Pre-processing knowledge is also necessary if you want to use different bound-
ary conditions (e.g. sea surface temperature and aerosol from a scenario).
This chapter will deal with changing geometry, and you will see that some
scripts can be used to change boundary conditions without changing geom-
etry. Most tools mentioned here are on:
sxclimat:/eac9/deque/V5.2/preprocessing/
If you wish to run scenarios in the framework of the Cordex experiment,
there is an additional guide on Arpege-climat web site which explains
how to prepare sea surface temperatures, ozone and aerosols fields.

5.2 Climatology files

The first step when you decide to change geometry is to create twelve clima-
tology files. This corresponds to the old 923 configuration, and is now done
by incli.sh . To use this script, you first give a name to your geometry
(variable GEOM), and you create a nam_$GEOM file on your working directory.
This namelist file contains information about your geometry (most are com-
mon with those of Chapter 2):

NDGL number of latitudes


46 5. Pre-processing

NDLON maximum number of longitudes

NFLEV number of vertical levels

NSMAX spectral truncation

NMSMAX spectral truncation

NSTTYP type of geometry: without (1) or with (2) pole displacement

RNLGINC linear (0) or Gaussian (1) grid

RSTRET stretching factor

RLOCEN longitude of the pole

RMUCEN sine of latitude of the pole

NRGRI number of longitudes per latitude circle (for a new NDGL value,
use the script tori:/cnrm/gc/mrga/mrga561/V5.2/rgrid to generate
NRGRI)

DVALH A-profile for vertical levels: pressure=A+B*(surface pressure)

DVBH B-profile for vertical levels

You can use nam_tl127l31r as a template. The information about vertical


discretization is just necessary to create the frame of the Arpege files. The
values you introduce in this namelist are those you will have to change when
you create a model namelist from an already existing one. In addition,
the switches LNEWORO and LNEWLSM allow you to introduce your own
orography or land-sea mask. In this case, you must have a file neworo (in
m) or newlsm (1 over land 0 over sea) in Ascii format on the model grid.
Note that the script will first truncate your orography data in spectral space
before saving it.
To create the climatology files for Arpege, launch:
./incli.sh $GEOM
To create the climatology files for Aladin, launch:
./incli_ald.sh $GEOM
where GEOM is for example FRB50.
It may take up to one hour for the script to create your twelve files
nclim4_${GEOM}_m*
In addition, you get a $GEOM.grid file which will be necessary to make fur-
ther interpolations and for other applications. The twelve files are to be
sent to tori, because you will need them to run the model. In the case of
5. Pre-processing 47

Aladin, you get a ${GEOM}CIE.grid file which contains the central, inter-
action and extension zones. In the case of ascii or ieee Aladin files, it is
essential that the name indicates which area (C, CI or CIE) is concerned. FA
files such as nclim4* are self-documented about the area they cover. The
script
/eac9/deque/interpolation/redgridald.sh
creates the ${GEOM}CI.grid and ${GEOM}C.grid files from ${GEOM}CIE.grid

5.3 Initial conditions for the atmosphere

Although climate simulation is a boundary value problem rather than an


initial value problem, it is necessary to have an initial restart at the right
date in the right geometry. You need to keep in mind that you will need
an initial restart file for the atmosphere and another initial restart file for
the surface (see next section) which are both files in the Arpege format.
Changing the date does not simply consist of changing the name of a file,
since the date is written internally in the Arpege file. You need script
ini_res_dat.sh which is simple to use. Edit the name of the input and
output restarts (RESTART and RESTARTM) and set the new date (YEAR, MONTH,
DAY, HOUR) in agreement with your namelist. Note that the hour in the
namelist (NSSSSS) is in second. The parameter LAG is important to reset
to zero: Arpege-IFS is a forecast model, so DAY refers to the starting date
of a run. At the end of a one-month run DAY is unchanged and LAG is 720
(or 744).
If you wish to change the date in a forecast perspective, i.e. you wish to
change also the fields, the full ERA40 period is available 6 h by 6 h with
Arpege files in the original ERA40 geometry. ERA interim is also available
at higher resolution for a shorter and nearer period.
To change geometry (horizontal, or horizontal plus vertical) the tool is
arp2arp.sh
which needs one restart and two climatology files. It is a special configuration
of Arpege (927) followed by a program which adds missing fields for the
climate version (SETCLI). You have to edit the script to define the directory
and name of input restart (DIR, RESTART), the directory of climatology files
(DIRBCOND, DIRBCOND2), the directory and name of output restart (DIR2,
RESTART2) and the input and output geometries (GEOM, GEOM2). The less
easy task is to prepare a file of namelists nam2_$GEOM2 with the output
geometry. There is one example in the sxclimat directory. There are only
3 namelists to modify:

1. NAMFPC
48 5. Pre-processing

2. NAMFPD

3. NAMFPG

If you wish to change only the vertical dicretization, the above script does
not work (another mistery of Arpege coding complexity). Instead, use
arp2arp_vert.sh
Note that the vertical interpolation is not as accurate as in 927 configuration
(linear interpolation with pressure, with constant extrapolation instead of
APACHE subroutine). If the near surface accuracy is an important issue
use 927 configuration two times with an intermediate horizontal resolution
finer than your geometry. In the case of Aladin you have no alternative
choice.

5.4 Initial conditions for the surface

The surface initial file is composed of physiographic fields and prognostics


fields. Only, the prognostics fields and time dependant. The creation of the
initial file is done in two steps :

• creation of the PGD file with the physiographic fields which depends
on the geometry of your domain.

• the prognostic fields which depend on the geometry of your domain and
the date and time of the start of your run will be added into the PGD
file. The file is then called the PREP file in the SURFEX environment.

The PREP file is what in the Arpege world is called the initial surface file.
The script initsfxarp will create the new surface initial file. You need to
edit the script to specify :
- the SURFEX namelist Chapter 2named by default OPTIONS.nam if you
want to change the geometry and/or the surface schemes you will use for
your run.
- if you need to create a new PGD or not to : set the variable makepgd to
“yes” or “no” . If you want to change geometry you will need to create a new
PGD.
- the atmospheric file where the prognostic fields will be read from. The file
is a Arpege restart file.
- the directories where the PGD and PREP files will be kept.
You will end with the PGD (if makepgd=”yes”) and the PREP files. To
be more accurate, two files are created for one set of SURFEX data : a file
5. Pre-processing 49

with the suffix .fa containing the data , a file with the suffix .txt containing
a description of the data (type of geometry, date and time of the prognostic
data, the surface schemes used ...)
Thus, the script will create PGD.fa / PGD.txt (if makepgd=”yes”) and
PREP.fa / PREP.txt .
We invite you to keep the SURFEX schemes used in the examples and
to check the values into the complete Externalized surface User’s guide
(http://www.cnrm.meteo.fr/surfex)
(ref : Compilation of auxilliary binairies for Surfex to create the binaries
needed by initsfxarp )
50 5. Pre-processing
6
Coupling with the ocean

6.1 Basic script

The basic model script is available on tori:


/cnrm/gc/mrga/mrga561/V5.2/mccV5.2.cmip5_cpl_auto
The coupled model taken into account in this script is Arpege-climat
V5.2 associated to Nemo V2-3 with the help of Oasis V3 (prism_2-5),
using the mpi1 communication technique. With this coupled model version,
each of the 3 elements needs at least 1 independent processor to be run. An
equilibrium between the simulation time of the atmosphere and ocean models
is recommended: the atmosphere model being the most time consuming,
2 processors ($NPROC) have been devoted to it, 1 for the ocean model
($NPNEMO) and 1 for the coupler ($NPOASIS). Thus we have a total of 4
processors, as in the uncoupled script.
The variable $OASIS3 has to be set to yes in order to tell Arpege-climat
to activate an Oasis mpi communication at the very beginning of the run.
The coupled Arpege-climat namelist ($ININAM) differs from the uncou-
pled one by additional variables in NAMMCC:

• LMMC03 activated for a coupled simulation

• NFRCPL set to coupling frequency in time-step

• NOACOMM set to 5 for a mpi1 communication

• LCURR activated to take into account the currents in the wind stress
computation

• LGELATO un-activated for the simplest ice model (ice if SST below
freezing temperature).
52 6. Coupling with the ocean

In addition to the atmosphere restart file, an oceanic restart file (19790101


as initial date, obtained from an ocean forced integration using ERA40 sur-
face fluxes, NetCDF format) is provided together with the coupler restart files
(NetCDF format, atmosphere surface fluxes, ocean temperature, ice cover and
currents); these latter two files are obtained with the help of two successive
coupled integrations (over the coupling time period each, using the present
script), the first one from zero atmospheric fluxes to get the ocean coupler
restart file and a second (using the previous file) to get the atmosphere cou-
pler restart file.

The update of the namelist concerns also the ocean one (named namelist)
and the coupler one (named namcouple). For the ocean, the initial date
(ndate0) together with the time step number (nitend) and the frequency of
restart (nstock) and diagnostic (nwrite) files are updated. For the coupler,
the initial date (_inidate_) together with the integration time (_duree_)
are updated.

Just after atmosphere boundary condition files, ocean and coupler ones are
added. The former contains coordinates, bathymetry, horizontal diffusion
coefficients, geothermal heating and climatological runoff, while the latter
contains grid, mask, area informations, weights for the gaussian interpolation
from the ocean to the atmosphere and a field name table.

The coupler and the ocean executable files are provided (named oasis and
opa9 respectively in the script). There is the possibility of using another
resolution for the ocean, but you will have to recompile the ocean model
accordingly to do so and changes will have also to be made in the coupler
restart and interpolation files (see next section).

In order to launch the coupled model, a special command (timex mpisx) is


used according to recommendations from the Nec computer specialists.

After the run, in addition to the atmosphere restart file, the ocean restart
file together with the coupler restart files are copied in order to be used at
the beginning of the next month.

The NetCDF ocean diagnostic files (PCO_*grid_*.nc) for the temperature


(T), zonal current (U) and meridional current (V) grids have to be saved
on permanent space in order to post-process them. Many free tools exist to
average or plot files in such a format, so you will not find here dedicated
post-processing tools

At the end of the script, the ocean namelist (similarly to the atmosphere
one) is copied in order to be used at the beginning of the next month.
6. Coupling with the ocean 53

6.2 Changing coupling frequency

If you want to change the 1-day coupling frequency, it will be necessary to


change the three namelists accordingly. For Arpege-climat, NFRCPL
(in NAMMCC) needs to be modified; for Nemo, nexco (in namcpl) needs
also to be modified; and finally, for Oasis, the coupling frequency in seconds
has to be changed (in namcouple) in the first line of each field (at the fourth
rank).

6.3 Changing model resolution

In order to change the atmosphere resolution, you must :

1. apply the recipes of Chapter 5 to deal with the chosen new geometry

2. update the coupler boundary file with the new grid and mask informa-
tions (NetCDF format), and modify the namelist namcouple accord-
ingly

3. provide a file containing fluxes set to zero (NetCDF format) at the


new geometry to be able to generate the coupler restart files (see the
methodology in section ??)

In order to change the ocean resolution, you must:

1. re-compile the Nemo code with the appropriate compilation key for
the chosen resolution together with some specific subroutine sources
associated to that resolution

2. update, as for the atmosphere counterpart, the coupler boundary file


with the new grid and mask informations (NetCDF format), and modify
the namelist namcouple accordingly

3. apply the methodology described in the section ?? to generate the new


ocean coupler restart
54 6. Coupling with the ocean
7
Compiling the model source

You are now eager to run Arpege-climat on your own machine. From a
technical point of view, you need to compile the source code and ancillary
libraries (for example Gribex coding). This chapter describes how to install
the ancillary libraries and the installation and use of GmkPack (a Météo-
France toolbox) to compile the Arpege-climat source code.

7.1 Description of the source code

You will need the Arpege-climat source code and the ancillary libraries
packages to have the model compiled.

7.1.1 Ancillary libraries packages

The ancillary libraries can be compiled independently and do not interfere


too closely with new Arpege-climat source code.

auxlibs_installer.1.3.tgz This package contains a wrapper to gribex.350


(ECMWF distribution), bufrdc.350 (ECMWF distribution), EC li-
brary (a light version of ECMWF-emos library), Rgb library (Météo-
France interface to read seviri data) and miscellaneous dummy li-
braries : MPI (including a header mpif.h), IBM-specific scientific li-
braries (light), Oasis coupler, ECMWF Fields Database, ECMWF
Wave model, Nag library (light)

lapack_installer.1.2.tgz This package is a semi-automatic wrapper to


Lapack 3.0 distribution in order to compile Blas and Lapack libraries
56 7. Compiling the model source

with g95 or gfortran compilers, on Linux or Darwin operating sys-


tems, with 32 bits or 64 bits addressing processors, Intel (PC and
MacIntosh) or Powerpc (MacIntosh).

odbdummy.tar.gz and psmiledummy-1.tar.gz Arpege-climat source code


is a shared code with the NWP model and coupled climate model.
Some parts of the NWP are not needed for standalone climate runs
and so, are not provided. However, you need to provide dummy rou-
tines to satisfy the linker: this is the case for ODB (Observational
DataBase software) and PSMILE (coupling with ocean model using
the coupler Oasis).

7.1.2 GmkPack toolbox

GmkPack is a toolbox made of bash scripts with some perl scripts for the
creation of an environment to compile some source code. After the creation
of this environment it can perform the compilation, manage objects libraries
from the result of the compilation, and build executable files from object
libraries.
From the definition above you can wonder whether GmkPack is a concurrent
to make. The answer is yes. It has been developed after some limitations
have been found with the use of make. For instance, make will not mark the
difference between two files which would have the same name (basename)
and a different path (dirname). The practice of the development of complex
softwares like Arpege or Aladin has led to the development of GmkPack .
While GmkPack is expected to work on any source code, it is especially de-
signed for Arpege or Aladin ; that is why its customization looks Arpege-
Aladin-oriented and why it includes some kinds of plug-ins for source codes
which needs particular pre-treatments.
The package gmkpack.6.3.1-eac.tar.gz has been modified to compile the
model. The modifications are minor and concern the list of libraries needed
to create the binary.

7.1.3 Arpege-climat source code

The file src_arp502_export.01.tar.gz contains the Arpege-climat source


code. If you prefer your own compilation method, you need the file
intfb_arp502_export.01.tar.gz
containing the interface files of Arpege routines.
The source code is structured into projects which allow to group routines
under distinct directories.
7. Compiling the model source 57

arp : this is the core of the model. It contains : adiab/ climate/ dia/
mwave/ ocean/ phys_ec/ transform/ ald_inc/ common/ function/
namelist/ onedvar/ pp_obs/ utility/ c9xx/ control/ kalman/ nmi/
parallel/ setup/ var/ canari/ dfi/ module/ obs_preproc/ phys_dmn/
sinvect/

ald : directory concerning Aladin model only.

mse : directory containing Surfex (the EXternalized SURFace) routines.

... and the following directories : sur / tal / tfl / uti / xrd / mpa

7.2 Installation of the different tools and libraries

Before running the installation script you need :

• to choose the compiler (for example : the Portland compiler)

• to choose and create (if needed) the directories where to copy the in-
clude files and the libraries that will be created (for example:
/home/user_adm/include and /home/user_adm/lib/gnu)

In all the packages, you will find README files that give you more information
about the compilation and installation of the package.

7.2.1 Ancillary libraries packages

auxlibs_installer.1.3.tgz

You can select the automatic or interactive installation. The package is


installed running the script : driver_automatic or driver_interactive.
Tests are performed for Gribex (program agrdemo from ECMWF distribu-
tion), Bufrdc (program decode_bufr from ECMWF distribution), and Rgb
(program test_media from Météo-France) during the installation procedure.
It has been tested on different platforms and with different compilers :

• g95 on Linux PC 32 bits, Linux PC 64 bits, MacIntel 32 bits, PowerMac


G5

• gfortran on Linux PC 32 bits, Linux PC 64 bits, MacIntel 32 bits,


PowerMac G5

• pgi on Linux PC 32 bits, Linux PC 64 bits and Cray XD1


58 7. Compiling the model source

• sxf90 cross-compiler on Linux front-end server for NEC SX8-R

• xlf ecgate/rs6000 and hpce/ibm_power4

How to proceed?
During the interactive installation you will be asked to choose to compile
the libraries with a 32 bits or 64 bits representation of real numbers . The
commands are:

% cp auxlibs_installer.1.3.tgz /home/user1/install
% cd /home/user1/install
% gzip -d auxlibs_installer.1.3.tgz
% tar xf auxlibs_installer.1.3.tar
% mkdir /home/user1/include
% mkdir -p /home/user1/lib/pgi
% cd auxlibs_installer.1.3
% ./driver_interactive
....

The script will end with :


SUMMARY OF INSTALLATION REPORT :
==============================
GRIBEX : SUCCESSFULLY TESTED AND INSTALLED
BUFR : NOT TESTED BUT INSTALLED
RGB : SUCCESSFULLY TESTED AND INSTALLED
ECLITE : INSTALLED
fdbdummy : INSTALLED
ibmdummy : INSTALLED
mpidummy : INSTALLED
naglitedummy : INSTALLED
oasisdummy : INSTALLED
wamdummy : INSTALLED

% cd /home/user1/install
7. Compiling the model source 59

% /bin/rm -rf auxlibs_installer.1.3

You can check the contents of the directories :


% ls -l /home/user1/lib/pgi
drwxrwxrwx 2 user1 gr1 4096 2008-07-09 09:14 bufrtables/
drwxrwxrwx 5 user1 gr1 4096 2008-07-09 09:13 gribtables/
drwxrwxrwx 2 user1 gr1 4096 2008-07-09 09:13 gribtemplates/
-r--r--r-- 1 user1 gr1 1853944 2008-07-09 09:14 libbufr_000350R64.a
lrwxrwxrwx 1 user1 gr1 19 2008-07-09 09:14 libbufr.a -> libbufr_000350R64.a
-r--r--r-- 1 user1 gr1 247674 2008-07-09 09:14 libeclite_001R64.a
lrwxrwxrwx 1 user1 gr1 18 2008-07-09 09:14 libeclite.a -> libeclite_001R64.a
-r--r--r-- 1 user1 gr1 12106 2008-07-09 09:16 libfdbdummy_001R64.a
lrwxrwxrwx 1 user1 gr1 20 2008-07-09 09:16 libfdbdummy.a -> libfdbdummy_001R64.a
-r--r--r-- 1 user1 gr1 3936676 2008-07-09 09:13 libgribex_000350R64.a
lrwxrwxrwx 1 user1 gr1 21 2008-07-09 09:13 libgribex.a -> libgribex_000350R64.a
-r--r--r-- 1 user1 gr1 14112 2008-07-09 09:16 libibmdummy_001R64.a
lrwxrwxrwx 1 user1 gr1 20 2008-07-09 09:16 libibmdummy.a -> libibmdummy_001R64.a
-r--r--r-- 1 user1 gr1 63802 2008-07-09 09:16 libmpidummy_001R64.a
lrwxrwxrwx 1 user1 gr1 20 2008-07-09 09:16 libmpidummy.a -> libmpidummy_001R64.a
-r--r--r-- 1 user1 gr1 3366 2008-07-09 09:16 libnaglitedummy_001R64.a
lrwxrwxrwx 1 user1 gr1 24 2008-07-09 09:16 libnaglitedummy.a ->\
libnaglitedummy_001R64.a
-r--r--r-- 1 user1 gr1 7292 2008-07-09 09:16 liboasisdummy_001R64.a
lrwxrwxrwx 1 user1 gr1 22 2008-07-09 09:16 liboasisdummy.a -> liboasisdummy_001R64.a
-r--r--r-- 1 user1 gr1 1099958 2008-07-09 09:15 librgb_001R64.a
lrwxrwxrwx 1 user1 gr1 15 2008-07-09 09:15 librgb.a -> librgb_001R64.a
-r--r--r-- 1 user1 gr1 5284 2008-07-09 09:16 libwamdummy_001R64.a
lrwxrwxrwx 1 user1 gr1 20 2008-07-09 09:16 libwamdummy.a -> libwamdummy_001R64.a
% ls -l /home/user1/include/*
/home/user1/include/mpidummy:
total 12
-rw-r--r-- 1 user1 gr1 8828 2008-07-09 09:16 mpif.h
60 7. Compiling the model source

lapack_installer.1.2.tgz

If you are working on tori you will not need to install this package. You
can select the automatic or interactive installation. The package is installed
running the script driver_automatic or driver_interactive .
How to proceed?
During the interactive installation you will be asked to choose to compile the
libraries with a 32 bits or 64 bits representation of real numbers .

% cp lapack_installer.1.2.tgz /home/user1/install
% cd /home/user1/install
% gzip -d lapack_installer.1.2.tgz
% tar xf lapack_installer.1.2.tar
% cd lapack_installer.1.2
% ./driver_interactive
.....
% cd /home/user1/install
% /bin/rm -rf lapack_installer.1.1

You can check the contents of the directories :


% ls -l /home/user_adm/lib/gnu
-rw-r--r-- 1 user_adm gr1 615344 2008-07-02 13:32 libblas.a
-rw-r--r-- 1 user_adm gr1 7975076 2008-07-02 13:32 liblapack.a

odbdummy.tar.gz

The script build_library creates and installs the library libodbdummy.a.


You need to edit the script to choose the compiler and directories for instal-
lation.
How to proceed?

% cp odbdummy.tar.gz /home/user1/install
% cd /home/user1/install
% gzip -d odbdummy.tar.gz
% tar xf odbdummy.tar
7. Compiling the model source 61

% cd odbdummy

Edit the script build_library


% ./build_library .....
% cd /home/user1/install
% /bin/rm -rf odbdummy

You can check the contents of the directories :


% ls -l /home/user_adm/lib/gnu
lrwxrwxrwx 1 user_adm gr1 44 2008-07-03 18:01 libodbdummy.a -> libodbdummy_R64.a
-r--r--r-- 1 user_adm gr1 19986 2008-07-03 18:01 libodbdummy_R64.a

psmiledummy-1.tar.gz

The script psmile.make will create and install the libraries libpsmile.MPI1.a
and libpsmiledummy.a. You need to edit the script to choose the compiler
and directories for installation.
How to proceed?

% cp psmiledummy-1.tar.gz /home/user_adm/install
% cd /home/user_adm/install
% gzip -d psmiledummy-1.tar.gz
% tar xf psmiledummy-1.tar
% cd psmile

Edit the script psmile.make


% ./psmile.make .....
% cd /home/user1/install
% /bin/rm -rf psmile

You can check the contents of the directories :


% ls -l /home/user_adm/lib/gnu
-rw-r--r-- 1 user_adm gr1 6056 2008-07-07 15:18 libpsmiledummy.a
% ls -l /home/user_adm/include/psmile.gnu
-rw-r--r-- 1 user_adm gr1 840 2008-07-09 14:03 errioipsl_psmile.mod
-rw-r--r-- 1 user_adm gr1 141502 2008-07-09 14:03 mathelp_psmile.mod
62 7. Compiling the model source

-rw-r--r-- 1 user_adm gr1 66908 2008-07-09 14:03 mod_comprism_proto.mod


-rw-r--r-- 1 user_adm gr1 174 2008-07-09 14:03 mod_gsip_model.mod
-rw-r--r-- 1 user_adm gr1 1508 2008-07-09 14:03 mod_kinds_model.mod
-rw-r--r-- 1 user_adm gr1 1497 2008-07-09 14:03 mod_prism_def_partition_proto.mod
-rw-r--r-- 1 user_adm gr1 15520 2008-07-09 14:03 mod_prism_get_proto.mod
-rw-r--r-- 1 user_adm gr1 13854 2008-07-09 14:03 mod_prism_proto.mod
-rw-r--r-- 1 user_adm gr1 9542 2008-07-09 14:03 mod_prism_put_proto.mod
-rwxr-x--- 1 user_adm gr1 298 2008-07-09 14:03 psmile_os.h*
-rw-r--r-- 1 user_adm gr1 6283 2008-07-09 14:03 stringop_psmile.mod

7.2.2 GmkPack toolbox

The script build_gmkpack will install the GmkPack toolbox. By default, the
installation script will use the directory /tmp; you can modify the variable
GMKTMP to change this value.
During the installation the script allows you to create a configuration file
for compilation of Arpege-climat. It is possible to do it afterward or to
create other configuration files. You will use the script gmkfilemaker.
Manual pages are installed as well as a html tutorial.

Installation of the toolbox

How to proceed?
Here, we choose to create the configuration file later.

% export GMKTMP=/tmp/tmp.user_adm
% cp gmkpack.6.3.1-eac.tgz /home/user_adm/install
% cd /home/user_adm/install
% gzip -d gmkpack.6.3.1-eac.tgz
% tar xf gmkpack.6.3.1-eac.tar
% cd gmkpack.6.3.1
% ./build_gmkpack
...

The script will end with :

Link to gmkpack created :


7. Compiling the model source 63

lrwxrwxrwx 1 user_adm gr1 13 2008-08-19 18:35 /home/user_adm/install/gmkpack


-> gmkpack.6.3.1
Warning : environment variables PATH and MANPATH should now be set
as follows in your profile :
GMKROOT=/home/user_adm/install/gmkpack
export PATH=$GMKROOT/util:$PATH
export MANPATH=$GMKROOT/man:$MANPATH
To create new packs with gmkpack you will need to setup a configuration
file,
defining compilers, options, etc.
You can setup this file manually or use a an automatic assitant.
Do you want to run the configuration file maker assistant now (y)
or later [n] ? n

Location of the html pages:


file:///home/user1/install/gmkpack/doc/index.html

Creation of configuration files for compilation with GmkPack

The user environment has been modified as specified here above (GMKROOT,
PATH, MANPATH).
As configure would do, the script gmkfilemaker tries to get information
from the system and asks the user for complementary information and creates
a configuration file. This command can be run more than once, especially
to run GmkPack with different compilers.
The files are stored under the directory $GMKPACK_SUPPORT/arch. By default
GMKPACK_SUPPORT is the directory /home/user_adm/install/gmkpack_support
where /home/user_adm/install is the GmkPack installation directory. After
running this command, it is recommended to edit the resulting configura-
tion file and make sure the setup looks correct. It is also an opportunity to
improve the customization of the configuration files.
The files SXF90.TORI.x and PGI.LXEAC7.x are examples of the configuration
files :

• SXF90.TORI.x for tori

• PGI.LXEAC7.x for a 64 bits Linux PC with the Portand Compiler


64 7. Compiling the model source

They have been created running gmkfilemaker and then customized to run
a coupled model on TORI and a non coupled model on the Linux PC.
The compilation of the libraries needed for the coupling (libmpp\_io.a and
libpsmile.MPI1.a) is described in Oasis :

• system-dependent libraries (section LD_SYS??) added


for tori:
/home/user_adm/lib/gnu/libibmdummy.a
/home/user_adm/lib/gnu/libodbdummy.a
/usr/local/lib/NETCDF-3.6.1/lib/libnetcdf.a
/home/user_adm/oasis/v3.3.02/prism/SX8/lib/libmpp\_io.a
/home/user_adm/oasis/v3.3.02/prism/SX8/lib/libpsmile.MPI1.a

for a PC without MPI:


/home/user_adm/lib/gnu/libibmdummy.a
/home/user_adm/lib/gnu/libodbdummy.a
/home/user_adm/lib/gnu/libpsmiledummy.a

• include directories added


for tori:
INCLUDEPATH=/home/user_adm/include/odbdummy:/home/user1/oasis/v3.3.02/prism/
for a PC without MPI:
INCLUDEPATH=/home/user_adm/include/odbdummy:/home/user_adm/include/psmile.gn

• value of PACK_PREFIX (used to create the name the packs changed)

• value of GMK_NQS_SMALL and GMK_NQS_LARGE (if you use NQS to com-


pile)

7.3 Compiling Arpege-climat with GmkPack

At this stage, all the externals libraries and GmkPack are installed, and a
configuration file for compilation has been created. You need now to install
the Arpege-climat source code and the script for compilation.
Here you will find a how-to to help you with GmkPack. You are invited to
read through the tutorial
7. Compiling the model source 65

file:///home/user_arm/install/gmkpack/doc/index.html
to have more information.
For GmkPack, there are two types of users : the administrator of the packs
and the developer.

• the administrator will create the reference packs. He will choose a di-
rectory to store the packs (ROOTPACK) with public access for developers.

• the developer will create local packs (in his directory HOMEPACK) based
on a reference pack, to test his new source code.

A pack is a directory containing specific sub-directories and files, which are


created running GmkPack. You will copy your new or modified routines in
this pack.

7.3.1 User environment

The user will need to modify his user profile file and create the directories
when needed.

• Administrator environment :

# Setup for GMKPACK : Administrator


GMKROOT=/home/user_adm/install/gmkpack
ROOTPACK=/home/user_adm/public/packs
GMKTMP=/tmp/tmp.user_adm
HOMEPACK=$ROOTPACK
HOMEBIN=$ROOTPACK/binpack
GMKFILE=SXF90.TORI
PATH=$GMKROOT/util:$PATH
MANPATH=$GMKROOT/man:$MANPATH
export GMKROOT ROOTPACK GMKTMP HOMEPACK HOMEBIN GMKFILE PATH MANPATH

• Developer environment :
# Setup for GMKPACK : developer ’fred’
GMKROOT=/home/user_adm/install/gmkpack
ROOTPACK=/home/user_adm/public/packs
GMKTMP=/tmp/tmp.fred
66 7. Compiling the model source

HOMEPACK=$HOME/mypacks
HOMEBIN=$HOME/mypacks/binpack
GMKFILE=SXF90.TORI
PATH=$GMKROOT/util:$PATH
MANPATH=$GMKROOT/man:$MANPATH
export ROOTPACK HOMEPACK ROOTBIN HOMEBIN GMKTMP GMKFILE MANPATH

7.3.2 Creation of reference packs

The administrator has setup his environment for GmkPack.


% gmkpack -r arp502 -b main -a -p arpclim
The directory $ROOTPACK/arp502_main.01.SX8RV20r400.x.pack and sub-
directories are created. The compilation script ics_arpclim is installed in
$ROOTPACK/arp502_main.01.SX8RV20r400.x.pack
% cd $ROOTPACK/arp502_main.01.SX8RV20r400.x.pack
% ls -l
total 8
drwxr-xr-x 2 user_adm gr1 6 Aug 21 09:31 bin
-rwxr-xr-x 1 user_adm gr1 5201 Aug 21 09:31 ics_arpclim
drwxr-xr-x 2 user_adm gr1 6 Aug 21 09:31 lib
drwxr-xr-x 5 user_adm gr1 44 Aug 21 09:31 src
drwxr-xr-x 2 user_adm gr1 6 Aug 21 09:31 sys
% ls -l src
total 0
drwxr-xr-x 2 user_adm gr1 6 Aug 21 09:31 local
drwxr-xr-x 4 user_adm gr1 32 Aug 21 09:31 unsxref
% ls -l src/local
total 0

Installation of the source code in the src/local directory:


% cp /home/user1/install/src_arp501_export.00.tar.gz .
% cp /home/user_adm/install/src_arp502_export.01.tar.gz .
% gzip -d src_arp502_export.01.tar.gz
% cd src/local
7. Compiling the model source 67

% tar xf /home/user_adm/install/src_arp502_export.01.tar
% ls -l
total 12
drwxr-xr-x 17 user_adm gr1 4096 Aug 21 09:43 ald
drwxr-xr-x 29 user_adm gr1 4096 Aug 21 09:43 arp
drwxr-xr-x 7 user_adm gr1 63 Aug 21 09:43 mpa
drwxr-xr-x 7 user_adm gr1 79 Aug 21 09:43 mse
drwxr-xr-x 7 user_adm gr1 79 Aug 21 09:43 sur
drwxr-xr-x 6 user_adm gr1 65 Aug 21 09:43 tal
drwxr-xr-x 6 user_adm gr1 65 Aug 21 09:43 tfl
drwxr-xr-x 3 user_adm gr1 23 Aug 21 09:43 uti
drwxr-xr-x 18 user_adm gr1 4096 Aug 21 09:44 xrd

The next step is to compile, running the script ics_arpclim. The binary is
created under $ROOTPACK/arp502_main.01.SX8RV20r400.x.pack/bin and
is named ARPCLIM:
on tori: qsub ics_arpclim
Do not forget to change the value of the elapse time request. Error and
output messages will be kept in the job output file.
on PC: ics_arpclim 1>arpclim.out 2>&1
The file arpclim.out will keep all error and output messages.

7.3.3 Creation of developer packs

The user has setup the GmkPack environment. The reference pack
$ROOTPACK/arp502_main.02.SX8RV20r400.x.pack
has been created and compiled by the administrator.
The administrator has first created
$ROOTPACK/arp502_main.01.SX8RV20r400.x.pack.
Then, he has created
$ROOTPACK/arp502_main.02.SX8RV20r400.x.pack
to insert modified routines on top of arp502_main.01.

% gmkpack -r arp502 -b main [-v NN] -u arp502_test -p arpclim


where NN is the version number of an administrator pack: arp502_main.NN.
By default, GmkPack will base your pack on the last version of the pack
arp502_main. In this case the value of NN is 02. The directory
$HOMEPACK/arp502_test
68 7. Compiling the model source

and sub-directories are created. The compilation script ics_arpclim is in-


stalled in it.
% cd $HOMEPACK/arp502_test
% ls -l
total 8
drwxr-xr-x 2 fred gr1 6 Aug 28 09:11 bin
-rwxr-xr-x 1 fred gr1 5201 Aug 28 09:11 ics_arpclim
drwxr-xr-x 2 fred gr1 6 Aug 28 09:11 lib
drwxr-xr-x 5 fred gr1 44 Aug 28 09:11 src
drwxr-xr-x 2 fred gr1 6 Aug 28 09:11 sys
% ls -l src
total 4
lrwxrwxrwx 1 fred gr1 76 Aug 28 09:11 inter.1\
-> /home/user_adm/public/packs/arp502_main.02.SX8RV20r400.x.pack/src/local
drwxr-xr-x 12 fred gr1 4096 Aug 28 09:11 local
lrwxrwxrwx 1 fred gr1 76 Aug 28 09:11 main\
-> /home/user_adm/public/packs/arp502_main.01.SX8RV20r400.x.pack/src/local
drwxr-xr-x 4 fred gr1 32 Aug 28 09:11 unsxref
% ls -l src/local
total 12
drwxr-xr-x 17 fred gr1 4096 Aug 28 09:11 ald
drwxr-xr-x 29 fred gr1 4096 Aug 28 09:11 arp
drwxr-xr-x 7 fred gr1 63 Aug 28 09:11 mpa
drwxr-xr-x 7 fred gr1 79 Aug 28 09:11 mse
drwxr-xr-x 7 fred gr1 79 Aug 28 09:11 sur
drwxr-xr-x 6 fred gr1 65 Aug 28 09:11 tal
drwxr-xr-x 6 fred gr1 65 Aug 28 09:11 tfl
drwxr-xr-x 3 fred gr1 23 Aug 28 09:11 uti
drwxr-xr-x 18 fred gr1 4096 Aug 28 09:12 xrd

You will put your own routines, following the directory structure of Arpege,
in the directory : $HOMEPACK/arp502_test/src/local
For example, if you have modified the routine aplpar.F90
7. Compiling the model source 69

% cd $HOMEPACK/arp502_test
% cp $HOME/work/aplpar.F90 src/local/arp/phys_dmn

The next step is to compile, running the script ics_arpclim. The binary is
created under $HOMEPACK/arp502_test/bin and is named ARPCLIM.
on tori: qsub ics_arpclim
Error and output messages will be kept in the job output file.
on PC: ics_arpclim 1>arpclim.out 2>&1
The file arpclim.out will keep all error and output message.

7.3.4 GmkPack commands

A set of commands are available with GmkPack:

• admpack : list administrator packs

• cleanpack : remove all files but source files (run after the command
resetpack)

• envpack : display your GmkPack environment

• genpack : display the genesis of the pack

• rmpack : remove a pack

• scanpack : scan the source code files within a pack (very useful within
$HOMEPACK/src/local)

• showpack : find the versions of a source file

7.4 Compilation of auxilliary binairies for SURFEX

The source code for Surfex is embeded in the Arpege-climat code. It


is thus compiled with GmkPack along theArpege-climat binary. However,
you will need specific binaries to create the initial Surfex files with the
script initsfxarp.

7.4.1 Creation of PGD and PREP binaries

These binaries are created by GmkPack through the scripts ics_pgd and
ics_prep.
You can created a developer pack based on the administrator pack with the
following command :
70 7. Compiling the model source

%gmkpack -r arp502 -b main [-v NN] -u arp502_sfx -p pgd


where NN is the version number of an administrator pack: arp502_main.NN.
By default, GmkPack will base your pack on the last version of the pack
arp502_main. In this case the value of NN is 02.
and then
%gmkpack -r arp502 -b main [-v NN] -u arp502_sfx -p prep
The pack arp502_sfx will contains the 2 scripts ics_pgd and ics_prep .
After running the scripts, you will get :
$HOMEPACK/arp502_sfx/bin/PGD : the PGD binary
$HOMEPACK/arp502_sfx/bin/PREP : the PREP binary

7.4.2 Creation of fa2gb_arp and xtrsfc binaries

The prognostic fields added to the PGD file come from a restart file by the
binary PREP. This version of PREP can read ASCII or GRIB files. You
will need to extract to fields from the restart file (using xtrsfc) and then
format this FA file to a GRIB file (using fa2gb_arp) as it is done in the
script initsfxarp.
xtrsfc is created running the script xtrsfc.sh provided in here.
fa2gb_arp is created using a Makefile and source code provided in fa2gb_arp.tar.
The scripts and Makefile provided are setup to run on tori so that the SUR-
FEX initial file is created on tori.

7.5 Source code and files

Provided the license to access the source has been signed, the packages and
files are available on tori:

/cnrm/gc/mrga/mrga561/compil/aux/
auxlibs_installer.1.3.tgz
fa2gb_arp.tar
gmkpack.6.3.1-eac.tar.gz
initsfxarp
lapack_installer.1.2.tg
odbdummy.tar.gz
7. Compiling the model source 71

psmiledummy-1.tar.gz
xtrsfc.sh

/cnrm/gc/mrga/mrga561/compil/arp5.2/
GFORTRAN.LXEAC7.x
SXF90.TORI.x
ics_arpclim
intfb_arp502_export.01.tar.gz
src_arp502_export.01.tar.gz
userpack.SXF90

7.6 Other sources

When looking at the model scripts, you can see several executable files which
are not the model itself. If you want to port the model on another computer
or to modify the executables, you need to access their sources. They are
included in compilation scripts with the same name of the executables. The
scripts are located in:
/cnrm/gc/mrga/mrga561/compil/misc/
Pre-processing scripts are updclig5a which updates the restart boundary
conditions and updozo5b updates the coefficients for the ozone parameteri-
zation.
For postprocessing, you need postM5b, postG5a, postE5a and postF5a.
72 7. Compiling the model source
8
Adding variables to the model

One major change in Arpege-climat V5 with respect to V4 is the intro-


duction of the GMV and GFL structures for coding the variables:
The GMV (Grid-point Model Variables) cover prognostic variables involved
in the semi-implicit (u,v,T,ps in the hydrostatic model). The prognostic
fields have spectral representation. GMV hold 3D variables and GMVS
holds 2D variables (surface pressure ...).
The GFL(Grid-point FieLds) cover all other variables (conservative prognos-
tic variables and pseudo-historical variables) (q,ql,qi,a, O3).
For Surface variables new structures have been introduced : a SP structure
(prognostic surface variables) and a SD structure (diagnostic variables).
We will not develop much more on GMV/GMVS coding. This document
will focus on the GFL and Surface variables as adding a GFL or a Surface
variable will be the most useful for you. In the third section, we will show
a way to post-process data available in the model but not accessible in the
current post-processing : using the Free Upper Air and Surface fields.

8.1 Adding a GFL variable

You can read through the document “User’s guide to add new GFL variables
or new GFL attributes in ARPEGE/IFS, ALADIN, AROME: cycle 32” by
K. Yessad to learn in details what adding a new GFL variable fully implies.
Here we will give an illustration with the example “adding the Convective
Vertical Velocity variable”. The GFL variable name will be YCVV . We will
show what are the steps to follow.
74 8. Adding variables to the model

8.1.1 General presentation of GFL

First of all, it is necessary for you to get familiar with the structures TYPE_GFL_COMP
and TYPE_GFL_NAML . These structures are descriptors and define the at-
tributes of the GFL. Several attributes of the TYPE_GFL_NAML structure are
also attributes of the TYPE_GFL_COMP. You will be able to modify the default
values of the GFL component through the namelist NAMGFL .
You have to set up these attributes when adding a new GFL.
The TYPE_GFL_COMP structure :

! Individual field descriptor


CHARACTER(LEN=16) :: CNAME ! ARPEGE field name
INTEGER(KIND=JPIM) :: IGRBCODE ! GRIB code
LOGICAL :: LADV ! Field advected or not
INTEGER(KIND=JPIM) :: NREQIN ! 1 if field requiered in input,
! 0 if not, -1 if initialised
! with a reference value REFVALI
LOGICAL :: LREQOUT ! T if field requiered in output
LOGICAL :: LGPINGP ! GP field input as GP
LOGICAL :: LGP ! Field exists and of grid-point type
LOGICAL :: LSP ! Field exists and of spectral type
LOGICAL :: LCDERS ! Derivatives required (spectral only)
LOGICAL :: LACTIVE ! Field in use
LOGICAL :: LTHERMACT ! Field thermodynamically active
REAL(KIND=JPRB) :: R
REAL(KIND=JPRB) :: RCP
LOGICAL :: LT9 ! Field in t-dt GFL
LOGICAL :: LT1 ! Field in t+dt GFL
LOGICAL :: LT5 ! Field in trajectory GFL
LOGICAL :: LPHY ! Field in physics GFL
LOGICAL :: LPT ! Field in PC phy. tend. GFL (GFLPT)
LOGICAL :: LTRAJIO ! Field written to and from trajectory
! structure
LOGICAL :: LPC ! Field in predictor/corrector time
! stepping (GFLPC)
REAL(KIND=JPRB) :: REFVALI ! Reference value for init, used in case
! NREQIN==-1
! LAM specific attributes (Arome/Aladin)
LOGICAL :: LADJUST0 ! True if field is thermodynamically
! adjusted at t (immediatly after inverse
! spectral transforms)
LOGICAL :: LADJUST1 ! True if field is thermodynamically
! adjusted at t+dt (after SL interpolations
8. Adding variables to the model 75

! and NL residuals)
INTEGER(KIND=JPIM) :: NCOUPLING ! 1 if field is coupled by Davies relaxation,
! 0 if not, -1 if coupled with reference
! value for coupling REFVALC
REAL(KIND=JPRB) :: REFVALC ! Reference value for coupling, used in case
! NCOUPLING==-1
LOGICAL :: LBIPER ! True if field must be biperiodised inside
! the transforms
! End LAM specific attributes (Arome/Aladin)
CHARACTER(LEN=12) :: CSLINT ! S.L interpolaion "type"
INTEGER(KIND=JPIM) :: MP ! Basic field "pointer"
INTEGER(KIND=JPIM) :: MPL ! zonal derivative "pointer"
INTEGER(KIND=JPIM) :: MPM ! Meridional derivative "pointer"
INTEGER(KIND=JPIM) :: MP9 ! Basic field "pointer" t-dt
INTEGER(KIND=JPIM) :: MP9_PH ! Basic field "pointer" for Physics
INTEGER(KIND=JPIM) :: MP1 ! Basic field "pointer" t+dt
INTEGER(KIND=JPIM) :: MP5 ! Basic field "pointer" trajectory
INTEGER(KIND=JPIM) :: MP5L ! zonal derivative "pointer" trajectory
INTEGER(KIND=JPIM) :: MP5M ! Meridional derivative "pointer" trajectory
INTEGER(KIND=JPIM) :: MPSLP ! Basic field "pointer" physics
INTEGER(KIND=JPIM) :: MPSP ! Basic field "pointer" spectral space
INTEGER(KIND=JPIM) :: MP_SPL ! Basic field "pointer" spline interpolation
INTEGER(KIND=JPIM) :: MP_SL1 ! Basic field "pointer" in SLBUF1
INTEGER(KIND=JPIM) :: MP_SLX ! Basic field "pointer" in SLBUF1 for CPG_PT
INTEGER(KIND=JPIM) :: MPPT ! Physics tendency "pointer"
INTEGER(KIND=JPIM) :: MPPC ! Predictor/corrector auxiliary array "pointer"
TYPE(TYPE_GFL_COMP),POINTER :: PREVIOUS ! Pointer to previously def. field

The TYPE_GFL_NAML structure :

! Individual field descriptor for namelist input


CHARACTER(LEN=16) :: CNAME ! ARPEGE field name
INTEGER(KIND=JPIM) :: IGRBCODE ! GRIB code
INTEGER(KIND=JPIM) :: NREQIN ! 1 if field required in input, 0 if not,
! -1 if initialised with a reference value
! REFVALI
REAL(KIND=JPRB) :: REFVALI ! Reference value for initialisation, used
! in case NREQIN==-1
LOGICAL :: LREQOUT ! T if field requiered in output
LOGICAL :: LGPINGP ! GP field input as GP
LOGICAL :: LGP ! Field exists and of grid-point type
LOGICAL :: LSP ! Field exists and of spectral type
LOGICAL :: LCDERS ! Derivatives required (spectral only)
76 8. Adding variables to the model

LOGICAL :: LT9 ! Field in t-dt GFL


LOGICAL :: LT1 ! Field in t+dt GFL
LOGICAL :: LT5 ! Field in trajectory GFL
LOGICAL :: LPHY ! Field with physics tendencies GFL
LOGICAL :: LPT ! Field in PC physics tendency GFLPT
LOGICAL :: LTRAJIO ! Field written to and from trajectory structure
LOGICAL :: LPC ! Field in predictor/corrector time stepping GFL
LOGICAL :: LADV ! Field advected or not
LOGICAL :: LQM ! quasi-monotonous interpolation for field
LOGICAL :: LQMH ! quasi-monotonous interpolation in horizontal
! for field
LOGICAL :: LSLHD ! Semi-lagrangian horizontal diffusion used
! for fields
LOGICAL :: LRSPLINE ! 12 points spline interpolation used
! for field
LOGICAL :: LHV ! Hermite vertical interpolation used
! for field (only ozone sofar)
LOGICAL :: LVSPLIP ! vertical spline interpolation used
! for field (only ozone so far)
INTEGER(KIND=JPIM) :: NCOUPLING ! 1 if field is coupled by Davies relaxation,
! 0 if not,
! -1 if coupled with reference value for
! coupling REFVALC
REAL(KIND=JPRB) :: REFVALC ! Reference value for coupling, used in case
! NCOUPLING==-1

The modules involved for GFL are :


1. yomgfl.F90 : contains the main grid-point GFL arrays definitions

• GFL - main GFL array holding t0 and t1 GFL variables

• GFLT1 - GFL array for t+dt quantities

• GFLSLP - GFL array for use in semi-lagrangian physics

• GFL5 - trajectory GFL array

• GFL_DEPART - used in 3-D FGAT (LIDMODEL)

• GFLPT - physics tendency GFL array

• GFLPC - predictor/corrector auxiliary arrays (3TL)

2. type_gfls.F90 : contains the type definitions of the structures holding


the GFL attributes.
8. Adding variables to the model 77

• TYPE_GFLD - overall descriptor, dimensions (number of GFL fields ....)

• TYPE_GFL_COMP - Individual field descriptor

• TYPE_GFL_NAML - Individual field descriptor for namelist input

3. gfl_subs.F90 : contains routines to do basic manipulatutions of GFL


descriptors for example,

• DEFINE_GFL_COMP - Setup indivual GFL field

• SET_GFL_ATTR - Add attributes to previously setup GFL components

• PRINT_GFL - Print GFL attributes

• FALSIFY_GFLC - Set field descriptors to false

4. yom_ygfl.F90 : contains the descriptors of GFL arrays

• YGFL - GFL general descriptor containing dimensions like : Number


of GFL fields,Number of spectrally represented GFL fields,Number of
grid-point GFL fields etc ...

• YQ (Specific humidity), YI (Ice water) . . . - Pointers of the Individual


descriptor( TYPE_GFL_COMP pointer)

• YQ_NL, YI_NL . . . - the corresponding structure to the GFL variable for


the namelist (TYPE_GFL_NAML structure )

• YGFLC - General descriptor of all components. This array will contain


the GFL (YQ, YI . . . point to this array) attributes

• TYPE_FADS - defines the structure of the Field Arpege Descriptors

5. yomfa.F90 : defines the Grib packing options and the list of Field Arpege
Descriptor (FAD)

• YFAQ, YFAI . . . : the corresponding GFL Field Arpege Descriptor (FAD


structure)

8.1.2 Step-By-Step

For our new CVV variable, we want to be able to read/write the GFL on a file
and to use/compute it in a convection scheme. No advection or horizontal
diffusion will be applied to this variable. The default setup here will not
activate the CVV variable. Each time you want to use this variable you will
specify the attributes through the namelist NAMGFL :
78 8. Adding variables to the model

&NAMGFL
...
YCVV_NL%LGP=.T.,
...
&

In your coding activity, please sign your modifications, according to the


Arpege rules. This does not apply to the namelists and yomxxx.F90 mod-
ules.

8.1.3 Step 1: definition and setup to read/write the GFL on


Arpege file

• yomfa.F90 : add YFACVV to create the FAD component.

• namfa.h : add YFACVV

• sufa.F90 : set the name of FAD and update the printout of YOMFA

Modifications done in sufa.F90 :

...
USE YOMFA , ONLY : NVGRIB, NBITPG ,NBITCS ,NSTRON ,NPULAP , &
...
& YFAFSP5 ,YFASRC ,YFASDSAT ,YFACVV ,...

...

!* 1. SET DEFAULT VALUES


! -------------------
...
YFACVV =YSUFAD(’CVV ’,.TRUE.)
...
!* 3. Control and set up of GRIB packing parameters
! for files ARPEGE/ALADIN
!
WRITE(UNIT=NULOUT,FMT=’(/,’’ MODULE YOMFA’’)’)
...
WRITE(UNIT=NULOUT,FMT=’(3(’’( ’’,A16,1X,I3,’’) ’’))’) &
...
& ...,YFACVV ,...
8. Adding variables to the model 79

8.1.4 Step 2: definition and setup to add the GFL variable

yom_ygfl.F90 : add YCVV and YCVV_NL and increment the number of indi-
vidual GFL (JPNAMED_GFL)

TYPE(TYPE_GFL_COMP),POINTER :: YCVV ! Convective Vertical Velocity


TYPE(TYPE_GFL_NAML) :: YCVV_NL ! Convective Vertical Velocity
NAMGFL.h : add YCVV and YCVV_NL

sudim1.F90 : set the default attributes and read the namelist NAMGFL
Modifications done in sudim1.F90 : You will have to look through the whole
routine sudim1.F90 .

• YCVV_NL added in the USE YOM_YGFL list

• attributes setup spread

• in part 1.1.2a:

! 1.1.1 Set implicit default values for items other than GFL attributes
...
! 1.1.2a Set implicit default values for GFL attributes
! (other than "GHG", "GRG", "TRAC", "AERO", "FORCING",
! "EASY DIAG" and "EXT").
YCVV_NL%LGP= .FALSE.
YCVV_NL%LSP= .FALSE.
YCVV_NL%NREQIN= 0
YCVV_NL%REFVALI= ZREFVALI_USELESS
YCVV_NL%LREQOUT= .FALSE.
YCVV_NL%LGPINGP= .FALSE.
YCVV_NL%LTRAJIO= .FALSE.
YCVV_NL%LADV= .FALSE.
...
! * Default for attribute LCDERS,LT9,LT1,LT5
! This value is automatically computed in SUGFL.
YCVV_NL%LPT= .FALSE.
YCVV_NL%LPC= .FALSE.
...
! * Default for attribute CNAME
! This value is automatically computed in SUGFL.
...
! * Default for attribute IGRBCODE
! This value is automatically computed in SUGFL.
80 8. Adding variables to the model

...
YCVV_NL%NCOUPLING= 0
...
! * Default for attribute REFVALC
! REFVALC is useful only when NCOUPLING=-1,
! but to avoid unitialised values, REFVALC is set to -999
! in the other cases.
...
YCVV_NL%REFVALC= ZREFVALC_USELESS
YCVV_NL%LSLHD=.FALSE.
YCVV_NL%LVSPLIP=.FALSE.
YCVV_NL%LRSPLINE=.FALSE.
YCVV_NL%LQM=.FALSE.
YCVV_NL%LQMH=.FALSE.
YCVV_NL%LHV=.FALSE.
...
! 1.2.1 Read NAMDIM and NAMGFL

CALL POSNAM(NULNAM,’NAMDIM’)
READ(NULNAM,NAMDIM)
CALL POSNAM(NULNAM,’NAMGFL’)
READ(NULNAM,NAMGFL)
...

• in part 1.2.2, update the different consitency checks :

LVSPLIP : add YCVV_NL%LVSPLIP in the tests


LHV : add YCVV_NL%LVH
LSLHD : add YCVV_NL%LSLHD

• in part 1.3.3, reset the GFL attributes LSP and LGP to .FALSE. for
configurations where there is no GFL at all.

YCVV_NL%LSP= .FALSE.
YCVV_NL%LGP= .FALSE

• in part 1.9, make sure that the FGFL is not defined as a Grid-Point
and a SPectral variable

IF(YCVV_NL%LGP.AND.YCVV_NL%LSP) THEN
WRITE(NULERR,’(’’BOTH YCVV_NL%LGP AND YCVV_NL%LSP TRUE’’)’)
CALL ABOR1(’ SUDIM1 ’)
ENDIF
8. Adding variables to the model 81

sugfl.F90 defines and sets the attributes of YCVV calling the routine
DEFINE_GFL_COMP.
In an Arpege-climat run, sugfl.F90 is called after sudim1.F90 : until
now only the attributes of YCVV_NL were updated. The pointers are set in
this routine. You should insert the lines dealing with your GFL with the
same rank in the list of GFL in the 3 parts of the code: 1.1, 1.2 and 1.3 .

• YCVV is placed after YSDAT and before YQVA.

• YGFLC = array that contains descriptors of all GFL components

• YGFL%NUMFLDS = Number of GFL fields

! 1.1 Initial settings.

YGFL%NUMFLDS=0
...
! All gridpoint fields have to be set up before the spectral ones
! (i.e. part 1.2 SHOULD be done before part 1.3)
! * Simple GFL variables:
! (order should be the same in parts 1.1, 1.2 and 1.3).
INCR=0
...
YSDSAT => YGFLC(JPGFL-INCR)
INCR=INCR+1
YCVV => YGFLC(JPGFL-INCR)
INCR=INCR+1
...
! 1.2 Grid-point GFL.
...
IF(YCVV_NL%LGP) THEN
IGFLPTR=YGFL%NUMFLDS+1
YCVV=>YGFLC(IGFLPTR)
CALL DEFINE_GFL_COMP(YDGFLC=YCVV,CDNAME=YFACVV%CLNAME,KGRIB=NGRB149,&
& LDGP=.TRUE.,KREQIN=YCVV_NL%NREQIN, &
& PREFVALI=YCVV_NL%REFVALI, LDREQOUT=YCVV_NL%LREQOUT,LDERS=LLDERS,&
& LD5=LL5,LDT1=LLT1)
ENDIF
! 1.3 Spectral GFL.
...
IF(YCVV_NL%LSP)THEN
CALL ABOR1(’SUGFL: spectral CVV not coded ’)
ENDIF
82 8. Adding variables to the model

sudyn.F90 sets attributes of the component YCVV after the calculation of the
semi-lagrangian interpolation (subroutine SUCSLINT):

IF(YCVV%LACTIVE) THEN
CALL SUCSLINT(YCVV_NL%LSLHD,YCVV_NL%LRSPLINE,YCVV_NL%LVSPLIP, &
& YCVV_NL%LHV,YCVV_NL%LQM,YCVV_NL%LQMH,CLSLINT)
! Notice : this field is not supposed to be pronostic !
LLPT = LPC_FULL .AND. LLDIAB .AND. YCVV_NL%LPT.AND.LSLAG
LLPC = LPC_FULL.AND..NOT.LTWOTL.AND.YCVV_NL%LPC
CALL SET_GFL_ATTR(YCVV,LDADV=YCVV_NL%LADV,LDT9=LLT9,LDPHY=LSLPHY, &
& LDPT=LLPT,LDPC=LLPC,KCOUPLING=YCVV_NL%NCOUPLING, &
& CDSLINT=CLSLINT,PREFVALC=YCVV_NL%REFVALC)
ENDIF

8.1.5 Step 3: passing a variable stored in GFL structure to


the physics

Our variable YCVV will be used in the routine accvimpgy.F90. The call tree
is :

CALL CPG(list-of-arguments)
CALL MF_PHYS(list-of-arguments)
CALL APLPAR(list-of-arguments)
CALL ACCVIMPGY(list-of-arguments)

The modifications are linked to the addition of CVV arguments in the rou-
tines.
GFL is the array (dimension NPROMA,NFLEVG,YGFL%NDIM,NGPBLKS) holding
t and t-dt time GFL variables.
cpg.F90 is to be changed:

USE YOM_YGFL , ONLY : YGFL,YQ,YL,YI,YCPF,YSPF,YS,YR,YG,YA,YSRC,YTKE,&


& YEXT, YCVGQ, YQVA, YSDSAT, YCVV, YFORC, YEZDIAG,&
& YDAL, YDOM, YUEN, YUAL, YUOM, YUNEBH
USE YOM_YGFL , ONLY : YQ, YL, YI,YCPF,YSPF

!* 4.4 MF-PHYSICS.
...
CALL MF_PHYS &
& (CDCONF,IBL,IGPCOMP,IST,IEND,IPCT,IGL1,IGL2,IGL3,IGL4,IOFF,ISTGLO, &
& LDRETCFOU,LDWRTCFOU0,LLADNMI,YI%LADV,YL%LADV,YS%LADV,YR%LADV, &
& YG%LADV,YTKE%LADV,YSDSAT%LADV,YCVV%LADV,YEXT(1)%LADV, &
8. Adding variables to the model 83

...
& GFL(1,1,YTKE%MP,IBL),GFL(1,1,YA%MP,IBL),GFL(1,1,YSRC%MP,IBL),&
& GFL(1,1,YSDSAT%MP,IBL),GFL(1,1,YCVV%MP,IBL),&
& GFL(1,1,YQVA%MP,IBL),GFL(1,1,YEXT(1)%MP,IBL),&
...
& GFL(1,1,YA%MP9,IBL),GFL(1,1,YSRC%MP9,IBL),&
& GFL(1,1,YSDSAT%MP9,IBL),GFL(1,1,YCVV%MP9,IBL),&
& ZDUMARR,GFL(1,1,YEXT(1)%MP9,IBL),PGMVS(1,YT9%MSP,IBL),&
...
& ’MF_’)

mf_phys.F90 is to be changed:

USE YOM_YGFL , ONLY : YGFL , YQ , YL , YI ,&


& YS ,YR ,YG ,YTKE , YO3 ,YCPF ,&
& YSPF ,YEXT ,NGFL_EXT, YCVV ,NGFL_EZDIAG ,&
& YQVA ,YA ,&
& YDAL ,YDOM , YUAL , YUOM ,YUNEBH
...
LOGICAL ,INTENT(IN) :: LDLADVCVV
...
REAL(KIND=JPRB) ,INTENT(INOUT) :: PCVVT0(NPROMA,NFLEVG)
...
REAL(KIND=JPRB) ,INTENT(INOUT) :: PCVVT9(NPROMA,NFLEVG)
...
! 2.2 Complete physics.
...
CALL APLPAR ( KST , KEND , NPROMA ,&
& ITDIA , NFLEVG , KGL1 , KGL2 ,&
& NVCLIS , YSD_VVD%NUMFLDS ,&
& NSTEP ,&
& NTSSG , YSP_SBD%NLEVS ,&
& KBL , KGPCOMP,&
& PHI0 , PRE0 , PHIF0 , PRE0F , PALPH0 , PSD_VV(1,YSD_VV%YARG%MP),&
& PSD_VV(1,YSD_VV%YD2%MP) ,&
& PDELP0(1,1),PSD_VV(1,YSD_VV%YIVEG%MP),PSD_VV(1,YSD_VV%YLAI%MP),PLNPR0,&
& PRDELP0,&
& PSD_VV(1,YSD_VV%YRSMIN%MP) , PSD_VV(1,YSD_VV%YSAB%MP ) ,&
& PSD_VV(1,YSD_VV%YZ0H%MP ) , PSD_VA(1,YSD_VA%YSEA%MP ) ,&
& PSD_VA(1,YSD_VA%YLAN%MP ) ,&
& PSD_VA(1,YSD_VA%YSOO%MP ) , PSD_VA(1,YSD_VA%YDES%MP ) ,&
& PSD_VA(1,YSD_VA%YSUL%MP ) ,&
& PSD_VA(1,YSD_VA%YVOL%MP ) , PRCORI ,&
84 8. Adding variables to the model

& PUT0 , PVT0 , PTT0 , PQT0 , PIT0 , PLT0 ,&


& PST0 , PRT0 , PTKET0 , PSDSAT0, PCVVT0 ,&
...
& ’APLPAR’ )
...
! 2.11 Evolution of SDSAT and CVV (GY)
! --------------------------

IF(LCVPGY) THEN
DO JLEV=1,NFLEVG
DO JROF=KST,KEND
PGFLT1(JROF,JLEV,YCVV%MP1)=PCVVT0(JROF,JLEV)
ENDDO
ENDDO
ENDIF

aplpar.F90 is to be changed:

..
REAL(KIND=JPRB) ,INTENT(INOUT) :: PCVV(KLON,KLEV)
...
! 1.- INITIALISATIONS COMPLEMENTAIRES
...
IF(LCVPGY.AND.KSTEP == 0) THEN
DO JLEV=KTDIA,KLEV
DO JLON=KIDIA,KFDIA
PCVV(JLON,JLEV)=0.0_JPRB
ENDDO
ENDDO
ENDIF
...
! 7.3.1 Shallow + Deep convection
CALL ACCVIMPGY ( KIDIA,KFDIA,KLON,NTCVIM,KLEV,&
& PALPH, PAPHIF, PAPRS, PAPRSF, PCP,&
& PDELP,PLH,PLNPR,ZQV,ZQCI,ZQCL,ZQLIS,PQSAT,PQW,&
& PR,PRDELP,PT,PTW, PU, PV,&
& PCPS,PGM,ZSTAB,PTS,&
& PDIFCQ,PDIFCQL,PDIFCQI,PDIFCS, PFCCQL, PFCCQN,&
& ZFHMLTSC,ZFHEVPPC,ZFPEVPPC,&
& PFPLCL,PFPLCN,ZNEBC,ZQLIC,PSTRCU,PSTRCV,&
& ICIS,INLAB,&
& INND,&
& PCVV,&
8. Adding variables to the model 85

& ’ACCVIMP’ )
...

accvimpgy.F90 : This routine, which is not part of the standard physics


package, but has been taken here as an example, contains the computation
itself.

8.2 Adding a Surface variable

When you want to add a new surface variable you have to update at least
the following routines :

• module/surface_fields.F90

• setup/su_surf_flds.F90

• and in some cases phys_dmn/mf_phys.F90

The surface variable structures are for prognostic surface variables (SD) and
diagnostic variables (SP). SP and SD buffers were split into groups. For
example: the group SB (SOILB) contains soil prognostic quantities for the
different reservoirs (1 or 3 at Météo-France, 4 at ECMWF): T Temperature,
Q Liquid water content, TL ice water content. The group VP (VCLIP) con-
tains deep soil diagnostic fields : TPC climatological deep layer temperature,
WPC climatological deep layer moisture.
As an illustration, we will follow the setup of one surface variable already
existing in the code. We choose the climatological deep layer moisture.

8.2.1 Looking at surface_fields.F90

The module surface_fields.F90 is where routines linked to the surface


data flow and surface groups and variables are defined. The climatological
deep layer moisture is a 2D diagnostic field (defined on one layer). This
variable is part of the group VP (for VCLIP).

! * Group VP=VCLIP: deep soil diagnostic fields:


TYPE TYPE_SFL_VCLIP
! climatological deep layer temperature:
TYPE(TYPE_SURF_MTL_2D),POINTER :: YTPC
! climatological deep layer moisture:
TYPE(TYPE_SURF_MTL_2D),POINTER :: YWPC
TYPE(TYPE_SURF_MTL_2D),POINTER :: YVP(:)
86 8. Adding variables to the model

END TYPE TYPE_SFL_VCLIP

! Vclip
REAL(KIND=JPRB),ALLOCATABLE :: SD_VP (:,:,:)
TYPE(TYPE_SURF_GEN) :: YSD_VPD
TYPE(TYPE_SFL_VCLIP) :: YSD_VP

The group YSD_VP has 2 variables : WPC and TPC. The description of the
group will be done setting up the attributes of the structure TYPE_SURF_GEN :
NUMFLDS (Number of field in group), NDIM (Field dimension), NLEVS (Number
of levels), LMTL (.TRUE. if prognostic field) . . .
The description of the variable WPC will be done through the attributes of
the structure TYPE_SURF_MTL_2D : CNAME (Arpege field name), IGRBCODE
(Grib parameter code ), MP (field pointer) . . .

• SD_VP : array (NPROMA,NUMFLDS,NBLOCS) where the values of the fields


will be stored.

• YVP : array containing the pointers of the 2 descriptors of fields YTPC


and YWPC.

8.2.2 Looking at su_surf_flds.F90

su_surf_flds.F90 is where the field is created and initialized.

!* 2. SETUP SURFACE DIAGNOSTIC VAR.


! VCLIP
...
IVCLIP = 0
IF(LECMWF) THEN
ELSE
IF (LRELAXT) IVCLIP=IVCLIP+1
IF (LRELAXW) IVCLIP=IVCLIP+1
ENDIF

IF(ASSOCIATED(YSD_VP%YVP)) DEALLOCATE(YSD_VP%YVP)
ALLOCATE(YSD_VP%YVP(JPMAXSFLDS))
CALL INI_SFLP2(YSD_VPD,YSD_VP%YVP,IVCLIP,.FALSE.,’VCLIP - SD_VP ’)
YSD_VP%YTPC => YSD_VP%YVP(JPMAXSFLDS)
YSD_VP%YWPC => YSD_VP%YVP(JPMAXSFLDS)

IF(LECMWF) THEN
8. Adding variables to the model 87

ELSE
IF(LRELAXT) THEN
YSD_VP%YTPC => YSD_VP%YVP(YSD_VPD%IPTR)
CALL SETUP_SFLP2(YSD_VPD,YSD_VP%YTPC,CDNAME=’RELATEMPERATURE ’)
ENDIF
IF(LRELAXW) THEN
YSD_VP%YWPC => YSD_VP%YVP(YSD_VPD%IPTR)
CALL SETUP_SFLP2(YSD_VPD,YSD_VP%YWPC,CDNAME=’RELARESERV.EAU ’)
ENDIF
ENDIF

The surface field “climatological deep layer moisture” is setup if the key
LRELAXW is set.

The SD group is initialized by subroutine INI_SFLP2 (SFLP2 means 2D field


group) :

• the name of the group is YSD_VPD%CGRPNAME="VCLIP - SD_VP"

• the number of surface fields in this group is setup to YSD_VPD%NUMFLDS=IVCLIP

• as YSD_VPD%LMTL=.FALSE. this is not a prognostic field

INI_SFLP2 increments the number of surface fields (NSURF).

YSD_VPD%IPTR is incremented in SETUP_SFLP2. If we have LRELAXT and


LRELAXW, YV will have 2 pointers : first for temperature and then moisture.

INI_SFLP2 and SETUP_SFLP2 will print out some attributes at the beginning
of a run : (case where LRELAXT=LRELAXW=.TRUE.)

INITIALIZING 2-D SURFACE FIELD GROUP VCLIP - SD_VP


NUMFLDS= 2 LMTL= F
VCLIP 1 RELATEMPERATURE -999 1 0 -1
VCLIP 2 RELARESERV.EAU -999 2 0 -1

In the columns -999 is the Grib parameter code (default), 1 and 2 are MP
(basic field pointer in YV) 0 is ITRAJ ( not in trajectory).

The data are initialized from an Arpege file and stored in SD_VP (in sugridadm.F90)
and used in the physics (cpwts.F90 called by mf_phys.F90).
88 8. Adding variables to the model

8.3 Using Free-use Upper Air and Surface fields

Full-Pos allows you to post-process your personal fields at the cost of some
modifications in the software. This is done by using the Free-use Upper Air
fields for a 3D field and/or the Free-use Surface field for a 2D field.
How to use this mecanism ?
Let us assume you want to post-process:

• three 3D diagnostic fields : total cloud cover FUA_TOT_CC, specific hu-


midity of liquid Water FUA_QLI_WAT and specific humidity of solid wa-
ter FUA_QIC_WAT

• two 2D diagnostic fields : the value of ∆θ from Grenier and Bretherton


FSU_LT_DTH and the value of ∆θ from Lilly FSU_VL_DTH (see Documen-
tation of the prognostic physics about the turbulence scheme)

You have to modify the software to fill the arrays PEXTRA and PEXTR2 with
your personnal fields. In this example this concerns the routine aplpar.F90.
The namelist of the run should look like :

/
&NAMAFN
TFP_FUA(1)%CLNAME=’FUA_TOT_CC ’, ; VEXTRA(1)
TFP_FUA(2)%CLNAME=’FUA_QLI_WAT ’, ; VEXTRA(2)
TFP_FUA(3)%CLNAME=’FUA_QIC_WAT ’, ; VEXTRA(3)
;
TFP_FUA(1)%LLGP=.TRUE., ; gridpoint field
TFP_FUA(2)%LLGP=.TRUE., ; gridpoint field
TFP_FUA(3)%LLGP=.TRUE., ; gridpoint field
;
TFP_FSU(1)%CLNAME=’FSU_LT_DTH ’, ; VEXTR2(1)
TFP_FSU(2)%CLNAME=’FSU_VL_DTH ’, ; VEXTR2(2)
;
TFP_FSU(1)%LLGP=.TRUE., ; gridpoint field
TFP_FSU(2)%LLGP=.TRUE., ; gridpoint field
/
&NAMDPHY
...
;
NVEXTR=3, ; Nb of 3D Free-use Upper air diagnostic fields
NCEXTR=31, ; Nb of levels in these 3D fields
NVXTR2=2, ; Nb of 2D Free-use Surface diagnostic fields
8. Adding variables to the model 89

;
;
NVEXTRDYN=0, ; Nb of extra fields coming from the dynamics
NVXP=0, ; Nb of Extra 3D prognostic fields
NCXP=31, ; Nb of levels in these 3D fields
NVXP2=0, ; Nb of extra 2D prognostic fields
;
/
&NAMFPC
CFP2DF(1)=’SURFPRESSION’,
’MSLPRESSURE’,
’FSU_LT_DTH ’, ; VEXTR2(1)
’FSU_VL_DTH ’, ; VEXTR2(2)
CFP3DF(1)=’GEOPOTENTIEL’,
’TEMPERATURE’,
’VENT_ZONAL’,
’VENT_MERIDIEN’,
’HUMI.SPECIFI’,
’FUA_TOT_CC ’, ; VEXTRA(1)
’FUA_QLI_WAT ’, ; VEXTRA(2)
’FUA_QIC_WAT ’, ; VEXTRA(3)
...
/

Modifications to aplpar.F90 :

! PNEB(JLON,JLEV) : Total Cloud Cover


! PQLI(JLON,JLEV) : Specific Humidity of Liquid Water
! PQICE(JLON,JLEV) : Specific Humidity of Solid water
! ZNEBS(JLON,JLEV) : Stratiform Cloudiness
! ZNEBC0(JLON,JLEV) : Convective Cloudiness
! ZDTHLT(JLON) : delta Theta from Grenier and Bretherton
! ZDTHVL(JLON) : delta Theta from Lilly
!*
! ------------------------------------------------------------------
! 16.- STORE SOME EXTRA FIELDS INTO "PEXTRA" ARRAY, FOR PULL-POS
! OUTPUT : SEE PGP(1,VEXTRA) IN MF_PHYS ; THEN GPPBUF STORAGE
! VIA SC2RDG/SC2WRG (IN MF_PHYS TOO).
! ------------------------------------------------------------------

!- - - - - - - - - - - -
! FOR 3D EXTRA FIELDS :
!- - - - - - - - - - - -
90 8. Adding variables to the model

DO JVEXTRA=1,KFLDX
!
IF (LLTRACE) THEN
WRITE(NULOUT,’(A,I3)’) " > APLPAR : JVEXTRA = ",JVEXTRA
ENDIF
!
IF (JVEXTRA == 1) THEN
DO JLEV=1,KLEVX
DO JLON=KIDIA,KFDIA
PEXTRA(JLON,JLEV,JVEXTRA)=PNEB(JLON,JLEV)
ENDDO
ENDDO
ENDIF
IF (JVEXTRA == 2) THEN
DO JLEV=1,KLEVX
DO JLON=KIDIA,KFDIA
PEXTRA(JLON,JLEV,JVEXTRA)=PQLI(JLON,JLEV)
ENDDO
ENDDO
ENDIF
IF (JVEXTRA == 3) THEN
DO JLEV=1,KLEVX
DO JLON=KIDIA,KFDIA
PEXTRA(JLON,JLEV,JVEXTRA)=PQICE(JLON,JLEV)
ENDDO
ENDDO
ENDIF
ENDDO
IF (JVEXTRA == 4) THEN
DO JLEV=1,KLEVX
DO JLON=KIDIA,KFDIA
PEXTRA(JLON,JLEV,JVEXTRA)=ZNEBS(JLON,JLEV)
ENDDO
ENDDO
ENDIF
IF (JVEXTRA == 5) THEN
DO JLEV=1,KLEVX
DO JLON=KIDIA,KFDIA
PEXTRA(JLON,JLEV,JVEXTRA)=ZNEBC0(JLON,JLEV)
ENDDO
ENDDO
ENDIF
8. Adding variables to the model 91

!- - - - - - - - - - - -
! FOR 2D EXTRA FIELDS :
!- - - - - - - - - - - -

DO JVEXTR2=1,KFLDX2
!
IF (LLTRACE) THEN
WRITE(NULOUT,’(A,I3)’) " > APLPAR : JVEXTR2 = ",JVEXTR2
ENDIF
!
IF (JVEXTR2 == 1) THEN
DO JLON=KIDIA,KFDIA
PEXTR2(JLON,JVEXTR2)=ZDTHLT(JLON)
ENDDO
ENDIF
!
IF (JVEXTR2 == 2) THEN
DO JLON=KIDIA,KFDIA
PEXTR2(JLON,JVEXTR2)=ZDTHVL(JLON)
ENDDO
ENDIF
!
ENDDO

The order of the fields in PEXTRA and PEXTR2 is important : you must give
to Full-Pos the name of the field in the same order. As it is coded, to ask
for the stratiform cloudiness ZNEBS you need to ask for four 3D diagnostics
fields:

/
&NAMAFN
TFP_FUA(1)%CLNAME=’FUA_TOT_CC ’, ; VEXTRA(1)
TFP_FUA(2)%CLNAME=’FUA_QLI_WAT ’, ; VEXTRA(2)
TFP_FUA(3)%CLNAME=’FUA_QIC_WAT ’, ; VEXTRA(3)
TFP_FUA(4)%CLNAME=’FUA_STRAT_C ’, ; VEXTRA(3)
;
TFP_FUA(1)%LLGP=.TRUE., ; gridpoint field
TFP_FUA(2)%LLGP=.TRUE., ; gridpoint field
TFP_FUA(3)%LLGP=.TRUE., ; gridpoint field
TFP_FUA(4)%LLGP=.TRUE., ; gridpoint field
;
...
/
92 8. Adding variables to the model

&NAMDPHY
...
;
NVEXTR=4, ; Nb of 3D Free-use Upper air diagnostic fields
NCEXTR=31, ; Nb of levels in these 3D fields
;
NVEXTRDYN=0, ; Nb of extra fields coming from the dynamics
NVXP=0, ; Nb of Extra 3D prognostic fields
NCXP=31, ; Nb of levels in these 3D fields
NVXP2=0, ; Nb of extra 2D prognostic fields
;
/
&NAMFPC
...
CFP3DF(1)=’GEOPOTENTIEL’,
’TEMPERATURE’,
’VENT_ZONAL’,
’VENT_MERIDIEN’,
’HUMI.SPECIFI’,
’FUA_TOT_CC ’, ; VEXTRA(1)
’FUA_QLI_WAT ’, ; VEXTRA(2)
’FUA_QIC_WAT ’, ; VEXTRA(3)
’FUA_STRAT_C ’, ; VEXTRA(4)
...
/

The value of KFLDX is set to NVEXTR, the value of KFLDX2 is set to NVXTR2
and the value of KLEVX is set to NCEXTR.

You might also like