Class Hessian

     object --+        
              |        
Common_diff_par --+    
                  |    
         Derivative --+
                      |
                     Hessian

Estimate Hessian matrix, with error estimate


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

**kwds
------
derOrder : Derivative order is always 2
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.



HESSIAN estimate the matrix of 2nd order partial derivatives of a real
valued function FUN evaluated at X0. HESSIAN is NOT a tool for frequent
use on an expensive to evaluate objective function, especially in a large
number of dimensions. Its computation will use roughly  O(6*n^2) function
evaluations for n parameters.

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
--------

#Rosenbrock function, minimized at [1,1]
>>> rosen = lambda x : (1.-x[0])**2 + 105*(x[1]-x[0]**2)**2
>>> Hfun = Hessian(rosen)
>>> h = Hfun([1, 1]) #  h =[ 842 -420; -420, 210];
>>> Hfun.error_estimate
array([[  2.86982123e-12,   1.92513461e-12],
       [  1.92513461e-12,   9.62567303e-13]])

#cos(x-y), at (0,0)
>>> cos = np.cos
>>> fun = lambda xy : cos(xy[0]-xy[1])
>>> Hfun2 = Hessian(fun)
>>> h2 = Hfun2([0, 0]) # h2 = [-1 1; 1 -1];
>>> Hfun2.error_estimate
array([[  4.34170696e-15,   4.34170696e-15],
       [  4.34170696e-15,   4.34170696e-15]])

>>> Hfun2.numTerms = 3
>>> h3 = Hfun2([0,0])
>>> Hfun2.error_estimate
array([[  1.70965039e-14,   1.29284572e-12],
       [  1.29284572e-12,   1.70965039e-14]])


See also
--------
Gradient,
Derivative,
Hessdiag,
Jacobian