## org.apache.mahout.math.function
Class Functions

    java.lang.Object
      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:

- `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(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:

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

- `Functions.chain(g,f);`

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)`:

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