pycif.plugins.models.lagrangian — API reference

pycif.plugins.models.lagrangian — API reference#

Configuration reference: lagrangian plugin

pycif.plugins.models.lagrangian.ini_mapper.ini_mapper(model, transform_type, general_mapper={}, backup_comps={}, transforms_order=[], ref_transform='', **kwargs)[source]#

Build the data-flow mapper for the Lagrangian (FLEXPART/STILT) model.

Declares:

  • Flux inputs — one surface flux field per active species, with date windows that extend backward by model.backward_trajdays to cover the full footprint integration period.

  • Background inputs (optional) — a background concentration field read from the period shifted backward by backward_trajdays.

  • Outputs — one sampled concentration field per active species.

Parameters:

  • model – Lagrangian model plugin instance (carries input_dates, input_background, tstep_dates, domain, and chemistry.acspecies).

  • transform_type (str) – unused; kept for API compatibility.

  • general_mapper (dict) – unused.

  • backup_comps (dict) – unused.

  • transforms_order (list) – unused.

  • ref_transform (str) – unused.

  • **kwargs – unused.

Returns:

mapper with inputs, outputs, and outputs2inputs.

Return type:

dict

pycif.plugins.models.lagrangian.ini_periods.ini_periods(self, **kwargs)[source]#

Compute temporal discretisation for the Lagrangian model.

Splits the full simulation window into sub-simulation periods and defines the footprint input date windows that extend backward by self.backward_trajdays from each period start.

Sets the following attributes on self:

  • subsimu_dates — boundary dates of sub-simulation windows (length = n_periods + 1).

  • tstep_dates — dict mapping each period start to its 1-hourly time-step array.

  • input_dates — dict mapping each period start to the backward- shifted flux input dates needed by the footprints.

  • input_background — same but shifted for background concentration read windows.

  • tstep_all — sorted unique merge of all time steps.

  • iniobs / reset_obs — per-period flags controlling obs dumping.

Parameters:

  • self – Lagrangian model plugin instance with datei, datef, period, subperiod, and backward_trajdays set.

  • **kwargs – unused.

pycif.plugins.models.lagrangian.perturb_model.perturb_model(self, nsamples, transf_mapper)[source]#

Extend the Lagrangian footprint model to accommodate ensemble members.

Creates nsamples copies of each active species (acspecies) in the chemistry plugin, using the __sample#NNN naming convention, then removes the original un-suffixed species. Records a perturbed_species mapping from sample name back to original name.

Parameters:

  • self – Lagrangian model plugin instance.

  • nsamples (int) – number of ensemble members.

  • transf_mapper (dict) – unused; kept for API consistency.

pycif.plugins.models.lagrangian.run.run(self, runsubdir, mode, workdir, ddi, nbproc=1, do_simu=True, **kwargs)[source]#

Empty run method for model FLEXPART

pycif.plugins.models.lagrangian.io.native2inputs.native2inputs(self, datastore, input_type, datei, datef, runsubdir, mode='fwd', onlyinit=False, do_simu=True, check_transforms=False, **kwargs)[source]#

Converts data at the model data resolution to model compatible input files.

Parameters:

  • self – the model Plugin

  • input_type (str) – one of ‘flux’, ‘obs’

  • datastore – data to convert if input_type == ‘flux’, a dictionary with flux maps if input_type == ‘obs’, a pandas dataframe with the observations

  • datei – date interval of the sub-simulation

  • datef – date interval of the sub-simulation

  • mode (str) – running mode: one of ‘fwd’, ‘adj’ and ‘tl’

  • runsubdir (str) – sub-directory for the current simulation

  • workdir (str) – the directory of the whole pycif simulation

Notes

Copied from LMDZ. We do not attempt to run the model at this point.

pycif.plugins.models.lagrangian.io.native2inputs_adj.native2inputs_adj(self, data2dump, input_type, di, df, runsubdir, mode='fwd', check_transforms=False, **kwargs)[source]#

