central_composite_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)

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.