pycif.plugins.transforms.basic.vertical_interpolation — API reference

pycif.plugins.transforms.basic.vertical_interpolation — API reference#

Configuration reference: vertical_interpolation plugin

pycif.plugins.transforms.basic.vertical_interpolation.adjoint.adjoint(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)[source]#

Adjoint vertical interpolation: scatter observation sensitivities back to model levels.

Dispatches to the sparse or array adjoint implementation. For sparse output (observation-indexed data), scatters adj_out from each observation back to the model level(s) it corresponds to. For array output, applies the transposed interpolation weights.

Parameters:

  • transf (Plugin) – vertical_interpolation instance (carries sparse_out, sampled_out).

  • inout_datastore (dict) – mutable datastore.

  • controlvect – unused.

  • obsvect – unused.

  • mapper (dict) – transform mapper.

  • di (datetime) – sub-simulation start date.

  • df (datetime) – sub-simulation end date.

  • mode (str) – 'adj'.

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • onlyinit (bool) – if True (array path), return immediately.

  • **kwargs – forwarded to the sparse/array implementations.

pycif.plugins.transforms.basic.vertical_interpolation.forward.forward(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, save_debug=False, **kwargs)[source]#

Vertically interpolate model fields to observation pressure/height levels.

Dispatches to either the sparse/sampled or gridded (array) implementation:

  • Sparse/sampled output — sparse_forward(): extracts model values at the observation vertical coordinate.

  • Array output — array_forward(): applies the configured interpolation method (static-levels, linear, closest, match-layer, or layer-weighted) to the full gridded field.

Parameters:

  • transf (Plugin) – vertical_interpolation instance (carries method, coord_in, coord_out, ignore_level, and optional file_statlev).

  • inout_datastore (dict) – mutable datastore.

  • controlvect – unused.

  • obsvect – unused.

  • mapper (dict) – transform mapper (carries sparse_data, sampled, and domain objects).

  • di (datetime) – sub-simulation start date.

  • df (datetime) – sub-simulation end date.

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

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • onlyinit (bool) – passed to the sparse/array implementations.

  • save_debug (bool) – if True, save intermediate results.

  • **kwargs – forwarded to the sparse/array implementations.

pycif.plugins.transforms.basic.vertical_interpolation.utils.array.adjoint.array_adjoint(transf, mapper, inout_datastore, ddi, onlyinit, **kwargs)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.array.closest.closest_fwd(transf, pres_in, pres_out, mode, inout_datastore, trid, ddi, mapper)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.array.closest.closest_adj(transf, pres_in, pres_out, nlev_in, nlev_out, inout_datastore, trid, ddi)[source]#

Adjoint of the closest-level method for gridded fields.

Pairs output and input levels greedily by increasing pressure distance (each level used at most once) and propagates the output sensitivity to the paired input level.

Parameters:

  • transf (Plugin) – vertical_interpolation instance (unused).

  • pres_in (np.ndarray) – input level mid-point pressures.

  • pres_out (np.ndarray) – output level mid-point pressures.

  • nlev_in (int) – number of input levels.

  • nlev_out (int) – number of output levels.

  • inout_datastore (dict) – mutable datastore; reads outputs[trid][ddi]["adj_out"], writes inputs[trid][ddi].

  • trid (tuple) – tracer identifier.

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

pycif.plugins.transforms.basic.vertical_interpolation.utils.array.forward.array_forward(transf, mapper, inout_datastore, ddi, mode, onlyinit, **kwargs)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.array.linear.linear_fwd(transf, pres_in, pres_out, mode, inout_datastore, trid, ddi)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.array.linear.linear_adj(transf, pres_in, pres_out, nlev_in, inout_datastore, trid, ddi)[source]#

Adjoint of linear_fwd() for gridded fields.

Scatters each output-level sensitivity back to the two bracketing input levels, with the same linear weights as in the forward.

Parameters:

  • transf (Plugin) – vertical_interpolation instance (carries fill_nans).

  • pres_in (np.ndarray) – input level mid-point pressures.

  • pres_out (np.ndarray) – output level mid-point pressures.

  • nlev_in (int) – number of input levels.

  • inout_datastore (dict) – mutable datastore; reads outputs[trid][ddi]["adj_out"], writes inputs[trid][ddi].

  • trid (tuple) – tracer identifier.

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

