- The maximal value is reached when the first derivative of - the function is equal to zero. So we need to compute the - first derivative f'(t) and find its - roots. Nabla will help in the first part: - computing f'(t). We start by implementing the + In order to compute f'(t). We start by implementing the function f(t):

- We get the maximal value by calling a solver on the + The derivative object implements the UnivariateDerivative + interface which means it provides a method f which is an enhanced + version of the f method of the original function object: + it computes both the value and the derivative of the function. +

+ We can therefore find the maximal value by calling a solver on the derivative. In this example, we will use the - Brent solver from - the commons-math - library. Functions passed to any commons-math solver must - implement a specific + Brent solver from the commons-math + library. Functions passed to any commons-math solver must implement a specific interface: UnivariateRealFunction. In order to comply with this requirement, we wrap the derivative object into another @@ -187,7 +189,7 @@

- 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 @@

- 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: +

analyzing the bytecode of the original object,
transforming the arithmetic operations along all possible + execution passes using the classical differentiation rules,
generating a new class on the fly with the transformed bytecode,
instantiating the generated class to create the derivative object.

+ This works for any pure Java function, or more generally for any program using the Java platform as its execution environment.

- 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.

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 @@

- 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 UnivariateDifferentiable is passed to its differentiate method, Nabla tracks the mathematical operations flow that leads from the t 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). +

+ +

+ Analysis and transformation of the bytecode is realized using both + the core API and the tree API from the asm + bytecode manipulation and analysis framework. The entry point of this differentiation process is the visitEnd method of the MethodDifferentiator @@ -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 DADD bytecode instruction corresponds +

+ +

+ Lets consider the DADD 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:

c=a+b

and we combine this with its derivative to form the pair:

(c=a+b, c'=a'+b')

@@ -145,8 +154,7 @@

This example shows that the instructions conversions have local - scope. No global tree representation of the method is needed - at all. + scope.

@@ -168,7 +176,7 @@ others will be build in the callee to return results to the caller. This is not the case for calls to the elementary mathematical functions defined in the Math and StrictMath - 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 Math.cos function will be inlined as a call to Math.cos, a call to Math.sin 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 @@

- 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.