com.jom

Class OptimizationProblem

java.lang.Object

com.jom.OptimizationProblem

public class OptimizationProblem
extends Object

This class contains the methods for handling optimization problems, defining their input parameters (if any), decision variables, objetive function and constraints, choosing and calling a solver to obtain a numerical solution, and retrieving that solution.

Author:

Pablo Pavon Mariño

See Also:

http://www.net2plan.com/jom

Constructor Summary

Constructors

Constructor and Description
OptimizationProblem() Creates an optimization problem object

Method Summary

Modifier and Type	Method and Description
String	about() Returns an informative string about the JOM library
Expression	addConstraint(String expression) Adds (an array of) constraints to the optimization problem.
Expression	addConstraint(String expression, String identifier) Adds (an array of) constraints to the optimization problem.
void	addDecisionVariable(String name, boolean isInteger, int[] size) Same as addDecisionVariable(name, isInteger, size, null, null);
void	addDecisionVariable(String name, boolean isInteger, int[] size, double[] x_l, double[] x_u) Adds an array of decision variables to the optimization problem
void	addDecisionVariable(String name, boolean isInteger, int[] size, double x_l, double x_u) addDecisionVariable(String name, boolean isInteger, int[] size, DoubleMatrixND x_l, DoubleMatrixND x_u), but now the lower (upper) bounds for all the decision variables in the array are equal to x_l (x_u).
void	addDecisionVariable(String name, boolean isInteger, int[] size, cern.colt.matrix.tdouble.DoubleMatrix1D x_l, cern.colt.matrix.tdouble.DoubleMatrix1D x_u) Adds an array of decision variables to the optimization problem
void	addDecisionVariable(String name, boolean isInteger, int[] size, DoubleMatrixND x_l, DoubleMatrixND x_u) Adds an array of decision variables to the optimization problem
boolean	feasibleSolutionDoesNotExist() Returns true if the problem was attempted to be solved, and the solver declares that the problem has no feasible solutions.
boolean	foundUnboundedSolution() Returns true if the problem was attempted to be solved, and the solver declares that the problem is unbounded.
double	getBestOptimalityBound() Returns the best optimality bound found by the solver.
DoubleMatrixND	getInputParameter(String name) Obtains the value (an array of doubles) of the input parameter previously set
DoubleMatrixND	getMultiplierOfLowerBoundConstraintToPrimalVariables(String decisionVariableName) Returns the multipliers of the automatic constraints: \(x_l \leq varName\) added to the problem, where \(x_l\) is the array of lower bounds provided, associated to the decision variable.
DoubleMatrixND	getMultiplierOfUpperBoundConstraintToPrimalVariables(String decisionVariableName) Returns the multipliers of the automatic constraints: \(varName \leq x_u\) added to the problem, where \(x_u\) is the array of upper bounds provided, associated to the decision variable.
DoubleMatrixND	getMultipliersOfConstraint(String constraintIdentifier) Returns the multipliers of the given constraint
int	getNumLinearScalarConstraints() Gets the number of scalar constraints in the problem that are linear (with integer variables or not).
int	getNumNonLinearScalarConstraints() Gets the number of scalar constraints in the problem that are non linear (with integer variables or not).
int	getNumScalarDecisionVariables() Gets the number of scalar decision variables.
Expression	getObjectiveFunction() Gets the objective function expression set in the problem
double	getOptimalCost() Returns the cost of the solution obtained by the solver
DoubleMatrixND	getPrimalSolution(String decisionVariable) Returns the primal solution obtained after solving the problem for the given (array of) decision variables.
DoubleMatrixND	getSlackOfConstraint(String constraintIdentifier) Returns the slack of the given constraints.
boolean	isInputParameter(String name) Returns true if the given name corresponds to an input parameter defined for the problem
boolean	isIntegerProblem() Returns true if the problem has one or more decision variables constrained to be integer, false otherwise
boolean	isLinearProblem() Returns true if the problem is linear (with some/all integer variables or not).
boolean	isToMinimize() Returns true if the current objective function has already been defined, and the problem is set as a minimization problem
Expression	parseExpression(String expression) Help function (not needed usually for solving optimization problems) to generate an Expression object from its String representation.
void	resetTimer() Resets the timers that track the amount of time involved in each part of the computation, to write the time report with the
void	setInitialSolution(String decisionVariableName, double initialValue) Sets the initial solution of the optimization algorithm solving the problem (can be used for setting the starting solution in IPOPT solver).
void	setInitialSolution(String decisionVariableName, DoubleMatrixND initialValue) Sets the initial solution of the optimization algorithm solving the problem (to be used by some solvers like IPOPT).
void	setInputParameter(String name, Collection<? extends Number> values, String rowColumnVector) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, double value) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, double[][] values) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, double[] values, String rowColumnVector) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, cern.colt.matrix.tdouble.DoubleMatrix1D values, String rowColumnVector) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, cern.colt.matrix.tdouble.DoubleMatrix2D array) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, DoubleMatrixND array) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, int value) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, int[] values, String rowColumnVector) Sets the value of the (arrayed) input parameter identified by its name.
void	setInputParameter(String name, String expression) Sets the value of the (arrayed) input parameter identified by its name.
Expression	setObjectiveFunction(String minMax, String expression) Sets the objective function of the optimization problem, and its direction (maximice or minimice).
boolean	solutionIsFeasible() Returns true if the problem was solved, and the solution obtained is feasible.
boolean	solutionIsOptimal() Returns true if the problem was solved, and the solution obtained is optimal according to the solver.
void	solve(String solverName, Object... paramValuePairs) Calls the indicated solver to solve the optimization problem in its current state (e.g. current objective function and input parameters set).
String	timeReport() Return a printed report with the time spended in the different parts of the problem: defining the variables, objective, constraints and solving.
String	toString() Returns a formatted string with some information of the optimization problem

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OptimizationProblem

