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

Fri Oct 20 21:23:01 EDT 2017

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: http
> > s://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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171020/3bb004ed/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: AB_Integer_Formulas.pdf
Type: application/pdf
Size: 88033 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171020/3bb004ed/attachment-0001.pdf>