Functions

java.lang.Object
- cern.jet.math.Functions

public 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 a^b.
Functions.pow.apply(2,3)==8.
Functions.pow(3) gives the function a³.
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 a^b.
Functions.bindArg2(Functions.pow,3) gives the function x³.
Functions.bindArg1(Functions.pow,3) gives the function 3^x.
Functions.swapArgs(Functions.pow) gives the function b^a.

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) + cos²(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 Summary

Fields
Modifier and Type	Field and Description
`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 Functions`	`functions` Little trick to allow for "aliasing", that is, renaming this class.
`static DoubleDoubleFunction`	`greater` Function that returns `a > b ? 1 : 0`.
`static DoubleFunction`	`identity` Function that returns its argument.
`static DoubleDoubleFunction`	`IEEEremainder` Function that returns `Math.IEEEremainder(a,b)`.
`static DoubleFunction`	`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 DoubleDoubleFunction`	`less` Function that returns `a < b ? 1 : 0`.
`static DoubleDoubleFunction`	`lg` Function that returns `Math.log(a) / Math.log(b)`.
`static DoubleFunction`	`log` Function that returns `Math.log(a)`.
`static DoubleFunction`	`log2` Function that returns `Math.log(a) / Math.log(2)`.
`static DoubleDoubleFunction`	`max` Function that returns `Math.max(a,b)`.
`static DoubleDoubleFunction`	`min` Function that returns `Math.min(a,b)`.
`static DoubleDoubleFunction`	`minus` Function that returns `a - b`.
`static DoubleDoubleFunction`	`mod` Function that returns `a % b`.
`static DoubleDoubleFunction`	`mult` Function that returns `a * b`.
`static DoubleFunction`	`neg` Function that returns `-a`.
`static DoubleDoubleFunction`	`plus` Function that returns `a + b`.
`static DoubleDoubleFunction`	`plusAbs` 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 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

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`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 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 void`	`demo1()` Demonstrates usage of this class.
`static void`	`demo2(int size)` Benchmarks and demonstrates usage of trivial and complex functions.
`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 DoubleFunction`	`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 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`	`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`	`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 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - functions
```
public static final Functions 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).
  - neg
```
public static final DoubleFunction neg
```
    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.
  - 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.
  - IEEEremainder
```
public static final DoubleDoubleFunction 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 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).
  - min
```
public static final DoubleDoubleFunction min
```
    Function that returns Math.min(a,b).
  - minus
```
public static final DoubleDoubleFunction minus
```
    Function that returns a - b.
  - 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.
  - plusAbs
```
public static final DoubleDoubleFunction plusAbs
```
    Function that returns Math.abs(a) + Math.abs(b).
  - pow
```
public static final DoubleDoubleFunction pow
```
    Function that returns Math.pow(a,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).
  - 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 unary 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) ).
  - 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.
  - 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).

Class Functions

Performance

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

functions

abs

acos

asin

atan

ceil

cos

exp

floor

identity

inv

log

log2

neg

rint

sign

sin

sqrt

square

tan

atan2

compare

div

equals

greater

IEEEremainder

isEqual

isLess

isGreater

less

lg

max

min

minus

mod

mult

plus

plusAbs

pow

Method Detail

between

bindArg1

bindArg2

chain

chain

chain

compare

constant

demo1

demo2

div

equals

greater

IEEEremainder

isBetween

isEqual

isGreater

isLess

less

lg

max

min

minus

minusMult

mod

mult

plus

plusMult

pow

random

round

swapArgs