0.29.23

Designs

Author: bartzbeielstein

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spotpython"
-version = "0.29.22"
+version = "0.29.23"
 authors = [
   { name="T. Bartz-Beielstein", email="tbb@bartzundbartz.de" }
 ]

src/spotpython/design/clustered.py

@@ -0,0 +1,52 @@
+import numpy as np
+from spotpython.design.designs import Designs
+from typing import Optional
+from sklearn.datasets import make_blobs
+
+
+class Clustered(Designs):
+    """
+    Super class for clustered designs.
+
+    Attributes:
+        k (int): The number of factors.
+        seed (int): The seed for the random number generator.
+    """
+
+    def __init__(self, k: int = 2, seed: int = 123) -> None:
+        """
+        Initializes a clustered design object.
+
+        Args:
+            k (int): The number of factors. Defaults to 2.
+            seed (int): The seed for the random number generator. Defaults to 123.
+        """
+        super().__init__(k, seed)
+        self.k = k
+        self.seed = seed
+
+    def generate_clustered_design(self, n_points: int, n_clusters: int, seed: Optional[int] = None) -> np.ndarray:
+        """Generates a clustered design.
+
+        Args:
+            n_points (int): The number of points to generate.
+            n_clusters (int): The number of clusters.
+            seed (Optional[int]): Optional seed for reproducibility.
+
+        Returns:
+            numpy.ndarray: A 2D array of shape (n_points, n_dim) with clustered points.
+
+        Examples:
+            >>> from spotpython.design.clustered import Clustered
+            >>> clustered_design = Clustered(k=3)
+            >>> clustered_design.generate_clustered_design(n_points=100, n_clusters=5, seed=42)
+            array([[0.12, 0.34, 0.56],
+                   [0.23, 0.45, 0.67],
+                   ...])
+        """
+        X, _ = make_blobs(n_samples=n_points, n_features=self.k, centers=n_clusters, cluster_std=0.05, random_state=seed, center_box=(0.1, 0.9))
+        X_min = X.min(axis=0)
+        X_max = X.max(axis=0)
+        if np.any(X_min < 0) or np.any(X_max > 1):
+            X = (X - X_min) / (X_max - X_min + 1e-6)
+        return X

src/spotpython/design/factorial.py

@@ -1,9 +1,9 @@
 import numpy as np
 from numpy import mgrid
