soogo 2.1.0

Surrogate-based 0-th Order Global Optimization for black-box problems

soogo

Surrogate-based 0-th Order Global Optimization for black-box problems.

Current functionality

Optimization algorithm	Description	Tags
surrogate_optimization()	Minimize a scalar function using a surrogate and an acquisition function based on (Björkman & Holmström; 2000) and (Müller; 2016).	mixed-integer
multistart_msrs()	Multistart Local Metric Stochastic Response Surface (LMSRS) (Regis & Shoemaker; 2007). Applies a derivative-free local search algorithm to obtain new samples. Restarts the surrogate model with new design points whenever the local search has converged.	multi-start, RBF
dycors()	Dynamic Coordinate Search (DYCORS) (Regis & Shoemaker; 2012). Acquisition cycles between global and local search. Uses the DDS search from (Tolson & Shoemaker; 2007) to generate pools of candidates.	mixed-integer, RBF
cptv()	Minimize a scalar function using rounds of coordinate perturbation (CP) and target value (TV) acquisition functions (Müller; 2016). Derivative-free local search is used to improve a prospective global minimum	mixed-integer, RBF
socemo()	Surrogate-based optimization of computationally expensive multiobjective problems (SOCEMO) (Müller; 2017a).	multi-objective, mixed-integer, RBF
gosac()	Global optimization with surrogate approximation of constraints (GOSAC) (Müller; 2017b).	mixed-integer, black-box-constraint, RBF
bayesian_optimization()	Bayesian optimization with dispersion-enhanced expected improvement acquisition (Müller; 2024).	GP, batch
shebo()	Surrogate optimization of problems with hidden constraints and expensive black-box objectives (SHEBO) (Müller & Day; 2019).	hidden-constraint, expensive-objective, RBF
fsapso()	Fast Surrogate Assisted Particle Swarm Optimization (Li et al.; 2020).	RBF, PSO

Acquisition function	Description
WeightedAcquisition	Weighted acquisition function based on the predicted value and distance to the nearest sample (Regis & Shoemaker; 2012). Used in multistart_msrs(), dycors(), and in the CP step from cptv(). It uses average values for the multi-objective scenario (Müller; 2017a).
TargetValueAcquisition	Target value acquisition based from (Gutmann; 2001). Used in the TV step from cptv(). Cycles through target values as in (Björkman & Holmström; 2000). For batched acquisition, uses the strategy from (Müller; 2016) to avoid duplicates.
MinimizeSurrogate	Sample at the local minimum of the surrogate model (Müller; 2016). The original method, Multi-Level Single-Linkage (MLSL), is described in (Rinnooy Kan & Timmer; 1987).
MaximizeEI	Maximize the expected improvement acquisition function for Gaussian processes. Use the dispersion-enhanced strategy from (Müller; 2024) for batch sampling.
ParetoFront	Sample at the Pareto front of the multi-objective surrogate model to fill gaps in the surface (Müller; 2017a).
MinimizeMOSurrogate	Obtain pareto-optimal sample points for the multi-objective surrogate model (Müller; 2017a).
GosacSample	Minimize a function with constraints to obtain a single new sample point (Müller; 2017b).
MaximizeDistance	Maximizes the minimum distance to the set of current points. Used in shebo() and as a fallback in EndPointsParetoFront and GosacSample (Müller & Day; 2019).

Installation

Use PyPI to install this package:

pip install soogo

See other installation methods below.

Binaries

The binaries for the latest version are available at https://github.com/NREL/soogo/releases/latest. They can be installed through standard installation, e.g.,

using pip (https://pip.pypa.io/en/stable/cli/pip_install/):

pip install git+https://github.com/NREL/soogo.git#egg=soogo

From source

This package contains a pyproject.toml with the list of requirements and dependencies (More about pyproject.toml at https://packaging.python.org/en/latest/specifications/pyproject-toml/). With the source downloaded to your local machine, use pip install [soogo/source/directory].

For developers

This project is configured to use the package manager pdm. With pdm installed, run pdm install at the root of this repository to install the dependencies. The file pyproject.toml has the list of dependencies and configurations for the project.

Documentation

This project uses Sphinx to generate the documentation. The latest documentation is available at https://nrel.github.io/soogo. To generate the documentation locally, run make html in the docs directory. The homepage of the documentation will then be found at docs/_build/html/index.html.

Logging and Output

The disp parameter on optimizers is deprecated and ignored. Use Python's logging to control verbosity and progress output.

Example setup:

import logging

# Show info-level messages from soogo
logging.basicConfig(level=logging.INFO)

# Enable debug for a specific optimizer module
logging.getLogger("soogo.optimize.surrogate_optimization").setLevel(logging.DEBUG)

# Or enable debug for all soogo modules
logging.getLogger("soogo").setLevel(logging.DEBUG)

Guidance:

• Module loggers follow Python paths (e.g., soogo.optimize.gosac, soogo.optimize.fsapso).
• Iteration progress and timings log at INFO; deeper diagnostics at DEBUG; non-fatal issues at WARNING.
• Passing disp will emit a deprecation warning and have no effect.

Testing

This project uses pytest to run the tests. To run the tests, run pytest at the root of this repository. Run pytest --help to see the available options.

Contributing

Please, read the contributing guidelines before contributing to this project.

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

---

NLR Software Record number: SWR-24-57