org.optimizationservices.oscommon.localinterface
Class OSInstance

java.lang.Object
  org.optimizationservices.oscommon.localinterface.OSInstance

public class OSInstance
extends java.lang.Object

The OSInstance class is a local interface for storing Optimization Services problem instance. Its design follows the Optimization Services instance Language (OSiL). Naming, structuring and layering all are exactly the same as those in the OSiL schema. In general there are three simple rules in translating the OSiL schema. 1. An element that is not of simple type (contains non-char nodes) or has attributes, become a class. The class type corresponds to the element type defined in the schema. 2. A simple type element (just contains character data in the element) becomes a correponding programming language (Java/C++/C#) data type. 3. A "sequence" of one or more same-type elements becomes an array, members with the selected choice being non-null. There are some exceptions. 1. Each "OSnLNode" "nonlinearExpressions" or "userFunctions" becomes an OSExpressionTree. 2. There are no definitions of "userFunctions", "simulations" and "realTimeData" because these definitions are substituted. 3. All compression-related elements and attributes in xml disappear in the local interface because they are all expanded. 4. "semidefiniteBlocks", "cones", "stages", "stochasticInformation" and "xmlData" are not implemented yet.

Since:

OS 1.0

Version:

1.0, 03/14/2005

Author:

Robert Fourer, Jun Ma, Kipp Martin

See Also:

OSResult, OSAnalysis, OSOption

Field Summary

InstanceData	instanceData instanceData holds the second child of the OSInstance specified by the OSiL Schema.
InstanceHeader	instanceHeader instanceHeader holds the first child of the OSInstance specified by the OSiL Schema.

Constructor Summary

OSInstance()
default constructor.

Method Summary

boolean	addConstraint(int index, java.lang.String name, double lowerBound, double upperBound, double constant) add a constraint.
boolean	addNonlinearExpressionTree(int index, OSExpressionTree osExpressionTree) add a nonlinear expression tree.
boolean	addNonlinearExpressionTree(int index, java.lang.String[] tokens, int start, int end, java.lang.String fixType) add a nonlinear expression tree.
boolean	addObjective(int index, java.lang.String name, java.lang.String maxOrMin, double constant, double weight, SparseVector objectiveCoefficients) add an objective.
boolean	addVariable(int index, java.lang.String name, double lowerBound, double upperBound, char type, double init, java.lang.String initString) add a variable.
double[]	calculateConstraintFunctionValues(double[] x) Calculate all the constraint function (nonlinear+quadratic+linear) values given the current variable values.
SparseVector[]	calculateFunctionGradients(double[] x, boolean functionEValuated)
SparseVector	calculateFunctionGradients(int index, double[] x, boolean functionEValuated)
MatrixMarket	calculateFunctionHessian(int index, double[] x, boolean gradientEvaluated)
double	calculateFunctionValue(int index, double[] x) Calculate the function (nonlinear+quadratic+linear) value in a specified row given the current variable values.
MatrixMarket	calculateLagragianFunctionHessian(int objectiveIndex, double[] x, double[] weights, boolean gradientEvaluated)
double[]	calculateLagragianFunctionHessianTimesVector(int objectiveIndex, double[] x, double[] weights, double[] vector, boolean gradientEvaluated)
double[]	calculateLinearConstraintFunctionValues(double[] x) Calculate all the values of the linear parts of the constraint functions given the current variable values.
double	calculateLinearFunctionValue(int index, double[] x) Calculate the value of the linear part of a function in a specified row given the current variable values.
SparseVector	calculateNonlinearExpressionGradients(int index, double[] x, boolean functionEvaluated) Calculate the nonlinear gradients in a specified row given the current variable.
MatrixMarket	calculateNonlinearExpressionHessian(int index, double[] x, boolean gradientEvaluated) Calculate the nonlinear hessian in a specified row given the current variable.
double	calculateNonlinearExpressionValue(int index, double[] x) Calculate the nonlinear function value in a specified row given the current variable values.
double[]	calculateQuadraticConstraintFunctionValues(double[] x) Calculate the value of the quadratic part of a function in a specified row given the current variable values.
double	calculateQuadraticFunctionValue(int index, double[] x) Calculate the value of the quadratic part of a function in a specified row given the current variable values.
double[]	getConstraintConstants() Get constraint constants.
double[]	getConstraintLowerBounds() Get constraint lower bounds.
java.lang.String[]	getConstraintNames() Get constraint names.
int	getConstraintNumber() Get constraint number.
char[]	getConstraintTypes() Get constraint types.
double[]	getConstraintUpperBounds() Get constraint upper bounds.
double[][]	getDenseObjectiveCoefficients() Get dense objective coefficients.
java.lang.String	getInstanceDescription() Get instance description.
java.lang.String	getInstanceName() Get instance name.
java.lang.String	getInstanceSource() Get instance source.
boolean	getLinearConstraintCoefficientMajor() Get whether the constraint coefficients is in column major (true) or row major (false).
int	getLinearConstraintCoefficientNumber() Get number of specified (usually nonzero) linear constraint coefficient values.
SparseMatrix	getLinearConstraintCoefficientsInColumnMajor() Get linear constraint coefficients in column major.
MatrixMarket	getLinearConstraintCoefficientsInMatrixMarket() Get linear constraint coefficients in matrix market form.
SparseMatrix	getLinearConstraintCoefficientsInRowMajor() Get linear constraint coefficients in row major.
OSExpressionTree	getNonlinearExpressionTree(int index) Get the nonlinear expression tree of a specific row in .
int[]	getNonlinearExpressionTreeIndexes() Get all the nonlinear expression tree indexes, i.e.
java.lang.String[]	getNonlinearExpressionTreeInInfix(int index) Get the nonlinear expression tree of a specific row in a string array of infix tokens.
java.lang.String[]	getNonlinearExpressionTreeInPostfix(int index) Get the nonlinear expression tree of a specific row in a string array of postfix tokens.
java.lang.String[]	getNonlinearExpressionTreeInPrefix(int index) Get the nonlinear expression tree of a specific row in a string array of prefix tokens.
int	getNonlinearExpressionTreeNumber() Get the number of nonlinear expression trees, i.e.
OSExpressionTree[]	getNonlinearExpressionTrees() Get all the nonlinear expression trees.
int[]	getObjectiveCoefficientNumbers() Get objective coefficient number.
SparseVector[]	getObjectiveCoefficients() Get objective coefficients.
double[]	getObjectiveConstants() Get objective constants.
java.lang.String[]	getObjectiveMaxOrMins() Get objective maxOrMins.
java.lang.String[]	getObjectiveNames() Get objective names.
int	getObjectiveNumber() Get objective number.
double[]	getObjectiveWeights() Get objective weights.
int[]	getQuadraticRowIndexes() Get all the quadratic row indexes, i.e.
int	getQuadraticTermNumber() Get the number of specified (usually nonzero) qTerms in the quadratic coefficients.
QuadraticTerms	getQuadraticTerms() Get all the quadratic terms in the instance.
java.lang.String[]	getVariableInitialStringValues() Get variable initial string values.
double[]	getVariableInitialValues() Get variable initial values.
double[]	getVariableLowerBounds() Get variable lower bounds.
java.lang.String[]	getVariableNames() Get variable names.
int	getVariableNumber() Get variable number.
char[]	getVariableTypes() Get variable types.
double[]	getVariableUpperBounds() Get variable upper bounds.
static void	main(java.lang.String[] args) main for test purposes.
OSInstance	readOSiL(java.lang.String osil, boolean isFile, boolean validate) read an OSiL instance and return an OSInstance object.
boolean	setConstraintNumber(int number) set the constraint number.
boolean	setConstraints(int number, java.lang.String[] names, double[] lowerBounds, double[] upperBounds, double[] constants) set all the constraint related elements.
boolean	setInstanceDescription(java.lang.String description) set the instance description.
boolean	setInstanceName(java.lang.String name) set the instance name.
boolean	setInstanceSource(java.lang.String source) set the instance source.
boolean	setLinearConstraintCoefficients(int number, boolean isColumnMajor, double[] values, int valuesBegin, int valuesEnd, int[] indexes, int indexesBegin, int indexesEnd, int[] starts, int startsBegin, int startsEnd) set linear constraint coefficients
boolean	setNonlinearExpressionTreeNumber(int number) set the number of nonlinear expression trees to add.
boolean	setObjectiveNumber(int number) set the objective number.
boolean	setObjectives(int number, java.lang.String[] names, java.lang.String[] maxOrMins, double[] constants, double[] weights, SparseVector[] objectitiveCoefficients) set all the objectives related elements.
boolean	setQuadraticTerms(int number, int[] rowIndexes, int[] varOneIndexes, int[] varTwoIndexes, double[] coefficients, int begin, int end) set quadratic terms
boolean	setVariableNumber(int number) set the variable number.
boolean	setVariables(int number, java.lang.String[] names, double[] lowerBounds, double[] upperBounds, char[] types, double[] inits, java.lang.String[] initsString) set all the variable related elements.
java.lang.String	writeOSiL() write the OSInstance to an osil xml string.

Methods inherited from class java.lang.Object

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

Field Detail

instanceHeader

public InstanceHeader instanceHeader

instanceHeader holds the first child of the OSInstance specified by the OSiL Schema.

instanceData

public InstanceData instanceData

instanceData holds the second child of the OSInstance specified by the OSiL Schema.

Constructor Detail

OSInstance

public OSInstance()

default constructor.

Method Detail

readOSiL

public OSInstance readOSiL(java.lang.String osil,
                           boolean isFile,
                           boolean validate)
                    throws java.lang.Exception

read an OSiL instance and return an OSInstance object.

Parameters:

osil - holds the optimization instance in a string which format follows the Optimization Services instance Language (OSiL) schema.

isFile - holds whether the osil string is a file name or a string that literally holds the osil instance.

validate - holds whether the reader should be validating against the schema or not.

Returns:

the OSInstance constructed from the OSiL String.

Throws:

java.lang.Exception - if there are errors in reading the string or setting the OSInstnace.

writeOSiL

public java.lang.String writeOSiL()
                           throws java.lang.Exception

write the OSInstance to an osil xml string.

Returns:

the osil xml string.

Throws:

java.lang.Exception - if there are errors in writing the osil string.

getInstanceName

public java.lang.String getInstanceName()

Get instance name.

Returns:

instance name. Null or empty string ("") if there is no instance name.

getInstanceSource

public java.lang.String getInstanceSource()

Get instance source.

Returns:

instance source. Null or empty string ("") if there is no instance source.

getInstanceDescription

public java.lang.String getInstanceDescription()

Get instance description.

Returns:

instance description. Null or empty string ("") if there is no instance description.

getVariableNumber

public int getVariableNumber()

Get variable number.

Returns:

variable number.

getVariableNames

public java.lang.String[] getVariableNames()
                                    throws java.lang.Exception

Get variable names.

Returns:

a string array of variable names, null if no variable names.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getVariableInitialValues

public double[] getVariableInitialValues()
                                  throws java.lang.Exception

Get variable initial values.

Returns:

a double array of variable initial values, null if no initial variable values.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getVariableInitialStringValues

public java.lang.String[] getVariableInitialStringValues()
                                                  throws java.lang.Exception

Get variable initial string values.

Returns:

a string array of variable initial values, null if no initial variable string values.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getVariableTypes

public char[] getVariableTypes()
                        throws java.lang.Exception

Get variable types.

• C for Continuous
• B for Binary
• I for Integer
• S for String

Returns:

a char array of variable types.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getVariableLowerBounds

public double[] getVariableLowerBounds()
                                throws java.lang.Exception

Get variable lower bounds.

Returns:

a double array of variable lower bounds.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getVariableUpperBounds

public double[] getVariableUpperBounds()
                                throws java.lang.Exception

Get variable upper bounds.

Returns:

a double array of variable upper bounds.

Throws:

java.lang.Exception - if the elements in variables are logically inconsistent.

getObjectiveNumber

public int getObjectiveNumber()

Get objective number.

Returns:

objective number.

getObjectiveNames

public java.lang.String[] getObjectiveNames()
                                     throws java.lang.Exception

Get objective names.

Returns:

a string array of objective names. Null if no objective names.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getObjectiveMaxOrMins

public java.lang.String[] getObjectiveMaxOrMins()
                                         throws java.lang.Exception

Get objective maxOrMins. One maxOrMin for each objective.

Returns:

a string array of objective maxOrMins ("max" or "min"), null if no objectives.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getObjectiveCoefficientNumbers

public int[] getObjectiveCoefficientNumbers()
                                     throws java.lang.Exception

Get objective coefficient number. One number for each objective.

Returns:

an integer array of objective coefficient numbers, null if no objectives.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getObjectiveConstants

public double[] getObjectiveConstants()
                               throws java.lang.Exception

Get objective constants. One constant for each objective.

Returns:

a double array of objective constants, null if no objectives.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getObjectiveWeights

public double[] getObjectiveWeights()
                             throws java.lang.Exception

Get objective weights. One weight for each objective.

Returns:

a double array of objective weights, null if no objectives.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getObjectiveCoefficients

public SparseVector[] getObjectiveCoefficients()
                                        throws java.lang.Exception

Get objective coefficients. One set of objective coefficients for each objective.

Returns:

an array of objective coefficients, null if no objective coefficients. If any one objective has objective coefficients, the array will not be null and the array size is equal to the number of objective functions. Each member of the array can still be null if the corresponding objective function doesn't have coefficients. Each member of the array is of type ObjectiveCoefficients. The ObjectiveCoefficients class contains two arrays: variableIndexes is an integer array and values is a double array of coefficient values.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

See Also:

SparseVector

getDenseObjectiveCoefficients

public double[][] getDenseObjectiveCoefficients()
                                         throws java.lang.Exception

Get dense objective coefficients. One set of dense objective coefficients for each objective.

Returns:

an array of dense objective coefficients, null if no objective coefficients. If any one objective has objective coefficients, the array will not be null and the array size is equal to the number of objective functions. Each member of the array can still be null if the corresponding objective function doesn't have coefficients.

Throws:

java.lang.Exception - if the elements in objectives are logically inconsistent.

getConstraintNumber

public int getConstraintNumber()

Get constraint number.

Returns:

constraint number.

getConstraintNames

public java.lang.String[] getConstraintNames()
                                      throws java.lang.Exception

Get constraint names.

Returns:

a string array of constraint names, null if no constraint names.

Throws:

java.lang.Exception - if the elements in constraints are logically inconsistent.

getConstraintLowerBounds

public double[] getConstraintLowerBounds()
                                  throws java.lang.Exception

Get constraint lower bounds.

Returns:

a double array of constraint lower bounds, null if no constraints.

Throws:

java.lang.Exception - if the elements in constraints are logically inconsistent.

getConstraintUpperBounds

public double[] getConstraintUpperBounds()
                                  throws java.lang.Exception

Get constraint upper bounds.

Returns:

a double array of constraint upper bounds, null if no constraints.

Throws:

java.lang.Exception - if the elements in constraints are logically inconsistent.

getConstraintConstants

public double[] getConstraintConstants()
                                throws java.lang.Exception

Get constraint constants.

Returns:

a double array of constraint constants, null if no constraints.

Throws:

java.lang.Exception - if the elements in constraints are logically inconsistent.

getConstraintTypes

public char[] getConstraintTypes()
                          throws java.lang.Exception

Get constraint types.

• R for range constraint lb <= constraint <= ub
• L for less than constraint -INF <= con <= ub or con <= ub
• G for greater than constraint lb <= con <= INF or con >= lb
• E for equal to constraint lb <= con <= ub where lb = ub or con = lb/ub
• U for unconstrained constraint -INF <= con <= INF

Returns:

a char array of constraint types, null if constraints.

Throws:

java.lang.Exception - if the elements in constraints are logically inconsistent.

getLinearConstraintCoefficientNumber

public int getLinearConstraintCoefficientNumber()

Get number of specified (usually nonzero) linear constraint coefficient values.

Returns:

number of specified (usually nonzero) linear constraint coefficient values.

getLinearConstraintCoefficientMajor

public boolean getLinearConstraintCoefficientMajor()
                                            throws java.lang.Exception

Get whether the constraint coefficients is in column major (true) or row major (false).

Returns:

whether the constraint coefficients is in column major (true) or row major (false).

Throws:

java.lang.Exception - if the elements in linear constraint coefficients are logically inconsistent.

getLinearConstraintCoefficientsInColumnMajor

public SparseMatrix getLinearConstraintCoefficientsInColumnMajor()
                                                          throws java.lang.Exception

Get linear constraint coefficients in column major.

Returns:

a sparse matrix reprsentation of linear constraint coefficients in column major, null if no linear constraint coefficients.

Throws:

java.lang.Exception - if the elements in linear constraint coefficients are logically inconsistent.

See Also:

SparseMatrix

getLinearConstraintCoefficientsInRowMajor

public SparseMatrix getLinearConstraintCoefficientsInRowMajor()
                                                       throws java.lang.Exception

Get linear constraint coefficients in row major.

Returns:

a sparse matrix reprsentation of linear constraint coefficients in row major, null if no linear constraint coefficients.

Throws:

java.lang.Exception - if the elements in linear constraint coefficients are logically inconsistent.

See Also:

SparseMatrix

getLinearConstraintCoefficientsInMatrixMarket

public MatrixMarket getLinearConstraintCoefficientsInMatrixMarket()
                                                           throws java.lang.Exception

Get linear constraint coefficients in matrix market form.

Returns:

a matrix market reprsentation (i, j, Cij) of linear constraint coefficients, null if no linear constraint coefficients.

Throws:

java.lang.Exception - if the elements in linear constraint coefficients are logically inconsistent.

See Also:

MatrixMarket

getQuadraticTermNumber

public int getQuadraticTermNumber()

Get the number of specified (usually nonzero) qTerms in the quadratic coefficients.

Returns:

qTerm number.

getQuadraticTerms

public QuadraticTerms getQuadraticTerms()
                                 throws java.lang.Exception

Get all the quadratic terms in the instance.

Returns:

the QuadraticTerms data structure for all quadratic terms in the instance, null if no quadratic terms. The QuadraticTerms contains four arrays: rowIndexes, varOneIndexes, varTwoIndexes, coefficients.

Throws:

java.lang.Exception - if the elements in quadratic coefficients are logically inconsistent.

See Also:

QuadraticTerms

getQuadraticRowIndexes

public int[] getQuadraticRowIndexes()
                             throws java.lang.Exception

Get all the quadratic row indexes, i.e. indexes of rows (objetives or constraints) that contain quadratic terms.

Returns:

an integer array of quadratic row indexes.

Throws:

java.lang.Exception - if the elements in quadratic expressions are logically inconsistent.

getNonlinearExpressionTreeNumber

public int getNonlinearExpressionTreeNumber()
                                     throws java.lang.Exception

Get the number of nonlinear expression trees, i.e. the number of nonlinear objectives or constraints.

Returns:

the number of nonlinear expression trees, i.e. the number of nonlinear objectives or constraints.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

getNonlinearExpressionTreeIndexes

public int[] getNonlinearExpressionTreeIndexes()
                                        throws java.lang.Exception

Get all the nonlinear expression tree indexes, i.e. indexes of rows (objetives or constraints) that contain nonlinear expressions.

Returns:

an integer array of nonlinear expression tree indexes.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

getNonlinearExpressionTrees

public OSExpressionTree[] getNonlinearExpressionTrees()
                                               throws java.lang.Exception

Get all the nonlinear expression trees.

Returns:

an array of nonlinear expression trees, each tree is of the standard type OSExpressionTree.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

See Also:

OSExpressionTree

getNonlinearExpressionTree

public OSExpressionTree getNonlinearExpressionTree(int index)
                                            throws java.lang.Exception

Get the nonlinear expression tree of a specific row in .

Parameters:

index - holds the row index (objective or constraint) to which the nonlinear expression tree belongs. Constraint indexes start from 0, 1, 2, ... up. Objective indexes start from -1, -2, -3, ... down.

Returns:

a nonlinear expression trees, of the standard type OSExpressionTree, null if there is no nonlinear expression tree from that row.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

See Also:

OSExpressionTree

getNonlinearExpressionTreeInPrefix

public java.lang.String[] getNonlinearExpressionTreeInPrefix(int index)
                                                      throws java.lang.Exception

Get the nonlinear expression tree of a specific row in a string array of prefix tokens.

Parameters:

index - holds the row index (objective or constraint) to which the nonlinear expression tree belongs. Constraint indexes start from 0, 1, 2, ... up. Objective indexes start from -1, -2, -3, ... down.

Returns:

a nonlinear expression tree of a specific row in a string array of prefix tokens.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

See Also:

OSExpressionTree

getNonlinearExpressionTreeInPostfix

public java.lang.String[] getNonlinearExpressionTreeInPostfix(int index)
                                                       throws java.lang.Exception

Get the nonlinear expression tree of a specific row in a string array of postfix tokens.

Parameters:

index - holds the row index (objective or constraint) to which the nonlinear expression tree belongs. Constraint indexes start from 0, 1, 2, ... up. Objective indexes start from -1, -2, -3, ... down.

Returns:

a nonlinear expression tree of a specific row in a string array of postfix tokens.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

See Also:

OSExpressionTree

getNonlinearExpressionTreeInInfix

public java.lang.String[] getNonlinearExpressionTreeInInfix(int index)
                                                     throws java.lang.Exception

Get the nonlinear expression tree of a specific row in a string array of infix tokens.

Parameters:

index - holds the row index (objective or constraint) to which the nonlinear expression tree belongs. Constraint indexes start from 0, 1, 2, ... up. Objective indexes start from -1, -2, -3, ... down.

Returns:

a nonlinear expression tree of a specific row in a string array of infix tokens.

Throws:

java.lang.Exception - if the elements in nonlinear expressions are logically inconsistent.

See Also:

OSExpressionTree

calculateLinearFunctionValue

public double calculateLinearFunctionValue(int index,
                                           double[] x)

Calculate the value of the linear part of a function in a specified row given the current variable values. Negative row indicates an objective function.

Parameters:

index - holds the row number to which the linear function belongs. Negative row indicates an objective function.

x - holds the values of the variables in a double array.

Returns:

the linear part value of the function in the specified row. If there are errors, Doule.NaN is returned.

calculateLinearConstraintFunctionValues

public double[] calculateLinearConstraintFunctionValues(double[] x)

Calculate all the values of the linear parts of the constraint functions given the current variable values.

Parameters:

x - holds the values of the variables in a double array.

Returns:

a double array of the linear part values of all the constraints. If there are errors, null is returned.

calculateQuadraticFunctionValue

public double calculateQuadraticFunctionValue(int index,
                                              double[] x)

Calculate the value of the quadratic part of a function in a specified row given the current variable values. Negative row indicates an objective function.

Parameters:

index - holds the row number to which the quadratic function belongs. Negative row indicates an objective function.

x - holds the values of the variables in a double array.

Returns:

the quadratic part value of the function in the specified row. If there are errors, Doule.NaN is returned.

calculateQuadraticConstraintFunctionValues

public double[] calculateQuadraticConstraintFunctionValues(double[] x)

Calculate the value of the quadratic part of a function in a specified row given the current variable values. Negative row indicates an objective function.

Parameters:

x - holds the values of the variables in a double array.

Returns:

the quadratic part value of the function in the specified row. If there are errors or there are no quadratic terms, null will be returned.

calculateNonlinearExpressionValue

public double calculateNonlinearExpressionValue(int index,
                                                double[] x)

Calculate the nonlinear function value in a specified row given the current variable values.

Parameters:

index - holds the row number to which the nonlinear function belongs. if negative, it is an objective function.

x - holds the values of the variables in a double array.

functionEvaluated - holds whether the function has been evaluated.

Returns:

the nonlinear function value in the specified constraint (row) given the current variable values.

calculateFunctionValue

public double calculateFunctionValue(int index,
                                     double[] x)

Calculate the function (nonlinear+quadratic+linear) value in a specified row given the current variable values.

Parameters:

index - holds the row number to which the function belongs. if negative, it is an objective function.

x - holds the values of the variables in a double array.

Returns:

the function value in the specified row given the current variable values.

calculateConstraintFunctionValues

public double[] calculateConstraintFunctionValues(double[] x)

Calculate all the constraint function (nonlinear+quadratic+linear) values given the current variable values.

Parameters:

x - holds the values of the variables in a double array.

Returns:

all the constraint function values given the current variable values. If there are errors, null is returned;

calculateNonlinearExpressionGradients

public SparseVector calculateNonlinearExpressionGradients(int index,
                                                          double[] x,
                                                          boolean functionEvaluated)

Calculate the nonlinear gradients in a specified row given the current variable.

Parameters:

index - holds the row number to which the nonlinear expression belongs. If negative, it's an objective function.

x - holds the values of the variables in a double array.

functionEvaluated - holds whether the function has been evaluated.

Returns:

a sparse representation of the function gradient values.

The SparseVector class holds a two array data structure (indexes, values). The indexes are not ordered.

See Also:

SparseVector

calculateFunctionGradients

public SparseVector calculateFunctionGradients(int index,
                                               double[] x,
                                               boolean functionEValuated)

calculateFunctionGradients

public SparseVector[] calculateFunctionGradients(double[] x,
                                                 boolean functionEValuated)

calculateNonlinearExpressionHessian

public MatrixMarket calculateNonlinearExpressionHessian(int index,
                                                        double[] x,
                                                        boolean gradientEvaluated)

Calculate the nonlinear hessian in a specified row given the current variable.

Parameters:

index - holds the row number to which the nonlinear expression belongs. If negative, it's an objective function.

x - holds the values of the variables in a double array.

functionEvaluated - holds whether the function has been evaluated.

Returns:

a matrix market (i, j, Cij triplets) representation of the function hessian values, null if none.

The MatrixMarket class holds the matrix market data structure (rowIndex, columnIndex, Value[rowIndex,columnIndex]) hessian values.

See Also:

MatrixMarket

calculateFunctionHessian

public MatrixMarket calculateFunctionHessian(int index,
                                             double[] x,
                                             boolean gradientEvaluated)

calculateLagragianFunctionHessian

public MatrixMarket calculateLagragianFunctionHessian(int objectiveIndex,
                                                      double[] x,
                                                      double[] weights,
                                                      boolean gradientEvaluated)

calculateLagragianFunctionHessianTimesVector

public double[] calculateLagragianFunctionHessianTimesVector(int objectiveIndex,
                                                             double[] x,
                                                             double[] weights,
                                                             double[] vector,
                                                             boolean gradientEvaluated)

setInstanceSource

public boolean setInstanceSource(java.lang.String source)

set the instance source.

Parameters:

source - holds the instance source.

Returns:

whether the instance source is set successfully.

setInstanceDescription

public boolean setInstanceDescription(java.lang.String description)

set the instance description.

Parameters:

description - holds the instance description.

Returns:

whether the instance description is set successfully.

setInstanceName

public boolean setInstanceName(java.lang.String name)

set the instance name.

Parameters:

name - holds the instance name.

Returns:

whether the instance name is set successfully.

setVariableNumber

public boolean setVariableNumber(int number)

set the variable number.

Parameters:

number - holds the variable number.

Returns:

whether the variable number is set successfully.

addVariable

public boolean addVariable(int index,
                           java.lang.String name,
                           double lowerBound,
                           double upperBound,
                           char type,
                           double init,
                           java.lang.String initString)

add a variable. In order to use the add method, the setVariableNumber must first be called so that the variable number is known ahead of time to assign appropriate memory. If a variable with the given variable index already exists, the old variable will be replaced.

Parameters:

index - holds the variable index. It is required.

name - holds the variable name; use null or empty string ("") if no variable name.

lowerBound - holds the variable lower bound; use Double.NEGATIVE_INFINITY if no lower bound.

upperBound - holds the variable upper bound; use Double.POSITIVE_INFINITY if no upper bound.

type - holds the variable type character, B for Binary, I for Integer, S for String, C or any other char for Continuous)

