Lagrangian/std Lagrangian/std

Lagrangian/std Lagrangian/std#

Description#

Plugin for Lagrangian (particle-tracking) atmospheric transport models.

This plugin interfaces FLEXPART (and STILT) Lagrangian footprints with the CIF inversion framework. Unlike Eulerian models, a Lagrangian model pre-computes the sensitivity of each receptor observation to surface fluxes offline (the footprints), and this plugin reads those pre-computed footprints to assemble the observation operator.

The underlying Lagrangian model is not run inside CIF; instead, CIF reads the footprint files that were generated in an offline FLEXPART/STILT simulation. The model direction therefore only concerns the linear mapping between fluxes and concentrations.

Adjoint is exact (the footprint is the adjoint of the forward transport): the same footprint matrix is used in both forward and adjoint passes.

Official resources#

Key references:

  • Stohl et al. (2005) — FLEXPART v6: Technical note: the Lagrangian particle dispersion model FLEXPART version 6.2, Atmos. Chem. Phys., 5, 2461–2474, doi:10.5194/acp-5-2461-2005.

YAML arguments#

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Optional arguments#

autoflush : bool, optional, default False

Cleans big temporary files when the simulation is done. Triggers the function flushrun of the model if available

ensrf_restart_file : str, optional

Use in EnSRF mode to point at relevant restart file

ensrf_datei : str, optional

New start date to use in EnSRF

ensrf_same_restart : bool, optional

Use in EnSRF mode to check if same restart

read_background : bool, optional, default False

Read sensitivity to the background according to FLEXPART

read_surface_sensitivity : bool, optional, default True

Read sensitivity to the surface fluxes according to FLEXPART/STILT

footprint_type : “FLEXPART” or “STILT”, optional, default “FLEXPART”

Type of footprints to read

  • “FLEXPART”: Footprints generated by FLEXPART

  • “STILT”: Footprints generated by STILT

period : str, optional, default “1MS”

Length of periods along which simulations are split

subperiod : str, optional, default “”

Complementary to period if inputs should be at a better resolution than period

numscale : float, optional, default 1000000000000.0

Scaling factor to convert from footprint native resolution to`ppm / (ng/m2/s)`

coeff : float, optional, default 0.001

Conversion coefficient to convert from native output unit to ppb/ppt/ppm, etc. A coefficient of 1 returns ppm; 1e-3 returns ppb, etc.

mmair : float, optional, default 28.97

Molar mass of dry air

footprint_dir_format : “str”, optional, default “%Y%m”

Structure for the footprints per stations. The format can use date formatting

footprint_stat_subdir_format : str, optional, default “{stat}”

Structure for the footprints split by stations

footprint_date_format : str, optional, default “%Y%m%d%H%M%S”

Date format for converting observation dates to footprint data

file_nest_format : str, optional, default “”

Format of the footprint file names.

Note

