Package numdifftools :: Module core :: Class Gradient
[show private | hide private]
[frames | no frames]

Class Gradient

     object --+        
              |        
Common_diff_par --+    
                  |    
         Derivative --+
                      |
                     Gradient


Estimate gradient of fun at x0, with error estimate


Input arguments
===============
fun = function to differentiate.

**kwds
------
derOrder : Derivative order is always 1
metOrder : Integer from 1 to 4 defining order of basic method used.
             (For 'central' methods, it must be from the set [2,4].
             (Default 2)
method   : Method of estimation.  Valid options are:
              'central', 'forward' or 'backwards'.     (Default 'central')
numTerms : Number of Romberg terms used in the extrapolation.
             Must be an integer from 0 to 3.  (Default 2)
             Note: 0 disables the Romberg step completely.
stepFix  : If not None, it will define the maximum excursion from x0
             that is used and prevent the adaptive logic from working.
             This will be considerably faster, but not necessarily
             as accurate as allowing the adaptive logic to run.
            (Default: None)
stepMax  : Maximum allowed excursion from x0 as a multiple of x0. (Default 100)
stepRatio: Ratio used between sequential steps in the estimation
             of the derivative (Default 2)
vectorized : True  - if your function is vectorized.
               False - loop over the successive function calls (default).

Uses a semi-adaptive scheme to provide the best estimate of the
derivative by its automatic choice of a differencing interval. It uses
finite difference approximations of various orders, coupled with a
generalized (multiple term) Romberg extrapolation. This also yields the
error estimate provided. See the document DERIVEST.pdf for more explanation
of the algorithms behind the parameters.

 Note on metOrder: higher order methods will generally be more accurate,
         but may also suffer more from numerical problems. First order
         methods would usually not be recommended.
 Note on method: Central difference methods are usually the most accurate,
        but sometimes one can only allow evaluation in forward or backward
        direction.



Assumptions
-----------
  fun - SCALAR analytical function to differentiate.
        fun must be a function of the vector or array x0,
        but it needs not to be vectorized.

  x0  - vector location at which to differentiate fun
        If x0 is an N x M array, then fun is assumed to be
        a function of N*M variables.


Examples
--------
>>> fun = lambda x: np.sum(x**2)
>>> dfun = Gradient(fun)
>>> dfun([1,2,3])
array([ 2.,  4.,  6.])

#At [x,y] = [1,1], compute the numerical gradient
#of the function sin(x-y) + y*exp(x)

>>> sin = np.sin; exp = np.exp
>>> z = lambda xy: sin(xy[0]-xy[1]) + xy[1]*exp(xy[0])
>>> dz = Gradient(z)
>>> grad2 = dz([1, 1])
>>> grad2
array([ 3.71828183,  1.71828183])
>>> dz.error_estimate
array([  1.05697754e-12,   6.39224510e-13])

#At the global minimizer (1,1) of the Rosenbrock function,
#compute the gradient. It should be essentially zero.

>>> rosen = lambda x : (1-x[0])**2 + 105.*(x[1]-x[0]**2)**2
>>> rd = Gradient(rosen)
>>> grad3 = rd([1,1])
>>> grad3
array([ 0.,  0.])
>>> rd.error_estimate
array([  2.22044605e-15,   2.22044605e-15])


See also
--------
Derivative, Hessdiag, Hessian, Jacobian

Method Summary
  __call__(self, x00)
  gradient(self, x00)
Gradient vector of an analytical function of n variables CALL: [grad,err,finaldelta] = fun.gradient(x0) grad = first partial derivatives of fun evaluated at x0.
    Inherited from Derivative
  __init__(self, fun, **kwds)
  derivative(self, x00)
Return estimate of n'th derivative of fun at x0 using romberg extrapolation
  _derivative(self, x00)
  _fder(self, f_x0i, x0i, h)
Return derivative estimates of f at x0 for a sequence of stepsizes h...
  _fun(self, xi)
  _gradient(self, x00)
  _hessdiag(self, x00)
  _hessian(self, x00)
  _partial_der(self, x00)
Return partial derivatives
    Inherited from Common_diff_par
  _check_params(self)
check the parameters for acceptability
  _fdamat(self, parity, nterms)
Return matrix for fda derivation.
  _fdiff_b(self, f_x0i, x0i, h)
Return backward differences...
  _fdiff_c(self, f_x0i, x0i, h)
Return central differences...
  _fdiff_f(self, f_x0i, x0i, h)
Return forward differences...
  _rombextrap(self, der_init)
Return Romberg extrapolated derivatives and error estimates based on the initial derivative estimates...
  _set_all_der_par(self)
Set derivative parameters: stepsize, differention rule and romberg extrapolation
  _set_delta(self)
Set the steps to use in derivation.
  _set_fdarule(self)
Generate finite differencing rule in advance.
  _set_fdiff(self)
Set _fdiff fun according to method
  _set_rombexpon(self)
Member variables used...
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __repr__(x)
x.__repr__() <==> repr(x)
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)
    Inherited from type
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T

Class Variable Summary
str _grad_txt = "\n\n    Input arguments\n    ==============...

Method Details

gradient(self, x00)

Gradient vector of an analytical function of n variables

CALL: [grad,err,finaldelta] = fun.gradient(x0)

 grad = first partial derivatives of fun evaluated at x0.    Size 1 x N
 err  = error estimates corresponding to each value in grad. Size 1 x N
 finaldelta = vector of final step sizes chosen for each partial derivative.
 fun  = analytical function to differentiate. fun must
       be a function of the vector or array x0.
 x0   = vector location at which to differentiate fun
       If x0 is an nxm array, then fun is assumed to be
       a function of N = n*m variables.

GRADEST estimate first partial derivatives of fun evaluated at x0.
GRADEST uses derivest to provide both derivative estimates
and error estimates. fun needs not be vectorized.

Examples

 #[grad,err] = gradest(@(x) sum(x.^2),[1 2 3]) #  grad = [ 2,4, 6];

Class Variable Details

_grad_txt

Type:
str
Value:
"""

    Input arguments
    ===============
    fun = function to differentiate.

    **kwds
    ------
...                                                                    

Generated by Epydoc 2.0 on Sat Nov 22 02:00:54 2008 http://epydoc.sf.net