gridpoints 1.0.3__tar.gz → 1.0.5__tar.gz

{gridpoints-1.0.3 → gridpoints-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridpoints
-Version: 1.0.3
+Version: 1.0.5
 Summary: fast multidimensional sorting tool for point clouds using the monotonic lagrangian grid 
 Author: Armand de Cacqueray
 License: MIT
@@ -16,25 +16,31 @@ 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.
+`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 more powerfull 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  
+What it does: Take raw point cloud `P(N, D)`  and find a grid shape and an index permutation `order` such that Pgrid = P[order].reshape(*gridshape, D) 
+is sorted along every axis of the grid. E.g. in 3D, for Pgrid = (x, y, z):
+```text
+x[i+1, j, k] >= x[i, j, k]
+y[i, j+1, k] >= y[i, j, k]
+z[i, j, k+1] >= z[i, j, k]
+```
+→ On the `Pgrid` view of `P`, neighbor queries become a simple stencil look-up :
+```text
+neighborhood[i, j, k] = {Pgrid[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 (convolution, clustering, …) can then be applied  
+directly on the `Pgrid` 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).  
+`P` 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.
+  
+This allow to gridsort prime or variable number of points N, as long as one is ready to deal with void/special grid cells.
 
 Expected runtime for sorting 1 million points: CPU → < 10s, GPU → < 500 ms
 
@@ -54,20 +60,20 @@ import gridpoints as grid
 import numpy as np
 
 # Raw point cloud (numpy, pytorch or cupy)
-X = np.random.rand(1_000_000, 3)
+A = 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)
+order = grid.argsort(A, gridshape=(100, 100, 100))
+Bflat = A[order]
+Bgrid = Bflat.reshape(100, 100, 100, 3)
 
 # Rest of your pipeline, working with grids
-Zgrid = apply_something(Ygrid)
+Cgrid = apply_something(Bgrid)
 
 # Back to the original points indexing
-Zflat = Zgrid.reshape(-1, 2)
+Cflat = Cgrid.reshape(-1, 3)
 orderinv = grid.invert_permutation(order)
-Z = Zflat[orderinv]   # matches the initial points order
+C = Cflat[orderinv]   # matches the initial points order
 ```
 
 <img src="https://raw.githubusercontent.com/Neighborhood-Grid/CubeNet/main/ballexemple.png">
@@ -85,6 +91,6 @@ As an example, empirical results in 2-D show that `R = 5` is enough for ~99 % of
 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 )
+output(i, j, k) = f( Pgrid[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.3 → gridpoints-1.0.5}/README.md

@@ -1,24 +1,30 @@
 ## ❒ 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  
+`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 more powerfull sorting algorithm.
+
+What it does: Take raw point cloud `P(N, D)`  and find a grid shape and an index permutation `order` such that Pgrid = P[order].reshape(*gridshape, D) 
+is sorted along every axis of the grid. E.g. in 3D, for Pgrid = (x, y, z):
+```text
+x[i+1, j, k] >= x[i, j, k]
+y[i, j+1, k] >= y[i, j, k]
+z[i, j, k+1] >= z[i, j, k]
+```
+→ On the `Pgrid` view of `P`, neighbor queries become a simple stencil look-up :
+```text
+neighborhood[i, j, k] = {Pgrid[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 (convolution, clustering, …) can then be applied  
+directly on the `Pgrid` 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).  
+`P` 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.
+  
+This allow to gridsort prime or variable number of points N, as long as one is ready to deal with void/special grid cells.
 
 Expected runtime for sorting 1 million points: CPU → < 10s, GPU → < 500 ms
 
@@ -38,20 +44,20 @@ import gridpoints as grid
 import numpy as np
 
 # Raw point cloud (numpy, pytorch or cupy)
-X = np.random.rand(1_000_000, 3)
+A = 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)
+order = grid.argsort(A, gridshape=(100, 100, 100))
+Bflat = A[order]
+Bgrid = Bflat.reshape(100, 100, 100, 3)
 
 # Rest of your pipeline, working with grids
-Zgrid = apply_something(Ygrid)
+Cgrid = apply_something(Bgrid)
 
 # Back to the original points indexing
-Zflat = Zgrid.reshape(-1, 2)
+Cflat = Cgrid.reshape(-1, 3)
 orderinv = grid.invert_permutation(order)
-Z = Zflat[orderinv]   # matches the initial points order
+C = Cflat[orderinv]   # matches the initial points order
 ```
 
 <img src="https://raw.githubusercontent.com/Neighborhood-Grid/CubeNet/main/ballexemple.png">
@@ -69,6 +75,6 @@ As an example, empirical results in 2-D show that `R = 5` is enough for ~99 % of
 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 )
