org.optimizationservices.oscommon.representationparser
Class OSiLWriter

java.lang.Object
  org.optimizationservices.oscommon.representationparser.OSgLWriter
      org.optimizationservices.oscommon.representationparser.OSiLWriter

public class OSiLWriter
extends OSgLWriter

The OSiLWriter class is used to construct an optimization instance that follows the Optimization Services instance Language format. Each element declared in the OSiL Schema has a corresponding protected element creation method (e.g. createEl for creation of element el). User do not have direct access to any of these protected methods. They get to manipulate the output of OSiL construction through a group of higher level optimization related public "set" methods (e.g. setConstraints). The "set" methods are the opposite "get" method in the corresponding OSiLReader class. Each method checks within itself the argument consistency against OSiL Schema at the syntax level. There is no specific sequence the user should follow to invoke these set methods. User can call the same set methods several times. If the parameters are different, old values will be replaced by new ones. Users should, though, make sure values submitted through different "set" methods are consistent, i.e. logically correct. For example if variableCount in setDescription is set to 2, then the variableLbs array in setVariables has to have a length 2.

The OSiLWriter class also provides auxiliary facilities to write the xml to different output.

The OSiLWriter class does not support writing mathML related elements.

Since:

OS 1.0

Version:

1.0, 03/14/2004

Author:

Robert Fourer, Jun Ma, Kipp Martin

See Also:

OSiLReader

Field Summary

Fields inherited from class org.optimizationservices.oscommon.representationparser.OSgLWriter

m_document

Constructor Summary

OSiLWriter()
constructor

Method Summary

boolean	addConstraint(java.lang.String constraintName, double constraintLhs, double constraintRhs, double constraintConstant) Add a constraint (or <con> element) to the existing constraints.
boolean	addNlNode(OSExpressionTree expressionTree, int rowIdx) Add an nl node.
boolean	addNlNode(java.util.Vector tokenizedExpression, java.lang.String type, int rowIdx, int start, int end) Add an nl node.
boolean	addObjective(java.lang.String objectiveName, boolean isMin, double objectiveConstant, double objectiveWeight, double[] coefValues, int[] coefIndexes) add an objective function related elements.
boolean	addSimulation(java.lang.String name, java.lang.String uri, OSsLWriter osslWriter) Add a simulation node.
boolean	addUserFunction(java.lang.String name, int numArg, OSExpressionTree expressionTree) Add a userFunction node.
boolean	addUserFunction(java.lang.String name, int numArg, java.util.Vector tokenizedExpression, java.lang.String type, int start, int end) Add a userFunction node.
boolean	addVariable(java.lang.String variableName, double variableLb, double variableUb, char variableType, double initialValue, java.lang.String initialStringValue) add a variable (or var element).
static void	main(java.lang.String[] argv) main for test purposes.
boolean	setConstraints(int numberConstraints, java.lang.String[] constraintNames, double[] constraintLbs, double[] constraintUbs, double[] constraintConstants) Set the constraint related elements.
boolean	setInstanceHeader(java.lang.String name, java.lang.String source, java.lang.String description) Set the InstanceHeader related elements.
boolean	setLinearConstraintCoefficients(int numberOfValues, boolean isColumnMajor, double[] nonzeroValues, int[] nonzeroValuesMultiplicity, double[] nonzeroValuesIncrement, int[] nonzeroIndexes, int[] nonzeroIndexesMultiplicity, int[] nonzeroIndexesIncrement, int[] startIndexes, int[] startIndexesMultiplicity, int[] startIndexesIncrement) Set the compressed sparse coefficient matrix related elements with support for multiplicity and increment.
boolean	setLinearConstraintCoefficients(int numberOfValues, boolean isColumnMajor, double[] nonzeroValues, int[] nonzeroValuesMultiplicity, double[] nonzeroValuesIncrement, int nonzeroValuesBegin, int nonzeroValuesEnd, int[] nonzeroIndexes, int[] nonzeroIndexesMultiplicity, int[] nonzeroIndexesIncrement, int nonzeroIndexesBegin, int nonzeroIndexesEnd, int[] startIndexes, int[] startIndexesMultiplicity, int[] startIndexesIncrement, int startIndexesBegin, int startIndexesEnd) Set the compressed sparse coefficient matrix related elements with support for multiplicity and increment.
boolean	setLinearConstraintCoefficients(int numberOfValues, boolean isColumnMajor, double[] nonzeroValues, int[] nonzeroIndexes, int[] startIndexes) Set the sparse coefficient matrix related elements.
boolean	setLinearConstraintCoefficients(int numberOfValues, boolean isColumnMajor, double[] nonzeroValues, int nonzeroValuesBegin, int nonzeroValuesEnd, int[] nonzeroIndexes, int nonzeroIndexesBegin, int nonzeroIndexesEnd, int[] startIndexes, int startIndexesBegin, int startIndexesEnd) Set the sparse coefficient matrix related elements.
boolean	setOSInstance(OSInstance osInstance) set the OSInstance, a standard optimization problem/data api.
boolean	setQuadraticTerms(int numberOfQuadraticTerms, int[] rowIndexes, int[] varOneIndexes, int[] varTwoIndexes, double[] coefficients, int begin, int end) Set the quadratic coefficient terms related elements.
boolean	setVariables(int numberVariables, java.lang.String[] variableNames, double[] variableLbs, double[] variableUbs, char[] variableTypes, double[] initialValues, java.lang.String[] initialStringValues) Set the variable related elements.
boolean	setXMLData(org.w3c.dom.Element xmlDataElement) Set the xmldData related elements.
boolean	setXMLData(java.lang.String xmlDataString) Set the xmldData related elements.

