gridpoints 1.0.0__py3-none-any.whl

griddemo/__init__.py

@@ -0,0 +1,10 @@
+
+from .quick_demo import sample, show_result, print_zoom
+
+__all__ = (
+    sample,
+    show_result,
+    print_zoom,
+)
+
+__version__ = "1.0.0"

griddemo/quick_demo.py

@@ -0,0 +1,115 @@
+"""
+Helpers: 
+sample various datasets,
+plot grids as a mesh, 
+check neighbormap counts
+
+Required:
+pip install squarenet
+"""
+
+def sample(method, size, backend="numpy"):
+    """Sample a dataset  and convert it to a backend array.
+
+    Parameters
+    ----------
+    method : str
+        Dataset sampling method:
+        "ball", "square", "gaussian", "spiky", "holy"
+        "france", "germany" (2D only)
+    size : (N, D)
+        Number of points to sample and dimension.
+    backend : {"numpy", "cupy", "torch"}, default="numpy"
+        Array backend for the returned points.
+
+    Returns
+    -------
+    array-like (N, D)
+        Sampled point cloud.
+    """
+    try:
+        import squarenet
+    except:
+        print("Missing dependencies for the demo. pip install gridsort[demo]")
+    from squarenet import samplepoints
+    points = samplepoints(method = method, size = size, plot_points = False)
+    if backend == "cupy":
+        import cupy as cp
+        points = cp.asarray(points)
+    if backend == "torch":
+        import torch
+        points = torch.tensor(points)
+    if method == "everest": #just a bug fix
+        points = points[..., [0, 2, 1]]
+    return points + 1
+
+def show_result(X, animate=False):
+    """Visualize a gridified point cloud as a mesh using ``squarenet``.
+    The point cloud must be sorted by the monotonic_lagrangian_sort 
+    fonction first, and reshaped as a grid (X.reshape(*gridshape, D))
+
+    Parameters
+    ----------
+    X : array-like (*G, D)
+        Point cloud arranged on a grid.
+    animate : bool, default=False
+        Whether to request an animated visualization.
+    """
+    try:
+        import squarenet
+    except:
+        print("Missing dependencies for the demo. pip install gridsort[demo]")
+    from squarenet import SquareNet
+    import numpy as np
+    X = np.asarray(X)
+    sn = SquareNet(gridshape = X.shape[:-1])
+    sn.pointsmaped = X
+    sn.plot(style = "mesh", animate = animate, save = animate)
+     #neighbormap counts the number of points found at a given relative delta = [i'-i, j'-j, k] such that
+     #P[i', j', k] = argmin(i', j') dist(P[i,j,k], P[i',j',k])
+    sn.neighbormap(projection = (0, 1)) #can also be projection = (1, 2)/(0, 1)
+
+def print_zoom(Ygrid, center, side=1):
+    """
+    Print a local cross-section of a 2D or 3D grid around ``center``.
+
+    Parameters
+    ----------
+    Ygrid : array-like
+        Grid of points, with shape ``(*grid_shape, D)`` where D is 2 or 3.
+    center : tuple of int
+        Index of the central grid point.
+    side : int, default=1
+        Number of cells shown on each side of the center.
+    """
+    import numpy as np
+    Ygrid = np.asarray(Ygrid)
+    ndim = Ygrid.ndim - 1
+    if ndim not in (2, 3):
+        raise ValueError("printzoom only for 2D/3D grids")
+    def _format_point(point):
+        return "(" + ", ".join(f"{float(x):.3f}" for x in point) + ")"
+    print(f"\n zooming arround the grid position {center} :\n")
+    if ndim == 2:
+        i, j = center
+        for point in Ygrid[i, j-side:j]:
+            print("." * (15*side-1), _format_point(point), "." * (15*side-1))
+        for point in Ygrid[i-side:i+side+1, j]:
+            print(_format_point(point), end=" ")
+        print("")
+        for point in Ygrid[i, j+1:j+side+1]:
+            print("." * (15*side-1), _format_point(point), "." * (15*side-1))
+    else:
+        i, j, k = center
+        print("axis 0:")
+        for ii in range(i-len, i+side+1):
+            print(_format_point(Ygrid[ii, j, k]), end=" ")
+        print()
+        print("axis 1:")
+        for jj in range(j-len, j+side+1):
+            print(_format_point(Ygrid[i, jj, k]), end=" ")
+        print()
+        print("axis 2:")
+        for kk in range(k-len, k+side+1):
+            print(_format_point(Ygrid[i, j, kk]), end=" ")
+        print()

gridpoints/__init__.py

@@ -0,0 +1,11 @@
+"""Monotonic Lagrangian sorting for NumPy, CuPy, and PyTorch arrays."""
+
+from .mlg_sort import argsort, sort, invert_permutation
+
+__all__ = (
+    "argsort",
+    "sort",
+    "invert_permutation",
+)
+
+__version__ = "1.0.0"