init - holds the double variable initial value; use Double.NaN if no initial value.

initString - holds the string variable initial value; use null or empty string ("") if no initial string value.

Returns:

whether the variable is added successfully.

setVariables

public boolean setVariables(int number,
                            java.lang.String[] names,
                            double[] lowerBounds,
                            double[] upperBounds,
                            char[] types,
                            double[] inits,
                            java.lang.String[] initsString)

set all the variable related elements. All the previous variable-related elements will be deleted.

Parameters:

number - holds the number of variables. It is required.

names - holds a string array of variable names; use null if no variable names.

lowerBounds - holds a double array of variable lower bounds; use null all lower bounds are 0; use Double.NEGATIVE_INFINITY if no lower bound for a specific variable in the array.

upperBounds - holds a double array of variable upper bounds; use null if no upper bounds; use Double.POSITIVE_INFINITY if no upper bound for a specific variable in the array.

types - holds a char array of variable types; use null if all variables are continuous; for a specfic variable in the array use B for Binary, I for Integer, S for String, C or any other char for Continuous,)

inits - holds a double array of varible initial values; use null if no initial values.

initsString - holds a string array of varible initial values; use null if no initial string values.

Returns:

whether the variables are set successfully.

setObjectiveNumber

public boolean setObjectiveNumber(int number)

