    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    }