Doc: add SacessOptimizer example

pypesto/optimize/ess/sacess.py

@@ -51,6 +51,35 @@ class SacessOptimizer:
     :class:`SacessOptimizer` can be used with or without a local optimizer, but
     it is highly recommended to use one.
 
+    A basic example using :class:`SacessOptimizer` to minimize the Rosenbrock
+    function:
+
+    >>> from pypesto.optimize import SacessOptimizer
+    >>> from pypesto.problem import Problem
+    >>> from pypesto.objective import Objective
+    >>> import scipy as sp
+    >>> import numpy as np
+    >>> import logging
+    >>> # Define some test Problem
+    >>> objective = Objective(
+    ...     fun=sp.optimize.rosen,
+    ...     grad=sp.optimize.rosen_der,
+    ...     hess=sp.optimize.rosen_hess,
+    ... )
+    >>> dim = 6
+    >>> problem = Problem(
+    ...     objective=objective,
+    ...     lb=-5 * np.ones((dim, 1)),
+    ...     ub=5 * np.ones((dim, 1)),
+    ... )
+    >>> # Create and run the optimizer
+    >>> sacess = SacessOptimizer(
+    ...     num_workers=2,
+    ...     max_walltime_s=5,
+    ...     sacess_loglevel=logging.WARNING
+    ... )
+    >>> result = sacess.minimize(problem)
+
     .. footbibliography::
 
     Attributes
@@ -86,8 +115,22 @@ def __init__(
             Resource limits such as ``max_eval`` apply to a single CESS
             iteration, not to the full search.
             Mutually exclusive with ``num_workers``.
+
             Recommended default settings can be obtained from
-            :func:`get_default_ess_options`.
+            :func:`get_default_ess_options`. For example, to run
+            :class:`SacessOptimizer` without a local optimizer, use:
+
+            >>> from pypesto.optimize.ess import get_default_ess_options
+            >>> ess_init_args = get_default_ess_options(
+            ...     num_workers=12,
+            ...     dim=10, # usually problem.dim
+            ...     local_optimizer=False,
+            ... )
+            >>> ess_init_args  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+            [{'dim_refset': 5, 'balance': 0.0, 'local_n1': 1, 'local_n2': 1},
+            ...
+             {'dim_refset': 7, 'balance': 1.0, 'local_n1': 4, 'local_n2': 4}]
+
         num_workers:
             Number of workers to be used. If this argument is given,
             (different) default ESS settings will be used for each worker.

pytest.ini

@@ -1,3 +1,4 @@
 [pytest]
+addopts = "--doctest-modules"
 filterwarnings =
     ignore:.*inspect.getargspec\(\) is deprecated.*:DeprecationWarning