0
# pyDOE3
1

2
A comprehensive Design of Experiments (DOE) library for Python that enables scientists, engineers, and statisticians to construct appropriate experimental designs for research and optimization. pyDOE3 provides a wide range of classical and modern experimental design methods with mathematical rigor and computational efficiency.
3

4
## Package Information
5

6
- **Package Name**: pyDOE3
7
- **Language**: Python
8
- **Installation**: `pip install pyDOE3`
9
- **Dependencies**: numpy, scipy
10
- **Documentation**: https://pydoe3.readthedocs.io
11

12
## Core Imports
13

14
```python
15
import pyDOE3
16
```
17

18
Common for specific design types:
19

20
```python
21
from pyDOE3 import bbdesign, ccdesign, fullfact, ff2n, fracfact, lhs, taguchi_design
22
```
23

24
Import optimal design functionality:
25

26
```python
27
from pyDOE3.doe_optimal import optimal_design, d_optimality, fedorov
28
```
29

30
## Basic Usage
31

32
```python
33
import pyDOE3
34
import numpy as np
35

36
# Create a 2-level full factorial design for 3 factors
37
factorial_design = pyDOE3.ff2n(3)
38
print("2^3 Factorial Design:")
39
print(factorial_design)
40

41
# Create a Latin Hypercube Sample with 10 points in 4 dimensions
42
lhs_design = pyDOE3.lhs(4, samples=10)
43
print("\nLatin Hypercube Sample:")
44
print(lhs_design)
45

46
# Create a Box-Behnken design for 3 factors
47
bb_design = pyDOE3.bbdesign(3)
48
print("\nBox-Behnken Design:")
49
print(bb_design)
50

51
# Create a Central Composite Design for 2 factors
52
cc_design = pyDOE3.ccdesign(2)
53
print("\nCentral Composite Design:")
54
print(cc_design)
55
```
56

57
## Architecture
58

59
pyDOE3 is organized into several functional areas:
60

61
- **Classical Designs**: Traditional factorial and screening designs with established statistical properties
62
- **Response Surface Methodology**: Designs optimized for fitting polynomial models and process optimization
63
- **Sampling Designs**: Space-filling and randomized approaches for computer experiments
64
- **Robust Design**: Taguchi methods with orthogonal arrays for quality engineering
65
- **Optimal Designs**: Advanced algorithms with multiple optimality criteria for customized experimental plans
66
- **Utilities**: Statistical analysis and design manipulation tools
67

68
## Capabilities
69

70
### Classical Factorial Designs
71

72
Traditional experimental designs including full factorial, fractional factorial, and screening designs. These form the foundation of experimental design methodology and are suitable for factor screening and main effects analysis.
73

74
```python { .api }
75
def fullfact(levels): ...
76
def ff2n(n): ...
77
def fracfact(gen): ...
78
def fracfact_by_res(n, res): ...
79
def fracfact_opt(n_factors: int, n_erased: int, max_attempts: int = 0) -> str: ...
80
def fracfact_aliasing(design: np.ndarray) -> dict: ...
81
def alias_vector_indices(n_factors: int) -> List[int]: ...
82
def pbdesign(n): ...
83
def gsd(levels, reduction, n=1): ...
84
```
85

86
[Classical Factorial Designs](./classical-factorial.md)
87

88
### Response Surface Methodology (RSM)
89

90
Designs optimized for fitting response surface models and process optimization. These designs efficiently estimate quadratic effects and interaction terms for modeling and optimization applications.
91

92
```python { .api }
93
def bbdesign(n, center=None): ...
94
def ccdesign(n, center=(4, 4), alpha="orthogonal", face="circumscribed"): ...
95
def doehlert_shell_design(num_factors, num_center_points=1): ...
96
def doehlert_simplex_design(num_factors): ...
97
```
98

99
[Response Surface Methodology](./response-surface.md)
100

101
### Sampling & Randomized Designs
102

103
Space-filling and randomized experimental designs for computer experiments, Monte Carlo simulation, and uncertainty quantification. These designs provide uniform coverage of the experimental space.
104

105
```python { .api }
106
def lhs(n: int, samples: int = None, criterion: str = None, iterations: int = None, random_state: Union[int, np.random.RandomState] = None, correlation_matrix: np.ndarray = None) -> np.ndarray: ...
107
def sukharev_grid(num_points: int, dimension: int) -> np.ndarray: ...
108
def fold(H: np.ndarray, columns: List[int] = None) -> np.ndarray: ...
109
```
110

