Author: luc
Date: Mon Aug 10 09:54:01 2009
New Revision: 802710
URL: http://svn.apache.org/viewvc?rev=802710&view=rev
Log:
improved documentation
Modified:
commons/sandbox/nabla/trunk/src/site/xdoc/index.xml
commons/sandbox/nabla/trunk/src/site/xdoc/internals.xml
commons/sandbox/nabla/trunk/src/site/xdoc/singularities.xml
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=802710&r1=802709&r2=802710&view=diff
==============================================================================
 commons/sandbox/nabla/trunk/src/site/xdoc/index.xml (original)
+++ commons/sandbox/nabla/trunk/src/site/xdoc/index.xml Mon Aug 10 09:54:01 2009
@@ 121,11 +121,7 @@
<subsection name="Solution implementation">
<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. Nabla will help in the first part:
 computing <code>f'(t)</code>. We start by implementing the
+ In order to compute <code>f'(t)</code>. We start by implementing the
function <code>f(t)</code>:
</p>
<source>
@@ 147,13 +143,19 @@
</source>
<p>
 We get the maximal value by calling a solver on the
+ The <code>derivative</code> object implements the <a
+ href="apidocs/org/apache/commons/nabla/core/UnivariateDerivative.html">UnivariateDerivative</a>
+ interface which means it provides a method <code>f</code> which is
an enhanced
+ version of the <code>f</code> method of the original <code>function</code>
object:
+ it computes both the value and the derivative of the function.
+ </p>
+
+ <p>
+ We can therefore find 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/">commonsmath</a>
 library. Functions passed to any commonsmath solver must
 implement a specific
+ Brent solver</a> from the <a href="http://commons.apache.org/math/">commonsmath</a>
+ library. Functions passed to any commonsmath solver must implement a specific
interface: <a href="http://commons.apache.org/math/apidocs/org/apache/commons/math/analysis/UnivariateRealFunction.html">
UnivariateRealFunction</a>. In order to comply with this
requirement, we wrap the derivative object into another
@@ 187,7 +189,7 @@
<subsection name="Discussion">
<p>
 This example shows that Nabla creates an object that
+ The example above 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
primitive function. Despite we had the source code available
@@ 217,24 +219,27 @@
<section name="Limitations">
<p>
 Basically, Nabla works by analyzing the bytecode of the
 original object, transforming the arithmetic operations along
 all 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
+ Basically, Nabla works by:
+ <ul>
+ <li>analyzing the bytecode of the original object,</li>
+ <li>transforming the arithmetic operations along all possible
+ execution passes using the classical differentiation rules,</li>
+ <li>generating a new class on the fly with the transformed bytecode,</li>
+ <li>instantiating the generated class to create the derivative object.</li>
+ </ul>
+ 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 that call native code
 cannot be handled. For these functions, a fallback method is
+ The main drawback of this approach is that functions that call native
+ code cannot be handled. For these functions, a fallback method is
provided that uses finite differences (with 2, 4, 6 or 8
points schemes). This fallback method does not have the same
advantages as the previous one: it needs configuration (number
of points and step size), it is not exact, it is more
 computing intensive and it cannot be used too close to domain
+ computation intensive and it cannot be used too close to domain
boundaries.
</p>
Modified: commons/sandbox/nabla/trunk/src/site/xdoc/internals.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/xdoc/internals.xml?rev=802710&r1=802709&r2=802710&view=diff
==============================================================================
 commons/sandbox/nabla/trunk/src/site/xdoc/internals.xml (original)
+++ commons/sandbox/nabla/trunk/src/site/xdoc/internals.xml Mon Aug 10 09:54:01 2009
@@ 27,17 +27,23 @@
<subsection name="Differentiation at bytecode instructions level">
<p>
 Nabla computes the derivatives applying the classical
+ Nabla computes the derivatives by applying the classical
differentiation rules at bytecode level. When an instance
of a class implementing <code>UnivariateDifferentiable</code>
is passed to its <code>differentiate</code> method, Nabla
tracks the mathematical operations flow that leads from the
<code>t</code> parameter to the return value of the
 function. At the bytecode instructions level, the operations
+ function. At the bytecode instructions level, all operations
are elementary ones. Each elementary operation is then
changed to compute both a value and a derivative. Nothing is
changed to the control flow instructions (loops, branches,
 operations scheduling). The entry point of this differentiation
+ operations scheduling).
+ </p>
+
+ <p>
+ Analysis and transformation of the bytecode is realized using both
+ the core API and the tree API from the <a href="http://asm.objectweb.org/">asm</a>
+ bytecode manipulation and analysis framework. The entry point of this differentiation
process is the <a
href="apidocs/org/apache/commons/nabla/algorithmic/forward/analysis/MethodDifferentiator.html#visitEnd()">
visitEnd</a> method of the <code>MethodDifferentiator</code>
@@ 57,9 +63,12 @@
For each one of these basic bytecode instructions, we know how to
map it to a mathematical equation and we can combine this equation
with its derivative to form a pair of equations we will use later.
 For example, a <code>DADD</code> bytecode instruction corresponds
+ </p>
+
+ <p>
+ Lets consider the <code>DADD</code> bytecode instruction. It corresponds
to the addition of two real numbers and produces a third number
 which is their sum. So we map the instruction to the equation:
+ which is their sum. We map the instruction to the equation:
<pre><code>c=a+b</code></pre>
and we combine this with its derivative to form the pair:
<pre><code>(c=a+b, c'=a'+b')</code></pre>
@@ 145,8 +154,7 @@
<p>
This example shows that the instructions conversions have local
 scope. No global tree representation of the method is needed
 at all.
+ scope.
</p>
</subsection>
@@ 168,7 +176,7 @@
others will be build in the callee to return results to the caller.
This is <em>not</em> the case for calls to the elementary mathematical
functions defined in the <code>Math</code> and <code>StrictMath</code>
 classes. For the known functions the derivative computation are inlined.
+ classes. For these known functions the derivatives computations are inlined.
For example a call to the <code>Math.cos</code> function will be inlined
as a call to <code>Math.cos</code>, a call to <code>Math.sin</code>
and some intermediate arithmetic operations.
Modified: commons/sandbox/nabla/trunk/src/site/xdoc/singularities.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/nabla/trunk/src/site/xdoc/singularities.xml?rev=802710&r1=802709&r2=802710&view=diff
==============================================================================
 commons/sandbox/nabla/trunk/src/site/xdoc/singularities.xml (original)
+++ commons/sandbox/nabla/trunk/src/site/xdoc/singularities.xml Mon Aug 10 09:54:01 2009
@@ 214,7 +214,6 @@
</p>
<p>

Blindly assuming a function is not differentiable simply
because it has a conditional is not acceptable. The
last example above is an example of this.
