process-improve 1.40.2__tar.gz → 1.44.0__tar.gz

{process_improve-1.40.2 → process_improve-1.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: process-improve
-Version: 1.40.2
+Version: 1.44.0
 Summary: Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.
 Keywords: Designed Experiments,Latent Variables,PCA,PLS,Multivariate Data Analysis,Batch data analysis
 Author: Kevin Dunn

{process_improve-1.40.2 → process_improve-1.44.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "process-improve"
-version = "1.40.2"
+version = "1.44.0"
 description = 'Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.'
 readme = "README.md"
 license = "MIT"

{process_improve-1.40.2 → process_improve-1.44.0}/src/process_improve/experiments/__init__.py

@@ -4,7 +4,8 @@ from process_improve.experiments.analysis import analyze_experiment
 from process_improve.experiments.augment import augment_design
 from process_improve.experiments.designs import generate_design
 from process_improve.experiments.designs_factorial import full_factorial
-from process_improve.experiments.evaluate import evaluate_design
+from process_improve.experiments.designs_omars import is_omars, omars_properties
+from process_improve.experiments.evaluate import evaluate_all, evaluate_design
 from process_improve.experiments.factor import Constraint, DesignResult, Factor, Response, ResponseGoal
 from process_improve.experiments.knowledge import doe_knowledge
 from process_improve.experiments.models import Model, lm, predict, summary
@@ -33,13 +34,16 @@ __all__ = [
     "augment_design",
     "c",
     "doe_knowledge",
+    "evaluate_all",
     "evaluate_design",
     "expand_grid",
     "full_factorial",
     "gather",
     "generate_design",
+    "is_omars",
     "lm",
     "main_effects_plot",
+    "omars_properties",
     "optimize_responses",
     "predict",
     "recommend_strategy",

{process_improve-1.40.2 → process_improve-1.44.0}/src/process_improve/experiments/designs.py

@@ -31,6 +31,7 @@ try:
     from pyDOE3 import ff2n
 except ImportError:  # pragma: no cover - exercised via env-without-pyDOE3
     from process_improve._extras import _MissingExtra
+
     ff2n = _MissingExtra("pyDOE3", "expt")  # type: ignore[assignment]
 
 from process_improve.experiments.designs_utils import build_design_result
@@ -92,6 +93,9 @@ def _dispatch_ccd(
         factors,
         center_points=kwargs.get("center_points", 3),
         alpha=kwargs.get("alpha"),
+        cube=kwargs.get("cube", "full"),
+        generators=kwargs.get("generators"),
+        resolution=kwargs.get("resolution"),
     )
 
 
@@ -104,6 +108,15 @@ def _dispatch_dsd(
     return dispatch_dsd(factors)
 
 
+def _dispatch_omars(
+    factors: list[Factor],
+    **kwargs: Any,  # noqa: ANN401
+) -> tuple[np.ndarray, dict]:
+    from process_improve.experiments.designs_omars import dispatch_omars  # noqa: PLC0415
+
+    return dispatch_omars(factors)
+
+
 def _dispatch_d_optimal(
     factors: list[Factor],
     **kwargs: Any,  # noqa: ANN401
@@ -178,6 +191,7 @@ _DESIGN_REGISTRY: dict[str, Callable[..., tuple[np.ndarray, dict]]] = {
     "box_behnken": _dispatch_box_behnken,
     "ccd": _dispatch_ccd,
     "dsd": _dispatch_dsd,
+    "omars": _dispatch_omars,
     "d_optimal": _dispatch_d_optimal,
     "i_optimal": _dispatch_i_optimal,
     "a_optimal": _dispatch_a_optimal,
@@ -255,6 +269,7 @@ def generate_design(  # noqa: PLR0913
     resolution: int | None = None,
     generators: list[str] | None = None,
     alpha: str | float | None = None,
+    cube: str = "full",
     constraints: list[Constraint] | None = None,
     hard_to_change: list[str] | None = None,
     random_seed: int = 42,
@@ -271,8 +286,8 @@ def generate_design(  # noqa: PLR0913
     design_type : str or None
         One of ``"full_factorial"``, ``"fractional_factorial"``,
         ``"plackett_burman"``, ``"box_behnken"``, ``"ccd"``, ``"dsd"``,
-        ``"d_optimal"``, ``"i_optimal"``, ``"a_optimal"``, ``"mixture"``,
-        ``"taguchi"``.
+        ``"omars"``, ``"d_optimal"``, ``"i_optimal"``, ``"a_optimal"``,
+        ``"mixture"``, ``"taguchi"``.
         If ``None``, the design type is chosen automatically based on the
         factor count, budget, and constraints.
     budget : int or None
@@ -293,6 +308,13 @@ def generate_design(  # noqa: PLR0913
     alpha : str, float, or None
         Axial distance for CCD designs: ``"rotatable"``,
         ``"face_centered"``, ``"orthogonal"``, or a numeric value.
+    cube : str
+        For CCD designs, how to build the cube (factorial) portion:
+        ``"full"`` (default) uses the complete 2^k factorial; ``"fractional"``
+        uses a resolution-V (or higher) fractional factorial, keeping the run
+        count practical for k >= 5.  When ``"fractional"`` and *generators* is
+        given, those generators define the cube; otherwise a minimum-aberration
+        half-fraction is chosen automatically.
     constraints : list[Constraint] or None
         Constraints on the factor space.
     hard_to_change : list[str] or None
@@ -331,10 +353,7 @@ def generate_design(  # noqa: PLR0913
         design_type = _auto_select(factors, budget, constraints, hard_to_change)
 
     if design_type not in _DESIGN_REGISTRY:
-        raise ValueError(
-            f"Unknown design_type={design_type!r}.  "
-            f"Choose from: {', '.join(sorted(_DESIGN_REGISTRY))}."
-        )
+        raise ValueError(f"Unknown design_type={design_type!r}.  Choose from: {', '.join(sorted(_DESIGN_REGISTRY))}.")
 
     # --- Dispatch ----------------------------------------------------------
     dispatch_fn = _DESIGN_REGISTRY[design_type]
@@ -346,6 +365,7 @@ def generate_design(  # noqa: PLR0913
         "resolution": resolution,
         "generators": generators,
         "alpha": alpha,
+        "cube": cube,
         "hard_to_change": hard_to_change,
         "constraints": constraints,
     }
@@ -355,7 +375,16 @@ def generate_design(  # noqa: PLR0913
     # --- Determine center-point handling -----------------------------------
     # Designs that embed their own center points (CCD, Box-Behnken)
     # already include them; don't add more.
-    designs_with_embedded_centers = {"ccd", "box_behnken", "dsd", "mixture", "d_optimal", "i_optimal", "a_optimal"}
+    designs_with_embedded_centers = {
+        "ccd",
+        "box_behnken",
+        "dsd",
+        "omars",
+        "mixture",
+        "d_optimal",
+        "i_optimal",
+        "a_optimal",
+    }
 
     # Optimal designs from pyoptex produce a pre-optimized run order
     # (especially important for split-plot).  Skip randomization for these.

process_improve-1.44.0/src/process_improve/experiments/designs_omars.py

@@ -0,0 +1,274 @@
+# (c) Kevin Dunn, 2010-2026. MIT License.
+
+"""OMARS (Orthogonal Minimally Aliased Response Surface) designs.
+
+OMARS designs are three-level designs (coded ``-1 / 0 / +1``) in which every
+main effect is orthogonal to every other main effect **and** to all
+second-order terms (the pure quadratics and the two-factor interactions),
+confining all aliasing to the second-order block.  They occupy the middle
+ground between screening designs and full response-surface designs.
+
+This module provides two things:
+
+* :func:`dispatch_omars` - a constructive generator wired into
+  :func:`process_improve.experiments.generate_design` as
+  ``design_type="omars"``.  It builds the conference-matrix foldover family of
+  OMARS designs; the definitive screening design (DSD) is the minimal member
+  of that family, so the construction is shared with
+  :func:`process_improve.experiments.designs_response_surface.dispatch_dsd`.
+* :func:`omars_properties` and :func:`is_omars` - dependency-free verifiers
+  that check the defining OMARS properties on *any* coded design matrix.  Use
+  them to validate designs we generate, designs produced by a future
+  enumerator, or designs supplied from an external source.
+
+A public catalogue of enumerated OMARS designs exists, but it is unlicensed
+and is therefore **not** redistributed with this package.  The verifiers here
+let a user cross-check a generated design against such a catalogue offline.
+
+References
+----------
+.. [1] Núñez Ares, J. and Goos, P. (2020).  "Enumeration and multicriteria
+   selection of orthogonal minimally aliased response surface designs."
+   *Technometrics*, 62(1):21-36.
+.. [2] Jones, B. and Nachtsheim, C. J. (2011).  "A class of three-level
+   designs for definitive screening in the presence of second-order
+   effects."  *Journal of Quality Technology*, 43(1):1-15.
+"""
+
+from __future__ import annotations
+
+import itertools
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from process_improve.experiments.factor import Factor
+
+# Default numerical tolerance for treating an inner product as zero.  The
+# constructive designs are integer-valued so exact-zero comparisons would also
+# work, but a small tolerance keeps the verifiers usable on floating-point or
+# slightly perturbed matrices.
+_DEFAULT_TOL = 1e-9
+
+
+def _second_order_terms(matrix: np.ndarray) -> tuple[np.ndarray, list[str]]:
+    """Build the second-order model terms (quadratics + two-factor interactions).
+
+    Parameters
+    ----------
+    matrix : np.ndarray
+        Coded design matrix of shape ``(n_runs, n_factors)``.
+
+    Returns
+    -------
+    tuple[np.ndarray, list[str]]
+        An ``(n_runs, n_terms)`` array whose columns are the ``k`` pure
+        quadratics ``x_i^2`` followed by the ``k (k - 1) / 2`` two-factor
+        interactions ``x_i x_j``, and a matching list of human-readable term
+        names.
+    """
+    n_factors = matrix.shape[1]
+    columns: list[np.ndarray] = []
+    names: list[str] = []
+    for i in range(n_factors):
+        columns.append(matrix[:, i] * matrix[:, i])
+        names.append(f"x{i + 1}^2")
+    for i, j in itertools.combinations(range(n_factors), 2):
+        columns.append(matrix[:, i] * matrix[:, j])
+        names.append(f"x{i + 1}*x{j + 1}")
+    if not columns:  # defensive: a zero-factor matrix has no second-order terms
+        return np.empty((matrix.shape[0], 0)), names
+    return np.column_stack(columns), names
+
+
+def _max_abs_correlation(terms: np.ndarray) -> float:
+    """Return the largest absolute pairwise correlation among the columns of *terms*.
+
+    Constant columns (zero variance) are skipped.  Returns ``0.0`` when fewer
+    than two non-constant columns are present.
+    """
+    if terms.shape[1] < 2:
+        return 0.0
+    centered = terms - terms.mean(axis=0, keepdims=True)
+    norms = np.linalg.norm(centered, axis=0)
+    keep = norms > 0
+    if keep.sum() < 2:
+        return 0.0
+    unit = centered[:, keep] / norms[keep]
+    corr = unit.T @ unit
+    off_diagonal = corr - np.diag(np.diag(corr))
+    return float(np.abs(off_diagonal).max())
+
+
+def omars_properties(matrix: np.ndarray, *, tol: float = _DEFAULT_TOL) -> dict:
+    """Compute the OMARS-defining properties of a coded design matrix.
+
+    The three properties that define an OMARS design are:
+
+    1. **Three levels** - every entry is one of ``-1``, ``0`` or ``+1``.
+    2. **Orthogonal main effects** - the main-effect columns are mutually
+       orthogonal and balanced (each column sums to zero).
+    3. **Minimally aliased** - every main effect is orthogonal to every
+       second-order term (all quadratics and all two-factor interactions);
+       aliasing is confined to the second-order block.
+
+    Parameters
+    ----------
+    matrix : np.ndarray
+        Coded design matrix of shape ``(n_runs, n_factors)``.
+    tol : float
+        Absolute tolerance below which an inner product is treated as zero.
+
+    Returns
+    -------
+    dict
+        A report with the keys ``n_runs``, ``n_factors``, ``levels``,
+        ``is_three_level``, ``quadratics_estimable``, ``is_balanced``,
+        ``main_effects_orthogonal``, ``main_effects_clear_of_second_order``,
+        ``max_main_effect_inner_product``,
+        ``max_main_vs_second_order_inner_product``,
+        ``max_second_order_correlation`` and ``is_omars``.
+
+    Notes
+    -----
+    ``quadratics_estimable`` is ``True`` only when every factor takes the
+    middle (``0``) level at least once.  A two-level design (e.g. a full
+    factorial) would otherwise pass the orthogonality checks but has constant,
+    inestimable quadratic terms, so it is not an OMARS design.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # The minimal 3-factor OMARS / DSD (conference-matrix foldover).
+    >>> from process_improve.experiments.factor import Factor
+    >>> from process_improve.experiments.designs_omars import dispatch_omars
+    >>> coded, _ = dispatch_omars([Factor(name=n, low=-1, high=1) for n in "ABC"])
+    >>> omars_properties(coded)["is_omars"]
+    True
+    """
+    matrix = np.asarray(matrix, dtype=float)
+    n_runs, n_factors = matrix.shape
+
+    levels = sorted({round(float(v), 9) for v in np.unique(matrix)})
+
+    # Three-level validity: every entry is within tol of one of {-1, 0, +1}.
+    nearest = np.round(matrix)
+    is_three_level = bool(
+        np.all(np.abs(matrix - nearest) <= tol) and np.all(np.isin(nearest, (-1.0, 0.0, 1.0)))
+    )
+
+    # OMARS factors are genuinely three-level: each must take the middle (0)
+    # level at least once, otherwise its pure quadratic is a constant column
+    # and cannot be estimated (as in a two-level factorial).
+    uses_middle_level = np.any(np.abs(matrix) <= tol, axis=0)
+    quadratics_estimable = bool(np.all(uses_middle_level))
+
+    column_sums = np.abs(matrix.sum(axis=0))
+    is_balanced = bool(np.all(column_sums <= tol))
+
+    # Main-effect orthogonality: off-diagonal of X'X.
+    gram = matrix.T @ matrix
+    me_off_diagonal = gram - np.diag(np.diag(gram))
+    max_me_inner = float(np.abs(me_off_diagonal).max()) if n_factors > 1 else 0.0
+    main_effects_orthogonal = max_me_inner <= tol
+
+    # Main effects clear of all second-order terms.
+    second_order, _ = _second_order_terms(matrix)
+    if second_order.shape[1] > 0:
+        cross = matrix.T @ second_order
+        max_me_vs_so = float(np.abs(cross).max())
+    else:  # defensive: a zero-factor matrix has no second-order terms
+        max_me_vs_so = 0.0
+    main_effects_clear = max_me_vs_so <= tol
+
+    max_so_corr = _max_abs_correlation(second_order)
+
+    is_omars = bool(
+        is_three_level
+        and quadratics_estimable
+        and is_balanced
+        and main_effects_orthogonal
+        and main_effects_clear
+    )
+
+    return {
+        "n_runs": int(n_runs),
+        "n_factors": int(n_factors),
+        "levels": levels,
+        "is_three_level": is_three_level,
+        "quadratics_estimable": quadratics_estimable,
+        "is_balanced": is_balanced,
+        "main_effects_orthogonal": main_effects_orthogonal,
+        "main_effects_clear_of_second_order": main_effects_clear,
+        "max_main_effect_inner_product": max_me_inner,
+        "max_main_vs_second_order_inner_product": max_me_vs_so,
+        "max_second_order_correlation": max_so_corr,
+        "is_omars": is_omars,
+    }
+
+
+def is_omars(matrix: np.ndarray, *, tol: float = _DEFAULT_TOL) -> bool:
+    """Return ``True`` iff *matrix* satisfies the OMARS-defining properties.
+
+    Convenience wrapper around :func:`omars_properties`.
+
+    Parameters
+    ----------
+    matrix : np.ndarray
+        Coded design matrix of shape ``(n_runs, n_factors)``.
+    tol : float
+        Absolute tolerance below which an inner product is treated as zero.
+
+    Returns
+    -------
+    bool
+        ``True`` if the design is three-level with orthogonal main effects
+        that are clear of all second-order terms.
+    """
+    return omars_properties(matrix, tol=tol)["is_omars"]
+
+
+def dispatch_omars(factors: list[Factor], *, verify: bool = True) -> tuple[np.ndarray, dict]:
+    """Generate an OMARS design via the conference-matrix foldover construction.
+
+    The construction is shared with :func:`dispatch_dsd`: for ``k`` factors it
+    folds a conference matrix ``C`` of order ``m`` over its negative and adds a
+    center run, giving ``[C; -C; 0]``.  ``m = k`` for even ``k`` (``2k + 1``
+    runs) and ``m = k + 1`` with the last column dropped for odd ``k``
+    (``2k + 3`` runs).  This yields the minimal OMARS design for ``k`` factors;
+    a future enumerator will expand coverage to the larger, non-foldover
+    members of the OMARS family.
+
+    Parameters
+    ----------
+    factors : list[Factor]
+        Continuous factors (at least three).
+    verify : bool
+        When ``True`` (default) the generated matrix is checked with
+        :func:`is_omars` and the result is recorded in the metadata under
+        ``"omars_verified"``.  The check is cheap and guards against the
+        degraded orthogonality of the cyclic conference-matrix fallback.
+
+    Returns
+    -------
+    tuple[np.ndarray, dict]
+        The coded design matrix and metadata.  Metadata includes
+        ``"construction"`` (the conference-matrix construction used),
+        ``"family"`` and, when *verify* is ``True``, ``"omars_verified"``.
+
+    Raises
+    ------
+    ValueError
+        If fewer than three factors are supplied.
+    """
+    from process_improve.experiments.designs_response_surface import dispatch_dsd  # noqa: PLC0415
+
+    if len(factors) < 3:
+        raise ValueError("OMARS designs require at least 3 factors.")
+
+    coded_matrix, dsd_meta = dispatch_dsd(factors)
+    meta = {**dsd_meta, "family": "conference_foldover"}
+    if verify:
+        meta["omars_verified"] = is_omars(coded_matrix)
+    return coded_matrix, meta

{process_improve-1.40.2 → process_improve-1.44.0}/src/process_improve/experiments/designs_response_surface.py

@@ -17,6 +17,7 @@ try:
     from pyDOE3 import bbdesign, ccdesign
 except ImportError:  # pragma: no cover - exercised via env-without-pyDOE3
     from process_improve._extras import _MissingExtra
+
     bbdesign = _MissingExtra("pyDOE3", "expt")  # type: ignore[assignment]
     ccdesign = _MissingExtra("pyDOE3", "expt")  # type: ignore[assignment]
 
@@ -26,10 +27,13 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-def dispatch_ccd(
+def dispatch_ccd(  # noqa: PLR0913
     factors: list[Factor],
     center_points: int = 3,
     alpha: str | float | None = None,
+    cube: str = "full",
+    generators: list[str] | None = None,
+    resolution: int | None = None,
 ) -> tuple[np.ndarray, dict]:
     """Generate a Central Composite Design (CCD).
 
@@ -43,6 +47,18 @@ def dispatch_ccd(
         Axial distance.  Accepted string values: ``"rotatable"``,
         ``"face_centered"``, ``"orthogonal"``.  A numeric value sets
         alpha directly.  Defaults to ``"orthogonal"``.
+    cube : str
+        How to build the cube (factorial) portion: ``"full"`` (default) uses
+        the complete 2^k factorial; ``"fractional"`` uses a resolution-V (or
+        higher) fractional factorial, keeping the run count practical for
+        k >= 5.
+    generators : list[str] or None
+        Explicit cube generators (e.g. ``["E=ABCD"]``), used only when
+        ``cube="fractional"``.  When omitted, a minimum-aberration
+        half-fraction is chosen automatically.
+    resolution : int or None
+        Desired minimum cube resolution, used only when ``cube="fractional"``
+        and *generators* is not given.
 
     Returns
     -------
@@ -55,6 +71,11 @@ def dispatch_ccd(
     ``center`` parameter).  The caller should set ``center_points=0`` in
     ``build_design_result`` to avoid adding duplicate center points.
     """
+    if cube == "fractional":
+        return _dispatch_ccd_fractional(factors, center_points, alpha, generators, resolution)
+    if cube != "full":
+        raise ValueError(f"cube must be 'full' or 'fractional', got {cube!r}.")
+
     k = len(factors)
 
     # Map alpha string to pyDOE3 face and alpha parameters.
@@ -97,6 +118,148 @@ def dispatch_ccd(
     return coded_matrix, {"alpha_value": alpha_value, "face": face}
 
 
+def _resolve_fractional_axial_distance(
+    alpha: str | float | None,
+    n_cube_runs: int,
+    k: int,
+    center_points: int,
+) -> tuple[float, str]:
+    """Axial (star-point) distance for a fractional-cube CCD.
+
+    Mirrors pyDOE3's :func:`star` formulas, but uses the actual number of
+    fractional cube runs *n_cube_runs* in place of the full ``2**k``.
+
+    Parameters
+    ----------
+    alpha : str, float, or None
+        ``"face_centered"`` (alpha = 1), ``"rotatable"``
+        (alpha = n_cube_runs ** 0.25), ``"orthogonal"`` / None (the orthogonal
+        formula), or a numeric value used directly.
+    n_cube_runs : int
+        Number of runs in the (fractional) cube portion.
+    k : int
+        Number of factors.
+    center_points : int
+        Total number of center points; split between the cube and axial blocks
+        for the orthogonal-alpha formula.
+
+    Returns
+    -------
+    tuple[float, str]
+        The axial distance and a short label for the design metadata.
+    """
+    if isinstance(alpha, (int, float)) and not isinstance(alpha, bool):
+        return float(alpha), "user"
+
+    alpha_lower = alpha.lower() if isinstance(alpha, str) else None
+    if alpha_lower in ("face_centered", "face centered", "ccf", "faced"):
+        return 1.0, "faced"
+    if alpha_lower in ("rotatable", "r"):
+        return float(n_cube_runs**0.25), "rotatable"
+    if alpha_lower in ("inscribed", "cci"):
+        raise ValueError(
+            "alpha='inscribed' is not supported with cube='fractional'; "
+            "use 'face_centered', 'rotatable', 'orthogonal', or a numeric alpha."
+        )
+
+    # "orthogonal", None, or any other string: orthogonal axial distance.
+    n_center_cube = center_points // 2
+    n_center_axial = center_points - n_center_cube
+    n_axial = 2 * k
+    a = (k * (1 + n_center_axial / n_axial) / (1 + n_center_cube / n_cube_runs)) ** 0.5
+    return float(a), "orthogonal"
+
+
+def _dispatch_ccd_fractional(
+    factors: list[Factor],
+    center_points: int,
+    alpha: str | float | None,
+    generators: list[str] | None,
+    resolution: int | None,
+) -> tuple[np.ndarray, dict]:
+    """Build a CCD whose cube portion is a resolution-V fractional factorial.
+
+    The cube is generated by reusing
+    :func:`process_improve.experiments.designs_screening.dispatch_fractional_factorial`,
+    then the axial (star) runs and the center runs are stacked on top.
+
+    Parameters
+    ----------
+    factors : list[Factor]
+        Continuous factors (at least 3).
+    center_points : int
+        Total number of center runs (added once, not split).
+    alpha : str, float, or None
+        Axial distance specification; see
+        :func:`_resolve_fractional_axial_distance`.
+    generators : list[str] or None
+        Explicit cube generators.  When omitted, a minimum-aberration
+        half-fraction (last factor = product of all the others) is used.
+    resolution : int or None
+        Desired minimum cube resolution; used only when *generators* is None.
+
+    Returns
+    -------
+    tuple[np.ndarray, dict]
+        Coded design matrix and metadata, including ``alpha_value``,
+        ``generators_used``, ``defining_relation``, and ``resolution``.
+    """
+    from process_improve.experiments.designs_screening import dispatch_fractional_factorial  # noqa: PLC0415
+    from process_improve.experiments.evaluate import (  # noqa: PLC0415
+        _defining_relation_from_generators,
+        _word_to_str,
+    )
+
+    k = len(factors)
+    if k < 3:
+        raise ValueError("A fractional-cube CCD requires at least 3 factors; use cube='full' for fewer.")
+
+    factor_names = [f.name for f in factors]
+
+    if generators is None and resolution is None:
+        # Minimum-aberration half-fraction: last factor = product of all the others.
+        generators = [f"{factor_names[-1]}={''.join(factor_names[:-1])}"]
+
+    cube, frac_meta = dispatch_fractional_factorial(factors, resolution=resolution, generators=generators)
+    n_cube_runs = cube.shape[0]
+
+    # Record the cube's generators, defining relation, and (true) resolution.
+    used_generators = frac_meta.get("generators_used") or generators
+    res = frac_meta.get("resolution")
+    defining_relation: list[str] | None = None
+    if used_generators:
+        words = _defining_relation_from_generators(used_generators, factor_names)
+        defining_relation = [f"I={_word_to_str(w, factor_names)}" for w in words]
+        if words:
+            res = min(len(w) for w in words)
+
+    if res is not None and res < 5:
+        raise ValueError(
+            f"The fractional cube has resolution {res}, but a CCD needs resolution V or higher so the "
+            "full quadratic model is estimable. Supply resolution-V generators or use cube='full'."
+        )
+
+    axial_distance, face = _resolve_fractional_axial_distance(alpha, n_cube_runs, k, center_points)
+
+    # Axial (star) runs: 2k rows at +/- axial_distance, zeros elsewhere.
+    star = np.zeros((2 * k, k))
+    for i in range(k):
+        star[2 * i : 2 * i + 2, i] = (-axial_distance, axial_distance)
+
+    center = np.zeros((max(0, center_points), k))
+
+    coded_matrix = np.vstack([cube, star, center])
+    meta = {
+        "alpha_value": axial_distance,
+        "face": face,
+        "cube": "fractional",
+        "generators_used": used_generators,
+        "defining_relation": defining_relation,
+        "resolution": res,
+    }
+    return coded_matrix, meta
+
+
 def dispatch_box_behnken(
     factors: list[Factor],
     center_points: int = 3,