healpix_resample.CloughTocherResampler#

class healpix_resample.CloughTocherResampler(lon_deg, lat_deg, level, *, nest=True, radius=6371000.0, ellipsoid='WGS84', dtype=torch.float64, device=None, verbose=True, out_cell_ids=None, candidate_ring_expand=3, grad_det_floor_rel=1e-09, num_threads=0)[source]#

Delaunay triangulation + Clough-Tocher C1 cubic HEALPix resampler.

Unlike every other resampler in this package, this class does not subclass KNeighborsResampler: that base class’s __init__/ comp_matrix() orchestration is built around the KNN/Gaussian-threshold geometry model (healpix_weighted_nearest, Npt, sigma_m, threshold), none of which apply to a triangulation-based construction – there is no fixed neighbour count, no Gaussian weight, and no distance threshold here. This is a deliberate design choice, not an oversight; see planning/05_clough_tocher_resampler.md.

It still follows every other shared convention from planning/00_init.md: generic NumPy/Torch in/out symmetry, (N,)/ (B, N) batching, @torch.no_grad() on resample(), returning ResampleResults (cg_residual_norms/cg_niters are always None here – no CG solve is involved), plus self.cell_ids, self.K, self.N, get_cell_ids().

What it computes#

A genuine bivariate Delaunay/Clough-Tocher interpolant (exact at input sample points, C1 across triangle edges), not a radial kernel sum – see the module docstring for the full comparison against BicubicResampler. Vertex gradients are estimated by a local least-squares plane fit over each vertex’s Delaunay 1-ring (see _build_gradient_operators); this is a standard, but not scipy- identical, Clough-Tocher construction (see module docstring).

Output validity: a candidate HEALPix cell is only kept in self.cell_ids if its projected center falls inside the convex hull of the (projected) input samples – Clough-Tocher, like scipy.interpolate.griddata, does not extrapolate.

Parameters:

  • lon_deg, lat_deg (array-like, shape (N,)) – Unstructured sample coordinates in degrees. Must span a regional/local extent (see the module docstring’s gnomonic- projection caveat) – __init__ raises if any sample is not well inside the projection’s valid hemisphere around the sample centroid.

  • level (int) – HEALPix level (nside = 2**level) for candidate/output cells.

  • nest (bool) – HEALPix indexing scheme.

  • radius (float) – Sphere radius (meters); only affects the projected-plane length scale (sigma_m-style quantities are not used by this resampler).

  • ellipsoid (str) – Passed through to healpix_geo.

  • dtype, device (torch.dtype, torch.device) – dtype and device used for self.Gx, self.Gy and self.M.

  • verbose (bool) – Print a one-line construction summary.

  • out_cell_ids (array-like or None) – Optional caller-supplied subset of HEALPix cell ids (at level) to further restrict the output to, intersected with the convex-hull criterion above.

  • candidate_ring_expand (int) – Number of fine-level HEALPix rings to expand the sample footprint by when enumerating candidate output cells, before filtering to “inside the convex hull” – see _candidate_output_cells. The exact value doesn’t affect correctness (over-generous candidates are just dropped by the hull test), only whether the hull is fully covered; the default is comfortably generous for any reasonably-dense point cloud relative to level.

  • grad_det_floor_rel (float) – Relative floor applied to the 2x2 normal-equation determinant in _build_gradient_operators, guarding near-singular vertex 1-rings.

  • Attributes (after construction)

  • ———————————

  • N, K, cell_ids – As in every other resampler.

  • points2d (numpy.ndarray) – Shape (N, 2) – samples projected to the local gnomonic tangent plane.

  • tri – The scipy.spatial.Delaunay triangulation object.

  • Gx, Gy (torch.Tensor) – Sparse (N, N) – grad_x = Gx @ f, grad_y = Gy @ f for any sample-space field f.

  • M (torch.Tensor) – Sparse CSR (N, K) – hval = y @ M.

__init__(lon_deg, lat_deg, level, *, nest=True, radius=6371000.0, ellipsoid='WGS84', dtype=torch.float64, device=None, verbose=True, out_cell_ids=None, candidate_ring_expand=3, grad_det_floor_rel=1e-09, num_threads=0)[source]#

Methods

__init__(lon_deg, lat_deg, level, *[, nest, ...])

get_cell_ids()

invert(hval)

Not implemented -- see planning/05_clough_tocher_resampler.md, "Composing everything into one sparse (N,K) matrix M".

resample(val)

Estimate the HEALPix field from unstructured samples.