healpix_resample.NearestResampler#

class healpix_resample.NearestResampler(*args, Npt=9, max_distance_m=None, search='knn', **kwargs)[source]#

Nearest-neighbour HEALPix resampler — no sparse matrices.

Uses Npt KNN neighbours (default 9) to robustly find the nearest source for every HEALPix cell, even when the output grid is finer than the input.

Parameters:
  • Npt (int) – Number of HEALPix neighbours per source sample used by the KNN. Larger values cover more cells at the cost of more memory during construction. Default 9 is a good trade-off for most use cases.

  • max_distance_m (float or None) – Only used with out_cell_ids. A requested cell that the KNN rings did not reach is filled with its nearest sample only if that sample lies within max_distance_m metres of the cell centre; otherwise the cell is left out of the result, like the cells the interpolating resamplers cannot compute. None (default) fills every requested cell, however far its nearest sample is.

  • search ({"knn", "kdtree"}) – How the nearest sample of each cell is found. "knn" (default): through the Npt nearest cells of every sample (the KNN links of KNeighborsResampler), the cells they miss from a KD-tree. "kdtree" (with out_cell_ids only): every requested cell takes its nearest sample from a KD-tree of the samples, directly: the same sample (the KNN path keeps, per cell, the linked sample of largest Gaussian weight, i.e. the nearest), several times faster on dense inputs, and no KNN links (neighbours) to search or keep. Samples exactly as near as each other may be picked differently. On a CUDA device (nested cells), the search runs on the GPU from HEALPix buckets of the samples (_nearest_source_buckets): the same samples as the KD-tree, ties apart. max_distance_m then applies to every requested cell (the KNN path applies it only to the cells its rings did not reach).

  • All other parameters are forwarded to ``KNeighborsResampler``.

__init__(*args, Npt=9, max_distance_m=None, search='knn', **kwargs)[source]#

Pre-compute sparse operators.

Parameters:
  • lon_deg, lat_deg – unstructured sample coordinates in degrees, shape (N,); float32 or float64, the geometry is computed in float64

  • Npt – number of nearest HEALPix cells used per sample. A sample that does not find Npt kept cells within ring_search_max rings (samples much sparser than the cells) keeps the ones it found.

  • ring_search_init, ring_search_max – first and last HEALPix ring of the per-sample neighbour search; a ring_search_max below ring_search_init is raised to it

  • level – HEALPix level, nside = 2**level

  • sigma_m – Gaussian length scale (meters). If None, uses the HEALPix pixel scale sigma = sqrt(4*pi/(12*4**level))*R.

  • threshold – keep only HEALPix cells whose global weight sum >= threshold

  • nest – HEALPix indexing scheme

  • dtype/device – torch dtype/device for all matrices and computations

  • out_cell_ids – optional subset of level cells to restrict the output to (e.g. one chunk or one parent cell). If none of these cells has enough support among the samples, the operator is built with K = 0 instead of raising: resample() then returns cell_ids of size 0 and cell_data of shape (B, 0), except NearestResampler, whose fallback fills the requested cells with their nearest sample (see its max_distance_m).

  • batch_size – process the samples in slices of this size when building the operators (see healpix_weighted_nearest): the temporary memory of the neighbour search is then about 2 kB per sample of a slice instead of 2 kB per sample. None (default) processes all samples at once. The result is the same.

  • coarse_level_delta – number the cells of the neighbour search from their parents this many levels coarser (nested only; see healpix_weighted_nearest): the same cells, neighbours and ties as the fine-level search, in less time and memory. None (default): the fine-level search.

  • neighbours – the links (NeighbourLinks) of an earlier resampler on the same samples, level and search parameters (its neighbours attribute): the neighbour search is skipped and the distances computed again, so the resampler is the same, bit for bit. With Npt=1 it is ignored.

Raises:

RuntimeError – without out_cell_ids, when no cell passes threshold (lower threshold or widen the neighbourhood rings), or when cells pass it but no sample reaches any of them within ring_search_max rings.

Methods

__init__(*args[, Npt, max_distance_m, search])

Pre-compute sparse operators.

comp_matrix()

Build hi_k (K,) — nearest source index per HEALPix cell.

get_cell_ids()

invert(hval)

HEALPix cells → source samples.

resample(val, **_kwargs)

Source samples → HEALPix cells.

Attributes

MT

Sparse CSR (K, N) operator, cells -> samples (invert()); built on first access.

M_cons

Sparse CSR (N, K) conservative operator (resample(conservative=True), same links as M, each sample's weights summing to 1); built on first access.