flexpart_prepare

../../_images/FLEXPART_PREPARE.png

Generates the gridded input data and the AVAILABLE file needed to run the FLEXPART Lagrangian dispersion model. The input forecast or analysis fields are either automatically retrieved from ECMWF’s MARS archive or read from the specified input file.

Tip

A tutorial on using FLEXPART from within Metview is available here.

What data is available?

flexpart_prepare() is currently only able to handle data from the operational ECMWF forecasts/analyses 2008, 4 June onwards.

Input data fields

The following is for information only - flexpart_prepare() handles these details internally.

FLEXPART requires input fields on a regular latitude-longitude grid in GRIB format. The input data must contain five three-dimensional fields: the two horizontal wind components, vertical velocity, temperature and specific humidity. Additional surface fields (e.g. fluxes) are also needed. The three-dimensional input data has to be available on ECMWF model (i.e. \(\eta\)) levels defined by a hybrid vertical coordinate system. An important restriction is that all the data fields used within a FLEXPART run must have the same domain size, resolution, number of levels, etc.

All the required fields, with one exception, can be retrieved from ECMWF’s MARS archive. The only exception is vertical velocity because FLEXPART needs the following field for its computations: \(\dot \eta \frac{\partial \eta}{\partial p}\). Since only \(\dot \eta\) is archived in MARS the full product needs to be computed during the data preparation process (flexpart_prepare() does it for you).

Input filenames

FLEXPART requires all the input GRIB files to be in the same folder using the following file naming convention: ENyymmddhh. The same directory has to contain the AVAILABLE file as well (it is automatically generated by flexpart_prepare()).

Note

This function performs the same task as the Flexpart Prepare icon in Metview’s user interface. It accepts its parameters as keyword arguments, described below.

flexpart_prepare(**kwargs)

Generates the gridded input data and the AVAILABLE file needed to run the FLEXPART Lagrangian dispersion model.

Parameters

  • prepare_mode ({"forecast", "period"}, default: "forecast") –

    Specifies the data preparation mode. The possible values are:

    • ”forecast”: the selected steps of a given forecast can be used for data generation.

    • ”period”: a period with a start and end date and constant time-step can be defined. In this case flexpart_prepare() tries to retrieve analysis fields from MARS whenever it is possible (for dates in the past) and uses forecast fields otherwise (for dates in the future).

  • input_source ({"mars", "file"}, default: "mars") – Specifies the source of the input GRIB data. If the input_source is “mars” the input GRIB data is retrieved from the MARS archive. When prepare_mode is forecast input_source can also be set to “file”. In this case the GRIB file specified in input_file will be used as input data.

  • input_file (str) –

    Specifies the full path to the file containing the input GRIB data. Available when prepare_mode is “forecast” and input_source is “file”. The input_file must contain the following fields:

    Note

    The surface fluxes are accumulated fields and for the de-accumulation process they also require the step preceding the first step. We have a special case when the first step is 0 because in this case we need two additional steps but from the previous model run! E.g. for a 0 UTC model run when we use 3 hourly steps we need the fluxes from step=6 and step=3 of the 18 UTC run on the previous day.

  • date (number, default: -1) – Specifies the run date of the forecast. Available when prepare_mode is “forecast”.

  • time (number, default: 0) – Specifies the run time of the forecast in hours. Available when prepare_mode is “forecast”.

  • step (number or str or list[number] or list[str], default: "0") – Specifies the forecast steps in hours. Available when prepare_mode is “forecast”.

  • period_start_date (number, default: -1) – Specifies the start date of the period. Available when prepare_mode is “period”.

  • period_start_time (number, default: 0) – Specifies the start time of the period. Available when prepare_mode is “period”.

  • period_end_date (number, default: -1) – Specifies the end date of the period. Available when prepare_mode is “period”.

  • period_end_time (number, default: 0) – Specifies the end time of the period. Available when prepare_mode is “period”.

  • period_step ({"3", "6"}, default: "3") – Specifies the timestep of the period in hours. Available when prepare_mode is “period”.

  • grid_interpolation ({"on", "off"}, default: "on") – Specifies if the input GRIB fields need to be interpolated onto a target grid specified by area and grid. Available when input_source is “file”.

  • area (list[number], default: [-90, -179, 90, 180]) –

    Specifies the area of the output grid in south/west/north/east format.

    Note

    To make global domains work with FLEXPART the western border must be set to one grid cell east of 180. E.g. if the east-west grid resolution is 1 degree area should be set to [-90, -179, 90, 180] etc.

  • grid (list[number], default: [1, 1]) – Specifies the resolution of the output grid in [dx/dy] format, where dx is the grid increment in east-west direction, while dy is the grid increment in north-south direction (both in units of degrees).

  • top_level (number, default: 1) – Only data on and below this model level will be used to generate the FLEXPART input fields. This level can be specified either as a model level or as a pressure value. In the latter case flexpart_prepare() will use the data retrieved for the first date to determine the topmost model level. The default value of this parameter is 1, which means that all the model levels will be used if top_level_units is set to “ml”.

  • top_level_units ({"ml", "hpa"}, default: "ml") – Specifies the units of the value of top_level.

  • reuse_input ({"on", "off"}, default: "on") – If this parameter is set on flexpart_prepare() checks the existence of the data files to be generated and if they are already in place no new data is retrieved and processed. If it is off all the fields are always retrieved and processed and the existing data files are overwritten. The same happens to the AVAILABLE file. The existence of a FLEXPART input GRIB file is checked by using the file name and a set of ecCodes keys from the first message in the file. These keys are as follows: date, time, stepRange, gridType, iDirectionIncrement, jDirectionIncrement, latitudeOfFirstGridPoint, latitudeOfLastGridPoint, longitudeOfFirstGridPoint, longitudeOfLastGridPoint.

  • output_path (str) – Specifies the output directory (can be a relative or absolute path) where the GRIB files and the AVAILABLE file will be generated. If this directory does not exist Metview will create it. The output GRIB files have the following naming convention: ENyymmddhh

Return type

Request