org.apache.mahout.math.function
Class Functions

java.lang.Object
  extended by org.apache.mahout.math.function.Functions

public class Functions
extends java.lang.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 UnaryFunction, binary functions of type BinaryFunction. 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:

More general, any binary function can be made an unary functions by fixing either the first or the second argument. See methods bindArg1(org.apache.mahout.math.function.BinaryFunction ,double) and bindArg2(org.apache.mahout.math.function.BinaryFunction ,double). The order of arguments can be swapped so that the first argument becomes the second and vice-versa. See method swapArgs(org.apache.mahout.math.function.BinaryFunction). Example:

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(org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.UnaryFunction):

Assume further we have a binary function f. The binary function g(f(a,b)) can be generated via chain(org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.BinaryFunction): The binary function f(g(a),h(b)) can be generated via chain(org.apache.mahout.math.function.BinaryFunction , org.apache.mahout.math.function.UnaryFunction , org.apache.mahout.math.function.UnaryFunction): Arbitrarily complex functions can be composed from these building blocks. For example sin(a) + cos2(b) can be specified as follows: or, of course, as
 new BinaryFunction() {
    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);
 log.info(v);
 Functions F = Functions.functions;
 BinaryFunction f = F.chain(F.plus,F.sin,F.chain(F.square,F.cos));
 log.info(f.apply(a,b));
 BinaryFunction g = new BinaryFunction() {
    public double apply(double a, double b) { return Math.sin(a) + Math.pow(Math.cos(b),2); }
 };
 log.info(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 Summary
static UnaryFunction abs
          Function that returns Math.abs(a).
static UnaryFunction acos
          Function that returns Math.acos(a).
static UnaryFunction asin
          Function that returns Math.asin(a).
static UnaryFunction atan
          Function that returns Math.atan(a).
static BinaryFunction atan2
          Function that returns Math.atan2(a,b).
static UnaryFunction ceil
          Function that returns Math.ceil(a).
static BinaryFunction compare
          Function that returns a < b ? -1 : a > b ? 1 : 0.
static UnaryFunction cos
          Function that returns Math.cos(a).
static BinaryFunction div
          Function that returns a / b.
static BinaryFunction equals
          Function that returns a == b ? 1 : 0.
static UnaryFunction exp
          Function that returns Math.exp(a).
static UnaryFunction floor
          Function that returns Math.floor(a).
static BinaryFunction greater
          Function that returns a > b ? 1 : 0.
static UnaryFunction identity
          Function that returns its argument.
static BinaryFunction IEEEremainder
          Function that returns Math.IEEEremainder(a,b).
static UnaryFunction inv
          Function that returns 1.0 / a.
static DoubleDoubleProcedure isEqual
          Function that returns a == b.
static DoubleDoubleProcedure isGreater
          Function that returns a > b.
static DoubleDoubleProcedure isLess
          Function that returns a < b.
static BinaryFunction less
          Function that returns a < b ? 1 : 0.
static BinaryFunction lg
          Function that returns Math.log(a) / Math.log(b).
static UnaryFunction log2
          Function that returns Math.log(a) / Math.log(2).
static UnaryFunction logarithm
          Function that returns Math.log(a).
static BinaryFunction max
          Function that returns Math.max(a,b).
static BinaryFunction min
          Function that returns Math.min(a,b).
static BinaryFunction minus
          Function that returns a - b.
static BinaryFunction mod
          Function that returns a % b.
static BinaryFunction mult
          Function that returns a * b.
static UnaryFunction negate
          Function that returns -a.
static BinaryFunction plus
          Function that returns a + b.
static BinaryFunction plusAbs
          Function that returns Math.abs(a) + Math.abs(b).
static BinaryFunction pow
          Function that returns Math.pow(a,b).
static UnaryFunction rint
          Function that returns Math.rint(a).
static UnaryFunction sign
          Function that returns a < 0 ? -1 : a > 0 ? 1 : 0.
static UnaryFunction sin
          Function that returns Math.sin(a).
static UnaryFunction sqrt
          Function that returns Math.sqrt(a).
static UnaryFunction square
          Function that returns a * a.
static UnaryFunction tan
          Function that returns Math.tan(a).
 
Method Summary
static UnaryFunction between(double from, double to)
          Constructs a function that returns (from<=a && a<=to) ? 1 : 0.
static UnaryFunction bindArg1(BinaryFunction function, double c)
          Constructs a unary function from a binary function with the first operand (argument) fixed to the given constant c.
static UnaryFunction bindArg2(BinaryFunction function, double c)
          Constructs a unary function from a binary function with the second operand (argument) fixed to the given constant c.
static BinaryFunction chain(BinaryFunction f, UnaryFunction g, UnaryFunction h)
          Constructs the function f( g(a), h(b) ).
static BinaryFunction chain(UnaryFunction g, BinaryFunction h)
          Constructs the function g( h(a,b) ).
static UnaryFunction chain(UnaryFunction g, UnaryFunction h)
          Constructs the function g( h(a) ).
static UnaryFunction compare(double b)
          Constructs a function that returns a < b ? -1 : a > b ? 1 : 0.
static UnaryFunction constant(double c)
          Constructs a function that returns the constant c.
static UnaryFunction div(double b)
          Constructs a function that returns a / b.
static UnaryFunction equals(double b)
          Constructs a function that returns a == b ? 1 : 0.
static UnaryFunction greater(double b)
          Constructs a function that returns a > b ? 1 : 0.
static UnaryFunction IEEEremainder(double b)
          Constructs a function that returns Math.IEEEremainder(a,b).
static DoubleProcedure isBetween(double from, double to)
          Constructs a function that returns from<=a && a<=to.
static DoubleProcedure isEqual(double b)
          Constructs a function that returns a == b.
static DoubleProcedure isGreater(double b)
          Constructs a function that returns a > b.
static DoubleProcedure isLess(double b)
          Constructs a function that returns a < b.
static UnaryFunction less(double b)
          Constructs a function that returns a < b ? 1 : 0.
static UnaryFunction lg(double b)
          Constructs a function that returns Math.log(a) / Math.log(b).
static UnaryFunction max(double b)
          Constructs a function that returns Math.max(a,b).
static UnaryFunction min(double b)
          Constructs a function that returns Math.min(a,b).
static UnaryFunction minus(double b)
          Constructs a function that returns a - b.
static BinaryFunction minusMult(double constant)
          Constructs a function that returns a - b*constant.
static UnaryFunction mod(double b)
          Constructs a function that returns a % b.
static UnaryFunction mult(double b)
          Constructs a function that returns a * b.
static UnaryFunction plus(double b)
          Constructs a function that returns a + b.
static BinaryFunction plusMult(double constant)
          Constructs a function that returns a + b*constant.
static UnaryFunction pow(double b)
          Constructs a function that returns Math.pow(a,b).
static UnaryFunction 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).
static UnaryFunction round(double precision)
          Constructs a function that returns the number rounded to the given precision; Math.rint(a/precision)*precision.
