Doc: Update SacessOptimizer

pypesto/optimize/ess/sacess.py

@@ -89,7 +89,7 @@ def __init__(
             See :func:`get_default_ess_options` for details on the default
             settings.
         max_walltime_s:
-            Maximum walltime in seconds. Will only be checked between local
+            Maximum walltime in seconds. It will only be checked between local
             optimizations and other simulations, and thus, may be exceeded by
             the duration of a local search. Defaults to no limit.
             Note that in order to impose the wall time limit also on the local
@@ -100,10 +100,10 @@ def __init__(
         sacess_loglevel:
             Loglevel for SACESS runs.
         tmpdir:
-            Directory for temporary files. Defaults to a directory in the current
-            working directory named ``SacessOptimizerTemp-{random suffix}``.
-            When setting this option, make sure any optimizers running in parallel
-            have unique tmpdirs.
+            Directory for temporary files. This defaults to a directory in the
+            current working directory named ``SacessOptimizerTemp-{random suffix}``.
+            When setting this option, make sure any optimizers running in
+            parallel have unique `tmpdir`.
         """
         if (num_workers is None and ess_init_args is None) or (
             num_workers is not None and ess_init_args is not None
@@ -139,16 +139,36 @@ def minimize(
         self,
         problem: Problem,
         startpoint_method: StartpointMethod = None,
-    ):
+    ) -> pypesto.Result:
         """Solve the given optimization problem.
 
+        Note that if this function is called from a multithreaded program (
+        multiple threads running at the time of calling this function) and
+        the :mod:`multiprocessing` `start method` is set to ``fork``, there is
+        a good chance for deadlocks. Postpone spawning threads until after
+        `minimize` or change the *start method* to ``spawn``.
+
         Parameters
         ----------
         problem:
             Minimization problem.
+            :meth:`Problem.startpoint_method` will be used to sample random
+            points. `SacessOptimizer` will deal with non-evaluable points.
+            Therefore, using :class:`pypesto.startpoint.CheckedStartpoints`
+            with ``check_fval=True`` or ``check_grad=True`` is not recommended
+            since it would create significant overhead.
+
         startpoint_method:
             Method for choosing starting points.
             **Deprecated. Use ``problem.startpoint_method`` instead.**
+
+        Returns
+        -------
+        Result object with optimized parameters in
+        :attr:`pypesto.Result.optimize_result`.
+        Results are sorted by objective. At least the best parameters are
+        included. Additional results may be included - this is subject to
+        change.
         """
         if startpoint_method is not None:
             warn(
@@ -613,7 +633,7 @@ def _maybe_adapt(self, problem: Problem):
 
         Update ESS settings if conditions are met.
         """
-        # Update ESS settings if we received way more solutions than we  sent
+        # Update ESS settings if we received way more solutions than we sent
         # Magic numbers from [PenasGon2017]_ algorithm 5
         if (
             self._n_received_solutions > 10 * self._n_sent_solutions + 20
@@ -761,8 +781,12 @@ def get_default_ess_options(
     num_workers: Number of configurations to return.
     dim: Problem dimension (number of optimized parameters).
     local_optimizer: The local optimizer to use
-        (see same argument in :class:`ESSOptimizer`), or a boolean indicating
-        whether to set the default local optimizer (currently :class:`FidesOptimizer`).
+        (see same argument in :class:`ESSOptimizer`), a boolean indicating
+        whether to set the default local optimizer
+        (currently :class:`FidesOptimizer`), a :obj:`Callable` returning an
+        optimizer instance.
+        The latter can be used to propagate walltime limits to the local
+        optimizers. See :meth:`SacessFidesFactory.__call__` for an example.
     """
     min_dimrefset = 5