DoubleFunctions
cern.jet.math.tdouble

Class DoubleFunctions



  • public class DoubleFunctionsextends Object
    Function objects to be passed to generic methods. Contains the functions of Math as function objects, as well as a few more basic functions.

    Function objects conveniently allow to express arbitrary functions in a generic manner. Essentially, a function object is an object that can perform a function on some arguments. It has a minimal interface: a method apply that takes the arguments, computes something and returns some result value. Function objects are comparable to function pointers in C used for call-backs.

    Unary functions are of type DoubleFunction , binary functions of type DoubleDoubleFunction. All can be retrieved via public static final variables named after the function. Unary predicates are of type DoubleProcedure, binary predicates of type DoubleDoubleProcedure. All can be retrieved via public static final variables named isXXX.

    Binary functions and predicates also exist as unary functions with the second argument being fixed to a constant. These are generated and retrieved via factory methods (again with the same name as the function). Example:

    • Functions.pow gives the function ab.
    • Functions.pow.apply(2,3)==8.
    • Functions.pow(3) gives the function a3.
    • Functions.pow(3).apply(2)==8.
    More general, any binary function can be made an unary functions by fixing either the first or the second argument. See methods bindArg1(DoubleDoubleFunction,double) and bindArg2(DoubleDoubleFunction,double). The order of arguments can be swapped so that the first argument becomes the second and vice-versa. See method swapArgs(DoubleDoubleFunction). Example:
    • Functions.pow gives the function ab.
    • Functions.bindArg2(Functions.pow,3) gives the function x3.
    • Functions.bindArg1(Functions.pow,3) gives the function 3x.
    • Functions.swapArgs(Functions.pow) gives the function ba.

    Even more general, functions can be chained (composed, assembled). Assume we have two unary functions g and h. The unary function g(h(a)) applying both in sequence can be generated via chain(DoubleFunction,DoubleFunction):

    • Functions.chain(g,h);
    Assume further we have a binary function f. The binary function g(f(a,b)) can be generated via chain(DoubleFunction,DoubleDoubleFunction):
    • Functions.chain(g,f);
    The binary function f(g(a),h(b)) can be generated via chain(DoubleDoubleFunction,DoubleFunction,DoubleFunction):
    • Functions.chain(f,g,h);
    Arbitrarily complex functions can be composed from these building blocks. For example sin(a) + cos2(b) can be specified as follows:
    • chain(plus,sin,chain(square,cos));
    or, of course, as
     new DoubleDoubleFunction() {     public final double apply(double a, double b) {         return Math.sin(a) + Math.pow(Math.cos(b), 2);     } } 

    For aliasing see functions. Try this

     // should yield 1.4399560356056456 in all cases double a = 0.5; double b = 0.2; double v = Math.sin(a) + Math.pow(Math.cos(b), 2); System.out.println(v); Functions F = Functions.functions; DoubleDoubleFunction f = F.chain(F.plus, F.sin, F.chain(F.square, F.cos)); System.out.println(f.apply(a, b)); DoubleDoubleFunction g = new DoubleDoubleFunction() {     public double apply(double a, double b) {         return Math.sin(a) + Math.pow(Math.cos(b), 2);     } }; System.out.println(g.apply(a, b)); 

    Performance

    Surprise. Using modern non-adaptive JITs such as SunJDK 1.2.2 (java -classic) there seems to be no or only moderate performance penalty in using function objects in a loop over traditional code in a loop. For complex nested function objects (e.g. F.chain(F.abs,F.chain(F.plus,F.sin,F.chain(F.square,F.cos)))) the penalty is zero, for trivial functions (e.g. F.plus) the penalty is often acceptable.
    Iteration Performance [million function evaluations per second]
    Pentium Pro 200 Mhz, SunJDK 1.2.2, NT, java -classic,
     

    30000000 iterations

    3000000 iterations (10 times less)  
    F.plus a+b F.chain(F.abs,F.chain(F.plus,F.sin,F.chain(F.square,F.cos))) Math.abs(Math.sin(a) + Math.pow(Math.cos(b),2))    
      10.8 29.6 0.43 0.35    
    • Field Detail

      • functions

        public static final DoubleFunctions functions
        Little trick to allow for "aliasing", that is, renaming this class. Writing code like

        Functions.chain(Functions.plus,Functions.sin,Functions.chain(Functions.square,Functions.cos));

        is a bit awkward, to say the least. Using the aliasing you can instead write

        Functions F = Functions.functions;
        F.chain(F.plus,F.sin,F.chain(F.square,F.cos));

      • abs

        public static final DoubleFunction abs
        Function that returns Math.abs(a).
      • acos

        public static final DoubleFunction acos
        Function that returns Math.acos(a).
      • asin

        public static final DoubleFunction asin
        Function that returns Math.asin(a).
      • atan

        public static final DoubleFunction atan
        Function that returns Math.atan(a).
      • ceil

        public static final DoubleFunction ceil
        Function that returns Math.ceil(a).
      • cos

        public static final DoubleFunction cos
        Function that returns Math.cos(a).
      • exp

        public static final DoubleFunction exp
        Function that returns Math.exp(a).
      • floor

        public static final DoubleFunction floor
        Function that returns Math.floor(a).
      • identity

        public static final DoubleFunction identity
        Function that returns its argument.
      • inv

        public static final DoubleFunction inv
        Function that returns 1.0 / a.
      • log

        public static final DoubleFunction log
        Function that returns Math.log(a).
      • log2

        public static final DoubleFunction log2
        Function that returns Math.log(a) / Math.log(2).
      • rint

        public static final DoubleFunction rint
        Function that returns Math.rint(a).
      • sign

        public static final DoubleFunction sign
        Function that returns a < 0 ? -1 : a > 0 ? 1 : 0.
      • sin

        public static final DoubleFunction sin
        Function that returns Math.sin(a).
      • sqrt

        public static final DoubleFunction sqrt
        Function that returns Math.sqrt(a).
      • square

        public static final DoubleFunction square
        Function that returns a * a.
      • tan

        public static final DoubleFunction tan
        Function that returns Math.tan(a).
      • compare

        public static final DoubleDoubleFunction compare
        Function that returns a < b ? -1 : a > b ? 1 : 0.
      • IEEEremainder

        public static final DoubleDoubleFunction IEEEremainder
        Function that returns Math.IEEEremainder(a,b).
      • plusAbs

        public static final DoubleDoubleFunction plusAbs
        Function that returns Math.abs(a) + Math.abs(b).
    • Method Detail

      • between

        public static DoubleFunction between(double from,                     double to)
        Constructs a function that returns (from<=a && a<=to) ? 1 : 0. a is a variable, from and to are fixed.
      • bindArg1

        public static DoubleFunction bindArg1(DoubleDoubleFunction function,                      double c)
        Constructs a unary function from a binary function with the first operand (argument) fixed to the given constant c. The second operand is variable (free).
        Parameters:
        function - a binary function taking operands in the form function.apply(c,var).
        Returns:
        the unary function function(c,var).
      • bindArg2

        public static DoubleFunction bindArg2(DoubleDoubleFunction function,                      double c)
        Constructs a unary function from a binary function with the second operand (argument) fixed to the given constant c. The first operand is variable (free).
        Parameters:
        function - a binary function taking operands in the form function.apply(var,c).
        Returns:
        the unary function function(var,c).
      • compare

        public static DoubleFunction compare(double b)
        Constructs a function that returns a < b ? -1 : a > b ? 1 : 0. a is a variable, b is fixed.
      • constant

        public static DoubleFunction constant(double c)
        Constructs a function that returns the constant c.
      • demo1

        public static void demo1()
        Demonstrates usage of this class.
      • demo2

        public static void demo2(int size)
        Benchmarks and demonstrates usage of trivial and complex functions.
      • div

        public static DoubleFunction div(double b)
        Constructs a function that returns a / b. a is a variable, b is fixed.
      • equals

        public static DoubleFunction equals(double b)
        Constructs a function that returns a == b ? 1 : 0. a is a variable, b is fixed.
      • greater

        public static DoubleFunction greater(double b)
        Constructs a function that returns a > b ? 1 : 0. a is a variable, b is fixed.
      • IEEEremainder

        public static DoubleFunction IEEEremainder(double b)
        Constructs a function that returns Math.IEEEremainder(a,b). a is a variable, b is fixed.
      • isBetween

        public static DoubleProcedure isBetween(double from,                        double to)
        Constructs a function that returns from<=a && a<=to. a is a variable, from and to are fixed.
      • isEqual

        public static DoubleProcedure isEqual(double b)
        Constructs a function that returns a == b. a is a variable, b is fixed.
      • isGreater

        public static DoubleProcedure isGreater(double b)
        Constructs a function that returns a > b. a is a variable, b is fixed.
      • isLess

        public static DoubleProcedure isLess(double b)
        Constructs a function that returns a < b. a is a variable, b is fixed.
      • less

        public static DoubleFunction less(double b)
        Constructs a function that returns a < b ? 1 : 0. a is a variable, b is fixed.
      • lg

        public static DoubleFunction lg(double b)
        Constructs a function that returns Math.log(a) / Math.log(b) . a is a variable, b is fixed.
      • max

        public static DoubleFunction max(double b)
        Constructs a function that returns Math.max(a,b). a is a variable, b is fixed.
      • min

        public static DoubleFunction min(double b)
        Constructs a function that returns Math.min(a,b). a is a variable, b is fixed.
      • minus

        public static DoubleFunction minus(double b)
        Constructs a function that returns a - b. a is a variable, b is fixed.
      • minusMult

        public static DoubleDoubleFunction minusMult(double constant)
        Constructs a function that returns a - b*constant. a and b are variables, constant is fixed.
      • mod

        public static DoubleFunction mod(double b)
        Constructs a function that returns a % b. a is a variable, b is fixed.
      • mult

        public static DoubleFunction mult(double b)
        Constructs a function that returns a * b. a is a variable, b is fixed.
      • plus

        public static DoubleFunction plus(double b)
        Constructs a function that returns a + b. a is a variable, b is fixed.
      • multSecond

        public static DoubleDoubleFunction multSecond(double constant)
        Constructs a function that returns b*constant.
      • plusMultSecond

        public static DoubleDoubleFunction plusMultSecond(double constant)
        Constructs a function that returns a + b*constant. a and b are variables, constant is fixed.
      • plusMultFirst

        public static DoubleDoubleFunction plusMultFirst(double constant)
        Constructs a function that returns a * constant + b. a and b are variables, constant is fixed.
      • pow

        public static DoubleFunction pow(double b)
        Constructs a function that returns Math.pow(a,b). a is a variable, b is fixed.
      • random

        public static DoubleFunction random()
        Constructs a function that returns a new uniform random number in the open unit interval (0.0,1.0) (excluding 0.0 and 1.0). Currently the engine is DoubleMersenneTwister and is seeded with the current time.

        Note that any random engine derived from DoubleRandomEngine and any random distribution derived from AbstractDoubleDistribution are function objects, because they implement the proper interfaces. Thus, if you are not happy with the default, just pass your favourite random generator to function evaluating methods.

      • round

        public static DoubleFunction round(double precision)
        Constructs a function that returns the number rounded to the given precision; Math.rint(a/precision)*precision. Examples:
         precision = 0.01 rounds 0.012 --> 0.01, 0.018 --> 0.02 precision = 10   rounds 123   --> 120 , 127   --> 130 
      • swapArgs

        public static DoubleDoubleFunction swapArgs(DoubleDoubleFunction function)
        Constructs a function that returns function.apply(b,a), i.e. applies the function with the first operand as second operand and the second operand as first operand.
        Parameters:
        function - a function taking operands in the form function.apply(a,b).
        Returns:
        the binary function function(b,a).

SCaVis 2.2 © jWork.ORG