[SciPy-Dev] Fixing a bug with scipy's hypergeometric function hyp2f1

Adam Former at physicist.net
Fri Oct 27 19:50:49 EDT 2017 

Okay *that* worked! Thank you very much!
> > If _generate_ufuncs.py is in your repo then you aren't working with
> the master branch of SciPy. It was changed to _generate_pyx.py recently
> and is now run automatically as part of the build process. Make sure
> you update (or there will be a ton of merge conflicts when you submit
> the PR).
My repo actually does have _generate_pyx.py which is what I meant; I
copied _generate_ufuncs.py from the comment header of add_newdocs.py.
 In my PR, I'll change these comments so they refer to the new
_generate_pyx.py...
I'll also fix the reference to "Computation of Special Functions" in my
PR unless someone objects...
On Fri, 2017-10-27 at 16:46 -0500, Joshua Wilson wrote:
> > it appears I wasn't running _generate_ufuncs.py beforehand> 
> If _generate_ufuncs.py is in your repo then you aren't working with the master branch of SciPy. It was changed to _generate_pyx.py recently and is now run automatically as part of the build process. Make sure you update (or there will be a ton of merge conflicts when you submit the PR).> 

> > Is there a way of generating HTML that renders the latex equations?> 
> Maybe try make html-scipyorg. The first time you try it will probably complain that you are missing a git submodule, but it should also give instructions on how to fix that.> 

> > Is the 2nd author of the first reference misspelled> 
> Looks like it.

> On Fri, Oct 27, 2017 at 3:56 PM, Adam > <Former at physicist.net>>  wrote:
> > I figured it out and it appears I wasn't running _generate_ufuncs.py beforehand...
> > > > That said, the generated HTML still doesn't render my equations as a latex equation.  That is to say, my output looks like:
> > > > Is there a way of generating HTML that renders the latex equations? Like it appears on the https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.hyp2f1.html
> > > > Bonus question: Is the 2nd author of the first reference misspelled, i.e., Jjie [sic]?  Shouldn't the entire reference be:> > S. Zhang, J. Jin "Computation of Special Functions", Wiley, 1996? See https://books.google.com/books/about/Computation_of_special_functions.html?id=ASfvAAAAMAAJ

> > I can fix the first reference in my PR as well...

