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

[Ralf Gommers]

On Fri, Aug 2, 2013 at 7:19 PM, Nathan Woods <charlesnwoods at gmail.com>wrote:

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

My first instinct was that nquad should match what's already there in
scipy.integrate, but I've changed my mind. I always have to look at the
dblquad/tplquad documentation to get it right, so those functions don't
have a good API imho. Therefore just making nquad do the logical thing
(i.e. ``f(x, y ,z)``) makes sense to me.

Let's not use the word "deprecate" for dblquad/tplquad, since they
shouldn't be removed. Instead just recommend `nquad` as the function to use
in the docs.

Any other opinions?

Ralf


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.
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20130805/0b44f007/attachment.html>