discopt-doe 0.2.0__py3-none-any.whl

discopt/doe/__init__.py

@@ -0,0 +1,282 @@
+"""discopt.doe -- Design of Experiments.
+
+This package has three complementary entry points, each tailored to
+a different question:
+
+1. **"What is the best operating condition?"**
+   :func:`optimize_round` runs one active-learning round: fit a
+   surrogate to the experiments completed so far, recommend the
+   next batch via an acquisition function (expected improvement,
+   UCB, steepest ascent), append the batch to a workbook for
+   execution. See the ``active-learning`` tutorial notebook.
+
+2. **"Does this factor matter?"**
+   :func:`factorial_2level_design` builds 2-level full factorial
+   screening designs; :func:`effects_estimates` gives signed
+   main-effect estimates; :func:`anova_report` produces the
+   F-table.
+
+3. **"How precisely can I estimate the model parameters?"**
+   :func:`optimal_experiment` and :func:`batch_optimal_experiment`
+   solve for an exact D/A/E-optimal design using the Fisher
+   Information Matrix computed with JAX autodiff;
+   :func:`diagnose_identifiability` and
+   :func:`estimability_rank` warn when the chosen experiments
+   cannot identify the parameters.
+
+Quick start (FIM-based parameter-estimation design)
+---------------------------------------------------
+>>> from discopt.doe import compute_fim, optimal_experiment, DesignCriterion
+>>> fim_result = compute_fim(experiment, param_values, design_values)
+>>> design = optimal_experiment(experiment, param_values, design_bounds)
+>>> print(design.summary())
+
+Quick start (active-learning optimization)
+------------------------------------------
+>>> from discopt.doe import optimize_round, OptimizationCriterion
+>>> result = optimize_round(
+...     workbook="opt.xlsx",
+...     criterion=OptimizationCriterion.MAXIMIZE,
+...     surrogate="gp",                       # or sklearn estimator, or Surrogate
+...     acquisition="expected_improvement",
+...     batch_size=4,
+... )
+>>> print(result.next_designs)
+
+Identifiability and estimability diagnostics
+--------------------------------------------
+>>> from discopt.doe import diagnose_identifiability, estimability_rank, profile_likelihood
+>>> diag = diagnose_identifiability(experiment, param_values)
+>>> est = estimability_rank(experiment, param_values)
+>>> profile = profile_likelihood(experiment, data, "k")
+
+See Also
+--------
+discopt.estimate : Parameter estimation using the same Experiment interface.
+discopt.doe.surrogate : Surrogate model protocol + sklearn adapter.
+discopt.doe.acquisition : Acquisition functions (EI, UCB, steepest ascent).
+"""
+
+from importlib.metadata import PackageNotFoundError as _PkgNotFound
+from importlib.metadata import version as _dist_version
+
+# discopt-doe consumes the public discopt.parametric API and the
+# "discopt.cli" plugin hook, both introduced in discopt 0.6. A stale base
+# install fails here with a clear message instead of an AttributeError later.
+# Two-component compare so 0.6.0.dev0 local builds pass.
+_MIN_DISCOPT = (0, 6)
+
+
+def _version_prefix(found: str) -> tuple[int, ...]:
+    """(major, minor) integer prefix, tolerant of pre-release suffixes.
+
+    ``"0.6rc1"`` -> ``(0, 6)``, ``"0.7b2"`` -> ``(0, 7)``. The old
+    ``int(p) for p in ... if p.isdigit()`` dropped a component like ``"6rc1"``
+    entirely and spuriously rejected valid pre-releases.
+    """
+    import re as _re
+
+    out: list[int] = []
+    for p in found.split(".")[:2]:
+        m = _re.match(r"\d+", p)
+        if m:
+            out.append(int(m.group()))
+    return tuple(out)
+
+
+try:
+    _found = _dist_version("discopt")
+    _v = _version_prefix(_found)
+    if _v < _MIN_DISCOPT:
+        raise ImportError(
+            f"discopt-doe requires discopt>={'.'.join(map(str, _MIN_DISCOPT))} "
+            f"(found {_found}); upgrade with `pip install -U discopt`."
+        )
+except _PkgNotFound:  # odd dev setups (no dist metadata): don't block
+    pass
+
+from discopt.doe.acquisition import (
+    ACQUISITIONS,
+    confidence_bound,
+    expected_improvement,
+    resolve_acquisition,
+    steepest_ascent,
+)
+from discopt.doe.anova import AnovaEffect, AnovaTable, anova_report
+from discopt.doe.design import (
+    BatchDesignResult,
+    BatchStrategy,
+    DesignConstraint,
+    DesignCriterion,
+    DesignResult,
+    batch_optimal_experiment,
+    optimal_experiment,
+    project_to_simplex,
+    sample_simplex,
+    sum_constraint,
+)
+from discopt.doe.discrimination import (
+    DiscriminationCriterion,
+    DiscriminationDesignResult,
+    discriminate_compound,
+    discriminate_design,
+    evaluate_discrimination_criterion,
+)
+from discopt.doe.discrimination_sequential import (
+    DiscriminationRound,
+    sequential_discrimination,
+)
+from discopt.doe.estimability import (
+    EstimabilityResult,
+    collinearity_index,
+    d_optimal_subset,
+    estimability_rank,
+)
+from discopt.doe.exploration import (
+    ExplorationResult,
+    explore_design_space,
+)
+from discopt.doe.fim import (
+    FIMResult,
+    IdentifiabilityDiagnostics,
+    IdentifiabilityResult,
+    check_identifiability,
+    compute_fim,
+    diagnose_identifiability,
+)
+from discopt.doe.fractional import (
+    fractional_factorial_design,
+)
+from discopt.doe.latin import (
+    LatinDesign,
+    graeco_latin_square,
+    hyper_graeco_latin_square,
+    latin_square,
+    latin_square_design,
+)
+from discopt.doe.model_based import (
+    ModelBasedRoundResult,
+    ParametricSurrogate,
+    model_based_optimize_round,
+)
+from discopt.doe.optimize import (
+    OptimizationCriterion,
+    OptimizationRoundResult,
+    optimize_round,
+)
+from discopt.doe.profile import (
+    ProfileLikelihoodResult,
+    profile_all,
+    profile_likelihood,
+)
+from discopt.doe.screening import (
+    FactorialDesign,
+    effects_estimates,
+    factorial_2level_design,
+)
+from discopt.doe.selection import (
+    ModelSelectionResult,
+    likelihood_ratio_test,
+    model_selection,
+    vuong_test,
+)
+from discopt.doe.sequential import (
+    DoERound,
+    sequential_doe,
+)
+from discopt.doe.surrogate import (
+    PRESETS as SURROGATE_PRESETS,
+)
+from discopt.doe.surrogate import (
+    Surrogate,
+    coerce_surrogate,
+)
+from discopt.doe.templates import (
+    TEMPLATE_NAMES,
+    build_template,
+    linear_template,
+    polynomial_1d_template,
+    response_surface_template,
+    scheffe_linear_template,
+    scheffe_quadratic_template,
+    scheffe_special_cubic_template,
+    simplex_centroid_points,
+    simplex_lattice_points,
+)
+
+__all__ = [
+    "AnovaEffect",
+    "AnovaTable",
+    "BatchDesignResult",
+    "BatchStrategy",
+    "DesignConstraint",
+    "DesignCriterion",
+    "DesignResult",
+    "FactorialDesign",
+    "LatinDesign",
+    "DiscriminationCriterion",
+    "DiscriminationDesignResult",
+    "DiscriminationRound",
+    "DoERound",
+    "EstimabilityResult",
+    "ExplorationResult",
+    "FIMResult",
+    "IdentifiabilityDiagnostics",
+    "IdentifiabilityResult",
+    "ModelBasedRoundResult",
+    "ModelSelectionResult",
+    "OptimizationCriterion",
+    "OptimizationRoundResult",
+    "ParametricSurrogate",
+    "ProfileLikelihoodResult",
+    "SURROGATE_PRESETS",
+    "Surrogate",
+    "ACQUISITIONS",
+    "TEMPLATE_NAMES",
+    "anova_report",
+    "batch_optimal_experiment",
+    "build_template",
+    "coerce_surrogate",
+    "confidence_bound",
+    "expected_improvement",
+    "optimize_round",
+    "resolve_acquisition",
+    "steepest_ascent",
+    "check_identifiability",
+    "graeco_latin_square",
+    "hyper_graeco_latin_square",
+    "latin_square",
+    "latin_square_design",
+    "collinearity_index",
+    "compute_fim",
+    "d_optimal_subset",
+    "diagnose_identifiability",
+    "discriminate_compound",
+    "effects_estimates",
+    "factorial_2level_design",
+    "fractional_factorial_design",
+    "discriminate_design",
+    "estimability_rank",
+    "evaluate_discrimination_criterion",
+    "explore_design_space",
+    "likelihood_ratio_test",
+    "linear_template",
+    "model_based_optimize_round",
+    "model_selection",
+    "optimal_experiment",
+    "polynomial_1d_template",
+    "project_to_simplex",
+    "response_surface_template",
+    "profile_all",
+    "profile_likelihood",
+    "sample_simplex",
+    "scheffe_linear_template",
+    "scheffe_quadratic_template",
+    "scheffe_special_cubic_template",
+    "sequential_discrimination",
+    "sequential_doe",
+    "simplex_centroid_points",
+    "simplex_lattice_points",
+    "sum_constraint",
+    "vuong_test",
+]

