[SciPy-User] Flaws in fmin_cobyla

[Robaula]

On Sep 26, 2012, at 12:57 AM, scipy-user-request at scipy.org Denis Laxalde wrote:
> Robaula a ?crit :
>> 1. The routine returns only the optimal argument value. No description of the status at the end of the run, such as would be provided by the "Results" class are included. Consequently the user receives no information on the trustworthiness of the returned value.
> 
> You mean `fmin_cobyla`, I guess. See answer to point 4.
> 
>> 2. Although "disp" and "iprint" are among the options in cobyla's calling signature, assigning different values to them has absolutely no effect on the output.
> 
> This is documented. `disp` overrides `iprint`, which is deprecated.

Sorry, the documentation is flat wrong. Both disp and iprint are completely, utterly, and totally ignored. See fmin_cobyla line 165.

>> 3. The docstring's Examples section mentions several values that would be included in the "Results", but with no indication of where they come from or how the users could get at them.
> 
> Which docstring?
> Most of the information comes from the internal solver.
> As mentioned in its docstring, `Result` is a subclass of `dict` with 
> attribute accessors. You may then access attributes with a dot notation 
> or as a regular dict.

I guess we're reading the same documentation, specifically the SciPy Reference Guide of 05 June 2012, pages 401-403, and the fmin_cobyla docstrings.

>> 4. The cobyla routine calls the _minimize_cobyla routine, which prepares and returns the "Results" class information. This includes: the optimal value of the argument, the status at end, the success flag value, a message expressing the success flag in English, the optimal value of the function, and the maximum constraint violation. Then the cobyla routine "throws away" all but the first of these values. That occurs because after the cobyla routine receives the "Results" dictionary of values from _minimize_cobyla, it returns, in effect, "Results['x']", i.e., just the "Results" dictionary entry for key 'x'.  This is done in line 165 of the cobyla routine.
> 
> The `Result` object was introduced recently, for the `minimize` 
> interface. It is not returned by `fmin_cobyla` for backwards 
> compatibility. If you want the full results, use `minimize(..., 
> method='cobyla', ...)`.
> 
> The old `fmin_` functions and the new `minimize` interface are present 
> in the 0.11 release, which is good for transition purpose but is also 
> confusing. We could deprecated the former in the next release I guess.

Then I guess we'd have to deprecate nearly all of the optimize and root-finding stuff mentioned in the SciPy Reference Guide on pages 388-442?? I note that Ralf Gomers thinks we should find a better way. Cleaning up the fmin_cobyla documentation can certainly be a start on that, and I'll take that on. 

However, I think there other, and more important issues here, namely, "How should the new 'minimize' interfaces be documented? How should existing documentation for the "old" interfaces be changed in light of the new 'minimize' approach? How to bring the two of them more nearly into alignment? Are changes to the documentation standards advisable to facilitate this?" Sure, "minimize's" docstring is an excellent start, tho I do see a couple areas where a little more explanation and/or some examples would be helpful. Among other things, I think it would be a lot better to just come out and tell folks what options are available for each of the various "methods", rather than telling them the code sequence to use to view them. Certainly the cobyla options for 'minimize'  differ noticeably from those for the fmin_cobyla approach. For example, using fmin_cobyla ignores disp and iprint and never returns 'Results', while using 'minimize' has no iprint option, ignores the disp option, and always returns 'Results'.

I'd welcome good ideas on how best to document the new 'minimize' interface, and how best to coordinate that with the "old style" method documentation. I'm not looking for ideas that are merely the programmer's personal reminders--the current documentation is just fine for that! Instead, I'm looking for documentation suitable for use by folks who might be described as: first year grad students just slightly familiar with Python who have a one week deadline to solve their problem and desperately need _very_ clear, unambiguous, and detailed instructions on exactly how to proceed. Try to remember _your_ first year grad experiences!!