# The CONTROL parameters¶

## User Section¶

User parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

ECUID

String

None

ECGID

String

None

DESTINATION

String

<name>@ generic<scope>

None

The remote destination which is used to transfer files from ECMWF server to local gateway server.

This has to be set up by the user on the local gateway server. See installation instruction for more information of how to set it up.

GATEWAY

String

None

The gateway server the user is using.

## General Section¶

General parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

DEBUG

Integer

0;1

0

If set to “1” all temporary output files from the mars requests are kept and some extra information is written out to the log file.

Usually all temporary files except the FLEXPART ready output files are deleted at the end of flex_extract.

REQUEST

Integer

0;1;2

2

This parameter allows to write out the mars requests in a seperate file.

The requests are stored in the file “mars_requests.csv”. Possible selections are: 0: normal data retrievement; 1: neglect data retrievement and just writes out the mars requests; 2: retrieve data and write out the mars requests.

PUBLIC

Integer

0;1

0

This specifies the selection of the kind of ECMWF Web Api access and therefore the kind of available datasets. Public data sets (1) and Memberstate data sets (0).

Selecting the public access method, the DATASET parameter has explicitly to be set to select the dataset. (CLASS is not enough.) ATTENTION: For public datasets, the user has to accept the license of the dataset to be retrieved. See here for available datasets and their licenses: https://software.ecmwf.int/wiki/display/WEBAPI/ Available+ECMWF+ Public+Datasets

OPER

Integer

0;1

0

Switch to prepare the operational job script. Start date, end date and basetime will be prepared with environment variables at ecgate.

This is only necessary if extraction of half-day retrievals should be done automatically. Specific extra feature which is usually not used by normal flex_extract users.

ECSTORAGE

Integer

0;1

0

Switch to store FLEXPART ready output files in the ECFS file system.

Mind the data limit.

ECTRANS

Integer

0;1

0

Switch to transfer FLEXPART ready input files to the gateway server.

The gateway server has to be up and running. A destination has to be installed. See installation instructions for more information.

PREFIX

String

anything

EN

Prefix of FLEXPART ready input files

The output files usually have the format <PREFIX>YYMMDDHH. Sometimes it also has some more information, e.g. to distinguish between numbers or in pure forecast mode.

ECFSDIR

String

any path available

ectmp:/${USER}/econdemand/ The destination directory on ECFS file system if the retrieved data should be stored on ECMWF servers. This is only used if parameter ECSTORAGE is set to “1”. MAILOPS list of String [m1, m2, …] any number of mail addresses, seperated by comma${USER}

Email list for operational log files on ECMWF servers. The email addresses should be seperated by a comma.

For the ECMWF server it is enough to give \${USER} as input. On local system an actual email is prefered to operate correctly.

## Time Section¶

Time parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

START_DATE

String (YYYYMMDD)

depends on dataset

None

The first day of the retrieval period.

If END_DATE is set, START_DATE must be greater than END_DATE.

END_DATE

String (YYYYMMDD)

depends on dataset

None

The last day of the retrieval period. For a one day retrieval it has to be the same date as START_DATE. If not set, it is automatically equal to START_DATE.

Doesn’t have to be set. If set, it has to be greater or equal than START_DATE.

DTIME

Integer

1, 3, 6

None

Time step of retrieved data. Detects TYPE, TIME, STEP, ACCTYPE, ACCTIME according to DTIME. Therefore CONTROL file can have more values than needed.

Available resolution in time depends on availability in the data set. Coarser resolution can always be selected.

DATE_CHUNK

Integer

depends on resolution

3

Maximum number of days retrieved within one MARS request.

This number is limited due to maximum allowed memory and time limit for one MARS request. Be careful in changing this number. It can be larger for reanalysis data but may be too large for very high resolution retrievals.

BASETIME

Integer

0; 12

None

This parameter is intended for half-day retrievals. Only half a day will be retrieved starting from BASETIME going back 12 hours. E.g. 20180510 with a BASETIME = 00 would lead to a data retrieval of 20180509 12h until 20180510 00h.

Can be set to 00 or 12 only.

## Data Section¶

Data parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

CLASS

String [xx]

EI, E4, EA, EP, OD

None

ECMWF data classification identifier for data sets.

EI: ERA-Interim; E4: ERA-40; EA: ERA5; EP: CERA-20C; OD: operational;

DATASET

String

CERA20C, INTERIM, ERA5

None

This keyword has to be defined as soon as you want to retrieve public data sets. Public data are stored on a different server and are available for everyone after registration at ECMWF (see installation plan).

A list of available public dataset can be found here: https://software.ecmwf.int/wiki/display/WEBAPI/Available+ECMWF+Public+Datasets

STREAM

String [xxxx]

OPER, ENFO, ENDO

None

Identifies the forecasting system used to generate the data.

