Java example source code file (LeastSquaresProblem.java)

This example Java source code file (LeastSquaresProblem.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

evaluation, leastsquaresproblem, realmatrix, realvector

The LeastSquaresProblem.java Java example source code

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.math3.fitting.leastsquares;

import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.linear.RealVector;
import org.apache.commons.math3.optim.OptimizationProblem;

/**
 * The data necessary to define a non-linear least squares problem.
 * <p>
 * Includes the observed values, computed model function, and
 * convergence/divergence criteria. Weights are implicit in {@link
 * Evaluation#getResiduals()} and {@link Evaluation#getJacobian()}.
 * </p>
 * <p>
 * Instances are typically either created progressively using a {@link
 * LeastSquaresBuilder builder} or created at once using a {@link LeastSquaresFactory
 * factory}.
 * </p>
 * @see LeastSquaresBuilder
 * @see LeastSquaresFactory
 * @see LeastSquaresAdapter
 *
 * @since 3.3
 */
public interface LeastSquaresProblem extends OptimizationProblem<LeastSquaresProblem.Evaluation> {

    /**
     * Gets the initial guess.
     *
     * @return the initial guess values.
     */
    RealVector getStart();

    /**
     * Get the number of observations (rows in the Jacobian) in this problem.
     *
     * @return the number of scalar observations
     */
    int getObservationSize();

    /**
     * Get the number of parameters (columns in the Jacobian) in this problem.
     *
     * @return the number of scalar parameters
     */
    int getParameterSize();

    /**
     * Evaluate the model at the specified point.
     *
     *
     * @param point the parameter values.
     * @return the model's value and derivative at the given point.
     * @throws org.apache.commons.math3.exception.TooManyEvaluationsException
     *          if the maximal number of evaluations (of the model vector function) is
     *          exceeded.
     */
    Evaluation evaluate(RealVector point);

    /**
     * An evaluation of a {@link LeastSquaresProblem} at a particular point. This class
     * also computes several quantities derived from the value and its Jacobian.
     */
    public interface Evaluation {

        /**
         * Get the covariance matrix of the optimized parameters. <br/> Note that this
         * operation involves the inversion of the <code>JTJ matrix,
         * where {@code J} is the Jacobian matrix. The {@code threshold} parameter is a
         * way for the caller to specify that the result of this computation should be
         * considered meaningless, and thus trigger an exception.
         *
         *
         * @param threshold Singularity threshold.
         * @return the covariance matrix.
         * @throws org.apache.commons.math3.linear.SingularMatrixException
         *          if the covariance matrix cannot be computed (singular problem).
         */
        RealMatrix getCovariances(double threshold);

        /**
         * Get an estimate of the standard deviation of the parameters. The returned
         * values are the square root of the diagonal coefficients of the covariance
         * matrix, {@code sd(a[i]) ~= sqrt(C[i][i])}, where {@code a[i]} is the optimized
         * value of the {@code i}-th parameter, and {@code C} is the covariance matrix.
         *
         *
         * @param covarianceSingularityThreshold Singularity threshold (see {@link
         *                                       #getCovariances(double) computeCovariances}).
         * @return an estimate of the standard deviation of the optimized parameters
         * @throws org.apache.commons.math3.linear.SingularMatrixException
         *          if the covariance matrix cannot be computed.
         */
        RealVector getSigma(double covarianceSingularityThreshold);

        /**
         * Get the normalized cost. It is the square-root of the sum of squared of
         * the residuals, divided by the number of measurements.
         *
         * @return the cost.
         */
        double getRMS();

        /**
         * Get the weighted Jacobian matrix.
         *
         * @return the weighted Jacobian: W<sup>1/2 J.
         * @throws org.apache.commons.math3.exception.DimensionMismatchException
         * if the Jacobian dimension does not match problem dimension.
         */
        RealMatrix getJacobian();

        /**
         * Get the cost.
         *
         * @return the cost.
         * @see #getResiduals()
         */
        double getCost();

        /**
         * Get the weighted residuals. The residual is the difference between the
         * observed (target) values and the model (objective function) value. There is one
         * residual for each element of the vector-valued function. The raw residuals are
         * then multiplied by the square root of the weight matrix.
         *
         * @return the weighted residuals: W<sup>1/2 K.
         * @throws org.apache.commons.math3.exception.DimensionMismatchException
         * if the residuals have the wrong length.
         */
        RealVector getResiduals();

        /**
         * Get the abscissa (independent variables) of this evaluation.
         *
         * @return the point provided to {@link #evaluate(RealVector)}.
         */
        RealVector getPoint();
    }
}