Methods inherited from class org.optimizationservices.oscommon.representationparser.OSgLWriter

getDocument, setDocument, writeToFile, writeToSring, writeToStandardOutput

Methods inherited from class java.lang.Object

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

Constructor Detail

OSiLWriter

public OSiLWriter()

constructor

Method Detail

setOSInstance

public boolean setOSInstance(OSInstance osInstance)
                      throws java.lang.Exception

set the OSInstance, a standard optimization problem/data api.

Returns:

whether the OSInstance is set successfully

Throws:

java.lang.Exception - if there are errors setting the OSInstnace.

setInstanceHeader

public boolean setInstanceHeader(java.lang.String name,
                                 java.lang.String source,
                                 java.lang.String description)

Set the InstanceHeader related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

Parameters:

name - holds the name of the optimization problem.

source - holds the source information of the optimization problem.

description - holds the description information of the optimization problem.

Returns:

whether the InstanceHeader construction is successful.

setVariables

public boolean setVariables(int numberVariables,
                            java.lang.String[] variableNames,
                            double[] variableLbs,
                            double[] variableUbs,
                            char[] variableTypes,
                            double[] initialValues,
                            java.lang.String[] initialStringValues)

Set the variable related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

Parameters:

numberVariables - holds the number of variables.

variableNames - holds the names of all the variables. It may be empty.

variableLbs - holds the values of lower bounds for the variables. It may be empty.

variableUbs - holds the values of upper bounds for the variables. It may be empty.

variableTypes - holds the types of all the variables, (e.g. 'C' for continuous type, 'I' for integer type, and 'B' for binary type). It may be empty.

initialValues - holds the initial double values of the variables. It may be empty.

initialStringValues - holds the initial string values of the variables. It may be empty.

Returns:

whether variable construction is successful.

addVariable

public boolean addVariable(java.lang.String variableName,
                           double variableLb,
                           double variableUb,
                           char variableType,
                           double initialValue,
                           java.lang.String initialStringValue)

add a variable (or var element).

Parameters:

variableName - holds the name of a variable. It may be null.

variableLb - holds the value of the lower bound for the variable.

variableUb - holds the value of the upper bound for the variables.

variableType - holds the type of the variable, (e.g. 'C' for continuous type, 'I' for integer type, and 'B' for binary type).

initialValue - holds the initial value of the variables. It may be NaN, i.e. Double.NaN.

initialStringValue - holds the initial string value of the variables. It may be null.

Returns:

whether variable addition is successful.

addObjective

public boolean addObjective(java.lang.String objectiveName,
                            boolean isMin,
                            double objectiveConstant,
                            double objectiveWeight,
                            double[] coefValues,
                            int[] coefIndexes)

add an objective function related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

Parameters:

objectiveName - holds the name of the objective. It may be empty.

isMin - holds whether the objective is minimization or not.

objectiveConstant - holds the objective constant. It may be zero.

coefValues - holds the nonzero coefficient values of the objective function.

coefIndexes - holds the nonzero coefficient variable indexes of the objective function.

Returns:

objectiveWeight holds the weight of the objective. It is usually 1 by default.

setConstraints

