Author: luc
Date: Tue Apr 22 14:57:32 2008
New Revision: 650673
URL: http://svn.apache.org/viewvc?rev=650673&view=rev
Log:
improved documentation
Added:
commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png
(with props)
Modified:
commons/sandbox/nabla/trunk/src/site/xdoc/index.xml
commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml
Added: commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png
URL:
http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/resources/images/public-API.png?rev=650673&view=auto
==============================================================================
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
URL:
http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/xdoc/index.xml?rev=650673&r1=650672&r2=650673&view=diff
==============================================================================
--- 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 @@
<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
+ 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 @@
</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).
+ 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).
</p>
</section>
Modified: commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml
URL:
http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/xdoc/usage.xml?rev=650673&r1=650672&r2=650673&view=diff
==============================================================================
--- 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 @@
<body>
<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 as
+ 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 <= +1; second += 0.01) {
+ DifferentialPair t = DifferentialPair.newVariable(second);
+ System.out.println(second + " " + derived.f(t).getFirstDerivative());
+ }
+ </source>
+
</section>
- <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>
+
</section>
+
</body>
</document>
