OptInterface Class Methods
This section discusses the optimization methods for the OptInterface PeopleCode class. The methods are listed in alphabetical order.
Note: You can use the OptInterface class methods only within an application class that you extend from the OptBase application class, or within PeopleCode that you call from that application class. This ensures that the OptInterface PeopleCode runs only on the optimization engine.
Syntax
ActivateModel(ModelID, SolverSettingID)
Description
The ActivateModel method designates the specified model and solver setting as active. The model and the solver are initialized and populated with data from the current analytic instance.
Note: This method fails if the specified model (and by extension, one of its solver settings) is already active. If you want to activate a different solver setting for the same model, you must first deactivate the model.
See DeactivateModel.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify the name of the optimization model you want to activate. This must be the name of one of the models associated with the analytic type definition. |
SolverSettingID |
Specify the name of the solver setting you want to activate. This is the name you specified for the solver setting in the analytic type definition. |
Returns
This method returns a constant value. Valid values are:
Value |
Description |
---|---|
%OptInter_Success |
Returned if method succeeds. |
%OptInter_Fail |
Returned if the solver fails to solve the problem. |
Example
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
&result = &oi.ActivateModel("QE_PSA_MODEL", "abc");
Syntax
ActivateObjective(Model_Name, Objective_Name)
Description
Use the ActivateObjective method to activate the specified objective for an optimization model.
Parameters
Field or Control |
Definition |
---|---|
Model_Name |
Specify the name of the model. |
Objective_Name |
Specify the name of the objective. |
Returns
This method returns a constant value. Valid values are:
Value |
Description |
---|---|
%OptInter_Success |
Returned if method succeeds. |
%OptInter_Fail |
Returned if the solver fails to solve the problem. |
Syntax
DeactivateModel(ModelID)
Description
The DeactivateModel method detaches the solver from the specified model.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify the name of the optimization model you want to deactivate. This must be the name of one of the models associated with the analytic type definition. |
Returns
This method returns a constant value. Valid values are:
Value |
Description |
---|---|
%OptInter_Success |
Returned if method succeeds. |
%OptInter_Fail |
Returned if the solver fails to solve the problem. |
Example
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
&result = &oi.DeactivateModel("QE_PSA_MODEL");
Syntax
DumpMsgToLog(LogSeverity, Message)
Description
The DumpMsgToLog method writes the specified status message to the optimization engine log file, with the specified severity.
Parameters
Field or Control |
Definition |
---|---|
LogSeverity |
Specify the severity level of the message, as one of the following system constants:
|
Message |
Specify as a string the text of the log message. |
Returns
None.
Syntax
FindRowNum(&Record [, startrow [, endrow [, field_list]]])
Where field_list is a list of field names in the form:
[fieldname1 [, fieldname2]]...
Description
The FindRowNum method determines the row number of a row in the datacache rowset. You provide a record with key values, and this method finds the row with the same key values and returns its row number.
Parameters
Field or Control |
Definition |
---|---|
&Record |
Specify a record with the same structure as the records that comprise the rowset, with its key fields populated. |
startrow |
Specify as an integer the starting row number of the search. Specify 0 to search from the first row in the rowset. |
endrow |
Specify as an integer the ending row number of the search. Specify 0 to search through the last row in the rowset. |
fieldname |
Specify the name of a field in the input record which contains a value to be matched. You can specify one or more field names, in any order. Note: If you use this parameter, the fields specified here are used to search, instead of the record's key fields. Any value that doesn't correspond to a field name is ignored. |
Returns
The row number of the row containing the specified key values, or 0 if no row is found.
Example
The following example searches the whole scroll to find the partial key OPT_SITE:
Local Record &rec = CreateRecord(Scroll.OPT_TRANSCOST);
Local Optineterface &oi;
&rec.OPT_SITE.value = "New York";
int nRowNum = &oi.FindRowNum(&rec, 0, 0, "OPT_SITE");
The following example searches from row 5 to row 15 with the full key values New York and San Jose:
Local Record &rec = CreateRecord(Scroll.OPT_TRANSCOST);
Local Optineterface &oi;
&rec.OPT_SITE.value = "New York";
&rec.OPT_STORE.value = "San Jose";
int nRowNum = &oi.FindRowNum(&rec, 5, 15);
Syntax
GetSolution(ModelID, varArrayID, skipZero [, KeyFieldNames, KeyFieldValues [, &Solution]])
Description
The GetSolution method retrieves the model solution values generated by the Solve method.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify as a string the name of the optimization model for which you want the solution. This is the name used for the model definition in Application Designer. |
varArrayID |
Specify as a string the name of the variable array being optimized. Your application documentation should provide this name. |
skipZero |
Indicate whether solutions with a value of zero should be fetched. This parameter takes a Boolean value:
|
KeyFieldNames and KeyFieldValues |
Specify a set of key field names as an array of string and a set of key field values as an equal length array of ANY, with one key field value corresponding to each key field name. You use these arrays to restrict the set of returned solutions. Solutions are returned only for model variables with the specified key field values. Note: If you provide either of these arrays, you must provide both. You can include each parameter from the variable array at most only once. |
&Solution |
Specify a rowset to contain the solutions. |
Returns
This method returns a constant value. Valid values are:
Value |
Description |
---|---|
%OptInter_Success |
Returned if method succeeds. |
%OptInter_Fail |
Returned if the solver fails to solve the problem. |
Example
Local array of string &strArray;
Local array of any &valArray;
Local integer &index;
Local Rowset &rowSet;
Local integer &result;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local boolean &bSkipZero = True;
Local OptInterface &oi = CreateOptInterface();
&strArray = CreateArrayRept("", 0);
&valArray = CreateArrayAny();
&rowSet = CreateRowset(Record.QEOPT_VAL_X_WRK);
&strArray [1] = "EMPLID";
&valArray [1] = 1;
&strArray [2] = "ORDER_ID";
&valArray [2] = 23;
/* fetch only the part of the solution where EMPLID = 1 and ORDER_ID = 23 */
&result = &oi.GetSolution(&modelId, &varArrayName,
&bSkipZero, &strArray, &valArray, &rowSet);
Syntax
GetSolutionDetail(ModelID, SolutionType, Name, &Solution)
Description
The GetSolutionDetail method retrieves the model solution detail of the specified type generated by the Solve method. You can retrieve dual value, slack value, or reduced cost information.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify as a string the name of the optimization model for which you want the solution detail. This is the name used for the model definition in Application Designer. |
SolutionType |
Specify a system constant indicating the type of solution detail you want to retrieve. The value you specify here determines the content of the Name and &Solution parameters.
|
Name |
If you specified a SolutionType of %OPT_DUAL or %OPT_SLACK, specify here the name of a constraint block from the active model. If you specified a SolutionType of %OPT_RCOST, specify here the name of a variable array from the active model. |
&Solution |
Specify a rowset to contain the solution details. The rowset should have the same key fields as the constraint block or the variable array you specified with the Name parameter. |
Returns
This method returns a constant value. Valid values are:
Value |
Description |
---|---|
%OptInter_Success |
Returned if method succeeds. |
%OptInter_Fail |
Returned if solver fails to solve the problem. |
Example
Local Rowset &dual_rowset;
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local string &constrName = "Constraint_1";
/* fetch dual values for Contraint "Constraint_1"
in a rowset based on the QEOPT_C1_WRK record */
&dual_rowset = CreateRowset(Record.QEOPT_C1_WRK);
&result = &oi.GetSolutionDetail(&modelId, %Opt_Dual, &constrName, &dual_rowset);
Syntax
IsModelActive(ModelID)
Description
Use the IsModelActive method to determine if the model specified by ModelId is active before it is used.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify the model ID as a string. This is the name used for the model definition in Application Designer. |
Returns
A Boolean value: true if the model is active, false otherwise.
Syntax
RestoreBounds(modelID [,varArrayID])
Description
The RestoreBounds method returns the bounding values of the specified variable array or arrays to the current settings in the specified model.
If you previously called the SetVariableBounds method with the changeModelBounds parameter set to true for any variable or variable array, those bounding values still apply.
Parameters
Field or Control |
Definition |
---|---|
modelID |
Specify as a string the name of the optimization model for which you want to restore the bounding values. This is the name used for the model definition in Application Designer. |
varArrayID |
Specify as a string the name of a variable array for which you want to restore the bounding values. Your application documentation should provide this name. If you don't specify a variable array name, the bounding values are restored for all variable arrays in the specified model. |
Returns
%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.
Syntax
SetVariableBounds(modelID, varArrayID, boundType, lowerBound, upperBound, &keyRecord [, changeModelBounds])
Description
The SetVariableBounds method overrides the bounding values specified for a model variable array, or for a variable within the array.
Parameters
Field or Control |
Definition |
---|---|
modelID |
Specify as a string the name of the optimization model for which you want to override the bounding values. This is the name used for the model definition in Application Designer. |
varArrayID |
Specify as a string the name of the variable array being optimized. Your application documentation should provide this name. |
boundType |
Specify a system constant indicating which bounding values to override. The value you specify here determines how the lowerBound and upperBound parameters are applied to the specified model.
|
lowerBound |
Specify as a number the lower bound that should be applied to a variable or a variable array if the boundType parameter permits the override. You can also set this parameter to one of the following system constants: |
upperBound |
Specify as a number the upper bound that should be applied to a variable or a variable array if the boundType parameter permits the override. You can also set this parameter to one of the following system constants: |
&keyRecord |
Specify a record with the same key fields as the variable array being optimized. To override the bounding values specified for a single variable within the array, populate the record's key fields to specify the variable. To override the bounding values specified for the entire variable array, set all of the record's fields to a null value. Note: You must either provide values for all keys, or set them all to null values. |
changeModelBounds |
Specify a Boolean value:
|
Returns
%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.
Example
Local Record &rec;
Local integer &result;
Local OptInterface &oi = CreateOptInterface();
Local float &objval = 0.0;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local float &lb = 0.0;
Local float &ub = 0.0;
&rec = CreateRecord(Record.QEOPT_VAL_X_WRK);
&rec.QEOPT_RESINDEX.Value = 1;
&rec.QEOPT_SOLINDEX.Value = 2;
&rec.QEOPT_TIMEINDEX.Value = 3;
&result = &oi.SetVariableBounds(&modelId, &varArrayName,
%Opt_Upper_Bound, &lb, &ub, &rec, False);
Syntax
SetVariableType(modelID, varArrayID, varType)
Description
Use the SetVariableType method to change the data type of a model variable array.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify as a string the name of the optimization model for which you want to change the variable type. This must be the name of one of the models associated with the analytic type definition. |
varArrayID |
Specify as a string the name of the variable array for which you want to change the variable type. Your application documentation should provide this name. |
varType |
Specify one of the following system constants representing the new variable type:
|
Returns
%OptInter_Success if the method succeeds, %OptInter_Fail otherwise.
Example
Local OptInterface &oi = CreateOptInterface();
Local string &varArrayName = "X";
Local integer &result;
&result = &oi.SetVariableType("QE_PSA_MODEL", &varArrayName, %Opt_Var_Bin);
If (&result <> %OptInter_Success) Then
&oi.DumpMsgToLog(%Severity_Status, "Failed to change variable type ");
End-If;
Syntax
Solve(modelID, SolutionType [, &objValue [, name-value_pairs]])
Where name-value_pairs is a list of solver setting parameter values in the form:
[parmname1, parmvalue1 [, parmname2, parmvalue2]]...
Description
The Solve method solves the specified model using the currently active solver settings, and provides an objective value as the solution output. You can override the solver setting parameters. The returned solution status is a predefined system constant.
Parameters
Field or Control |
Definition |
---|---|
ModelID |
Specify as a string the name of the optimization model you want to solve. This is the name used for the model definition in Application Designer. |
SolutionType |
Specify a system constant indicating the type of solution detail you want the model to be solved for.
You can also combine any or all of these system constants, by connecting them with a plus sign (+), for example: %OPT_DUAL + %OPT_RCOST. |
&objValue |
Specify a reference to a variable of type float. This variable contains the output objective value produced by the solver upon successfully solving the specified optimization model. |
parmname and parmvalue |
Specify a solver setting parameter ID and value to override the original value you specified for the solver setting in the analytic type definition. You can override any or all of the solver setting parameter values. |
Returns
One of the following system constants:
%OptInter_Fail: The solver fails to solve the problem.
%Opt_Optimal: The solution is optimal.
%Opt_Infeasible: The solution is infeasible.
%Opt_Unbounded: The solution is unbounded.
%Opt_Timeup: The solver reached the time limit specified in the solver setting.
%Opt_Iterlimit: The solver reached the limit on the number of iterations specified in the solver setting.
%Opt_LP_Max_Sols: The solver generated maximum number of solutions without improvement.
%Opt_Idle: The solution shows no improvement in a specified time limit.
%Opt_Unknown: The solver status is unknown.
%Opt_MIP_NumSolutions: The specified number of solutions corresponding to an MIP solver reached.
%Opt_MIP_NumNodes: The specified number of nodes corresponding to an MIP solver reached.
%Opt_Aborted: The solver aborted.
%Opt_User_Exit: A user exit was encountered.
%Opt_First_LP_NoOpt: While solving an MIP, the first LP solution obtained was not optimal.
Example
Following is an example of the basic use of the Solve method:
Local OptInterface &oi = CreateOptInterface();
Local float &objval = 0.0;
Local integer &result;
Local string &modelId = "QE_PSA_MODEL";
Local string &varArrayName = "X";
Local integer &solType;
&solType = %Opt_RCost + %Opt_Dual + %Opt_Slack;
/* Solve the problem */
&result = &oi.Solve("QE_PSA_MODEL", &solType, &objval);
If & result = %Opt_Optimal Then
&oi.DumpMsgToLog(%Severity_Warn, " Solution Status = " Optimal !!!");
Else
&oi.DumpMsgToLog(%Severity_Warn, " Solution Status = " | &result );
End-If;
Following is an example of a solver setting parameter override:
Local OptInterface &oi = CreateOptInterface();
Local float &objval = 0.0;
Local integer &result;
/* This overrides the solver setting for MPS_Filename and generates
an MPS file called myfile.mps instead of the name specified
in the current solver setting parameter. */
&result = &oi.Solve("QE_PSA_MODEL", %Opt_Primal, &objval, "MPS_FileName",
"myfile");