set the objective number.

Parameters:

number - holds the objective number.

Returns:

whether the objective number is set successfully.

addObjective

public boolean addObjective(int index,
                            java.lang.String name,
                            java.lang.String maxOrMin,
                            double constant,
                            double weight,
                            SparseVector objectiveCoefficients)

add an objective. In order to use the add method, the setObjectiveNumber must first be called so that the objective number is known ahead of time to assign appropriate memory. If a objective with the given objective index already exists, the old objective will be replaced. Objective index will start from -1, -2, -3, ... down, with -1 corresponding to the first objective.

Parameters:

index - holds the objective index. Remember the first objective index is -1, second -2, ...

name - holds the objective name; use null or empty string ("") if no objective name.

maxOrMin - holds the objective sense or direction; it can only take two values: "max" or "min".

constant - holds the objective constant; use 0.0 if no objective constant.

weight - holds the objective weight; use 1.0 if no objective weight.

objectiveCoefficients - holds the objective coefficients (null if no objective coefficients) in a sparse representation that holds two arrays: index array and a value array.

Returns:

whether the objective is added successfully.

setObjectives

public boolean setObjectives(int number,
                             java.lang.String[] names,
                             java.lang.String[] maxOrMins,
                             double[] constants,
                             double[] weights,
                             SparseVector[] objectitiveCoefficients)