gridpoints/array_libs.py

@@ -0,0 +1,165 @@
+"""
+Helpers:
+Unified array syntax to support numpy, cupy and pytorch arrays
+
+Here we just define basic primitives that we will need later 
+like arange, copy, shuffle etc.
+"""
+
+#This have to be promoted to float64 and int64 for very big point clouds (more than 1 billion points)
+_FLOAT = 'float32'
+_INT = 'int32'
+
+EPS = 10**(-10)
+
+
+def get_dtype(dtp, xp):
+    if dtp == 'float':
+        dtp = _FLOAT
+    elif dtp in ('int', 'integer'):
+        dtp = _INT
+    return getattr(xp, dtp) if isinstance(dtp, str) else dtp
+
+
+def get_backend(X):
+    module = type(X).__module__.split('.')[0]
+    if module == 'torch':
+        import torch
+        return torch, 'torch'
+    elif module == 'cupy':
+        import cupy
+        return cupy, 'cupy'
+    else:
+        import numpy
+        return numpy, 'numpy'
+
+def astype(X, dtype_str, reference_array=None):
+    xp, backend_name = get_backend(X)
+    dtype = get_dtype(dtype_str, xp)
+    if backend_name == 'torch':
+        device = reference_array.device if reference_array is not None else X.device
+        return X.to(dtype=dtype, device=device)
+    return X.astype(dtype)
+
+
+def inplace_sort(X, axis):
+    _, backend_name = get_backend(X)
+    if backend_name == 'torch':
+        X.copy_(X.sort(dim=axis)[0])
+    else:
+        X.sort(axis=axis)
+
+
+def empty(shape, dtype_str, reference_array):
+    xp, backend_name = get_backend(reference_array)
+    dtype = get_dtype(dtype_str, xp)
+    if backend_name == 'torch':
+        return xp.empty(shape, dtype=dtype, device=reference_array.device)
+    return xp.empty(shape, dtype=dtype)
+
+
+def arange(N, dtype_str, reference_array):
+    xp, backend_name = get_backend(reference_array)
+    dtype = get_dtype(dtype_str, xp)
+    if backend_name == 'torch':
+        return xp.arange(N, dtype=dtype, device=reference_array.device)
+    return xp.arange(N, dtype=dtype)
+
+def argmax(arr, axis):
+    xp, backend_name = get_backend(arr)
+    if backend_name == 'torch':
+        if arr.dtype == xp.bool:
+            arr = arr.to(xp.int32)
+        return arr.argmax(dim=axis)
+    return arr.argmax(axis=axis)
+
+def random_noise(shape, reference_array):
+    xp, backend_name = get_backend(reference_array)
+    if backend_name == 'torch':
+        return EPS * xp.rand(*shape, device=reference_array.device)
+    elif backend_name == 'cupy':
+        return EPS * xp.random.rand(*shape)
+    else:
+        rng = xp.random.default_rng(42)
+        return EPS * rng.random(shape)
+
+def copy(arr):
+    _, backend_name = get_backend(arr)
+    if backend_name == 'torch':
+        return arr.clone()
+    return arr.copy()
+
+def nan_to_num(arr):
+    xp, backend = get_backend(arr)
+    out = copy(arr)
+
+    for d in range(arr.shape[1]):
+        x = arr[:, d]
+        finite = xp.isfinite(x)
+        vals = x[finite]
+
+        out[xp.isposinf(x), d] = 2 * vals.max()
+        out[xp.isneginf(x), d] = 2 * vals.min()
+
+        nan = xp.isnan(x)
+        n = nan.sum().item() if backend == 'torch' else int(nan.sum())
+        if n:
+            idx = (xp.randint(len(vals), (n,), device=arr.device)
+                   if backend == 'torch' else xp.random.randint(len(vals), size=n))
+            out[nan, d] = vals[idx]
+
+    return out + random_noise(out.shape, out)
+
+def all_true(tensor):
+    _, backend_name = get_backend(tensor)
+    if backend_name == 'torch':
+        return tensor.all().item()
+    return bool(tensor.all())
+
+def random_permutation(arr):
+    xp, backend_name = get_backend(arr)
+    if backend_name == 'torch':
+        perm = xp.randperm(len(arr), device=arr.device)
+        return arr[perm]
+    return xp.random.permutation(arr)
+
+def flip(X, axis=None):
+    xp, _ = get_backend(X)
+    if axis is None or axis == () or axis == []:
+        return X
+
+    if isinstance(axis, int):
+        axis = (axis,)
+    else:
+        axis = tuple(axis)
+
+    if hasattr(X, "flip") and callable(X.flip):
+        return X.flip(axis)
+
+    return xp.flip(X, axis=axis)
+
+def argpartition(X, mid, axis):
+    xp, backend_name = get_backend(X)
+    if backend_name == 'torch':
+        return xp.argsort(X, dim=axis)
+    else:
+        return xp.argpartition(X, mid - 1, axis=-1)
+
+def take_along_axis(idx, val, axis):
+    xp, backend_name = get_backend(val)
+    if backend_name == 'torch':
+        return xp.take_along_dim(idx, val, dim=axis)
+    else:
+        return xp.take_along_axis(idx, val, axis=axis)
+
+def concatenate(arrays, axis = 0):
+    xp, name = get_backend(arrays[0])
+    if name == "torch":
+        return xp.cat(list(arrays), dim=axis)
+    return xp.concatenate(arrays, axis=axis)
+
+def transpose(X, axes):
+    _, name = get_backend(X)
+    if name == "torch":
+        return X.permute(*axes)
+    return X.transpose(axes)

