[SciPy-Dev] Doc error in scipy.optimize.fmin and missing info in ref guide

[David Goldsmith]

On Fri, Mar 19, 2010 at 12:37 PM,  <josef.pktd@gmail.com> wrote:
> On Fri, Mar 19, 2010 at 3:16 PM, David Goldsmith
> <d.l.goldsmith@gmail.com> wrote:
>> On Mon, Mar 15, 2010 at 4:05 PM, Rob Clewley <rob.clewley@gmail.com> wrote:
>>> Hi,
>>>
>>> In both my old version and the one in the svn trunk there is an
>>> inconsistency in the docstring of scipy.optimize.fmin.
>>>
>>>    Other Parameters
>>>    ----------------
>>>    xtol : float
>>>        Relative error in xopt acceptable for convergence.
>>>    ftol : number
>>>        Relative error in func(xopt) acceptable for convergence.
>>>
>>> As you see from the following code snippet from the body of the
>>> function, the convergence test is in terms of absolute error for both
>>> x and f, as the sim array contains x values and fsim the function
>>> values.
>>>
>>>    if (max(numpy.ravel(abs(sim[1:]-sim[0]))) <= xtol \
>>>                and max(abs(fsim[0]-fsim[1:])) <= ftol):
>>>        break
>>
>> OK, folks, so what's the _desired_ behavior: absolute or relative
>> error (i.e., where's the bug: in the code or in the doc)?
>
> I think the docs should reflect the actual behavior of the function.
> Whether the criteria will be changed and made consistent across
> functions is a different question. But it's not a bug, so the docs
> should adjust.
>
> my opinion
>
> Josef

Well, I'm pretty sure we formally adopted the opposite policy: the
docs should reflect _desired_ behavior - if the code doesn't implement
desired behavior then a bug report is to be filed.  (I thought this
was in the Wiki Q&A section, but apparently not, so, UIAM, it's "only"
in an email thread somewhere).  Can anyone else confirm and,
hopefully, supply a link to the email thread in which this was
discussed?

DG