Return-Path: Delivered-To: apmail-commons-commits-archive@locus.apache.org Received: (qmail 45136 invoked from network); 20 Apr 2008 18:56:09 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 20 Apr 2008 18:56:09 -0000 Received: (qmail 13231 invoked by uid 500); 20 Apr 2008 18:56:09 -0000 Delivered-To: apmail-commons-commits-archive@commons.apache.org Received: (qmail 13172 invoked by uid 500); 20 Apr 2008 18:56:09 -0000 Mailing-List: contact commits-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commons.apache.org Delivered-To: mailing list commits@commons.apache.org Received: (qmail 13163 invoked by uid 99); 20 Apr 2008 18:56:09 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 20 Apr 2008 11:56:09 -0700 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 20 Apr 2008 18:55:33 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id DC2E61A9832; Sun, 20 Apr 2008 11:55:46 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r649953 - in /commons/sandbox/nabla/trunk/src/site: resources/ resources/images/ resources/images/maximum.png xdoc/index.xml Date: Sun, 20 Apr 2008 18:55:46 -0000 To: commits@commons.apache.org From: luc@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20080420185546.DC2E61A9832@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: luc Date: Sun Apr 20 11:55:44 2008 New Revision: 649953 URL: http://svn.apache.org/viewvc?rev=649953&view=rev Log: added an example to documentation Added: commons/sandbox/nabla/trunk/src/site/resources/ commons/sandbox/nabla/trunk/src/site/resources/images/ commons/sandbox/nabla/trunk/src/site/resources/images/maximum.png (with props) Modified: commons/sandbox/nabla/trunk/src/site/xdoc/index.xml Added: commons/sandbox/nabla/trunk/src/site/resources/images/maximum.png URL: http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/resources/images/maximum.png?rev=649953&view=auto ============================================================================== Binary file - no diff available. Propchange: commons/sandbox/nabla/trunk/src/site/resources/images/maximum.png ------------------------------------------------------------------------------ svn:mime-type = image/png Modified: commons/sandbox/nabla/trunk/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/xdoc/index.xml?rev=649953&r1=649952&r2=649953&view=diff ============================================================================== --- commons/sandbox/nabla/trunk/src/site/xdoc/index.xml (original) +++ commons/sandbox/nabla/trunk/src/site/xdoc/index.xml Sun Apr 20 11:55:44 2008 @@ -1,77 +1,188 @@ - + - - Nabla: an automatic differentiator - - - - -
-

Nabla is an automatic differentiator for mathematical - functions. Just like the mathematical Nabla (&nabla;) operator - transform a function into its differential, the Nabla library - transforms an existing java object implementing a - function double f(double) { ... } into another java - object that in addition to computing the value of f - like the original one also computes its differential. The created - object implements differentiation using the classical exact - rules. There are no approximations and no step sizes.

- -

This approach has the following benefits:

-
    -
  • differentiation is exact
    • -
  • there are no problem-dependent step size to handle
    • -
  • differentiation can be computed even at domains - boundaries
    • -
  • there is no special handling of source (no symbolic package - with its own language, no source code generation, no integration - with the rest of application)
    • -
  • one writes and maintains only the basic equation and get the - differential for free
    • -
  • it is effective even when source code is not available (but - there may be licensing issues in this case since what Nabla does - automatically is really ... derived work)
    • -
- -

The derivative instance is tightly bound to the base instance. So - if after Nabla has performed the transformation the base instance - is mutated outside of the scope of Nabla, the already produced - derivative instance will used this mutated state for its later - computation automatically.

- -
-
- -

Basically, Nabla works by analyzing the bytecode of the - original object, transforming the arithmetic operations, - generating a new class on the fly with the transformed bytecode, - and instantiating it to generate the derivative object. This should - work for Java or for any program using the Java platform as its - execution environment.

- -

The main drawback is that functions calling native code cannot - be handled. For these functions, a poor man implementation is - provided that use finite differences (with 2, 4, 6 or 8 points - schemes).

+ + Nabla: an automatic differentiator + + + + +
+