-from .designs import designs
+from spotpython.design.designs import Designs
 
 
-class factorial(designs):
+class factorial(Designs):
     """
     Super class for factorial designs.
 

src/spotpython/design/grid.py

@@ -0,0 +1,51 @@
+import numpy as np
+from spotpython.design.designs import Designs
+
+
+class Grid(Designs):
+    """
+    Super class for grid designs.
+
+    Attributes:
+        k (int): The number of factors (dimension).
+        seed (int): The seed for the random number generator.
+    """
+
+    def __init__(self, k: int = 2, seed: int = 123) -> None:
+        """
+        Initializes a grid design object.
+
+        Args:
+            k (int): The number of factors. Defaults to 2.
+            seed (int): The seed for the random number generator. Defaults to 123.
+        """
+        super().__init__(k, seed)
+        self.k = k
+        self.seed = seed
+
+    def generate_grid_design(self, points_per_dim: int) -> np.ndarray:
+        """Generates a regular grid design.
+
+        Args:
+            points_per_dim (int): The number of points per dimension.
+
+        Returns:
+            numpy.ndarray: A 2D array of shape (points_per_dim^n_dim, n_dim) with grid points.
+
+        Examples:
+            >>> from spotpython.design.grid import Grid
+            >>> grid_design = Grid(k=2)
+            >>> grid_points = grid_design.generate_grid_design(points_per_dim=5)
+            >>> print(grid_points)
+            [[0.  0. ]
+             [0.  0.25]
+             [0.  0.5 ]
+             ...
+             [1.   1. ]]
+
+        """
+        if self.k != 2:
+            raise ValueError("Grid design currently implemented for 2D only for simplicity.")
+        ticks = np.linspace(0, 1, points_per_dim, endpoint=True)
+        x, y = np.meshgrid(ticks, ticks)
+        return np.vstack([x.ravel(), y.ravel()]).T

src/spotpython/design/poor.py

@@ -0,0 +1,52 @@
+import numpy as np
+from spotpython.design.designs import Designs
+
+
+class Poor(Designs):
+    """
+    Super class for poorly projected (collinear) designs.
+
+    Attributes:
+        k (int): The number of factors.
+        seed (int): The seed for the random number generator.
+    """
+
+    def __init__(self, k: int = 2, seed: int = 123) -> None:
+        """
+        Initializes a Poor design object.
+
+        Args:
+            k (int): The number of factors. Defaults to 2.
+            seed (int): The seed for the random number generator. Defaults to 123.
+        """
+        super().__init__(k, seed)
+        self.k = k
+        self.seed = seed
+
+    def generate_collinear_design(self, n_points: int) -> np.ndarray:
+        """Generates a collinear design (poorly projected).
+
+        Args:
+            n_points (int): The number of points to generate.
+
+        Returns:
+            numpy.ndarray: A 2D array of shape (n_points, n_dim) with collinear points.
+
+        Examples:
+            >>> from spotpython.design.poor import Poor
+            >>> poor_design = Poor(k=2)
+            >>> collinear_points = poor_design.generate_collinear_design(n_points=10)
+            >>> print(collinear_points)
+            [[0.1  0.5 ]
+             [0.2  0.5 ]
+             [0.3  0.5 ]
+             ...
+             [0.9  0.5 ]]
+
+        """
+        if self.k != 2:
+            raise ValueError("Collinear design currently implemented for 2D only.")
+        x_coords = np.linspace(0.1, 0.9, n_points)
+        y_coords = np.full_like(x_coords, 0.5)  # All points on y=0.5 line
+        # y_coords = 0.2 * x_coords + 0.3  # Or a sloped line
+        return np.vstack([x_coords, y_coords]).T

src/spotpython/design/random.py

@@ -0,0 +1,51 @@
+import numpy as np
+from spotpython.design.designs import Designs
+
+
+class Random(Designs):
+    """
+    Super class for random designs.
+
+    Attributes:
+        k (int): The number of factors.
+        seed (int): The seed for the random number generator.
+    """
+
+    def __init__(self, k: int = 2, seed: int = 123) -> None:
+        """
+        Initializes a random design object.
+
+        Args:
+            k (int): The number of factors. Defaults to 2.
+            seed (int): The seed for the random number generator. Defaults to 123.
+        """
+        super().__init__(k, seed)
+        self.k = k
+        self.seed = seed
+
+    def uniform(self, n_points: int, seed: int = None) -> np.ndarray:
+        """
+        Generates a random design using uniform distribution.
+
+        Args:
+            n_points (int): The number of points to generate.
+            seed (int, optional): The seed for the random number generator. If None, uses the instance's seed.
+
+        Returns:
+            numpy.ndarray: A 2D array of shape (n_points, k) with random values in [0, 1).
+
+        Examples:
+            >>> from spotpython.design.random import Random
+            >>> random_design = Random(k=3)
+            >>> random_design.uniform(n_points=5)
+            array([[0.123, 0.456, 0.789],
+                   [0.234, 0.567, 0.890],
+                   [0.345, 0.678, 0.901],
+                   [0.456, 0.789, 0.012],
+                   [0.567, 0.890, 0.123]])
+
+        """
+        if seed is not None:
+            seed = self.seed
+        rng = np.random.default_rng(seed)
+        return rng.random((n_points, self.k))

src/spotpython/design/sobol.py

@@ -0,0 +1,57 @@
+import numpy as np
+from spotpython.design.designs import Designs
+from scipy.stats import qmc
+from typing import Optional
+
+
+class Sobol(Designs):
+    """
+    Super class for sobol designs.
+
+    Attributes:
+        k (int): The number of factors.
+        seed (int): The seed for the random number generator.
+    """
+
+    def __init__(self, k: int = 2, seed: int = 123) -> None:
+        """
+        Initializes a sobol design object.
+
+        Args:
+            k (int): The number of factors (dimension). Defaults to 2.
+            seed (int): The seed for the random number generator. Defaults to 123.
+        """
+        super().__init__(k, seed)
+        self.k = k
+        self.seed = seed
+
+    def generate_sobol_design(self, n_points: int, seed: int = None) -> np.ndarray:
+        """Generates a Sobol sequence design
+
+        Args:
+            n_points (int):
+                The number of points to generate in the Sobol sequence.
+            seed (Optional[int]):
+                The seed for the random number generator.
+                If None, uses the instance's seed.
+
+        Returns:
+            np.ndarray: An array of shape (n_points, n_dim) containing the generated Sobol sequence points.
+
+        Notes:
+            - The Sobol sequence is generated with a length that is a power of 2. The function generates at least n_points and returns the first n_points.
+            - For n_points not being a power of 2, extra points are generated and truncated.
+            - Scrambling is enabled for improved uniformity.
+
+        Examples:
+            >>> from spotpython.design.sobol import Sobol
+            >>> sobol_design = Sobol(k=3, seed=42)
+            >>> sobol_points = sobol_design.generate_sobol_design(n_points=10)
+            >>> print(sobol_points.shape)
+            (10, 3)
+        """
+        if seed is not None:
+            self.seed = seed
+        sampler = qmc.Sobol(d=self.k, scramble=True, seed=seed)
+        m = int(np.ceil(np.log2(n_points)))
+        return sampler.random_base2(m=m)[:n_points, :]

src/spotpython/design/spacefilling.py

@@ -3,6 +3,7 @@
 from spotpython.utils.transform import scale
 from typing import Optional, Union
 from spotpython.design.designs import Designs
+from scipy.stats import qmc
 
 
 class SpaceFilling(Designs):
@@ -94,3 +95,33 @@ def scipy_lhd(
         sample = self.sampler.random(n=n)
         des = scale(sample, lower, upper)
         return np.repeat(des, repeats, axis=0)
+
+    def generate_qms_lhs_design(self, n_points: int, seed: Optional[int] = None) -> np.ndarray:
+        """Generates a Latin Hypercube Sampling design using the `scipy.stats.qmc` module.
+        Generates a Latin Hypercube Sampling (LHS) design with the specified number of points
+        and dimensions.
+
+        Args:
+            n_points (int): The number of points to generate.
+            seed (Optional[int]):
+                Seed for the random number generator to ensure reproducibility.
+                Defaults to None. If None, uses the seed specified during initialization.
+
+        Returns:
+            np.ndarray: An array of shape (n_points, n_dim) containing the generated Latin Hypercube Sampling points.
+
+        Notes:
+            - The Latin Hypercube Sampling is generated with a specified number of points and dimensions.
+            - The points are uniformly distributed across the unit hypercube [0, 1]^n_dim.
+
+        Examples:
+            >>> from spotpython.design.spacefilling import SpaceFilling
+            >>> lhs_design = SpaceFilling(k=3, seed=42)
+            >>> lhs_points = lhs_design.generate_qms_lhs_design(n_points=10)
+            >>> print(lhs_points.shape)
+            (10, 3)
+        """
+        if seed is None:
+            seed = self.seed
+        sampler = qmc.LatinHypercube(d=self.k, seed=seed)
+        return sampler.random(n=n_points)