Javadoc cleanup of linear optimization package.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1385307 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2012-09-16 16:19:55 +00:00
parent 0a900fa692
commit 75fe8b8b99
9 changed files with 56 additions and 54 deletions

View File

@ -27,11 +27,12 @@ import org.apache.commons.math3.optimization.PointValuePair;
/**
* Base class for implementing linear optimizers.
* <p>This base class handles the boilerplate methods associated to thresholds
* settings and iterations counters.</p>
* <p>
* This base class handles the boilerplate methods associated to thresholds
* settings and iterations counters.
*
* @version $Id$
* @since 2.0
*
*/
public abstract class AbstractLinearOptimizer implements LinearOptimizer {
@ -68,7 +69,8 @@ public abstract class AbstractLinearOptimizer implements LinearOptimizer {
/** Number of iterations already performed. */
private int iterations;
/** Simple constructor with default settings.
/**
* Simple constructor with default settings.
* <p>The maximal number of evaluation is set to its default value.</p>
*/
protected AbstractLinearOptimizer() {
@ -118,9 +120,9 @@ public abstract class AbstractLinearOptimizer implements LinearOptimizer {
return iterations;
}
/** Increment the iterations counter by 1.
* @exception MaxCountExceededException if the maximal number
* of iterations is exceeded
/**
* Increment the iterations counter by 1.
* @exception MaxCountExceededException if the maximal number of iterations is exceeded
*/
protected void incrementIterationsCounter()
throws MaxCountExceededException {
@ -131,9 +133,9 @@ public abstract class AbstractLinearOptimizer implements LinearOptimizer {
/** {@inheritDoc} */
public PointValuePair optimize(final LinearObjectiveFunction f,
final Collection<LinearConstraint> constraints,
final GoalType goalType, final boolean restrictToNonNegative)
throws MathIllegalStateException {
final Collection<LinearConstraint> constraints,
final GoalType goalType, final boolean restrictToNonNegative)
throws MathIllegalStateException {
// store linear problem characteristics
this.function = f;
@ -148,12 +150,12 @@ public abstract class AbstractLinearOptimizer implements LinearOptimizer {
}
/** Perform the bulk of optimization algorithm.
/**
* Perform the bulk of optimization algorithm.
* @return the point/value pair giving the optimal value for objective function
* @exception MathIllegalStateException if no solution fulfilling the constraints
* can be found in the allowed number of iterations
*/
protected abstract PointValuePair doOptimize()
throws MathIllegalStateException;
protected abstract PointValuePair doOptimize() throws MathIllegalStateException;
}

View File

@ -184,7 +184,6 @@ public class LinearConstraint implements Serializable {
return value;
}
/** {@inheritDoc} */
@Override
public boolean equals(Object other) {
@ -201,7 +200,6 @@ public class LinearConstraint implements Serializable {
return false;
}
/** {@inheritDoc} */
@Override
public int hashCode() {
return relationship.hashCode() ^
@ -209,7 +207,8 @@ public class LinearConstraint implements Serializable {
coefficients.hashCode();
}
/** Serialize the instance.
/**
* Serialize the instance.
* @param oos stream where object should be written
* @throws IOException if object cannot be written to stream
*/
@ -219,7 +218,8 @@ public class LinearConstraint implements Serializable {
MatrixUtils.serializeRealVector(coefficients, oos);
}
/** Deserialize the instance.
/**
* Deserialize the instance.
* @param ois stream from which the object should be read
* @throws ClassNotFoundException if a class in the stream cannot be found
* @throws IOException if object cannot be read from the stream

View File

@ -101,7 +101,6 @@ public class LinearObjectiveFunction implements Serializable {
return coefficients.dotProduct(point) + constantTerm;
}
/** {@inheritDoc} */
@Override
public boolean equals(Object other) {
@ -117,13 +116,13 @@ public class LinearObjectiveFunction implements Serializable {
return false;
}
/** {@inheritDoc} */
@Override
public int hashCode() {
return Double.valueOf(constantTerm).hashCode() ^ coefficients.hashCode();
}
/** Serialize the instance.
/**
* Serialize the instance.
* @param oos stream where object should be written
* @throws IOException if object cannot be written to stream
*/
@ -133,7 +132,8 @@ public class LinearObjectiveFunction implements Serializable {
MatrixUtils.serializeRealVector(coefficients, oos);
}
/** Deserialize the instance.
/**
* Deserialize the instance.
* @param ois stream from which the object should be read
* @throws ClassNotFoundException if a class in the stream cannot be found
* @throws IOException if object cannot be read from the stream

View File

@ -52,17 +52,20 @@ import org.apache.commons.math3.optimization.PointValuePair;
*/
public interface LinearOptimizer {
/** Set the maximal number of iterations of the algorithm.
/**
* Set the maximal number of iterations of the algorithm.
* @param maxIterations maximal number of function calls
*/
void setMaxIterations(int maxIterations);
/** Get the maximal number of iterations of the algorithm.
/**
* Get the maximal number of iterations of the algorithm.
* @return maximal number of iterations
*/
int getMaxIterations();
/** Get the number of iterations realized by the algorithm.
/**
* Get the number of iterations realized by the algorithm.
* <p>
* The number of evaluations corresponds to the last call to the
* {@link #optimize(LinearObjectiveFunction, Collection, GoalType, boolean) optimize}
@ -72,18 +75,17 @@ public interface LinearOptimizer {
*/
int getIterations();
/** Optimizes an objective function.
/**
* Optimizes an objective function.
* @param f linear objective function
* @param constraints linear constraints
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
* or {@link GoalType#MINIMIZE}
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}
* @param restrictToNonNegative whether to restrict the variables to non-negative values
* @return point/value pair giving the optimal value for objective function
* @exception MathIllegalStateException if no solution fulfilling the constraints
* can be found in the allowed number of iterations
* can be found in the allowed number of iterations
*/
PointValuePair optimize(LinearObjectiveFunction f, Collection<LinearConstraint> constraints,
GoalType goalType, boolean restrictToNonNegative)
throws MathIllegalStateException;
GoalType goalType, boolean restrictToNonNegative) throws MathIllegalStateException;
}

View File

@ -21,8 +21,8 @@ import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.util.LocalizedFormats;
/**
* This class represents exceptions thrown by optimizers when no solution
* fulfills the constraints.
* This class represents exceptions thrown by optimizers when no solution fulfills the constraints.
*
* @version $Id$
* @since 2.0
*/

View File

@ -43,7 +43,6 @@ public enum Relationship {
this.stringValue = stringValue;
}
/** {@inheritDoc} */
@Override
public String toString() {
return stringValue;

View File

@ -27,6 +27,7 @@ import org.apache.commons.math3.util.Precision;
/**
* Solves a linear problem using the Two-Phase Simplex Method.
*
* @version $Id$
* @since 2.0
*/

View File

@ -110,8 +110,7 @@ class SimplexTableau implements Serializable {
* Build a tableau for a linear problem.
* @param f linear objective function
* @param constraints linear constraints
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
* or {@link GoalType#MINIMIZE}
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}
* @param restrictToNonNegative whether to restrict the variables to non-negative values
* @param epsilon amount of error to accept when checking for optimality
*/
@ -126,8 +125,7 @@ class SimplexTableau implements Serializable {
* Build a tableau for a linear problem.
* @param f linear objective function
* @param constraints linear constraints
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
* or {@link GoalType#MINIMIZE}
* @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} or {@link GoalType#MINIMIZE}
* @param restrictToNonNegative whether to restrict the variables to non-negative values
* @param epsilon amount of error to accept when checking for optimality
* @param maxUlps amount of error to accept in floating point comparisons
@ -397,7 +395,6 @@ class SimplexTableau implements Serializable {
/**
* Get the current solution.
*
* @return current solution
*/
protected PointValuePair getSolution() {
@ -437,8 +434,8 @@ class SimplexTableau implements Serializable {
* Subtracts a multiple of one row from another.
* <p>
* After application of this operation, the following will hold:
* minuendRow = minuendRow - multiple * subtrahendRow
* </p>
* <pre>minuendRow = minuendRow - multiple * subtrahendRow</pre>
*
* @param dividendRow index of the row
* @param divisor value of the divisor
*/
@ -452,8 +449,8 @@ class SimplexTableau implements Serializable {
* Subtracts a multiple of one row from another.
* <p>
* After application of this operation, the following will hold:
* minuendRow = minuendRow - multiple * subtrahendRow
* </p>
* <pre>minuendRow = minuendRow - multiple * subtrahendRow</pre>
*
* @param minuendRow row index
* @param subtrahendRow row index
* @param multiple multiplication factor
@ -486,7 +483,8 @@ class SimplexTableau implements Serializable {
return tableau.getRowDimension();
}
/** Get an entry of the tableau.
/**
* Get an entry of the tableau.
* @param row row index
* @param column column index
* @return entry at (row, column)
@ -495,7 +493,8 @@ class SimplexTableau implements Serializable {
return tableau.getEntry(row, column);
}
/** Set an entry of the tableau.
/**
* Set an entry of the tableau.
* @param row row index
* @param column column index
* @param value for the entry
@ -532,10 +531,9 @@ class SimplexTableau implements Serializable {
/**
* Get the number of decision variables.
* <p>
* If variables are not restricted to positive values, this will include 1
* extra decision variable to represent the absolute value of the most
* negative variable.
* </p>
* If variables are not restricted to positive values, this will include 1 extra decision variable to represent
* the absolute value of the most negative variable.
*
* @return number of decision variables
* @see #getOriginalNumDecisionVariables()
*/
@ -576,7 +574,6 @@ class SimplexTableau implements Serializable {
return tableau.getData();
}
/** {@inheritDoc} */
@Override
public boolean equals(Object other) {
@ -599,7 +596,6 @@ class SimplexTableau implements Serializable {
return false;
}
/** {@inheritDoc} */
@Override
public int hashCode() {
return Boolean.valueOf(restrictToNonNegative).hashCode() ^
@ -613,7 +609,8 @@ class SimplexTableau implements Serializable {
tableau.hashCode();
}
/** Serialize the instance.
/**
* Serialize the instance.
* @param oos stream where object should be written
* @throws IOException if object cannot be written to stream
*/
@ -623,7 +620,8 @@ class SimplexTableau implements Serializable {
MatrixUtils.serializeRealMatrix(tableau, oos);
}
/** Deserialize the instance.
/**
* Deserialize the instance.
* @param ois stream from which the object should be read
* @throws ClassNotFoundException if a class in the stream cannot be found
* @throws IOException if object cannot be read from the stream

View File

@ -21,8 +21,8 @@ import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.util.LocalizedFormats;
/**
* This class represents exceptions thrown by optimizers when a solution
* escapes to infinity.
* This class represents exceptions thrown by optimizers when a solution escapes to infinity.
*
* @version $Id$
* @since 2.0
*/