set all the objectives related elements. All the previous objective-related elements will be deleted.

Parameters:

number - holds the number of objectives. It is required.

names - holds a string array of objective names; use null if no objective names.

maxOrMins - holds a string array of objective objective senses or directions: "max" or "min"; use null if all objectives are "min".

constants - holds a double array of objective constants; use null if all objective constants are 0.0.

weights - holds a double array of objective weights; use null if all objective weights are 1.0.

objectitiveCoefficients - holds an array of objective coefficients, (null if no objective have any coefficeints) For each objective, the coefficients are stored in a sparse representation that holds two arrays: index array and a value array. If for a specific objective, there are no objecitve coefficients, use null for the corresponding array member.

Returns:

whether the objectives are set successfully.

setConstraintNumber

public boolean setConstraintNumber(int number)

set the constraint number.

Parameters:

number - holds the constraint number.

Returns:

whether the constraint number is set successfully.

addConstraint

public boolean addConstraint(int index,
                             java.lang.String name,
                             double lowerBound,
                             double upperBound,
                             double constant)

add a constraint. In order to use the add method, the setConstraintNumber must first be called so that the constraint number is known ahead of time to assign appropriate memory. If a constraint with the given constraint index already exists, the old constraint will be replaced.

Parameters:

index - holds the constraint index. It is required.

