[SciPy-Dev] Discussion on a new interface for multidimensional quadrature

[Nathan Woods]

I'm copying the most relevant parts over from a discussion on GitHub, having to do with a new n-dimensional integration tool. The discussion is whether or not to make nquad's new interface consistent with dbl-and tplquad, even though their precedent is arguably more confusing to users.

nquad is a recursively defined wrapper to scipy.integrate.quad that allows for n-dimensional integration with almost the entire list of arguments allowed by quad. It is therefore more general than either dbl- or tplquad, and encompasses their use cases, while allowing the user greater control over the integration. The interface is given: nquad( f(x0,x1,…xn,t0,…tm) ,[[x0_lo,x0_hi],…[xn_lo,xn_hi]],[t0,…tm],[opts0,…optsn]).
The ranges of integration are given in the same order as the arguments in the function to be integrated. This ordering is consistent with both Matlab and Octave, and it is similar to what is encountered in other SciPy packages such as fft. It is also what makes sense to new users. 

dbl- and tplquad, however, reverse the order of arguments in f. From the documentation for tplquad:

Return the triple integral of func(z, y, x) from x=a..b, y=gfun(x)..hfun(x), and z=qfun(x,y)..rfun(x,y)

This is confusing, and contrary to common practice.

It is proposed that nquad's calling sequence be left as is, and that the use of dbl- and tplquad be deprecated in some future version of SciPy, and that nquad be recommended for multidimensional integration in new code. dbl- and tplquad would of course be retained, though not recommended, in order to avoid breaking existing code.

Wow, that came out all legalistic. Anyway, what do you all think about this change? I have a horse in the race (I wrote most of nquad), but I really think that maintaining the backwards style from dbl- and tplquad and enshrining it in new code is a bad idea. This is a perfect time to get away from it, if that's what we want to do.

> Good question. I think this needs some discussion on the scipy-dev list, because it would be a fairly large change (dblquad/tplquad are old and widely used I think). Could you please bring it up there?
> 
>> Yeah, I remember wondering how to handle that. It's not a very difficult fix, and most of the work will be in changing over the examples and tests so they work with the new ordering. However, do we really want to stick with the old order? 
>> 
>> If we want to change it, then now is a perfect time, since nquad duplicates and extends the functionality of dbl- and tplquad. Those two could be deprecated and retained for compatibility, while nquad is recommended for new code. Since the calling sequence for nquad is so different, new users will have to adjust anyway.
>> 
>> The current argument list for tplquad is confusing. The order of arguments in the function does not match with the order of the range functions that must be provided, which is a source of confusion. The ordering was presumably chosen to make things look as much like quad as possible, but is that really important now?
>> 
>> As a reference, Matlab's integral3 and triplequad and GNU Octave's triple quad both order things (x,y,z). SciPy's fft2 also appears to do things the same way.
> 
>>> There's one thing that needs discussion: the integration order is reversed compared to dblquad and tplquad. Where you'd use def func3d(z, y, x) in tplquad you have to use def func3d(x, y, z) here. I was never a fan of the order in dbp/tplquad, but we're stuck with that and I thinknquad should use that same order for consistency.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20130802/440fbd0c/attachment.html>