Documentation API of the 'cern.jet.math.Functions' Java class
Functions
cern.jet.math

Class Functions



  • public class Functionsextends 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 examplesin(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 casesdouble 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    

Warning: You cannot see the full API documentation of this class since the access to the DatMelt documentation for third-party Java classes is denied. Guests can only view jhplot Java API. To view the complete description of this class and its methods, please request the full DataMelt membership.

If you are already a full member, please login to the DataMelt member area before visiting this documentation.