Differentiable function can trigger any MathIllegalArgumentException.

One very important case corresponds to an unsupported derivation order.
The order is not enforced in the API, but is specified as the properties
of the DerivativeStructure argument, as well as the number of free
parameters. Some functions have no limitation on this order (typically
functions implemented using only the DerivativeStructure API), but some
functions may limit the derivation order to 1 or 2 as they implement the
differentiation themselves or through finite differences.

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

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

@@ -18,7 +18,6 @@
 package org.apache.commons.math3.analysis.differentiation;
 
 import org.apache.commons.math3.analysis.MultivariateFunction;
-import org.apache.commons.math3.exception.DimensionMismatchException;
 import org.apache.commons.math3.exception.MathIllegalArgumentException;
 
 /**
@@ -34,16 +33,11 @@ public interface MultivariateDifferentiableFunction extends MultivariateFunction
      *
      * @param point Point at which the function must be evaluated.
      * @return the function value for the given point.
-     * @throws org.apache.commons.math3.exception.DimensionMismatchException
-     * if the parameter's dimension is wrong for the function being evaluated.
-     * @throws  org.apache.commons.math3.exception.MathIllegalArgumentException
-     * when the activated method itself can ascertain that preconditions,
-     * specified in the API expressed at the level of the activated method,
-     * have been violated.  In the vast majority of cases where Commons Math
-     * throws this exception, it is the result of argument checking of actual
-     * parameters immediately passed to a method.
+     * @exception MathIllegalArgumentException if {@code point} does not
+     * fulfill functions constraints (wrong dimension, argument out of bound,
+     * or unsupported derivative order for example)
      */
     DerivativeStructure value(DerivativeStructure[] point)
-        throws DimensionMismatchException, MathIllegalArgumentException;
+        throws MathIllegalArgumentException;
 
 }

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

@@ -18,7 +18,7 @@
 package org.apache.commons.math3.analysis.differentiation;
 
 import org.apache.commons.math3.analysis.MultivariateVectorFunction;
-import org.apache.commons.math3.exception.DimensionMismatchException;
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 
 
 /**
@@ -34,9 +34,11 @@ public interface MultivariateDifferentiableVectorFunction
      * Compute the value for the function at the given point.
      * @param point point at which the function must be evaluated
      * @return function value for the given point
-     * @exception DimensionMismatchException if points dimension is wrong
+     * @exception MathIllegalArgumentException if {@code point} does not
+     * fulfill functions constraints (wrong dimension, argument out of bound,
+     * or unsupported derivative order for example)
      */
     DerivativeStructure[] value(DerivativeStructure[] point)
-        throws DimensionMismatchException;
+        throws MathIllegalArgumentException;
 
 }

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

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.analysis.differentiation;
 
 import org.apache.commons.math3.analysis.UnivariateFunction;
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 
 /** Interface for univariate functions derivatives.
  * <p>This interface represents a simple function which computes
@@ -34,7 +35,10 @@ public interface UnivariateDifferentiableFunction extends UnivariateFunction {
      * value and the first derivative of the function.</p>
      * @param t function input value
      * @return function result
+     * @exception MathIllegalArgumentException if {@code t} does not
+     * fulfill functions constraints (argument out of bound, or unsupported
+     * derivative order for example)
      */
-    DerivativeStructure value(DerivativeStructure t);
+    DerivativeStructure value(DerivativeStructure t) throws MathIllegalArgumentException;
 
 }

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

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.analysis.differentiation;
 
 import org.apache.commons.math3.analysis.UnivariateMatrixFunction;
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 
 /**
  * Extension of {@link UnivariateMatrixFunction} representing a univariate differentiable matrix function.
@@ -31,7 +32,10 @@ public interface UnivariateDifferentiableMatrixFunction
      * Compute the value for the function.
      * @param x the point for which the function value should be computed
      * @return the value
+     * @exception MathIllegalArgumentException if {@code x} does not
+     * fulfill functions constraints (argument out of bound, or unsupported
+     * derivative order for example)
      */
-    DerivativeStructure[][] value(DerivativeStructure x);
+    DerivativeStructure[][] value(DerivativeStructure x) throws MathIllegalArgumentException;
 
 }

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

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.analysis.differentiation;
 
 import org.apache.commons.math3.analysis.UnivariateVectorFunction;
+import org.apache.commons.math3.exception.MathIllegalArgumentException;
 
 /**
  * Extension of {@link UnivariateVectorFunction} representing a univariate differentiable vectorial function.
@@ -31,7 +32,10 @@ public interface UnivariateDifferentiableVectorFunction
      * Compute the value for the function.
      * @param x the point for which the function value should be computed
      * @return the value
+     * @exception MathIllegalArgumentException if {@code x} does not
+     * fulfill functions constraints (argument out of bound, or unsupported
+     * derivative order for example)
      */
-    DerivativeStructure[] value(DerivativeStructure x);
+    DerivativeStructure[] value(DerivativeStructure x) throws MathIllegalArgumentException;
 
 }