Most times the operational data stream OPER is appropriate. Use ENFO for ensemble forecasts and ENDO for CERA data.

EXPVER

String

1

1

Experiment number, necessary for R&D experiments, E-suites

NUMBER

Integer or String [i/to/i]

depends on availability

OFF

In most cases this can be set to “OFF” but for access to individual ensemble members of ensemble forecasts it is necessary to select numbers. Note, however, that model level data are not stored in MARS for individual ensemble members except the control run. They exist only for a few days before they are discarded.

For retrieving CERA data, a number has to be selected explicitly. Usually “0” is enough. For operational data just one number or a list of number can be selected. You can use the syntax “1/to/9” for example.

FORMAT

String

[GRIB1, GRIB2]

GRIB1

Output format (either GRIB1 or GRIB2). Use GRIB2 only when using FLEXPART versions >9.2 or FLEXPART hast to be adapted for reading GRIB2

GRIB2 is only available for 3D model level fields, not for surface fields.

## Data field Section¶

Data field parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

TYPE

list of String [xx xx … xx]

AN, FC, CV, CF, 4V, PF

None

A list of field types for each retrieving hour per day. E.g. AN FC FC FC AN FC FC FC for a day with 3-hourly retrieval DTIME . At 0 and 12 UTC we retrieve analysis fields and at 3, 6, 9, 15, 18 and 21 UTC forecast fields.

So far flex_extract is using ANalysis (AN), ForeCast (FC), Control Forecast (CF), Perturbed Forecast (PF), Calibration/Validation forecast (CV) and 4D Variational analysis (4V). Other types might be also possible but were not tested. The analysis fields are usually (depending on data set) available at 00/06/12/18 UTC. For better temporal resolution, the time inbetween the AN fields can be filled with forecasts (FC). Additionally, it is recommended to use analysis fields only at 00 and 12 UTC and fill the rest of the times with other field types, such as forecasts.

TIME

list of String [xx xx … xx]

[00 - 23]

None

The time of the corresponding field type (TYPE) in hours. It is important to set the correct forecast times. E.g. In Era-Interim data set, to get forecast fields between 1 and 11 hours, forecast times starting at 00 UTC are normally used. To get fields between 13 and 23 hours, forecast times starting at 12 UTC are used. Mostly there are two forecasts starting per day.

Has to have the same amount of values as in TYPE! The start times of forecasts can vary from one data set to another. It is also possible to have just one forecast per day, such as in the CERA data set.

STEP

list of String [xx xx … xx]

[00 - max available STEP in data set]

None

This is the forecast time step in hours for each corresponding field type (TYPE). Counting of the steps starts from the forecast times. E.g. In Era-Interim, for forecasts at 3, 6, 9 UTC the STEPS 3,6 and 9 are used and the forecast TIME 00 UTC.

Has to have the same amount of values as in TYPE and TIME! For analysis (AN) fields the STEP has to be 00 always!

MAXSTEP

Integer

> 24

None

This parameter allows to retrieve data from forecasts longer than 24 hours. With MAXSTEP > 24 the forecasts from different days overlap, the naming scheme of the output files changes from <PREFIX>YYMMDD to <PREFIX>YYMMDD.HH.SSS where HH is the hour of the start of the forecast and SSS is the forecast step in hours.

Optional parameter.

## Flux data Section¶

Flux data parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

ACCTYPE

String

FC, CV, CF, 4V, PF - just one of them

None

The type of field for accumulated data retrieval. The accumulated data fields are only available from forecast fields. Therefore it is seperated from the normal TYPE parameter to allow, for example, retrievment solely of hourly analysis fields in the Era5 data set.

For downward compatibility to older versions: if ACCTYPE is not specified, the default value is taken form the second position of the original TYPE parameter (TYPE[2]). NOTE: This is important at the moment the original TYPE parameter is changed from FC to AN for example.

ACCTIME

String

E.g.: Operational, Era-Interim: 00/12 CERA: 18 ERA5 06/18

None

Start times of accumulated forecast fields (fluxes). The starting times of forecast fields varies between different datasets.

For downward compatibility to older versions: if ACCTIME is not specified, the default value is 00/12 for ERA-Interim and operational data, 06/18 for ERA5 data and 18 for CERA-20C data.

ACCMAXSTEP

Integer

12, 24 or larger

None

This parameter specifies the maximum step in hours for a specific accumulated forecast start time. For daily retrievals with one forecast time the step shouldn’t be greater than 24h. For two forecast times the ACCMAXSTEP should be 12. If the parameter MAXSTEP is specified to retrieve forecasts longer than 24 hours, this parameter must have the same value.

For downward compatibility to older versions: if ACCMAXSTEP is not specified, the default value is set to 12 for ERA5, Era-Interim and operational data or 24 for CERA-20C data, according to one or two forecast times of the data set.

