org.apache.mahout.math.function
Class Functions

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

public final class Functions
extends 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:

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.DoubleDoubleFunction ,double) and bindArg2(org.apache.mahout.math.function.DoubleDoubleFunction ,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.DoubleDoubleFunction). 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.DoubleFunction , org.apache.mahout.math.function.DoubleFunction):

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.DoubleFunction , org.apache.mahout.math.function.DoubleDoubleFunction): The binary function f(g(a),h(b)) can be generated via chain(org.apache.mahout.math.function.DoubleDoubleFunction , org.apache.mahout.math.function.DoubleFunction , org.apache.mahout.math.function.DoubleFunction): 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 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);
 log.info(v);
 Functions F = Functions.functions;
 DoubleDoubleFunction f = F.chain(F.plus,F.sin,F.chain(F.square,F.cos));
 log.info(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); }
 };
 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 DoubleFunction ABS
          Function that returns Math.abs(a).
static DoubleFunction ACOS
          Function that returns Math.acos(a).
static DoubleFunction ASIN
          Function that returns Math.asin(a).
static DoubleFunction ATAN
          Function that returns Math.atan(a).
static DoubleDoubleFunction ATAN2
          Function that returns Math.atan2(a,b).
static DoubleFunction CEIL
          Function that returns Math.ceil(a).
static DoubleDoubleFunction COMPARE
          Function that returns a < b ? -1 : a > b ? 1 : 0.
static DoubleFunction COS
          Function that returns Math.cos(a).
static DoubleDoubleFunction DIV
          Function that returns a / b.
static DoubleDoubleFunction EQUALS
          Function that returns a == b ? 1 : 0.
static DoubleFunction EXP
          Function that returns Math.exp(a).
static DoubleFunction FLOOR
          Function that returns Math.floor(a).
static DoubleDoubleFunction GREATER
          Function that returns a > b ? 1 : 0.
static DoubleFunction IDENTITY
          Function that returns its argument.
static DoubleDoubleFunction IEEE_REMAINDER
          Function that returns Math.IEEEremainder(a,b).
static DoubleFunction INV
          Function that returns 1.0 / a.
static DoubleDoubleProcedure IS_EQUAL
          Function that returns a == b.
static DoubleDoubleProcedure IS_GREATER
          Function that returns a > b.
static DoubleDoubleProcedure IS_LESS
          Function that returns a < b.
static DoubleDoubleFunction LESS
          Function that returns a < b ? 1 : 0.
static DoubleDoubleFunction LG
          Function that returns Math.log(a) / Math.log(b).
static DoubleFunction LOG2
          Function that returns Math.log(a) / Math.log(2).
static DoubleFunction LOGARITHM
          Function that returns Math.log(a).
static DoubleDoubleFunction MAX
          Function that returns Math.max(a,b).
static DoubleDoubleFunction MAX_ABS
           
static DoubleDoubleFunction MIN
          Function that returns Math.min(a,b).
static DoubleDoubleFunction MINUS
          Function that returns a - b.
static DoubleDoubleFunction MINUS_ABS
           
static DoubleDoubleFunction MINUS_SQUARED
           
static DoubleDoubleFunction MOD
          Function that returns a % b.
static DoubleDoubleFunction MULT
          Function that returns a * b.
static DoubleDoubleFunction MULT_RIGHT_PLUS1
           
static DoubleDoubleFunction MULT_SQUARE_LEFT
           
static DoubleFunction NEGATE
          Function that returns -a.
static DoubleDoubleFunction PLUS
          Function that returns a + b.
static DoubleDoubleFunction PLUS_ABS
          Function that returns Math.abs(a) + Math.abs(b).
static DoubleDoubleFunction POW
          Function that returns Math.pow(a,b).
static DoubleFunction RINT
          Function that returns Math.rint(a).
static DoubleDoubleFunction SECOND
           
static DoubleDoubleFunction SECOND_LEFT_ZERO
          This function is specifically designed to be used when assigning a vector to one that is all zeros (created by like()).
