gov.sandia.cognition.learning.algorithm.gradient
Class GradientDescendableApproximator

java.lang.Object
  extended by gov.sandia.cognition.util.AbstractCloneableSerializable
      extended by gov.sandia.cognition.learning.algorithm.gradient.GradientDescendableApproximator
All Implemented Interfaces:
Evaluator<Vector,Vector>, GradientDescendable, ParameterGradientEvaluator<Vector,Matrix>, VectorFunction, Vectorizable, VectorizableVectorFunction, CloneableSerializable, Serializable, Cloneable

@CodeReview(reviewer="Kevin R. Dixon",
            date="2008-07-23",
            changesNeeded=false,
            comments={"Minor change to class javadoc.","Looks fine."})
@PublicationReference(author="Wikipedia",
                      title="Numerical differentiation",
                      type=WebPage,
                      year=2009,
                      url="http://en.wikipedia.org/wiki/Numerical_differentiation")
public class GradientDescendableApproximator
extends AbstractCloneableSerializable
implements GradientDescendable

Creates a radientDescendable from a VectorizableVectorFunction by estimating the parameter gradient using a forward-difference approximation of the parameter Jacobian. Requires N+1 VectorFunction evaluations to approximate the Jacobian, where N is the number of parameters in the VectorizableVectorFunction. To compute the approximated derivative of the output with respect to the input, use NumericalDifferentiator.

Since:
2.0
Author:
Kevin R. Dixon
See Also:
NumericalDifferentiator, Serialized Form

Field Summary
static double DEFAULT_DELTA_SIZE
          Default deltaSize, 1.0E-5
 
Constructor Summary
GradientDescendableApproximator()
          Default constructor.
GradientDescendableApproximator(VectorizableVectorFunction function)
          Creates a new instance of GradientDescendableApproximator
GradientDescendableApproximator(VectorizableVectorFunction function, double deltaSize)
          Creates a new instance of GradientDescendableApproximator
 
Method Summary
 GradientDescendableApproximator clone()
          This makes public the clone method on the Object class and removes the exception that it throws.
 Matrix computeParameterGradient(Vector input)
          Computes a forward-differences approximation to the parameter Jacobian
static Matrix computeParameterGradient(VectorizableVectorFunction function, Vector input, double deltaSize)
          Computes a forward-differences approximation to the parameter Jacobian
 void convertFromVector(Vector parameters)
          Converts the object from a Vector of parameters.
 Vector convertToVector()
          Converts the object to a vector.
 Vector evaluate(Vector input)
          Evaluates the function on the given input and returns the output.
 double getDeltaSize()
          Getter for deltaSize
 VectorizableVectorFunction getFunction()
          Getter for function
 void setDeltaSize(double deltaSize)
          Setter for deltaSize
 void setFunction(VectorizableVectorFunction function)
          Setter for function
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_DELTA_SIZE

public static final double DEFAULT_DELTA_SIZE
Default deltaSize, 1.0E-5

See Also:
Constant Field Values
Constructor Detail

GradientDescendableApproximator

public GradientDescendableApproximator()
Default constructor.


GradientDescendableApproximator

public GradientDescendableApproximator(VectorizableVectorFunction function)
Creates a new instance of GradientDescendableApproximator

Parameters:
function - Internal VectorizableVectorFunction to consider

GradientDescendableApproximator

public GradientDescendableApproximator(VectorizableVectorFunction function,
                                       double deltaSize)
Creates a new instance of GradientDescendableApproximator

Parameters:
function - Internal VectorizableVectorFunction to consider
deltaSize - Size of the finite-difference unit vectors, typically ~1e-5
Method Detail

clone

public GradientDescendableApproximator clone()
Description copied from class: AbstractCloneableSerializable
This makes public the clone method on the Object class and removes the exception that it throws. Its default behavior is to automatically create a clone of the exact type of object that the clone is called on and to copy all primitives but to keep all references, which means it is a shallow copy. Extensions of this class may want to override this method (but call super.clone() to implement a "smart copy". That is, to target the most common use case for creating a copy of the object. Because of the default behavior being a shallow copy, extending classes only need to handle fields that need to have a deeper copy (or those that need to be reset). Some of the methods in ObjectUtil may be helpful in implementing a custom clone method. Note: The contract of this method is that you must use super.clone() as the basis for your implementation.

Specified by:
clone in interface GradientDescendable
Specified by:
clone in interface Vectorizable
Specified by:
clone in interface VectorizableVectorFunction
Specified by:
clone in interface CloneableSerializable
Overrides:
clone in class AbstractCloneableSerializable
Returns:
A clone of this object.

getFunction

public VectorizableVectorFunction getFunction()
Getter for function

Returns:
Internal VectorizableVectorFunction to consider

setFunction

public void setFunction(VectorizableVectorFunction function)
Setter for function

Parameters:
function - Internal VectorizableVectorFunction to consider

convertToVector

public Vector convertToVector()
Description copied from interface: Vectorizable
Converts the object to a vector.

Specified by:
convertToVector in interface Vectorizable
Returns:
The Vector form of the object.

convertFromVector

public void convertFromVector(Vector parameters)
Description copied from interface: Vectorizable
Converts the object from a Vector of parameters.

Specified by:
convertFromVector in interface Vectorizable
Parameters:
parameters - The parameters to incorporate.

evaluate

public Vector evaluate(Vector input)
Description copied from interface: Evaluator
Evaluates the function on the given input and returns the output.

Specified by:
evaluate in interface Evaluator<Vector,Vector>
Parameters:
input - The input to evaluate.
Returns:
The output produced by evaluating the input.

computeParameterGradient

public static Matrix computeParameterGradient(VectorizableVectorFunction function,
                                              Vector input,
                                              double deltaSize)
Computes a forward-differences approximation to the parameter Jacobian

Parameters:
function - Internal VectorizableVectorFunction to consider
input - Input about which to estimate the Jacobian
deltaSize - Size of the finite-difference unit vectors, typically ~1e-5
Returns:
Forward-difference approximated Jacobian about the input

computeParameterGradient

public Matrix computeParameterGradient(Vector input)
Computes a forward-differences approximation to the parameter Jacobian

Specified by:
computeParameterGradient in interface GradientDescendable
Specified by:
computeParameterGradient in interface ParameterGradientEvaluator<Vector,Matrix>
Parameters:
input - Input about which to estimate the Jacobian
Returns:
Forward-difference approximated Jacobian about the input

getDeltaSize

public double getDeltaSize()
Getter for deltaSize

Returns:
Size of the finite-difference unit vectors, typically ~1e-5

setDeltaSize

public void setDeltaSize(double deltaSize)
Setter for deltaSize

Parameters:
deltaSize - Size of the finite-difference unit vectors, typically ~1e-5