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

Thu Oct 26 21:52:17 EDT 2017

> 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
>