mixle.doe._contracts module

Structural (duck-typed) contracts for the DOE layer, as runtime-checkable Protocols (WS-E).

The DOE layer follows a “register, don’t branch” pattern: acquisition functions go through mixle.doe.bayesopt.register_acquisition(), optimality criteria through mixle.doe.optimal.register_criterion(), and the GP surrogate is passed in as a duck-typed gp= argument. This module formalizes those three contracts as @runtime_checkable Protocols so the registry value types and the gp= parameters can be annotated precisely (instead of bare Callable[..., ...] / Any), and so a surrogate can be validated with isinstance.

These are typing-level only: they add no behavior and the registries / call sites are unchanged.

class Acquisition(*args, **kwargs)[source]

Bases: Protocol

The acquisition-function contract registered via register_acquisition (EI/PI/UCB).

An acquisition scores candidate points from their surrogate posterior moments and returns a merit array that the proposal loop maximizes over the candidate set. It is called as fn(mean, std, best, *, maximize, **params) where mean / std are the predictive mean and standard deviation at the candidates, best is the incumbent objective value, maximize selects the optimization sense, and **params carries per-acquisition knobs (e.g. xi for EI/PI, kappa for UCB). Built-ins mixle.doe.bayesopt.expected_improvement(), probability_of_improvement(), and upper_confidence_bound() satisfy this contract.

class Surrogate(*args, **kwargs)[source]

Bases: Protocol

The GP-surrogate contract passed as gp= to the Bayesian-optimization loops.

A surrogate is fit to the observed (x, y) and queried for the posterior predictive moments at new candidate points. The call convention is the one used by mixle.models.gaussian_process.GaussianProcessRegressor: fit trains in place (it may return diagnostics, which the loops ignore), and predict takes the training data alongside the query points, returning the posterior mean (return_cov=False) or (mean, cov) pair (return_cov=True).

fit(x, y, **kwargs)[source]

Fit or update the surrogate from observed design points x and responses y.

Parameters:
Return type:

Any

predict(x_train, y_train, x_new, return_cov=...)[source]

Return predictive moments at x_new using the observed training data.

Parameters:
Return type:

Any

class Criterion(*args, **kwargs)[source]

Bases: Protocol

The optimality-criterion contract registered via register_criterion (D/A/I-optimality).

A criterion maps the information matrix M = F.T @ F to a scalar merit that mixle.doe.optimal.optimal_design() maximizes over candidate designs. It is called as fn(info, *, ref) where ref is an optional reference model matrix (used by I-optimality). Built-ins mixle.doe.optimal.d_criterion(), a_criterion(), and i_criterion() satisfy this contract.