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

Adam Former at physicist.net
Thu Oct 26 21:26:18 EDT 2017 

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/blo
b/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 
> > om> 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: ht
> > > tps://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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20171026/b2625ed7/attachment-0001.html>

More information about the SciPy-Dev mailing list