cern.jet.math

## Class Functions

- java.lang.Object
- - cern.jet.math.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 `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

    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

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

Jump to the Colt Homepage