0
# Optimal Experimental Design
1

2
Advanced experimental design algorithms with multiple optimality criteria for creating customized experimental plans. These methods provide maximum statistical efficiency for specific modeling objectives by optimizing mathematical criteria that measure design quality.
3

4
## Capabilities
5

6
### Main Optimal Design Function
7

8
Generate optimal experimental designs using various algorithms and optimality criteria.
9

10
```python { .api }
11
def optimal_design(
12
    candidates: np.ndarray,
13
    n_points: int,
14
    degree: int,
15
    criterion: Literal["D", "A", "I"] = "D",
16
    method: Literal["sequential", "simple_exchange", "fedorov", "modified_fedorov", "detmax"] = "detmax",
17
    alpha: float = 0.0,
18
    max_iter: int = 200
19
) -> Tuple[np.ndarray, dict]:
20
    """
21
    Generate an optimal experimental design using specified algorithm and criterion
22
    
23
    Parameters:
24
    - candidates: 2d-array, candidate set (region R) of shape (N0, k)
25
    - n_points: int, requested design size (n >= p recommended)
26
    - degree: int, polynomial degree of the model
27
    - criterion: str, optimality criterion - "D", "A", or "I" (default "D")
28
    - method: str, algorithm - "sequential", "simple_exchange", "fedorov", 
29
             "modified_fedorov", or "detmax" (default "detmax")
30
    - alpha: float, augmentation parameter for information matrix (default 0.0)
31
    - max_iter: int, maximum iterations for iterative methods (default 200)
32
    
33
    Returns:
34
    - design: 2d-array, selected design points of shape (n_points, k)
35
    - info: dict, design statistics including criterion value and efficiencies
36
    """
37
```
38

39
**Usage Example:**
40
```python
41
import pyDOE3
42
import numpy as np
43

44
# Generate candidate set for 3 factors
45
candidates = pyDOE3.doe_optimal.generate_candidate_set(n_factors=3, n_levels=5)
46

47
# Create D-optimal design with 15 points for quadratic model
48
design, info = pyDOE3.doe_optimal.optimal_design(
49
    candidates=candidates,
50
    n_points=15,
51
    degree=2,  # quadratic model
52
    criterion="D",
53
    method="detmax"
54
)
55

56
print(f"Design shape: {design.shape}")
57
print(f"D-efficiency: {info['D_eff']:.3f}")
58
print(f"Criterion value: {info['score']:.3f}")
59
```
60

61
### Candidate Set Generation
62

63
Create candidate point sets for defining the experimental design space.
64

65
```python { .api }
66
def generate_candidate_set(n_factors: int, n_levels: int, bounds: Optional[List[Tuple[float, float]]] = None) -> np.ndarray:
67
    """
68
    Generate candidate points for design space
69
    
70
    Parameters:
71
    - n_factors: int, number of factors
72
    - n_levels: int, number of levels per factor
73
    - bounds: list of tuples, optional, (min, max) bounds for each factor
74
    
75
    Returns:
76
    - candidates: 2d-array, candidate points in design space
77
    """
78
```
79

80
**Usage Example:**
81
```python
82
import pyDOE3
83

84
# Generate 5x5x5 grid for 3 factors in [-1, 1] range
85
candidates = pyDOE3.doe_optimal.generate_candidate_set(n_factors=3, n_levels=5)
86

87
# Custom bounds for each factor
88
bounds = [(-2, 2), (0, 10), (50, 100)]
89
custom_candidates = pyDOE3.doe_optimal.generate_candidate_set(
90
    n_factors=3, n_levels=7, bounds=bounds
91
)
92
```
93

94
## Optimization Algorithms
95

96
### DETMAX Algorithm
97

98
Modern algorithm for D-optimal designs with excellent convergence properties.
99

100
```python { .api }
101
def detmax(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray:
102
    """
103
    DETMAX algorithm for optimal experimental design
104
    
105
    Parameters:
106
    - candidates: 2d-array, candidate point set
107
    - n_points: int, number of design points to select
108
    - degree: int, polynomial model degree
109
    - criterion: str, optimality criterion
110
    - alpha: float, augmentation parameter
111
    - max_iter: int, maximum iterations
112
    
113
    Returns:
114
    - design: 2d-array, optimal design points
115
    """
116
```
117

118
### Fedorov Algorithm
119

120
Classical exchange algorithm for optimal design construction.
121

122
```python { .api }
123
def fedorov(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray:
124
    """
125
    Fedorov algorithm for optimal experimental design
126
    
127
    Parameters:
128
    - candidates: 2d-array, candidate point set
129
    - n_points: int, number of design points to select
130
    - degree: int, polynomial model degree  
131
    - criterion: str, optimality criterion
132
    - alpha: float, augmentation parameter
133
    - max_iter: int, maximum iterations
134
    
135
    Returns:
136
    - design: 2d-array, optimal design points
137
    """
138
```
139

140
### Modified Fedorov Algorithm
141

142
Enhanced version of Fedorov algorithm with improved performance.
143

