use a single set of consistent functions definitions in the analysis package

instead of one set in the analysis and another one in optimization


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

src/java/org/apache/commons/math/analysis/DifferentiableMultivariateRealFunction.java

@@ -0,0 +1,51 @@
+/*
+ * 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.math.analysis;
+
+/** 
+ * Extension of {@link MultivariateRealFunction} representing a differentiable
+ * multivariate real function.
+ * @version $Revision$ $Date$
+ * @since 2.0
+ */
+public interface DifferentiableMultivariateRealFunction extends MultivariateRealFunction {
+
+    /**
+     * Returns the partial derivative of the function with respect to a point coordinate.
+     * <p>
+     * The partial derivative is defined with respect to point coordinate
+     * x<sub>k</sub>. If the partial derivatives with respect to all coordinates are
+     * needed, it may be more efficient to use the {@link #gradient()} method which will
+     * compute them all at once.
+     * </p>
+     * @param k index of the coordinate with respect to which the partial
+     * derivative is computed
+     * @return the partial derivative function with respect to k<sup>th</sup> point coordinate
+     */
+    MultivariateRealFunction partialDerivative(int k);
+
+    /**
+     * Returns the gradient function.
+     * <p>If only one partial derivative with respect to a specific coordinate is
+     * needed, it may be more efficient to use the {@link #partialDerivative(int)} method
+     * which will compute only the specified component.</p>
+     * @return the gradient function
+     */
+    MultivariateVectorialFunction gradient();
+
+}

src/java/org/apache/commons/math/analysis/DifferentiableMultivariateVectorialFunction.java

@@ -0,0 +1,74 @@
+/*
+ * 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.math.analysis;
+
+
+/** 
+ * Extension of {@link MultivariateVectorialFunction} representing a differentiable
+ * multivariate vectorial function.
+ * @version $Revision$ $Date$
+ * @since 2.0
+ */
+public interface DifferentiableMultivariateVectorialFunction
+    extends MultivariateVectorialFunction {
+
+    /**
+     * Returns the partial derivative of the function with respect to point
+     * coordinate x<sub>j</sub>.
+     * <p>
+     * The partial derivative basically represents column j of the jacobian
+     * matrix. If the partial derivatives with respect to all coordinates are
+     * needed, it may be more efficient to use the {@link #jacobian()} method
+     * which will compute the complete matrix at once.
+     * </p>
+     * @param j index of the coordinate with respect to which the partial
+     * derivative is computed
+     * @return the partial derivative function with respect to point coordinate
+     * x<sub>i</sub>
+     */
+    MultivariateVectorialFunction partialDerivative(int j);
+
+    /**
+     * Returns the gradient function of the i<sup>th</sup> component of
+     * the vectorial function.
+     * 
+     * <p>
+     * The i<sup>th</sup> gradient basically represents row i of the jacobian
+     * matrix. If all gradients are needed, it may be more efficient to use the
+     * {@link #jacobian()} method which will compute the complete matrix at once.
+     * </p>
+     * @param i index of the function component for which the gradient is requested
+     * @return the gradient function of the i<sup>th</sup> component of
+     * the vectorial function
+     */
+    MultivariateVectorialFunction gradient(int i);
+
+    /**
+     * Returns the jacobian function.
+     * <p>
+     * If only one column of the jacobian is needed, it may be more efficient to
+     * use the {@link #partialDerivative(int)} method which will compute only the
+     * specified column. If only one row of the jacobian is needed, it may be more
+     * efficient to use the {@link #gradient(int)} method which will compute only the
+     * specified row.
+     * </p>
+     * @return the jacobian function
+     */
+    MultivariateMatrixFunction jacobian();
+
+}

src/java/org/apache/commons/math/analysis/DifferentiableUnivariateMatrixFunction.java

@@ -0,0 +1,35 @@
+/*
+ * 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.math.analysis;
+
+/**
+ * Extension of {@link UnivariateMatrixFunction} representing a differentiable univariate matrix function.
+ *
+ * @version $Revision$ $Date$
+ * @since 2.0
+ */
+public interface DifferentiableUnivariateMatrixFunction
+    extends UnivariateMatrixFunction {
+ 
+    /**
+     * Returns the derivative of the function
+     * 
+     * @return  the derivative function
+     */
+    public UnivariateMatrixFunction derivative();
+
+}

