High-Level API#

Layer 1: Use
saealib.minimize(func, algorithm=UNSET, *, dim=None, lb=None, ub=None, n_obj=1, direction=None, surrogate=UNSET, strategy=UNSET, preset=None, max_fe=None, pop_size=None, seed=None, history_channels=None, verbose=True)[source]#

Run surrogate-assisted minimization.

Parameters:

  • func (callable or Problem) – Objective function f(x) -> float | array, or a fully configured Problem instance (in which case dim, lb, ub, and n_obj are ignored; its own direction is respected, and passing direction is invalid).

  • algorithm (str, Algorithm, or None) – 'GA', 'PSO', or an Algorithm instance. If omitted, the library’s bundled default preset resolves it (currently GA with BLX-alpha crossover and uniform mutation).

  • dim (int, optional) – Number of design variables. Required when func is a callable.

  • lb (array-like, optional) – Lower bounds of length dim. Required when func is a callable.

  • ub (array-like, optional) – Upper bounds of length dim. Required when func is a callable.

  • n_obj (int) – Number of objectives. Ignored when func is a Problem. Default: 1.

  • direction (np.ndarray, list[str], or None) – Optimization direction per objective. Each element is -1/"minimize" (minimize) or +1/"maximize" (maximize). Default: all minimize for callable objectives. A Problem uses its own direction.

  • surrogate (str, Surrogate, SurrogateManager, or None) – 'rbf', a Surrogate, or a SurrogateManager. If omitted, the library’s bundled default preset resolves it (currently an RBF surrogate with mean-prediction acquisition). Passing None explicitly is not supported and raises ValidationError.

  • strategy (str, OptimizationStrategy, or None) – 'ib', 'gb', 'ps', or an OptimizationStrategy. If omitted, the library’s bundled default preset resolves it (currently individual-based).

  • preset (str, Path, dict, or None, optional) – A preset (YAML file path or dict) providing default component configuration. See Optimizer.set_preset(). Components explicitly passed via algorithm/surrogate/strategy still take precedence.

  • max_fe (int or None) – Maximum true function evaluations. If omitted, semantic defaults or the 200 * dim fallback are used.

  • pop_size (int or None) – Population size. Semantic defaults from the configured composition are used when omitted, with 4 * dim as the fallback.

  • seed (int or None) – Random seed for LHSInitializer.

  • history_channels (sequence of str or None) – Execution history channels to record. None keeps the default summary history. Include "evaluation" to record every true evaluation result.

  • verbose (bool) – If False, suppress per-generation log output. Default: True.

Return type:

Result

Examples

>>> from saealib import minimize
>>> import numpy as np
>>> result = minimize(lambda x: np.sum(x**2), dim=5, lb=[-5]*5, ub=[5]*5,
...                   max_fe=500, seed=0, verbose=False)
>>> result.x, result.f
saealib.maximize(func, algorithm=UNSET, *, dim=None, lb=None, ub=None, n_obj=1, direction=None, surrogate=UNSET, strategy=UNSET, preset=None, max_fe=None, pop_size=None, seed=None, history_channels=None, verbose=True)[source]#

Run surrogate-assisted maximization.

Identical to minimize() except that all objectives are maximized (direction = +1) for callable objectives. When a Problem is passed, its own direction is respected.

Parameters:

  • func (callable or Problem) – Objective function f(x) -> float | array, or a fully configured Problem instance (in which case dim, lb, ub, and n_obj are ignored; its own direction is respected, and passing direction is invalid).

  • algorithm (str, Algorithm, or None) – 'GA', 'PSO', or an Algorithm instance. If omitted, the library’s bundled default preset resolves it (currently GA with BLX-alpha crossover and uniform mutation).

  • dim (int, optional) – Number of design variables. Required when func is a callable.

  • lb (array-like, optional) – Lower bounds of length dim. Required when func is a callable.

  • ub (array-like, optional) – Upper bounds of length dim. Required when func is a callable.

  • n_obj (int) – Number of objectives. Ignored when func is a Problem. Default: 1.

  • direction (np.ndarray, list[str], or None) – Optimization direction per objective. Each element is -1/"minimize" (minimize) or +1/"maximize" (maximize). Default: all maximize for callable objectives. A Problem uses its own direction.

  • surrogate (str, Surrogate, SurrogateManager, or None) – 'rbf', a Surrogate, or a SurrogateManager. If omitted, the library’s bundled default preset resolves it (currently an RBF surrogate with mean-prediction acquisition). Passing None explicitly is not supported and raises ValidationError.

  • strategy (str, OptimizationStrategy, or None) – 'ib', 'gb', 'ps', or an OptimizationStrategy. If omitted, the library’s bundled default preset resolves it (currently individual-based).

  • preset (str, Path, dict, or None, optional) – A preset (YAML file path or dict) providing default component configuration. See Optimizer.set_preset(). Components explicitly passed via algorithm/surrogate/strategy still take precedence.

  • max_fe (int or None) – Maximum true function evaluations. If omitted, semantic defaults or the 200 * dim fallback are used.

  • pop_size (int or None) – Population size. Semantic defaults from the configured composition are used when omitted, with 4 * dim as the fallback.

  • seed (int or None) – Random seed for LHSInitializer.

  • history_channels (sequence of str or None) – Execution history channels to record. None keeps the default summary history. Include "evaluation" to record every true evaluation result.

  • verbose (bool) – If False, suppress per-generation log output. Default: True.

Return type:

Result

Examples

>>> from saealib import maximize
>>> import numpy as np
>>> result = maximize(lambda x: -np.sum(x**2) + 10, dim=5, lb=[-5]*5, ub=[5]*5,
...                   max_fe=500, seed=0, verbose=False)
>>> result.x, result.f

saealib.Result

Optimization result returned by minimize() / maximize().