<html><head></head><body><div>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." </div><div><br></div><div>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...</div><div><br></div><div>--Adam</div><div><br></div><div>On Fri, 2017-10-20 at 08:54 -0400, josef.pktd@gmail.com wrote:</div><blockquote type="cite"><div dir="ltr"><div>One possibility:</div><div>Currently the only more extensive Latex based documentation is in the tutorial.</div><div>I think it would be possible to add a technical appendix or something like that</div><div>to the scipy.special tutorial, a bit similar to the distributions formulas attached to the </div><div>stats tutorial.</div><div><br></div><div>For example Boost, last time I checked, had long documentation for the special</div><div>functions, which might be too long to fit in docstrings.</div><div><br></div><div>I don't know how much there would be for special functions and whether it is </div><div>difficult to maintain those notes. However, I think it would be good to have</div><div>notes that developers have already written available for future</div><div>developers and users that are interested in technical details.</div><div><br></div><div><br></div><div>Josef</div><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Oct 20, 2017 at 2:01 AM, Ralf Gommers <span dir="ltr"><<a href="mailto:ralf.gommers@gmail.com" target="_blank">ralf.gommers@gmail.com</a>></span> wrote:<br><blockquote type="cite"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On Thu, Oct 19, 2017 at 8:04 PM, Ted Pudlik <span dir="ltr"><<a href="mailto:tpudlik@gmail.com" target="_blank">tpudlik@gmail.com</a>></span> wrote:<br><blockquote type="cite"><div dir="ltr">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 <a href="https://github.com/scipy/scipy/blob/8a994cac55f6ec5d4279d9910ac3cee9f5c6a2be/scipy/special/add_newdocs.py#L3367" target="_blank">docstring</a>. The LaTeX will render in the HTML version of the documentation (<a href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.jv.html#scipy.special.jv" target="_blank">example</a>). I'm not sure how the maintainers feel about this, though (this is just a suggestion from a "private citizen").<br></div><br></blockquote><div><br></div></span><div>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.</div><div><br></div><div>Here's a recent PR with discussion about various LaTeX styles: <a href="https://github.com/scipy/scipy/pull/7756" target="_blank">https://github.com/scipy/<wbr>scipy/pull/7756</a>. The style that got merged is about right.</div><div><br></div><div>Cheers,<br></div><div>Ralf</div><div><div class="h5"><div><br></div><blockquote type="cite"><div dir="ltr"><br><br></div><div class="m_4151375736252460884gmail-HOEnZb"><div class="m_4151375736252460884gmail-h5"><br><div class="gmail_quote"><div dir="ltr">On Thu, Oct 19, 2017 at 11:59 AM Adam <<a href="mailto:Former@physicist.net" target="_blank">Former@physicist.net</a>> wrote:<br></div><blockquote type="cite">Okay cool; thanks for the helpful reply!<br>
<br>
I'll look at Gosper's method and see how it compares with Buhring's method.<br>
For now I'll plan on doing a PR that implements one of these two methods. I<br>
was just worried that I might end up doing a lot of work on a PR that<br>
implements Buhring's series only to have a reviewer reject it saying "Well,<br>
you should have used such-and-such's algorithm which is must faster, much<br>
more accurate, etc."<br>
<br>
I'll also hold off on adding a latex doc to the repo of the actual formulas<br>
used for the b-a=integer special case (unless I hear otherwise).<br>
<br>
Thanks again!<br>
<br>
--Adam<br>
<br>
-----Original Message-----<br>
From: Joshua Wilson<br>
Sent: Thursday, October 19, 2017 9:35 AM<br>
To: SciPy Developers List<br>
Subject: Re: [SciPy-Dev] Fixing a bug with scipy's hypergeometric function<br>
hyp2f1<br>
<br>
Hey Adam,<br>
<br>
> Does this sound like a worthwhile PR?<br>
<br>
Yes, definitely<br>
<br>
> Does the implementation sound reasonable?<br>
<br>
It's been a while since I've thought about this, but if I recall<br>
correctly the problematic region you've found is one that comes up<br>
quite frequently--see e.g. page 14 in<br>
<br>
<a href="http://fredrikj.net/math/hypgeom.pdf" rel="noreferrer" target="_blank">http://fredrikj.net/math/hypge<wbr>om.pdf</a><br>
<br>
Floating around in the ether is a method credited to Bill Gosper for<br>
handling that region which also uses a recurrence relation (maybe<br>
related to/the same as in the paper you cited)? I can never seem to<br>
find the original reference (dead link), but I've attached someone's<br>
writeup of it.<br>
<br>
So, your implementation sounds reasonable, but if you really want to<br>
dig into it you could check out the Gosper stuff and see how they<br>
compare.<br>
<br>
> Can the PR implement formulas/methods that don't appear in the literature?<br>
> Is it going to be a problem if I implement this limit case in the PR?<br>
<br>
It's implicit in the literature, so I think it's fine.<br>
<br>
> I don't what reference I would place hyp2f1's doc string<br>
<br>
The Buhring paper. The formula is something that an informed reader<br>
could figure out after reading it.<br>
<br>
> I would be wiling to maybe add a latex doc to the PR (placed somewhere in<br>
> the doc folder?)<br>
<br>
If I recall correctly people were opposed to adding LaTeX docs. (But<br>
maybe I recall incorrectly; if so please someone correct me.) I also<br>
have various special function write ups that might be handy for future<br>
devs... maybe in a separate repo?<br>
<br>
On Wed, Oct 18, 2017 at 6:47 PM, Adam <<a href="mailto:Former@physicist.net" target="_blank">Former@physicist.net</a>> wrote:<br>
> Hello guys,<br>
><br>
> I've found a small region in the complex plane where scipy's<br>
> implementation<br>
> of the hypergeometric function hyp2f1 fails. I've documented this error in<br>
> issue 8054 on github.<br>
><br>
> I am willing to submit a PR that fixes this issue. My PR would basically<br>
> implement the analytic continuation formula given in this paper: (Buhring,<br>
> An Analytic Continuation of the Hypergeometric Series). I've already<br>
> implemented this series in some prototype code written in Fortran and it<br>
> agrees well with the values returned by mpmath's implementation of hyp2f1.<br>
><br>
> Before I attempt a PR, I just wanted to touch base and ask the group the<br>
> following:<br>
><br>
> 1) Does this sound like a worthwhile PR? The failure region is somewhat<br>
> small and I don't know with what urgency people would want this fixed.<br>
><br>
> 2) Does the implementation sound reasonable? My background is physics and<br>
> so<br>
> I haven't done a complete literature search looking for the *fastest*<br>
> algorithm. All I can say that the Buhring's formula works and my<br>
> implementation only seems to be about %50 slower than the current hyp2f1<br>
> (at<br>
> points in the complex plane where both methods converge). I would only<br>
> apply<br>
> Buhring's series in the region where hyp2f1 currently diverges.<br>
><br>
> 3) Can the PR implement formulas/methods that don't appear in the<br>
> literature? Buhring's paper *only* gives the analytic continuation for the<br>
> case where the difference between the a/b parameters is NOT an integer.<br>
> When<br>
> a-b=m, the limit case of his series can be derived using a method<br>
> described<br>
> in "The Special Functions and Their Approximations" by Y. Luke (as Buhling<br>
> mentions in his paper). I've derived the formula for this limit case and<br>
> have an implementation of it that produces values in agreement with<br>
> mpmath.<br>
> Is it going to be a problem if I implement this limit case in the PR? I<br>
> ask<br>
> because I don't what reference I would place hyp2f1's doc string. I would<br>
> be<br>
> wiling to maybe add a latex doc to the PR (placed somewhere in the doc<br>
> folder?) that contains the formula so that future scipy devs have<br>
> something<br>
> to reference when reviewing hyp2f1's source code.<br>
><br>
> Anyways, let me know if my idea for a PR sounds like a good idea! I<br>
> apologize for the longish email, but this is my first time trying to<br>
> contribute to scipy...<br>
><br>
> --Adam<br>
><br>
> ______________________________<wbr>_________________<br>
> SciPy-Dev mailing list<br>
> <a href="mailto:SciPy-Dev@python.org" target="_blank">SciPy-Dev@python.org</a><br>
> <a href="https://mail.python.org/mailman/listinfo/scipy-dev" rel="noreferrer" target="_blank">https://mail.python.org/mailma<wbr>n/listinfo/scipy-dev</a><br>
><br>
<br>
<br>
<br>
<br>
<br>
<br>
______________________________<wbr>_________________<br>
SciPy-Dev mailing list<br>
<a href="mailto:SciPy-Dev@python.org" target="_blank">SciPy-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/scipy-dev" rel="noreferrer" target="_blank">https://mail.python.org/mailma<wbr>n/listinfo/scipy-dev</a><br>
<br>
______________________________<wbr>_________________<br>
SciPy-Dev mailing list<br>
<a href="mailto:SciPy-Dev@python.org" target="_blank">SciPy-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/scipy-dev" rel="noreferrer" target="_blank">https://mail.python.org/mailma<wbr>n/listinfo/scipy-dev</a><br>
<br></blockquote></div>
</div></div><br>______________________________<wbr>_________________<br>
SciPy-Dev mailing list<br>
<a href="mailto:SciPy-Dev@python.org" target="_blank">SciPy-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/scipy-dev" rel="noreferrer" target="_blank">https://mail.python.org/mailma<wbr>n/listinfo/scipy-dev</a><br>
<br></blockquote></div></div></div><br></div></div>
<br>______________________________<wbr>_________________<br>
SciPy-Dev mailing list<br>
<a href="mailto:SciPy-Dev@python.org">SciPy-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/scipy-dev" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/listinfo/scipy-dev</a><br>
<br></blockquote></div><br></div></div>
<pre>_______________________________________________
SciPy-Dev mailing list
<a href="mailto:SciPy-Dev@python.org">SciPy-Dev@python.org</a>
<a href="https://mail.python.org/mailman/listinfo/scipy-dev">https://mail.python.org/mailman/listinfo/scipy-dev</a>
</pre></blockquote></body></html>