name - holds the constraint name; use null or empty string ("") if no constraint name.

lowerBound - holds the constraint lower bound; use Double.NEGATIVE_INFINITY if no lower bound.

upperBound - holds the constraint upper bound; use Double.POSITIVE_INFINITY if no upper bound.

constant - holds the constraint constant.

Returns:

whether the constraint is added successfully.

setConstraints

public boolean setConstraints(int number,
                              java.lang.String[] names,
                              double[] lowerBounds,
                              double[] upperBounds,
                              double[] constants)

set all the constraint related elements. All the previous constraint-related elements will be deleted.

Parameters:

number - holds the number of constraints. It is required.

names - holds a string array of constraint names; use null if no constraint names.

lowerBounds - holds a double array of constraint lower bounds; use null if no lower bounds; use Double.NEGATIVE_INFINITY if no lower bound for a specific constraint in the array.

upperBounds - holds a double array of constraint upper bounds; use null if no upper bounds; use Double.POSITIVE_INFINITY if no upper bound for a specific constraint in the array.

constants - holds a double array of constraint constants, use null if all are zeros.

Returns:

whether the constraints are set successfully.

setLinearConstraintCoefficients

public boolean setLinearConstraintCoefficients(int number,
                                               boolean isColumnMajor,
                                               double[] values,
                                               int valuesBegin,
                                               int valuesEnd,
                                               int[] indexes,
                                               int indexesBegin,
                                               int indexesEnd,
                                               int[] starts,
                                               int startsBegin,
                                               int startsEnd)

