[Scipy-svn] r5231 - in trunk/scipy: ndimage optimize
scipy-svn at scipy.org
scipy-svn at scipy.org
Sun Dec 7 12:31:04 EST 2008
Author: ptvirtan
Date: 2008-12-07 11:30:50 -0600 (Sun, 07 Dec 2008)
New Revision: 5231
Modified:
trunk/scipy/ndimage/interpolation.py
trunk/scipy/optimize/zeros.py
Log:
Docstring updates from wiki
Modified: trunk/scipy/ndimage/interpolation.py
===================================================================
--- trunk/scipy/ndimage/interpolation.py 2008-12-07 12:02:43 UTC (rev 5230)
+++ trunk/scipy/ndimage/interpolation.py 2008-12-07 17:30:50 UTC (rev 5231)
@@ -143,7 +143,8 @@
def map_coordinates(input, coordinates, output_type = None, output = None,
order = 3, mode = 'constant', cval = 0.0, prefilter = True):
- """Apply an arbritrary coordinate transformation.
+ """
+ Map the input array to new coordinates by interpolation.
The array of coordinates is used to find, for each point in the output,
the corresponding coordinates in the input. The value of the input at
@@ -153,32 +154,71 @@
The shape of the output is derived from that of the coordinate
array by dropping the first axis. The values of the array along
the first axis are the coordinates in the input array at which the
- output value is found. For example, if the input has dimensions
- (100,200,3), then the shape of coordinates will be (3,100,200,3),
- where coordinates[:,1,2,3] specify the input coordinate at which
- output[1,2,3] is found.
+ output value is found.
- Points outside the boundaries of the input are filled according to
- the given mode ('constant', 'nearest', 'reflect' or 'wrap'). The
- parameter prefilter determines if the input is pre-filtered before
- interpolation (necessary for spline interpolation of order >
- 1). If False it is assumed that the input is already filtered.
+ Parameters
+ ----------
+ input : ndarray
+ The input array
+ coordinates : array_like
+ The coordinates at which `input` is evaluated.
+ output_type : deprecated
+ Use `output` instead.
+ output : dtype, optional
+ If the output has to have a certain type, specify the dtype.
+ The default behavior is for the output to have the same type
+ as `input`.
+ order : int, optional
+ The order of the spline interpolation, default is 3.
+ The order has to be in the range 0-5.
+ mode : str, optional
+ Points outside the boundaries of the input are filled according
+ to the given mode ('constant', 'nearest', 'reflect' or 'wrap').
+ Default is 'constant'.
+ cval : scalar, optional
+ Value used for points outside the boundaries of the input if
+ `mode='constant`. Default is 0.0
+ prefilter : bool, optional
+ The parameter prefilter determines if the input is
+ pre-filtered with `spline_filter`_ before interpolation
+ (necessary for spline interpolation of order > 1).
+ If False, it is assumed that the input is already filtered.
- Example
+ Returns
-------
- >>> a = arange(12.).reshape((4,3))
+ return_value : ndarray
+ The result of transforming the input. The shape of the
+ output is derived from that of `coordinates` by dropping
+ the first axis.
+
+
+ See Also
+ --------
+ spline_filter, geometric_transform, scipy.interpolate
+
+ Examples
+ --------
+ >>> import scipy.ndimage
+ >>> a = np.arange(12.).reshape((4,3))
>>> print a
- [[ 0. 1. 2.]
- [ 3. 4. 5.]
- [ 6. 7. 8.]
- [ 9. 10. 11.]]
- >>> output = map_coordinates(a,[[0.5, 2], [0.5, 1]],order=1)
- >>> print output
- [ 2. 7.]
+ array([[ 0., 1., 2.],
+ [ 3., 4., 5.],
+ [ 6., 7., 8.],
+ [ 9., 10., 11.]])
+ >>> sp.ndimage.map_coordinates(a, [[0.5, 2], [0.5, 1]], order=1)
+ [ 2. 7.]
- Here, the interpolated value of a[0.5,0.5] gives output[0], while
- a[2,1] is output[1].
+ Above, the interpolated value of a[0.5, 0.5] gives output[0], while
+ a[2, 1] is output[1].
+ >>> inds = np.array([[0.5, 2], [0.5, 4]])
+ >>> sp.ndimage.map_coordinates(a, inds, order=1, cval=-33.3)
+ array([ 2. , -33.3])
+ >>> sp.ndimage.map_coordinates(a, inds, order=1, mode='nearest')
+ array([ 2., 8.])
+ >>> sp.ndimage.map_coordinates(a, inds, order=1, cval=0, output=bool)
+ array([ True, False], dtype=bool
+
"""
if order < 0 or order > 5:
raise RuntimeError, 'spline order not supported'
Modified: trunk/scipy/optimize/zeros.py
===================================================================
--- trunk/scipy/optimize/zeros.py 2008-12-07 12:02:43 UTC (rev 5230)
+++ trunk/scipy/optimize/zeros.py 2008-12-07 17:30:50 UTC (rev 5231)
@@ -99,60 +99,69 @@
def ridder(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
full_output=False, disp=False):
- """Find root of f in [a,b]
+ """
+ Find a root of a function in an interval.
- Ridder routine to find a zero of the function
- f between the arguments a and b. f(a) and f(b) can not
- have the same signs. Faster than bisection, but not
- generaly as fast as the brent rountines. A description
- may be found in a recent edition of Numerical Recipes.
- The routine here is modified a bit to be more careful
- of tolerance.
-
- f : Python function returning a number.
-
- a : Number, one end of the bracketing interval.
-
- b : Number, the other end of the bracketing interval.
-
- xtol : Number, the routine converges when a root is known
+ Parameters
+ ----------
+ f : function
+ Python function returning a number.
+ `f` must be continuous, and `f(a)` and `f(b)` must have opposite signs.
+ a : number
+ one end of the bracketing interval `[a,b]`
+ b : number
+ the other end of the bracketing interval `[a,b]`
+ xtol : number, optional
+ the routine converges when a root is known
to lie within xtol of the value return. Should be >= 0.
The routine modifies this to take into account the relative
precision of doubles.
+ maxiter : number, optional
+ if convergence is not achieved in
+ maxiter iterations, and error is raised.
+ Must be >= 0.
+ args : tuple, optional
+ containing extra arguments for the function `f`.
+ `f` is called by ``apply(f, (x)+args)``.
+ full_output : bool, optional
+ If `full_output` is False, the root is returned.
+ If `full_output` is True, the return value is ``(x, r)``, where `x`
+ is the root, and `r` is a RootResults object.
+ disp : bool, optional
+ If True, print a message to ``stderr`` if the algorithm didn't
+ converge.
- maxiter : Number, if convergence is not achieved in
- maxiter iterations, and error is raised. Must be
- >= 0.
+ Returns
+ -------
+ x0 : float
+ Zero of `f` between `a` and `b`.
+ r : RootResults (present if ``full_output = True``)
+ Object containing information about the convergence.
+ In particular, ``r.converged`` is True if the routine converged.
- args : tuple containing extra arguments for the function f.
- f is called by apply(f,(x)+args).
+ See Also
+ --------
+ brentq, brenth, bisect, newton : one-dimensional root-finding
+ fixed_point : scalar fixed-point finder
- If full_output is False, the root is returned.
+ Notes
+ -----
+ Uses [Ridders1979]_ method to find a zero of the function `f` between
+ the arguments `a` and `b`. Ridders' method is faster than bisection,
+ but not generaly as fast as the brent rountines. [Ridders1979]_ provides
+ the classic description and source of the algorithm. A description can
+ also be found in may be found in any recent edition of Numerical Recipes.
- If full_output is True, the return value is (x, r), where x
- is the root, and r is a RootResults object containing information
- about the convergence. In particular, r.converged is True if the
- the routine converged.
+ The routine used here diverges slightly from standard presentations
+ in order to be a bit more careful of tolerance.
- See also:
+ References
+ ----------
+ .. [Ridders1979]
+ Ridders, C. F. J. "A New Algorithm for Computing a
+ Single Root of a Real Continuous Function."
+ IEEE Trans. Circuits Systems 26, 979-980, 1979.
- fmin, fmin_powell, fmin_cg,
- fmin_bfgs, fmin_ncg -- multivariate local optimizers
- leastsq -- nonlinear least squares minimizer
-
- fmin_l_bfgs_b, fmin_tnc,
- fmin_cobyla -- constrained multivariate optimizers
-
- anneal, brute -- global optimizers
-
- fminbound, brent, golden, bracket -- local scalar minimizers
-
- fsolve -- n-dimenstional root-finding
-
- brentq, brenth, ridder, bisect, newton -- one-dimensional root-finding
-
- fixed_point -- scalar fixed-point finder
-
"""
if type(args) != type(()) :
args = (args,)
@@ -162,61 +171,107 @@
def brentq(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
full_output=False, disp=False):
- """Find root of f in [a,b]
+ """
+ Find a root of a function in given interval.
- The classic Brent routine to find a zero of the function
- f between the arguments a and b. f(a) and f(b) can not
- have the same signs. Generally the best of the routines here.
+ Return float, a zero of `f` between `a` and `b`.
+ `f` must be a continuous function, and
+ [a,b] must be a sign changing interval.
+
+ Description:
+ Uses the classic Brent (1973) method to find a zero
+ of the function `f` on the sign changing interval [a , b].
+ Generally considered the best of the rootfinding routines here.
It is a safe version of the secant method that uses inverse
- quadratic extrapolation. The version here is a slight
- modification that uses a different formula in the extrapolation
- step. A description may be found in Numerical Recipes, but the
- code here is probably easier to understand.
+ quadratic extrapolation.
+ Brent's method combines root bracketing, interval bisection,
+ and inverse quadratic interpolation.
+ It is sometimes known as the van Wijngaarden-Deker-Brent method.
+ Brent (1973) claims convergence is guaranteed for functions
+ computable within [a,b].
- f : Python function returning a number.
+ [Brent1973]_ provides the classic description of the algorithm.
+ Another description is in any recent edition of Numerical Recipes,
+ including [PressEtal1992]_.
+ Another description is at http://mathworld.wolfram.com/BrentsMethod.html.
+ It should be easy to understand the algorithm just by reading our code.
+ Our code diverges a bit from standard presentations:
+ we choose a different formula for the extrapolation step.
- a : Number, one end of the bracketing interval.
- b : Number, the other end of the bracketing interval.
+ Parameters
+ ----------
- xtol : Number, the routine converges when a root is known
- to lie within xtol of the value return. Should be >= 0.
- The routine modifies this to take into account the relative
- precision of doubles.
+ `f` : function
+ Python function returning a number.
- maxiter : Number, if convergence is not achieved in
- maxiter iterations, and error is raised. Must be
- >= 0.
+ `a` : number
+ one end of the bracketing interval [a,b]
- args : tuple containing extra arguments for the function f.
- f is called by apply(f,(x)+args).
+ `b` : number
+ the other end of the bracketing interval [a,b]
- If full_output is False, the root is returned.
+ `xtol` : number
+ the routine converges when a root is known
+ to lie within xtol of the value return. Should be >= 0.
+ The routine modifies this to take into account the relative
+ precision of doubles.
- If full_output is True, the return value is (x, r), where x
- is the root, and r is a RootResults object containing information
- about the convergence. In particular, r.converged is True if the
- the routine converged.
+ `maxiter` : number
+ if convergence is not achieved in
+ maxiter iterations, and error is raised.
+ Must be >= 0.
- See also:
+ `args` : tuple
+ containing extra arguments for the function `f`.
+ `f` is called by apply(f,(x)+args).
- fmin, fmin_powell, fmin_cg,
- fmin_bfgs, fmin_ncg -- multivariate local optimizers
- leastsq -- nonlinear least squares minimizer
+ `full_output` : bool
+ If `full_output` is False, the root is returned.
+ If `full_output` is True, the return value is (x, r), where x
+ is the root, and r is a RootResults object containing information
+ about the convergence. In particular, r.converged is True if the
+ the routine converged.
- fmin_l_bfgs_b, fmin_tnc,
- fmin_cobyla -- constrained multivariate optimizers
- anneal, brute -- global optimizers
+ See Also
+ --------
- fminbound, brent, golden, bracket -- local scalar minimizers
+ multivariate local optimizers
+ `fmin`, `fmin_powell`, `fmin_cg`, `fmin_bfgs`, `fmin_ncg`
+ nonlinear least squares minimizer
+ `leastsq`
+ constrained multivariate optimizers
+ `fmin_l_bfgs_b`, `fmin_tnc`, `fmin_cobyla`
+ global optimizers
+ `anneal`, `brute`
+ local scalar minimizers
+ `fminbound`, `brent`, `golden`, `bracket`
+ n-dimenstional root-finding
+ `fsolve`
+ one-dimensional root-finding
+ `brentq`, `brenth`, `ridder`, `bisect`, `newton`
+ scalar fixed-point finder
+ `fixed_point`
- fsolve -- n-dimenstional root-finding
+ Notes
+ -----
- brentq, brenth, ridder, bisect, newton -- one-dimensional root-finding
+ `f` must be continuous.
+ f(a) and f(b) must have opposite signs.
- fixed_point -- scalar fixed-point finder
+ .. [Brent1973]
+ Brent, R. P.,
+ *Algorithms for Minimization Without Derivatives*.
+ Englewood Cliffs, NJ: Prentice-Hall, 1973. Ch. 3-4.
+
+ .. [PressEtal1992]
+ Press, W. H.; Flannery, B. P.; Teukolsky, S. A.; and Vetterling, W. T.
+ *Numerical Recipes in FORTRAN: The Art of Scientific Computing*, 2nd ed.
+ Cambridge, England: Cambridge University Press, pp. 352-355, 1992.
+ Section 9.3: "Van Wijngaarden-Dekker-Brent Method."
+
"""
if type(args) != type(()) :
args = (args,)
More information about the Scipy-svn
mailing list