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
NptKNN 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 (
floatorNone) – Only used without_cell_ids. A requested cell that the KNN rings did not reach is filled with its nearest sample only if that sample lies withinmax_distance_mmetres 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 theNptnearest cells of every sample (the KNN links ofKNeighborsResampler), the cells they miss from a KD-tree."kdtree"(without_cell_idsonly): 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_mthen 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_maxrings (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_maxbelowring_search_initis raised to itlevel – 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
levelcells 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 withK = 0instead of raising:resample()then returnscell_idsof size 0 andcell_dataof shape(B, 0), exceptNearestResampler, whose fallback fills the requested cells with their nearest sample (see itsmax_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
neighboursattribute): the neighbour search is skipped and the distances computed again, so the resampler is the same, bit for bit. WithNpt=1it is ignored.
- Raises:
RuntimeError – without
out_cell_ids, when no cell passesthreshold(lowerthresholdor widen the neighbourhood rings), or when cells pass it but no sample reaches any of them withinring_search_maxrings.
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
MTSparse CSR
(K, N)operator, cells -> samples (invert()); built on first access.M_consSparse CSR
(N, K)conservative operator (resample(conservative=True), same links asM, each sample's weights summing to 1); built on first access.