Class RealValuedFunctionTwo

java.lang.Object
org.bzdev.math.RealValuedFunctionVA
org.bzdev.math.RealValuedFunctionTwo
All Implemented Interfaces:
DoubleBinaryOperator, RealValuedFunctTwoOps, RealValuedFunctVAOps, VADomainOps
Direct Known Subclasses:
BicubicInterpolator, BicubicTriangleInterp

public class RealValuedFunctionTwo extends RealValuedFunctionVA implements RealValuedFunctTwoOps
Class defining a real-valued function with two real 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, deriv1At, deriv2At, deriv11At, deriv12At, deriv21At, and deriv22At to provide the values for a function and its first and second partial derivative. 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 function and its derivatives:


     importClass(org.bzdev.RealValuedFunctionTwo);
     ....
     // assume ourObject is a Java class with a method setFunction
     // that takes a RealValuedFunctionTwo as its argument.
     funct = new RealValuedFunctionTwo(scripting,
               {valueAt: function(x,y) {return Math.sin(x) * Math.cos(y);},
                deriv1At: function(x,y) {return Math.cos(x) * Math.cos(y);},
                deriv2At: function(x,y) {return -Math.sin(x) * Math.sin(y);},
                deriv11At: function(x,y) {return -Math.sin(x) * Math.cos(y);},
                deriv12At: function(x,y) {return -Math.cos(x) * Math.sin(y);},
                deriv21At: function(x,y) {return -Math.cos(x) * Math.sin(y);},
                deriv22At: function(x,y) {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.RealValuedFunctionTwo);
     ...
     function f(x,y) {return Math.sin(x) * Math.cos(y);}
     function f1(x,y) {return Math.cos(x) * Math.cos(y);}
     function f2(x,y) {return -Math.sin(x) * Math.sin(y);}
     function f11(x,y) {return -Math.sin(x) * Math.cos(y);}
     function f12(x,y) {return  -Math.cos(x) * Math.sin(y);}
     function f21(x,y) {return -Math.cos(x) * Math.sin(y);}
     function f22(x,y) {return -Math.sin(x) * Math.cos(y);}
     ...
     // assume ourObject is a Java class with a method setFunction
     // that takes a RealValuedFunction as its argument.
     funct = new RealValuedFunction(scripting, "f", "f1", "f2",
                                      "f11", "f12", "f21", "f22");
     ourObject.setFunction(funct);
 
  • Constructor Details

    • RealValuedFunctionTwo

      public RealValuedFunctionTwo()
      Constructor.
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(RealValuedFunctTwoOps function)
      Constructor given a function that determines its value. The argument implements RealValuedFunctTwoOps and can be a lambda expression with two arguments. The interface RealValuedFunctTwoOps provides a single method: RealValuedFunctTwoOps.valueAt(double,double) that, when called, provides the function's value.
      Parameters:
      function - the function providing the value for the method valueAt; null if the valueAt method is not supported
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(RealValuedFunctTwoOps function, RealValuedFunctTwoOps function1, RealValuedFunctTwoOps function2)
      Constructor given functions that determines its value and its first partial derivatives. The arguments implement RealValuedFunctTwoOps and can be a lambda expression with two arguments. The interface RealValuedFunctTwoOps provides a single method: RealValuedFunctTwoOps.valueAt(double,double) that, when called, provides the function's value.
      Parameters:
      function - the function providing the value for the method valueAt; null if the valueAt method is not supported
      function1 - the function providing the value for the method {#link #deriv1At(double,double)}; null if the deriv1At method is not supported
      function2 - the function providing the value for the method {#link #deriv2At(double,double)}; null if the deriv2At method is not supported
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(RealValuedFunctTwoOps function, RealValuedFunctTwoOps function1, RealValuedFunctTwoOps function2, RealValuedFunctTwoOps function11, RealValuedFunctTwoOps function12, RealValuedFunctTwoOps function21, RealValuedFunctTwoOps function22)
      Constructor given functions that determines its value and its first and second partial derivatives The arguments implement RealValuedFunctTwoOps and can be a lambda expression with two arguments. The interface RealValuedFunctTwoOps provides a single method: RealValuedFunctTwoOps.valueAt(double,double) that, when called, provides the function's value.
      Parameters:
      function - the function providing the value for the method valueAt; null if the valueAt method is not supported
      function1 - the function providing the value for the method deriv1At(double,double); null if the deriv1At method is not supported
      function2 - the function providing the value for the method deriv2At(double,double); null if the deriv2At method is not supported
      function11 - the function providing the value for the method deriv11At(double,double); null if the deriv11At method is not supported
      function12 - thea function providing the value for the method deriv12At(double,double); null if the deriv12At method is not supported
      function21 - the function providing the value for the method deriv21At(double,double); null if the deriv21At method is not supported
      function22 - the function providing the value for the method deriv22At(double,double); null if the deriv22At method is not supported
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(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 RealValuedFunctionTwo or an object defined by a scripting language with methods named "valueAt", "deriv1At" "deriv2At", "deriv11At", "deriv12At", deriv21At", and "deriv22At". Each of these methods takes two arguments, both real numbers, and returns a number. For a real-valued function f(x1,x2), these methods are defined as follows:
      • valueAt returns f(x1,x2).
      • deriv1At returns ∂f/∂x1 evaluated at the point (x1,x2).
      • deriv2At returns ∂f/∂x2 evaluated at the point (x1,x2).
      • deriv11At returns ∂2f/∂x12 evaluated at the point (x1,x2).
      • deriv12At returns ∂2f/∂x1∂x2 evaluated at the point (x1,x2).
      • deriv21At returns ∂2f/∂x2∂x1 evaluated at the point (x1,x2).
      • deriv22At returns ∂2f/∂x12 evaluated at the point (x1,x2).
      Parameters:
      scriptingContext - the scripting context
      object - an object from a scripting environment defining the methods defined above or a subset of those methods
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(ScriptingContext scriptingContext, String fname, String f1name, String f2name)
      Constructor when the function and its first partial derivatives are provided by a script. The script is expected to define up to three functions, indicated by their names.
      Parameters:
      scriptingContext - the scripting context
      fname - the name of a function providing the value for the method valueAt; null if the valueAt method is not supported
      f1name - the name of a function providing the value for the method deriv1At(double,double); null if the deriv1At method is not supported
      f2name - the name of a function providing the value for the method deriv2At(double,double); null if the deriv2At method is not supported
    • RealValuedFunctionTwo

      public RealValuedFunctionTwo(ScriptingContext scriptingContext, String fname, String f1name, String f2name, String f11name, String f12name, String f21name, String f22name)
      Constructor when the function and its first and second partial derivatives are provided by a script. The script is expected to define up to seven functions, indicated by their names.
      Parameters:
      scriptingContext - the scripting context
      fname - the name of a function providing the value for the method valueAt; null if the valueAt method is not supported
      f1name - the name of a function providing the value for the method deriv1At(double,double); null if the deriv1At method is not supported
      f2name - the name of a function providing the value for the method deriv2At(double,double); null if the deriv2At method is not supported
      f11name - the name of a function providing the value for the method deriv11At(double,double); null if the deriv11At method is not supported
      f12name - the name of a function providing the value for the method deriv12At(double,double); null if the deriv12At method is not supported
      f21name - the name of a function providing the value for the method deriv21At(double,double); null if the deriv21At method is not supported
      f22name - the name of a function providing the value for the method deriv22At(double,double); null if the deriv22At method is not supported
  • Method Details

    • getDomainMin

      public final double getDomainMin(int i) throws IllegalArgumentException, IllegalStateException
      Description copied from class: RealValuedFunctionVA
      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
      Overrides:
      getDomainMin in class RealValuedFunctionVA
      Parameters:
      i - 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 final double getDomainMax(int i) throws IllegalArgumentException, IllegalStateException
      Description copied from class: RealValuedFunctionVA
      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
      Overrides:
      getDomainMax in class RealValuedFunctionVA
      Parameters:
      i - 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 final boolean domainMinClosed(int i) throws IllegalArgumentException, IllegalStateException
      Description copied from class: RealValuedFunctionVA
      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
      Overrides:
      domainMinClosed in class RealValuedFunctionVA
      Parameters:
      i - 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 final boolean domainMaxClosed(int i) throws IllegalArgumentException, IllegalStateException
      Description copied from class: RealValuedFunctionVA
      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
      Overrides:
      domainMaxClosed in class RealValuedFunctionVA
      Parameters:
      i - 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.
    • getDomainMin1

      public double getDomainMin1() throws IllegalStateException
      Get the minimum value of the first argument in the domain of the function.
      Returns:
      the minimum value
      Throws:
      IllegalStateException - the function was not fully initialized.
    • getDomainMax1

      public double getDomainMax1() throws IllegalStateException
      Get the maximum value of the first argument in the domain of the function.
      Returns:
      the maximum value
      Throws:
      IllegalStateException - the function was not fully initialized.
    • getDomainMin2

      public double getDomainMin2() throws IllegalStateException
      Get the minimum value of the second argument in the domain of the function.
      Returns:
      the minimum value
      Throws:
      IllegalStateException - the function was not fully initialized.
    • getDomainMax2

      public double getDomainMax2() throws IllegalStateException
      Get the maximum value of the second argument in the domain of the function.
      Returns:
      the maximum value
      Throws:
      IllegalStateException - the function was not fully initialized.
    • domainMin1Closed

      public boolean domainMin1Closed() throws IllegalStateException
      Determine if the domain minimum for the first argument is in the domain.
      Returns:
      true if the domain minimum is in the domain; false if it is the greatest lower bound for the domain
      Throws:
      IllegalStateException - the function was not fully initialized.
    • domainMax1Closed

      public boolean domainMax1Closed() throws IllegalStateException
      Determine if the domain maximum for the first argument is in the domain.
      Returns:
      true if the domain maximum is in the domain; false if it is the least upper bound for the domain
      Throws:
      IllegalStateException - the function was not fully initialized.
    • domainMin2Closed

      public boolean domainMin2Closed() throws IllegalStateException
      Determine if the domain minimum for the second argument is in the domain.
      Returns:
      true if the domain minimum is in the domain; false if it is the greatest lower bound for the domain
      Throws:
      IllegalStateException - the function was not fully initialized.
    • domainMax2Closed

      public boolean domainMax2Closed() throws IllegalStateException
      Determine if the domain maximum for the second argument is in the domain.
      Returns:
      true if the domain maximum is in the domain; false if it is the least upper bound for the domain
      Throws:
      IllegalStateException - the function was not fully initialized.
    • isInDomain

      public final boolean isInDomain(double... args) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException
      Description copied from class: RealValuedFunctionVA
      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 RealValuedFunctionVA.getDomainMin(int), RealValuedFunctionVA.getDomainMax(int), RealValuedFunctionVA.domainMinClosed(int), RealValuedFunctionVA.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
      Overrides:
      isInDomain in class RealValuedFunctionVA
      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.
    • isInDomain

      public boolean isInDomain(double x, double y) throws UnsupportedOperationException, IllegalStateException
      Determine if a point (x, y) is within the domain of a real-valued function of two arguments.

      The default behavior of this method assumes the domain is a rectangular region and uses the methods getDomainMin1(), getDomainMin2(), getDomainMax1(), getDomainMax2() domainMin1Closed(), domainMin2Closed(), domainMax1Closed(), and domainMax2Closed() 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.

      Parameters:
      x - the 1st coordinate
      y - the 2nd coordinate
      Returns:
      true if the point (x, y) is in this function's domain; false otherwise
      Throws:
      UnsupportedOperationException - domain membership could not be determined.
      IllegalStateException - the function was not fully initialized.
    • valueAt

      public final double valueAt(double... args) throws IllegalArgumentException, UnsupportedOperationException
      Description copied from class: RealValuedFunctionVA
      Call the function.
      Specified by:
      valueAt in interface RealValuedFunctTwoOps
      Specified by:
      valueAt in interface RealValuedFunctVAOps
      Overrides:
      valueAt in class RealValuedFunctionVA
      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.
    • valueAt

      public double valueAt(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Call the function.
      Specified by:
      valueAt in interface RealValuedFunctTwoOps
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • deriv

      public final RealValuedFunctTwoOps deriv(int i)
      Get a function that computes the value of partial derivative that would be computed by calling derivAt(int,double...).
      Parameters:
      i - an index in the range [0, 1] indicating the argument with which to differentiate
      Returns:
      the function
    • derivAt

      public final 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, ...).

      This method calls a method named deriv<i+1>At(...) where i is the value of the first argument of this method. One should usually override those methods (for (i+1) in [1,2]) instead of this one.

      Overrides:
      derivAt in class RealValuedFunctionVA
      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.
    • deriv1

      public RealValuedFunctTwoOps deriv1()
      Get a function computing $\frac{\partial f}{\partial x_1}$.
      Returns:
      a function that computes $\frac{\partial f}{\partial x_1}$
    • deriv1At

      public double deriv1At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial f}{\partial x_1}$ for a function f(x1, x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • deriv2

      public RealValuedFunctTwoOps deriv2()
      Get a function computing $\frac{\partial f}{\partial x_2}$.
      Returns:
      a function that computes $\frac{\partial f}{\partial x_2}$
    • deriv2At

      public double deriv2At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial f}{\partial x_2}$ for a function f(x1,x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • secondDeriv

      public final RealValuedFunctTwoOps secondDeriv(int i, int j)
      Get a function that computes the value of the second partial derivative that would be computed by calling secondDerivAt(int,int,double...).
      Parameters:
      i - the index of the argument for the first differentiation
      j - the index of the argument for the second differentiation
      Returns:
      the function
    • secondDerivAt

      public final 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, ...).

      This method calls a method named deriv<i+1><j+1<At(...) where i and j are the values of the first two arguments. One should usually override those methods instead of this one.

      Overrides:
      secondDerivAt in class RealValuedFunctionVA
      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.
    • deriv11

      public RealValuedFunctTwoOps deriv11()
      Get a function that computes $\frac{\partial^2 f}{\partial x_1^2}$ where f is this function.
      Returns:
      a function that computes $\frac{\partial^2 f}{\partial x_1^2}$
    • deriv11At

      public double deriv11At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $ \frac{\partial^2 f}{\partial x_1^2}$ for a function f(x1,x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • deriv12

      public RealValuedFunctTwoOps deriv12()
      Get a function that computes $\frac{\partial^2 f}{\partial x_1 \partial x_2}$ where f is this function.
      Returns:
      a function that computes $\frac{\partial^2 f}{\partial x_1 \partial x_2}$
    • deriv12At

      public double deriv12At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_1 \partial x_2}$ for a function f(x1,x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • deriv21

      public RealValuedFunctTwoOps deriv21()
      Get a function that computes $\frac{\partial^2 f}{\partial x_2 \partial x_1}$ where f is this function.
      Returns:
      a function that computes $\frac{\partial^2 f}{\partial x_2 \partial x_1}$
    • deriv21At

      public double deriv21At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2 \partial x_1}$ for a function f(x1,x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.
    • deriv22

      public RealValuedFunctTwoOps deriv22()
      Get a function that computes $\frac{\partial^2 f}{\partial x_2^2}$ where f is this function.
      Returns:
      a function that computes $\frac{\partial^2 f}{\partial x_2^2}$
    • deriv22At

      public double deriv22At(double arg1, double arg2) throws IllegalArgumentException, UnsupportedOperationException, IllegalStateException
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2^2}$ for a function f(x1,x2).
      Parameters:
      arg1 - the function's first argument
      arg2 - the function's second argument
      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.