utils#

Functions

`central_composite_DOE`(d[, alpha, n_CP, ...])	Creates a classical Central Composite Design (CCD) for response surface methodology (RSM).
`factorial_DOE`(d[, n_CP, shuffle, seed, full])	Creates a statistically designed factorial experiment (DOE).
`factorial_DOE_n_level`(d[, levels, n_CP, ...])	Creates a statistically designed factorial experiment (DOE).

obsidian.experiment.utils.central_composite_DOE(d: int, alpha: float | str = 'rotatable', n_CP: int | None = None, face_core_full: bool = True, inscribe: bool = True, shuffle: bool = True, seed: Generator | int | None = None)[source]#

Creates a classical Central Composite Design (CCD) for response surface methodology (RSM).

A CCD combines a two-level factorial (or fractional-factorial) core to estimate main effects and two-factor interactions, axial (“star”) points to estimate quadratic curvature, and replicated center points to estimate pure error. It is the standard “old school” design for fitting a full second-order (quadratic) response surface.

Because obsidian generates designs in the (0,1) unit cube (which is then mapped onto the real parameter bounds), the design is by default inscribed (inscribe=True): when the axial distance exceeds the cube (alpha > 1), the whole design is scaled by 1/alpha so the axial points sit on the cube faces and the factorial core is pulled inward, guaranteeing every point falls within the parameter bounds (at the cost of running the core at a fraction of the full range). When alpha <= 1 (e.g. 'faced') the design already fits inside the cube, so no scaling is applied. Set inscribe=False to instead keep the factorial core at the box corners and clip axials to the bounds, which breaks rotatability – equivalent to a face-centered design.

Parameters:

d (int) – Number of dimensions/inputs in the design.
alpha (float | str, optional) –
Axial distance in coded (-1, 1) units. Either a positive float, or one of: - 'rotatable' (default): alpha = n_factorial ** 0.25, giving a

rotatable design (constant prediction variance at fixed distance from center).
- 'faced': alpha = 1 (face-centered, “CCF”); axials lie on the cube faces and only three levels per factor are used.
n_CP (int | None, optional) – Number of center points. If None (default), uses standard uniform-precision values (e.g. 5/6/7 for d=2/3/4), falling back to 3.
face_core_full (bool, optional) – Whether the factorial core is a full 2**d design (default) or an efficient Resolution IV+ fractional factorial. Full cores are recommended for RSM (Resolution V+) but grow quickly with d.
inscribe (bool, optional) – Whether to inscribe the design in the unit cube so all points respect the parameter bounds. Default is True.
shuffle (bool, optional) – Whether to shuffle the run order. Default is True.
seed (Generator | int | None, optional) – Controls the run-order shuffle. A Generator is used directly; an int seeds an isolated default_rng (reproducible, without touching global RNG state); None (default) defers to the ambient global np.random stream (e.g. one set by with_tmp_seed). Global state is never reseeded.

Returns:

An (m)-by-(d) array of experiments in the (0,1) domain.

Return type:

ndarray

Raises:

UnsupportedError – If the number of dimensions exceeds 12.
ValueError – If d < 1, n_CP < 0, or alpha is an unrecognized string or a non-positive value.

obsidian.experiment.utils.factorial_DOE(d: int, n_CP: int = 3, shuffle: bool = True, seed: Generator | int | None = None, full: bool = False)[source]#

Creates a statistically designed factorial experiment (DOE). Specifically for 2-level designs only. Uses the range (0,1) for low-high instead of the typical (-1,1), although (-1,1) is used for calculations during alias design.

For n-level designs (3-level, 4-level, etc.), use factorial_DOE_n_level.

Parameters:

d (int) – Number of dimensions/inputs in the design.
n_CP (int, optional) – The number of centerpoints to include in the design, for estimating uncertainty and curvature. Default is 3.
shuffle (bool, optional) – Whether or not to shuffle the design or leave them in the default run order. Default is True.
seed (Generator | int | None, optional) – Controls the run-order shuffle. A Generator is used directly; an int seeds an isolated default_rng (reproducible, without touching global RNG state); None (default) defers to the ambient global np.random stream (e.g. one set by with_tmp_seed). Global state is never reseeded.
full (bool, optional) – Whether or not to run the full DOE. Default is False, which will lead to an efficient Res4+ design.

Returns:

An (m)-by-(d) array of experiments in the (0,1) domain

Return type:

ndarray

Raises:

UnsupportedError – If the number of dimensions exceeds 12
ValueError – If d < 1 or n_CP < 0

obsidian.experiment.utils.factorial_DOE_n_level(d: int, levels: int = 2, n_CP: int | None = None, shuffle: bool = True, seed: Generator | int | None = None, full: bool = False)[source]#

Creates a statistically designed factorial experiment (DOE). Supports n-level designs (2-level, 3-level, etc.). Uses the range (0,1) for low-high.

Parameters:

d (int) – Number of dimensions/inputs in the design.
levels (int, optional) – Number of levels per factor (e.g., 2, 3, 4). Default is 2.
n_CP (int | None, optional) – Number of replicate centerpoints, for estimating pure error and testing curvature/lack-of-fit. Default (None) is 3 for all levels, since replication is what provides pure-error degrees of freedom. Use n_CP=0 for a deterministic, noise-free grid comparison.
shuffle (bool, optional) – Whether or not to shuffle the design or leave them in the default run order. Default is True.
seed (Generator | int | None, optional) – Controls the run-order shuffle. A Generator is used directly; an int seeds an isolated default_rng (reproducible, without touching global RNG state); None (default) defers to the ambient global np.random stream (e.g. one set by with_tmp_seed). Global state is never reseeded.
full (bool, optional) – Whether or not to run the full DOE. Default is False, which will lead to an efficient Res4+ design (2-level only).

Returns:

An (m)-by-(d) array of experiments in the (0,1) domain

Return type:

ndarray

Raises:

UnsupportedError – If the number of dimensions exceeds 12
ValueError – If d < 1, levels < 2, n_CP < 0, or a fractional factorial is requested with levels != 2