gridpoints/diagonal_tricks.py

@@ -0,0 +1,96 @@
+"""
+Helpers:
+Diagonal trick is based on a tensor rotation that allow 
+to sort arrays efficiently along arbitrary diagonal fibers.
+"""
+
+
+from .array_libs import (
+    get_backend,
+    arange,
+    inplace_sort,
+    all_true
+)
+
+def sort_diag_trick(X):
+    """ 
+    we rotate the tensor along the main diagonal 
+    to place diagonals on the last axis, then 
+    perform a standard sort(axis = -1), and
+    rotate back the diagonals
+    """
+    xp, _ = get_backend(X)
+    bigM = (X.max() - X.min()) + 1#bigM for safety, protect
+    #overlapping diagonals
+
+    n, m = X.shape[-2:]
+    
+    if m > n: #Optional, maximal parallelisation
+        X = xp.moveaxis(X, [-1, -2], [-2, -1]) 
+        n, m = m, n
+        
+    i = arange(n, 'int', X)[:, None]
+    j = arange(m, 'int', X)[None, :]
+    
+    di = (i - j)
+    i_ = di % n
+    ires = di // n 
+    groupkey = bigM * ires 
+    
+    X[..., i_, j] = X[..., i, j] - groupkey #Rotation
+    # ========================
+    # here is the trick: as we rotated the tensor
+    # sorting on the diagonal is just working on
+    # axis -1 of the rotated view
+    # ========================
+    was_sorted = all_true(xp.diff(X, axis=-1) >= 0)
+    inplace_sort(X, axis=-1)
+    X[..., i, j] = X[..., i_, j] + groupkey
+    
+    return was_sorted
+
+def sort_tridiag_trick(X):
+    """ 
+    we rotate the tensor along the tridiagonal, 
+    then perform a standard sort(axis = -1), 
+    and rotate back the tridiagonals
+    """
+    xp, _ = get_backend(X)
+    bigM = (X.max() - X.min()) + 1#bigM for safety, protect
+    #overlapping diagonals
+
+    a, b, c = X.shape[-3:]
+
+    #Optional, maximal parallelisation:
+    #move the smallest axis to last position
+    #before the tridiagonal rotation
+    if (a < b) and (a < c):
+        X = xp.moveaxis(X, [-3, -1], [-1, -3]) 
+        a, c = c, a
+    elif b < c:
+        X = xp.moveaxis(X, [-2, -1], [-1, -2]) 
+        b, c = c, b
+    
+    i = arange(a, 'int', X)[:, None, None]
+    j = arange(b, 'int', X)[None, :, None]
+    k = arange(c, 'int', X)[None, None, :]
+    
+    di = i - k
+    dj = j - k
+    di_ = di % a
+    dj_ = dj % b
+    dires = di // a         
+    djres = dj // b
+    groupkey = bigM * (dires * (2 * (b + c)) + djres)
+    
+    X[..., di_, dj_, k] = X[..., i, j, k] - groupkey #Trirotation
+    # ========================
+    # Again, thanks to the rotation trick
+    # we just need to .sort(X, axis = -1)
+    # to sort the tridiagonal
+    # ========================
+    was_sorted = all_true(xp.diff(X, axis=-1) >= 0)
+    inplace_sort(X, axis=-1)  
+    X[..., i, j, k] = X[..., di_, dj_, k] + groupkey
+    
+    return was_sorted

gridpoints/kdtree.py

