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.optimization.linear;
019
020import java.util.Collection;
021import java.util.Collections;
022
023import org.apache.commons.math3.exception.MathIllegalStateException;
024import org.apache.commons.math3.exception.MaxCountExceededException;
025import org.apache.commons.math3.optimization.GoalType;
026import org.apache.commons.math3.optimization.PointValuePair;
027
028/**
029 * Base class for implementing linear optimizers.
030 * <p>
031 * This base class handles the boilerplate methods associated to thresholds
032 * settings and iterations counters.
033 *
034 * @deprecated As of 3.1 (to be removed in 4.0).
035 * @since 2.0
036 */
037@Deprecated
038public abstract class AbstractLinearOptimizer implements LinearOptimizer {
039
040    /** Default maximal number of iterations allowed. */
041    public static final int DEFAULT_MAX_ITERATIONS = 100;
042
043    /**
044     * Linear objective function.
045     * @since 2.1
046     */
047    private LinearObjectiveFunction function;
048
049    /**
050     * Linear constraints.
051     * @since 2.1
052     */
053    private Collection<LinearConstraint> linearConstraints;
054
055    /**
056     * Type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}.
057     * @since 2.1
058     */
059    private GoalType goal;
060
061    /**
062     * Whether to restrict the variables to non-negative values.
063     * @since 2.1
064     */
065    private boolean nonNegative;
066
067    /** Maximal number of iterations allowed. */
068    private int maxIterations;
069
070    /** Number of iterations already performed. */
071    private int iterations;
072
073    /**
074     * Simple constructor with default settings.
075     * <p>The maximal number of evaluation is set to its default value.</p>
076     */
077    protected AbstractLinearOptimizer() {
078        setMaxIterations(DEFAULT_MAX_ITERATIONS);
079    }
080
081    /**
082     * @return {@code true} if the variables are restricted to non-negative values.
083     */
084    protected boolean restrictToNonNegative() {
085        return nonNegative;
086    }
087
088    /**
089     * @return the optimization type.
090     */
091    protected GoalType getGoalType() {
092        return goal;
093    }
094
095    /**
096     * @return the optimization type.
097     */
098    protected LinearObjectiveFunction getFunction() {
099        return function;
100    }
101
102    /**
103     * @return the optimization type.
104     */
105    protected Collection<LinearConstraint> getConstraints() {
106        return Collections.unmodifiableCollection(linearConstraints);
107    }
108
109    /** {@inheritDoc} */
110    public void setMaxIterations(int maxIterations) {
111        this.maxIterations = maxIterations;
112    }
113
114    /** {@inheritDoc} */
115    public int getMaxIterations() {
116        return maxIterations;
117    }
118
119    /** {@inheritDoc} */
120    public int getIterations() {
121        return iterations;
122    }
123
124    /**
125     * Increment the iterations counter by 1.
126     * @exception MaxCountExceededException if the maximal number of iterations is exceeded
127     */
128    protected void incrementIterationsCounter()
129        throws MaxCountExceededException {
130        if (++iterations > maxIterations) {
131            throw new MaxCountExceededException(maxIterations);
132        }
133    }
134
135    /** {@inheritDoc} */
136    public PointValuePair optimize(final LinearObjectiveFunction f,
137                                   final Collection<LinearConstraint> constraints,
138                                   final GoalType goalType, final boolean restrictToNonNegative)
139        throws MathIllegalStateException {
140
141        // store linear problem characteristics
142        this.function          = f;
143        this.linearConstraints = constraints;
144        this.goal              = goalType;
145        this.nonNegative       = restrictToNonNegative;
146
147        iterations  = 0;
148
149        // solve the problem
150        return doOptimize();
151
152    }
153
154    /**
155     * Perform the bulk of optimization algorithm.
156     * @return the point/value pair giving the optimal value for objective function
157     * @exception MathIllegalStateException if no solution fulfilling the constraints
158     * can be found in the allowed number of iterations
159     */
160    protected abstract PointValuePair doOptimize() throws MathIllegalStateException;
161
162}