View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math.estimation;
19  
20  /**
21   * This interface represents solvers for estimation problems.
22   *
23   * <p>The classes which are devoted to solve estimation problems
24   * should implement this interface. The problems which can be handled
25   * should implement the {@link EstimationProblem} interface which
26   * gather all the information needed by the solver.</p>
27   *
28   * <p>The interface is composed only of the {@link #estimate estimate}
29   * method.</p>
30   *
31   * @see EstimationProblem
32   *
33   * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
34   * @since 1.2
35   *
36   */
37  
38  public interface Estimator {
39  
40    /** 
41     * Solve an estimation problem.
42     *
43     * <p>The method should set the parameters of the problem to several
44     * trial values until it reaches convergence. If this method returns
45     * normally (i.e. without throwing an exception), then the best
46     * estimate of the parameters can be retrieved from the problem
47     * itself, through the {@link EstimationProblem#getAllParameters
48     * EstimationProblem.getAllParameters} method.</p>
49     *
50     * @param problem estimation problem to solve
51     * @exception EstimationException if the problem cannot be solved
52     *
53     */
54    public void estimate(EstimationProblem problem)
55      throws EstimationException;
56  
57    /** 
58     * Get the Root Mean Square value.
59     * Get the Root Mean Square value, i.e. the root of the arithmetic
60     * mean of the square of all weighted residuals. This is related to the
61     * criterion that is minimized by the estimator as follows: if
62     * <em>c</em> is the criterion, and <em>n</em> is the number of
63     * measurements, then the RMS is <em>sqrt (c/n)</em>.
64     * @see #guessParametersErrors(EstimationProblem)
65     * 
66     * @param problem estimation problem
67     * @return RMS value
68     */
69    public double getRMS(EstimationProblem problem);
70  
71    /**
72     * Get the covariance matrix of estimated parameters.
73     * @param problem estimation problem
74     * @return covariance matrix
75     * @exception EstimationException if the covariance matrix
76     * cannot be computed (singular problem)
77     */
78    public double[][] getCovariances(EstimationProblem problem)
79      throws EstimationException;
80  
81    /**
82     * Guess the errors in estimated parameters.
83     * @see #getRMS(EstimationProblem)
84     * @param problem estimation problem
85     * @return errors in estimated parameters
86       * @exception EstimationException if the error cannot be guessed
87     */
88    public double[] guessParametersErrors(EstimationProblem problem)
89      throws EstimationException;
90  
91  }