+output(i, j, k) = f( Pgrid[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.
+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.3 → gridpoints-1.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gridpoints"
-version = "1.0.3"
+version = "1.0.5"
 description = "fast multidimensional sorting tool for point clouds using the monotonic lagrangian grid "
 readme = "README.md"
 requires-python = ">=3.9"

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/griddemo/__init__.py

@@ -7,4 +7,4 @@ __all__ = (
     print_zoom,
 )
 
-__version__ = "1.0.3"
+__version__ = "1.0.5"

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/griddemo/quick_demo.py

@@ -108,14 +108,14 @@ def print_zoom(Ygrid, center, side=1):
     else:
         i, j, k = center
         print("axis 0:")
-        for ii in range(i-len, i+side+1):
+        for ii in range(i-side, i+side+1):
             print(_format_point(Ygrid[ii, j, k]), end=" ")
         print()
         print("axis 1:")
-        for jj in range(j-len, j+side+1):
+        for jj in range(j-side, j+side+1):
             print(_format_point(Ygrid[i, jj, k]), end=" ")
         print()
         print("axis 2:")
-        for kk in range(k-len, k+side+1):
+        for kk in range(k-side, k+side+1):
             print(_format_point(Ygrid[i, j, kk]), end=" ")
         print()

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/gridpoints/__init__.py

@@ -8,4 +8,4 @@ __all__ = (
     "invert_permutation",
 )
 
-__version__ = "1.0.3"
+__version__ = "1.0.5"

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/gridpoints/array_libs.py

@@ -10,7 +10,7 @@ like arange, copy, shuffle etc.
 _FLOAT = 'float32'
 _INT = 'int32'
 
-EPS = 10**(-10)
+EPS = 10**(-5) if (_FLOAT == 'float32') else 10**(-10)
 
 
 def get_dtype(dtp, xp):
@@ -100,8 +100,8 @@ def nan_to_num(arr):
         finite = xp.isfinite(x)
         vals = x[finite]
 
-        out[xp.isposinf(x), d] = 2 * vals.max()
-        out[xp.isneginf(x), d] = 2 * vals.min()
+        out[xp.isposinf(x), d] = vals.max() + 1
+        out[xp.isneginf(x), d] = vals.min() - 1
 
         nan = xp.isnan(x)
         n = nan.sum().item() if backend == 'torch' else int(nan.sum())
@@ -164,4 +164,4 @@ def transpose(X, axes):
     _, name = get_backend(X)
     if name == "torch":
         return X.permute(*axes)
-    return X.transpose(axes)
+    return X.transpose(axes)

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/gridpoints/mlg_sort.py

@@ -18,7 +18,7 @@ from .kdtree import kdtree_order
 #                   Sorting API
 # ============================================
 
-def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
+def argsort(X, gridshape, verbose = 2, level=2, init="kdtree", n_iter=40):
     """Compute a multi-directional monotonic sorted ordering of a point cloud.
 
     Parameters
@@ -33,6 +33,8 @@ def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
         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.
+    verbose : int, default 2
+        0 = silent, 1 = log progress, 2 = 1 + warn if convergence failed
     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` 
@@ -40,19 +42,14 @@ def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
     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
+    n_iter : int, default=40
         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
@@ -65,9 +62,8 @@ def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
             order = kdtree_order(X, gridshape)
             if verbose >=1:
                 print("done")
-            converged = True
             if level == 1:
-                return order, converged
+                return order
     else:
         order = arange(len(X), 'int', reference_array=X)
     if init == "shuffle":
@@ -77,27 +73,28 @@ def argsort(X, gridshape, level=2, init="kdtree", n_iter=50, verbose = 2):
     order = order[ordernew]
     
     if not converged:
-        while level >= 2:
+        while level >= 2 and not converged:
             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 not converged and verbose >=2:
+        warnings.warn(
+            f"Algorithm failed to converge after {n_iter} iterations.\n " \
+            "Consider checking if the grid structure is already suitable \n" \
+            "for the given task, which is higly probable, or increase the \n" \
+            "`n_iter` parameter if strict convergence is required.\n",
+            "(to shutup this warning, run the sort with verbose <= 1)",
+            category=ConvergenceWarning,
+            stacklevel=2
+        )
     if verbose:
         print("done")
-    return order, converged
+    return order
 
 
-def sort(X, gridshape, level=2, init="kdtree", inplace=False, n_iter=50, verbose = 2):
+def sort(X, gridshape, verbose = 2, level=2, init="kdtree", inplace=False, n_iter=40):
     """Sort a point cloud `X` using the monotonic Lagrangian algorithm.
 
     Parameters
@@ -112,6 +109,8 @@ def sort(X, gridshape, level=2, init="kdtree", inplace=False, n_iter=50, verbose
         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.
+    verbose : int, default 2
+        0 = silent, 1 = log progress, 2 = 1 + warn if convergence failed
     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` 
@@ -121,10 +120,8 @@ def sort(X, gridshape, level=2, init="kdtree", inplace=False, n_iter=50, verbose
         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
+    n_iter : int, default=40
         Maximum number of optimization iterations.
-    verbose : int, default 2
-         0 = silent, 1 = log progress, 2 = 1 + warn if convergence failed
 
     Returns
     -------
@@ -132,7 +129,7 @@ def sort(X, gridshape, level=2, init="kdtree", inplace=False, n_iter=50, verbose
         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)
+    order = argsort(X, gridshape, verbose = verbose, level=level, init = init, n_iter=n_iter)
 
     if inplace:
         X[:] = X[order]

{gridpoints-1.0.3 → gridpoints-1.0.5}/src/gridpoints.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridpoints
-Version: 1.0.3
+Version: 1.0.5
 Summary: fast multidimensional sorting tool for point clouds using the monotonic lagrangian grid 
 Author: Armand de Cacqueray
 License: MIT
@@ -16,25 +16,31 @@ 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.
+`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 more powerfull 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  
+What it does: Take raw point cloud `P(N, D)`  and find a grid shape and an index permutation `order` such that Pgrid = P[order].reshape(*gridshape, D) 
+is sorted along every axis of the grid. E.g. in 3D, for Pgrid = (x, y, z):
+```text
+x[i+1, j, k] >= x[i, j, k]
+y[i, j+1, k] >= y[i, j, k]
+z[i, j, k+1] >= z[i, j, k]
+```
+→ On the `Pgrid` view of `P`, neighbor queries become a simple stencil look-up :
+```text
+neighborhood[i, j, k] = {Pgrid[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 (convolution, clustering, …) can then be applied  
+directly on the `Pgrid` 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).  
+`P` 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.
+  
+This allow to gridsort prime or variable number of points N, as long as one is ready to deal with void/special grid cells.
 
 Expected runtime for sorting 1 million points: CPU → < 10s, GPU → < 500 ms
 
@@ -54,20 +60,20 @@ import gridpoints as grid
 import numpy as np
 
 # Raw point cloud (numpy, pytorch or cupy)
-X = np.random.rand(1_000_000, 3)
+A = 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)
+order = grid.argsort(A, gridshape=(100, 100, 100))
+Bflat = A[order]
+Bgrid = Bflat.reshape(100, 100, 100, 3)
 
 # Rest of your pipeline, working with grids
-Zgrid = apply_something(Ygrid)
+Cgrid = apply_something(Bgrid)
 
 # Back to the original points indexing
-Zflat = Zgrid.reshape(-1, 2)
+Cflat = Cgrid.reshape(-1, 3)
 orderinv = grid.invert_permutation(order)
-Z = Zflat[orderinv]   # matches the initial points order
+C = Cflat[orderinv]   # matches the initial points order
 ```
 
 <img src="https://raw.githubusercontent.com/Neighborhood-Grid/CubeNet/main/ballexemple.png">
@@ -85,6 +91,6 @@ As an example, empirical results in 2-D show that `R = 5` is enough for ~99 % of
 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 )
+output(i, j, k) = f( Pgrid[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.