Class RealValuedFunctionVA

java.lang.Object
org.bzdev.math.RealValuedFunctionVA
All Implemented Interfaces:
RealValuedFunctVAOps, VADomainOps
Direct Known Subclasses:
RealValuedFunction, RealValuedFunctionThree, RealValuedFunctionTwo, RealValuedFunctionVA.Linear

public class RealValuedFunctionVA extends Object implements VADomainOps, RealValuedFunctVAOps
Class defining a real-valued function with an arbitrary number of arguments.

This is intended for cases in which a function should be passed as an argument.

A subclass will typically override one or more of the methods valueAt, derivAt, and secondDerivAt to provide the values for a function and its first and second partial derivative. The subclass may also override the methods getDomainMin, getDomainMax, getDomainMinClosed, getDomainMaxClosed, or isInDomain. For any that are not available, an UnsupportedOperationException will be thrown.

The class also provides scripting-language support. If a Scripting context is named scripting, the following EMCAScript code will implement a sin function and its derivatives:


     importClass(org.bzdev.RealValuedFunctionVA);
     ....
     // assume ourObject is a Java class with a method setFunction
     // that takes a RealValuedFunctionVA as its argument.
     funct = new RealValuedFunctionVA(scripting,
               {valueAt: function(array) {
                             var x = array[0]; var y = array[1];
                             return Math.sin(x) * Math.cos(y);
                         },
                derivAt: function(i, array) {
                             var x = array[0]; var y = array[1];
                              if (i == 0) {
                                  return Math.cos(x) * Math.cos(y);
                              } else if (i == 1) {
                                    return -Math.sin(x) * Math.sin(y);
                              }
                          },
                  secondDerivAt: function(i, j, array) {
                                   var x = array[0]; var y = array[1];
                                   if (i == 0 && j == 0) {
                                      return -Math.sin(x) * Math.cos(y);
                                   } else if (i == 0 && j == 1) {
                                      return -Math.cos(x) * Math.sin(y);
                                   } else if (i == 1 && j == 0) {
                                      return -Math.cos(x) * Math.sin(y);
                                   } else if (i == 1 && j == 1) {
                                      return -Math.sin(x) * Math.cos(y);
                                   }
                                }
               });
     ourObject.setFunction(funct);
 
