EmptySpaceSearch 0.1__tar.gz

emptyspacesearch-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mário Antunes
+
+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.

emptyspacesearch-0.1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: EmptySpaceSearch
+Version: 0.1
+Summary: Empty Space Search
+Home-page: https://github.com/mariolpantunes/ess
+Author: Mário Antunes
+Author-email: mario.antunes@ua.pt
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: numba>=0.61.0
+Requires-Dist: hnswlib>=0.8.0
+Dynamic: license-file
+
+# Empty Space Search (ESS)
+MIT License
+
+Copyright (c) 2025 Mário Antunes
+
+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.

emptyspacesearch-0.1/README.md

@@ -0,0 +1 @@
+# Empty Space Search (ESS)

emptyspacesearch-0.1/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ['setuptools>=42']
+build-backend = 'setuptools.build_meta'

emptyspacesearch-0.1/setup.cfg

@@ -0,0 +1,31 @@
+[metadata]
+name = EmptySpaceSearch
+version = 0.1
+author = Mário Antunes
+author_email = mario.antunes@ua.pt
+description = Empty Space Search
+long_description = file: README.md, LICENSE
+long_description_content_type = text/markdown
+url = https://github.com/mariolpantunes/ess
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+
+[options]
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.8
+install_requires = 
+	numpy>=2.1.0
+	numba>=0.61.0
+	hnswlib>=0.8.0
+
+[options.packages.find]
+where = src
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

emptyspacesearch-0.1/src/EmptySpaceSearch.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: EmptySpaceSearch
+Version: 0.1
+Summary: Empty Space Search
+Home-page: https://github.com/mariolpantunes/ess
+Author: Mário Antunes
+Author-email: mario.antunes@ua.pt
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: numba>=0.61.0
+Requires-Dist: hnswlib>=0.8.0
+Dynamic: license-file
+
+# Empty Space Search (ESS)
+MIT License
+
+Copyright (c) 2025 Mário Antunes
+
+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.

emptyspacesearch-0.1/src/EmptySpaceSearch.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/EmptySpaceSearch.egg-info/PKG-INFO
+src/EmptySpaceSearch.egg-info/SOURCES.txt
+src/EmptySpaceSearch.egg-info/dependency_links.txt
+src/EmptySpaceSearch.egg-info/requires.txt
+src/EmptySpaceSearch.egg-info/top_level.txt
+src/ess/__init__.py
+src/ess/ess.py
+test/test_ess.py

emptyspacesearch-0.1/src/EmptySpaceSearch.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

emptyspacesearch-0.1/src/EmptySpaceSearch.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=2.1.0
+numba>=0.61.0
+hnswlib>=0.8.0

emptyspacesearch-0.1/src/EmptySpaceSearch.egg-info/top_level.txt

@@ -0,0 +1 @@
+ess

emptyspacesearch-0.1/src/ess/__init__.py

@@ -0,0 +1 @@
+import src.ess as ess

emptyspacesearch-0.1/src/ess/ess.py

