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

Fri Oct 27 16:56:49 EDT 2017

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/gener
ated/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 h
ttps://books.google.com/books/about/Computation_of_special_functions.ht
ml?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
> > 
> > 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171027/33886af4/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/33886af4/attachment-0001.png>