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

Configuration reference: regrid plugin

pycif.plugins.transforms.basic.regrid.adjoint.adjoint(transf, inout_datastore, controlvect, obsvect, mapper, ddi, ddf, mode, runsubdir, workdir, onlyinit=False, save_debug=False, **kwargs)

Adjoint horizontal re-gridding: transpose the weight matrix.

Reloads the same interpolation weights as the forward pass and applies the transposed operation: each output cell’s adj_out value is distributed back to the input cells weighted by the same coefficients used in the forward.

Parameters:

• transf (Plugin) – regrid instance.

• inout_datastore (dict) – mutable datastore.

• controlvect – unused.

• obsvect – unused.

• mapper (dict) – transform mapper.

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

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

• mode (str) – 'adj'.

• runsubdir (str) – unused.

• workdir (str) – unused.

• onlyinit (bool) – if True and non-sparse, return immediately.

• save_debug (bool) – passed to do_regridding_adj().

• **kwargs – unused.

pycif.plugins.transforms.basic.regrid.adjoint.do_regridding_adj(data, nlat_in, nlon_in, nlat_out, nlon_out, weights, min_weight=1e-10, is_sparse_in=False, is_sparse_out=False, save_debug=False, transf=None)

Apply the transposed regridding weights to adjoint sensitivity data.

For gridded data, scatters output sensitivities back to input cells via np.add.at. For sparse output, distributes the observation sensitivity to each contributing input cell weighted by the regridding coefficients.

Parameters:

• data – the output-domain sensitivity (xarray DataArray for gridded, DataFrame for sparse).

• nlat_in (int) – input domain dimensions.

• nlon_in (int) – input domain dimensions.

• nlat_out (int) – output domain dimensions.

• nlon_out (int) – output domain dimensions.

• weights (dict) – regridding weight dict with keys 'i', 'j', 'wgt', and optionally 'filtered'.

• min_weight (float) – minimum weight threshold; lower weights are zeroed.

• is_sparse_in (bool) – True if the input is observation-indexed.

• is_sparse_out (bool) – True if the output is observation-indexed.

• save_debug (bool) – unused (kept for API consistency).

• transf (Plugin) – unused (kept for API consistency).

Returns:

adjoint sensitivity on the input domain.

Return type:

xarray.DataArray or pd.DataFrame

Raises:

Exception – if is_sparse_in = True and is_sparse_out = False (not yet implemented).

pycif.plugins.transforms.basic.regrid.forward.forward(transf, inout_datastore, controlvect, obsvect, mapper, ddi, ddf, mode, runsubdir, workdir, onlyinit=False, save_debug=False, **kwargs)

Reprojects data from the input domain to the output domain.

Computes or reloads interpolation weights (from the dir_wgt directory when available) and applies them to the 'spec' (and 'incr' in TL mode) arrays. Handles four data configurations:

• Array → Array (gridded field to gridded field)

• Sparse → Array (obs-indexed data scattered onto a grid)

• Array → Sparse (gridded field sampled at obs locations)

• Sparse → Sparse (obs-indexed to obs-indexed)

Parameters:

• transf (Plugin) – regrid instance (carries method, min_weight, dir_wgt, dir_regrid).

• inout_datastore (dict) – mutable datastore.

• controlvect – unused.

• obsvect – unused.

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

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

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

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

• runsubdir (str) – unused.

• workdir (str) – unused.

• onlyinit (bool) – if True and input is sparse, return immediately.

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

• **kwargs – unused.

pycif.plugins.transforms.basic.regrid.forward.do_regridding(datastore_out, data, nlat_in, nlon_in, nlat_out, nlon_out, weights, min_weight=1e-10, is_sparse_in=False, is_sparse_out=False, save_debug=False, transf=None, nthreads=1)

pycif.plugins.transforms.basic.regrid.utils.bilinear.bilinear(domain_in, nlon_in, nlat_in, zlon_in, zlat_in, zlon_out, zlat_out)

pycif.plugins.transforms.basic.regrid.utils.find_gridcells.find_gridcells(domain_in, domain_out, forward_direction=True, grid_to_surface=False, chunksize=2000000.0)

pycif.plugins.transforms.basic.regrid.utils.find_gridcells.find_gridcell(lon, lat, zlonc, zlatc, orig_proj='epsg:4326', isregular=False, is_unstructured=False, discont=180)

Finds the grid cell corresponding to a coordinate.