public OptimizationProblem()

Creates an optimization problem object

Method Detail

about

public String about()

Returns an informative string about the JOM library

Returns:

the string

addConstraint

public Expression addConstraint(String expression)

Adds (an array of) constraints to the optimization problem. No identifier is assigned, so after the problem is solved, it is not possible to access the multipliers and other constraint-related info. Constraints have the form: expression-left-hand-side connector expression-right-hand-side. Expressions are strings that can be evaluated to arrayed expressions of the defined input parameters and decision variables. Connectors must be of the type less-equal (<= or =<), greater-equal (>= or =>) or equal (==).

Parameters:

expression - The string expression of the constraint.

Returns:

The Expression object holding the expression (lhs - rhs), where lhs and rhs are the expression in the left-hand-side and right-hand-side of the constraint

addConstraint

public Expression addConstraint(String expression,
                                String identifier)

Adds (an array of) constraints to the optimization problem. Constraints have the form: expression-left-hand-side connector expression-right-hand-side. Expressions are strings that can be evaluated to arrayed expressions of the defined input parameters and decision variables. Connectors must be of the type less-equal (<= or =<), greater-equal (>= or =>) or equal (==).

Parameters:

expression - The string expression of the constraint.

identifier - A unique string given to identify this constraint

Returns:

The Expression object holding the expression (lhs - rhs), where lhs and rhs are the expression in the left-hand-side and right-hand-side of the constraint

addDecisionVariable

public void addDecisionVariable(String name,
                                boolean isInteger,
                                int[] size)

Same as addDecisionVariable(name, isInteger, size, null, null);

Parameters:

name - Name of the array of decision variables, as it will used in the expressions.

isInteger - True if the decision variables in the array are all constrained to be integer

size - One coordinate per dimension of the array, each coordinate is the size of the array in the respective dimension.

addDecisionVariable

public void addDecisionVariable(String name,
                                boolean isInteger,
                                int[] size,
                                double x_l,
                                double x_u)

addDecisionVariable(String name, boolean isInteger, int[] size, DoubleMatrixND x_l, DoubleMatrixND x_u), but now the lower (upper) bounds for all the decision variables in the array are equal to x_l (x_u).

Parameters:

name - Name of the array of decision variables, as it will used in the expressions.

isInteger - True if the decision variables in the array are all constrained to be integer

size - One coordinate per dimension of the array, each coordinate is the size of the array in the respective dimension.

