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
018package org.apache.commons.math3.optim.nonlinear.vector;
019
020import org.apache.commons.math3.exception.TooManyEvaluationsException;
021import org.apache.commons.math3.exception.DimensionMismatchException;
022import org.apache.commons.math3.analysis.MultivariateVectorFunction;
023import org.apache.commons.math3.optim.OptimizationData;
024import org.apache.commons.math3.optim.BaseMultivariateOptimizer;
025import org.apache.commons.math3.optim.ConvergenceChecker;
026import org.apache.commons.math3.optim.PointVectorValuePair;
027import org.apache.commons.math3.linear.RealMatrix;
028
029/**
030 * Base class for a multivariate vector function optimizer.
031 *
032 * @since 3.1
033 */
034@Deprecated
035public abstract class MultivariateVectorOptimizer
036    extends BaseMultivariateOptimizer<PointVectorValuePair> {
037    /** Target values for the model function at optimum. */
038    private double[] target;
039    /** Weight matrix. */
040    private RealMatrix weightMatrix;
041    /** Model function. */
042    private MultivariateVectorFunction model;
043
044    /**
045     * @param checker Convergence checker.
046     */
047    protected MultivariateVectorOptimizer(ConvergenceChecker<PointVectorValuePair> checker) {
048        super(checker);
049    }
050
051    /**
052     * Computes the objective function value.
053     * This method <em>must</em> be called by subclasses to enforce the
054     * evaluation counter limit.
055     *
056     * @param params Point at which the objective function must be evaluated.
057     * @return the objective function value at the specified point.
058     * @throws TooManyEvaluationsException if the maximal number of evaluations
059     * (of the model vector function) is exceeded.
060     */
061    protected double[] computeObjectiveValue(double[] params) {
062        super.incrementEvaluationCount();
063        return model.value(params);
064    }
065
066    /**
067     * {@inheritDoc}
068     *
069     * @param optData Optimization data. In addition to those documented in
070     * {@link BaseMultivariateOptimizer#parseOptimizationData(OptimizationData[])
071     * BaseMultivariateOptimizer}, this method will register the following data:
072     * <ul>
073     *  <li>{@link Target}</li>
074     *  <li>{@link Weight}</li>
075     *  <li>{@link ModelFunction}</li>
076     * </ul>
077     * @return {@inheritDoc}
078     * @throws TooManyEvaluationsException if the maximal number of
079     * evaluations is exceeded.
080     * @throws DimensionMismatchException if the initial guess, target, and weight
081     * arguments have inconsistent dimensions.
082     */
083    @Override
084    public PointVectorValuePair optimize(OptimizationData... optData)
085        throws TooManyEvaluationsException,
086               DimensionMismatchException {
087        // Set up base class and perform computation.
088        return super.optimize(optData);
089    }
090
091    /**
092     * Gets the weight matrix of the observations.
093     *
094     * @return the weight matrix.
095     */
096    public RealMatrix getWeight() {
097        return weightMatrix.copy();
098    }
099    /**
100     * Gets the observed values to be matched by the objective vector
101     * function.
102     *
103     * @return the target values.
104     */
105    public double[] getTarget() {
106        return target.clone();
107    }
108
109    /**
110     * Gets the number of observed values.
111     *
112     * @return the length of the target vector.
113     */
114    public int getTargetSize() {
115        return target.length;
116    }
117
118    /**
119     * Scans the list of (required and optional) optimization data that
120     * characterize the problem.
121     *
122     * @param optData Optimization data. The following data will be looked for:
123     * <ul>
124     *  <li>{@link Target}</li>
125     *  <li>{@link Weight}</li>
126     *  <li>{@link ModelFunction}</li>
127     * </ul>
128     */
129    @Override
130    protected void parseOptimizationData(OptimizationData... optData) {
131        // Allow base class to register its own data.
132        super.parseOptimizationData(optData);
133
134        // The existing values (as set by the previous call) are reused if
135        // not provided in the argument list.
136        for (OptimizationData data : optData) {
137            if (data instanceof ModelFunction) {
138                model = ((ModelFunction) data).getModelFunction();
139                continue;
140            }
141            if (data instanceof Target) {
142                target = ((Target) data).getTarget();
143                continue;
144            }
145            if (data instanceof Weight) {
146                weightMatrix = ((Weight) data).getWeight();
147                continue;
148            }
149        }
150
151        // Check input consistency.
152        checkParameters();
153    }
154
155    /**
156     * Check parameters consistency.
157     *
158     * @throws DimensionMismatchException if {@link #target} and
159     * {@link #weightMatrix} have inconsistent dimensions.
160     */
161    private void checkParameters() {
162        if (target.length != weightMatrix.getColumnDimension()) {
163            throw new DimensionMismatchException(target.length,
164                                                 weightMatrix.getColumnDimension());
165        }
166    }
167}