[Scipy-svn] r6401 - trunk/scipy/integrate
scipy-svn at scipy.org
scipy-svn at scipy.org
Mon May 24 09:09:36 EDT 2010
Author: rgommers
Date: 2010-05-24 08:09:36 -0500 (Mon, 24 May 2010)
New Revision: 6401
Modified:
trunk/scipy/integrate/quadpack.py
trunk/scipy/integrate/quadrature.py
Log:
DOC: merge wiki edits - integrate module.
Modified: trunk/scipy/integrate/quadpack.py
===================================================================
--- trunk/scipy/integrate/quadpack.py 2010-05-23 20:53:37 UTC (rev 6400)
+++ trunk/scipy/integrate/quadpack.py 2010-05-24 13:09:36 UTC (rev 6401)
@@ -9,6 +9,20 @@
error = _quadpack.error
def quad_explain(output=sys.stdout):
+ """
+ Print extra information about integrate.quad() parameters and returns.
+
+ Parameters
+ ----------
+ output : instance with "write" method
+ Information about `quad` is passed to ``output.write()``.
+ Default is ``sys.stdout``.
+
+ Returns
+ -------
+ None
+
+ """
output.write("""
Extra information for quad() inputs and outputs:
@@ -119,86 +133,95 @@
limit=50, points=None, weight=None, wvar=None, wopts=None, maxp1=50,
limlst=50):
"""
- quad(func, a, b, args=(), full_output=0, epsabs=1.4899999999999999e-08, epsrel=1.4899999999999999e-08, limit=50, points=None, weight=None, wvar=None, wopts=None, maxp1=50, limlst=50)
-
Compute a definite integral.
Integrate func from a to b (possibly infinite interval) using a technique
from the Fortran library QUADPACK.
+ If func takes many arguments, it is integrated along the axis corresponding
+ to the first argument. Use the keyword argument `args` to pass the other
+ arguments.
+
Run scipy.integrate.quad_explain() for more information on the
more esoteric inputs and outputs.
Parameters
- -----------
- func : function
- a Python function or method to integrate.
- a : float
- lower limit of integration (use -scipy.integrate.Inf for -infinity).
- b : float
- upper limit of integration (use scipy.integrate.Inf for +infinity).
- full_output :
- non-zero to return a dictionary of integration information.
- If non-zero, warning messages are also suppressed and the
- message is appended to the output tuple.
+ ----------
+ func : function
+ A Python function or method to integrate.
+ a : float
+ Lower limit of integration (use -scipy.integrate.Inf for -infinity).
+ b : float
+ Upper limit of integration (use scipy.integrate.Inf for +infinity).
+ args : tuple, optional
+ extra arguments to pass to func
+ full_output : int
+ Non-zero to return a dictionary of integration information.
+ If non-zero, warning messages are also suppressed and the
+ message is appended to the output tuple.
+
Returns
- -----------
+ -------
- y : float
- the integral of func from a to b.
- abserr : float
- an estimate of the absolute error in the result.
+ y : float
+ The integral of func from a to b.
+ abserr : float
+ an estimate of the absolute error in the result.
- infodict : dict
- a dictionary containing additional information.
- Run scipy.integrate.quad_explain() for more information.
- message :
- a convergence message.
- explain :
- appended only with 'cos' or 'sin' weighting and infinite
- integration limits, it contains an explanation of the codes in
- infodict['ierlst']
+ infodict : dict
+ a dictionary containing additional information.
+ Run scipy.integrate.quad_explain() for more information.
+ message :
+ a convergence message.
+ explain :
+ appended only with 'cos' or 'sin' weighting and infinite
+ integration limits, it contains an explanation of the codes in
+ infodict['ierlst']
Other Parameters
----------------
- epsabs :
- absolute error tolerance.
- epsrel :
- relative error tolerance.
- limit :
- an upper bound on the number of subintervals used in the adaptive
- algorithm.
- points :
- a sequence of break points in the bounded integration interval
- where local difficulties of the integrand may occur (e.g.,
- singularities, discontinuities). The sequence does not have
- to be sorted.
+ epsabs :
+ absolute error tolerance.
+ epsrel :
+ relative error tolerance.
+ limit :
+ an upper bound on the number of subintervals used in the adaptive
+ algorithm.
+ points :
+ a sequence of break points in the bounded integration interval
+ where local difficulties of the integrand may occur (e.g.,
+ singularities, discontinuities). The sequence does not have
+ to be sorted.
+ weight :
+ string indicating weighting function.
+ wvar :
+ variables for use with weighting functions.
+ limlst :
+ Upper bound on the number of cylces (>=3) for use with a sinusoidal
+ weighting and an infinite end-point.
+ wopts :
+ Optional input for reusing Chebyshev moments.
+ maxp1 :
+ An upper bound on the number of Chebyshev moments.
- **
- ** Run scipy.integrate.quad_explain() for more information
- ** on the following inputs
- **
- weight :
- string indicating weighting function.
- wvar :
- variables for use with weighting functions.
- limlst :
- Upper bound on the number of cylces (>=3) for use with a sinusoidal
- weighting and an infinite end-point.
- wopts :
- Optional input for reusing Chebyshev moments.
- maxp1 :
- An upper bound on the number of Chebyshev moments.
+ See Also
+ --------
+ dblquad, tplquad - double and triple integrals
+ fixed_quad - fixed-order Gaussian quadrature
+ quadrature - adaptive Gaussian quadrature
+ odeint, ode - ODE integrators
+ simps, trapz, romb - integrators for sampled data
+ scipy.special - for coefficients and roots of orthogonal polynomials
-
Examples
--------
Calculate :math:`\\int^4_0 x^2 dx` and compare with an analytic result
+ >>> from scipy import integrate
>>> x2 = lambda x: x**2
- >>> quad(x,0.,4.)
+ >>> integrate.quad(x,0.,4.)
(21.333333333333332, 2.3684757858670003e-13)
>> print 4.**3/3
21.3333333333
@@ -206,17 +229,17 @@
Calculate :math:`\\int^\\infty_0 e^{-x} dx`
>>> invexp = lambda x: exp(-x)
- >>> quad(invexp,0,inf)
+ >>> integrate.quad(invexp,0,inf)
(0.99999999999999989, 5.8426061711142159e-11)
- See also:
- dblquad, tplquad - double and triple integrals
- fixed_quad - fixed-order Gaussian quadrature
- quadrature - adaptive Gaussian quadrature
- odeint, ode - ODE integrators
- simps, trapz, romb - integrators for sampled data
- scipy.special - for coefficients and roots of orthogonal polynomials
+ >>> f = lambda x,a : a*x
+ >>> y, err = integrate.quad(f, 0, 1, args=(1,))
+ >>> y
+ 0.5
+ >>> y, err = integrate.quad(f, 0, 1, args=(3,))
+ >>> y
+ 1.5
"""
if type(args) != type(()): args = (args,)
@@ -410,50 +433,51 @@
Return the triple integral of func3d(z, y,x) from
x=a..b, y=gfun(x)..hfun(x), and z=qfun(x,y)..rfun(x,y)
-
Parameters
- -----------
- func3d : function
- a Python function or method of at least three variables in the
- order (z, y, x).
- (a,b) : tuple
- the limits of integration in x: a < b
- gfun : function
- the lower boundary curve in y which is a function taking a single
- floating point argument (x) and returning a floating point result:
- a lambda function can be useful here.
- hfun : function
- the upper boundary curve in y (same requirements as gfun).
- qfun : function
- the lower boundary surface in z. It must be a function that takes
- two floats in the order (x, y) and returns a float.
- rfun : function
- the upper boundary surface in z. (Same requirements as qfun.)
- args :
- extra arguments to pass to func3d.
- epsabs : float
- absolute tolerance passed directly to the innermost 1-D quadrature
- integration.
- epsrel : float
- relative tolerance of the innermost 1-D integrals.
+ ----------
+ func3d : function
+ A Python function or method of at least three variables in the
+ order (z, y, x).
+ (a,b) : tuple
+ The limits of integration in x: a < b
+ gfun : function
+ The lower boundary curve in y which is a function taking a single
+ floating point argument (x) and returning a floating point result:
+ a lambda function can be useful here.
+ hfun : function
+ The upper boundary curve in y (same requirements as gfun).
+ qfun : function
+ The lower boundary surface in z. It must be a function that takes
+ two floats in the order (x, y) and returns a float.
+ rfun : function
+ The upper boundary surface in z. (Same requirements as qfun.)
+ args : Arguments
+ Extra arguments to pass to func3d.
+ epsabs : float
+ Absolute tolerance passed directly to the innermost 1-D quadrature
+ integration.
+ epsrel : float
+ Relative tolerance of the innermost 1-D integrals.
-
Returns
- -----------
+ -------
+ y : float
+ The resultant integral.
+ abserr : float
+ An estimate of the error.
- y : float
- the resultant integral.
- abserr : float
- an estimate of the error.
+ See Also
+ --------
+ quad: Adaptive quadrature using QUADPACK
+ quadrature: Adaptive Gaussian quadrature
+ fixed_quad: Fixed-order Gaussian quadrature
+ dblquad: Double integrals
+ romb: Integrators for sampled data
+ trapz: Integrators for sampled data
+ simps: Integrators for sampled data
+ ode: ODE integrators
+ odeint: ODE integrators
+ scipy.special: For coefficients and roots of orthogonal polynomials
- See also:
- quad - single integral
- dblquad - double integral
- fixed_quad - fixed-order Gaussian quadrature
- quadrature - adaptive Gaussian quadrature
- odeint, ode - ODE integrators
- simps, trapz, romb - integrators for sampled data
- scipy.special - for coefficients and roots of orthogonal polynomials
-
"""
return dblquad(_infunc2,a,b,gfun,hfun,(func,qfun,rfun,args),epsabs=epsabs,epsrel=epsrel)
Modified: trunk/scipy/integrate/quadrature.py
===================================================================
--- trunk/scipy/integrate/quadrature.py 2010-05-23 20:53:37 UTC (rev 6400)
+++ trunk/scipy/integrate/quadrature.py 2010-05-24 13:09:36 UTC (rev 6401)
@@ -10,34 +10,39 @@
import math
def fixed_quad(func,a,b,args=(),n=5):
- """Compute a definite integral using fixed-order Gaussian quadrature.
+ """
+ Compute a definite integral using fixed-order Gaussian quadrature.
- Description:
+ Integrate `func` from a to b using Gaussian quadrature of order n.
- Integrate func from a to b using Gaussian quadrature of order n.
+ Parameters
+ ----------
+ func : callable
+ A Python function or method to integrate (must accept vector inputs).
+ a : float
+ Lower limit of integration.
+ b : float
+ Upper limit of integration.
+ args : tuple, optional
+ Extra arguments to pass to function, if any.
+ n : int, optional
+ Order of quadrature integration. Default is 5.
- Inputs:
+ Returns
+ -------
+ val : float
+ Gaussian quadrature approximation to the integral
- func -- a Python function or method to integrate
- (must accept vector inputs)
- a -- lower limit of integration
- b -- upper limit of integration
- args -- extra arguments to pass to function.
- n -- order of quadrature integration.
+ See Also
+ --------
+ quad : adaptive quadrature using QUADPACK
+ dblquad, tplquad : double and triple integrals
+ romberg : adaptive Romberg quadrature
+ quadrature : adaptive Gaussian quadrature
+ romb, simps, trapz : integrators for sampled data
+ cumtrapz : cumulative integration for sampled data
+ ode, odeint - ODE integrators
- Outputs: (val, None)
-
- val -- Gaussian quadrature approximation to the integral.
-
- See also:
-
- quad - adaptive quadrature using QUADPACK
- dblquad, tplquad - double and triple integrals
- romberg - adaptive Romberg quadrature
- quadrature - adaptive Gaussian quadrature
- romb, simps, trapz - integrators for sampled data
- cumtrapz - cumulative integration for sampled data
- ode, odeint - ODE integrators
"""
[x,w] = p_roots(n)
x = real(x)
@@ -95,39 +100,52 @@
return vfunc
def quadrature(func,a,b,args=(),tol=1.49e-8,maxiter=50, vec_func=True):
- """Compute a definite integral using fixed-tolerance Gaussian quadrature.
+ """
+ Compute a definite integral using fixed-tolerance Gaussian quadrature.
- Description:
-
Integrate func from a to b using Gaussian quadrature
- with absolute tolerance tol.
+ with absolute tolerance `tol`.
- Inputs:
+ Parameters
+ ----------
+ func : function
+ A Python function or method to integrate.
+ a : float
+ Lower limit of integration.
+ b : float
+ Upper limit of integration.
+ args : tuple, optional
+ Extra arguments to pass to function.
+ tol : float, optional
+ Iteration stops when error between last two iterates is less than
+ tolerance.
+ maxiter : int, optional
+ Maximum number of iterations.
+ vec_func : bool, optional
+ True or False if func handles arrays as arguments (is
+ a "vector" function). Default is True.
- func -- a Python function or method to integrate.
- a -- lower limit of integration.
- b -- upper limit of integration.
- args -- extra arguments to pass to function.
- tol -- iteration stops when error between last two iterates is less than
- tolerance.
- maxiter -- maximum number of iterations.
- vec_func -- True or False if func handles arrays as arguments (is
- a "vector" function ). Default is True.
+ Returns
+ -------
+ val : float
+ Gaussian quadrature approximation (within tolerance) to integral.
+ err : float
+ Difference between last two estimates of the integral.
- Outputs: (val, err)
+ See also
+ --------
+ romberg: adaptive Romberg quadrature
+ fixed_quad: fixed-order Gaussian quadrature
+ quad: adaptive quadrature using QUADPACK
+ dblquad: double integrals
+ tplquad: triple integrals
+ romb: integrator for sampled data
+ simps: integrator for sampled data
+ trapz: integrator for sampled data
+ cumtrapz: cumulative integration for sampled data
+ ode: ODE integrator
+ odeint: ODE integrator
- val -- Gaussian quadrature approximation (within tolerance) to integral.
- err -- Difference between last two estimates of the integral.
-
- See also:
-
- romberg - adaptive Romberg quadrature
- fixed_quad - fixed-order Gaussian quadrature
- quad - adaptive quadrature using QUADPACK
- dblquad, tplquad - double and triple integrals
- romb, simps, trapz - integrators for sampled data
- cumtrapz - cumulative integration for sampled data
- ode, odeint - ODE integrators
"""
err = 100.0
val = err
@@ -148,20 +166,41 @@
return tuple(l)
def cumtrapz(y, x=None, dx=1.0, axis=-1):
- """Cumulatively integrate y(x) using samples along the given axis
+ """
+ Cumulatively integrate y(x) using samples along the given axis
and the composite trapezoidal rule. If x is None, spacing given by dx
is assumed.
- See also:
+ Parameters
+ ----------
+ y : array
- quad - adaptive quadrature using QUADPACK
- romberg - adaptive Romberg quadrature
- quadrature - adaptive Gaussian quadrature
- fixed_quad - fixed-order Gaussian quadrature
- dblquad, tplquad - double and triple integrals
- romb, trapz - integrators for sampled data
- cumtrapz - cumulative integration for sampled data
- ode, odeint - ODE integrators
+ x : array, optional
+
+ dx : int, optional
+
+ axis : int, optional
+ Specifies the axis to cumulate:
+
+ - -1 --> X axis
+ - 0 --> Z axis
+ - 1 --> Y axis
+
+ See Also
+ --------
+
+ quad: adaptive quadrature using QUADPACK
+ romberg: adaptive Romberg quadrature
+ quadrature: adaptive Gaussian quadrature
+ fixed_quad: fixed-order Gaussian quadrature
+ dblquad: double integrals
+ tplquad: triple integrals
+ romb: integrators for sampled data
+ trapz: integrators for sampled data
+ cumtrapz: cumulative integration for sampled data
+ ode: ODE integrators
+ odeint: ODE integrators
+
"""
y = asarray(y)
if x is None:
@@ -204,39 +243,57 @@
def simps(y, x=None, dx=1, axis=-1, even='avg'):
- """Integrate y(x) using samples along the given axis and the composite
+ """
+ Integrate y(x) using samples along the given axis and the composite
Simpson's rule. If x is None, spacing of dx is assumed.
If there are an even number of samples, N, then there are an odd
number of intervals (N-1), but Simpson's rule requires an even number
- of intervals. The parameter 'even' controls how this is handled as
- follows:
+ of intervals. The parameter 'even' controls how this is handled.
- even='avg': Average two results: 1) use the first N-2 intervals with
- a trapezoidal rule on the last interval and 2) use the last
- N-2 intervals with a trapezoidal rule on the first interval
+ Parameters
+ ----------
+ y : array_like
+ Array to be integrated.
+ x : array_like, optional
+ If given, the points at which `y` is sampled.
+ dx : int, optional
+ Spacing of integration points along axis of `y`. Only used when
+ `x` is None. Default is 1.
+ axis : int, optional
+ Axis along which to integrate. Default is the last axis.
+ even : {'avg', 'first', 'str'}, optional
+ 'avg' : Average two results:1) use the first N-2 intervals with
+ a trapezoidal rule on the last interval and 2) use the last
+ N-2 intervals with a trapezoidal rule on the first interval.
- even='first': Use Simpson's rule for the first N-2 intervals with
- a trapezoidal rule on the last interval.
+ 'first' : Use Simpson's rule for the first N-2 intervals with
+ a trapezoidal rule on the last interval.
- even='last': Use Simpson's rule for the last N-2 intervals with a
- trapezoidal rule on the first interval.
+ 'last' : Use Simpson's rule for the last N-2 intervals with a
+ trapezoidal rule on the first interval.
+ See Also
+ --------
+ quad: adaptive quadrature using QUADPACK
+ romberg: adaptive Romberg quadrature
+ quadrature: adaptive Gaussian quadrature
+ fixed_quad: fixed-order Gaussian quadrature
+ dblquad: double integrals
+ tplquad: triple integrals
+ romb: integrators for sampled data
+ trapz: integrators for sampled data
+ cumtrapz: cumulative integration for sampled data
+ ode: ODE integrators
+ odeint: ODE integrators
+
+ Notes
+ -----
For an odd number of samples that are equally spaced the result is
- exact if the function is a polynomial of order 3 or less. If
- the samples are not equally spaced, then the result is exact only
- if the function is a polynomial of order 2 or less.
+ exact if the function is a polynomial of order 3 or less. If
+ the samples are not equally spaced, then the result is exact only
+ if the function is a polynomial of order 2 or less.
- See also:
-
- quad - adaptive quadrature using QUADPACK
- romberg - adaptive Romberg quadrature
- quadrature - adaptive Gaussian quadrature
- fixed_quad - fixed-order Gaussian quadrature
- dblquad, tplquad - double and triple integrals
- romb, trapz - integrators for sampled data
- cumtrapz - cumulative integration for sampled data
- ode, odeint - ODE integrators
"""
y = asarray(y)
nd = len(y.shape)
@@ -293,21 +350,31 @@
return result
def romb(y, dx=1.0, axis=-1, show=False):
- """Romberg integration using samples of a function
+ """
+ Romberg integration using samples of a function
- Inputs:
+ Parameters
+ -----------
+ y : array like
+ a vector of 2**k + 1 equally-spaced samples of a function
- y - a vector of 2**k + 1 equally-spaced samples of a fucntion
- dx - the sample spacing.
- axis - the axis along which to integrate
- show - When y is a single 1-d array, then if this argument is True
- print the table showing Richardson extrapolation from the
- samples.
+ dx : array like
+ the sample spacing.
- Output: ret
+ axis : array like?
+ the axis along which to integrate
- ret - The integrated result for each axis.
+ show : Boolean
+ When y is a single 1-d array, then if this argument is True
+ print the table showing Richardson extrapolation from the
+ samples.
+ Returns
+ -----------
+
+ ret : array_like?
+ The integrated result for each axis.
+
See also:
quad - adaptive quadrature using QUADPACK
@@ -318,6 +385,7 @@
simps, trapz - integrators for sampled data
cumtrapz - cumulative integration for sampled data
ode, odeint - ODE integrators
+
"""
y = asarray(y)
nd = len(y.shape)
@@ -603,35 +671,46 @@
}
def newton_cotes(rn,equal=0):
- r"""Return weights and error coefficient for Netwon-Cotes integration.
+ """
+ Return weights and error coefficient for Newton-Cotes integration.
- Suppose we have (N+1) samples of f at the positions
- x_0, x_1, ..., x_N. Then an N-point Newton-Cotes formula for the
- integral between x_0 and x_N is:
+ Suppose we have (N+1) samples of f at the positions
+ x_0, x_1, ..., x_N. Then an N-point Newton-Cotes formula for the
+ integral between x_0 and x_N is:
- $\int_{x_0}^{x_N} f(x)dx = \Delta x \sum_{i=0}^{N} a_i f(x_i)
- + B_N (\Delta x)^{N+2} f^{N+1} (\xi)$
+ :math:`\\int_{x_0}^{x_N} f(x)dx = \\Delta x \\sum_{i=0}^{N} a_i f(x_i)
+ + B_N (\\Delta x)^{N+2} f^{N+1} (\\xi)`
- where $\xi \in [x_0,x_N]$ and $\Delta x = \frac{x_N-x_0}{N}$ is the
- averages samples spacing.
+ where :math:`\\xi \\in [x_0,x_N]` and :math:`\\Delta x = \\frac{x_N-x_0}{N}`
+ is the averages samples spacing.
- If the samples are equally-spaced and N is even, then the error
- term is $B_N (\Delta x)^{N+3} f^{N+2}(\xi)$.
+ If the samples are equally-spaced and N is even, then the error
+ term is :math:`B_N (\\Delta x)^{N+3} f^{N+2}(\\xi)`.
- Normally, the Newton-Cotes rules are used on smaller integration
- regions and a composite rule is used to return the total integral.
+ Parameters
+ ----------
- Inputs:
- rn -- the integer order for equally-spaced data
- or the relative positions of the samples with
- the first sample at 0 and the last at N, where
- N+1 is the length of rn. N is the order of the Newt
- equal -- Set to 1 to enforce equally spaced data
+ rn : int
+ The integer order for equally-spaced data
+ or the relative positions of the samples with
+ the first sample at 0 and the last at N, where
+ N+1 is the length of rn. N is the order of the Newton
+ equal: int, optional
+ Set to 1 to enforce equally spaced data
- Outputs:
- an -- 1-d array of weights to apply to the function at
- the provided sample positions.
- B -- error coefficient
+ Returns
+ -------
+ an : array
+ 1-d array of weights to apply to the function at
+ the provided sample positions.
+ B : float
+ error coefficient
+
+ Notes
+ -----
+ Normally, the Newton-Cotes rules are used on smaller integration
+ regions and a composite rule is used to return the total integral.
+
"""
try:
N = len(rn)-1
More information about the Scipy-svn
mailing list