sampling.design
sampling.design
Functions
| Name | Description |
|---|---|
| fullfactorial | Generates a full factorial sampling plan in the unit cube. |
| generate_clustered_design | Generates a clustered design. |
| generate_collinear_design | Generates a collinear design (poorly projected). |
| generate_grid_design | Generates a regular grid design. |
| generate_qmc_lhs_design | Generates a Latin Hypercube Sampling design using QMC. |
| generate_sobol_design | Generates a Sobol sequence design. |
| generate_uniform_design | Generate a uniform random experimental design. |
fullfactorial
sampling.design.fullfactorial(q, Edges=1)Generates a full factorial sampling plan in the unit cube.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| q | list or np.ndarray | A list or array containing the number of points along each dimension (k-vector). | required |
| Edges | int | Determines spacing of points. If Edges=1, points are equally spaced from edge to edge (default). Otherwise, points will be in the centers of n = q[0]q[1]…*q[k-1] bins filling the unit cube. |
1 |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | Full factorial sampling plan as an array of shape (n, k), where n is the total number of points and k is the number of dimensions. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If any dimension in q is less than 2. |
Notes
Many thanks to the original author of this code, A Sobester, for providing the original Matlab code under the GNU Licence. Original Matlab Code: Copyright 2007 A Sobester: “This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU General Public License and GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.”
Examples
>>> from spotpython.utils.sampling import fullfactorial
>>> q = [3, 2]
>>> X = fullfactorial(q, Edges=0)
>>> print(X)
[[0. 0. ]
[0. 0.75 ]
[0.41666667 0. ]
[0.41666667 0.75 ]
[0.83333333 0. ]
[0.83333333 0.75 ]]
>>> X = fullfactorial(q, Edges=1)
>>> print(X)
[[0. 0. ]
[0. 1. ]
[0.5 0. ]
[0.5 1. ]
[1. 0. ]
[1. 1. ]]generate_clustered_design
sampling.design.generate_clustered_design(
bounds,
n_design,
n_clusters,
seed=None,
)Generates a clustered design.
Generates clusters of points using sklearn.datasets.make_blobs. Points are scaled to the provided bounds.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. | required |
| n_design | int | The number of points to generate. | required |
| n_clusters | int | The number of clusters. | required |
| seed | Optional[Union[int, Generator]] | Random seed or generator. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: A 2D array of shape (n_design, n_dim) with clustered points. |
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_clustered_design
>>> bounds = [(-5, 5), (0, 10)]
>>> X = generate_clustered_design(bounds, n_design=5, n_clusters=2, seed=42)
>>> X.shape
(5, 2)
>>> np.all((X >= [-5, 0]) & (X <= [5, 10]))
Truegenerate_collinear_design
sampling.design.generate_collinear_design(
bounds,
n_design,
sigma=0.01,
seed=None,
)Generates a collinear design (poorly projected).
Currently implemented for 2D designs only. Generates points along a line with some Gaussian noise. The points are scaled to the provided bounds.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. | required |
| n_design | int | The number of points to generate. | required |
| sigma | float | The standard deviation of the noise added to the y-coordinate (relative to unit scale). Defaults to 0.01. | 0.01 |
| seed | Optional[Union[int, Generator]] | Random seed or generator. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: A 2D array of shape (n_design, n_dim) with collinear points. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If dimension is not 2. |
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_collinear_design
>>> bounds = [(0, 1), (0, 1)]
>>> X = generate_collinear_design(bounds, n_design=10, seed=42)
>>> X.shape
(10, 2)generate_grid_design
sampling.design.generate_grid_design(bounds, n_design, seed=None)Generates a regular grid design.
Points are generated by creating a regular grid where the number of points per dimension is derived from n_design (floor(n_design^(1/n_dim))).
Note: The actual number of points returned might be less than n_design if n_design is not a perfect power of n_dim.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. | required |
| n_design | int | The target number of points. Used to determine points per dimension. | required |
| seed | Optional[Union[int, Generator]] | Unused, kept for API consistency. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: A 2D array of shape (points_per_dim^n_dim, n_dim) with grid points. |
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_grid_design
>>> bounds = [(0, 1), (0, 1)]
>>> X = generate_grid_design(bounds, n_design=25) # 5^2 = 25
>>> X.shape
(25, 2)generate_qmc_lhs_design
sampling.design.generate_qmc_lhs_design(bounds, n_design, seed=None)Generates a Latin Hypercube Sampling design using QMC.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. | required |
| n_design | int | The number of points to generate. | required |
| seed | Optional[Union[int, Generator]] | Random seed or generator. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: An array of shape (n_design, n_dim) containing the generated LHS points. |
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_qmc_lhs_design
>>> bounds = [(-5, 5), (0, 10)]
>>> X = generate_qmc_lhs_design(bounds, n_design=5, seed=42)
>>> X.shape
(5, 2)generate_sobol_design
sampling.design.generate_sobol_design(bounds, n_design, seed=None)Generates a Sobol sequence design.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. | required |
| n_design | int | The number of points to generate. | required |
| seed | Optional[Union[int, Generator]] | Random seed or generator. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: An array of shape (n_design, n_dim) containing the generated Sobol sequence points. |
Notes
- The Sobol sequence is generated with a length that is a power of 2.
- Scrambling is enabled for improved uniformity.
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_sobol_design
>>> bounds = [(-5, 5), (0, 10)]
>>> X = generate_sobol_design(bounds, n_design=5, seed=42)
>>> X.shape
(5, 2)generate_uniform_design
sampling.design.generate_uniform_design(bounds, n_design, seed=None)Generate a uniform random experimental design.
Generates n_design points uniformly distributed within the specified bounds. This function is compatible with SpotOptim’s random number handling.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| bounds | Union[List[Tuple[float, float]], np.ndarray] | Design space bounds. List of (lower, upper) tuples for each dimension. | required |
| n_design | int | Number of design points to generate. | required |
| seed | Optional[Union[int, Generator]] | Random seed or generator. Defaults to None. | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | np.ndarray: Generated design points of shape (n_design, n_dim). |
Examples
>>> import numpy as np
>>> from spotoptim.sampling.design import generate_uniform_design
>>> bounds = [(-5, 5), (0, 10)]
>>> X = generate_uniform_design(bounds, n_design=5, seed=42)
>>> X.shape
(5, 2)
>>> np.all((X >= [-5, 0]) & (X <= [5, 10]))
True