You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by lu...@apache.org on 2008/04/20 20:55:46 UTC
svn commit: r649953 - in /commons/sandbox/nabla/trunk/src/site: resources/
resources/images/ resources/images/maximum.png xdoc/index.xml
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 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8" ?>
<!--
- 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/LICENSE-2.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/LICENSE-2.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 problem-dependent 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 problem-dependent 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) = (6-t)/3 + cos(4t-4) 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>