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.algebra.Matrix;
19 import com.irurueta.numerical.EvaluationException;
20
21 /**
22 * Interface to evaluate non-linear multi variate and multidimensional
23 * functions.
24 * Evaluation of functions requires both function value at provided point x and
25 * function jacobian respect to its parameters (i.e. derivatives respect to its
26 * parameters for each function output or variable)
27 */
28 public interface LevenbergMarquardtMultiVariateFunctionEvaluator {
29
30 /**
31 * Number of dimensions of points (i.e. length of input points arrays)
32 * evaluated by this function evaluator
33 *
34 * @return number of dimensions of points
35 */
36 int getNumberOfDimensions();
37
38 /**
39 * Number of variables of function f. This is equal to the length of the
40 * array obtained as function evaluations. Hence, a function f can
41 * be expressed as f = [f1, f2, ... fN], and the number of variables would
42 * be N
43 *
44 * @return number of variables of function f
45 */
46 int getNumberOfVariables();
47
48 /**
49 * Creates array where estimated parameters will be stored.
50 * This array MUST contain the initial guessed solution for the Levenberg-
51 * Marquardt algorithm
52 *
53 * @return array where estimated parameters will be stored
54 */
55 double[] createInitialParametersArray();
56
57 /**
58 * Evaluates a non-linear multi variate function at provided point using
59 * provided parameters and returns its evaluation and jacobian of the
60 * function respect the function parameters
61 *
62 * @param i number of sample being evaluated
63 * @param point point where function will be evaluated
64 * @param result result of function evaluation. Its length is equal to the
65 * number of function variables
66 * @param params initial parameters estimation to be tried. These will
67 * change as the Levenberg-Marquard algorithm iterates to the best solution.
68 * These are used as input parameters along with point to evaluate function
69 * @param jacobian jacobian containing partial derivatives of the function
70 * respect to each provided parameter for each function output or variable
71 * @throws EvaluationException raised if something failed during the evaluation
72 */
73 void evaluate(final int i, final double[] point, final double[] result, final double[] params,
74 final Matrix jacobian) throws EvaluationException;
75
76 }