Scatter search documentation / use local optimizer by default

doc/conf.py

@@ -71,6 +71,8 @@
     'autodoc_inherit_docstrings': True,
 }
 autodoc_mock_imports = ["amici"]
+autodoc_class_signature = "separated"
+
 
 # links for intersphinx
 intersphinx_mapping = {
@@ -90,7 +92,7 @@
 typehints_document_rtype = True
 autodoc_typehints = "description"
 
-bibtex_bibfiles = ["using_pypesto.bib"]
+bibtex_bibfiles = ["using_pypesto.bib", "references.bib"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/references.bib

@@ -0,0 +1,67 @@
+
+@Article{EgeaBal2009,
+  author           = {Egea, Jose A. and Balsa-Canto, Eva and García, María-Sonia G. and Banga, Julio R.},
+  journal          = {Industrial & Engineering Chemistry Research},
+  title            = {Dynamic Optimization of Nonlinear Processes with an Enhanced Scatter Search Method},
+  year             = {2009},
+  issn             = {1520-5045},
+  month            = apr,
+  number           = {9},
+  pages            = {4388--4401},
+  volume           = {48},
+  creationdate     = {2023-11-21T15:56:38},
+  doi              = {10.1021/ie801717t},
+  modificationdate = {2023-11-21T16:27:59},
+  publisher        = {American Chemical Society (ACS)},
+}
+
+@Article{EgeaMar2010,
+  author           = {Jose A. Egea and Rafael Martí and Julio R. Banga},
+  journal          = {Computers & Operations Research},
+  title            = {An evolutionary method for complex-process optimization},
+  year             = {2010},
+  issn             = {0305-0548},
+  number           = {2},
+  pages            = {315-324},
+  volume           = {37},
+  abstract         = {In this paper we present a new evolutionary method for complex-process optimization. It is partially based on the principles of the scatter search methodology, but it makes use of innovative strategies to be more effective in the context of complex-process optimization using a small number of tuning parameters. In particular, we introduce a new combination method based on path relinking, which considers a broader area around the population members than previous combination methods. We also use a population-update method which improves the balance between intensification and diversification. New strategies to intensify the search and to escape from suboptimal solutions are also presented. The application of the proposed evolutionary algorithm to different sets of both state-of-the-art continuous global optimization and complex-process optimization problems reveals that it is robust and efficient for the type of problems intended to solve, outperforming the results obtained with other methods found in the literature.},
+  creationdate     = {2023-11-21T15:57:20},
+  doi              = {https://doi.org/10.1016/j.cor.2009.05.003},
+  keywords         = {Evolutionary algorithms, Complex-process optimization, Continuous optimization, Global optimization, Metaheuristics},
+  modificationdate = {2023-11-21T15:57:20},
+  url              = {https://www.sciencedirect.com/science/article/pii/S0305054809001440},
+}
+
+
+@Article{VillaverdeEge2012,
+  author           = {Villaverde, Alejandro F and Egea, Jose A and Banga, Julio R},
+  journal          = {BMC Systems Biology},
+  title            = {A cooperative strategy for parameter estimation in large scale systems biology models},
+  year             = {2012},
+  issn             = {1752-0509},
+  month            = jun,
+  number           = {1},
+  volume           = {6},
+  creationdate     = {2023-11-21T15:57:46},
+  doi              = {10.1186/1752-0509-6-75},
+  modificationdate = {2023-11-21T15:57:46},
+  publisher        = {Springer Science and Business Media LLC},
+}
+
+
+@Article{PenasGon2017,
+  author           = {Penas, David R. and González, Patricia and Egea, Jose A. and Doallo, Ramón and Banga, Julio R.},
+  journal          = {BMC Bioinformatics},
+  title            = {Parameter estimation in large-scale systems biology models: a parallel and self-adaptive cooperative strategy},
+  year             = {2017},
+  issn             = {1471-2105},
+  month            = jan,
+  number           = {1},
+  volume           = {18},
+  creationdate     = {2023-11-21T15:57:58},
+  doi              = {10.1186/s12859-016-1452-4},
+  modificationdate = {2023-11-21T15:57:58},
+  publisher        = {Springer Science and Business Media LLC},
+}
+
+@Comment{jabref-meta: databaseType:bibtex;}

pypesto/optimize/__init__.py

@@ -6,7 +6,13 @@
 Multistart optimization with support for various optimizers.
 """
 
-from .ess import CESSOptimizer, ESSOptimizer, SacessOptimizer
+from .ess import (
+    CESSOptimizer,
+    ESSOptimizer,
+    SacessFidesFactory,
+    SacessOptimizer,
+    get_default_ess_options,
+)
 from .load import (
     fill_result_from_history,
     optimization_result_from_history,

pypesto/optimize/ess/__init__.py

@@ -7,4 +7,8 @@
     FunctionEvaluatorMT,
 )
 from .refset import RefSet
-from .sacess import SacessOptimizer, get_default_ess_options
+from .sacess import (
+    SacessFidesFactory,
+    SacessOptimizer,
+    get_default_ess_options,
+)

pypesto/optimize/ess/cess.py

@@ -23,25 +23,21 @@ class CESSOptimizer:
     r"""
     Cooperative Enhanced Scatter Search Optimizer (CESS).
 
-    A cooperative scatter search algorithm based on [VillaverdeEge2012]_.
+    A cooperative scatter search algorithm based on :footcite:t:`VillaverdeEge2012`.
     In short, multiple scatter search instances with different hyperparameters
     are running in different threads/processes, and exchange information.
     Some instances focus on diversification while others focus on
     intensification. Communication happens at fixed time intervals.
 
-    Proposed hyperparameter values in [VillaverdeEge2012]_:
+    Proposed hyperparameter values in :footcite:t:`VillaverdeEge2012`:
 
     * ``dim_refset``: ``[0.5 n_parameter, 20 n_parameters]``
     * ``local_n2``: ``[0, 100]``
     * ``balance``: ``[0, 0.5]``
     * ``n_diverse``: ``[5 n_par, 20 n_par]``
-    * ``max_eval``: such that :math:`\tau = log10(max_eval / n_par)` is in
-      [2.5, 3.5], with a recommended default value of 2.5.
-
-    .. [VillaverdeEge2012] 'A cooperative strategy for parameter estimation in
-       large scale systems biology models', Villaverde, A.F., Egea,
-       J.A. & Banga, J.R. BMC Syst Biol 2012, 6, 75.
-       https://doi.org/10.1186/1752-0509-6-75
+    * ``max_eval``: such that
+      :math:`\tau = log10(max\_eval / n\_par) \in [2.5, 3.5]`
+      with a recommended default value of :math:`\tau = 2.5`.
 
     Attributes
     ----------
@@ -65,6 +61,10 @@ class CESSOptimizer:
         Starting time of the most recent optimization.
     i_iter:
         Current iteration number.
+
+    References
+    ----------
+    .. footbibliography::
     """
 
     def __init__(

pypesto/optimize/ess/ess.py

@@ -1,28 +1,7 @@
 """Enhanced Scatter Search.
 
-See papers on ESS [EgeaBal2009]_ [EgeaMar2010]_, CESS [VillaverdeEge2012]_ and
-saCeSS [PenasGon2017]_.
-
-References
-==========
-
-.. [EgeaBal2009] 'Dynamic Optimization of Nonlinear Processes with an Enhanced
-   Scatter Search Method', Jose A. Egea, Eva Balsa-Canto,
-   María-Sonia G. García, and Julio R. Banga, Ind. Eng. Chem. Res.
-   2009, 48, 9, 4388–4401. https://doi.org/10.1021/ie801717t
-
-.. [EgeaMar2010] 'An evolutionary method for complex-process optimization',
-   Jose A. Egea, Rafael Martí, Julio R. Banga, Computers & Operations Research,
-   2010, 37, 2, 315-324. https://doi.org/10.1016/j.cor.2009.05.003
-
-.. [VillaverdeEge2012] 'A cooperative strategy for parameter estimation in
-   large scale systems biology models', Villaverde, A.F., Egea, J.A. & Banga,
-   J.R. BMC Syst Biol 2012, 6, 75. https://doi.org/10.1186/1752-0509-6-75
-
-.. [PenasGon2017] 'Parameter estimation in large-scale systems biology models:
-   a parallel and self-adaptive cooperative strategy', David R. Penas,
-   Patricia González, Jose A. Egea, Ramón Doallo and Julio R. Banga,
-   BMC Bioinformatics 2017, 18, 52. https://doi.org/10.1186/s12859-016-1452-4
+See papers on ESS :footcite:p:`EgeaBal2009,EgeaMar2010`,
+CESS :footcite:p:`VillaverdeEge2012`, and saCeSS :footcite:p:`PenasGon2017`.
 """
 import enum
 import logging
@@ -60,6 +39,11 @@ class ESSExitFlag(int, enum.Enum):
 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`.
+
+    .. footbibliography::
+
     .. note: Does not implement any constraint handling beyond box constraints
     """
 
@@ -83,7 +67,7 @@ def __init__(
     ):
         """Construct new ESS instance.
 
-        For plausible values of hyperparameters, see VillaverdeEge2012.
+        For plausible values of hyperparameters, see :footcite:t:`VillaverdeEge2012`.
 
         Parameters
         ----------
@@ -104,6 +88,7 @@ def __init__(
             In case of a callable, it will be called with the keyword arguments
             `max_walltime_s` and `max_eval`, which should be passed to the optimizer
             (if supported) to honor the overall budget.
+            See :class:`SacessFidesFactory` for an example.
         n_diverse:
             Number of samples to choose from to construct the initial RefSet
         max_eval: