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:mimetype = 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 @@
<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF8" ?>
<!
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements. See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
>
<document>
 <properties>
 <title>Nabla: an automatic differentiator</title>
 </properties>

 <body>

 <section name="Introduction" href="introduction">
 <p>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 <code>double f(double) { ... }</code> into another java
 object that in addition to computing the value of <code>f</code>
 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.</p>

 <p>This approach has the following benefits:</p>
 <ul>
 <li>differentiation is exact</li>
 <li>there are no problemdependent step size to handle</li>
 <li>differentiation can be computed even at domains
 boundaries</li>
 <li>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)</li>
 <li>one writes and maintains only the basic equation and get the
 differential for free</li>
 <li>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)</li>
 </ul>

 <p>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.</p>

 </section>
 <section name="How ?" href="how">

 <p>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.</p>

 <p>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).</p>
+ <properties>
+ <title>Nabla: an automatic differentiator</title>
+ </properties>
+
+ <body>
+
+ <section name="Introduction" href="introduction">
+ <p>
+ 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
+ <code>double f(double) { ... }</code>
+ into another java object that in addition to computing the value
+ of
+ <code>f</code>
+ 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.
+ </p>
+
+ <p>This approach has the following benefits:</p>
+ <ul>
+ <li>differentiation is exact</li>
+ <li>there are no problemdependent step size to handle</li>
+ <li>
+ differentiation can be computed even at domains boundaries
+ </li>
+ <li>
+ 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)
+ </li>
+ <li>
+ one writes and maintains only the basic equation and get the
+ differential for free
+ </li>
+ <li>
+ 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)
+ </li>
+ </ul>
+
+ <p>
+ 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.
+ </p>
+
+ </section>
+
+ <section name="Example" href="example">
+
+ <p>
+ The following example should explain better what Nabla can do
+ for you.
+ </p>
+
+ <p>
+ Let's consider a simple problem: we want to find the maximal
+ value of a function:
+ <pre><code>f(t) = (6t)/3 + cos(4t4) e<sup>0.9t</sup></code></pre>
+ </p>
+ <img src="images/maximum.png"
+ alt="a curve with maximal value 2.109747 at t = 0.898775" />
+
+ <p>
+ The maximal value is reached when the first derivative of the
+ function is equal to zero. So we need to compute the first
+ derivative <code>f'(t)</code> and find its roots. We start by
+ implementing the function <code>f(t)</code>:
+ </p>
+
+ <source>
+ UnivariateDifferentiable function = new UnivariateDifferentiable() {
+ public double f(double t) {
+ return (6  t) / 3 + Math.cos(4 * t  4) * Math.exp(0.9 * t);
+ }
+ };
+ </source>
+
+ <p>
+ We use the Nabla automatic differentiator to differentiate our
+ function and returning an object implementing the derivative:
+ </p>
+
+ <source>
+ UnivariateDifferentiator differentiator = new AutomaticDifferentiator();
+ final UnivariateDerivative derivative = differentiator.differentiate(function);
+ </source>
+
+ <p>
+ We get the maximal value by calling a solver on the derivative.
+ In this example, we will use the
+ <a href="http://commons.apache.org/math/apidocs/org/apache/commons/math/analysis/BrentSolver.html">
+ Brent solver</a> from the <a href="http://commons.apache.org/math/">commons
+ math</a> library. In order to do this, we wrap the derivative into an object
+ implementing the <a
+ href="http://commons.apache.org/math/apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html">
+ UnivariateRealFunction</a> interface required by all commons math solvers:
+ </p>
+
+ <source>
+ 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());
+ </source>
+
+ <p>
+ We get the following result:
+ </p>
+
+ <source>
+ max value = 2.1097470218140537, at t = 0.8987751653383649 (7 iterations)
+ </source>
+
+ <p>
+ We could also use the derivative object to compute both the
+ value and the first derivative of our function at any point:
+ </p>
+
+ <source>
+ 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());
+ }
+ </source>
+
+ </section>
+
+ <section name="How ?" href="how">
+
+ <p>
+ 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?
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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).
+ </p>
 </section>
 </body>
+ </section>
+ </body>
</document>