set linear constraint coefficients

Parameters:

number - holds the number of specified coefficient values (usually nonzero) in the coefficient matrix.

isColumnMajor - holds whether the coefficient matrix is stored in column major (true) or row major (false).

values - holds a double array coefficient values in the matrix.

valuesBegin - holds the begin index of the values array to copy from (usually 0).

valuesEnd - holds the end index of the values array to copy till (usually values.lenght - 1).

indexes - holds an integer array column/row indexes for each value in the values array.

indexesBegin - holds the begin index of the indexes array to copy from (usually 0).

indexesEnd - holds the end index of the indexes array to copy till (usually indexes.lenght - 1).

starts - holds an integer array start indexes in the matrix; the first value of starts should always be 0.

startsBegin - holds the begin index of the starts array to copy from (usually 0).

startsEnd - holds the end index of the starts array to copy till (usually starts.lenght - 1).

Returns:

whether the linear constraint coefficients are set successfully.

setQuadraticTerms

public boolean setQuadraticTerms(int number,
                                 int[] rowIndexes,
                                 int[] varOneIndexes,
                                 int[] varTwoIndexes,
                                 double[] coefficients,
                                 int begin,
                                 int end)

set quadratic terms

Parameters:

number - holds the number of quadratic terms.

rowIndexes - holds an integer array of row indexes of all the quadratic terms. A negative integer corresponds to an objective row, e.g. -1 for 1st objective and -2 for 2nd.