Alternatively, one may use the following code where the functions defining the derivatives are provided by name:

     importClass(org.bzdev.RealValuedFunctionVA);
     ...
     function f(array) {
        var x = array[0]; var y = array[1];
        return Math.sin(x) * Math.cos(y);
     }
     function f1(i, array) {
        var x = array[0]; var y = array[1];
        if (i == 0) {
           return Math.cos(x) * Math.cos(y);
        } else if (i == 1) {
           return - Math.sin(x)*Math.sin(y);
        }
     }
     function f2(i,j,array) {
        var x = array[0]; var y = array[1];
        if (i == 0 && j == 0) {
           return -Math.sin(x)*Math.cos(y);
        } else if (i == 0 && j == 1) {
           return -Math.cos(x)*Math.sin(y);
        } else if (i == 1 && j == 0) {
           return -Math.cos(x)*Math.sin(y);
        } else if (i == 1 && j == 1) {
           return -Math.sin(x) * Math.sin(y);
        }
     }
     // assume ourObject is a Java class with a method setFunction
     // that takes a RealValuedFunction as its argument.
     funct = new RealValuedFunctionVA(scripting, "f", "f1", "f2");
     ourObject.setFunction(funct);
 
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Class representing a real-valued function of the form f(x,β1,...) = ∑i βifi(x).
  • Constructor Summary

    Constructors
    Constructor
    Description
    RealValuedFunctionVA(int minArgLength, int maxArgLength)
    Constructor.
    RealValuedFunctionVA(int minArgLength, int maxArgLength, ScriptingContext scriptingContext, Object object)
    Constructor when the function is provided by a script object.
    RealValuedFunctionVA(int minArgLength, int maxArgLength, ScriptingContext scriptingContext, String fname, String derivName, String secondDerivName)
    Constructor when the function is provided by a script.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    derivAt(int i, double... args)
    Evaluate the partial derivative $\frac{\partial f}{\partial x_i}$ for a function f(x0,x1, ...).
    boolean
    domainMaxClosed(int argIndex)
    Determine if the domain maximum for the ith argument, when the arguments are in the domain of the function, is in the function's domain.
    boolean
    domainMinClosed(int argIndex)
    Determine if the domain minimum for the ith argument, when the arguments are in the domain of the function, is in the function's domain.
    double
    getDomainMax(int argIndex)
    Get the least upper bound of the ith argument when the arguments are in the domain of the function.
    double
    getDomainMin(int argIndex)
    Get the greatest lower bound of the ith argument when the arguments are in the domain of the function.
    boolean
    isInDomain(double... args)
    Determine if a point is within the domain of this function.
    double[]
    jacobian(double... args)
    Compute the Jacobian of this function.
    double[]
    jacobian(int offset, double... args)
    Compute the Jacobian of this function, ignoring the derivatives for some initial arguments.
    int
    Get the maximum number of arguments allowed in calls to methods whose arguments are in the domain of a function implementing this interface.
    int
    Get the minimum number of arguments allowed in calls to methods whose arguments are in the domain of a function implementing this interface.
    double
    secondDerivAt(int i, int j, double... args)
    Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_i \partial z_j}$ for a function f(x0,x1, ...).
    double
    valueAt(double... args)
    Call the function.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • RealValuedFunctionVA

      public RealValuedFunctionVA(int minArgLength, int maxArgLength)
      Constructor.
      Parameters:
      minArgLength - the minimum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
      maxArgLength - the mmaximum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
    • RealValuedFunctionVA

      public RealValuedFunctionVA(int minArgLength, int maxArgLength, ScriptingContext scriptingContext, Object object)
      Constructor when the function is provided by a script object. The parameter 'object' is expected to be either an instance of RealValuedFunctionVA or an object defined by a scripting language with methods named "valueAt", "deri1At", and secondDerivAt. Each of these methods takes an array of real numbers as its last argument, and returns a number. The method deriv1At has an integer as its first argument - an index i indicating that the derivative is computed with respect to xi. The method secondDerivAt has an integer as its first argument and an integer as its second argument - an index i and an index j indicating the the derivative is a second partial derivative with respect to xi and xj. For a real-valued function f(x0,x1,...), these methods are defined as follows:
      • valueAt returns f(x0,x1,...) with the values x0... stored in a Java array that provides valueAt's argument(s).
      • derivAt returns $\frac{\partial f}{\partial x_i}$ evaluated at the point (x0,x1, ...), where i is the index into the array indicating the argument with respect to which differentiation occures. The values x0... are stored in an array and provide the point at which the derivative is evaluated.
      • secondDerivAt returns $\frac{\partial^2 f}{\partial x_i \partial x_j}$ evaluated at the point (x0,x1,...), where i and j are indices into the array containing the arguments and indicate with respect to which arguments the differentiation occurs. The values x0... are stored in an array.
      Except for the integer-valued indices, all the arguments for these methods are double-precision numbers. If one of these methods is not defined, an UnsupportedOperationException may be thrown when the current object's method of the same name is called.

      The object that the scripting language provides can also define several other methods:

        getDomainMin returns the greatest lower bound for the ith component xi of the points in the function's domain, where i is the argument passed to this method. domainMinClosed returns true if there exists a point in the function's domain whose ith component is equal to the greatest lower bound for that component. The integer index i is this method's sole argument. getDomainMax returns the least upper bound for the ith component xi of the poinst in the function's domain, where i is the argument passed to this method. domainMaxClosed returns true if there exists a point in the function's domain whose ith component is equal to the least upper bound for that component. The integer index i is this method's sole argument. isInDomain returns true if a point is in this function's domain and false if does not. The point is passed as an argument consisting of an array containing the coordinates of this point (x0, x1, ...).
      Parameters:
      minArgLength - the minimum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
      maxArgLength - the mmaximum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
      scriptingContext - the scripting context
      object - an object from a scripting environment defining the methods defined above or a subset of those methods
    • RealValuedFunctionVA

      public RealValuedFunctionVA(int minArgLength, int maxArgLength, ScriptingContext scriptingContext, String fname, String derivName, String secondDerivName)
      Constructor when the function is provided by a script. The script is expected to define up to three functions, indicated by their names. These functions (when not null) must satisfy the following conditions:
      • the scripting-language function whose name is the fname argument of this method returns f(x0,x1,...) with the values x0... stored in a Java array that provides valueAt's argument.
      • the scripting-language function whose name is the derivName argument of this method returns $\frac{\partial f}{\partial x_i}$ evaluated at the point (x0,x1, ...), where i is the first argument and the values x0... are stored in a Java array that provides the second argument for derivAt.
      • the scripting-language function whose name is the secondDerivName argument of this method returns $\frac{\partial^2 f}{\partial x_i \partial x_j}$ evaluated at the point (x0,x1,...), where i is the first argument, j is the second argument, and the values x0... are stored in a Java array that provides the third argument for secondDerivAt.
      Parameters:
      minArgLength - the minimum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
      maxArgLength - the mmaximum number of double-precision arguments for methods that allow a variable number of arguments; -1 for the default
      scriptingContext - the scripting context
      fname - the name of a scripting-language function; null if the valueAt method is not supported
      derivName - the name of a scripting-language function providing the desired function's first derivative; null if the deriv1At method is not supported
      secondDerivName - the name of a scripting-language function providing the desired function's second derivative; null if the secondDerivAt method is not supported a
  • Method Details

    • getDomainMin

      public double getDomainMin(int argIndex) throws IllegalArgumentException, IllegalStateException
      Get the greatest lower bound of the ith argument when the arguments are in the domain of the function. The implementation will either return the most negative double-precision number or the result of calling a method named getDomainMin (with the same arguments as this method) provided by an object created by a scripting language. If an object created via a scripting language is not passed to a constructor, and a different value is appropriate, this method should be overridden.
      Specified by:
      getDomainMin in interface VADomainOps
      Parameters:
      argIndex - the index determining the argument for which this method applies (0th, 1st, ...)
      Returns:
      the minimum value
      Throws:
      IllegalArgumentException - the argument is out of range
      IllegalStateException - the function was not fully initialized.
    • getDomainMax

      public double getDomainMax(int argIndex) throws IllegalArgumentException, IllegalStateException
      Get the least upper bound of the ith argument when the arguments are in the domain of the function. The implementation will either return the largest double-precision number or the result of calling a method named getDomainMax (with the same arguments as this method) provided by an object created by a scripting language. If an object created via a scripting language is not passed to a constructor, and a different value is appropriate, this method should be overridden.
      Specified by:
      getDomainMax in interface VADomainOps
      Parameters:
      argIndex - the index determining the argument for which this method applies (0th, 1st, ...)
      Returns:
      the maximum value
      Throws:
      IllegalArgumentException - the argument is out of range
      IllegalStateException - the function was not fully initialized.
    • domainMinClosed

      public boolean domainMinClosed(int argIndex) throws IllegalArgumentException, IllegalStateException
      Determine if the domain minimum for the ith argument, when the arguments are in the domain of the function, is in the function's domain. The implementation will either return true or the result of calling a method named getDomainMinClosed (with the same arguments as this method) provided by an object created by a scripting language. If an object created via a scripting language is not passed to a constructor, and a different value is appropriate, this method should be overridden.
      Specified by:
      domainMinClosed in interface VADomainOps
      Parameters:
      argIndex - the index determining the argument for which this method applies (0th, 1st, ...)
      Returns:
      true if the domain minimum is in the domain; false if it is the greatest lower bound for the domain
      Throws:
      IllegalArgumentException - the argument is out of range
      IllegalStateException - the function was not fully initialized.
    • domainMaxClosed

      public boolean domainMaxClosed(int argIndex) throws IllegalArgumentException, IllegalStateException
      Determine if the domain maximum for the ith argument, when the arguments are in the domain of the function, is in the function's domain. The implementation will either return true or the result of calling a method named getDomainMaxClosed (with the same arguments as this method) provided by an object created by a scripting language. If an object created via a scripting language is not passed to a constructor, and a different value is appropriate, this method should be overridden.
      Specified by:
      domainMaxClosed in interface VADomainOps
      Parameters:
      argIndex - the index determining the argument for which this method applies (0th, 1st, ...)
      Returns:
      true if the domain maximum is in the domain; false if it is the least upper bound for the domain
      Throws:
      IllegalArgumentException - the argument is out of range
      IllegalStateException - the function was not fully initialized.
    • minArgLength

      public int minArgLength()
      Description copied from interface: VADomainOps
      Get the minimum number of arguments allowed in calls to methods whose arguments are in the domain of a function implementing this interface. A subclass must not return a value less than 1.
      Specified by:
      minArgLength in interface RealValuedFunctVAOps
      Specified by:
      minArgLength in interface VADomainOps
      Returns:
      the minimum number of arguments
    • maxArgLength

      public int maxArgLength()
      Description copied from interface: VADomainOps
      Get the maximum number of arguments allowed in calls to methods whose arguments are in the domain of a function implementing this interface.
      Specified by:
      maxArgLength in interface RealValuedFunctVAOps
      Specified by:
      maxArgLength in interface VADomainOps
      Returns:
      the maximum number of arguments
    • isInDomain

      public boolean isInDomain(double... args) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException
      Determine if a point is within the domain of this function.

      The default behavior of this method assumes the domain is a rectangular region and uses the methods getDomainMin(int), getDomainMax(int), domainMinClosed(int), domainMaxClosed(int), to determine if the arguments represent a point in the functions domain. If the domain is not rectangular with each side either in or not in the domain, then this method must be overridden. If it is not possible with a reasonable amount of computation to determine that a point is in the domain, an UnsupportedOperationException may be thrown. If this exception is thrown, it should be thrown regardless of the arguments.

      Specified by:
      isInDomain in interface VADomainOps
      Parameters:
      args - the arguments (x0,x1,...) giving the coordinates of a point
      Returns:
      true if the point (x0,x1,...) is in this function's domain; false otherwise
      Throws:
      UnsupportedOperationException - domain membership could not be determined.
      IllegalArgumentException - an argument is out of range
      IllegalStateException - the function was not fully initialized.
    • valueAt

      public double valueAt(double... args) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Call the function.
      Specified by:
      valueAt in interface RealValuedFunctVAOps
      Parameters:
      args - the function's arguments
      Returns:
      the value of the function for the given arguments
      Throws:
      IllegalArgumentException - the function's argument(s) were out of range
      UnsupportedOperationException - the operation is not supported.
      IllegalStateException - the function was not fully initialized.
    • jacobian

      public double[] jacobian(double... args) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Compute the Jacobian of this function. Because this is a limiting case (a 1 by n matrix, where n is the number of arguments), the Jacobian is stored as a one-dimensional array. Java represents two dimensional arrays as nested one dimensional arrays, so to compute the Jacobian for a vector of m functions, one would could use the following code:
           RealValuedFunctionVA[] farray = {f1, f2, ... fm};
           double[][] J = new double[farray.length][];
           for (int i = 0; i < farray.length; i++) {
               J[i] = farray[i].jacobian(x1, x2, x3, ...);
           }
       
      Parameters:
      args - the arguments to the function.
      Returns:
      the Jacobian
      Throws:
      IllegalArgumentException - the function's argument(s) were out of range
      UnsupportedOperationException - the operation is not supported.
      IllegalStateException - the function was not fully initialized.
    • jacobian

      public double[] jacobian(int offset, double... args) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Compute the Jacobian of this function, ignoring the derivatives for some initial arguments. Because this is a limiting case (a 1 by n matrix, where n is the number of arguments minus a specified offset), the Jacobian is stored as a one-dimensional array. The length of the vector is reduced by stripping off the first elements of the vector that would be returned by jacobian(double...).

      Java represents two dimensional arrays as nested one dimensional arrays, so to compute the Jacobian for a vector of m functions, one would could use the following code:

           RealValuedFunctionVA[] farray = {f1, f2, ... fm};
           double[][] J = new double[farray.length][];
           for (int i = 0; i < farray.length; i++) {
               J[i] = farray[i].jacobian(1,x,beta0, beta1, ...);
           }
       
      if the functions f1, ... fm are functions of x, β1, β2, ..., the call to jacobian(1, x, ...) causes the argument x to be treated as a constant.

      Note: this method is useful when using the Gauss-Newton method for finding the parameters for a non-linear least-squares fit.

      Parameters:
      offset - the offset determining the variable at which to start differentiating
      args - the arguments to the function.
      Returns:
      the Jacobian
      Throws:
      IllegalArgumentException - the function's argument(s) were out of range
      UnsupportedOperationException - the operation is not supported.
      IllegalStateException - the function was not fully initialized.
    • derivAt

      public double derivAt(int i, double... args) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial f}{\partial x_i}$ for a function f(x0,x1, ...).
      Parameters:
      i - the index indicating that the partial derivative is computed for the ith argument, numbered from zero
      args - the function f's arguments
      Returns:
      the value of the partial derivative for the given argument
      Throws:
      IllegalArgumentException - the function's argument(s) were out of range
      UnsupportedOperationException - the operation is not supported.
      IllegalStateException - the function was not fully initialized.
    • secondDerivAt

      public double secondDerivAt(int i, int j, double... args) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_i \partial z_j}$ for a function f(x0,x1, ...).
      Parameters:
      i - the index indicating that the partial derivative is computed for the ith argument, numbered from 0
      j - the index indicating that the partial derivative is computed for the jth argument, numbered from 0
      args - the function f's arguments
      Returns:
      the value of the partial derivative $\frac{\partial^2 f}{\partial x_i \partial z_j}$ for the given arguments x0, x1, ...
      Throws:
      IllegalArgumentException - the function's arguments were out of range
      UnsupportedOperationException - the operation is not supported.
      IllegalStateException - the function was not fully initialized.