Source code for healpix_resample.bilinear

"""
bilinear.py

GPU-friendly sparse HEALPix regridding from unstructured lon/lat samples
to a subset of HEALPix pixels at a target resolution (nside = 2**level).

Core ideas:
- Use npt=4.

This module is designed for large N and batched values (B,N) on CUDA.
"""
from typing import Optional

import math
import numpy as np
import torch

from healpix_resample.base import ResampleResults, T_Array
from healpix_resample.knn import KNeighborsResampler, _conservative_resample


[docs] class BilinearResampler(KNeighborsResampler): """Bilinear (Npt=4, inverse-distance weighted) HEALPix resampler. Parameters ---------- area : array-like or None Per-sample pixel area/weight, shape ``(N,)``. Only used by ``resample(conservative=True)`` (see below) -- ignored by the default interpolation path. Defaults to ``1.0`` for every sample (equal-area pixels / already-extensive quantities), the same convention as :class:`~healpix_resample.conservative.ConservativeResampler`. All other parameters are forwarded to ``KNeighborsResampler``. """
[docs] def __init__(self, *args, area: Optional[T_Array] = None, **kwargs): super().__init__(Npt=4, *args, **kwargs) if area is None: area_t = torch.ones(self.N, dtype=self.dtype, device=self.device) else: area_t = area if isinstance(area, torch.Tensor) else torch.as_tensor(area) area_t = area_t.to(self.device, dtype=self.dtype).reshape(-1) if area_t.numel() != self.N: raise ValueError( f"area must have {self.N} elements (one per sample), got {area_t.numel()}" ) if torch.any(area_t < 0): raise ValueError("area must be non-negative") self.area = area_t
def _distance_weights(self, d: torch.Tensor, rows: Optional[torch.Tensor] = None) -> torch.Tensor: # inverse-distance weights per sample->cell link (Npt=4, and the # tied links); `M`, `MT` and `M_cons` are assembled by # `KNeighborsResampler` (`M` per-cell normalised; `MT` / `M_cons` # per-sample normalised, built on first access -- see # `KNeighborsResampler.comp_matrix`). return 1 / (1e-6 + d / self.sigma_m) @torch.no_grad() def resample(self, val: T_Array, *, conservative: bool = False, **kwargs) -> ResampleResults[T_Array]: """Estimate the HEALPix field from unstructured samples. Args: val: (N,) or (B, N) values at lon/lat sample points. conservative: see below. Extra ``**kwargs`` (``lam``, ``max_iter``, ``tol``, ``x0``, ``return_info``) are accepted for signature symmetry with other resamplers and forwarded to ``KNeighborsResampler.resample()`` when ``conservative=False`` -- none of them actually change anything for this class (no CG solve involved either way), and they are ignored when ``conservative=True``. ``conservative=False`` (default) --------------------------------- The usual bilinear interpolation: each cell's value is a weighted blend of its 4 nearest samples (inverse-distance weights, normalized per cell via ``self.M``) -- smooth, but *not* exactly mass-conserving (a cell's weights are renormalized against whichever samples happen to link to it, independent of any other cell). ``conservative=True`` (issue #44: "conservative bi-linear") -------------------------------------------------------------- Each sample's own value (scaled by its ``area``, see ``__init__``) is instead redistributed across its own 4 nearest cells using ``self.M_cons`` -- the *same* inverse-distance weights, but normalized so each sample's own weights sum to exactly 1 (a partition of unity), rather than normalizing per output cell. No value is invented or lost: sum_k hval[k] == sum_i (valid i) val[i] * area[i] exactly, regardless of how many samples any given cell happens to receive contributions from. This trades a small amount of interpolation "sharpness" (identical weights to the non-conservative path, just redistributed the other way) for an unconditional global conservation guarantee -- a bilinear-weighted analogue of :class:`~healpix_resample.conservative.ConservativeResampler`'s exact area conservation, without that class's single-nearest-cell binning blockiness. NaN handling (``conservative=True`` only -- ``conservative=False``'s NaN behaviour is documented on the inherited ``KNeighborsResampler.resample()``): a NaN sample's value *and* its area are excluded from every cell's total, so the exact identity above holds over precisely the valid samples. This is a cleaner guarantee than the interpolation path's NaN handling, which only zeroes a NaN sample's contribution without renormalizing the *other* samples sharing a cell -- ``conservative=True`` needs no such caveat, because ``self.M_cons``'s per-sample normalization is fixed at construction time and never renormalizes per output cell. A batch row where every sample is NaN comes back entirely ``nan``. Returns: hval: (B, K) or (K,) """ if not conservative: return super().resample(val, **kwargs) return _conservative_resample(self, val, self.area)