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: 754732 $ $Date: 2009-03-15 15:30:44 -0400 (Sun, 15 Mar 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      public void estimate(EstimationProblem problem)
057        throws EstimationException;
058    
059      /** 
060       * Get the Root Mean Square value.
061       * Get the Root Mean Square value, i.e. the root of the arithmetic
062       * mean of the square of all weighted residuals. This is related to the
063       * criterion that is minimized by the estimator as follows: if
064       * <em>c</em> is the criterion, and <em>n</em> is the number of
065       * measurements, then the RMS is <em>sqrt (c/n)</em>.
066       * @see #guessParametersErrors(EstimationProblem)
067       * 
068       * @param problem estimation problem
069       * @return RMS value
070       */
071      public double getRMS(EstimationProblem problem);
072    
073      /**
074       * Get the covariance matrix of estimated parameters.
075       * @param problem estimation problem
076       * @return covariance matrix
077       * @exception EstimationException if the covariance matrix
078       * cannot be computed (singular problem)
079       */
080      public double[][] getCovariances(EstimationProblem problem)
081        throws EstimationException;
082    
083      /**
084       * Guess the errors in estimated parameters.
085       * @see #getRMS(EstimationProblem)
086       * @param problem estimation problem
087       * @return errors in estimated parameters
088         * @exception EstimationException if the error cannot be guessed
089       */
090      public double[] guessParametersErrors(EstimationProblem problem)
091        throws EstimationException;
092    
093    }