0
# Sampling & Randomized Designs
1
2
Space-filling and randomized experimental designs for computer experiments, Monte Carlo simulation, and uncertainty quantification. These designs provide uniform coverage of the experimental space and are particularly suitable for deterministic simulations and high-dimensional problems.
3
4
## Capabilities
5
6
### Latin Hypercube Sampling
7
8
Stratified sampling method that ensures each factor is uniformly sampled across its range while maintaining randomness.
9
10
```python { .api }
11
def lhs(n, samples=None, criterion=None, iterations=None, random_state=None, correlation_matrix=None):
12
"""
13
Generate a Latin Hypercube Sampling design
14
15
Parameters:
16
- n: int, number of factors to generate samples for
17
- samples: int, optional, number of samples to generate (default: n)
18
- criterion: str, optional, optimization criterion for sample placement
19
- iterations: int, optional, number of iterations for optimization (default: 5)
20
- random_state: int or RandomState, optional, random seed for reproducibility
21
- correlation_matrix: ndarray, optional, enforce correlation between factors
22
23
Returns:
24
- H: 2d-array, design matrix normalized to [0,1] with uniform factor spacing
25
"""
26
```
27
28
**Criterion Options:**
29
- **None** (default): Simple randomized Latin hypercube
30
- **"center"** or **"c"**: Centered Latin hypercube (samples at stratum centers)
31
- **"maximin"** or **"m"**: Maximizes minimum distance between sample points
32
- **"centermaximin"** or **"cm"**: Combines center and maximin criteria
33
- **"correlation"** or **"corr"**: Minimizes correlations between factors
34
35
**Key Features:**
36
- Ensures each factor is sampled across its full range
37
- Maintains stratification properties for any number of samples
38
- Excellent space-filling properties for computer experiments
39
- Supports correlation control and distance optimization
40
41
**Usage Examples:**
42
```python
43
import pyDOE3
44
import numpy as np
45
46
# Basic 4-factor LHS with 10 samples
47
design = pyDOE3.lhs(4, samples=10, random_state=42)
48
print(f"Design shape: {design.shape}") # (10, 4)
49
50
# Centered LHS for more uniform coverage
51
centered_design = pyDOE3.lhs(3, samples=8, criterion='center', random_state=42)
52
53
# Maximin LHS for maximum space-filling
54
maximin_design = pyDOE3.lhs(5, samples=20, criterion='maximin', iterations=100)
55
56
# LHS with enforced correlation structure
57
correlation_matrix = np.array([[1.0, 0.5], [0.5, 1.0]])
58
correlated_design = pyDOE3.lhs(2, samples=15, correlation_matrix=correlation_matrix)
59
```
60
61
### Grid Designs
62
63
Deterministic space-filling designs with regular structure for systematic exploration of experimental space.
64
65
#### Sukharev Grid
66
67
Low-discrepancy grid design with optimal covering radius properties based on max-norm distance.
68
69
```python { .api }
70
def sukharev_grid(num_points, dimension):
71
"""
72
Create Sukharev grid in unit hypercube
73
74
Parameters:
75
- num_points: int, number of points to generate
76
num_points^(1/dimension) must be integer
77
- dimension: int, dimensionality of the space
78
79
Returns:
80
- points: 2d-array, (num_points, dimension) grid coordinates in [0,1]
81
"""
82
```
83
84
**Key Features:**
85
- Points placed at centroids of subcells (not on boundaries)
86
- Optimal covering radius for max-norm distances
87
- Deterministic and reproducible point placement
88
- Uniform space-filling with regular structure
89
90
**Usage Example:**
91
```python
92
import pyDOE3
93
94
# 3D Sukharev grid with 27 points (3^3)
95
grid = pyDOE3.sukharev_grid(27, 3)
96
print(f"Grid shape: {grid.shape}") # (27, 3)
97
98
# 2D grid with 16 points (4^2)
99
grid_2d = pyDOE3.sukharev_grid(16, 2)
100
print(f"Grid shape: {grid_2d.shape}") # (16, 2)
101
102
# Note: num_points must be a perfect power of dimension
103
# For 3D: valid values are 1, 8, 27, 64, 125, ... (1^3, 2^3, 3^3, 4^3, 5^3, ...)
104
```
105
106
### Design Manipulation
107
108
Tools for modifying and augmenting existing experimental designs.
109
110
#### Design Folding
111
112
Augments 2-level designs by adding their geometric reflection to reduce confounding effects.
113
114
```python { .api }
115
def fold(H, columns=None):
116
"""
117
Fold a design to reduce confounding effects
118
119
Parameters:
120
- H: 2d-array, design matrix to be folded (must be 2-level)
121
- columns: array-like, optional, indices of columns to fold (default: all)
122
123
Returns:
124
- Hf: 2d-array, folded design matrix with doubled number of runs
125
"""
126
```
127
128
**Key Features:**
129
- Doubles the number of experimental runs
130
- Reduces confounding by creating geometric reflections
131
- Can fold specific columns or entire design
132
- Only works with 2-level factors
133
134
**Usage Example:**
135
```python
136
import pyDOE3
137
138
# Create a fractional factorial design
139
original_design = pyDOE3.fracfact("a b ab")
140
print(f"Original shape: {original_design.shape}") # (4, 3)
141
142
# Fold the entire design
143
folded_design = pyDOE3.fold(original_design)
144
print(f"Folded shape: {folded_design.shape}") # (8, 3)
145
146
# Fold only specific columns (first two factors)
147
partial_fold = pyDOE3.fold(original_design, columns=[0, 1])
148
print(f"Partial fold shape: {partial_fold.shape}") # (8, 3)
149
```
150
151
## Design Selection Guidelines
152
153
### When to Use Each Design Type:
154
155
**Latin Hypercube Sampling:**
156
- **Best for:** Computer experiments, Monte Carlo simulation, uncertainty quantification
157
- **Use when:** Need good space-filling properties with random sampling
158
- **Factors:** Any number (scales well to high dimensions)
159
- **Advantages:** Excellent coverage, flexible sample sizes, optimization criteria
160
161
**Sukharev Grid:**
162
- **Best for:** Deterministic simulations, systematic space exploration
163
- **Use when:** Need reproducible, regular point placement
164
- **Factors:** Low to moderate dimensions (constraint: num_points^(1/dimension) = integer)
165
- **Advantages:** Optimal covering radius, deterministic placement
166
167
**Design Folding:**
168
- **Best for:** Augmenting existing 2-level designs, resolution enhancement
169
- **Use when:** Initial design shows confounding, need to separate main effects from interactions
170
- **Factors:** Any number of 2-level factors
171
- **Advantages:** Doubles information, reduces confounding, cost-effective augmentation
172
173
### LHS Criterion Selection:
174
175
| Criterion | Best For | Properties |
176
|-----------|----------|------------|
177
| None | General use | Random placement within strata |
178
| "center" | Uniform coverage | Points at stratum centers |
179
| "maximin" | Space-filling | Maximizes minimum distance |
180
| "centermaximin" | Optimal coverage | Combines center + maximin |
181
| "correlation" | Independence | Minimizes factor correlations |
182
183
### Sample Size Recommendations:
184
185
- **Computer experiments:** 10-20 samples per factor
186
- **Monte Carlo simulation:** Based on convergence requirements
187
- **Screening studies:** 5-10 samples per factor minimum
188
- **Response surface:** Combine with RSM designs for modeling
189
190
## Types
191
192
```python { .api }
193
import numpy as np
194
from typing import Optional, Union, Tuple
195
from numpy.random import RandomState
196
197
# Type aliases
198
DesignMatrix = np.ndarray
199
RandomSeed = Union[int, RandomState, None]
200
OptimizationCriterion = Optional[str]
201
ColumnIndices = Optional[Union[list, np.ndarray]]
202
CorrelationMatrix = Optional[np.ndarray]
203
```
204
205
## Integration with Other Design Types
206
207
Sampling and randomized designs complement other experimental design approaches:
208
209
- **With Factorial Designs:** Use LHS for initial exploration, then factorial for detailed study
210
- **With RSM:** Combine LHS screening with Box-Behnken/CCD for optimization
211
- **With Optimal Designs:** Use LHS to generate candidate sets for optimal design algorithms
212
- **Sequential Approach:** Start with LHS screening → Fold promising regions → Apply RSM