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    package org.apache.commons.math3.optim.nonlinear.vector;
018    
019    import org.apache.commons.math3.analysis.MultivariateMatrixFunction;
020    import org.apache.commons.math3.optim.ConvergenceChecker;
021    import org.apache.commons.math3.optim.OptimizationData;
022    import org.apache.commons.math3.optim.PointVectorValuePair;
023    import org.apache.commons.math3.exception.TooManyEvaluationsException;
024    import org.apache.commons.math3.exception.DimensionMismatchException;
025    
026    /**
027     * Base class for implementing optimizers for multivariate vector
028     * differentiable functions.
029     * It contains boiler-plate code for dealing with Jacobian evaluation.
030     * It assumes that the rows of the Jacobian matrix iterate on the model
031     * functions while the columns iterate on the parameters; thus, the numbers
032     * of rows is equal to the dimension of the {@link Target} while the
033     * number of columns is equal to the dimension of the
034     * {@link org.apache.commons.math3.optim.InitialGuess InitialGuess}.
035     *
036     * @version $Id: JacobianMultivariateVectorOptimizer.java 1454464 2013-03-08 16:58:10Z luc $
037     * @since 3.1
038     */
039    public abstract class JacobianMultivariateVectorOptimizer
040        extends MultivariateVectorOptimizer {
041        /**
042         * Jacobian of the model function.
043         */
044        private MultivariateMatrixFunction jacobian;
045    
046        /**
047         * @param checker Convergence checker.
048         */
049        protected JacobianMultivariateVectorOptimizer(ConvergenceChecker<PointVectorValuePair> checker) {
050            super(checker);
051        }
052    
053        /**
054         * Computes the Jacobian matrix.
055         *
056         * @param params Point at which the Jacobian must be evaluated.
057         * @return the Jacobian at the specified point.
058         */
059        protected double[][] computeJacobian(final double[] params) {
060            return jacobian.value(params);
061        }
062    
063        /**
064         * {@inheritDoc}
065         *
066         * @param optData Optimization data. In addition to those documented in
067         * {@link MultivariateVectorOptimizer#optimize(OptimizationData...)}
068         * MultivariateOptimizer}, this method will register the following data:
069         * <ul>
070         *  <li>{@link ModelFunctionJacobian}</li>
071         * </ul>
072         * @return {@inheritDoc}
073         * @throws TooManyEvaluationsException if the maximal number of
074         * evaluations is exceeded.
075         * @throws DimensionMismatchException if the initial guess, target, and weight
076         * arguments have inconsistent dimensions.
077         */
078        @Override
079        public PointVectorValuePair optimize(OptimizationData... optData)
080            throws TooManyEvaluationsException,
081                   DimensionMismatchException {
082            // Set up base class and perform computation.
083            return super.optimize(optData);
084        }
085    
086        /**
087         * Scans the list of (required and optional) optimization data that
088         * characterize the problem.
089         *
090         * @param optData Optimization data.
091         * The following data will be looked for:
092         * <ul>
093         *  <li>{@link ModelFunctionJacobian}</li>
094         * </ul>
095         */
096        @Override
097        protected void parseOptimizationData(OptimizationData... optData) {
098            // Allow base class to register its own data.
099            super.parseOptimizationData(optData);
100    
101            // The existing values (as set by the previous call) are reused if
102            // not provided in the argument list.
103            for (OptimizationData data : optData) {
104                if (data instanceof ModelFunctionJacobian) {
105                    jacobian = ((ModelFunctionJacobian) data).getModelFunctionJacobian();
106                    // If more data must be parsed, this statement _must_ be
107                    // changed to "continue".
108                    break;
109                }
110            }
111        }
112    }