src/java/org/apache/commons/math/analysis/DifferentiableUnivariateVectorialFunction.java

@@ -0,0 +1,35 @@
+/*
+ * 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.math.analysis;
+
+/**
+ * Extension of {@link UnivariateVectorialFunction} representing a differentiable univariate vectorial function.
+ *
+ * @version $Revision$ $Date$
+ * @since 2.0
+ */
+public interface DifferentiableUnivariateVectorialFunction
+    extends UnivariateVectorialFunction {
+ 
+    /**
+     * Returns the derivative of the function
+     * 
+     * @return  the derivative function
+     */
+    public UnivariateVectorialFunction derivative();
+
+}

src/java/org/apache/commons/math/analysis/MultivariateMatrixFunction.java

@@ -15,24 +15,27 @@
  * limitations under the License.
  */
 
-package org.apache.commons.math.optimization;
+package org.apache.commons.math.analysis;
+
+import java.io.Serializable;
+
+import org.apache.commons.math.FunctionEvaluationException;
 
 /** 
- * This interface represents a vectorial objective function that can be differentiated.
+ * An interface representing a multivariate matrix function.
  * @version $Revision$ $Date$
  * @since 2.0
  */
-public interface VectorialDifferentiableObjectiveFunction extends VectorialObjectiveFunction {
+public interface MultivariateMatrixFunction extends Serializable {
 
     /** 
-     * Compute the jacobian of the objective function.
-     * @param variables variables set
-     * @param value value of the objective function (already computed)
-     * @return jacobian of the objective function
-     * @exception ObjectiveException if no cost can be computed for the parameters
-     * @exception IllegalArgumentException if variables dimension is wrong
+     * 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 FunctionEvaluationException if the function evaluation fails
+     * @exception IllegalArgumentException if points dimension is wrong
      */
-    double[][] jacobian(double[] variables, double[] value)
-        throws ObjectiveException, IllegalArgumentException;
+    double[][] value(double[] point)
+        throws FunctionEvaluationException, IllegalArgumentException;
 
 }

src/java/org/apache/commons/math/analysis/MultivariateRealFunction.java

@@ -15,26 +15,27 @@
  * limitations under the License.
  */
 
-package org.apache.commons.math.optimization;
+package org.apache.commons.math.analysis;
 
 import java.io.Serializable;
 
+import org.apache.commons.math.FunctionEvaluationException;
+
 /** 
- * This interface represents a vectorial objective function to be either minimized or maximized.
- * @see LeastSquaresConverter
+ * An interface representing a multivariate real function.
  * @version $Revision$ $Date$
  * @since 2.0
  */
-public interface VectorialObjectiveFunction extends Serializable {
+public interface MultivariateRealFunction extends Serializable {
 
     /** 
-     * Compute the function value for the given variables set.
-     * @param variables variables set
-     * @return function value for the given variables set
-     * @exception ObjectiveException if no cost can be computed for the parameters
-     * @exception IllegalArgumentException if variables dimension is wrong
+     * 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 FunctionEvaluationException if the function evaluation fails
+     * @exception IllegalArgumentException if points dimension is wrong
      */
-    double[] objective(double[] variables)
-        throws ObjectiveException, IllegalArgumentException;
+    double value(double[] point)
+        throws FunctionEvaluationException, IllegalArgumentException;
 
 }

src/java/org/apache/commons/math/analysis/MultivariateVectorialFunction.java

@@ -0,0 +1,41 @@
+/*
+ * 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.math.analysis;
+
+import java.io.Serializable;
+
+import org.apache.commons.math.FunctionEvaluationException;
+
+/** 
+ * An interface representing a multivariate vectorial function.
+ * @version $Revision$ $Date$
+ * @since 2.0
+ */
+public interface MultivariateVectorialFunction extends Serializable {
+
+    /** 
+     * 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 FunctionEvaluationException if the function evaluation fails
+     * @exception IllegalArgumentException if points dimension is wrong
+     */
+    double[] value(double[] point)
+        throws FunctionEvaluationException, IllegalArgumentException;
+
+}

src/java/org/apache/commons/math/analysis/UnivariateMatrixFunction.java

@@ -14,26 +14,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
-package org.apache.commons.math.optimization;
+package org.apache.commons.math.analysis;
 
 import java.io.Serializable;
 
+import org.apache.commons.math.FunctionEvaluationException;
+
 /**
- * This interface represents a scalar objective function to be either minimized or maximized.
+ * An interface representing a univariate matrix function.
+ *  
  * @version $Revision$ $Date$
  * @since 2.0
  */
-public interface ScalarObjectiveFunction extends Serializable {
-
+public interface UnivariateMatrixFunction extends Serializable {
     /**
-     * Compute the function value for the given variables set.
-     * @param variables variables set
-     * @return function value for the given variables set
-     * @exception ObjectiveException if no value can be computed for the parameters
-     * @exception IllegalArgumentException if variables dimension is wrong
+     * Compute the value for the function.
+     * @param x the point for which the function value should be computed
+     * @return the value
+     * @throws FunctionEvaluationException if the function evaluation fails
      */
-    double objective(double[] variables)
-        throws ObjectiveException, IllegalArgumentException;
+    public double[][] value(double x) throws FunctionEvaluationException;
 
 }

src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.math.analysis;
 
+import java.io.Serializable;
+
 import org.apache.commons.math.FunctionEvaluationException;
 
 /**
@@ -23,7 +25,7 @@ import org.apache.commons.math.FunctionEvaluationException;
  *  
  * @version $Revision$ $Date$
  */
-public interface UnivariateRealFunction {
+public interface UnivariateRealFunction extends Serializable {
     /**
      * Compute the value for the function.
      * @param x the point for which the function value should be computed

src/java/org/apache/commons/math/analysis/UnivariateVectorialFunction.java

@@ -14,24 +14,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+package org.apache.commons.math.analysis;
 
-package org.apache.commons.math.optimization;
+import java.io.Serializable;
+
+import org.apache.commons.math.FunctionEvaluationException;
 
 /**
- * This interface represents a scalar objective function that can be differentiated.
+ * An interface representing a univariate vectorial function.
+ *  
  * @version $Revision$ $Date$
  * @since 2.0
  */
-public interface ScalarDifferentiableObjectiveFunction extends ScalarObjectiveFunction {
-
+public interface UnivariateVectorialFunction extends Serializable {
     /**
-     * Compute the partial derivatives of the objective function.
-     * @param variables variables set
-     * @return partial derivatives of the objective function
-     * @exception ObjectiveException if no value can be computed for the parameters
-     * @exception IllegalArgumentException if variables dimension is wrong
+     * Compute the value for the function.
+     * @param x the point for which the function value should be computed
+     * @return the value
+     * @throws FunctionEvaluationException if the function evaluation fails
      */
-    double[] partials(double[] variables)
-        throws ObjectiveException, IllegalArgumentException;
+    public double[] value(double x) throws FunctionEvaluationException;
 
 }

src/java/org/apache/commons/math/analysis/package.html

@@ -16,8 +16,18 @@
    limitations under the License.
   -->
     <!-- $Revision$ $Date$ -->
-    <body>
-     Parent package for common numerical analysis procedures, including root finding,
-     function interpolation and integration.
-    </body>
+  <body>
+    <p>
+      Parent package for common numerical analysis procedures, including root finding,
+      function interpolation and integration. Note that the optimization (i.e. minimization
+      and maximization) is a huge separate top package, despite it also operate on functions
+      as defined by this top-level package.
+    </p>
+    <p>
+      Functions interfaces are intended to be implemented by user code to represent their
+      domain problems. The algorithms provided by the library will then operate on these
+      function to find their roots, or integrate them, or ... Functions can be multivariate
+      or univariate, real vectorial or matrix valued, and they can be differentiable or not.
+    </p>
+  </body>
 </html>