@@ -0,0 +1,203 @@
+"""
+Helpers:
+anything related to kdtree
+"""
+
+import math
+from collections import defaultdict
+from .array_libs import (
+    get_backend,
+    transpose,
+    arange,
+    empty,
+    argpartition,
+    take_along_axis,
+    concatenate,
+)
+
+
+def kdtree_order_dyadic(X):
+    """
+    Sorting version for the (easy) dyadic case, were X has a power of 2**D shape.
+    Mainly for pedagogical reason. It will help to understand what the general
+    version do, when the number of points is not necesarily a power of two and 
+    we have to deal with potential median hyperplan. 
+
+    Parameters
+    ----------
+    X    : array-like, shape (N, D). Point cloud
+
+    Returns
+    -------
+    order : array, shape (N,), based on the kdtree cuts, such that
+        Xgrid = X[order].reshape(*gridshape, D) is monotonic along each axis:
+        Xgrid[i+1, j, k][0] >= Xgrid[i, j, k][0]
+        Xgrid[i, j+1, k][1] >= Xgrid[i, j, k][1]
+
+    """
+    N, D = X.shape
+    M = int(N**(1/D) + 0.1)
+    K = int(math.log2(M))
+    
+    idx = arange(N, 'int', reference_array=X)
+    
+    for step in range(K * D):
+        axis = step % D
+        size = idx.shape[-1]
+        mid = size // 2
+        X_curr = X[idx, axis]
+        p = argpartition(X_curr, mid, axis = -1)
+        idx = take_along_axis(idx, p, axis = -1)    
+        idx = idx.reshape(*idx.shape[:-1], 2, mid)
+        
+    idx = idx.squeeze(-1)
+    transpose_axes = [d + k * D for d in range(D) for k in range(K)]
+    idx = transpose(idx, transpose_axes)
+
+    return idx.flatten()
+
+
+
+def kdtree_order(X, gridshape):
+    """
+    Parameters
+    ----------
+    X         : array-like, shape (N, D). Point cloud
+    gridshape : sequence of int, length D, product == N
+
+    Returns
+    -------
+    order : array, shape (N,), based on the kdtree cuts, such that
+        Xgrid = X[order].reshape(*gridshape, D) is monotonic along each axis:
+        Xgrid[i+1, j, k][0] >= Xgrid[i, j, k][0]
+        Xgrid[i, j+1, k][1] >= Xgrid[i, j, k][1]
+
+    Note: 
+    -----
+    It is the natural generalisation of the kdtree_order_dyadic version.
+    What make the general case more complex is simply to deal with 
+    the median hyperplan when cuting a non even shape of the grid hyperrectangle.
+    """
+    xp, _ = get_backend(X)
+    N, D = X.shape
+    shape = tuple(int(s) for s in gridshape)
+    assert math.prod(shape) == N
+    assert len(shape) == D
+
+    def next_axis(sh, start):
+        for off in range(D):
+            a = (start + off) % D
+            if sh[a] > 1:
+                return a
+        return None
+
+    def multi_index_on_axis(pos, axis):
+        """Multi-index component on `axis` for C-order linear indices `pos`."""
+        stride = int(math.prod(shape[axis + 1 :])) if axis + 1 < D else 1
+        return (pos // stride) % shape[axis]
+
+    output = empty(N, 'int', reference_array=X)
+
+    if N == 1:
+        output[0] = 0
+        return output
+
+    # idx = point indices, pos = fixed destination slots (C-order of the grid)
+    idx_init = arange(N, 'int', reference_array=X)[None, :]
+    pos_init = arange(N, 'int', reference_array=X)[None, :]
+
+    ax0 = next_axis(shape, 0)
+    worklist = defaultdict(lambda: ([], []))
+    worklist[(shape, ax0)][0].append(idx_init)
+    worklist[(shape, ax0)][1].append(pos_init)
+
+    while worklist:
+        key = next(iter(worklist))
+        idx_list, pos_list = worklist.pop(key)
+        cur_shape, cur_axis = key
+
+        idx_b = concatenate(idx_list) if len(idx_list) > 1 else idx_list[0]
+        pos_b = concatenate(pos_list) if len(pos_list) > 1 else pos_list[0]
+
+        n = idx_b.shape[-1]
+        if n == 1:
+            output[pos_b[:, 0]] = idx_b[:, 0]
+            continue
+
+        axis  = cur_axis
+        size  = cur_shape[axis]
+        slab  = n // size
+        lsize = size // 2
+        ln    = lsize * slab
+        mid_n = slab if (size % 2) else 0
+
+        def push(idx_part, pos_part, child_shape, child_n_axis):
+            m = idx_part.shape[-1]
+            if m == 1 or child_n_axis is None:
+                output[pos_part[:, 0]] = idx_part[:, 0]
+            else:
+                ckey = (child_shape, child_n_axis)
+                worklist[ckey][0].append(idx_part)
+                worklist[ckey][1].append(pos_part)
+
+        # --- partition the POINTS only ---
+        if size % 2 == 0:
+            vals = X[idx_b, axis]
+            p = argpartition(vals, ln, axis=-1)
+            idx_b = take_along_axis(idx_b, p, axis=-1)
+            idx_l, idx_r = idx_b[:, :ln], idx_b[:, ln:]
+
+            # destinations = current pos sorted by their multi-index on `axis`
+            mi = multi_index_on_axis(pos_b, axis)
+            order_mi = xp.argsort(mi, axis=-1)
+            pos_sorted = take_along_axis(pos_b, order_mi, axis=-1)
+            pos_l, pos_r = pos_sorted[:, :ln], pos_sorted[:, ln:]
+
+            child_shape = list(cur_shape)
+            child_shape[axis] = lsize
+            child_shape = tuple(child_shape)
+            nax = next_axis(child_shape, (axis + 1) % D)
+
+            push(concatenate([idx_l, idx_r]),
+                 concatenate([pos_l, pos_r]),
+                 child_shape, nax)
+
+        else:
+            # odd: left + median slab + right
+            total_keep = ln + mid_n
+            vals = X[idx_b, axis]
+            p = argpartition(vals, total_keep, axis=-1)
+            idx_b = take_along_axis(idx_b, p, axis=-1)
+            idx_r  = idx_b[:, total_keep:]
+            idx_lm = idx_b[:, :total_keep]
+
+            if ln > 0:
+                vals_lm = X[idx_lm, axis]
+                p2 = argpartition(vals_lm, ln, axis=-1)
+                idx_lm = take_along_axis(idx_lm, p2, axis=-1)
+                idx_l = idx_lm[:, :ln]
+                idx_m = idx_lm[:, ln:]
+            else:
+                idx_l = None
+                idx_m = idx_lm
+
+            mi = multi_index_on_axis(pos_b, axis)
+            order_mi = xp.argsort(mi, axis=-1)
+            pos_sorted = take_along_axis(pos_b, order_mi, axis=-1)
+            pos_l = pos_sorted[:, :ln] if ln > 0 else None
+            pos_m = pos_sorted[:, ln : ln + mid_n]
+            pos_r = pos_sorted[:, ln + mid_n :]
+
+            child_l = list(cur_shape); child_l[axis] = lsize; child_l = tuple(child_l)
+            child_m = list(cur_shape); child_m[axis] = 1;     child_m = tuple(child_m)
+
+            nax_lr = next_axis(child_l, (axis + 1) % D)
+            nax_m  = next_axis(child_m, (axis + 1) % D)
+
+            if idx_l is not None:
+                push(concatenate([idx_l, idx_r]),
+                     concatenate([pos_l, pos_r]),
+                     child_l, nax_lr)
+            push(idx_m, pos_m, child_m, nax_m)
+
+    return output

gridpoints/mlg_sort.py

@@ -0,0 +1,267 @@
+"""
+Main fonctions of the library are defined here: 
+argsort and sort
+"""
+
+
+import math
+import warnings
+from .array_libs import (
+    arange, get_backend, all_true, 
+    inplace_sort, empty, astype, nan_to_num, 
+    random_permutation, argmax, copy, flip
+)
+from .diagonal_tricks import sort_diag_trick, sort_tridiag_trick
+from .kdtree import kdtree_order
+
+# ============================================
+#                   Sorting API
+# ============================================
+
+def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
+    """Compute a multi-directional monotonic sorted ordering of a point cloud.
+
+    Parameters
+    ----------
+    X : ndarray of shape (N, D)
+        Input point cloud.
+    gridshape : tuple of int
+        Target shape of the sorting grid. The product of the dimensions must 
+        equal N and its length must equal D. E.g., for X of shape (42, 2), 
+        `shape` can be (6, 7); for (60, 3), `shape` can be (3, 4, 5).
+
+        Note: Point clouds can be padded with +/- infinity placeholders to reach 
+        a valid grid size. NaNs can also be used, but will be placed randomly 
+        rather than pushed to grid boundaries.
+    level : {1, 2, 3}, default=2
+        Maximum order of lattice directions considered. Higher values improve 
+        grid quality at the expense of computational speed. Note that `level=3` 
+        is only supported if D >= 3.
+    init : {'kdtree', 'shuffle'} or None, default="kdtree"
+        Initialization method for the permutation order. Try init = None
+        if the point cloud is already nearly sorted.
+    n_iter : int, default=50
+        Maximum number of optimization iterations.
+    verbose : int, default 2
+        0 = silent, 1 = log progress, 2 = 1 + warn if convergence failed
+
+    Returns
+    -------
+    order : ndarray of shape (N,)
+        Permutation indices such that `X[order].reshape(*shape, D)` forms a 
+        monotonically sorted grid.
+    converged : bool
+        `True` if the algorithm converged within `n_iter` iterations, `False` otherwise.
+        If not converged, the fonction will also raise a convergence warning
+    """
+    N, D = X.shape
+    assert math.prod(gridshape) == N
+    assert len(gridshape) == D
+    
+    level = min(level, X.shape[-1])
+    if init == "kdtree":
+            if verbose >=1:
+                print("performing kdtree initialisation")
+            order = kdtree_order(X, gridshape)
+            if verbose >=1:
+                print("done")
+            converged = True
+            if level == 1:
+                return order, converged
+    else:
+        order = arange(len(X), 'int', reference_array=X)
+    if init == "shuffle":
+        order = random_permutation(order)
+
+    ordernew, converged = _mlg_step(X[order], gridshape, level=level, n_iter=n_iter, verbose = verbose)
+    order = order[ordernew]
+    
+    if not converged:
+        while level >= 2:
+            level = level - 1
+            ordernew, converged = _mlg_step(
+                X[order], gridshape, level=level, n_iter=n_iter, verbose = verbose
+            )
+            order = order[ordernew]
+        if not converged and verbose >=2:
+            warnings.warn(
+                f"Algorithm failed to converge after {n_iter} iterations. " \
+                "Consider checking if the grid structure is already suitable" \
+                "for the given task, which is higly probable, or increase the" \
+                "`n_iter` parameter if strict convergence is required.",
+                category=ConvergenceWarning,
+                stacklevel=2,
+            )
+    if verbose:
+        print("done")
+    return order, converged
+
+
+def sort(X, gridshape, level=2, init="kdtree", inplace=False, n_iter=50, verbose = 2):
+    """Sort a point cloud `X` using the monotonic Lagrangian algorithm.
+
+    Parameters
+    ----------
+    X : ndarray of shape (N, D)
+        Input point cloud.
+    gridshape : tuple of int
+        Target shape of the sorting grid. The product of the dimensions must 
+        equal N and its length must equal D. E.g., for X of shape (42, 2), 
+        `shape` can be (6, 7); for (60, 3), `shape` can be (3, 4, 5).
+
+        Note: Point clouds can be padded with +/- infinity placeholders to reach 
+        a valid grid size. NaNs can also be used, but will be placed randomly 
+        rather than pushed to grid boundaries.
+    level : {1, 2, 3}, default=1
+        Maximum order of lattice directions considered. Higher values improve 
+        grid quality at the expense of computational speed. Note that `level=3` 
+        is only supported if D >= 3.
+    init : {'kdtree', 'shuffle'} or None, default="kdtree"
+        Initialization method for the permutation order. Try init = None
+        if the point cloud is already nearly sorted.
+    inplace : bool, default=False
+        If True, modify the point cloud `X` in place.
+    n_iter : int, default=50
+        Maximum number of optimization iterations.
+    verbose : int, default 2
+         0 = silent, 1 = log progress, 2 = 1 + warn if convergence failed
+
+    Returns
+    -------
+    X_sorted : ndarray of shape (N, D) or None
+        The sorted point cloud such that `X_sorted.reshape(*shape, D)` forms a 
+        monotonically sorted grid. Returns `None` if `inplace=True`.
+    """
+    order, _ = argsort(X, gridshape, level=level, init = init, n_iter=n_iter,verbose = verbose)
+
+    if inplace:
+        X[:] = X[order]
+        return None
+        
+    return X[order]
+
+def invert_permutation(sigma):
+    """
+    invert permutation helper, sigma_inv[sigma] = identity
+    """
+    xp, _ = get_backend(sigma)
+    return xp.argsort(sigma)
+
+# ============================================
+#                   Helpers
+# ============================================
+
+class ConvergenceWarning(UserWarning):
+    """Warning for convergence issues."""
+    pass
+
+def _canonical_directions(directions):
+    first_nz = argmax(directions != 0, axis=1)
+    idx = arange(len(directions), 'int', reference_array=directions)
+    first_nz_sign = directions[idx, first_nz]
+    return directions[first_nz_sign > 0]
+
+
+def _direction_blocks(level, xp, dim=3):
+    offsets = xp.arange(-1, 2)
+    lattice = xp.stack(xp.meshgrid(*(offsets,) * dim, indexing="ij"), axis=-1).reshape(-1, dim)
+    sq_norms = xp.sum(lattice ** 2, axis=-1)
+    dirs = _canonical_directions(lattice[(sq_norms > 0) & (sq_norms <= level ** 2)])
+    return [dirs[xp.sum(dirs ** 2, axis=-1) == k] for k in range(1, level + 1)]
+
+
+def _sort_along_direction(X, direction):
+    xp, _ = get_backend(X)
+    level = int(xp.abs(direction).sum())
+
+    if level == 1:
+        axis = int(xp.argmax(xp.abs(direction)))
+        if all_true(xp.diff(X, axis=axis) >= 0):
+            return True
+        inplace_sort(X, axis=axis)
+        return False
+
+    elif level == 2:
+        ax0, ax1 = xp.where(direction != 0)[0]
+        Y = xp.moveaxis(X, [ax0, ax1], [-2, -1])
+        flipaxes = []
+        for ax, _ax in zip([ax0, ax1], [-2, -1]):
+            if direction[ax] == -1:
+                flipaxes.append(_ax)
+        Y[...] = flip(Y, flipaxes)
+        was_sorted = sort_diag_trick(Y)
+        Y[...] = flip(Y, flipaxes)
+        return was_sorted
+
+    elif level == 3:
+        ax0, ax1, ax2 = xp.where(direction != 0)[0]
+        Y = xp.moveaxis(X, [ax0, ax1, ax2], [-3, -2, -1])
+        flipaxes = []
+        for ax, _ax in zip([ax0, ax1, ax2], [-3, -2, -1]):
+            if direction[ax] == -1:
+                flipaxes.append(_ax)
+        Y[...] = flip(Y, flipaxes)
+        was_sorted = sort_tridiag_trick(Y)
+        Y[...] = flip(Y, flipaxes)
+        return was_sorted
+
+    raise ValueError(f"Unsupported direction with L1-norm {level}")
+
+
+def _build_monotonic_lagrangian_loop(X, directions):
+    xp, _ = get_backend(X)
+    N, K = len(X), len(directions)
+    projections = X @ directions.T
+
+    rank = empty((K, N), 'int', reference_array=X)
+    for k in range(K):
+        order = xp.argsort(projections[:, k])
+        rank[k, order] = arange(N, 'int', reference_array=X)
+
+    identity = arange(N, 'int', reference_array=X)
+    h = [identity] + [rank[k] for k in range(K)]
+    h_next = [rank[k] for k in range(K)] + [identity]
+
+    perms = []
+    for hk, hk_next in zip(h, h_next):
+        sigma = empty((N,), 'int', reference_array=X)
+        sigma[hk] = hk_next
+        perms.append(sigma)
+
+    init_perm, end_perm = copy(perms[0]), copy(perms[-1])
+    cycle_perms = perms[:-1]
+    cycle_perms[0] = init_perm[end_perm]
+
+    return init_perm, cycle_perms, end_perm
+
+
+def _sort_loop(loop, directions, shape, n_iter, verbose):
+    idx_to_cycle, directions_cycle, cycle_to_idx = loop
+    grid = idx_to_cycle.reshape(shape)
+    first_step = True
+
+    for it in range(n_iter):
+        if verbose:
+            print("-", end="", flush=True)
+        fully_sorted = True
+        for direction, along_direction in zip(directions, directions_cycle):
+            if not first_step:
+                grid = along_direction[grid]
+            first_step = False
+            fully_sorted = fully_sorted & _sort_along_direction(grid, direction)
+        if fully_sorted:
+            break
+
+    print("it:", it)
+    return (cycle_to_idx[grid]).ravel(), fully_sorted
+
+def _mlg_step(X, shape, level, n_iter, verbose):
+    xp, _ = get_backend(X)     
+    directions_raw = xp.vstack(_direction_blocks(level=level, xp=xp, dim=X.shape[-1]))
+    directions = astype(directions_raw, 'float', reference_array=X)
+    X_float = nan_to_num(astype(X, 'float'))
+    
+    loop = _build_monotonic_lagrangian_loop(X_float, directions)
+    if verbose >=1:
+        print(f"level [{level}]. sorting")
+    return _sort_loop(loop, directions, shape, n_iter, verbose)

gridpoints-1.0.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: gridpoints
+Version: 1.0.0
+Summary: fast multidimensional sorting tool for point clouds using the monotonic lagrangian grid 
+Author: Armand de Cacqueray
+License: MIT
+Project-URL: Homepage, https://github.com/Neighborhood-Grid/CubeNet
+Project-URL: Repository, https://github.com/Neighborhood-Grid/CubeNet
+Keywords: sorting,point-clouds,multi-indexing,grid,neighborhood-grid,monotonic-lagrangian-grid,squarenet,nearest-neighbor
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: demo
+Requires-Dist: squarenet; extra == "demo"
+Dynamic: license-file
+
+## ❒ Gridpoints — Multi dimensional sort for point clouds
+
+`Gridpoints` maps unstructured **point clouds** to structured grids through a **bijective transformation**: one point, one cell, no overlap, fully invertible. It replaces and enhances the squarenet project with a faster sorting algorithm.
+
+Take raw point cloud `X(N, D)`  
+→ find a grid shape and a permutation `order` such that  
+Xgrid = X[order].reshape(*gridshape, D) is sorted along every axis of the grid.  
+→ On the `Xgrid` view of `X`, neighbor queries become a simple stencil look-up  
+neighborhood[i, j, k] = {Xgrid[i±di, j±dj, k±dk] | (di, dj, dk) ≤ R}, where `R` is a radius cutoff to determine,  
+allowing local operations in linear time.  
+→ Standard operations (grid convolution, clustering, …) can then be applied  
+directly on the `Xgrid` view instead of relying on complex graph convolutions  
+or other point-cloud techniques.
+
+`X` can be a NumPy, PyTorch or CuPy array of any dimension (N, D).  
+To allow natural padding when the grid has more cells than points,  
+NaNs and Infs are supported in a consistent manner: 
+- nans → random position
+- (+-) infs → border of the grid
+This allow to deal with prime or variable N, as long as one is ready to 
+deal with void/special grid cells.
+
+Expected runtime for sorting 1 million points: CPU → < 10s, GPU → < 100 ms
+
+---
+
+### Installation
+
+```bash
+pip install gridpoints          # core only
+pip install gridpoints[demo]    # for the demonstration notebook, see `notebook.ipynb`
+```
+
+### Quickstart
+
+```python
+import gridpoints as grid
+import numpy as np
+
+# Raw point cloud (numpy, pytorch or cupy)
+X = np.random.rand(1_000_000, 3)
+
+# Sorted view: place the points inside the grid
+order = grid.argsort(X, gridshape=(100, 100, 100))
+Yflat = X[order]
+Ygrid = Yflat.reshape(100, 100, 100, 3)
+
+# Rest of your pipeline, working with grids
+Zgrid = apply_something(Ygrid)
+
+# Back to the original points indexing
+Zflat = Zgrid.reshape(-1, 2)
+orderinv = grid.invert_permutation(order)
+Z = Zflat[orderinv]   # matches the initial points order
+```
+
+<img src="https://raw.githubusercontent.com/Neighborhood-Grid/CubeNet/main/ballexemple.png">
+
+---
+
+### Note on the cutoff radius R
+
+There is no strict theoretical guarantee about what the cutof radius R should be for a given task. E.g the relative grid position between a point and its nearest neighbors can't be garanted to be in the exact adjacent grid cells. What is guaranteed from the sorted ordering is only **grid monotonicity**: *x* coordinates increase along rows, *y* coordinates along columns, and so on.
+
+As an example, empirical results in 2-D show that `R = 5` is enough for ~99 % of the nearest neighbors; some outlier neighbors will sit further apart for complex geometries with pronounced peaks, holes or any non-smoothness. When a stricter neighborhood is required, or in high dimensional setting, the best practice is to build an assembly of grid experts, each working on a rotated / projected view of the points, as discussed in [this topic](https://github.com/glotzerlab/freud/discussions/1417).
+
+### Note on efficient stencil operations
+
+The typical use-case of `Gridpoints` is to allow fast local operations on arbitrary point clouds using stencil kernels:
+
+```text
+output(i, j, k) = f( Xgrid[i±di, j±dj, k±dk] | di, dj, dk in local window )
+```
+To go beyond standard (slow) python loops, this can be accelerated with native grid convolution operations of standard libraries whenever possible, or with `pystencils` or `taichi` compilers for complex/non linear grid kernels.

gridpoints-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+griddemo/__init__.py,sha256=6V0GaQ-14Nt31OK30w5AVHgO1RH03CscWIcT3oGYX_o,148
+griddemo/quick_demo.py,sha256=nHkTSOsLBwy2pMa4envFlTrvGKO1hLvd__nET1AF1ag,3913
+gridpoints/__init__.py,sha256=vUdnYE5bemyOrkrQfggllWmIwmDi7wb7_gEFXc8mKEI,229
+gridpoints/array_libs.py,sha256=K8JTF3Ul8aMz6zX7o6H5mgOu-tgdtgrQliIgcXLXY_E,4831
+gridpoints/diagonal_tricks.py,sha256=JpKb8lOeXYb8tg37fdlalhDrsz0FgK69Xa_HcawguWQ,2705
+gridpoints/kdtree.py,sha256=pO7EBBpjxGW0f1Z1FywRYmWnjBfdBdLPIfuZbKlB7-k,6816
+gridpoints/mlg_sort.py,sha256=NJpLme2gQxQwurUVZMcjinPjtjbKZaTd7ZvrgrxqB94,9931
+gridpoints-1.0.0.dist-info/licenses/LICENSE,sha256=BFLP4IAOAWhrs3Al_5RUZem9LTTud3BOTcD0XAEEd3g,1095
+gridpoints-1.0.0.dist-info/METADATA,sha256=_2bNQR6mPInFr90wZZ-r7QPQycLmp7SSt_0YYXv1UIM,4298
+gridpoints-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gridpoints-1.0.0.dist-info/top_level.txt,sha256=IOiFob4pQdS5foU3vSvqjzxVSWqaIhSxH4ed6nY5SzM,20
+gridpoints-1.0.0.dist-info/RECORD,,

gridpoints-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gridpoints-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neighborhood-grid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gridpoints-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+griddemo
+gridpoints