discopt/doe/acquisition.py

@@ -0,0 +1,221 @@
+"""Acquisition functions for active-learning optimization.
+
+An acquisition function scores candidate design points by how
+*valuable* they are to evaluate next. Higher scores are better; the
+optimizer selects the top-``batch_size`` candidates.
+
+Every function in this module has the signature::
+
+    score(surrogate, X_candidates, *, y_best, direction, **kw) -> ndarray
+
+* ``surrogate`` is a fitted object satisfying the
+  :class:`~discopt.doe.surrogate.Surrogate` protocol.
+* ``X_candidates`` is a 2D array of shape ``(n, d)``.
+* ``y_best`` is the best observed response so far (incumbent).
+* ``direction`` is ``+1`` for *maximize* or ``-1`` for *minimize*.
+
+Implementations
+---------------
+
+* :func:`expected_improvement` -- the standard EI used in Bayesian
+  optimization. Balances exploitation (high predicted mean in the
+  desired direction) and exploration (high uncertainty).
+* :func:`upper_confidence_bound` / :func:`lower_confidence_bound` --
+  UCB / LCB. A direction-aware wrapper :func:`confidence_bound` picks
+  the right sign automatically.
+* :func:`steepest_ascent` -- Box-Wilson style: score points by the
+  predicted improvement only (ignores uncertainty). Useful with a
+  response-surface surrogate when you want classical RSM behaviour.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable, Literal
+
+import numpy as np
+
+from discopt.doe.surrogate import Surrogate
+
+Direction = Literal[1, -1]
+
+
+def _erf(x: np.ndarray) -> np.ndarray:
+    return np.asarray(np.vectorize(math.erf)(x), dtype=float)
+
+
+def _norm_cdf(x: np.ndarray) -> np.ndarray:
+    return 0.5 * (1.0 + _erf(x / math.sqrt(2.0)))
+
+
+def _norm_pdf(x: np.ndarray) -> np.ndarray:
+    return np.asarray(np.exp(-0.5 * x * x) / math.sqrt(2.0 * math.pi), dtype=float)
+
+
+def expected_improvement(
+    surrogate: Surrogate,
+    X_candidates: np.ndarray,
+    *,
+    y_best: float,
+    direction: Direction,
+    xi: float = 0.0,
+) -> np.ndarray:
+    """Expected improvement over the incumbent ``y_best``.
+
+    For maximization (``direction = +1``)::
+
+        EI(x) = (μ - y_best - xi) Φ(z) + σ φ(z)
+        z     = (μ - y_best - xi) / σ
+
+    For minimization (``direction = -1``), the sign flips so EI is
+    always non-negative for points that improve on the incumbent.
+
+    ``xi`` is an exploration knob -- a small positive value
+    (e.g. ``0.01``) demands a slightly stronger improvement and
+    encourages exploration.
+    """
+    mu, sigma = surrogate.predict(np.asarray(X_candidates, dtype=float))
+    mu = np.asarray(mu, dtype=float).ravel()
+    sigma = np.asarray(sigma, dtype=float).ravel()
+    dir_sign = int(direction)
+    if dir_sign not in (1, -1):
+        raise ValueError(f"direction must be +1 or -1, got {dir_sign}")
+
+    improvement = dir_sign * (mu - y_best) - xi
+    safe_sigma = np.where(sigma > 0.0, sigma, 1.0)
+    z = improvement / safe_sigma
+    ei = improvement * _norm_cdf(z) + safe_sigma * _norm_pdf(z)
+    ei = np.where(sigma > 0.0, ei, np.maximum(improvement, 0.0))
+    return ei
+
+
+def upper_confidence_bound(
+    surrogate: Surrogate,
+    X_candidates: np.ndarray,
+    *,
+    kappa: float = 2.0,
+) -> np.ndarray:
+    """``μ + κ σ`` -- maximize when ``direction = +1``."""
+    mu, sigma = surrogate.predict(np.asarray(X_candidates, dtype=float))
+    return np.asarray(mu).ravel() + float(kappa) * np.asarray(sigma).ravel()
+
+
+def lower_confidence_bound(
+    surrogate: Surrogate,
+    X_candidates: np.ndarray,
+    *,
+    kappa: float = 2.0,
+) -> np.ndarray:
+    """``-(μ - κ σ)`` -- larger is *better* under minimization."""
+    mu, sigma = surrogate.predict(np.asarray(X_candidates, dtype=float))
+    return -(np.asarray(mu).ravel() - float(kappa) * np.asarray(sigma).ravel())
+
+
+def confidence_bound(
+    surrogate: Surrogate,
+    X_candidates: np.ndarray,
+    *,
+    direction: Direction,
+    kappa: float = 2.0,
+) -> np.ndarray:
+    """Direction-aware UCB/LCB. Higher score = better candidate."""
+    if direction == 1:
+        return upper_confidence_bound(surrogate, X_candidates, kappa=kappa)
+    if direction == -1:
+        return lower_confidence_bound(surrogate, X_candidates, kappa=kappa)
+    raise ValueError(f"direction must be +1 or -1, got {direction}")
+
+
+def steepest_ascent(
+    surrogate: Surrogate,
+    X_candidates: np.ndarray,
+    *,
+    direction: Direction,
+    y_best: float | None = None,
+) -> np.ndarray:
+    """Predicted improvement only -- ignores uncertainty.
+
+    Score is ``direction * μ(x)`` (or, if ``y_best`` is supplied,
+    ``direction * (μ(x) - y_best)``, which only shifts the score and
+    does not change the ranking). Use this with a response-surface
+    surrogate to reproduce classical Box-Wilson behaviour.
+    """
+    mu, _sigma = surrogate.predict(np.asarray(X_candidates, dtype=float))
+    mu = np.asarray(mu, dtype=float).ravel()
+    if y_best is None:
+        return int(direction) * mu
+    return int(direction) * (mu - float(y_best))
+
+
+# Note: "ucb" and "lcb" both resolve to the *direction-aware* confidence_bound
+# wrapper, which picks upper (maximize) or lower (minimize) from the round's
+# direction. So under maximization "lcb" still computes the UCB (and vice
+# versa) -- the names are aliases for "confidence bound", not a hard choice of
+# upper vs lower. Use the raw upper_confidence_bound / lower_confidence_bound
+# callables directly if you need a fixed side.
+ACQUISITIONS: dict[str, Callable[..., np.ndarray]] = {
+    "expected_improvement": expected_improvement,
+    "ei": expected_improvement,
+    "ucb": confidence_bound,
+    "lcb": confidence_bound,
+    "confidence_bound": confidence_bound,
+    "steepest_ascent": steepest_ascent,
+}
+
+
+def resolve_acquisition(name_or_fn):
+    """Look up an acquisition function by string or pass through a callable."""
+    if callable(name_or_fn):
+        return name_or_fn
+    try:
+        return ACQUISITIONS[name_or_fn]
+    except KeyError as e:
+        raise ValueError(
+            f"unknown acquisition {name_or_fn!r}; available: {sorted(set(ACQUISITIONS))}"
+        ) from e
+
+
+def call_acquisition(acq_fn, surrogate, X_candidates, *, direction, y_best, acq_kwargs=None):
+    """Invoke an acquisition, passing only the arguments it accepts.
+
+    Replaces a ``try/except TypeError`` dispatch that both masked genuine
+    errors raised *inside* an acquisition and silently discarded the caller's
+    tuning kwargs. ``direction``/``y_best`` are injected only when the callable
+    declares them (or has ``**kwargs``), and user ``acq_kwargs`` that the
+    callable cannot consume raise a clear error instead of being swallowed.
+    """
+    import inspect
+
+    acq_kwargs = dict(acq_kwargs or {})
+    params = inspect.signature(acq_fn).parameters
+    has_var_kw = any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values())
+    named = {
+        n
+        for n, p in params.items()
+        if p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+    }
+    if not has_var_kw:
+        bad = [k for k in acq_kwargs if k not in named]
+        if bad:
+            tunable = sorted(named - {"surrogate", "X_candidates", "direction", "y_best"})
+            raise TypeError(
+                f"acquisition {getattr(acq_fn, '__name__', acq_fn)!r} got unexpected "
+                f"keyword(s) {bad}; it accepts {tunable}."
+            )
+    call_kwargs = dict(acq_kwargs)
+    if "direction" in named or has_var_kw:
+        call_kwargs["direction"] = direction
+    if "y_best" in named or has_var_kw:
+        call_kwargs["y_best"] = y_best
+    return acq_fn(surrogate, X_candidates, **call_kwargs)
+
+
+__all__ = [
+    "ACQUISITIONS",
+    "confidence_bound",
+    "expected_improvement",
+    "lower_confidence_bound",
+    "resolve_acquisition",
+    "steepest_ascent",
+    "upper_confidence_bound",
+]