public boolean setConstraints(int numberConstraints,
                              java.lang.String[] constraintNames,
                              double[] constraintLbs,
                              double[] constraintUbs,
                              double[] constraintConstants)

Set the constraint related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

The constraint information contains all the information about the constraints except for the coefMatrix (AMatrix), which is to be set in the setCoefMatrix method.

Parameters:

numberConstraints - holds the number of constraints.

constraintNames - holds the names of all the constraints. It may be empty.

constraintLbs - holds the values of the lower bounds for the constraints. It may be empty.

constraintUbs - holds the values of the upper bounds for the constraints. It may be empty.

constraintConstants - holds the values of the constants for the constraints. It may be empty.

Returns:

whether constraint construction is successful.

addConstraint

public boolean addConstraint(java.lang.String constraintName,
                             double constraintLhs,
                             double constraintRhs,
                             double constraintConstant)

Add a constraint (or <con> element) to the existing constraints.

Parameters:

constraintName - holds the name of a constraint. It may be null.

constraintLhs - holds the value of the lower bounds for the constraint.

constraintRhs - holds the values of the upper bounds for the constraint.

constraintConstant - holds the values of the constant for the constraint.

Returns:

whether constraint addition is successful.

setLinearConstraintCoefficients

public boolean setLinearConstraintCoefficients(int numberOfValues,
                                               boolean isColumnMajor,
                                               double[] nonzeroValues,
                                               int[] nonzeroIndexes,
                                               int[] startIndexes)

Set the sparse coefficient matrix related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them. The sizes of all the input arrays should be consistent with constraint and variable number in the optimization problem.

The coefMatrix (AMatrix) stores all the information in the A part of Ax ~ b, i.e. the linear part of all constraints

Parameters:

numberOfValues - holds the number of specified values in the linear coefficient matrix.

isColumnMajor - holds the value of whether the coefMatrix (AMatrix) holding linear constraint data is stored by column. If false, the matrix is stored by row.

nonzeroValues - holds the values of the vector element value in coefMatrix (AMatrix), which contains nonzero elements.

nonzeroIndexes - holds the values of the vector element rowIdx or colIdx in coefMatrix (AMatrix). If the matrix is stored by column (row), rowIdx (colIdx) is the vector of row (column) indexes.

startIndexes - holds the values of the vector element start in coefMatrix (AMatrix), which points to the start of a column (row) of nonzero elements in coefMatrix (AMatrix).

Returns:

whether user wants to clear the arrays passed in to save memory if the arrays will still be referenced, a false value is to be returned.

setLinearConstraintCoefficients

public boolean setLinearConstraintCoefficients(int numberOfValues,
                                               boolean isColumnMajor,
                                               double[] nonzeroValues,
                                               int nonzeroValuesBegin,
                                               int nonzeroValuesEnd,
                                               int[] nonzeroIndexes,
                                               int nonzeroIndexesBegin,
                                               int nonzeroIndexesEnd,
                                               int[] startIndexes,
                                               int startIndexesBegin,
                                               int startIndexesEnd)

Set the sparse coefficient matrix related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them. The start and begin array indexes should be consistent with constraint and variable number in the optimization problem.

The coefMatrix (AMatrix) stores all the information in the A part of Ax ~ b, i.e. the linear part of all constraints

Parameters:

numberOfValues - holds the number of specified values in the linear coefficient matrix.

isColumnMajor - holds the value of whether the coefMatrix (AMatrix) holding linear constraint data is stored by column. If false, the matrix is stored by row.

nonzeroValues - holds the values of the vector element value in coefMatrix (AMatrix), which contains nonzero elements.

nonzeroValuesBegin - holds the begin index of the nonzeroValues array

nonzeroValuesEnd - holds the end index of the nonzeroValues array

nonzeroIndexes - holds the values of the vector element rowIdx or colIdx in coefMatrix (AMatrix). If the matrix is stored by column (row), rowIdx (colIdx) is the vector of row (column) indexes.

nonzeroIndexesBegin - holds the begin index of the nonzeroIndexes array

nonzeroIndexesEnd - holds the end index of the nonzeroIndexes array

startIndexes - holds the values of the vector element start in coefMatrix (AMatrix), which points to the start of a column (row) of nonzero elements in coefMatrix (AMatrix).

startIndexesBegin - holds the begin index of the startIndexes array

startIndexesEnd - holds the end index of the startIndexes array

Returns:

whether user wants to clear the arrays passed in to save memory if the arrays will still be referenced, a false value is to be returned.