Reads outputs to pycif objects.

Does nothing for now as we instead read FLEXPART output inside loop over observations in obsoper.py

pycif.plugins.models.lagrangian.io.outputs2native.outputs2native(self, data2dump, input_type, di, df, runsubdir, mode='fwd', onlyinit=False, check_transforms=False, **kwargs)[source]#

Reads outputs to pycif objects.

Does nothing for now as we instead read Lagrangian output inside loop over observations in obsoper.py

pycif.plugins.models.lagrangian.io.outputs2native_adj.outputs2native_adj(self, data2dump, input_type, di, df, runsubdir, mode='fwd', dump=True, onlyinit=False, do_simu=True, check_transforms=False, **kwargs)[source]#

Reads outputs to pycif objects.

Does nothing for now as we instead read FLEXPART output inside loop over observations in obsoper.py

pycif.plugins.models.lagrangian.io.inputs.fluxes.flux_contribution(self, mode, dataobs, fp_header_nest, fp_header_glob, spec, ddi, batch_computation=False)[source]#

Compute the flux–concentration contribution for one species and period.

Convolves pre-loaded flux fields with FLEXPART/STILT footprints to produce simulated concentration increments for each observation in dataobs. For TL mode, also convolves the flux increment.

Parameters:

  • self – Lagrangian model plugin instance.

  • mode (str) – 'fwd' or 'tl'.

  • dataobs – CIF observation data-store for the period.

  • fp_header_nest – FLEXPART header for the nested-domain footprints.

  • fp_header_glob – FLEXPART header for the outer-domain footprints.

  • spec (str) – species name.

  • ddi (datetime) – sub-simulation period start.

  • batch_computation (bool) – if True, process all ensemble members in a single pass.

Returns:

dataobs updated with simulated 'spec' (and optionally 'incr') columns.

pycif.plugins.models.lagrangian.io.inputs.fluxes.process_obs_row(self, dataobs, ithread, fp_header_nest, fp_header_glob, flux, obs_i, sample_species, batch_computation)[source]#

Compute the flux–concentration contribution for a single observation row.

Reads the nested-domain and (optionally) outer-domain footprint grids for the observation at row obs_i, convolves them with flux, and accumulates the result into dataobs.

Parameters:

  • self – Lagrangian model plugin instance.

  • dataobs (dict) – species-keyed observation data-stores.

  • ithread (int) – thread index (used for debug logging).

  • fp_header_nest – FLEXPART header for the nested-domain footprints.

  • fp_header_glob – FLEXPART header for the outer-domain footprints.

  • flux (dict) – forward flux arrays keyed by species.

  • obs_i (int) – row index into the observation data-store.

  • sample_species (list) – species names to process (may include ensemble-sample variants).

  • batch_computation (bool) – ensemble batch mode flag.

pycif.plugins.models.lagrangian.io.inputs.fluxes_ad.flux_contribution_ad(self, mode, dataobs, fp_header_nest, fp_header_glob, spec, ddi)[source]#

Compute the adjoint flux sensitivity from FLEXPART/STILT footprints.

For each observation in dataobs, reads the footprint grid and accumulates the adjoint flux sensitivity (adj_out departure) into the in-memory flux store self.dataflx, indexed by period and grid cell.

Parameters:

  • self – Lagrangian model plugin instance.

  • mode (str) – 'adj'.

  • dataobs – CIF observation data-store for the period (contains 'adj_out' departure values).

  • fp_header_nest – FLEXPART header for the nested-domain footprints.

  • fp_header_glob – FLEXPART header for the outer-domain footprints.

  • spec (str) – species name.

  • ddi (datetime) – sub-simulation period start.

pycif.plugins.models.lagrangian.io.inputs.fluxes_ad.process_obs_row(self, dataobs, ithread, fp_header_nest, fp_header_glob, flux, flx_sensit_tmp, flx_dates, obs_i)[source]#

