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
This commit is contained in:
Luc Maisonobe 2009-03-24 22:05:13 +00:00
parent 31e9c848f2
commit 187dd35c9a
11 changed files with 306 additions and 54 deletions

View File

@ -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();
}

View File

@ -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();
}

View File

@ -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();
}

View File

@ -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();
}

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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