1 /*
2 * Copyright (C) 2015 Alberto Irurueta Carro (alberto@irurueta.com)
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package com.irurueta.numerical.fitting;
17
18 import com.irurueta.numerical.EvaluationException;
19
20 /**
21 * Interface to evaluate non-linear multidimensional functions.
22 * Evaluation of functions requires both function value at provided point x and
23 * function gradient respect to its parameters (i.e. derivatives respect to its
24 * parameters).
25 */
26 public interface LevenbergMarquardtMultiDimensionFunctionEvaluator {
27
28 /**
29 * Number of dimensions of points (i.e. length of arrays) evaluated by
30 * this function evaluator.
31 *
32 * @return number of dimensions of points.
33 */
34 int getNumberOfDimensions();
35
36 /**
37 * Creates array where estimated parameters will be stored.
38 * This array MUST contain the initial guessed solution for the Levenberg-
39 * Marquardt algorithm.
40 *
41 * @return array where estimated parameters will be stored.
42 */
43 double[] createInitialParametersArray();
44
45 /**
46 * Evaluates a non-linear multi dimension function at provided point using
47 * provided parameters and returns its evaluation and derivatives of the
48 * function respect the function parameters.
49 *
50 * @param i number of sample being evaluated.
51 * @param point point where function will be evaluated.
52 * @param params initial parameters estimation to be tried. These will
53 * change as the Levenberg-Marquard algorithm iterates to the best solution.
54 * These are used as input parameters along with point to evaluate function.
55 * @param derivatives partial derivatives of the function respect to each
56 * provided parameter.
57 * @return function evaluation at provided point.
58 * @throws EvaluationException raised if something failed during the evaluation.
59 */
60 double evaluate(final int i, final double[] point, final double[] params,
61 final double[] derivatives) throws EvaluationException;
62 }