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: %Severity_Fatal %Severity_Status %Severity_Error %Severity_Warn %Severity_Info %Severity_Trace1 %Severity_Trace2
`Message`	Specify as a string the text of the log message.

Field or Control

Definition

LogSeverity

Specify the severity level of the message, as one of the following system constants:

%Severity_Fatal
%Severity_Status
%Severity_Error
%Severity_Warn
%Severity_Info
%Severity_Trace1
%Severity_Trace2

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: True: Don't fetch solutions with a zero value. This can increase the performance of the GetSolution method if zero values aren't meaningful. False: Do fetch solutions with a zero 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. %OPT_DUAL: Retrieve the dual value attributes of the specified constraint block. %OPT_SLACK: Retrieve the slack value attributes of the specified constraint block. %OPT_RCOST: Retrieve the reduced cost attributes of the specified variable array.
`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. %OPT_LOWER_BOUND: Override only the lower bound as specified by the `lowerBound` parameter. The `upperBound` parameter is ignored. %OPT_UPPER_BOUND: Override only the upper bound as specified by the `upperBound` parameter. The `lowerBound` parameter is ignored. %OPT_BOUND_BOTH: Override both the lower bound and the upper bound as specified by the `lowerBound` and `upperBound` parameters, respectively.
`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: true: Indicates that the specified model should be updated in memory to reflect the specified variable bounds. Any analytic instance that invokes this model from the active optimization engine is affected by these settings, which are propagated to the solver in memory. This is the default value if you omit this parameter. false: Indicates that the specified model should not be updated in memory, and that the specified variable bounds apply only to the next time the Solve method is called.

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: %Opt_Var_Cont: Represents a continuous variable type, which can be any floating point value. %Opt_Var_Bin: Represents a binary variable type, for which the value can be only 0 or 1. %Opt_Var_Int: Represents an integer variable type, which can be any integer.

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:

%Opt_Var_Cont: Represents a continuous variable type, which can be any floating point value.
%Opt_Var_Bin: Represents a binary variable type, for which the value can be only 0 or 1.
%Opt_Var_Int: Represents an integer variable type, which can be any integer.

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. %OPT_DUAL: Generate dual value attributes. %OPT_SLACK: Generate slack value attributes. %OPT_RCOST: Generate reduced cost attributes. 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. See Configuring Models for Optimization.

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");