144
```python { .api }
145
def modified_fedorov(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray:
146
    """
147
    Modified Fedorov algorithm for optimal experimental design
148
    
149
    Parameters:
150
    - candidates: 2d-array, candidate point set
151
    - n_points: int, number of design points to select
152
    - degree: int, polynomial model degree
153
    - criterion: str, optimality criterion
154
    - alpha: float, augmentation parameter
155
    - max_iter: int, maximum iterations
156
    
157
    Returns:
158
    - design: 2d-array, optimal design points
159
    """
160
```
161

162
### Exchange Algorithms
163

164
#### Simple Exchange (Wynn-Mitchell)
165

166
Point-exchange algorithm for optimal design improvement.
167

168
```python { .api }
169
def simple_exchange_wynn_mitchell(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray:
170
    """
171
    Simple Exchange (Wynn-Mitchell) algorithm
172
    
173
    Parameters:
174
    - candidates: 2d-array, candidate point set
175
    - n_points: int, number of design points to select
176
    - degree: int, polynomial model degree
177
    - criterion: str, optimality criterion  
178
    - alpha: float, augmentation parameter
179
    - max_iter: int, maximum iterations
180
    
181
    Returns:
182
    - design: 2d-array, optimal design points
183
    """
184
```
185

186
#### Sequential Dykstra Algorithm
187

188
Sequential algorithm for optimal design construction.
189

190
```python { .api }
191
def sequential_dykstra(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0) -> np.ndarray:
192
    """
193
    Sequential Dykstra algorithm for optimal design
194
    
195
    Parameters:
196
    - candidates: 2d-array, candidate point set
197
    - n_points: int, number of design points to select
198
    - degree: int, polynomial model degree
199
    - criterion: str, optimality criterion
200
    - alpha: float, augmentation parameter
201
    
202
    Returns:
203
    - design: 2d-array, optimal design points
204
    """
205
```
206

207
## Optimality Criteria
208

209
### D-Optimality
210

211
Maximizes the determinant of the information matrix, minimizing the volume of confidence ellipsoids.
212

213
```python { .api }
214
def d_optimality(M: np.ndarray) -> float:
215
    """
216
    Compute D-optimality criterion value
217
    
218
    Parameters:
219
    - M: 2d-array, information matrix
220
    
221
    Returns:
222
    - criterion: float, D-optimality value (determinant)
223
    """
224
```
225

226
### A-Optimality
227

228
Minimizes the trace of the inverse information matrix, minimizing average parameter variance.
229

230
```python { .api }
231
def a_optimality(M: np.ndarray) -> float:
232
    """
233
    Compute A-optimality criterion value
234
    
235
    Parameters:
236
    - M: 2d-array, information matrix
237
    
238
    Returns:
239
    - criterion: float, A-optimality value (negative trace of inverse)
240
    """
241
```
242

243
### I-Optimality
244

245
Minimizes the integrated prediction variance over the design region.
246

247
```python { .api }
248
def i_optimality(M_X: np.ndarray, moment_matrix: np.ndarray) -> float:
249
    """
250
    Compute I-optimality criterion value
251
    
252
    Parameters:
253
    - M_X: 2d-array, information matrix
254
    - moment_matrix: 2d-array, uniform moment matrix
255
    
256
    Returns:
257
    - criterion: float, I-optimality value
258
    """
259
```
260

261
### Additional Criteria
262

263
```python { .api }
264
def c_optimality(M: np.ndarray, c: np.ndarray) -> float:
265
    """
266
    Compute C-optimality for linear combination of parameters
267
    
268
    Parameters:
269
    - M: 2d-array, information matrix
270
    - c: 1d-array, linear combination coefficients
271
    
272
    Returns:
273
    - criterion: float, C-optimality value
274
    """
275
```
276

277
```python { .api }
278
def e_optimality(M: np.ndarray) -> float:
279
    """
280
    Compute E-optimality (maximum eigenvalue)
281
    
282
    Parameters:
283
    - M: 2d-array, information matrix
284
    
285
    Returns:
286
    - criterion: float, E-optimality value
287
    """
288
```
289

290
```python { .api }
291
def g_optimality(M: np.ndarray, candidates: np.ndarray) -> float:
292
    """
293
    Compute G-optimality (maximum prediction variance)
294
    
295
    Parameters:
296
    - M: 2d-array, information matrix
297
    - candidates: 2d-array, candidate points
298
    
299
    Returns:
300
    - criterion: float, G-optimality value
301
    """
302
```
303

304
## Model Building Functions
305

306
### Design Matrix Construction
307

308
```python { .api }
309
def build_design_matrix(X: np.ndarray, degree: int) -> np.ndarray:
310
    """
311
    Build design matrix for polynomial models
312
    
313
    Parameters:
314
    - X: 2d-array, design points
315
    - degree: int, polynomial degree
316
    
317
    Returns:
318
    - design_matrix: 2d-array, expanded design matrix with polynomial terms
319
    """
320
```
321

322
### Moment Matrix Construction
323

324
```python { .api }
325
def build_uniform_moment_matrix(X: np.ndarray) -> np.ndarray:
326
    """
327
    Build uniform moment matrix for I-optimality
328
    
329
    Parameters:
330
    - X: 2d-array, candidate points
331
    
332
    Returns:
333
    - moment_matrix: 2d-array, uniform moment matrix
334
    """
335
```
336