varOneIndexes - holds an integer array of the first varialbe indexes of all the quadratic terms.

varTwoIndexes - holds an integer array of the second varialbe indexes of all the quadratic terms.

coefficients - holds a double array all the quadratic term coefficients.

begin - holds the begin index of all the arrays to copy from (usually = 0).

end - holds the end index of all the arrays to copy till (usually = array length -1).

Returns:

whether the quadratic terms are set successfully.

setNonlinearExpressionTreeNumber

public boolean setNonlinearExpressionTreeNumber(int number)

set the number of nonlinear expression trees to add. Expression trees with the same row indexes are concatenaged so they are counted as just one nonlinear expression tree.

Parameters:

number - holds the nonlinear expression tree number.

Returns:

whether the nonlinear expression tree number is set successfully.

addNonlinearExpressionTree

public boolean addNonlinearExpressionTree(int index,
                                          OSExpressionTree osExpressionTree)

add a nonlinear expression tree. In order to use the add method, the setNonlinearExpressionTreeNumber must first be called so that the nonlinear expression tree number is known ahead of time to assign appropriate memory. If a nonlinear expression tree with the given index already exists, the old constraint will be concatenated (added) with the new expression tree.

Parameters:

index - holds the row the nonlienar expression tree belongs to. If negative, it is an objective function.

