Python API🔗

This page summarizes the Python API signatures from python/egobox/egobox.pyi for:

• Egor constructor and Egor.minimize(...)
• Belfegor constructor and Belfegor.minimize(...) (multi-objective)
• Gpx.builder(...)
• Gpx instance and static methods

Default values are copied from the stub.

Egor constructor🔗

Signature:

Egor(
    xspecs,
    gp_config=GpConfig(),
    n_cstr=0,
    cstr_specs=None,
    infill_n_start=20,
    n_doe=0,
    x_doe=None,
    y_doe=None,
    infill_strategy=InfillStrategy.LOG_EI,
    feasible_infill_strategy=FeasibleInfillStrategy.NONE,
    cstr_infill=False,
    cstr_strategy=ConstraintStrategy.MC,
    qei_config=QEiConfig(),
    infill_optimizer=InfillOptimizer.COBYLA,
    trego=None,
    coego_n_coop=0,
    target=-1.7976931348623157e+308,
    failsafe_strategy=FailsafeStrategy.REJECTION,
    seed=None,
    verbose=None,
)

GpConfig🔗

QEiConfig🔗

TregoConfig🔗

When trego=True in Egor(...), the Python binding activates TREGO with TregoConfig() defaults.

Egor.minimize🔗

Signature:

Egor.minimize(
    fun,
    fcstrs=[],
    fcstr_specs=[],
    max_iters=20,
    run_info=None,
    outdir=None,
    warm_start=False,
    hot_start=None,
    seed=None,
    timeout=None,
    verbose=None,
)

It returns an EgorOptim with result (an OptimResult holding x_opt, y_opt, x_doe, y_doe) and status. The result fields are also available directly on the returned object, which can be unpacked as (x_opt, y_opt):

res = egor.minimize(fun, max_iters=20)
res.x_opt, res.y_opt  # same as res.result.x_opt, res.result.y_opt
x_opt, y_opt = egor.minimize(fun, max_iters=20)

Egor.best_result(x_doe, y_doe) and Egor.best_index(y_doe) give the best point of a given DOE.

Belfegor (multi-objective, experimental)🔗

Belfegor approximates the Pareto front of several objectives, all minimized: fun(x) returns [obj_1, ..., obj_n_obj, cstr_1, ... cstr_k] columns (ny = n_obj + n_cstr). It shares the Egor options which apply to several objectives (trego, coego_n_coop and target are not available).

Signature:

Belfegor(
    xspecs,
    n_obj=2,
    moo_config=None,
    gp_config=None,
    n_cstr=0,
    cstr_specs=None,
    infill_n_start=20,
    n_doe=0,
    x_doe=None,
    y_doe=None,
    infill_strategy=InfillStrategy.LOG_EI,
    feasible_infill_strategy=FeasibleInfillStrategy.NONE,
    cstr_infill=False,
    cstr_strategy=ConstraintStrategy.MC,
    infill_optimizer=InfillOptimizer.COBYLA,
    failsafe_strategy=FailsafeStrategy.REJECTION,
    seed=None,
    verbose=None,
)

The other parameters are the Egor ones. infill_strategy and feasible_infill_strategy apply to the scalarized objective of MooStrategy.PAREGO. Batches of points are set with MooConfig(batch=...) (there is no qei_config).

MooConfig🔗

MooConfig(
    strategy=None,
    batch=1,
    eim_aggregation=EimAggregation.EUCLIDEAN,
    hv_stop=None,
    rho=0.05,
    n_divisions=None,
)

A dict with the same keys is also accepted.

Belfegor.minimize🔗

Belfegor.minimize(fun, fcstrs=None, fcstr_specs=None, max_iters=20, run_info=None, outdir=None, warm_start=False, hot_start=None, seed=None, timeout=None, verbose=None, stop_on_error=False) takes the Egor.minimize parameters and returns a BelfegorOptim with result (a ParetoResult holding x_pareto, y_pareto, x_opt, y_opt, x_doe, y_doe) and status. x_pareto/y_pareto is the (constrained) Pareto front approximation and x_opt/y_opt its compromise point. The result fields are also available directly on the returned object, which can be unpacked as (x_pareto, y_pareto):

res = belfegor.minimize(fun, max_iters=20)
res.x_pareto, res.y_pareto  # same as res.result.x_pareto, res.result.y_pareto
x_pareto, y_pareto = belfegor.minimize(fun, max_iters=20)

Belfegor.suggest(x_doe, y_doe) gives the next points to evaluate (ask-and-tell), and Belfegor.pareto_result(x_doe, y_doe) / Belfegor.pareto_indices(y_doe) give the Pareto front of a given DOE.

Gpx.builder🔗

Signature:

Gpx.builder(
    xspecs=None,
    regr_spec=1,
    corr_spec=1,
    kpls_dim=None,
    n_clusters=1,
    recombination=Recombination.HARD,
    theta_init=None,
    theta_bounds=None,
    theta_n_start=10,
    theta_max_eval=50,
    seed=None,
    verbose=None,
)

Gpx methods🔗

def __repr__(self) -> str
def __str__(self) -> str
def save(self, filename: str) -> bool
@staticmethod
def load(filename: str) -> Gpx
def predict(self, x: NDArray[float64], return_std: bool = False) -> NDArray[float64] | tuple[NDArray[float64], NDArray[float64]]
def predict_var(self, x: NDArray[float64]) -> NDArray[float64]
def predict_gradients(self, x: NDArray[float64]) -> NDArray[float64]
def predict_var_gradients(self, x: NDArray[float64]) -> NDArray[float64]
def sample(self, x: NDArray[float64], n_traj: int) -> NDArray[float64]
def dims(self) -> tuple[int, int]
nx: int  # read-only property, number of inputs
ny: int  # read-only property, number of outputs
def training_data(self) -> tuple[NDArray[float64], NDArray[float64]]
thetas: NDArray[float64]  # read-only property, optimized hyperparameters (n_clusters, nx or kpls_dim)
variances: NDArray[float64]  # read-only property, variance of each expert (n_clusters,)
likelihoods: NDArray[float64]  # read-only property, reduced likelihood of each expert (n_clusters,)

XSpecs🔗

xspecs passed to Egor(...) or Gpx.builder(...) is a sequence of XSpec, one per input dimension (len(xspecs) == nx).

Note: When using continuous variables only, the simplest form is a list of [lower, upper] pairs, e.g. [[0.0, 1.0], [1.0, 10.0], [-5.0, 5.0]]. Otherwise, use XSpec(...) for more complex variable types.

Signature:

XSpec(xtype: XType, xlimits: Sequence[float] = [], tags: Sequence[str] = [])

xlimits meaning by xtype:

Full mixed-type example:

xspecs = [
    XSpec(XType.FLOAT, [0.0, 1.0]),
    XSpec(XType.INT, [1, 8]),
    XSpec(XType.ORD, [0.2, 0.5, 1.0]),
    XSpec(XType.ENUM, tags=["small", "medium", "large"]),
]