    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    }