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 2009/08/10 11:54:02 UTC
svn commit: r802710 - in /commons/sandbox/nabla/trunk/src/site/xdoc:
index.xml internals.xml singularities.xml
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/">commons-math</a>
- library. Functions passed to any commons-math solver must
- implement a specific
+ Brent solver</a> from the <a href="http://commons.apache.org/math/">commons-math</a>
+ library. Functions passed to any commons-math 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.