@@ -0,0 +1,228 @@
+import numba
+import hnswlib
+import logging
+import numpy as np
+
+
+logging.basicConfig(level=logging.INFO, format='%(message)s')
+logger = logging.getLogger(__name__)
+
+
+@numba.jit(nopython=True, parallel=True, fastmath=True)
+def clip(a, vmin, vmax):
+    return np.maximum(np.minimum(a, vmax), vmin)
+
+
+@numba.jit(nopython=True, parallel=True, fastmath=True)
+def mean(a):
+    return np.divide(np.sum(a), a.shape[0])
+
+
+def _scale(arr, min_val=None, max_val=None):
+    if min_val is None:
+        min_val = min(arr)
+    
+    if max_val is None:
+        max_val = max(arr)
+
+    scl_arr = (arr - min_val) / (max_val - min_val)
+    return scl_arr, min_val, max_val
+
+
+def _inv_scale(scl_arr, min_val, max_val):
+    return scl_arr*(max_val - min_val) + min_val
+
+
+@numba.jit(nopython=True, parallel=True, fastmath=True)
+def _force(sigma, d):
+    """
+    Optimized Force function.
+    """
+    #ratio = sigma / d # Reuse this computation
+    #np.clip(ratio, a_min=None, a_max=3.1622, out=ratio)  # Avoids overflow
+    #ratio = clip(sigma / d, 0, 3.1622)
+    ratio = np.minimum(sigma/d, 3.1622)
+    #attrac = ratio ** 6
+    #np.clip(attrac, a_min=None, a_max=1000, out=attrac)  # Avoids overflow
+    #attrac = clip(attrac, 0, 1000)
+    attrac = np.minimum(ratio ** 6, 1000)
+    
+    return np.abs(6 * (2 * attrac ** 2 - attrac) / d)
+
+
+def _elastic(es, neighbors, neighbors_dist):
+    """
+    Optimized Elastic force with vectorization.
+    """
+    sigma = mean(neighbors_dist) / 5.0
+    neighbors_dist = np.maximum(neighbors_dist, 0.001)  # Avoids distances < 0.001
+
+    # Vectorized force computation
+    forces = _force(sigma, neighbors_dist)
+
+    # Vectorized displacement computation
+    vecs = (es - neighbors) / neighbors_dist[:, np.newaxis]
+    
+    # Compute the directional force
+    #TODO: check this one
+    direc = np.sum(vecs * forces[:, np.newaxis], axis=0)
+
+    return direc
+
+
+def _empty_center(coor, data, neigh, movestep, iternum:int=100, bounds=np.array([[-1, 1]])):
+    """
+    Empty center search process.
+    """
+    
+    for i in range(iternum):
+        adjs_, distances_ = neigh.knn_query(coor, k=data.shape[1]+1)
+
+        logger.debug(f'Empty Centers {adjs_} {distances_}')
+        
+        direc = _elastic(coor, data[adjs_[0]], distances_[0])
+        mag = np.linalg.norm(direc)
+        if mag < 1e-7:
+            break
+        direc /= mag
+        coor += direc * movestep
+
+        # TODO (4): should the bounds be fixed to [0, 1]?
+        # may help code here 
+        if (coor < bounds[:, 0]).any() or (coor > bounds[:, 1]).any():
+            np.clip(coor, bounds[:, 0], bounds[:, 1], out=coor)
+            break
+
+    return coor
+
+
+def _esa_01(samples, bounds, n:int=None, seed:int=None):
+    '''
+    apply esa in the experiment
+    '''
+    min_val = bounds[:,0]
+    max_val = bounds[:,1]
+    samples, _, _ = _scale(samples, min_val, max_val)
+
+    neigh = hnswlib.Index(space='l2', dim=samples.shape[1])
+    if seed is not None:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48, 
+        random_seed = seed)
+    else:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48)
+    neigh.add_items(samples)
+    
+    #TODO (2): improve by adding one point at a time (avoiding clustering points together) 
+    coors = np.random.uniform(0, 1, (n, samples.shape[1]))
+    logger.debug(f'Coors({n}, {samples.shape[1]})\n{coors}')
+    es_params = []
+    logger.debug(f'Samples\n{samples}')
+    es_params = [_empty_center(coor.reshape(1, -1), samples, neigh, 
+    movestep=0.01, iternum=100, bounds=np.array([[0, 1]]))[0] for coor in coors]
+    logger.debug(f'Params({len(es_params)})\n{es_params}')
+    #rv = np.array(es_params)[:n]
+    rv = np.array(es_params)
+    rv = _inv_scale(rv, min_val=min_val, max_val=max_val)
+    
+    logger.debug(f'RV({rv.shape})\n{rv}')
+
+    return rv
+
+
+def _esa_02(samples, bounds, n:int=None, seed:int=None):
+    '''
+    apply esa in the experiment
+    '''
+    min_val = bounds[:,0]
+    max_val = bounds[:,1]
+    samples, _, _ = _scale(samples, min_val, max_val)
+
+    neigh = hnswlib.Index(space='l2', dim=samples.shape[1])
+    if seed is not None:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48, 
+        random_seed = seed)
+    else:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48)
+    neigh.add_items(samples)
+    
+    #TODO (2): improve by adding one point at a time (avoiding clustering points together) 
+    coors = np.random.uniform(0, 1, (n, samples.shape[1]))
+    logger.debug(f'Coors({n}, {samples.shape[1]})\n{coors}')
+    es_params = []
+    logger.debug(f'Samples\n{samples}')
+    for c in coors:
+        es_param = _empty_center(c.reshape(1, -1), samples, neigh, 
+        movestep=0.01, iternum=100, bounds=np.array([[0, 1]]))
+        es_params.append(es_param[0])
+        samples = np.concatenate((samples, es_param), axis=0)
+        #samples = np.append(samples, es_param)
+        logger.debug(f'Samples\n{samples}')
+        neigh.add_items(es_param)
+    #es_params = [_empty_center(coor.reshape(1, -1), samples, neigh, 
+    #movestep=0.01, iternum=100, bounds=np.array([[0, 1]]))[0] for coor in coors]
+    logger.debug(f'Params({len(es_params)})\n{es_params}')
+    #rv = np.array(es_params)[:n]
+    rv = np.array(es_params)
+    rv = _inv_scale(rv, min_val=min_val, max_val=max_val)
+    
+    logger.debug(f'RV({rv.shape})\n{rv}')
+
+    return rv
+
+
+def esa(samples, bounds, n:int=None, seed:int=None):
+    '''
+    apply esa in the experiment
+    '''
+    min_val = bounds[:,0]
+    max_val = bounds[:,1]
+    samples, _, _ = _scale(samples, min_val, max_val)
+    samples = samples.astype(np.float32)
+
+    neigh = hnswlib.Index(space='l2', dim=samples.shape[1])
+    if seed is not None:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48, 
+        random_seed = seed)
+    else:
+        neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48)
+    
+    #TODO: apply seed number here
+    coors = np.random.uniform(0, 1, (n, samples.shape[1])).astype(np.float32)
+    # increase the sample pool and keep original size as idx
+    idx = len(samples)
+    samples = np.concatenate((samples, coors), axis=0)
+    neigh.add_items(samples)
+
+    iternum = 100
+    movestep=0.01
+
+    for _ in range(iternum):
+        for i in range(idx, len(samples)):
+            p = samples[i]
+            
+            adjs_, distances_ = neigh.knn_query(p, k=samples.shape[1]+2)        
+            direc = _elastic(p, samples[adjs_[0, 1:]], distances_[0, 1:])
+            p += (direc/np.linalg.norm(direc)) * movestep
+            
+            samples[i] = p
+        
+        samples = clip(samples, 0, 1)
+        neigh = hnswlib.Index(space='l2', dim=samples.shape[1])
+        if seed is not None:
+            neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48, 
+            random_seed = seed)
+        else:
+            neigh.init_index(max_elements=len(samples)+n, ef_construction = 200, M=48)
+        neigh.add_items(samples)
+    
+    rv = samples[idx:]
+    rv = _inv_scale(rv, min_val=min_val, max_val=max_val)
+    
+    return rv
+
+
+def ess(samples, bounds, n:int=None, seed:int=None):
+    if type(samples) is not np.ndarray:
+        samples = np.array(samples).astype(np.float32)
+    rv = esa(samples=samples, bounds=bounds, n=n, seed=seed)
+    return np.concatenate((samples, rv), axis=0)

