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: 925812 $ $Date: 2010-03-21 16:49:31 +0100 (dim. 21 mars 2010) $
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        /**
041         * Linear objective function.
042         * @since 2.1
043         */
044        protected LinearObjectiveFunction function;
045    
046        /**
047         * Linear constraints.
048         * @since 2.1
049         */
050        protected Collection<LinearConstraint> linearConstraints;
051    
052        /**
053         * Type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}.
054         * @since 2.1
055         */
056        protected GoalType goal;
057    
058        /**
059         * Whether to restrict the variables to non-negative values.
060         * @since 2.1
061         */
062        protected boolean nonNegative;
063    
064        /** Maximal number of iterations allowed. */
065        private int maxIterations;
066    
067        /** Number of iterations already performed. */
068        private int iterations;
069    
070        /** Simple constructor with default settings.
071         * <p>The maximal number of evaluation is set to its default value.</p>
072         */
073        protected AbstractLinearOptimizer() {
074            setMaxIterations(DEFAULT_MAX_ITERATIONS);
075        }
076    
077        /** {@inheritDoc} */
078        public void setMaxIterations(int maxIterations) {
079            this.maxIterations = maxIterations;
080        }
081    
082        /** {@inheritDoc} */
083        public int getMaxIterations() {
084            return maxIterations;
085        }
086    
087        /** {@inheritDoc} */
088        public int getIterations() {
089            return iterations;
090        }
091    
092        /** Increment the iterations counter by 1.
093         * @exception OptimizationException if the maximal number
094         * of iterations is exceeded
095         */
096        protected void incrementIterationsCounter()
097            throws OptimizationException {
098            if (++iterations > maxIterations) {
099                throw new OptimizationException(new MaxIterationsExceededException(maxIterations));
100            }
101        }
102    
103        /** {@inheritDoc} */
104        public RealPointValuePair optimize(final LinearObjectiveFunction f,
105                                           final Collection<LinearConstraint> constraints,
106                                           final GoalType goalType, final boolean restrictToNonNegative)
107             throws OptimizationException {
108    
109            // store linear problem characteristics
110            this.function          = f;
111            this.linearConstraints = constraints;
112            this.goal              = goalType;
113            this.nonNegative       = restrictToNonNegative;
114    
115            iterations  = 0;
116    
117            // solve the problem
118            return doOptimize();
119    
120        }
121    
122        /** Perform the bulk of optimization algorithm.
123         * @return the point/value pair giving the optimal value for objective function
124         * @exception OptimizationException if no solution fulfilling the constraints
125         * can be found in the allowed number of iterations
126         */
127        protected abstract RealPointValuePair doOptimize()
128            throws OptimizationException;
129    
130    }