RRINT

Integer

0;1

1

Switch to select method of disaggregation for precipitation fields. Old method (0) with a simple linear disaggregation or new method (1) with 2 additional subsequent intervals per time interval.

For more information see article: Hittmeir, S.; Philipp, A.; Seibert, P. (2017): A conservative interpolation scheme for extensive quantities with application to the Lagrangian particle dispersion model FLEXPART., Geoscientific Model Development. https://doi.org/10.5194/gmd-11-2503-2018

## Domain Section¶

Domain parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

GRID

String [i/i]

0.1° - appropriate value e.g. 2°

None

Horizontal resolution of Latitude/Longitude grid. Best possible resolution varies for different data sets. E.g in operational data it’s 0.1° whereas in Era-Interim it is 0.75°.

It can be specified in tenth degrees (1°) or thousandth degrees (1000 for 1°).

RESOL

String

depends on GRID

None

Horizontal resolution of spectral fields. Specifies the desired triangular truncation of retrieved data, before carrying out any other selected post-processing.

SMOOTH

Integer

approriate number

0

Spectral truncation of ETADOT after calculation on Gaussian grid

For more information see: Sardeshmukh and Hoskins, (1984): Spatial Smoothing on the Sphere, Monthly Weather Review, Vol. 112, No.12, P. 2524-2529

UPPER

String

-90+GRID to 90

None

Latitude of upper right corner of grid area.

LOWER

String

-90+GRID to 90

None

Latitude of lower left corner of grid area.

LEFT

String

-180+GRID to 180

None

Longitude of lower left corner of grid area.

For cyclic (global) grids, use e.g. LEFT = - 180 + GRID, RIGHT = 180. For noncyclic grids crossing the dateline (180W), RIGHT may be smaller than LEFT.

RIGHT

String

-180+GRID to 180

None

Longitude of upper right corner of grid area.

For cyclic (global) grids, use e.g. LEFT = - 180 + GRID, RIGHT = 180. For noncyclic grids crossing the dateline (180W), RIGHT may be smaller than LEFT.

LEVEL

String

60, 91, 137 depends on data set

None

Maximum number of vertical levels.

ERA-Interim has 60 levels; ERA5 has 137 levels; CERA-20C has 91 levels; Operational data can have different number of model levels depending on the date. Check upfront in the MARS catalogue. If LEVELIST is set , this parameter is not needed.

LEVELIST

String [start/to/end]

1/to/137

None

List of vertical levels for MARS request. It can be a subset of levels but it has to include the maximum level (end).

If full list of levels is needed and parameter LEVEL is set, the LEVELIST parameter is not needed. “end” has to be the maximum number of possible levels and has to be the same as in LEVEL, if specified.

## Vertical wind Section¶

Vertical wind parameter in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

GAUSS

Integer

0;1

0

A switch to calculate ETADOT from Lat/Lon grid (0) or from Gaussian grid (1)

ACCURACY

Integer

24

Specifies the number of bits per value to be used in the generated GRIB coded fields.

OMEGA

Integer

0;1

0

Retrieve Omega from MARS and put it to file OMEGAyymmddhh

Only useful for debugging reasons.

Integer

0;1

0

Calculate Omega and Dps/Dt from continuity equation for diagnostic purposes and include it in file OMEGAyymmddhh

Only useful for debugging reasons.

ETA

Integer

0;1

0

Switch to read ETADOT precalculated by ECMWF and multiply it with DPDETA to be compatible with ETADOT calculated from continuity equation. ETADOT calculation from continuity equation on either Gaussian or lat/lon grid is disabled unless ETADIFF is set to 1 as well.

ETADOT is available in ERA5, CERA-20C and operational data sets. Precalculated ETADOT is operationally available from September 2008 onwards. However, it is not available in the ERA-40 and ERA-Interim data set. If ETA is selected in the last two data sets, flex_extract fails.

Integer

0;1

0

Switch to calculate etadot and Dps/Dt from continuity equation for diagnostic purposes and include it in file ETAyymmddhh. Expensive option, only for debugging purposes.

DPDETA

Integer

0;1

1

Switch to multiply etadot with dpdeta – this is the default. In some future version this may change.

ETAPAR

Integer

77

77

GRIB parameter number for ETADOT/DPDETA

## Additional data Section¶

Additional data parameters in CONTROL file

PARAMETER

Format

Possible value range

Default

Description

Information / Conditions

CWC

Integer

0;1

0

Switch to retrieve cloud water content (sum of cloud liquid water and cloud ice) (1) or not (0).

DOUBLEELDA

Integer

0;1

0

Switch to select the calculation of extra ensemble members for the ELDA stream. It doubles the amount of retrieved ensemble members.

Each ensemble member is used to create a new synthesized ensemble member by subtracting 2 * ( current time step value - last time step value ) from the current time step value