[Scipysvn] r5231  in trunk/scipy: ndimage optimize
scipysvn@scip...
scipysvn@scip...
Sun Dec 7 11:31:04 CST 2008
Author: ptvirtan
Date: 20081207 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 20081207 12:02:43 UTC (rev 5230)
+++ trunk/scipy/ndimage/interpolation.py 20081207 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 prefiltered 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 05.
+ 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
+ prefiltered 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 20081207 12:02:43 UTC (rev 5230)
+++ trunk/scipy/optimize/zeros.py 20081207 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 : onedimensional rootfinding
+ fixed_point : scalar fixedpoint 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, 979980, 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  ndimenstional rootfinding

 brentq, brenth, ridder, bisect, newton  onedimensional rootfinding

 fixed_point  scalar fixedpoint 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 WijngaardenDekerBrent 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`
+ ndimenstional rootfinding
+ `fsolve`
+ onedimensional rootfinding
+ `brentq`, `brenth`, `ridder`, `bisect`, `newton`
+ scalar fixedpoint finder
+ `fixed_point`
 fsolve  ndimenstional rootfinding
+ Notes
+ 
 brentq, brenth, ridder, bisect, newton  onedimensional rootfinding
+ `f` must be continuous.
+ f(a) and f(b) must have opposite signs.
 fixed_point  scalar fixedpoint finder
+ .. [Brent1973]
+ Brent, R. P.,
+ *Algorithms for Minimization Without Derivatives*.
+ Englewood Cliffs, NJ: PrenticeHall, 1973. Ch. 34.
+
+ .. [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. 352355, 1992.
+ Section 9.3: "Van WijngaardenDekkerBrent Method."
+
"""
if type(args) != type(()) :
args = (args,)
More information about the Scipysvn
mailing list