commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From l..@apache.org
Subject svn commit: r802710 - in /commons/sandbox/nabla/trunk/src/site/xdoc: index.xml internals.xml singularities.xml
Date Mon, 10 Aug 2009 09:54:02 GMT
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.



Mime
View raw message