diff --git a/README.rst b/README.rst index 667d509..4db2806 100644 --- a/README.rst +++ b/README.rst @@ -27,7 +27,7 @@ Py-BOBYQA is a flexible package for solving bound-constrained general objective More details about Py-BOBYQA and its enhancements over BOBYQA can be found in our papers: 1. Coralia Cartis, Jan Fiala, Benjamin Marteau and Lindon Roberts, `Improving the Flexibility and Robustness of Model-Based Derivative-Free Optimization Solvers `_, *ACM Transactions on Mathematical Software*, 45:3 (2019), pp. 32:1-32:41 [`arXiv preprint: 1804.00154 `_] -2. Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization* (2021). [`arXiv preprint: 1812.11343 `_] +2. Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization*, 71:8 (2022), pp. 2343-2373. [`arXiv preprint: 1812.11343 `_] Please cite [1] when using Py-BOBYQA for local optimization, and [1,2] when using Py-BOBYQA's global optimization heuristic functionality. For reproducibility of all figures, please feel free to contact the authors. @@ -47,19 +47,19 @@ Cartis, C., Fiala, J., Marteau, B. and Roberts, L., Improving the Flexibility an If you use Py-BOBYQA's global optimization heuristic, please cite the above and also -Cartis, C., Roberts, L. and Sheridan-Methven, O., Escaping local minima with derivative-free methods: a numerical investigation, Optimization, (2021). +Cartis, C., Roberts, L. and Sheridan-Methven, O., Escaping local minima with derivative-free methods: a numerical investigation, Optimization, 71:8 (2022), pp. 2343-2373. Requirements ------------ Py-BOBYQA requires the following software to be installed: -* Python 2.7 or Python 3 (http://www.python.org/) +* Python 3.8 or higher (http://www.python.org/) Additionally, the following python packages should be installed (these will be installed automatically if using *pip*, see `Installation using pip`_): -* NumPy 1.11 or higher (http://www.numpy.org/) -* SciPy 0.18 or higher (http://www.scipy.org/) -* Optionally, Pandas 0.17 or higher (http://pandas.pydata.org/), to return the diagnostic information as a DataFrame +* NumPy (http://www.numpy.org/) +* SciPy (http://www.scipy.org/) +* Pandas (http://pandas.pydata.org/) **Optional package:** Py-BOBYQA versions 1.2 and higher also support the `trustregion `_ package for fast trust-region subproblem solutions. To install this, make sure you have a Fortran compiler (e.g. `gfortran `_) and NumPy installed, then run :code:`pip install trustregion`. You do not have to have trustregion installed for Py-BOBYQA to work, and it is not installed by default. @@ -125,11 +125,12 @@ To upgrade Py-BOBYQA to the latest version, navigate to the top-level directory Testing ------- -If you installed Py-BOBYQA manually, you can test your installation by running: +If you installed Py-BOBYQA manually, you can test your installation using the pytest package: .. code-block:: bash - $ python setup.py test + $ pip install pytest + $ python -m pytest --pyargs pybobyqa Alternatively, the HTML documentation provides some simple examples of how to run Py-BOBYQA. diff --git a/docs/index.rst b/docs/index.rst index 44d3b87..f0ec695 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,9 +26,9 @@ The upper and lower bounds on the variables are non-relaxable (i.e. Py-BOBYQA wi Full details of the Py-BOBYQA algorithm are given in our papers: 1. Coralia Cartis, Jan Fiala, Benjamin Marteau and Lindon Roberts, `Improving the Flexibility and Robustness of Model-Based Derivative-Free Optimization Solvers `_, *ACM Transactions on Mathematical Software*, 45:3 (2019), pp. 32:1-32:41 [`preprint `_] -2. Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization* (2021). [`preprint `_] +2. Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization*, 71:8 (2022), pp. 2343-2373. [`arXiv preprint: 1812.11343 `_] -Please cite [1] when using Py-BOBYQA for local optimization, and [1,2] when using Py-BOBYQA's global optimization heuristic functionality **(new in v1.1!)**. +Please cite [1] when using Py-BOBYQA for local optimization, and [1,2] when using Py-BOBYQA's global optimization heuristic functionality. If you are interested in solving least-squares minimization problems, you may wish to try `DFO-LS `_, which has the same features as Py-BOBYQA (plus some more), and exploits the least-squares problem structure, so performs better on such problems. diff --git a/docs/install.rst b/docs/install.rst index c331af2..94454c0 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -5,13 +5,13 @@ Requirements ------------ Py-BOBYQA requires the following software to be installed: -* `Python 2.7 or Python 3 `_ +* Python 3.8 or higher (http://www.python.org/) Additionally, the following python packages should be installed (these will be installed automatically if using `pip `_, see `Installation using pip`_): -* `NumPy 1.11 or higher `_ -* `SciPy 0.18 or higher `_ -* Optionally, `Pandas 0.17 or higher `_, to return the diagnostic information as a DataFrame +* NumPy (http://www.numpy.org/) +* SciPy (http://www.scipy.org/) +* Pandas (http://pandas.pydata.org/) **Optional package:** Py-BOBYQA versions 1.2 and higher also support the `trustregion `_ package for fast trust-region subproblem solutions. To install this, make sure you have a Fortran compiler (e.g. `gfortran `_) and NumPy installed, then run :code:`pip install trustregion`. You do not have to have trustregion installed for Py-BOBYQA to work, and it is not installed by default. @@ -71,11 +71,12 @@ To upgrade Py-BOBYQA to the latest version, navigate to the top-level directory Testing ------- -If you installed Py-BOBYQA manually, you can test your installation by running: +If you installed Py-BOBYQA manually, you can test your installation using the pytest package: .. code-block:: bash - $ python setup.py test + $ pip install pytest + $ python -m pytest --pyargs pybobyqa Uninstallation -------------- diff --git a/docs/userguide.rst b/docs/userguide.rst index 87a9ae8..b88d30e 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -14,7 +14,7 @@ Py-BOBYQA is designed to solve the local optimization problem where the bound constraints :math:`a \leq x \leq b` are optional. The upper and lower bounds on the variables are non-relaxable (i.e. Py-BOBYQA will never ask to evaluate a point outside the bounds). The objective function :math:`f(x)` is usually nonlinear and nonquadratic. If you know your objective is linear or quadratic, you should consider a solver designed for such functions (see `here `_ for details). Py-BOBYQA iteratively constructs an interpolation-based model for the objective, and determines a step using a trust-region framework. -For an in-depth technical description of the algorithm see the paper [CFMR2018]_, and for the global optimization heuristic, see [CRO2018]_. +For an in-depth technical description of the algorithm see the paper [CFMR2018]_, and for the global optimization heuristic, see [CRO2022]_. How to use Py-BOBYQA -------------------- @@ -402,12 +402,12 @@ The output of this is: Warning (max evals): Objective has been called MAXFUN times ****************************** -As we can see, the :code:`seek_global_minimum` flag helped Py-BOBYQA escape the local minimum from the first run, and find the global minimum. More details are given in [CRO2018]_. +As we can see, the :code:`seek_global_minimum` flag helped Py-BOBYQA escape the local minimum from the first run, and find the global minimum. More details are given in [CRO2022]_. References ---------- .. [CFMR2018] Coralia Cartis, Jan Fiala, Benjamin Marteau and Lindon Roberts, `Improving the Flexibility and Robustness of Model-Based Derivative-Free Optimization Solvers `_, *ACM Transactions on Mathematical Software*, 45:3 (2019), pp. 32:1-32:41 [`preprint `_] -.. [CRO2018] - Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization* (2021). [`preprint `_] +.. [CRO2022] + Coralia Cartis, Lindon Roberts and Oliver Sheridan-Methven, `Escaping local minima with derivative-free methods: a numerical investigation `_, *Optimization*, 71:8 (2022), pp. 2343-2373. [`arXiv preprint: 1812.11343 `_]