pycif.plugins.models.wrfchem — API reference

Configuration reference: wrfchem plugin

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

Build the data-flow mapper for the WRF-Chem model.

Defines the input/output streams for WRF-Chem:

• Inputs — anthropogenic emissions (flux), meteorological lateral boundary conditions (lbc), initial concentrations (inicond), WRF namelist (namelist), WRF executable (model).

• Outputs — simulated concentrations per active species.

Uses meteo_dates for the meteorological input date grid (which may differ from input_dates).

Parameters:

• model – WRF-Chem model plugin instance.

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

• general_mapper (dict) – unused.

• backup_comps (dict) – unused.

• transforms_order (list) – unused.

• ref_transform (str) – unused.

• transform_name (str) – unused.

• **kwargs – unused.

Returns:

mapper with inputs, outputs, and outputs2inputs.

Return type:

dict

pycif.plugins.models.wrfchem.ini_periods.ini_periods(self, **kwargs)

Compute temporal discretisation for the WRF-Chem model.

Splits the full simulation window into sub-simulation periods (using self.periods if set, otherwise a single window) and derives the output and input date arrays from the WRF namelist output interval.

Sets on self:

• subsimu_dates — period boundary dates.

• tstep_dates — per-period time-step arrays (at WRF output frequency).

• meteo_dates — per-period meteorological input date arrays.

• input_dates — per-period initial/end-concentration date arrays.

• tstep_all — sorted unique merge of all time steps.

• iniobs, reset_obs — per-period observation bookkeeping flags.

• chain — per-period flag indicating chained restarts.

Parameters:

• self – WRF-Chem model plugin instance with datei, datef, and domain (WRF namelist) set.

• **kwargs – unused.

pycif.plugins.models.wrfchem.perturb_model.perturb_model(self, nsamples, transf_mapper)

Extend the WRF-Chem chemistry scheme to accommodate ensemble members.

Creates nsamples copies of each active species using the __sample#NNN naming convention, then removes the original un-suffixed species.

Note

This function currently emits debug warnings (warn) for diagnostic purposes.

Parameters:

• self – WRF-Chem model plugin instance.

• nsamples (int) – number of ensemble members.

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

pycif.plugins.models.wrfchem.run.run(self, runsubdir, mode, workdir, ddi, do_simu=True, **kwargs)

Run WRF

Parameters:

• runsubdir (str) – working directory for the current run

• mode (str) – forward or backward

• workdir (str) – pycif working directory

• do_simu (bool) – if False, considers that the simulation was already run

VERSION HISTORY

2021-08-19 Original code from online doc and from

plugins/models/lmdz/run.py

From ctdas-wrf’s wrchem utilities.

class pycif.plugins.models.wrfchem.utilities.utilities

Bases: object

Utilities for wrfchem model

static check_out_err(process)

Displays stdout and stderr, returns returncode of the process. Only makes sense if stdout and stderr are directed to PIPE, else process.communicate doesn’t see them (I think). If verbose, only display errors if there are any.

Created on Mon Jul 22 15:03:02 2019

VERSION HISTORY 2021-09-25 freum Adapted from CTDAS-WRF wrfchem_helper.py - Everything not (yet) needed is commented

@author: friedemann

class pycif.plugins.models.wrfchem.wrfchem_helper.WRFChemHelper(settings)

Bases: object

Contains helper functions for sampling WRF-Chem

static read_namelist(nml_file)

Read run settings from namelist file

static get_int_coefs(pb_ret, pb_mod, level_def)

Computes a coefficients matrix to transfer a model profile onto a retrieval pressure axis.

If level_def==”layer_average”, this assumes that profiles are constant in each layer of the retrieval, bound by the pressure boundaries pb_ret. In this case, the WRF model layer is treated in the same way, and coefficients integrate over the assumed constant model layers. This works with non-staggered WRF variables (on “theta” points). However, this is actually not how WRF is defined, and the implementation should be changed to z-staggered variables. Details for this change are in a comment at the beginning of the code.

If level_def==”pressure_boundary” (IMPLEMENTATION IN PROGRESS), assumes that profiles, kernel and pwf are defined at pressure boundaries that don’t have a thickness (this is how OCO-2 data are defined, for example). In this case, the coefficients linearly interpolate adjacent model level points. This is incompatible with the treatment of WRF in the above-described layer-average assumption, but is closer to how WRF is actually defined. The exception is that pb_mod is still constructed and non-staggered variables are not defined at psurf. This can only be fixed by switching to z-staggered variables.

In cases where retrieval surface pressure is higher than model surface pressure, and in cases where retrieval top pressure is lower than model top pressure, the model profile will be extrapolated with constant tracer mixing ratios. In cases where retrieval surface pressure is lower than model surface pressure, and in cases where retrieval top pressure is higher than model top pressure, only the parts of the model column that fall within the retrieval presure boundaries are sampled.

pb_ret (array_like)

Pressure boundaries of the retrieval column

pb_mod (array_like)

Pressure boundaries of the model column

level_def (string)

“layer_average” or “pressure_boundary” (IMPLEMENTATION IN PROGRESS). Refers to the retrieval profile.

Note 2021-09-13: Inspected code for pressure_boundary. Should be correct. Interpolates linearly between two model levels.

coefs (array_like)

Integration coefficient matrix. Each row sums to 1.

import numpy as np

from ….utils.check.errclass import CifValueError

