[SciPy-Dev] Discussion on a new interface for multidimensional quadrature
Tue Aug 6 00:35:45 CDT 2013
On Mon, Aug 5, 2013 at 4:24 PM, Ralf Gommers <email@example.com> wrote:
> On Fri, Aug 2, 2013 at 7:19 PM, Nathan Woods <firstname.lastname@example.org>
>> 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)
>> 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
> 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
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)
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.
>> 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 mailing list
More information about the SciPy-Dev