Parameters:

• lon (np.array) – longitude of the point to find

• lat (np.array) – latitude of the point to find

• zlonc (np.array) – longitudes of the corners of the grid

• zlatc (np.array) – latitudes of the corners of the grid

• orig_proj (projection) – the projection for reporting coordinates. Default is WSG84

• isregular (Boolean) – if True, simplified operations are computed. Default is False

Returns:

i, j the grid cell ID

Notes

• For very regular grids, this script could be made more effileient

and shorter, but the objective is to be able to deal with any domain - zlonc and zlatc must be in ascending order

pycif.plugins.transforms.basic.regrid.utils.get_weights.get_weights(transform, trid, mapper, domain_in, domain_out, is_lbc, ddi, is_sparse_in=False, is_sparse_out=False, **kwargs)

pycif.plugins.transforms.basic.regrid.utils.get_weights.copy_weights(transform, mapper, domain_in, domain_out, ddi, is_sparse_in, is_sparse_out, trid)

pycif.plugins.transforms.basic.regrid.utils.reproject.reproject_emissions(emis_orig, zlonc_orig, zlatc_orig, zlonc_target, zlatc_target, resol=10, option='mean', wk_proj='wgs84', orig_regular=True, return_weight=False, orig_unstructured=False, orig_lon_cyclic=False, target_unstructured=False, rounding_domain=8)

pycif.plugins.transforms.basic.regrid.utils.reproject.domain2polygons(zlonc_target, zlatc_target, wk_proj='wgs84', data=None, is_regular=True)

pycif.plugins.transforms.basic.regrid.utils.reproject.zonal_stats(feat, raster, resol=10, option='mean', return_weight=False, orig_lon_cyclic=False, **kwargs)

pycif.plugins.transforms.basic.regrid.utils.reproject.loop_zonal_stats(lyr, raster, resol=10, option='mean', return_weight=False, orig_lon_cyclic=False)

pycif.plugins.transforms.basic.regrid.utils.conservative.conservative.conservative(domain_in: Domain, domain_out: Domain, chunk_size: int | None = None, processes: int | None = None) → dict[str, ndarray]

Compute indices and weigths for conservative interpolation between unstructured or regular grids.

Parameters:

• domain_in (Domain) – Input domain plugin.

• domain_out (Domain) – Output domain plugin.

• chunk_size (int, optional) – Chunk size in the latitude bins. Defaults to None.

• processes (int, optional) – Number of processes. Defaults to None.

Returns:

dict with keys “i”, “j” and “wgt”

pycif.plugins.transforms.basic.regrid.utils.conservative.weights.compute_weights_unstructured(lon_vertices_out: ndarray[tuple[Any, ...], dtype[floating]], lat_vertices_out: ndarray[tuple[Any, ...], dtype[floating]], cell_area_out: ndarray[tuple[Any, ...], dtype[floating]] | None, lon_vertices_in: ndarray[tuple[Any, ...], dtype[floating]], lat_vertices_in: ndarray[tuple[Any, ...], dtype[floating]], cell_area_in: ndarray[tuple[Any, ...], dtype[floating]] | None, chunk_size: int | None = None, processes: int | None = None, use_numba: bool = True) → tuple[ndarray[tuple[Any, ...], dtype[signedinteger]], ndarray[tuple[Any, ...], dtype[floating]]]

Compute indices and weigths for conservative interpolation between unstructured grids.

Parameters:

• lon_vertices_out (2D array (M1, N1)) – Output grid longitudes of the vertices of each cell.

• lat_vertices_out (2D array (M1, N1)) – Output grid latitudes of the vertices of each cell.

• cell_area_out (1D array (M1) or None) – Precomputed areas of each cell of the output grid.

• lon_vertices_in (2D array (M2, N2)) – Input grid longitudes of the vertices of each cell.

• lat_vertices_in (2D array (M2, N2)) – Input grid latitudes of the vertices of each cell.

• cell_area_in (1D array (M2) or None) – Precomputed areas of each cell of the input grid.

• chunk_size (int, optional) – Chunk size in the latitude bins. Defaults to None.

• processes (int, optional) – Number of processes. Defaults to None.

• use_numba (bool, optional) – Use Numba if available, only used for unit tests. Defaults to True.

Returns:

Indices and weights

for interpolation.

Return type:

2D array of int (M1, K), 2D array of float (M1, K)