LeastSquaresBuilder.java

  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. package org.apache.commons.math4.legacy.fitting.leastsquares;

  18. import org.apache.commons.math4.legacy.analysis.MultivariateMatrixFunction;
  19. import org.apache.commons.math4.legacy.analysis.MultivariateVectorFunction;
  20. import org.apache.commons.math4.legacy.fitting.leastsquares.LeastSquaresProblem.Evaluation;
  21. import org.apache.commons.math4.legacy.linear.ArrayRealVector;
  22. import org.apache.commons.math4.legacy.linear.RealMatrix;
  23. import org.apache.commons.math4.legacy.linear.RealVector;
  24. import org.apache.commons.math4.legacy.optim.ConvergenceChecker;
  25. import org.apache.commons.math4.legacy.optim.PointVectorValuePair;

  26. /**
  27.  * A mutable builder for {@link LeastSquaresProblem}s.
  28.  *
  29.  * @see LeastSquaresFactory
  30.  * @since 3.3
  31.  */
  32. public class LeastSquaresBuilder {

  33.     /** max evaluations. */
  34.     private int maxEvaluations;
  35.     /** max iterations. */
  36.     private int maxIterations;
  37.     /** convergence checker. */
  38.     private ConvergenceChecker<Evaluation> checker;
  39.     /** model function. */
  40.     private MultivariateJacobianFunction model;
  41.     /** observed values. */
  42.     private RealVector target;
  43.     /** initial guess. */
  44.     private RealVector start;
  45.     /** weight matrix. */
  46.     private RealMatrix weight;
  47.     /**
  48.      * Lazy evaluation.
  49.      *
  50.      * @since 3.4
  51.      */
  52.     private boolean lazyEvaluation;
  53.     /** Validator.
  54.      *
  55.      * @since 3.4
  56.      */
  57.     private ParameterValidator paramValidator;


  58.     /**
  59.      * Construct a {@link LeastSquaresProblem} from the data in this builder.
  60.      *
  61.      * @return a new {@link LeastSquaresProblem}.
  62.      */
  63.     public LeastSquaresProblem build() {
  64.         return LeastSquaresFactory.create(model,
  65.                                           target,
  66.                                           start,
  67.                                           weight,
  68.                                           checker,
  69.                                           maxEvaluations,
  70.                                           maxIterations,
  71.                                           lazyEvaluation,
  72.                                           paramValidator);
  73.     }

  74.     /**
  75.      * Configure the max evaluations.
  76.      *
  77.      * @param newMaxEvaluations the maximum number of evaluations permitted.
  78.      * @return this
  79.      */
  80.     public LeastSquaresBuilder maxEvaluations(final int newMaxEvaluations) {
  81.         this.maxEvaluations = newMaxEvaluations;
  82.         return this;
  83.     }

  84.     /**
  85.      * Configure the max iterations.
  86.      *
  87.      * @param newMaxIterations the maximum number of iterations permitted.
  88.      * @return this
  89.      */
  90.     public LeastSquaresBuilder maxIterations(final int newMaxIterations) {
  91.         this.maxIterations = newMaxIterations;
  92.         return this;
  93.     }

  94.     /**
  95.      * Configure the convergence checker.
  96.      *
  97.      * @param newChecker the convergence checker.
  98.      * @return this
  99.      */
  100.     public LeastSquaresBuilder checker(final ConvergenceChecker<Evaluation> newChecker) {
  101.         this.checker = newChecker;
  102.         return this;
  103.     }

  104.     /**
  105.      * Configure the convergence checker.
  106.      * <p>
  107.      * This function is an overloaded version of {@link #checker(ConvergenceChecker)}.
  108.      *
  109.      * @param newChecker the convergence checker.
  110.      * @return this
  111.      */
  112.     public LeastSquaresBuilder checkerPair(final ConvergenceChecker<PointVectorValuePair> newChecker) {
  113.         return this.checker(LeastSquaresFactory.evaluationChecker(newChecker));
  114.     }

  115.     /**
  116.      * Configure the model function.
  117.      *
  118.      * @param value the model function value
  119.      * @param jacobian the Jacobian of {@code value}
  120.      * @return this
  121.      */
  122.     public LeastSquaresBuilder model(final MultivariateVectorFunction value,
  123.                                      final MultivariateMatrixFunction jacobian) {
  124.         return model(LeastSquaresFactory.model(value, jacobian));
  125.     }

  126.     /**
  127.      * Configure the model function.
  128.      *
  129.      * @param newModel the model function value and Jacobian
  130.      * @return this
  131.      */
  132.     public LeastSquaresBuilder model(final MultivariateJacobianFunction newModel) {
  133.         this.model = newModel;
  134.         return this;
  135.     }

  136.     /**
  137.      * Configure the observed data.
  138.      *
  139.      * @param newTarget the observed data.
  140.      * @return this
  141.      */
  142.     public LeastSquaresBuilder target(final RealVector newTarget) {
  143.         this.target = newTarget;
  144.         return this;
  145.     }

  146.     /**
  147.      * Configure the observed data.
  148.      *
  149.      * @param newTarget the observed data.
  150.      * @return this
  151.      */
  152.     public LeastSquaresBuilder target(final double[] newTarget) {
  153.         return target(new ArrayRealVector(newTarget, false));
  154.     }

  155.     /**
  156.      * Configure the initial guess.
  157.      *
  158.      * @param newStart the initial guess.
  159.      * @return this
  160.      */
  161.     public LeastSquaresBuilder start(final RealVector newStart) {
  162.         this.start = newStart;
  163.         return this;
  164.     }

  165.     /**
  166.      * Configure the initial guess.
  167.      *
  168.      * @param newStart the initial guess.
  169.      * @return this
  170.      */
  171.     public LeastSquaresBuilder start(final double[] newStart) {
  172.         return start(new ArrayRealVector(newStart, false));
  173.     }

  174.     /**
  175.      * Configure the weight matrix.
  176.      *
  177.      * @param newWeight the weight matrix
  178.      * @return this
  179.      */
  180.     public LeastSquaresBuilder weight(final RealMatrix newWeight) {
  181.         this.weight = newWeight;
  182.         return this;
  183.     }

  184.     /**
  185.      * Configure whether evaluation will be lazy or not.
  186.      *
  187.      * @param newValue Whether to perform lazy evaluation.
  188.      * @return this object.
  189.      *
  190.      * @since 3.4
  191.      */
  192.     public LeastSquaresBuilder lazyEvaluation(final boolean newValue) {
  193.         lazyEvaluation = newValue;
  194.         return this;
  195.     }

  196.     /**
  197.      * Configure the validator of the model parameters.
  198.      *
  199.      * @param newValidator Parameter validator.
  200.      * @return this object.
  201.      *
  202.      * @since 3.4
  203.      */
  204.     public LeastSquaresBuilder parameterValidator(final ParameterValidator newValidator) {
  205.         paramValidator = newValidator;
  206.         return this;
  207.     }
  208. }