..

pypesto/optimize/ess/ess.py

@@ -58,12 +58,47 @@ def __call__(
 class ESSOptimizer:
     """Enhanced Scatter Search (ESS) global optimization.
 
-    See papers on ESS :footcite:p:`EgeaBal2009,EgeaMar2010`,
-    CESS :footcite:p:`VillaverdeEge2012`, and saCeSS :footcite:p:`PenasGon2017`.
+    Scatter search is a meta-heuristic for global optimization. A set of points
+    (the reference set, RefSet) is iteratively adapted to explore the parameter
+    space and to follow promising directions.
 
-    .. footbibliography::
+    This implementation is based on :footcite:p:`EgeaBal2009,EgeaMar2010`,
+    but does not implement any constraint handling beyond box constraints.
+
+    The basic steps of ESS are:
+
+    * Initialization: Generate a diverse set of points in the parameter space.
+    * Recombination: Generate new points by recombining the RefSet.
+    * Improvement: Improve the RefSet by replacing points with better ones.
+
+    The steps are repeated until a stopping criterion is met.
+
+    ESS is gradient-free, unless a gradient-based local optimizer is used.
+
+
+    Exit criteria
+    -------------
 
-    .. note: Does not implement any constraint handling beyond box constraints
+    The optimization stops if any of the following criteria is met:
+
+    * The maximum number of iterations is reached (`max_iter`).
+    * The maximum number of objective function evaluations is reached
+      (`max_eval`).
+    * The maximum wall-time is reached (`max_walltime_s`).
+
+    One of these criteria needs to be provided.
+    Note that the wall-time and function evaluation criteria are not checked
+    after every single function evaluation, and thus, the actual number of
+    function evaluations may slightly exceed the given value.
+
+    Parallelization
+    ---------------
+
+    Objective function evaluations inside :class:`ESSOptimizer` can be
+    parallelized using multiprocessing or multithreading by passing a value
+    >1 for `n_procs` or `n_threads`, respectively.
+
+    .. footbibliography::
     """
 
     def __init__(