x_l - The lower bounds of the variables are created as new DoubleMatrixND (size,x_l)

x_u - The upper bounds of the variables are created as new DoubleMatrixND (size,x_u)

addDecisionVariable

public void addDecisionVariable(String name,
                                boolean isInteger,
                                int[] size,
                                double[] x_l,
                                double[] x_u)

Adds an array of decision variables to the optimization problem

Parameters:

name - Name of the array of decision variables, as it will used in the expressions.

isInteger - True if the decision variables in the array are all constrained to be integer

size - One coordinate per dimension of the array, each coordinate is the size of the array in the respective dimension.

x_l - The lower bounds of the variables are created as new DoubleMatrixND (size,x_l)

x_u - The upper bounds of the variables are created as new DoubleMatrixND (size,x_u)

addDecisionVariable

public void addDecisionVariable(String name,
                                boolean isInteger,
                                int[] size,
                                cern.colt.matrix.tdouble.DoubleMatrix1D x_l,
                                cern.colt.matrix.tdouble.DoubleMatrix1D x_u)

Adds an array of decision variables to the optimization problem

Parameters:

name - Name of the array of decision variables, as it will used in the expressions.

isInteger - True if the decision variables in the array are all constrained to be integer

size - One coordinate per dimension of the array, each coordinate is the size of the array in the respective dimension.

x_l - The lower bounds of the variables are created as new DoubleMatrixND (size,x_l)

x_u - The upper bounds of the variables are created as new DoubleMatrixND (size,x_u)

addDecisionVariable

public void addDecisionVariable(String name,
                                boolean isInteger,
                                int[] size,
                                DoubleMatrixND x_l,
                                DoubleMatrixND x_u)

Adds an array of decision variables to the optimization problem

Parameters:

name - Name of the array of decision variables, as it will used in the expressions.

isInteger - True if the decision variables in the array are all constrained to be integer

size - One coordinate per dimension of the array, each coordinate is the size of the array in the respective dimension.

x_l - An array of doubles of the same size of the decision variables, with the lower bounds of the variables.

x_u - An array of doubles of the same size of the decision variables, with the upper bounds of the variables.

feasibleSolutionDoesNotExist

public boolean feasibleSolutionDoesNotExist()

Returns true if the problem was attempted to be solved, and the solver declares that the problem has no feasible solutions. If the method "solve" was not invoked yet, throws an exception

Returns:

See above

foundUnboundedSolution

public boolean foundUnboundedSolution()

Returns true if the problem was attempted to be solved, and the solver declares that the problem is unbounded. If the method "solve" was not invoked yet, throws an exception

Returns:

See above

getInputParameter

public DoubleMatrixND getInputParameter(String name)

Obtains the value (an array of doubles) of the input parameter previously set

Parameters:

name - Name of the input parameter as it appears in the expressions

Returns:

The value of the input parameter

getMultiplierOfLowerBoundConstraintToPrimalVariables

public DoubleMatrixND getMultiplierOfLowerBoundConstraintToPrimalVariables(String decisionVariableName)

Returns the multipliers of the automatic constraints: \(x_l \leq varName\) added to the problem, where \(x_l\) is the array of lower bounds provided, associated to the decision variable.

Parameters:

decisionVariableName - The name of the decision variable

Returns:

The multipliers as an array of the same size of the decision variables

getMultiplierOfUpperBoundConstraintToPrimalVariables

public DoubleMatrixND getMultiplierOfUpperBoundConstraintToPrimalVariables(String decisionVariableName)

Returns the multipliers of the automatic constraints: \(varName \leq x_u\) added to the problem, where \(x_u\) is the array of upper bounds provided, associated to the decision variable.

Parameters:

decisionVariableName - The name of the decision variable

Returns:

The multipliers as an array of the same size of the decision variables

getMultipliersOfConstraint

public DoubleMatrixND getMultipliersOfConstraint(String constraintIdentifier)

Returns the multipliers of the given constraint

Parameters:

constraintIdentifier - The unique identifier of the constraint

Returns:

The multipliers as an array of the same size of the constraints

getNumLinearScalarConstraints

public int getNumLinearScalarConstraints()