Compute the adjoint flux sensitivity for a single observation row.

Reads the footprint grids for the observation at obs_i, weights them by adj_out, and accumulates the result into flx_sensit_tmp.

Parameters:

  • self – Lagrangian model plugin instance.

  • dataobs – CIF observation data-store for the period.

  • ithread (int) – thread index.

  • fp_header_nest – nested-domain FLEXPART header.

  • fp_header_glob – outer-domain FLEXPART header.

  • flux (dict) – forward flux arrays (for background subtraction).

  • flx_sensit_tmp – thread-local accumulator for adjoint flux sensitivity.

  • flx_dates – dates of the flux grid.

  • obs_i (int) – row index into the observation data-store.

pycif.plugins.models.lagrangian.io.inputs.inicond.inicond_contribution(self, mode, dataobs, fp_header_init, spec, ddi, batch_computation=False)[source]#

Compute the initial-condition–concentration contribution for one species and period.

Convolves the FLEXPART initial-condition sensitivity fields (grid_initial_*) with the stored initial-condition array to produce the background concentration increment for each observation in dataobs.

Parameters:

  • self – Lagrangian model plugin instance.

  • mode (str) – 'fwd' or 'tl'.

  • dataobs – CIF observation data-store for the period.

  • fp_header_init – FLEXPART header for the initial-condition sensitivity.

  • spec (str) – species name.

  • ddi (datetime) – sub-simulation period start.

  • batch_computation (bool) – ensemble batch mode flag.

Returns:

dataobs updated with 'spec' contributions from initial conditions.

pycif.plugins.models.lagrangian.io.inputs.inicond.process_obs_row(self, dataobs, ithread, fp_header_init, inicond, obs_i, sample_species, batch_computation)[source]#

Compute the initial-condition contribution for a single observation row.

Reads the initial-condition sensitivity field for the observation at obs_i and convolves it with inicond to produce the background concentration contribution.

Parameters:

  • self – Lagrangian model plugin instance.

  • dataobs (dict) – species-keyed observation data-stores.

  • ithread (int) – thread index.

  • fp_header_init – FLEXPART initial-condition sensitivity header.

  • inicond (dict) – initial-condition arrays keyed by species.

  • obs_i (int) – row index into the observation data-store.

  • sample_species (list) – species names to process.

  • batch_computation (bool) – ensemble batch mode flag.

pycif.plugins.models.lagrangian.io.inputs.inicond_ad.inicond_contribution_ad(self, mode, dataobs, fp_header_init, spec, ddi)[source]#

Compute the adjoint initial-condition sensitivity from FLEXPART fields.

Reads initial-condition sensitivity grids and weights them by adj_out departures from dataobs, accumulating the result into the in-memory initial-condition sensitivity store indexed by period and grid cell.

Parameters:

  • self – Lagrangian model plugin instance.

  • mode (str) – 'adj'.

  • dataobs – CIF observation data-store (contains 'adj_out').

  • fp_header_init – FLEXPART initial-condition sensitivity header.

  • spec (str) – species name.

  • ddi (datetime) – sub-simulation period start.

pycif.plugins.models.lagrangian.io.inputs.inicond_ad.process_obs_row(self, dataobs, ithread, fp_header_init, ini_dates, inicond, inicond_sensit_tmp, obs_i)[source]#

Compute the adjoint initial-condition sensitivity for a single observation row.

Reads the initial-condition sensitivity field for obs_i and weights it by adj_out from dataobs, accumulating the result into inicond_sensit_tmp.

Parameters:

  • self – Lagrangian model plugin instance.

  • dataobs – CIF observation data-store for the period.

  • ithread (int) – thread index.

  • fp_header_init – FLEXPART initial-condition sensitivity header.

  • ini_dates – list of initial-condition sensitivity dates.

  • inicond (dict) – initial-condition arrays.

  • inicond_sensit_tmp – thread-local accumulator for the sensitivity.

  • obs_i (int) – row index into the observation data-store.

