Added differentiator interfaces for vector and matrix functions.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1386742 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java

@@ -32,19 +32,24 @@ import org.apache.commons.math3.util.FastMath;
  * 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$

src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateDifferentiableFunction.java

@@ -24,7 +24,7 @@ import org.apache.commons.math3.exception.MathIllegalArgumentException;
  * 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$
  */

src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateFunctionDifferentiator.java

@@ -22,10 +22,10 @@ import org.apache.commons.math3.analysis.UnivariateFunction;
  * @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
      */

src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateMatrixFunctionDifferentiator.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.math3.analysis.differentiation;
+
+import org.apache.commons.math3.analysis.UnivariateMatrixFunction;
+
+/** Interface defining the function differentiation operation.
+ * @version $Id$
+ * @since 3.1
+ */
+public interface UnivariateMatrixFunctionDifferentiator {
+
+    /** Create an implementation of a {@link UnivariateDifferentiableMatrixFunction
+     * differential} from a regular {@link UnivariateMatrixFunction matrix function}.
+     * @param function function to differentiate
+     * @return differential function
+     */
+    UnivariateDifferentiableMatrixFunction differentiate(UnivariateMatrixFunction function);
+
+}

src/main/java/org/apache/commons/math3/analysis/differentiation/UnivariateVectorFunctionDifferentiator.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.math3.analysis.differentiation;
+
+import org.apache.commons.math3.analysis.UnivariateVectorFunction;
+
+/** Interface defining the function differentiation operation.
+ * @version $Id$
+ * @since 3.1
+ */
+public interface UnivariateVectorFunctionDifferentiator {
+
+    /** Create an implementation of a {@link UnivariateDifferentiableVectorFunction
+     * differential} from a regular {@link UnivariateVectorFunction vector function}.
+     * @param function function to differentiate
+     * @return differential function
+     */
+    UnivariateDifferentiableVectorFunction differentiate(UnivariateVectorFunction function);
+
+}

src/main/java/org/apache/commons/math3/analysis/differentiation/package-info.java

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