Colt 1.2.0

## cern.jet.math
Class 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 `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 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);
    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 |  |

Version:
  1.0, 09/24/99

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

Colt 1.2.0

Jump to the Colt Homepage