svn commit: r1386742 - /commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/

[lu...@apache.org]

Author: luc
Date: Mon Sep 17 17:41:54 2012
New Revision: 1386742

URL: http://svn.apache.org/viewvc?rev=1386742&view=rev
Log:
Added differentiator interfaces for vector and matrix functions.

Added:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java
      - copied, changed from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java
      - copied, changed from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java   (contents, props changed)
      - copied, changed from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java
Removed:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java
Modified:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java?rev=1386742&r1=1386741&r2=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java Mon Sep 17 17:41:54 2012
@@ -32,19 +32,24 @@ import org.apache.commons.math3.util.Fas
  * Recursive Multivariate Automatic Differentiation</a>, Mathematics Magazine, vol. 75,
  * no. 3, June 2002.</p>. Rall's numbers are an extension to the real numbers used
  * throughout mathematical expressions; they hold the derivative together with the
- * value of a function. Dan Kalman's derivative structures holds all partial derivatives
- * up to any specified order, with respect to any number of free variables. Rall's
- * number therefore can be seen as derivative structures for order one derivative and
- * one free variable, and real numbers can be seen as derivative structures with zero
- * order derivative and no free variables.</p>
+ * value of a function. Dan Kalman's derivative structures hold all partial derivatives
+ * up to any specified order, with respect to any number of free parameters. Rall's
+ * numbers therefore can be seen as derivative structures for order one derivative and
+ * one free parameter, and real numbers can be seen as derivative structures with zero
+ * order derivative and no free parameters.</p>
  * <p>{@link DerivativeStructure} instances can be used directly thanks to
  * the arithmetic operators to the mathematical functions provided as static
  * methods by this class (+, -, *, /, %, sin, cos ...).</p>
  * <p>Implementing complex expressions by hand using these classes is
- * however a complex and error-prone task, so the classical use is
- * simply to develop computation code using standard primitive double
- * values and to use {@link UnivariateDifferentiator differentiators} to create
- * the {@link DerivativeStructure}-based instances.</p>
+ * a tedious and error-prone task but has the advantage of having no limitation
+ * on the derivation order despite no requiring users to compute the derivatives by
+ * themselves. Implementing complex expression can also be done by developing computation
+ * code using standard primitive double values and to use {@link
+ * UnivariateFunctionDifferentiator differentiators} to create the {@link
+ * DerivativeStructure}-based instances. This method is simpler but may be limited in
+ * the accuracy and derivation orders and may be computationally intensive (this is
+ * typically the case for {@link FiniteDifferencesDifferentiator finite differences
+ * differentiator).</p>
  * <p>Instances of this class are guaranteed to be immutable.</p>
  * @see DSCompiler
  * @version $Id$

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java?rev=1386742&r1=1386741&r2=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java Mon Sep 17 17:41:54 2012
@@ -24,7 +24,7 @@ import org.apache.commons.math3.exceptio
  * both the value and the first derivative of a mathematical function.
  * The derivative is computed with respect to the input variable.</p>
  * @see UnivariateDifferentiableFunction
- * @see UnivariateDifferentiator
+ * @see UnivariateFunctionDifferentiator
  * @since 3.1
  * @version $Id$
  */

Copied: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java (from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java)
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java?p2=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java&p1=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java&r1=1386741&r2=1386742&rev=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java Mon Sep 17 17:41:54 2012
@@ -22,10 +22,10 @@ import org.apache.commons.math3.analysis
  * @version $Id$
  * @since 3.1
  */
-public interface UnivariateDifferentiator {
+public interface UnivariateFunctionDifferentiator {
 
-    /** Create an implementation of a differential for a
-     * {@link UnivariateDifferentiableFunction differentiable function}.
+    /** Create an implementation of a {@link UnivariateDifferentiableFunction
+     * differential} from a regular {@link UnivariateFunction function}.
      * @param function function to differentiate
      * @return differential function
      */

Copied: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java (from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java)
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java?p2=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java&p1=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java&r1=1386741&r2=1386742&rev=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java Mon Sep 17 17:41:54 2012
@@ -16,19 +16,19 @@
  */
 package org.apache.commons.math3.analysis.differentiation;
 
-import org.apache.commons.math3.analysis.UnivariateFunction;
+import org.apache.commons.math3.analysis.UnivariateMatrixFunction;
 
 /** Interface defining the function differentiation operation.
  * @version $Id$
  * @since 3.1
  */
-public interface UnivariateDifferentiator {
+public interface UnivariateMatrixFunctionDifferentiator {
 
-    /** Create an implementation of a differential for a
-     * {@link UnivariateDifferentiableFunction differentiable function}.
+    /** Create an implementation of a {@link UnivariateDifferentiableMatrixFunction
+     * differential} from a regular {@link UnivariateMatrixFunction matrix function}.
      * @param function function to differentiate
      * @return differential function
      */
-    UnivariateDifferentiableFunction differentiate(UnivariateFunction function);
+    UnivariateDifferentiableMatrixFunction differentiate(UnivariateMatrixFunction function);
 
 }

Copied: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java (from r1386741, commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java)
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java?p2=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java&p1=commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java&r1=1386741&r2=1386742&rev=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiator.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java Mon Sep 17 17:41:54 2012
@@ -16,19 +16,19 @@
  */
 package org.apache.commons.math3.analysis.differentiation;
 
-import org.apache.commons.math3.analysis.UnivariateFunction;
+import org.apache.commons.math3.analysis.UnivariateVectorFunction;
 
 /** Interface defining the function differentiation operation.
  * @version $Id$
  * @since 3.1
  */
-public interface UnivariateDifferentiator {
+public interface UnivariateVectorFunctionDifferentiator {
 
-    /** Create an implementation of a differential for a
-     * {@link UnivariateDifferentiableFunction differentiable function}.
+    /** Create an implementation of a {@link UnivariateDifferentiableVectorFunction
+     * differential} from a regular {@link UnivariateVectorFunction vector function}.
      * @param function function to differentiate
      * @return differential function
      */
-    UnivariateDifferentiableFunction differentiate(UnivariateFunction function);
+    UnivariateDifferentiableVectorFunction differentiate(UnivariateVectorFunction function);
 
 }

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java?rev=1386742&r1=1386741&r2=1386742&view=diff
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java (original)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java Mon Sep 17 17:41:54 2012
@@ -26,14 +26,14 @@
  *   interface. Any differentiable function should implement this interface.
  * </p>
  * <p>
- *   Similar interfaces also exist for multivariate functions and for vector or
- *   matrix valued functions.
- * </p>
- * <p>
- *   The {@link UnivariateDifferentiator} interface defines a way to differentiation
+ *   The {@link UnivariateFunctionDifferentiator} interface defines a way to differentiation
  *   a simple {@link org.apache.commons.math3.analysis.UnivariateFunction
  *   univariate function} and get a {@link differential function}.
  * </p>
+ * <p>
+ *   Similar interfaces also exist for multivariate functions and for vector or
+ *   matrix valued functions.
+ * </p>
  *
  */
 package org.apache.commons.math3.analysis.differentiation;