Gets the number of scalar constraints in the problem that are linear (with integer variables or not). Arrayed constraints are counted as many times as its number of constituting scalar elements.

Returns:

The number of linear scalar constraints

getNumNonLinearScalarConstraints

public int getNumNonLinearScalarConstraints()

Gets the number of scalar constraints in the problem that are non linear (with integer variables or not). Arrayed constraints are counted as many times as its number of constituting scalar elements.

Returns:

The number of non-linear scalar constraints

getNumScalarDecisionVariables

public int getNumScalarDecisionVariables()

Gets the number of scalar decision variables. Arrayed decision variables are counted as many times as its number of constituting scalar elements.

Returns:

The number of scalar decision variables

getObjectiveFunction

public Expression getObjectiveFunction()

Gets the objective function expression set in the problem

Returns:

The objective expression of the objective function

getOptimalCost

public double getOptimalCost()

Returns the cost of the solution obtained by the solver

Returns:

The primal solution cost

getBestOptimalityBound

public double getBestOptimalityBound()

Returns the best optimality bound found by the solver. This is a lower bound of the value of an optimum solution in minimization problems, and an upper bound in maximization problems. Some solvers are able to provide this information, even if a feasible solution is not found. If this information is not available, -Double.MAX_VALUE is returned in minimization problems, and Double.MAX_VALUE is returned in maximization problems.

Returns:

The optimality bound

getPrimalSolution

public DoubleMatrixND getPrimalSolution(String decisionVariable)

Returns the primal solution obtained after solving the problem for the given (array of) decision variables. If the decision variable is constrained to be integer, it is rounded. In this case, we are assuming that non-integer values returned by the solver were caused by negligible numerical errors. Recall that, after the solver ends, JOM checks if its exit code signals an error-free execution. Thus, if the solver returns an "everything ok" code, numerical errors in integer variables should be negligible.

Parameters:

decisionVariable - The name of the decision variable

Returns:

An array of the same size of the decision variables, with the solution

getSlackOfConstraint

public DoubleMatrixND getSlackOfConstraint(String constraintIdentifier)

Returns the slack of the given constraints. It should be zero for equality constraints.

Parameters:

constraintIdentifier - Id of the constrain

Returns:

An array of the same size of the constraints, with the slack values

isInputParameter

public boolean isInputParameter(String name)

Returns true if the given name corresponds to an input parameter defined for the problem

Parameters:

name - Name of the input parameter

Returns:

True if the previous statement is true, false otherwise

isIntegerProblem

public boolean isIntegerProblem()

Returns true if the problem has one or more decision variables constrained to be integer, false otherwise

Returns:

See above.

isLinearProblem

public boolean isLinearProblem()

Returns true if the problem is linear (with some/all integer variables or not). False if the objective function or one or more constraints are non-linear.

Returns:

See above

isToMinimize

public boolean isToMinimize()

Returns true if the current objective function has already been defined, and the problem is set as a minimization problem

Returns:

True if the previous statement is true, false otherwise

parseExpression

public Expression parseExpression(String expression)

Help function (not needed usually for solving optimization problems) to generate an Expression object from its String representation.

Parameters:

expression - The string expression.

Returns:

The Expression object

resetTimer

public void resetTimer()

Resets the timers that track the amount of time involved in each part of the computation, to write the time report with the

setInitialSolution

public void setInitialSolution(String decisionVariableName,
                               double initialValue)

Sets the initial solution of the optimization algorithm solving the problem (can be used for setting the starting solution in IPOPT solver).

Parameters:

decisionVariableName - Name of the decision variable

initialValue - Initial solution. All the scalar decision variables in the array of decision variables have this same initial value.

setInitialSolution

public void setInitialSolution(String decisionVariableName,
                               DoubleMatrixND initialValue)

Sets the initial solution of the optimization algorithm solving the problem (to be used by some solvers like IPOPT).

Parameters:

decisionVariableName - Name of the decision variable

initialValue - Initial solution. Array of the same size as the decision variable

setInputParameter

public void setInputParameter(String name,
                              double value)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

value - The scalar value of the input parameter, converted to an N-DIM array object of size (1,1)

setInputParameter

