MATLAB

Prerequisites

PDFO supports MATLAB R2014a and later releases. To use the MATLAB version of PDFO, you need first to configure the MEX of your MATLAB so that it can compile Fortran. To check whether your MEX is ready, run the following code in MATLAB:

mex('-v', '-setup', 'Fortran'); mex('-v', fullfile(matlabroot, 'extern', 'examples', 'refbook', 'timestwo.F')); timestwo(1); delete('timestwo.mex*'); 

It will attempt to set up your MEX and then compile an example provided by MathWorks for testing MEX on Fortran. If this completes successfully, then your MEX is ready. Otherwise, it is not. To configure MEX for compiling Fortran, see the official documentation of MathWorks. It will require you to install a supported Fortran compiler on your system. Note that MathWorks (rather than PDFO) is quite rigid concerning the version of your compiler, which has to be compatible with the release of your MATLAB; the latest compiler is not necessarily supported by your MATLAB. On Windows, MathWorks needs you to install also Microsoft Visual Studio and Microsoft Windows SDK. Follow the official documentation closely.

Installation

Download and decompress the source code package. You will obtain a folder containing setup.m. Place this folder at the location where you want PDFO to be installed. In MATLAB, change the directory to this folder, and execute the following command:

setup

If this command runs successfully, PDFO is installed. You may execute the following command in MATLAB to verify the installation:

testpdfo

Python

Recommended installation

To use the Python version of PDFO on Linux, Mac, or Windows, you need Python 3.7 or above.

We highly recommend installing PDFO via PyPI. This does not need you to download the source code. Install pip in your system. Then execute

python -m pip install pdfo

in a command shell (e.g., the terminal in Linux or Mac, or the Command Shell for Windows). If your Python launcher is not python, adapt the command accordingly. If this command runs successfully, PDFO is installed. You may verify the installation by

python -m unittest pdfo.testpdfo

If you are an Anaconda user, PDFO is also available through the conda installer. However, it is not managed by us.

Alternative installation (using source distribution)

Alternatively, although deeply discouraged, PDFO can be installed from the source code. It requires you to install additional Python headers, a Fortran compiler (e.g., gfortran), and F2PY (provided by NumPy). Download and decompress the source code package; you will obtain a folder containing setup.py; in a command shell, change your directory to this folder, and then run python -m pip install ./ to install PDFO.

MATLAB

PDFO provides the following MATLAB functions: pdfo, uobyqa, newuoa, bobyqa, lincoa, and cobyla.

The pdfo function can automatically identify the type of your problem and then call one of Powell's Fortran solvers. The other five functions call the solver indicated by their names. It is highly recommended to use pdfo instead of uobyqa, newuoa, etc.

The pdfo function is designed to be compatible with the fmincon function available in the Optimization Toolbox of MATLAB. You can call pdfo in the same way as calling fmincon. In addition, pdfo can be called in some flexible ways that are not supported by fmincon, which will be illustrated in the example below.

For the detailed syntax of these functions, use the standard help command of MATLAB. For example,

help pdfo

will tell you how to use the pdfo function.

An example

The following code illustrates how to minimize the chained Rosenbrock function $$\sum_{i=1}^2 [(x_i - 1)^2 + 4(x_{i+1} - x_i^2)^2]$$ subject to various constraints.

Options

When calling pdfo, we may specify some options by passing a structure to pdfo as the last input. Here are several useful options.

1. solver: a string indicating which solver to use; default: 'uobyqa' for unconstrained problems with at most 8 variables, 'newuoa' for unconstrained problems with 9 or more variables, 'bobyqa' for bound-constrained problems, 'lincoa' for linearly constrained problems, and 'cobyla' for nonlinearly constrained problems. If you want to choose a solver, note that UOBYQA and NEWUOA can solve unconstrained problems, NEWUOA being preferable except for rather small problems; BOBYQA can solve unconstrained and bound-constrained problems; LINCOA can solve unconstrained, bound-constrained, and linearly constrained problems; COBYLA can solve general nonlinear optimization problems. We observe that LINCOA sometimes outperforms NEWUOA on unconstrained problems. It is also worth noting that BOBYQA evaluates the objective function only at feasible points, while LINCOA and COBYLA may explore infeasible points.
2. maxfun: maximal number of function evaluations; default: 500*length(x0).
3. ftarget: target function value; pdfo terminates once it finds a feasible point with a function value at most ftarget; default: -inf.
4. scale: a boolean value indicating whether to scale the problem according to bound constraints; if it is true and if all the variables have both lower and upper bounds, then the problem will be scaled so that the bound constraints become \(-1 \leq x \le 1\); default: false.
5. rhobeg: initial trust-region radius; typically, rhobeg should be in the order of one tenth of the greatest expected change to a variable; rhobeg should be positive; default: 1 if the problem will not be scaled, and 0.5 if the problem will be scaled; in case of scaling, rhobeg will be used as the initial trust-region radius of the scaled problem.
6. rhoend: final trust-region radius; rhoend reflects the precision of the approximate solution obtained by pdfo; rhoend should be positive and not larger than rhobeg; default: 1e-6; in case of scaling, rhoend will be used as the final trust-region radius of the scaled problem.

For instance, to minimize the aforementioned chained Rosenbrock function without constraints by LINCOA with at most \(50\) function evaluations and a target function value \(10^{-2}\), it suffices to replace pdfo(@chrosen, x0) in the above example by

pdfo(@chrosen, x0, struct('solver', 'lincoa', 'maxfun', 50, 'ftarget', 1e-2))

Python

PDFO provides the following Python functions: pdfo, uobyqa, newuoa, bobyqa, lincoa, and cobyla.

The pdfo function can automatically identify the type of your problem and the call one of Powell's solvers. The other five functions call the solver indicated by their names. It is highly recommended to use pdfo instead of uobyqa, newuoa, etc.

The pdfo function is designed to be compatible with the minimize function available in the scipy.optimize module of SciPy. You can call pdfo in exactly the same way as calling minimize except that pdfo does not accept derivative arguments.

For detailed syntax of these functions, use the standard help command of Python. For example,

 from pdfo import pdfo; help(pdfo)

will tell you how to use pdfo.

An example

The following code illustrates how to minimize the chained Rosenbrock function defined above subject to various constraints.

Method and options

When using pdfo, we may specify the solver by passing a string to the keyword argument named method. Otherwise, pdfo will choose the solver in the same way as the MATLAB version does.

In addition, options may be specified by passing a dictionary to the keyword argument named options. Useful options include maxfev, ftarget, scale, rhobeg, and rhoend, who are identical to the options for the MATLAB version with the same names, except that the maximal number of function evaluations is named maxfev to align with the minimize function in scipy.optimize.

For instance, to minimize the aforementioned chained Rosenbrock function without constraints by LINCOA with at most \(50\) function evaluations and a target function value \(10^{-2}\), it suffices to replace pdfo(chrosen, x0) in the above example by

pdfo(chrosen, x0, method='lincoa', options={'maxfev': 50, 'ftarget': 1e-2})