static DoubleFunction SIGMOID
          Function that returns 1 / (1 + exp(-a)
static DoubleFunction SIGMOIDGRADIENT
          Function that returns a * (1-a)
static DoubleFunction SIGN
          Function that returns a < 0 ? -1 : a > 0 ? 1 : 0.
static DoubleFunction SIN
          Function that returns Math.sin(a).
static DoubleFunction SQRT
          Function that returns Math.sqrt(a).
static DoubleFunction SQUARE
          Function that returns a * a.
static DoubleFunction TAN
          Function that returns Math.tan(a).
 
Method Summary
static DoubleFunction between(double from, double to)
          Constructs a function that returns (from<=a && a<=to) ? 1 : 0.
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.
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.
static DoubleDoubleFunction chain(DoubleDoubleFunction f, DoubleFunction g, DoubleFunction h)
          Constructs the function f( g(a), h(b) ).
static DoubleDoubleFunction chain(DoubleFunction g, DoubleDoubleFunction h)
          Constructs the function g( h(a,b) ).
static DoubleFunction chain(DoubleFunction g, DoubleFunction h)
          Constructs the function g( h(a) ).
static IntIntFunction chain(DoubleFunction g, IntIntFunction h)
          Constructs the function g( h(a) ).
static DoubleFunction compare(double b)
          Constructs a function that returns a < b ? -1 : a > b ? 1 : 0.
static DoubleFunction constant(double c)
          Constructs a function that returns the constant c.
static DoubleFunction div(double b)
          Constructs a function that returns a / b.
static DoubleFunction equals(double b)
          Constructs a function that returns a == b ? 1 : 0.
static DoubleFunction greater(double b)
          Constructs a function that returns a > b ? 1 : 0.
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 DoubleFunction less(double b)
          Constructs a function that returns a < b ? 1 : 0.
static DoubleFunction lg(double b)
          Constructs a function that returns Math.log(a) / Math.log(b).
static DoubleFunction mathIEEEremainder(double b)
          Constructs a function that returns Math.IEEEremainder(a,b).
static DoubleFunction max(double b)
          Constructs a function that returns Math.max(a,b).
static DoubleFunction min(double b)
          Constructs a function that returns Math.min(a,b).
static DoubleFunction minus(double b)
          Constructs a function that returns a - b.
static DoubleDoubleFunction minusAbsPow(double exponent)
           
static DoubleDoubleFunction minusMult(double constant)
          Constructs a function that returns a - b*constant.
static DoubleFunction mod(double b)
          Constructs a function that returns a % b.
static DoubleFunction mult(double b)
          Constructs a function that returns a * b.
static DoubleFunction plus(double b)
          Constructs a function that returns a + b.
static DoubleDoubleFunction plusMult(double constant)
          Constructs a function that returns a + b*constant.
static DoubleFunction pow(double b)
          Constructs a function that returns Math.pow(a,b).
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).
static DoubleDoubleFunction reweigh(double wx, double wy)
           
static DoubleFunction round(double precision)
          Constructs a function that returns the number rounded to the given precision; Math.rint(a/precision)*precision.
static DoubleDoubleFunction swapArgs(DoubleDoubleFunction 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 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.


LOGARITHM

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


LOG2

public static final DoubleFunction LOG2
Function that returns Math.log(a) / Math.log(2).


NEGATE

public static final DoubleFunction NEGATE
Function that returns -a.


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.


SIGMOID

public static final DoubleFunction SIGMOID
Function that returns 1 / (1 + exp(-a)


SIGMOIDGRADIENT

public static final DoubleFunction SIGMOIDGRADIENT
Function that returns a * (1-a)


TAN

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


ATAN2

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


COMPARE

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


DIV

public static final DoubleDoubleFunction DIV
Function that returns a / b.


EQUALS

public static final DoubleDoubleFunction EQUALS
Function that returns a == b ? 1 : 0.


GREATER

public static final DoubleDoubleFunction GREATER
Function that returns a > b ? 1 : 0.


IEEE_REMAINDER

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


IS_EQUAL

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


IS_LESS

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


IS_GREATER

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


LESS

public static final DoubleDoubleFunction LESS
Function that returns a < b ? 1 : 0.


LG

public static final DoubleDoubleFunction LG
Function that returns Math.log(a) / Math.log(b).


MAX

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


MAX_ABS

public static final DoubleDoubleFunction MAX_ABS

MIN

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


MINUS

public static final DoubleDoubleFunction MINUS
Function that returns a - b.


MINUS_SQUARED

public static final DoubleDoubleFunction MINUS_SQUARED

MOD

public static final DoubleDoubleFunction MOD
Function that returns a % b.


MULT

public static final DoubleDoubleFunction MULT
Function that returns a * b.


PLUS

public static final DoubleDoubleFunction PLUS
Function that returns a + b.


PLUS_ABS

public static final DoubleDoubleFunction PLUS_ABS
Function that returns Math.abs(a) + Math.abs(b).


MINUS_ABS

public static final DoubleDoubleFunction MINUS_ABS

POW

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


SECOND

public static final DoubleDoubleFunction SECOND

SECOND_LEFT_ZERO

public static final DoubleDoubleFunction SECOND_LEFT_ZERO
This function is specifically designed to be used when assigning a vector to one that is all zeros (created by like()). It enables iteration only through the nonzeros of the right hand side by declaring isLikeRightPlus to be true. This is NOT generally true for SECOND (hence the other function above).


MULT_SQUARE_LEFT

public static final DoubleDoubleFunction MULT_SQUARE_LEFT

MULT_RIGHT_PLUS1

public static final DoubleDoubleFunction MULT_RIGHT_PLUS1
Method Detail

reweigh

public static DoubleDoubleFunction reweigh(double wx,
                                           double wy)

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).

chain

public static DoubleDoubleFunction chain(DoubleDoubleFunction f,
                                         DoubleFunction g,
                                         DoubleFunction 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 DoubleDoubleFunction chain(DoubleFunction g,
                                         DoubleDoubleFunction h)
Constructs the function g( h(a,b) ).

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

chain

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

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

chain

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

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

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.


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.


mathIEEEremainder

public static DoubleFunction mathIEEEremainder(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. Note that DoubleProcedure is generated code and thus looks like an invalid reference unless you can see the generated stuff.


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.


plusMult

public static DoubleDoubleFunction plusMult(double constant)
Constructs a function that returns a + b*constant. 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 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 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).

minusAbsPow

public static DoubleDoubleFunction minusAbsPow(double exponent)


Copyright © 2008–2014 The Apache Software Foundation. All rights reserved.