001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.math.estimation;
019    
020    /**
021     * This interface represents solvers for estimation problems.
022     *
023     * <p>The classes which are devoted to solve estimation problems
024     * should implement this interface. The problems which can be handled
025     * should implement the {@link EstimationProblem} interface which
026     * gather all the information needed by the solver.</p>
027     *
028     * <p>The interface is composed only of the {@link #estimate estimate}
029     * method.</p>
030     *
031     * @see EstimationProblem
032     *
033     * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
034     * @since 1.2
035     * @deprecated as of 2.0, everything in package org.apache.commons.math.estimation has
036     * been deprecated and replaced by package org.apache.commons.math.optimization.general
037     *
038     */
039    @Deprecated
040    public interface Estimator {
041    
042      /**
043       * Solve an estimation problem.
044       *
045       * <p>The method should set the parameters of the problem to several
046       * trial values until it reaches convergence. If this method returns
047       * normally (i.e. without throwing an exception), then the best
048       * estimate of the parameters can be retrieved from the problem
049       * itself, through the {@link EstimationProblem#getAllParameters
050       * EstimationProblem.getAllParameters} method.</p>
051       *
052       * @param problem estimation problem to solve
053       * @exception EstimationException if the problem cannot be solved
054       *
055       */
056      void estimate(EstimationProblem problem) throws EstimationException;
057    
058      /**
059       * Get the Root Mean Square value.
060       * Get the Root Mean Square value, i.e. the root of the arithmetic
061       * mean of the square of all weighted residuals. This is related to the
062       * criterion that is minimized by the estimator as follows: if
063       * <em>c</em> is the criterion, and <em>n</em> is the number of
064       * measurements, then the RMS is <em>sqrt (c/n)</em>.
065       * @see #guessParametersErrors(EstimationProblem)
066       *
067       * @param problem estimation problem
068       * @return RMS value
069       */
070      double getRMS(EstimationProblem problem);
071    
072      /**
073       * Get the covariance matrix of estimated parameters.
074       * @param problem estimation problem
075       * @return covariance matrix
076       * @exception EstimationException if the covariance matrix
077       * cannot be computed (singular problem)
078       */
079      double[][] getCovariances(EstimationProblem problem) throws EstimationException;
080    
081      /**
082       * Guess the errors in estimated parameters.
083       * @see #getRMS(EstimationProblem)
084       * @param problem estimation problem
085       * @return errors in estimated parameters
086         * @exception EstimationException if the error cannot be guessed
087       */
088      double[] guessParametersErrors(EstimationProblem problem) throws EstimationException;
089    
090    }