+ Nabla is an automatic differentiator for mathematical functions. + Just like the mathematical Nabla operator transforms a function + into its differential, the Nabla library transforms an existing + java object implementing a function + double f(double) { ... } + into another java object that in addition to computing the value + of + f + like the original one also computes its differential. The + created object implements differentiation using the classical + exact rules. There are no approximations and no step sizes. +

+ +

This approach has the following benefits:

+
    +
  • differentiation is exact
    • +
  • there are no problem-dependent step size to handle
    • +
  • + differentiation can be computed even at domains boundaries +
    • +
  • + there is no special handling of source (no symbolic package + with its own language, no source code generation, no + integration with the rest of application) +
    • +
  • + one writes and maintains only the basic equation and get the + differential for free +
    • +
  • + it is effective even when source code is not available (but + there may be licensing issues in this case since what Nabla + does automatically is really ... derived work) +
    • +
+ +

+ The derivative instance is tightly bound to the base instance. + So if after Nabla has performed the transformation the base + instance is mutated outside of the scope of Nabla, the already + produced derivative instance will used this mutated state for + its later computation automatically. +

+ +
+ +
+ +

+ The following example should explain better what Nabla can do + for you. +

+ +

+ Let's consider a simple problem: we want to find the maximal + value of a function: + 

f(t) = (6-t)/3 + cos(4t-4) e-0.9t
+

+ a curve with maximal value 2.109747 at t = 0.898775 + +

+ The maximal value is reached when the first derivative of the + function is equal to zero. So we need to compute the first + derivative f'(t) and find its roots. We start by + implementing the function f(t): +

+ + + UnivariateDifferentiable function = new UnivariateDifferentiable() { + public double f(double t) { + return (6 - t) / 3 + Math.cos(4 * t - 4) * Math.exp(-0.9 * t); + } + }; + + +

+ We use the Nabla automatic differentiator to differentiate our + function and returning an object implementing the derivative: +

+ + + UnivariateDifferentiator differentiator = new AutomaticDifferentiator(); + final UnivariateDerivative derivative = differentiator.differentiate(function); + + +

+ We get the maximal value by calling a solver on the derivative. + In this example, we will use the + + Brent solver from the commons + math library. In order to do this, we wrap the derivative into an object + implementing the + UnivariateRealFunction interface required by all commons math solvers: +

+ + + UnivariateRealFunction wrappedDerivative = new UnivariateRealFunction() { + public double value(double x) { + return derivative.f(DifferentialPair.newVariable(x)).getFirstDerivative(); + } + }; + UnivariateRealSolver solver = new BrentSolver(wrappedDerivative); + double tMax = solver.solve(0.5, 1.5); + double yMax = derivative.f(DifferentialPair.newVariable(tMax)).getValue(); + System.out.println("max value = " + yMax + ", at t = " + tMax + " " + solver.getIterationCount()); + + +

+ We get the following result: +

+ + + max value = 2.1097470218140537, at t = 0.8987751653383649 (7 iterations) + + +

+ We could also use the derivative object to compute both the + value and the first derivative of our function at any point: +

+ + + for (double t = 0.0; t < 1.0; t += 0.01) { + DifferentialPair y = derivative.f(DifferentialPair.newVariable(t)); + System.out.println(t + " " + y.getValue() + " " + y.getFirstDerivative()); + } + + +
+ +
+ +

+ The previous example shows that Nabla creates an object that + computes both the value and the derivative of a function, given + only an instance of a class that computes the base function. How + does it do that? +

+ +

+ Basically, Nabla works by analyzing the bytecode of the original + object, transforming the arithmetic operations along all + possible exectution passes using the differentiation, generating + a new class on the fly with the transformed bytecode, and + instantiating it to generate the derivative object. This works + for any pure Java function, or more generally for any program + using the Java platform as its execution environment. +

+ +

+ The main drawback is that functions calling native code cannot + be handled. For these functions, a poor man implementation is + provided that use finite differences (with 2, 4, 6 or 8 points + schemes). +

-
- +
+