Public API of high-level interfaces to PRIMA

[zaikunzhang]

This is related to
#183
libprima/PRIMA.jl#29

The public API of a high-level interface to PRIMA can be one of the three:

1. Provide a single function prima, and make the individual solvers available with an option/argument solver (used in MATLAB) or method (used in SciPy).
2. Provide five individual solvers lincoa etc.
3. Provide both prima and the five individual solvers.

The Python binding takes 1, PRIMA.jl currently takes option 2, and the MATLAB interface chose 3, which is inherited from PDFO.

According to my 4-plus-year experience working on PRIMA and PDFO (the predecessor of PRIMA), 1 is ideal, 2 is OK, and 3 is wrong.

Let me first explain why option 3 is wrong: prima and lincoa correspond to two different abstraction levels, and hence it is radically wrong to expose both of them to the end users. For example, both prima and the user can call lincoa, which leads to unnecessarily complicated logic in the code. This is a bitter lesson learned from PDFO and the current MATLAB binding.

Option 2 is much better than option 3, because its logic is simpler. All the functions exposed to the end users in parallel to each other, lying on the same level of abstraction.

Option 1 is the best. It provides a simple and uniform interface to all solvers. It reduces the burden of maintaining the public API, which contains only one function. In addition, it avoids code repetition when we need to do preprocessing and postprocessing.

For these reasons, PDFO has deprecated calling the individual solvers directly, and it now supports only calling the solvers via the uniform interface called pdfo. The MATLAB binding of PRIMA will do the same, switching from option 3 to option 1.