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

Thu Aug 8 23:55:20 EDT 2013

How about adding an optional argument to nquad, specifying the order of
integration limits? Defaulting to the 'forward' order. Something like

nquad(f(x,y), [a, b], [g(x), h(x)])
being the default, and

nquad(f(x,y), [a, b], [g(y), h(y)], integration_order='reversed')
interpreting the limits the way dblquad/tplquad do.

Evgeni
On Aug 9, 2013 11:35 AM, "Nathan Woods" <charlesnwoods at gmail.com> wrote:

> 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
>
> _______________________________________________
> 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/20130809/016e1c88/attachment.html>