static BinaryFunction swapArgs(BinaryFunction function)
          Constructs a function that returns function.apply(b,a), i.e.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

abs

public static final UnaryFunction abs
Function that returns Math.abs(a).


acos

public static final UnaryFunction acos
Function that returns Math.acos(a).


asin

public static final UnaryFunction asin
Function that returns Math.asin(a).


atan

public static final UnaryFunction atan
Function that returns Math.atan(a).


ceil

public static final UnaryFunction ceil
Function that returns Math.ceil(a).


cos

public static final UnaryFunction cos
Function that returns Math.cos(a).


exp

public static final UnaryFunction exp
Function that returns Math.exp(a).


floor

public static final UnaryFunction floor
Function that returns Math.floor(a).


identity

public static final UnaryFunction identity
Function that returns its argument.


inv

public static final UnaryFunction inv
Function that returns 1.0 / a.


logarithm

public static final UnaryFunction logarithm
Function that returns Math.log(a).


log2

public static final UnaryFunction log2
Function that returns Math.log(a) / Math.log(2).


negate

public static final UnaryFunction negate
Function that returns -a.


rint

public static final UnaryFunction rint
Function that returns Math.rint(a).


sign

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


sin

public static final UnaryFunction sin
Function that returns Math.sin(a).


sqrt