pb_ret = np.linspace(900., 50., 5) pb_mod = np.linspace(1013., 50., 7) model_profile = 1. - np.linspace(0., 1., len(pb_mod)-1)**3 coefs = get_int_coefs(pb_ret, pb_mod, “layer_average”) retrieval_profile = np.matmul(coefs, model_profile)

static times_in_wrf_file(filename)

Returns the times in netcdf file as datetime object

wrf_times(file_list)

Read all times in a list of wrf files

Output

• 1D-array containing all times

• 1D-array containing start indices of each file

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

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

VERSION HISTORY 2021-10-06 freum Added code for namelist and model 2021-10-01 aberchet Defined ddi and ddf before call to make_fluxes 2021-09-09 freum Temporarily replaced NotImplementedErrors with logging.info to run WRF with preprocessed input data 2021-08-17 freum Original modified from models/lmdz

pycif.plugins.models.wrfchem.io.outputs2native.outputs2native(self, data2dump, input_type, di, df, runsubdir, mode='fwd', dump=True, onlyinit=False, check_transforms=False, **kwargs)

Reads outputs to pyCIF objects.

If the mode is ‘fwd’ or ‘tl’, only observation-like outputs are extracted. For the ‘adj’ mode, all outputs relative to model sensitivity are extracted.

Dumps to a NetCDF file with output concentrations if needed

pycif.plugins.models.wrfchem.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)

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.wrfchem.io.inputs.make_auxiliary.make_auxiliary(self, ddi, runsubdir, onlyinit=False, do_simu=True, mode='fwd', **kwargs)

Set up the WRF-Chem run directory and namelist for one sub-period.

Copies or links the WRF executable and updates the WRF namelist (namelist.input) with the correct start/end date and output interval for this period, then creates the required sub-directory structure under runsubdir.

Returns immediately when do_simu=False or onlyinit=True.

Parameters:

• self – WRF-Chem model plugin instance with workdir set.

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

• runsubdir (str) – path to the period run directory.

• onlyinit (bool) – skip if True.

• do_simu (bool) – skip if False.

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

• **kwargs – unused.

pycif.plugins.models.wrfchem.io.inputs.make_endconcs.make_endconcs(self, datastore, runsubdir, ddi, mode)

Link restart file from chain directory. It was put there by the previous simulation at the end of run.py

pycif.plugins.models.wrfchem.io.inputs.make_fluxes.make_fluxes(self, datastore, runsubdir, datei, datef, mode)

Write fluxes to WRF flux input files

Parameters:

• self (pycif.utils.classes.fluxes.Flux) – Flux plugin with all attributes

• datastore (dict) – information on flux species

• runsubdir (str) – directory of the current run

• datei (datetime.datetime)

• datef (datetime.datetime)

• mode (str) – running mode: ‘fwd’, ‘tl’ or ‘adj’

pycif.plugins.models.wrfchem.io.inputs.make_inicond.make_inicond(self, datastore, runsubdir, datei, mode)

Write or symlink the WRF-Chem initial concentration file wrfinput_d01.

Mirrors the logic of the CHIMERE make_inicond: links from disk when no CIF-modified data exists, otherwise copies and overwrites the relevant species variables.

Parameters:

• self – WRF-Chem model plugin instance.

• datastore (dict) – tracer-ID-keyed CIF data-store entries.

• runsubdir (str) – path to the period run directory.

• datei (datetime) – period start date.

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

pycif.plugins.models.wrfchem.io.inputs.make_latcond.make_latcond(self, datastore, runsubdir, datei, mode)

Generates boundary conditions files for wrf (Could merge with make_inicond, it’s pretty much the same)

Parameters:

• self

• datastore (dict)

• runsubdir (str)

• mode

Returns:

pycif.plugins.models.wrfchem.io.inputs.params.update_namelist_file(namelist, datei, datef, is_restart, runsubdir)

Update namelist.input file for run

Updated values: - start time, end time - restart timestep - restart flag

Note: format of namelist.input is slightly different after running this: - 19, 19, -> 19, 19 - 00 -> 0 - 2. -> 2.0 - “wrfchemi_d<domain>_<date>” -> “wrfchemi_d<domain>_<date>” This could be adjusted in f90nml settings, but it doesn’t seem to matter to WRF.

VERSION HISTORY 2021-10-06 freum Replaced instances of ‘self’ with instances of

‘namelist’, fixed call to f90nml.patch

2021-09-26 freum Misc - commented restart timestep and interval - added runsubdir as argument 2021-08-18 freum Modified from CTDAS - replaced dates - commented fp_original

pycif.plugins.models.wrfchem.io.outputs.endconcs.fetch_end(self, data2dump, runsubdir, mode, ddi, ddf)

Stub for registering WRF-Chem restart paths after a run.

WRF-Chem manages end-concentrations through wrfrst restart files which are handled directly in run.py and make_endconcs. This function returns an empty fileorig entry for each tracer to maintain API compatibility.

Parameters:

• self – WRF-Chem model plugin instance.

• data2dump (dict) – tracer-ID-keyed data-store entries to update.

• runsubdir (str) – path to the period run directory (unused).

• mode (str) – 'fwd', 'tl', or 'adj' (unused).

• ddi (datetime) – period start date (unused).

• ddf (datetime) – period end date (unused).

Returns:

data2dump with empty dicts for each tracer.

Return type:

dict

pycif.plugins.models.wrfchem.io.outputs.read_sim.read_sim(self, data2dump, runsubdir, mode, ddi, ddf)

Read simulated observations from WRF-Chem output