Class for reading FLEXPART binary headers

pycif.plugins.models.lagrangian.utils.flexpart_header.read_header(self, filename)[source]#

Reading FLEXPART header file

class pycif.plugins.models.lagrangian.utils.flexpart_header.Flexpartheader[source]#

Bases: object

Class for reading FLEXPART binary headers

Routines for reading Lagrangian footprints

pycif.plugins.models.lagrangian.utils.read.read_footprint_grid(self, subdir, file_name, release_date, fp_header, stilt=False, **kwargs)[source]#

Reads footprints files. Convert s.m3/kg to s.m2/kg

Inputs:

file_name - full path name to file name fp_header - a Flexpart header object

Returns:

Array (nlon, nlat, ntime) of footprints gtime : Array (maxngrid) of file dates

Return type:

grid_fp

pycif.plugins.models.lagrangian.utils.read.read_grid(path_file, release_date, fp_header, scaleconc)[source]#

Read a FLEXPART binary footprint grid file.

Parses the Fortran-unformatted binary format (grid_time_*_001 or grid_initial_*_001) and reconstructs the sparse footprint array as a dense (nlon, nlat, ntimes) array.

Parameters:

  • path_file (str) – path to the binary footprint file.

  • release_date (pd.Timestamp) – observation release date.

  • fp_header – FLEXPART domain header object (carries grid metadata).

  • scaleconc (float) – unit scaling factor applied to the footprint.

Returns:

(grid_fp, gtime, ngrid, valid_file) where grid_fp is the dense footprint array, gtime is the list of footprint dates, ngrid is the time dimension, and valid_file is True if the file was successfully read.

Return type:

tuple

pycif.plugins.models.lagrangian.utils.read.read_grid_nc(path_file, release_date, fp_header)[source]#

Read a FLEXPART NetCDF footprint file.

Reads the spec001 variable from the NetCDF footprint file and returns a dense (nlon, nlat, ntimes) footprint array.

Parameters:

  • path_file (str) – path to the NetCDF footprint file.

  • release_date (pd.Timestamp) – observation release date.

  • fp_header – FLEXPART domain header object.

Returns:

(grid_fp, gtime, ngrid, valid_file).

Return type:

tuple

pycif.plugins.models.lagrangian.utils.read.read_grid_stilt(self, path_file, release_date, fp_header)[source]#

Read a STILT footprint CSV file.

Reads the STILT footprint format (one CSV per observation) and reconstructs a dense (nlon, nlat, nhours) footprint array matched to the CIF domain grid.

Parameters:

  • self – Lagrangian model plugin instance (carries backward_trajdays and domain).

  • path_file (str) – path to the STILT footprint CSV file.

  • release_date (pd.Timestamp) – observation release date.

  • fp_header – FLEXPART header (for grid metadata; only numpoint used).

Returns:

(grid_fp, gtime, ngrid, valid_file).

Return type:

tuple

pycif.plugins.models.lagrangian.utils.read.read_flexpart_gridinit(subdir, filename, fp_header, scaleconc=1, **kwargs)[source]#

Read a FLEXPART initial-condition sensitivity binary file.

Parses grid_initial_*_001 Fortran-binary files and reconstructs the sparse initial-condition sensitivity as a dense (nlon, nlat, nlev) array.

Parameters:

  • subdir (str) – directory containing the file.

  • filename (str) – file name (without directory).

  • fp_header – FLEXPART domain header object.

  • scaleconc (float) – unit scaling factor.

  • **kwargs – unused.

Returns:

(grid_fp, gtime, ngrid, valid_file) where grid_fp is the dense sensitivity array, gtime is the sensitivity date list, ngrid is the time dimension, and valid_file is True on success.

Return type:

tuple

pycif.plugins.models.lagrangian.utils.read.get_spec(subdir, **kwargs)[source]#

Get species name from simulation output