emptyspacesearch-0.1/test/test_ess.py

@@ -0,0 +1,147 @@
+# coding: utf-8
+
+__author__ = 'Mário Antunes'
+__version__ = '0.1'
+__email__ = 'mario.antunes@ua.pt'
+__status__ = 'Development'
+__license__ = 'MIT'
+__copyright__ = '''
+Copyright (c) 2021-2023 Stony Brook University
+Copyright (c) 2021-2023 The Research Foundation of SUNY
+'''
+
+
+import unittest
+import numpy as np
+import ess.ess as ess
+
+
+def calculate_grid_coverage(points, bounds, grid):
+    """
+    Calculates grid-based coverage of N-dimensional points.
+
+    Args:
+        points (np.ndarray): A 2D NumPy array of shape (N_points, N_dims)
+        where N_points is the number of points, and N_dims is the number of dimensions.
+        
+        bounds (np.ndarray): A 2D array of shape (N_dims,2) specifying 
+        the minimum and maximum coordinate for each dimension of the grid.
+        
+        grid (int or tuple or list): The number of bins (cells)
+        along each dimension. If int, it's used for all N_dims.
+        If tuple/list (res1, res2, ..., resN), specifies bins for each dimension.
+
+    Returns:
+        percentage_coverage (float): The percentage of the total grid area (volume) covered.
+    """
+    num_dims = points.shape[1]
+
+    if isinstance(grid, int):
+        bins = [grid] * num_dims
+    elif len(grid) != num_dims:
+        raise ValueError(f"grid_resolutions must be an int or a list/tuple of length {num_dims}")
+    else:
+        bins = list(grid)
+
+    # Define bin edges for each dimension
+    # np.histogramdd expects a list of 1D arrays for bin edges
+    bin_edges = []
+    for d in range(num_dims):
+        bin_edges.append(np.linspace(bounds[d, 0], bounds[d, 1], bins[d] + 1))
+
+    # Use np.histogramdd to count points in each N-dimensional bin
+    # The output 'H' is an N-dimensional array where H[i, j, k, ...]
+    # is the number of points in the corresponding N-dim cell.
+    H, _ = np.histogramdd(points, bins=bin_edges)
+
+    # Create the coverage map: 1 if cell has points, 0 otherwise
+    coverage_map = (H > 0).astype(int)
+
+    # Calculate metrics
+    total_covered_cells = np.sum(coverage_map)
+    
+    total_grid_cells = np.prod(bins) # Product of resolutions for total cells
+
+    if total_grid_cells == 0: # Avoid division by zero if no cells are defined
+        percentage_coverage = 0.0
+    else:
+        percentage_coverage = (total_covered_cells / total_grid_cells)
+
+    # Calculate cell hyper-volume
+    #cell_dimensions = [(max_coords[d] - min_coords[d]) / bins[d] for d in range(num_dims)]
+    #cell_volume = np.prod(cell_dimensions)
+
+    return percentage_coverage
+
+
+class TestESS(unittest.TestCase):
+
+    def test_ess_00(self):
+        points = np.array([[0,0], [5,5], [5,0], [0,5], [2.5,2.5]])
+        bounds = np.array([[0,5], [0,5]])
+        n_points = 100
+        grid = 10
+        
+        rnd_points = np.random.uniform(bounds[0, 0], bounds[0, 1], 
+        size=(n_points, points.shape[1]))
+        b = np.concatenate((points, rnd_points), axis=0)
+        
+        a = ess.ess(points, bounds, n_points)
+
+        coverage_a = calculate_grid_coverage(a, bounds=bounds, grid=grid)
+        coverage_b = calculate_grid_coverage(b, bounds=bounds, grid=grid)
+
+        self.assertGreater(coverage_a, coverage_b)
+    
+    def test_ess_01(self):
+        points = np.array([[0,0], [5,5], [5,0], [0,5], [2.5,2.5]])
+        bounds = np.array([[0, 100], [0, 100]])
+        n_points = 100
+        grid = 10
+        
+        rnd_points = np.random.uniform(bounds[0, 0], bounds[0, 1], 
+        size=(n_points, points.shape[1]))
+        b = np.concatenate((points, rnd_points), axis=0)
+        
+        a = ess.ess(points, bounds, n_points)
+
+        coverage_a = calculate_grid_coverage(a, bounds=bounds, grid=grid)
+        coverage_b = calculate_grid_coverage(b, bounds=bounds, grid=grid)
+
+        self.assertGreater(coverage_a, coverage_b)
+    
+    def test_ess_02(self):
+        points = np.array([[0,0,0], [5,5,5], [5,0,0], [0,5,0], 
+        [0,0,5], [0,5,5], [5,0,5], [5,5,0], [2,2,2]])
+        bounds = np.array([[0, 5], [0, 5], [0, 5]])
+        n_points = 500
+        grid = 10
+        
+        rnd_points = np.random.uniform(bounds[0, 0], bounds[0, 1], 
+        size=(n_points, points.shape[1]))
+        b = np.concatenate((points, rnd_points), axis=0)
+        
+        a = ess.ess(points, bounds, n_points)
+
+        coverage_a = calculate_grid_coverage(a, bounds=bounds, grid=grid)
+        coverage_b = calculate_grid_coverage(b, bounds=bounds, grid=grid)
+
+        self.assertGreater(coverage_a, coverage_b)
+
+    def test_ess_03(self):
+        points = np.array([[0,0,0], [5,5,5], [5,0,0], [0,5,0], 
+        [0,0,5], [0,5,5], [5,0,5], [5,5,0], [2,2,2]])
+        bounds = np.array([[0, 10], [0, 10], [0, 10]])
+        n_points = 500
+        grid = 10
+        
+        rnd_points = np.random.uniform(bounds[0, 0], bounds[0, 1], 
+        size=(n_points, points.shape[1]))
+        b = np.concatenate((points, rnd_points), axis=0)
+        
+        a = ess.ess(points, bounds, n_points)
+
+        coverage_a = calculate_grid_coverage(a, bounds=bounds, grid=grid)
+        coverage_b = calculate_grid_coverage(b, bounds=bounds, grid=grid)
+
+        self.assertGreater(coverage_a, coverage_b)