Skip to content

remap-weights.rst

Latest commit

 

History

History
114 lines (78 loc) · 3.77 KB

remap-weights.rst

File metadata and controls

114 lines (78 loc) · 3.77 KB
.. currentmodule:: uxarray

Remap with Weights

UXarray can apply precomputed offline remapping weights produced outside of UXarray. This is useful when weights are generated once with tools such as ESMF or TempestRemap and then reused many times across multiple ensemble members, time slices, or variables.

The core workflow is:

  1. Generate a weight file for a specific source grid and destination grid.
  2. Apply it with :meth:`UxDataArray.remap.apply_weights` or :meth:`UxDataset.remap.apply_weights`.

Basic Usage

import uxarray as ux

src = ux.open_dataset("source_grid.nc", "source_data.nc")
dst = ux.open_grid("destination_grid.nc")

remapped_temperature = src["temperature"].remap.apply_weights(dst, "map.nc")
remapped_dataset = src.remap.apply_weights(dst, "map.nc")

Repeated calls with the same path reuse a cached sparse operator, so applying the same file again in one Python session avoids rebuilding the matrix.

What A Weight File Represents

A remap weight file represents a linear operator from one grid to another:

target_values = W @ source_values

If the source grid has 4800 elements and the destination grid has 11000 elements, then:

  • source_values.shape = (4800,)
  • W.shape = (11000, 4800)
  • target_values.shape = (11000,)

So the weight file necessarily encodes both the source grid and the destination grid. It is specific to that grid pair and to the ordering of the source and destination degrees of freedom.

Supported File Structure

UXarray currently supports the standard sparse offline-map structure used by ESMF-style and TempestRemap-style map files. The essential pieces are:

  • n_a: source size
  • n_b: destination size
  • n_s: number of nonzero entries
  • row: destination indices
  • col: source indices
  • S: sparse weight values

Common aliases are also accepted:

  • src_grid_size and dst_grid_size
  • src_address and dst_address
  • weights instead of S

In full offline map files, these sparse arrays are typically accompanied by source and destination metadata such as center coordinates, corner coordinates, areas, masks, and grid-dimension metadata.

Tool Compatibility

This implementation was verified against real files from both families:

  • ESMF-generated offline map files created with ESMF_RegridWeightGen
  • TempestRemap-generated offline map files created with GenerateOfflineMap

In practice, UXarray supports the standard full offline map format used by both tools.

Currently, this API applies externally generated sparse remap files. Generating reusable UXarray weight maps can be added as a future extension.

Current caveats:

  • The source data ordering must match the source ordering encoded in the weight file.
  • Not every possible file variant is guaranteed yet.
  • ESMF weight_only outputs may require additional handling if they omit source and destination size metadata.

How It Applies Data

When remapping a :class:`UxDataArray` or :class:`UxDataset`, UXarray identifies a single spatial dimension whose size matches the source size in the loaded weights. That dimension is remapped to the requested destination dimension (faces, edges, or nodes).

Non-spatial dimensions are preserved, which makes this workflow suitable for reusing one operator across many time steps, ensemble members, or variables.

Why Use This Workflow

This path is useful when:

  • weight generation is expensive and should be done once
  • remapping needs to be repeated many times
  • external tools already produce trusted offline maps
  • you want to stay in Python for applying the map and preserving array metadata