commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From l..@apache.org
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 GMT
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 (&amp;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 &lt; 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>



Mime
View raw message