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	server address	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.
OMEGADIFF	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.
ETADIFF	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
ADDPAR	String [p1/p2/../pn]		None	Additional optional surface parameters (2D fields, non-accumulated) Mostly: 27/28/173/186/187/188/235/139/39	Parameters can be specified as the Integer IDs or with the short names.