pycif.plugins.transforms.basic.vertical_interpolation.utils.array.weight.weight_matrix(pres_in, pres_out)[source]#

Compute the layer-weighted remapping matrix.

W[k, i] is the fraction of output layer k covered by input layer i, in pressure (or log10-pressure) thickness, normalized so that each row covering at least one input layer sums to 1. Rows of output layers entirely outside the input column are zero.

pres_in and pres_out can be ordered in opposite directions: the weights are then computed on the reversed outputs and the rows flipped back to the original output order.

Parameters:

  • pres_in (np.ndarray) – input layer interfaces, nlev_in + 1 values, monotonic.

  • pres_out (np.ndarray) – output layer interfaces, nlev_out + 1 values, monotonic.

Returns:

weight matrix of shape (nlev_out, nlev_in).

Return type:

np.ndarray

pycif.plugins.transforms.basic.vertical_interpolation.utils.array.weight.weight_fwd(transf, pres_in, pres_out, mode, inout_datastore, trid, ddi, mapper)[source]#

Layer-weighted (conservative) vertical remapping of a gridded field.

Each output layer, bounded by two consecutive interfaces of pres_out, receives the average of the input layers it overlaps, weighted by the pressure thickness of the overlap (i.e., a mass-weighted average for mixing ratios):

out[k] = sum_i(dp_overlap(k, i) * in[i]) / sum_i(dp_overlap(k, i))

The weights are computed by weight_matrix(). Interface pressures are converted to fractional input-interface indices by linear interpolation in pressure. Output interfaces outside the input column are clamped to the column edges, so a partially covered output layer is averaged over its covered part only; an output layer entirely outside the input column is set to 0.

If transf.log_interp is True, pres_in and pres_out are log10-pressures (converted in array_forward()): the weights are then log-pressure thicknesses and the result is no longer a mass-weighted average.

Called by array_forward() when transf.method is 'layer-weighted'.

Parameters:

  • transf (Plugin) – vertical_interpolation instance (unused).

  • pres_in (np.ndarray) – input layer interfaces, nlev_in + 1 values, monotonic. Pressure, or log10-pressure if transf.log_interp.

  • pres_out (np.ndarray) – output layer interfaces, nlev_out + 1 values, monotonic. Same unit as pres_in.

  • mode (str) – 'fwd' to process spec only; 'tl' to also process incr (with the same, linear, weights).

  • inout_datastore (dict) – mutable datastore; reads inputs[trid][ddi], writes outputs[trid][ddi].

  • trid (tuple) – tracer identifier.

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

  • mapper (dict) – transform mapper (unused).

Notes

Output arrays are xr.DataArray of dims (time, lev, lat, lon) with nlev_out levels.

pycif.plugins.transforms.basic.vertical_interpolation.utils.array.weight.weight_adj(transf, pres_in, pres_out, inout_datastore, trid, ddi)[source]#

Adjoint of weight_fwd() for gridded fields.

Applies the transpose of the forward weight matrix W (see weight_matrix()):

adj_in[i] = sum_k(W[k, i] * adj_out[k])
Parameters:

  • transf (Plugin) – vertical_interpolation instance (unused).

  • pres_in (np.ndarray) – input layer interfaces, nlev_in + 1 values. Pressure, or log10-pressure if transf.log_interp; must be the same as in the forward.

  • pres_out (np.ndarray) – output layer interfaces, nlev_out + 1 values, monotonic. Same unit as pres_in.

  • inout_datastore (dict) – mutable datastore; reads outputs[trid][ddi]["adj_out"], writes inputs[trid][ddi].

  • trid (tuple) – tracer identifier.

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

pycif.plugins.transforms.basic.vertical_interpolation.utils.sparse.adjoint.sparse_adjoint(transf, mapper, inout_datastore, ddi, onlyinit, **kwargs)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.sparse.forward.sparse_forward(transf, mapper, inout_datastore, ddi, onlyinit, mode, **kwargs)[source]#
pycif.plugins.transforms.basic.vertical_interpolation.utils.sparse.vcoordfromfile.vcoordfromfile(datastore, file_lev, **kwargs)[source]#

Computes vertical levels from pre-defined file

Parameters:

  • datastore (dict) – dictionary of pd.Dataframes containing measurement informations

  • file_lev (str) – path to the file defining station levels