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

josef.pktd@gmai... josef.pktd@gmai...
Fri Mar 19 15:58:17 CDT 2010


On Fri, Mar 19, 2010 at 4:51 PM, David Goldsmith
<d.l.goldsmith@gmail.com> wrote:
> On Fri, Mar 19, 2010 at 1:09 PM,  <josef.pktd@gmail.com> wrote:
>> On Fri, Mar 19, 2010 at 4:05 PM, David Goldsmith
>> <d.l.goldsmith@gmail.com> wrote:
>>> 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?
>>
>> 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
>> docs.
>
> 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).

Sorry if I was ambiguous, my initial statement was about the specific
case of the fmin, not reflecting an opinion about a general policy.

I agree we have to check case by case. my "bug in docs" is for this case only

Josef

>>
>> 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.
>>
>> Josef
>
> Agreed: the most robust behavior it to allow specification of both
> types of tolerance.
>
> DG
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>


More information about the SciPy-Dev mailing list