setLinearConstraintCoefficients

public boolean setLinearConstraintCoefficients(int numberOfValues,
                                               boolean isColumnMajor,
                                               double[] nonzeroValues,
                                               int[] nonzeroValuesMultiplicity,
                                               double[] nonzeroValuesIncrement,
                                               int[] nonzeroIndexes,
                                               int[] nonzeroIndexesMultiplicity,
                                               int[] nonzeroIndexesIncrement,
                                               int[] startIndexes,
                                               int[] startIndexesMultiplicity,
                                               int[] startIndexesIncrement)

Set the compressed sparse coefficient matrix related elements with support for multiplicity and increment. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

The coefMatrix (AMatrix) stores all the information in the A part of Ax ~ b, i.e. the linear part of all constraints

Parameters:

numberOfValues - holds the number of specified values in the linear coefficient matrix.

isColumnMajor - holds the value of whether the coefMatrix (AMatrix) holding linear constraint data is stored by column. If false, the matrix is stored by row.

nonzeroValues - holds the values of the vector element value in coefMatrix (AMatrix), which contains nonzero elements.

nonzeroValuesMultiplicity - holds the multiplicity (repetition) of each nonzero value in the nonzeroValues array. If null, all multiplicities are 1.

nonzeroValuesIncrement - holds the increment value of each repetition of the nonzeroValues for "multiplicity" times. If null, all increments are 0.

nonzeroIndexes - holds the values of the vector element rowIdx or colIdx in coefMatrix (AMatrix). If the matrix is stored by column (row), rowIdx (colIdx) is the vector of row (column) indexes.

nonzeroIndexesMultiplicity - holds the multiplicity (repetition) of each nonzero index in the nonzeroIndexes array. If null, all multiplicities are 1.

nonzeroIndexesIncrement - holds the increment value of each repetition of the nonzeroIndexes for "multiplicity" times. If null, all increments are 0.

startIndexes - holds the values of the vector element start in coefMatrix (AMatrix), which points to the start of a column (row) of nonzero elements in coefMatrix (AMatrix).

startIndexesMultiplicity - holds the multiplicity (repetition) of each start index in the startIndexes array. If null, all multiplicities are 1.

startIndexesIncrement - holds the increment value of each repetition of the startIndexes for "multiplicity" times. If null, all increments are 0.

Returns:

whether user wants to clear the arrays passed in to save memory if the arrays will still be referenced, a false value is to be returned.

setLinearConstraintCoefficients

public boolean setLinearConstraintCoefficients(int numberOfValues,
                                               boolean isColumnMajor,
                                               double[] nonzeroValues,
                                               int[] nonzeroValuesMultiplicity,
                                               double[] nonzeroValuesIncrement,
                                               int nonzeroValuesBegin,
                                               int nonzeroValuesEnd,
                                               int[] nonzeroIndexes,
                                               int[] nonzeroIndexesMultiplicity,
                                               int[] nonzeroIndexesIncrement,
                                               int nonzeroIndexesBegin,
                                               int nonzeroIndexesEnd,
                                               int[] startIndexes,
                                               int[] startIndexesMultiplicity,
                                               int[] startIndexesIncrement,
                                               int startIndexesBegin,
                                               int startIndexesEnd)

Set the compressed sparse coefficient matrix related elements with support for multiplicity and increment. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

The coefMatrix (AMatrix) stores all the information in the A part of Ax ~ b, i.e. the linear part of all constraints

Parameters:

numberOfValues - holds the number of specified values in the linear coefficient matrix.

isColumnMajor - holds the value of whether the coefMatrix (AMatrix) holding linear constraint data is stored by column. If false, the matrix is stored by row.

nonzeroValues - holds the values of the vector element value in coefMatrix (AMatrix), which contains nonzero elements.

nonzeroValuesMultiplicity - holds the multiplicity (repetition) of each nonzero value in the nonzeroValues array. If null, all multiplicities are 1.

nonzeroValuesIncrement - holds the increment value of each repetition of the nonzeroValues for "multiplicity" times. If null, all increments are 0.

nonzeroValuesBegin - holds the begin index of the nonzeroValues array

nonzeroValuesEnd - holds the end index of the nonzeroValues array

nonzeroIndexes - holds the values of the vector element rowIdx or colIdx in coefMatrix (AMatrix). If the matrix is stored by column (row), rowIdx (colIdx) is the vector of row (column) indexes.

