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    
018    package org.apache.commons.math.optimization.linear;
019    
020    import java.util.Collection;
021    
022    import org.apache.commons.math.MaxIterationsExceededException;
023    import org.apache.commons.math.optimization.GoalType;
024    import org.apache.commons.math.optimization.OptimizationException;
025    import org.apache.commons.math.optimization.RealPointValuePair;
026    
027    /**
028     * Base class for implementing linear optimizers.
029     * <p>This base class handles the boilerplate methods associated to thresholds
030     * settings and iterations counters.</p>
031     * @version $Revision: 786466 $ $Date: 2009-06-19 08:03:14 -0400 (Fri, 19 Jun 2009) $
032     * @since 2.0
033     *
034     */
035    public abstract class AbstractLinearOptimizer implements LinearOptimizer {
036    
037        /** Default maximal number of iterations allowed. */
038        public static final int DEFAULT_MAX_ITERATIONS = 100;
039    
040        /** Maximal number of iterations allowed. */
041        private int maxIterations;
042    
043        /** Number of iterations already performed. */
044        private int iterations;
045    
046        /** Linear objective function. */
047        protected LinearObjectiveFunction f;
048    
049        /** Linear constraints. */
050        protected Collection<LinearConstraint> constraints;
051    
052        /** Type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}. */
053        protected GoalType goalType;
054    
055        /** Whether to restrict the variables to non-negative values. */
056        protected boolean restrictToNonNegative;
057    
058        /** Simple constructor with default settings.
059         * <p>The maximal number of evaluation is set to its default value.</p>
060         */
061        protected AbstractLinearOptimizer() {
062            setMaxIterations(DEFAULT_MAX_ITERATIONS);
063        }
064    
065        /** {@inheritDoc} */
066        public void setMaxIterations(int maxIterations) {
067            this.maxIterations = maxIterations;
068        }
069    
070        /** {@inheritDoc} */
071        public int getMaxIterations() {
072            return maxIterations;
073        }
074    
075        /** {@inheritDoc} */
076        public int getIterations() {
077            return iterations;
078        }
079    
080        /** Increment the iterations counter by 1.
081         * @exception OptimizationException if the maximal number
082         * of iterations is exceeded
083         */
084        protected void incrementIterationsCounter()
085            throws OptimizationException {
086            if (++iterations > maxIterations) {
087                throw new OptimizationException(new MaxIterationsExceededException(maxIterations));
088            }
089        }
090    
091        /** {@inheritDoc} */
092        public RealPointValuePair optimize(final LinearObjectiveFunction f,
093                                           final Collection<LinearConstraint> constraints,
094                                           final GoalType goalType, final boolean restrictToNonNegative)
095             throws OptimizationException {
096    
097            // store linear problem characteristics
098            this.f                     = f;
099            this.constraints           = constraints;
100            this.goalType              = goalType;
101            this.restrictToNonNegative = restrictToNonNegative;
102    
103            iterations  = 0;
104    
105            // solve the problem
106            return doOptimize();
107    
108        }
109    
110        /** Perform the bulk of optimization algorithm.
111         * @return the point/value pair giving the optimal value for objective function
112         * @exception OptimizationException if no solution fulfilling the constraints
113         * can be found in the allowed number of iterations
114         */
115        abstract protected RealPointValuePair doOptimize()
116            throws OptimizationException;
117    
118    }