It is possible to dynamically include the name of the station in file_nest_format (but also in footprint_date_format and footprint_dir_format.

To do so, simply include the string {stat} in the variable.

For instance, if file_nest_format is footprint_{stat}_%Y%m.nc, it will be replaced by footprint_PAL_201001.nc for the station PAL for the month of January 2010.

Similarly, the network column can be used with {network}.

file_glob_format : str, optional, default “”

Same as file_nest_format for footprints outside the regional domain.

file_ini_format : str, optional, default “”

Same as file_nest_format for the initial condition sensitivity files.

run_dir_nest : str, optional, default “”

Directory where footprints for the nested domain are stored. In the case of a non-nested domain, this argument is used for the overall domain.

Note

The expected structure of the footprint folder is:

run_dir_nest

├── station_ID#1 │ └── footprint_dir_format │ └── file_nest_format └── station_ID#2

└── footprint_dir_format

└── file_nest_format

run_dir_glob : str, optional, default “”

Same as run_dir_nest for the outer domain.

Warning

For non-nested domains, run_dir_glob is used by default to read footprints. It is possible to force reading the inside domain with force_read_nest

run_dir_bg : str, optional, default “”

Same as run_dir_nest for reading the influence of the background.

release_shift : str, optional, default “0h”

Releases start X time before observation starts. Accepts pandas date syntax

footprint_format : “bin” or “nc”, optional, default “bin”

Format of FLEXPART/STILT output files ‘grid_time’

  • “bin”: standard FLEXPART outputs

  • “nc”: netCDF adaptation of FLEXPART outputs

force_read_nest : bool, optional, default False

Use it to force using the nested format even when simulations where nested, but the CIF uses them as non-nested. It has no impact for nested simulations, but for non-nested, if the original FLEXPART/STILT simulation was nested and force_read_nest is False, the CIF will use the outer domain by default, which may lead to shape issues

dump_debug : bool, optional, default False

Dumps intermediate datastores (contributions from nested fluxes, global fluxes and initial conditions) in the model sub-directory

backward_trajdays : str, optional, default “”

Duration of backward trajectories. If not specified, automatically inferred from the domain information.

Warning

This argument should be explicitly specified only with STILT

ref_header_ID : str, optional

Name of the station to be used to initialize the header for the model footprints. If not specified, The first station of the observation files will be used.

nthreads : int, optional, default 1

Number of threads to read in parallel grid files. There is a balance to find between to few threads which do not optimize anything and too many threads that overload I/O.

flexversion : float, optional, default 10.4

Version of FLEXPART used to generate footprints

exp_decay : optional

Apply an exponential decay of the emitted species from fluxes to observation data.

Argument structure:
halflife : str, mandatory

The half time of the exponential decay to apply

inverse_decay : bool, optional, default False

Applies a exponential convergence toward an asymptote

station_name_dict : optional

Information to translate station IDs from CIF to footprint file names.

Argument structure:
dict_file : str, mandatory

Path to the file to use as dictionary

separator : str, optional, default “;”

Separator to use to parse the parse dict_file

CIF_stations_id : str, optional, default “CIF_stations_id”

Column name to use as CIF station names

footprint_stations_id : str, optional, default “footprint_stations_id”

Column name to use in footprint station name

reload_footprints : bool, optional, default False

Keeps in memory previous footprint in case other observation have the same release.

Requirements#

The current plugin requires the present plugins to run properly:

Requirement name

Requirement type

Explicit definition

Any valid

Default name

Default version

domain

Domain

False

False

FLEXPART

std

flux

DataStream

True

False

FLEXPART

nc

YAML template#

Please find below a template for a YAML configuration:

 1model:
 2  plugin:
 3    name: Lagrangian
 4    version: std
 5    type: model
 6
 7  # Optional arguments
 8  autoflush: XXXXX  # bool
 9  ensrf_restart_file: XXXXX  # str
10  ensrf_datei: XXXXX  # str
11  ensrf_same_restart: XXXXX  # bool
12  read_background: XXXXX  # bool
13  read_surface_sensitivity: XXXXX  # bool
14  footprint_type: XXXXX  # FLEXPART|STILT
15  period: XXXXX  # str
16  subperiod: XXXXX  # str
17  numscale: XXXXX  # float
18  coeff: XXXXX  # float
19  mmair: XXXXX  # float
20  footprint_dir_format: XXXXX  # str
21  footprint_stat_subdir_format: XXXXX  # str
22  footprint_date_format: XXXXX  # str
23  file_nest_format: XXXXX  # str
24  file_glob_format: XXXXX  # str
25  file_ini_format: XXXXX  # str
26  run_dir_nest: XXXXX  # str
27  run_dir_glob: XXXXX  # str
28  run_dir_bg: XXXXX  # str
29  release_shift: XXXXX  # str
30  footprint_format: XXXXX  # bin|nc
31  force_read_nest: XXXXX  # bool
32  dump_debug: XXXXX  # bool
33  backward_trajdays: XXXXX  # str
34  ref_header_ID: XXXXX  # str
35  nthreads: XXXXX  # int
36  flexversion: XXXXX  # float
37  exp_decay:
38    halflife: XXXXX  # str
39    inverse_decay: XXXXX  # bool
40  station_name_dict:
41    dict_file: XXXXX  # str
42    separator: XXXXX  # str
43    CIF_stations_id: XXXXX  # str
44    footprint_stations_id: XXXXX  # str
45  reload_footprints: XXXXX  # bool

See also

API reference (functions & code)