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

[josef.pktd at gmail.com]

On Mon, Aug 5, 2013 at 4:24 PM, Ralf Gommers <ralf.gommers at gmail.com> wrote:
>
>
>
> 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?

How do you know the integration order in the new interface?

The current dblquad, tplquad looks to me like writing an integral

integral_x integral_y integral_z  func3d(z, y,x)  dz dy dz
where integration limits are x=a..b, y=gfun(x)..hfun(x), and
z=qfun(x,y)..rfun(x,y)

based on reading of the docstrings for tplquad. So this doesn't look
very strange to me.

The suggested description
``
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.
```

Does this mean we integrate over x0 first (innermost integral) or last
(outermost integral) ?

But I never used either function, so I could get used to both if the
docstring is clear.

Josef


>
> 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
>>
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>