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 */
017package org.apache.commons.math3.fitting.leastsquares;
018
019import org.apache.commons.math3.analysis.MultivariateMatrixFunction;
020import org.apache.commons.math3.analysis.MultivariateVectorFunction;
021import org.apache.commons.math3.fitting.leastsquares.LeastSquaresProblem.Evaluation;
022import org.apache.commons.math3.linear.ArrayRealVector;
023import org.apache.commons.math3.linear.RealMatrix;
024import org.apache.commons.math3.linear.RealVector;
025import org.apache.commons.math3.optim.ConvergenceChecker;
026import org.apache.commons.math3.optim.PointVectorValuePair;
027
028/**
029 * A mutable builder for {@link LeastSquaresProblem}s.
030 *
031 * @see LeastSquaresFactory
032 * @since 3.3
033 */
034public class LeastSquaresBuilder {
035
036    /** max evaluations */
037    private int maxEvaluations;
038    /** max iterations */
039    private int maxIterations;
040    /** convergence checker */
041    private ConvergenceChecker<Evaluation> checker;
042    /** model function */
043    private MultivariateJacobianFunction model;
044    /** observed values */
045    private RealVector target;
046    /** initial guess */
047    private RealVector start;
048    /** weight matrix */
049    private RealMatrix weight;
050    /**
051     * Lazy evaluation.
052     *
053     * @since 3.4
054     */
055    private boolean lazyEvaluation;
056    /** Validator.
057     *
058     * @since 3.4
059     */
060    private ParameterValidator paramValidator;
061
062
063    /**
064     * Construct a {@link LeastSquaresProblem} from the data in this builder.
065     *
066     * @return a new {@link LeastSquaresProblem}.
067     */
068    public LeastSquaresProblem build() {
069        return LeastSquaresFactory.create(model,
070                                          target,
071                                          start,
072                                          weight,
073                                          checker,
074                                          maxEvaluations,
075                                          maxIterations,
076                                          lazyEvaluation,
077                                          paramValidator);
078    }
079
080    /**
081     * Configure the max evaluations.
082     *
083     * @param newMaxEvaluations the maximum number of evaluations permitted.
084     * @return this
085     */
086    public LeastSquaresBuilder maxEvaluations(final int newMaxEvaluations) {
087        this.maxEvaluations = newMaxEvaluations;
088        return this;
089    }
090
091    /**
092     * Configure the max iterations.
093     *
094     * @param newMaxIterations the maximum number of iterations permitted.
095     * @return this
096     */
097    public LeastSquaresBuilder maxIterations(final int newMaxIterations) {
098        this.maxIterations = newMaxIterations;
099        return this;
100    }
101
102    /**
103     * Configure the convergence checker.
104     *
105     * @param newChecker the convergence checker.
106     * @return this
107     */
108    public LeastSquaresBuilder checker(final ConvergenceChecker<Evaluation> newChecker) {
109        this.checker = newChecker;
110        return this;
111    }
112
113    /**
114     * Configure the convergence checker.
115     * <p/>
116     * This function is an overloaded version of {@link #checker(ConvergenceChecker)}.
117     *
118     * @param newChecker the convergence checker.
119     * @return this
120     */
121    public LeastSquaresBuilder checkerPair(final ConvergenceChecker<PointVectorValuePair> newChecker) {
122        return this.checker(LeastSquaresFactory.evaluationChecker(newChecker));
123    }
124
125    /**
126     * Configure the model function.
127     *
128     * @param value the model function value
129     * @param jacobian the Jacobian of {@code value}
130     * @return this
131     */
132    public LeastSquaresBuilder model(final MultivariateVectorFunction value,
133                                     final MultivariateMatrixFunction jacobian) {
134        return model(LeastSquaresFactory.model(value, jacobian));
135    }
136
137    /**
138     * Configure the model function.
139     *
140     * @param newModel the model function value and Jacobian
141     * @return this
142     */
143    public LeastSquaresBuilder model(final MultivariateJacobianFunction newModel) {
144        this.model = newModel;
145        return this;
146    }
147
148    /**
149     * Configure the observed data.
150     *
151     * @param newTarget the observed data.
152     * @return this
153     */
154    public LeastSquaresBuilder target(final RealVector newTarget) {
155        this.target = newTarget;
156        return this;
157    }
158
159    /**
160     * Configure the observed data.
161     *
162     * @param newTarget the observed data.
163     * @return this
164     */
165    public LeastSquaresBuilder target(final double[] newTarget) {
166        return target(new ArrayRealVector(newTarget, false));
167    }
168
169    /**
170     * Configure the initial guess.
171     *
172     * @param newStart the initial guess.
173     * @return this
174     */
175    public LeastSquaresBuilder start(final RealVector newStart) {
176        this.start = newStart;
177        return this;
178    }
179
180    /**
181     * Configure the initial guess.
182     *
183     * @param newStart the initial guess.
184     * @return this
185     */
186    public LeastSquaresBuilder start(final double[] newStart) {
187        return start(new ArrayRealVector(newStart, false));
188    }
189
190    /**
191     * Configure the weight matrix.
192     *
193     * @param newWeight the weight matrix
194     * @return this
195     */
196    public LeastSquaresBuilder weight(final RealMatrix newWeight) {
197        this.weight = newWeight;
198        return this;
199    }
200
201    /**
202     * Configure whether evaluation will be lazy or not.
203     *
204     * @param newValue Whether to perform lazy evaluation.
205     * @return this object.
206     *
207     * @since 3.4
208     */
209    public LeastSquaresBuilder lazyEvaluation(final boolean newValue) {
210        lazyEvaluation = newValue;
211        return this;
212    }
213
214    /**
215     * Configure the validator of the model parameters.
216     *
217     * @param newValidator Parameter validator.
218     * @return this object.
219     *
220     * @since 3.4
221     */
222    public LeastSquaresBuilder parameterValidator(final ParameterValidator newValidator) {
223        paramValidator = newValidator;
224        return this;
225    }
226}