commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r650673 - in /commons/sandbox/nabla/trunk/src/site: resources/images/public-API.png xdoc/index.xml xdoc/usage.xml
Date Tue, 22 Apr 2008 21:57:33 GMT
Author: luc
Date: Tue Apr 22 14:57:32 2008
New Revision: 650673

improved documentation

    commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png   (with props)

Added: commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png
Binary file - no diff available.

Propchange: commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png
    svn:mime-type = image/png

Modified: commons/sandbox/nabla/trunk/src/site/xdoc/index.xml
--- commons/sandbox/nabla/trunk/src/site/xdoc/index.xml (original)
+++ commons/sandbox/nabla/trunk/src/site/xdoc/index.xml Tue Apr 22 14:57:32 2008
@@ -169,7 +169,7 @@
         Basically, Nabla works by analyzing the bytecode of the original
         object, transforming the arithmetic operations along all
-        possible exectution passes using the differentiation, generating
+        possible execution 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
@@ -177,10 +177,9 @@
-        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).
+        The main drawback is that functions that call native code cannot
+        be handled. For these functions, a work around is provided that
+        uses finite differences (with 2, 4, 6 or 8 points schemes).

Modified: commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml
--- commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml (original)
+++ commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml Tue Apr 22 14:57:32 2008
@@ -24,8 +24,94 @@
     <section name="Public API" href="api">
+      <p>
+        Nabla public interface is very small, it is composed of only three
+        interfaces and two classes.
+        <dl>
+          <dt>UnivariateDifferentiable</dt>
+          <dd>is the interface representing the mathematical function that should
+          be differentiated. The user-defined class are provided to Nabla as
+          classes implementing this interface</dd>
+          <dt>UnivariateDerived</dt>
+          <dd>is the interface representing the derived function created by
+          Nabla. It is the result of the differentiation.</dd>
+          <dt>UnivariateDifferentiator</dt>
+          <dd>is the interface implemented by the various differentiators provided
+          by Nabla.</dd>
+          <dt>DifferentialPair</dt>
+          <dd>is a simple container holding both a value and a derivative. It can be
+          considered simply as an <em>enhanced double</em> that is used both
+          the type of input parameters and return value of derived functions.</dd>
+          <dt>AutomaticDifferentiator</dt>
+          <dd>is the main implementation of the UnivariateDifferentiator interface.
+          It performs differentiation by bytecode analysis and generation, using
+          the exact differentiation rules in order to create functions that
+          compute exact differentials.</dd>
+        </dl>
+      </p>
+      <img src="images/public-API.png" alt="UML class diagram of Nabla public API" />
+      <p>
+        In order to use differentiate a function using Nabla, the function must be
+        provided as an implementation of the UnivariateDifferentiable interface and
+        passed as the single parameter of the <code>differentiate</code> method
of an
+        AutomaticDifferentiator instance. If the existing class does not already
+        implements the UnivariateDifferentiable interface, it has to be wrapped when
+        provided to the differentiator.
+      </p>
+      <p>As an example, consider the following problem. We have a <code>model</code>
+      variable which is an instance of a class with a method <code>evaluate</code>:
+      <pre><code>double evaluate(double first, double second)</code></pre>
+      and we want to compute its partial derivative with respect to the second
+      parameter, when the first parameter value is 2.5 and the second parameter
+      ranges from -1 to +1. Here is a way to do that:
+      </p>
+      <source>
+      final double constantFirst = 2.5;
+      UnivariateDerived derived =
+          new AutomaticDifferentiator().differentiate(new UnivariateDifferentiable() {
+              public double f(double t) {
+                  return model.evaluate(constantFirst, t);
+              }
+          });
+      for (double second = -1; second &lt;= +1; second += 0.01) {
+        DifferentialPair t = DifferentialPair.newVariable(second);
+        System.out.println(second + " " + derived.f(t).getFirstDerivative());
+      } 
+      </source>
-    <section name="Integration with commons math" href="commons-math">
+    <section name="Updating the base and derived objects" href="updating">
+      <p>
+        One important thing to note is a consequence of the fact that the
+        <code>differentiate</code> method returns a new object when called.
+        This implies that we end up with two different instances of two
+        different classes that compute roughly similar things: the original
+        instance and the newly created object. If the implementation of the
+        <code>f</code> method does use some attribute of the original class,
+        then the class of the newly created object should also provide a way
+        to get this value.
+      </p>
+      <p>
+        An important design choice in Nabla is that the newly created instance
+        does <em>not</em> copy the state of the original object at derivation
+        time, but instead is permanently and tightly linked to this original
+        instance and uses it to get the values it needs when it needs them
+        (even if it is stored in a private attribute). A direct implication is
+        that if the state of the original object is changed <em>after</em>
+        differentiation, all subsequent calls to the <code>f</code> method of
+        the already created differentiated instance will reflect these changes
+        in their behavior. There is no need to bother about updating the
+        differentiated instance, it is already up-to-date.
+      </p>

View raw message