some problems with optimize.py docstrings
Hi all, unfortunately some days ago I had a problems with internet connection and that's why I didn't committed updated docstrings to optimize.py. That time I encountered some problems and that's why I switched to other tasks assigned to me, and forgot to do this one in-time. The problems that I mentioned are related to lack of documentation, and, moreover, to incorrect documentation. So, 1. def line_search(...) """... Outputs: (alpha, gc, fc) ...""" ... return alpha_star, _ls_fc, _ls_gc, fval_star, old_fval, fprime_star 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. 2) documentation has the line "For the zoom phase it uses an algorithm by" (so what should be here?) 3) Description misses meanings of amax, old_fval, old_old_fval (same to line_search_BFGS) 2. def line_search_BFGS(...) """... Outputs: (alpha, fc, gc)""" ... 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 So, as you see, 1) it has incorrect output - 4 values instead of 3 2) it doesn't describe what are those fc and gc 3) output gc is always equal to zero On the other hand, almost noone uses the funcs except some other funcs from optimize.py (elseware lots of tickets would be filed). The same to some other funcs from optimize.py (i.e. they are used only from other optimize.py funcs). So I suppose it could wait. Are you agree? So do you want me to commit the changes I done to svn right now, before tomorrow scipy 0.6 release? Let me attach to the letter links to optimize.py file as well as epydoc output. Regards, D. optimize.py http://www.box.net/shared/3bi5n8jtln html-file http://www.box.net/shared/0l44js08jj
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.
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?
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?
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. Cheers, Alan Isaac
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.
On 8/27/07, dmitrey <openopt@ukr.net> 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.
Hey Dmitrey, I would like to have your improvements to the docstrings for the optimization code included in the 0.6 release. They don't have to be complete as long as they are better than what we currently have. Thanks, Jarrod
Jarrod Millman wrote:
On 8/27/07, dmitrey <openopt@ukr.net> 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.
Hey Dmitrey,
I would like to have your improvements to the docstrings for the optimization code included in the 0.6 release. They don't have to be complete as long as they are better than what we currently have.
Thanks, Jarrod
Hi Jarrod, I don't know when 0.6 will be released, maybe I will commit the changes and some minutes later it will be already released - then it could turn out to have some problems. I mean: I didn't check how __docformat__="restructuredtext en" works, because if I put the line in start of optimize.py file my epydoc (v 2.1) says "unknown docformat" and stops. So maybe epydoc will just crush on optimize.py file. Also, I suppose that it would be better to clean optimize.py html output from all those auxiliary files like rosenbrock, but I don't know how to do this. Ok, so I committed it 1 min ago but it requires someone to check epydoc output (and maybe uncomment __docformat__="restructuredtext en" in the file head). Regards, D.
On 8/27/07, dmitrey <openopt@ukr.net> wrote:
I don't know when 0.6 will be released, maybe I will commit the changes and some minutes later it will be already released - then it could turn out to have some problems. I mean: I didn't check how __docformat__="restructuredtext en" works, because if I put the line in start of optimize.py file my epydoc (v 2.1) says "unknown docformat" and stops.
Before I tag the 0.6.0 release, I will first make a 0.6.x branch. I will ask for everyone to test the branch and then, if no one reports any problems, I will tag the release and start making binary packages. In short, you don't need to worry about making a change and then having the release come out a few minutes later.
So maybe epydoc will just crush on optimize.py file. Also, I suppose that it would be better to clean optimize.py html output from all those auxiliary files like rosenbrock, but I don't know how to do this.
Please commit your changes, so that I can see what you have done. If there are any problems, I can always revert the changes.
Ok, so I committed it 1 min ago but it requires someone to check epydoc output (and maybe uncomment __docformat__="restructuredtext en" in the file head).
I don't see your changes, so please try committing them again. Thanks for all your help. -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
Jarrod, I can't commit : Could not read status line: Connection reset by peer (http://svn.scipy.org) and my ping svn.scipy.org fails (already very long for now), either fix it if you can or maybe it will be better if you will download optimize.py from the location I had mentioned: http://www.box.net/shared/3bi5n8jtln I would attach the file to the letter but then I get "wait for moderator approvement" because letter exceeds max size 40 kb or kind of. Regards, D. Jarrod Millman wrote:
On 8/27/07, dmitrey <openopt@ukr.net> wrote:
I don't know when 0.6 will be released, maybe I will commit the changes and some minutes later it will be already released - then it could turn out to have some problems. I mean: I didn't check how __docformat__="restructuredtext en" works, because if I put the line in start of optimize.py file my epydoc (v 2.1) says "unknown docformat" and stops.
Before I tag the 0.6.0 release, I will first make a 0.6.x branch. I will ask for everyone to test the branch and then, if no one reports any problems, I will tag the release and start making binary packages. In short, you don't need to worry about making a change and then having the release come out a few minutes later.
So maybe epydoc will just crush on optimize.py file. Also, I suppose that it would be better to clean optimize.py html output from all those auxiliary files like rosenbrock, but I don't know how to do this.
Please commit your changes, so that I can see what you have done. If there are any problems, I can always revert the changes.
Ok, so I committed it 1 min ago but it requires someone to check epydoc output (and maybe uncomment __docformat__="restructuredtext en" in the file head).
I don't see your changes, so please try committing them again.
Thanks for all your help.
Hey Dmitrey, Looks like the server is down again. It should be back up in a few hours. You can just make the commits then. Thanks, Jarrod
participants (3)
-
Alan G Isaac -
dmitrey -
Jarrod Millman