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

[Nathan Woods]

Clear documentation is always important, so I don't think there will be any problems there. Does anyone else have thoughts they'd like to share?

Nate

On Aug 5, 2013, at 11:35 PM, josef.pktd at gmail.com wrote:

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