[SciPy-dev] some problems with optimize.py docstrings

[dmitrey]

Alan G Isaac wrote:
> On Sun, 26 Aug 2007, dmitrey apparently wrote:
>   
>> So do you want me to commit the changes I done to svn right now, before 
>> tomorrow scipy 0.6 release? 
>>     
>
> You are talking *only* about documentation improvements,
> even though incomplete?  Is that right?  Then unless Jarrod
> objects, that seems OK.
>
>   
Despite I have add meaning of some input/output parameters, the 
optimize.py documentation still remains incomplete, because I don't know 
ALL parameters (from whole optimize.py) meaning. However, I still 
suppose that some enhancements is better than nothing at all, and others 
could be added by Travis and/or other authors of the file.
>   
>> 1) is (gc, fc) really equal to _ls_fc, _ls_gc? Maybe vise versa? 
>> As for me, I don't know what are those return params mean. 
>>     
>
> Did you try comparing to the related minpack routines?
>   
Ok, I have looked at some, but fortran routine has other input/output 
parameters
As for python code - seems like fc and gc are func and gradient 
counters, but I still don't know all other parameters meaning and why gc 
is always zero. Also, I still think in :Returns: gc and fc should be 
vise versa: fc and gc.
>> 2) documentation has the line 
>> "For the zoom phase it uses an algorithm by" (so what should be here?)
>>     
>
> Only Travis can say ...
>
>
>   
>> 3) Description misses meanings of amax, old_fval, old_old_fval (same to 
>> line_search_BFGS)
>>     
>
> Again, did you try comparing to the related minpack 
> routines?
>   
Minpack routines have other syntax (some parameters from linesearch.py 
are transformed to other parameters and only then passed to fortran 
code). Also, amax is used in minpack but not in python code (i.e. in 
optimize.py it's unused as I had mentioned).
>
>   
>>    if (phi_a0 <= phi0 + c1*alpha0*derphi0):
>>        return alpha0, fc, 0, phi_a0
>> #NOTE: 4 params instead of 3 ...  if (phi_a1 <= phi0 
>> + c1*alpha1*derphi0):
>>        return alpha1, fc, 0, phi_a1
>> #same: 4 params instead of 3 
>> ... 
>>        if (phi_a2 <= phi0 + c1*alpha2*derphi0):
>>            return alpha2, fc, 0, phi_a2
>> #same 
>>     
>
> Note that in every case, one of the parameters is 0.
>   
Maybe I misunderstood something in code and/or your answer, let me 
explain my suspection once again:
documentation to the func (line_search_BFGS) says:
:Returns: (alpha, fc, gc)

It doesn't explain what are those fc and gc. Also, according to the 
function code, it always returns 4 parameters, and if someone use
my_alpha, my_fc, my_gc = line_search_BFGS(...)
then he will always got my_gc = 0.
Is this really what it was intended to be?!
On the other hand, if gc is number of gradient evaluation, it seems to 
be true - as I noticed the code to line_search_BFGS didn't use gradient.
On the other hand, as I mentioned before, very unlikely that someone 
will use line_search and line_search_BFGS, they are intended for 
optimize.py inner usage.
Regards, D.