public void setInputParameter(String name,
                              double[] values,
                              String rowColumnVector)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

values - The 1D array of values of the input parameter, converted to an N-DIM array object of size (1,values.length)

rowColumnVector - "row" for a row vector, "column" for a column vector

setInputParameter

public void setInputParameter(String name,
                              cern.colt.matrix.tdouble.DoubleMatrix1D values,
                              String rowColumnVector)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

values - The 1D array of values of the input parameter, converted to an N-DIM array object of size (1,values.length)

rowColumnVector - "row" for a row vector, "column" for a column vector

setInputParameter

public void setInputParameter(String name,
                              Collection<? extends Number> values,
                              String rowColumnVector)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

values - A collection with values of type Number (e.g. Double, Integer, Long...) of the input parameter

rowColumnVector - "row" for a row vector, "column" for a column vector

setInputParameter

public void setInputParameter(String name,
                              double[][] values)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

values - The 2D array of values of the input parameter, converted to an N-DIM array object of the same size

setInputParameter

public void setInputParameter(String name,
                              DoubleMatrixND array)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

array - The array of values of the input parameter

setInputParameter

public void setInputParameter(String name,
                              cern.colt.matrix.tdouble.DoubleMatrix2D array)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

array - The array of values of the input parameter

setInputParameter

public void setInputParameter(String name,
                              int value)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

value - The scalar value of the input parameter, casted to double, and converted to an N-DIM array object of size (1,1)

setInputParameter

public void setInputParameter(String name,
                              int[] values,
                              String rowColumnVector)

Sets the value of the (arrayed) input parameter identified by its name. If an input parameter with the same name was previously set, the old values are lost

Parameters:

name - Name of the input parameter as it appears in the expressions.

values - The 1D array of values of the input parameter, casted to double, and converted to an N-DIM array object of size (1,values .length)

rowColumnVector - "row" for a row vector, "column" for a column vector

setInputParameter

public void setInputParameter(String name,
                              String expression)

Sets the value of the (arrayed) input parameter identified by its name. The String should be evaluated to a constant Expression.

Parameters:

name - Name of the input parameter as it appears in the expressions.

expression - array The expression is evaluated using a common parseExpression. If it is not constant, an Exception is raised.

setObjectiveFunction

public Expression setObjectiveFunction(String minMax,
                                       String expression)

Sets the objective function of the optimization problem, and its direction (maximice or minimice). If an objective function and direction was previously set, they are lost.

Parameters:

minMax - "Minimize" if the target is to minimize this expression, "Maximize" if the target is to maximize this expression

expression - The string expression of the objective function, that should successfully parsed as an scalar expression of the decision variables and input parameters of the problem

Returns:

The Expression object associated to the objective function

solutionIsFeasible

public boolean solutionIsFeasible()

Returns true if the problem was solved, and the solution obtained is feasible. If the method "solve" was not invoked yet, throws an exception

Returns:

See above

solutionIsOptimal

public boolean solutionIsOptimal()

Returns true if the problem was solved, and the solution obtained is optimal according to the solver. If the method "solve" was not invoked yet, throws an exception

Returns:

See above

solve

public void solve(String solverName,
                  Object... paramValuePairs)

Calls the indicated solver to solve the optimization problem in its current state (e.g. current objective function and input parameters set).

Parameters:

solverName - The name of the solver to be used. Current supported solvers are GLPK (solverName "glpk") and CPLEX (solverName "cplex") for mixed integer linear problems and IPOPT (solverName "ipopt") for non-linear non-integer problems.

paramValuePairs - Parameters to be passed to the solver to tune its operation. An even number of Object objects is to be passed. For each object pair, first Object must be a String with the name of the parameter, second a general Object with its value. If no name-value pairs are set, solver default values are used. For the "solverLibraryName" parameter, passing a value equal to an empty string "" is equivalent to not passing this parameter. See the documentation for further information.

timeReport

public String timeReport()

Return a printed report with the time spended in the different parts of the problem: defining the variables, objective, constraints and solving.

Returns:

a formatted string with the report

toString

public String toString()

Returns a formatted string with some information of the optimization problem

Overrides:

toString in class Object

Returns:

The string