nonzeroIndexesMultiplicity - holds the multiplicity (repetition) of each nonzero index in the nonzeroIndexes array. If null, all multiplicities are 1.

nonzeroIndexesIncrement - holds the increment value of each repetition of the nonzeroIndexes for "multiplicity" times. If null, all increments are 0.

nonzeroIndexesBegin - holds the begin index of the nonzeroIndexes array

nonzeroIndexesEnd - holds the end index of the nonzeroIndexes array

startIndexes - holds the values of the vector element start in coefMatrix (AMatrix), which points to the start of a column (row) of nonzero elements in coefMatrix (AMatrix).

startIndexesMultiplicity - holds the multiplicity (repetition) of each start index in the startIndexes array. If null, all multiplicities are 1.

startIndexesIncrement - holds the increment value of each repetition of the startIndexes for "multiplicity" times. If null, all increments are 0.

startIndexesBegin - holds the begin index of the startIndexes array

startIndexesEnd - holds the end index of the startIndexes array

Returns:

whether user wants to clear the arrays passed in to save memory if the arrays will still be referenced, a false value is to be returned.

setQuadraticTerms

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

Set the quadratic coefficient terms related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them.

Parameters:

numberOfQuadraticTerms - 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. If null all coefficient values are 1.

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.

addNlNode

public boolean addNlNode(java.util.Vector tokenizedExpression,
                         java.lang.String type,
                         int rowIdx,
                         int start,
                         int end)

Add an nl node. It holds a nonlinear expression tree.

Parameters:

tokenizedExpression - holds the expression tokenized in a string vector 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.

type - whether the expression is in postfix, prefix or infix

rowIdx - holds the row number the nl node corresponds to. If rowIdx is negative, it corresponds to an objective.

start - holds the index of the tokenizedExpression to start processing.

end - holds the index of the tokenizedExpression to finish processing.

Returns:

whether nl node addition is successful.

addNlNode

public boolean addNlNode(OSExpressionTree expressionTree,
                         int rowIdx)

Add an nl node. It holds a nonlinear expression tree.

Parameters:

expressionTree - holds the os expression of the nl node.

rowIdx - holds the row number the nl node corresponds to. If rowIdx is negative, it corresponds to an objective.

Returns:

whether nl node addition is successful.

addSimulation

public boolean addSimulation(java.lang.String name,
                             java.lang.String uri,
                             OSsLWriter osslWriter)

Add a simulation node.

Parameters:

name - holds the name of the simulation

uri - holds the uri address of the simulation

osslWriter - holds the the root element of ossl.

Returns:

whether simulation node addition is successful.

addUserFunction

public boolean addUserFunction(java.lang.String name,
                               int numArg,
                               java.util.Vector tokenizedExpression,
                               java.lang.String type,
                               int start,
                               int end)

Add a userFunction node.

Parameters:

name - holds the name of the userFunction

numArg - holds the number of arguments of the user function

tokenizedExpression - holds the expression tokenized in a string vector 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.

type - whether the expression is in postfix, prefix or infix

start - holds the index of the tokenizedExpression to start processing.

end - holds the index of the tokenizedExpression to finish processing.

Returns:

whether userFunction node addition is successful.

addUserFunction

public boolean addUserFunction(java.lang.String name,
                               int numArg,
                               OSExpressionTree expressionTree)

Add a userFunction node.

Parameters:

name - holds the name of the userFunction

numArg - holds the number of arguments of the user function

expressionTree - holds the os expression of the nl node.

Returns:

whether userFunction node addition is successful.

setXMLData

public boolean setXMLData(org.w3c.dom.Element xmlDataElement)

Set the xmldData related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them. xmlDataElement can either have a root of <xmlData> or not. The method will add the root if the root is not there.

Parameters:

xmlDataElement - holds the xmlData element. xmlDataElement can either have a root of <xmlData> or not. The method will add the root if the root is not there.

Returns:

whether the xmldData construction is successful.

setXMLData

public boolean setXMLData(java.lang.String xmlDataString)

Set the xmldData related elements. If the elements (e.g. the required elements) are already there, it will reset the them. If the elements are not there (e.g. the optional elements), it will add them. xmlDataString can either have a root of <xmlData> or not. The method will add the root if the root is not there.

Parameters:

xmlDataString - holds the xmlData element. xmlDataElement can either have a root of <xmlData> or not. The method will add the root if the root is not there.

Returns:

whether the xmldData construction is successful.

main

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

main for test purposes.

Parameters:

argv - command line arguments.