111
[Sampling & Randomized Designs](./sampling-randomized.md)
112

113
### Taguchi & Robust Design
114

115
Taguchi methodology for robust parameter design with orthogonal arrays and signal-to-noise ratio analysis. These methods focus on minimizing variability and improving product/process robustness.
116

117
```python { .api }
118
def taguchi_design(oa_name: str, levels_per_factor: List[List[int]]) -> np.ndarray: ...
119
class TaguchiObjective(Enum): ...
120
def compute_snr(responses: np.ndarray, objective: TaguchiObjective = TaguchiObjective.LARGER_IS_BETTER) -> np.ndarray: ...
121
def list_orthogonal_arrays() -> List[str]: ...
122
def get_orthogonal_array(oa_name: str) -> np.ndarray: ...
123
```
124

125
[Taguchi & Robust Design](./taguchi-robust.md)
126

127
### Optimal Experimental Design
128

129
Advanced experimental design algorithms with multiple optimality criteria for creating customized experimental plans. These methods provide maximum statistical efficiency for specific modeling objectives. **Note: These functions are available through the `pyDOE3.doe_optimal` submodule.**
130

131
```python { .api }
132
# Available through pyDOE3.doe_optimal submodule
133
from pyDOE3.doe_optimal import optimal_design, d_optimality, a_optimality, fedorov, detmax
134

135
def optimal_design(candidates: np.ndarray, n_points: int, degree: int, criterion: Literal["D", "A", "I"] = "D", method: Literal["sequential", "simple_exchange", "fedorov", "modified_fedorov", "detmax"] = "detmax", alpha: float = 0.0, max_iter: int = 200) -> Tuple[np.ndarray, dict]: ...
136
def d_optimality(M: np.ndarray) -> float: ...
137
def a_optimality(M: np.ndarray) -> float: ...
138
def fedorov(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray: ...
139
def detmax(candidates: np.ndarray, n_points: int, degree: int, criterion: str = "D", alpha: float = 0.0, max_iter: int = 200) -> np.ndarray: ...
140
```
141

142
[Optimal Experimental Design](./optimal-design.md)
143

144
### Utilities & Advanced Functions
145

146
Statistical analysis tools and advanced design manipulation functions for evaluating and modifying experimental designs.
147

148
```python { .api }
149
def var_regression_matrix(H: np.ndarray, x: np.ndarray, model: str, sigma: float = 1) -> np.ndarray: ...
150
```
151

152
[Utilities & Advanced Functions](./utilities-advanced.md)
153

154
## Common Design Types Supported
155

156
1. **Screening Designs**: Full factorial, fractional factorial, Plackett-Burman, generalized subset designs
157
2. **Response Surface Designs**: Box-Behnken, central composite, Doehlert designs
158
3. **Space-Filling Designs**: Latin hypercube sampling, low-discrepancy sequences
159
4. **Robust Designs**: Taguchi designs with orthogonal arrays
160
5. **Computer Experiment Designs**: Optimal designs with various criteria
161
6. **Sequential Designs**: Design augmentation and folding capabilities
162

163
## Design Selection Guide
164

165
- **Factor Screening** (many factors, identify important ones): Use fractional factorial or Plackett-Burman designs
166
- **Response Surface Modeling** (few factors, fit polynomial models): Use Box-Behnken or central composite designs  
167
- **Computer Experiments** (deterministic simulations): Use Latin hypercube sampling or optimal designs
168
- **Robust Design** (minimize variability): Use Taguchi designs with orthogonal arrays
169
- **Custom Requirements** (specific statistical criteria): Use optimal design algorithms
170

171
## Types
172

173
```python { .api }
174
from enum import Enum
175
from typing import List, Optional, Union, Tuple, Literal
176
import numpy as np
177

178
class TaguchiObjective(Enum):
179
    LARGER_IS_BETTER = "larger_is_better"
180
    SMALLER_IS_BETTER = "smaller_is_better" 
181
    NOMINAL_IS_BEST = "nominal_is_best"
182

183
# Common type aliases used throughout the library
184
DesignMatrix = np.ndarray
185
LevelSpec = Union[int, List[int]]
186
GeneratorString = str
187
OptimalityCriterion = str
188
```