+ * The partial derivative is defined with respect to point coordinate + * xk. 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. + *
+ * @param k index of the coordinate with respect to which the partial + * derivative is computed + * @return the partial derivative function with respect to kth point coordinate + */ + MultivariateRealFunction partialDerivative(int k); + + /** + * Returns the gradient function. + *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.
+ * @return the gradient function + */ + MultivariateVectorialFunction gradient(); + +} diff --git a/src/java/org/apache/commons/math/analysis/DifferentiableMultivariateVectorialFunction.java b/src/java/org/apache/commons/math/analysis/DifferentiableMultivariateVectorialFunction.java new file mode 100644 index 000000000..1072df58d --- /dev/null +++ b/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 xj. + *+ * 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. + *
+ * @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 + * xi + */ + MultivariateVectorialFunction partialDerivative(int j); + + /** + * Returns the gradient function of the ith component of + * the vectorial function. + * + *+ * The ith 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. + *
+ * @param i index of the function component for which the gradient is requested + * @return the gradient function of the ith component of + * the vectorial function + */ + MultivariateVectorialFunction gradient(int i); + + /** + * Returns the jacobian function. + *+ * 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. + *
+ * @return the jacobian function + */ + MultivariateMatrixFunction jacobian(); + +} diff --git a/src/java/org/apache/commons/math/analysis/DifferentiableUnivariateMatrixFunction.java b/src/java/org/apache/commons/math/analysis/DifferentiableUnivariateMatrixFunction.java new file mode 100644 index 000000000..9d32e83bc --- /dev/null +++ b/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(); + +} diff --git a/src/java/org/apache/commons/math/analysis/DifferentiableUnivariateVectorialFunction.java b/src/java/org/apache/commons/math/analysis/DifferentiableUnivariateVectorialFunction.java new file mode 100644 index 000000000..aa9b25bce --- /dev/null +++ b/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(); + +} diff --git a/src/java/org/apache/commons/math/optimization/VectorialDifferentiableObjectiveFunction.java b/src/java/org/apache/commons/math/analysis/MultivariateMatrixFunction.java similarity index 54% rename from src/java/org/apache/commons/math/optimization/VectorialDifferentiableObjectiveFunction.java rename to src/java/org/apache/commons/math/analysis/MultivariateMatrixFunction.java index 3f71a1819..06ce812f8 100644 --- a/src/java/org/apache/commons/math/optimization/VectorialDifferentiableObjectiveFunction.java +++ b/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; } diff --git a/src/java/org/apache/commons/math/optimization/VectorialObjectiveFunction.java b/src/java/org/apache/commons/math/analysis/MultivariateRealFunction.java similarity index 57% rename from src/java/org/apache/commons/math/optimization/VectorialObjectiveFunction.java rename to src/java/org/apache/commons/math/analysis/MultivariateRealFunction.java index 5c5fb22b1..008810dfe 100644 --- a/src/java/org/apache/commons/math/optimization/VectorialObjectiveFunction.java +++ b/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; } diff --git a/src/java/org/apache/commons/math/analysis/MultivariateVectorialFunction.java b/src/java/org/apache/commons/math/analysis/MultivariateVectorialFunction.java new file mode 100644 index 000000000..9babee9f2 --- /dev/null +++ b/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; + +} diff --git a/src/java/org/apache/commons/math/optimization/ScalarObjectiveFunction.java b/src/java/org/apache/commons/math/analysis/UnivariateMatrixFunction.java similarity index 58% rename from src/java/org/apache/commons/math/optimization/ScalarObjectiveFunction.java rename to src/java/org/apache/commons/math/analysis/UnivariateMatrixFunction.java index cbb9ce83b..79d7efbf9 100644 --- a/src/java/org/apache/commons/math/optimization/ScalarObjectiveFunction.java +++ b/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; -/** - * This interface represents a scalar objective function to be either minimized or maximized. +import org.apache.commons.math.FunctionEvaluationException; + +/** + * An interface representing a univariate matrix function. + * * @version $Revision$ $Date$ * @since 2.0 */ -public interface ScalarObjectiveFunction 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 +public interface UnivariateMatrixFunction extends Serializable { + /** + * 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; } diff --git a/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java b/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java index 457ada762..bd79bc6e0 100644 --- a/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java +++ b/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 diff --git a/src/java/org/apache/commons/math/optimization/ScalarDifferentiableObjectiveFunction.java b/src/java/org/apache/commons/math/analysis/UnivariateVectorialFunction.java similarity index 56% rename from src/java/org/apache/commons/math/optimization/ScalarDifferentiableObjectiveFunction.java rename to src/java/org/apache/commons/math/analysis/UnivariateVectorialFunction.java index 87c2b28eb..eb5138327 100644 --- a/src/java/org/apache/commons/math/optimization/ScalarDifferentiableObjectiveFunction.java +++ b/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; -/** - * This interface represents a scalar objective function that can be differentiated. +import org.apache.commons.math.FunctionEvaluationException; + +/** + * An interface representing a univariate vectorial function. + * * @version $Revision$ $Date$ * @since 2.0 */ -public interface ScalarDifferentiableObjectiveFunction extends ScalarObjectiveFunction { - - /** - * 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 +public interface UnivariateVectorialFunction extends Serializable { + /** + * 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; } diff --git a/src/java/org/apache/commons/math/analysis/package.html b/src/java/org/apache/commons/math/analysis/package.html index 2621a9397..0b26f7522 100644 --- a/src/java/org/apache/commons/math/analysis/package.html +++ b/src/java/org/apache/commons/math/analysis/package.html @@ -16,8 +16,18 @@ limitations under the License. --> - - Parent package for common numerical analysis procedures, including root finding, - function interpolation and integration. - + ++ 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. +
++ 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. +
+