[SciPy-Dev] Doc error in scipy.optimize.fmin and missing info in ref guide
Fri Mar 19 15:51:36 CDT 2010
On Fri, Mar 19, 2010 at 1:09 PM, <firstname.lastname@example.org> wrote:
> On Fri, Mar 19, 2010 at 4:05 PM, David Goldsmith
> <email@example.com> wrote:
>> On Fri, Mar 19, 2010 at 12:37 PM, <firstname.lastname@example.org> wrote:
>>> On Fri, Mar 19, 2010 at 3:16 PM, David Goldsmith
>>> <email@example.com> wrote:
>>>> On Mon, Mar 15, 2010 at 4:05 PM, Rob Clewley <firstname.lastname@example.org> wrote:
>>>>> 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
>>>>> if (max(numpy.ravel(abs(sim[1:]-sim))) <= xtol \
>>>>> and max(abs(fsim-fsim[1:])) <= ftol):
>>>> 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
>> 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
> I know of that policy, but there are a lot of mistakes in the docs,
> and I don't think we change the code to match the mistakes in the
No, of course not, but the idea is that a "mistake" in the doc is not
a mistake if in fact it documents the desired behavior (and thus the
real mistake is in the code, in which case we've basically agreed that
we _will_ change the code to match the doc; for better or worse, this
means that when "mistakes" are found in the docs - mistakes which in
fact may not be mistakes but only appear to be so because they don't
match code behavior - we will need to address them on a case-by-case
basis, such as is being done in this instance).
> But you can also file a ticket for changing and reviewing convergence criteria
OK, yours is a "vote" for "bug in the doc."
> I don't think relative (to what?) error makes much sense if x or f goes to zero.
Agreed: the most robust behavior it to allow specification of both
types of tolerance.
More information about the SciPy-Dev