337
## Efficiency Measures
338

339
### D-Efficiency
340

341
```python { .api }
342
def d_efficiency(X: np.ndarray) -> float:
343
    """
344
    Compute D-efficiency of experimental design
345
    
346
    Parameters:
347
    - X: 2d-array, design matrix
348
    
349
    Returns:
350
    - efficiency: float, D-efficiency (0-1 scale)
351
    """
352
```
353

354
### A-Efficiency
355

356
```python { .api }
357
def a_efficiency(X: np.ndarray) -> float:
358
    """
359
    Compute A-efficiency of experimental design
360
    
361
    Parameters:
362
    - X: 2d-array, design matrix
363
    
364
    Returns:
365
    - efficiency: float, A-efficiency (0-1 scale)
366
    """
367
```
368

369
## Utility Functions
370

371
### Information Matrix
372

373
```python { .api }
374
def information_matrix(X: np.ndarray, alpha: float = 0.0) -> np.ndarray:
375
    """
376
    Compute information matrix from design matrix
377
    
378
    Parameters:
379
    - X: 2d-array, design matrix
380
    - alpha: float, augmentation parameter
381
    
382
    Returns:
383
    - M: 2d-array, information matrix X^T X + alpha*I
384
    """
385
```
386

387
### Criterion Value
388

389
```python { .api }
390
def criterion_value(X: np.ndarray, criterion: str, X0: np.ndarray = None, alpha: float = 0.0, M_moment: np.ndarray = None) -> float:
391
    """
392
    Compute criterion value for design evaluation
393
    
394
    Parameters:
395
    - X: 2d-array, design matrix
396
    - criterion: str, optimality criterion name
397
    - X0: 2d-array, optional, candidate set for some criteria
398
    - alpha: float, augmentation parameter
399
    - M_moment: 2d-array, optional, moment matrix for I-optimality
400
    
401
    Returns:
402
    - value: float, criterion value
403
    """
404
```
405

406
## Optimality Criterion Selection Guide
407

408
| Criterion | Optimizes | Best For | Mathematical Objective |
409
|-----------|-----------|----------|----------------------|
410
| **D-optimal** | det(X'X) | General parameter estimation | Minimizes confidence region volume |
411
| **A-optimal** | tr((X'X)⁻¹) | Parameter precision | Minimizes average parameter variance |
412
| **I-optimal** | ∫var(ŷ(x))dx | Prediction accuracy | Minimizes integrated prediction variance |
413
| **C-optimal** | c'(X'X)⁻¹c | Specific parameter combinations | Minimizes variance of linear combination |
414
| **E-optimal** | λₘᵢₙ(X'X) | Robust estimation | Maximizes minimum eigenvalue |
415
| **G-optimal** | max var(ŷ(x)) | Uniform prediction | Minimizes maximum prediction variance |
416
417
## Algorithm Selection Guide
418

419
| Algorithm | Speed | Quality | Best For |
420
|-----------|-------|---------|----------|
421
| **DETMAX** | Fast | Excellent | D-optimal designs, general use |
422
| **Fedorov** | Medium | Good | Classical approach, well-studied |
423
| **Modified Fedorov** | Medium | Better | Enhanced Fedorov performance |
424
| **Simple Exchange** | Slow | Good | Small problems, educational |
425
| **Sequential** | Fast | Fair | Quick approximations |
426
427
## Usage Patterns
428

429
### Basic Workflow
430
```python
431
import pyDOE3
432

433
# 1. Generate candidate set
434
candidates = pyDOE3.doe_optimal.generate_candidate_set(n_factors=4, n_levels=5)
435

436
# 2. Create optimal design
437
design, info = pyDOE3.doe_optimal.optimal_design(
438
    candidates, n_points=20, degree=2, criterion="D", method="detmax"
439
)
440

441
# 3. Evaluate design quality
442
print(f"D-efficiency: {info['D_eff']:.3f}")
443
print(f"A-efficiency: {info['A_eff']:.3f}")
444
```
445

446
### Comparing Multiple Criteria
447
```python
448
criteria = ["D", "A", "I"]
449
results = {}
450

451
for crit in criteria:
452
    design, info = pyDOE3.doe_optimal.optimal_design(
453
        candidates, n_points=15, degree=2, criterion=crit
454
    )
455
    results[crit] = {"design": design, "info": info}
456
```
457

458
## Types
459

460
```python { .api }
461
import numpy as np
462
from typing import Literal, Tuple, List, Optional
463

464
# Algorithm types
465
OptimalAlgorithm = Literal["sequential", "simple_exchange", "fedorov", "modified_fedorov", "detmax"]
466
OptimalityCriterion = Literal["D", "A", "I", "C", "E", "G", "V", "S", "T"]
467

468
# Design types
469
DesignMatrix = np.ndarray
470
CandidateSet = np.ndarray
471
InformationMatrix = np.ndarray
472
MomentMatrix = np.ndarray
473

474
# Result types
475
DesignInfo = dict
476
FactorBounds = List[Tuple[float, float]]
477
```