osExpressionTree - holds the os expression.

Returns:

whether the expression tree is added successfully.

See Also:

org.optimizationservices.oscommon.nonlinear.OSExpressionTree;

addNonlinearExpressionTree

public boolean addNonlinearExpressionTree(int index,
                                          java.lang.String[] tokens,
                                          int start,
                                          int end,
                                          java.lang.String fixType)

add a nonlinear expression tree. In order to use the add method, the setNonlinearExpressionTreeNumber must first be called so that the nonlinear expression tree number is known ahead of time to assign appropriate memory. If a nonlinear expression tree with the given index already exists, the old constraint will be concatenated (added) with the new expression tree.

Parameters:

index - holds the row the nonlienar expression tree belongs to. If negative, it is an objective function.

tokens - holds a string array of the tokenized expression, in either postfix, prefix, or infix. The operator name in each token has to be exactly the same as the name specified in the OSnL Schema. The operator name in the token may be followed (without space) by a sequence of ":atrributeValue" and end with [i] to indicate the number of arguments the operator can take if the operator's type is indefinite. The attributes specified have to follow the sequence in the OSnL schema. If one attribute is specified, all attributes have to be specified together. If an attribute are missing, an empty string has to be in place. Two alternative exception can be allowed for variable and number. A number can just a a numeric value and the variable can take the form Xi where i is the integer index of capital letter X.

fixType - holds whether the expression is in postfix, prefix or infix

start - holds the index of the tokenizedExpression to start processing (ususually 0).

end - holds the index of the tokenizedExpression to finish processing (usually tokens.length-1).

Returns:

whether the expression tree is added successfully.

main

public static void main(java.lang.String[] args)

main for test purposes.

Parameters:

argv - command line arguments.