public static final UnaryFunction sqrt
Function that returns Math.sqrt(a).


square

public static final UnaryFunction square
Function that returns a * a.


tan

public static final UnaryFunction tan
Function that returns Math.tan(a).


atan2

public static final BinaryFunction atan2
Function that returns Math.atan2(a,b).


compare

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


div

public static final BinaryFunction div
Function that returns a / b.


equals

public static final BinaryFunction equals
Function that returns a == b ? 1 : 0.


greater

public static final BinaryFunction greater
Function that returns a > b ? 1 : 0.


IEEEremainder

public static final BinaryFunction IEEEremainder
Function that returns Math.IEEEremainder(a,b).


isEqual

public static final DoubleDoubleProcedure isEqual
Function that returns a == b.


isLess

public static final DoubleDoubleProcedure isLess
Function that returns a < b.


isGreater

public static final DoubleDoubleProcedure isGreater
Function that returns a > b.


less

public static final BinaryFunction less
Function that returns a < b ? 1 : 0.


lg

public static final BinaryFunction lg
Function that returns Math.log(a) / Math.log(b).


max

public static final BinaryFunction max
Function that returns Math.max(a,b).


min

public static final BinaryFunction min
Function that returns Math.min(a,b).


minus

public static final BinaryFunction minus
Function that returns a - b.


mod

public static final BinaryFunction mod
Function that returns a % b.


mult

public static final BinaryFunction mult
Function that returns a * b.


plus

public static final BinaryFunction plus
Function that returns a + b.


plusAbs

public static final BinaryFunction plusAbs
Function that returns Math.abs(a) + Math.abs(b).


pow

public static final BinaryFunction pow
Function that returns Math.pow(a,b).

Method Detail

between

public static UnaryFunction 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 UnaryFunction bindArg1(BinaryFunction 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 UnaryFunction bindArg2(BinaryFunction 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).

chain

public static BinaryFunction chain(BinaryFunction f,
                                   UnaryFunction g,
                                   UnaryFunction h)
Constructs the function f( g(a), h(b) ).

Parameters:
f - a binary function.
g - a unary function.
h - a unary function.
Returns:
the binary function f( g(a), h(b) ).

chain

public static BinaryFunction chain(UnaryFunction g,
                                   BinaryFunction h)
Constructs the function g( h(a,b) ).

Parameters:
g - a unary function.
h - a binary function.
Returns:
the unary function g( h(a,b) ).

chain

public static UnaryFunction chain(UnaryFunction g,
                                  UnaryFunction h)
Constructs the function g( h(a) ).

Parameters:
g - a unary function.
h - a unary function.
Returns:
the unary function g( h(a) ).

compare

public static UnaryFunction 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 UnaryFunction constant(double c)
Constructs a function that returns the constant c.


div

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


equals

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


greater

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


IEEEremainder

public static UnaryFunction 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 UnaryFunction less(double b)
Constructs a function that returns a < b ? 1 : 0. a is a variable, b is fixed.


lg

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


max

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


min

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


minus

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


minusMult

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


mod

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


mult

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


plus

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


plusMult

public static BinaryFunction plusMult(double constant)
Constructs a function that returns a + b*constant. a and b are variables, constant is fixed.


pow

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


random

public static UnaryFunction 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 MersenneTwister and is seeded with the current time.

Note that any random engine derived from RandomEngine and any random distribution derived from AbstractDistribution 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 UnaryFunction 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 BinaryFunction swapArgs(BinaryFunction 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).


Copyright © 2008-2010 The Apache Software Foundation. All Rights Reserved.