> > --Adam> > > > On Thu, 2017-10-26 at 20:52 -0500, Joshua Wilson wrote:
> > > > 
> > > > I do in fact get a bunch of html in the folders build/html, but the html for hyp2f1 doesn't contain my edits
> > > If I recall correctly, Sphinx doesn't detect changes in the `_ufuncs`
> > > extension module. Maybe try forcing a complete rebuild with `make
> > > SPHINXOPTS=-Ea html`.
> > > 
> > > On Thu, Oct 26, 2017 at 8:26 PM, Adam <Former at physicist.net> wrote:
> > > > 
> > > > Hey guys,
> > > > 
> > > > How do I view the html version of a functions docstring?  I've added my
> > > > Buhring reference to the docstring and I want to see how it renders in HTML.
> > > > 
> > > > I've tried both methods described in
> > > > https://github.com/scipy/scipy/blob/master/doc/README.txt but neither of
> > > > them worked.
> > > > 
> > > > When I try:
> > > > (scipy-dev) adam at adam-P7xxDM-G:~/scipy-> > > > dev/scipy$ python setup.py
> > > > build_sphinx
> > > > I get:
> > > > (...blah...blah...)
> > > > usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
> > > >  or: setup.py --help [cmd1 cmd2 ...]
> > > >  or: setup.py --help-commands
> > > >  or: setup.py cmd --help
> > > > error: invalid command 'build_sphinx'
> > > > 
> > > > When I try :
> > > > (scipy-dev) adam at adam-P7xxDM-G:~/scipy-> > > > dev/scipy/doc$ make html
> > > > 
> > > > I do in fact get a bunch of html in the folders build/html, but the html for
> > > > hyp2f1 doesn't contain my edits.  I've tried building html after
> > > > reinstalling my dev version of scipy, but that didn't change anything.
> > > > 
> > > > Thanks for any help!
> > > > 
> > > > --Adam
> > > > 
> > > > On Fri, 2017-10-20 at 18:23 -0700, Adam wrote:
> > > > 
> > > > I can certainly add the formulas to the doc string if that's what people
> > > > want.  My only concern is that the a-b=m case involves about a page of
> > > > formula's and would take a lot of space in the doc string (I've attached the
> > > > pdf from my latex file of the formulas). Originally I was thinking that the
> > > > docstring would just contain some reference to the pdf document, e.g., "See
> > > > the pdf at location X for the method used when a-b is an integer."
> > > > 
> > > > But like I said, I can put them wherever they need to go; I justed wanted to
> > > > make sure that future maintainers have some reference as to what the code is
> > > > trying to do...
> > > > 
> > > > --Adam
> > > > 
> > > > On Fri, 2017-10-20 at 08:54 -0400, josef.pktd at gmail.com wrote:
> > > > 
> > > > One possibility:
> > > > Currently the only more extensive Latex based documentation is in the
> > > > tutorial.
> > > > I think it would be possible to add a technical appendix or something like
> > > > that
> > > > to the scipy.special tutorial, a bit similar to the distributions formulas
> > > > attached to the
> > > > stats tutorial.
> > > > 
> > > > For example Boost, last time I checked, had long documentation for the
> > > > special
> > > > functions, which might be too long to fit in docstrings.
> > > > 
> > > > I don't know how much there would be for special functions and whether it is
> > > > difficult to maintain those notes. However, I think it would be good to have
> > > > notes that developers have already written available for future
> > > > developers and users that are interested in technical details.
> > > > 
> > > > 
> > > > Josef
> > > > 
> > > > 
> > > > On Fri, Oct 20, 2017 at 2:01 AM, Ralf Gommers <ralf.gommers at gmail.com>
> > > > wrote:
> > > > 
> > > > 
> > > > 
> > > > On Thu, Oct 19, 2017 at 8:04 PM, Ted Pudlik <tpudlik at gmail.com> wrote:
> > > > 
> > > > Concerning the actual formulas: there's a compromise between leaving them
> > > > implicit and creating a separate LaTeX doc.  You could add the formulas to
> > > > the docstring.  The LaTeX will render in the HTML version of the
> > > > documentation (example).  I'm not sure how the maintainers feel about this,
> > > > though (this is just a suggestion from a "private citizen").
> > > > 
> > > > 
> > > > In general: using LaTeX can be a good idea, the one thing that has to be
> > > > kept in mind is readability as plain text (important both for reading
> > > > docstrings in IPython terminal and when working on the code in an editor).
> > > > Best to add LaTeX formulas to the Notes section rather than in the first
> > > > sentences. And avoid usage of things like \left[ that make the rendered html
> > > > slightly prettier but the actual math much harder to read as plain text.
> > > > 
> > > > Here's a recent PR with discussion about various LaTeX styles:
> > > > https://github.com/scipy/scipy/pull/7756. The style that got merged is about
> > > > right.
> > > > 
> > > > Cheers,
> > > > Ralf
> > > > 
> > > > 
> > > > 
> > > > 
> > > > On Thu, Oct 19, 2017 at 11:59 AM Adam <Former at physicist.net> wrote:
> > > > 
> > > > Okay cool; thanks for the helpful reply!
> > > > 
> > > > I'll look at Gosper's method and see how it compares with Buhring's method.
> > > > For now I'll plan on doing a PR that implements one of these two methods.  I
> > > > was just worried that I might end up doing a lot of work on a PR that
> > > > implements Buhring's series only to have a reviewer reject it saying "Well,
> > > > you should have used such-and-such's algorithm which is must faster, much
> > > > more accurate, etc."
> > > > 
> > > > I'll also hold off on adding a latex doc to the repo of the actual formulas
> > > > used for the b-a=integer special case (unless I hear otherwise).
> > > > 
> > > > Thanks again!
> > > > 
> > > > --Adam
> > > > 
> > > > -----Original Message-----
> > > > From: Joshua Wilson
> > > > Sent: Thursday, October 19, 2017 9:35 AM
> > > > To: SciPy Developers List
> > > > Subject: Re: [SciPy-Dev] Fixing a bug with scipy's hypergeometric function
> > > > hyp2f1
> > > > 
> > > > Hey Adam,
> > > > 
> > > > > 
> > > > > Does this sound like a worthwhile PR?
> > > > Yes, definitely
> > > > 
> > > > > 
> > > > > Does the implementation sound reasonable?
> > > > It's been a while since I've thought about this, but if I recall
> > > > correctly the problematic region you've found is one that comes up
> > > > quite frequently--see e.g. page 14 in
> > > > 
> > > > http://fredrikj.net/math/hypgeom.pdf
> > > > 
> > > > Floating around in the ether is a method credited to Bill Gosper for
> > > > handling that region which also uses a recurrence relation (maybe
> > > > related to/the same as in the paper you cited)? I can never seem to
> > > > find the original reference (dead link), but I've attached someone's
> > > > writeup of it.
> > > > 
> > > > So, your implementation sounds reasonable, but if you really want to
> > > > dig into it you could check out the Gosper stuff and see how they
> > > > compare.
> > > > 
> > > > > 
> > > > > Can the PR implement formulas/methods that don't appear in the literature?
> > > > > Is it going to be a problem if I implement this limit case in the PR?
> > > > It's implicit in the literature, so I think it's fine.
> > > > 
> > > > > 
> > > > > I don't what reference I would place hyp2f1's doc string
> > > > The Buhring paper. The formula is something that an informed reader
> > > > could figure out after reading it.
> > > > 
> > > > > 
> > > > > I would be wiling to maybe add a latex doc to the PR (placed somewhere in
> > > > > the doc folder?)
> > > > If I recall correctly people were opposed to adding LaTeX docs. (But
> > > > maybe I recall incorrectly; if so please someone correct me.) I also
> > > > have various special function write ups that might be handy for future
> > > > devs... maybe in a separate repo?
> > > > 
> > > > On Wed, Oct 18, 2017 at 6:47 PM, Adam <Former at physicist.net> wrote:
> > > > > 
> > > > > Hello guys,
> > > > > 
> > > > > I've found a small region in the complex plane where scipy's
> > > > > implementation
> > > > > of the hypergeometric function hyp2f1 fails. I've documented this error in
> > > > > issue 8054 on github.
> > > > > 
> > > > > I am willing to submit a PR that fixes this issue. My PR would basically
> > > > > implement the analytic continuation formula given in this paper: (Buhring,
> > > > > An Analytic Continuation of the Hypergeometric Series). I've already
> > > > > implemented this series in some prototype code written in Fortran and it
> > > > > agrees well with the values returned by mpmath's implementation of hyp2f1.
> > > > > 
> > > > > Before I attempt a PR, I just wanted to touch base and ask the group the
> > > > > following:
> > > > > 
> > > > > 1) Does this sound like a worthwhile PR? The failure region is somewhat
> > > > > small and I don't know with what urgency people would want this fixed.
> > > > > 
> > > > > 2) Does the implementation sound reasonable? My background is physics and
> > > > > so
> > > > > I haven't done a complete literature search looking for the *fastest*
> > > > > algorithm. All I can say that the Buhring's formula works and my
> > > > > implementation only seems to be about %50 slower than the current hyp2f1
> > > > > (at
> > > > > points in the complex plane where both methods converge). I would only
> > > > > apply
> > > > > Buhring's series in the region where hyp2f1 currently diverges.
> > > > > 
> > > > > 3) Can the PR implement formulas/methods that don't appear in the
> > > > > literature? Buhring's paper *only* gives the analytic continuation for the
> > > > > case where the difference between the a/b parameters is NOT an integer.
> > > > > When
> > > > > a-b=m, the limit case of his series can be derived using a method
> > > > > described
> > > > > in "The Special Functions and Their Approximations" by Y. Luke (as Buhling
> > > > > mentions in his paper). I've derived the formula for this limit case and
> > > > > have an implementation of it that produces values in agreement with
> > > > > mpmath.
> > > > > Is it going to be a problem if I implement this limit case in the PR? I
> > > > > ask
> > > > > because I don't what reference I would place hyp2f1's doc string. I would
> > > > > be
> > > > > wiling to maybe add a latex doc to the PR (placed somewhere in the doc
> > > > > folder?) that contains the formula so that future scipy devs have
> > > > > something
> > > > > to reference when reviewing hyp2f1's source code.
> > > > > 
> > > > > Anyways, let me know if my idea for a PR sounds like a good idea! I
> > > > > apologize for the longish email, but this is my first time trying to
> > > > > contribute to scipy...
> > > > > 
> > > > > --Adam
> > > > > 
> > > > > ______________________________> > > > > _________________
> > > > > SciPy-Dev mailing list
> > > > > SciPy-Dev at python.org
> > > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > > 
> > > > 
> > > > 
> > > > 
> > > > 
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > 
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > > 
> > > > ______________________________> > > > _________________
> > > > SciPy-Dev mailing list
> > > > SciPy-Dev at python.org
> > > > https://mail.python.org/mailman/listinfo/scipy-dev
> > > > 
> > > ______________________________> > > _________________
> > > SciPy-Dev mailing list
> > > SciPy-Dev at python.org
> > > https://mail.python.org/mailman/listinfo/scipy-dev

> > ______________________________> > _________________
> > 
> > SciPy-Dev mailing list
> > 
SciPy-Dev at python.org
> > 
https://mail.python.org/mailman/listinfo/scipy-dev
> > 



> _______________________________________________
> SciPy-Dev mailing list
> 
SciPy-Dev at python.org> 
https://mail.python.org/mailman/listinfo/scipy-dev> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171027/afc6eae7/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: unknown-WJZT8Y
Type: image/png
Size: 86595 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171027/afc6eae7/attachment-0001.png>

More information about the SciPy-Dev mailing list