Designing Analytic Type Definitions

This chapter provides overviews of analytic type definitions and optimization application record design and discusses how to:

Create and build optimization records.
Create analytic type definitions.
Run the optimization system audit.
Change existing analytic type definitions.
Administer optimization engines.
Administer optimization tables.
Update solver licenses.

Understanding Analytic Type Definitions

An analytic type definition groups the optimization application records, the optimization transactions, and the OPI together as one entity. The optimization application records contain the data stored in the database. The data is populated into memory in the optimization engine. The optimization transactions define the interface between the application server and the OPI, which performs the optimization computation. Use PeopleSoft Application Designer to create the analytic type definition for an optimization application.

An Optimization Problem Example

To illustrate the steps of creating an optimization-based application, consider the following example: Create an optimal exercise schedule that makes use of exercise machine availability and satisfies individuals’ exercise preferences. To create an optimization application for this problem, you need input data about:

Exercises that burn a set number of calories per minute.
People who know how long they want to exercise and how many calories they want to burn.

The goal of your application is to generate a list containing an exercise and the duration of exercise appropriate to each person, based on the input data.

To implement the analytic type definition for this example, you would:

Create and populate a set of records containing the input data about the exercises and the participants.

These are the optimization application records for this application.
Define a set of optimization transactions and their parameters that, when implemented, process the optimization application records to achieve the goal.

Note. For this example, assume that an OPI (QEOPT.DLL) already exists that implements these transactions.

Understanding Optimization Application Record Design

This section discusses:

Optimization application records.
Scenario management.

Optimization Application Records

You use PeopleSoft Application Designer to design optimization application records to contain source data, result data, and other data. You also decide how the optimization engine uses these records for synchronization. For each record that you create, decide:

Which data fields the record should contain.

Among other data, these records contain the data from the PeopleSoft application database that is used in the optimization process.
How the optimization engine uses the record for synchronization.

If the record is read once, the optimization engine reads this data during the initial load only. If the record is readable, the optimization engine checks for updates with every optimization transaction. If the record is writable, the optimization engine is allowed to modify the data in the database. All records except read-once records must have a VERSION field.
Whether the record should be scenario-managed.

A record should be scenario-managed if it contains data pertaining to multiple analytic instances. Such records must have a PROBINST key field, which the optimization engine uses as an additional key for storing and retrieving multiple solutions.

Scenario Management

In PeopleSoft Optimization Framework, scenario management is the mechanism to manage different source and result data sets using the same tables. A set of source data and associated result data is called an analytic instance. You can break down large optimization problems into smaller, more manageable problems (or analytic instances) that can each be solved independently. Individual analytic instances can share common data.

This concept can be extended to what-if scenarios to plan for potential business situations. Separate analytic instances can be created with what-if data and solved using optimization separately, without fear of affecting live data.

In terms of the exercise example, any number of people might want exercise schedules using the optimization application. Exercise goal data and the optimization-generated exercise schedule data are unique to each person. However, different people share the same set of exercise machines. In this case, it is logical to treat the generation of an individual person’s exercise schedule as a separate analytic instance.

In the exercise example, you would mark the data that is specific to each person (such as exercise goals and exercise schedules) as scenario-managed, and the data that is shared by all people (such as exercise machines) as non-scenario-managed. All scenario-managed records must include the PROBINST field as part of the primary key. This 20-character field identifies data specific to an analytic instance. During runtime, the optimization engine loads data for scenario-managed records based on the user-specified value for the PROBINST field. At any moment, the optimization engine contains data for only one analytic instance.

The following record, QE_ROSM_BIODATA, contains the name of a person who exercises, and physical data about the person. This record is read once and scenario-managed. Notice the use of the PROBINST field.

QE_ROSM_BIODATA record

Creating and Building Optimization Records

To create and build optimization application records:

Create the optimization application record definitions using PeopleSoft Application Designer.
For every optimization application record that is readable, create an optimization delete record by cloning the optimization application record.

Clone the record by performing a Save As operation on the optimization application record and renaming the optimization delete record to be similar to the original optimization application record. Use a naming convention for all optimization delete records. For example, the optimization delete record for the record QE_R_HOLIDAYS might be named QE_R_HOLIDAYDEL.

Alternately, use a sub-record definition that's shared by the optimization application record and the delete record.

Note. It is very important to keep the optimization application record and its associated optimization delete record in sync with each other.
For every optimization application record that is readable, associate that record with its optimization delete record.
1. Open the optimization application record.
2. Select File, Definition Properties.
3. Select the Use tab in the Record Properties dialog box.
4. Enter the name of the optimization delete record in the Optimization Delete Record field.
Open (or create) a project and insert all the optimization application records and optimization delete records into the project.
Create the tables from these records.
1. Select Build, Project.
  
  The Build dialog box appears, showing the optimization application records and optimization delete records in the project.
2. Select the Create Tables check box, and make sure that the Create Triggers check box is clear.
3. Click the Build button.
Create optimization database triggers from these records.
1. Select Build, Project.
  
  The Build page appears, showing the optimization application records and optimization delete records in the project.
2. Select the Create Triggers check box.
3. Click the Build button.

Note. Optimization delete records may be used by several analytic types. When a record is deleted from an analytic type, the associated delete record is not needed if this record is not used elsewhere.

Creating Analytic Type Definitions

This section discusses how to:

Define an analytic type.
Configure analytic type records.
Configure analytic type models.
Configure analytic type transactions.

Note. When working with analytic type definitions, you can use the typical drag-and-drop features offered by PeopleSoft Application Designer. For example, you can drag record definitions and drop them into the analytic type record list, which is maintained on the Record tab of the analytic type definition.

Defining an Analytic Type

In PeopleSoft Application Designer, select File, New, Analytic Type. A new analytic type definition appears, containing tabs for transactions, records, and models. The definition combines these items with an OPI to form the basis of an optimization application.

To complete the analytic type definition, you'll find it most useful to configure the analytic type properties, then insert and configure the records, the optimization models, and the transactions, in that order.

Access the Analytic Type Properties dialog box, and select the Attributes tab.

PeopleCode Plugin

Select to indicate that the analytic type should use the Optimization PeopleCode plug-in. Only select this check box if the analytic type is to be used with optimization. If the analytic type is to be used with the analytic calculation engine, do not select this check box.

Psopidplugin is automatically entered in the Plugin Lib Name field, which is read-only.

If you use this plug-in, you must also use the Package and Class fields to specify an application class that's been developed to adapt the Optimization PeopleCode plug-in to your optimization application.

See Invoking the Optimization PeopleCode Plug-In.

Plugin Lib Name (plug-in library name)

Enter the name of the OPI library. Enter only the portion of the name that is specific to this library. Ignore operating system-specific prefixes (such as lib) and suffixes (such as .dll). In the exercise example, on Microsoft Windows, the library is libqeopt.dll. You would enter only qeopt here.

If you selected the PeopleCode Plugin check box, this field contains the value psopidplugin, and is read-only.

Plugin Lib Version (plug-in library version)

Enter the application release version of the plug-in. The optimization engine uses this to confirm that the correct version of the plug-in library is used at runtime.

Message Set ID

Enter the message set ID in the message catalog containing the messages for the optimization application. The OPI uses this to access messages from the message catalog.

Plugin Application Class — Package

If you selected the PeopleCode Plugin check box, you must specify here the application package containing the application class to use with the Optimization PeopleCode plug-in for your optimization application.

Plugin Application Class — Class

If you selected the PeopleCode Plugin check box, you must specify here the application class containing the optimization PeopleCode program to use with the Optimization PeopleCode plug-in for your optimization application. This class must be a subclass of the PT_OPT_BASE:OptBase application class.

AnalyticInstance Application Class — Package

If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the application package name that should be associated with this analytic type, that contains the functionality to be used with the analytic type when it is created, deleted or copied.

See Creating, Deleting, and Copying Analytic Instances.

AnalyticInstance Application Class — Class

If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the name of the class in the application package that contains the Create, Copy and Delete classes.

Configuring Analytic Type Records

In the analytic type definition, select the Records tab, then select Insert, Record. The Analytic Type Record Property dialog box appears.

Note. You can access the properties of an existing analytic type record by right-clicking the record and selecting Analytic Type Record Properties.

Record Name	Select the record to use in the analytic type definition. Note. If you select a derived/work record, keep in mind that its scope in optimization PeopleCode is different than in other PeopleCode. When you use the CreateOptEngine or CreateAnalyticInstance function, each derived/work record is instantiated at level zero of the analytic instance rowset. The record persists, and you can continuously modify its data across multiple transactions, until you shut down the optimization engine using the ShutDown method.
Synchronization Order	Indicates the order in which the optimization engine reads the optimization application records. If a record has dependencies on another record, the dependent record should be read later. For example, the QE_RSM_EXERTGT record (synchronization order number is 4) depends on data in the QE_RO_MACH_CALS record (synchronization order number is 1). This order is determined by the application logic.
Read Once	Select to have the record read only once during the initial load of the analytic instance into the optimization engine. You cannot select Writeable if this check box is selected. The optimization engine reads these records only once during the initial data load. It is assumed that the data in these records does not change (or the user doesn’t care if it changes) from the initial load of the optimization engine until shutdown. For the exercise machine problem, you might create a record that contains the name of an exercise machine and the number of calories one can burn on it. This information only needs to be read once by the optimization engine. Furthermore, the information will not change, so a VERSION field is not required.
Readable	Select to have the record checked for updates by the optimization engine with every optimization transaction. Readable records, besides being loaded during the initial load, are checked for updates by the optimization engine at the beginning of every optimization transaction. For every readable optimization application record, you must also create a corresponding optimization delete record and associate the readable record with the delete record. This process is explained later in this chapter. Note. It is important to keep the analytic type records in sync with the optimization delete records. For the exercise machine example, an appropriate readable record contains the name of a person who exercises, the start time and duration of the exercise, and the number of calories that the person wants to burn. This record is readable and scenario-managed. It has a VERSION field and a PROBINST field that contains the name of the person. Because this is pure source data, this data is not writable.
Writable	Select to enable the optimization engine to modify rows for this record. A record can be both readable and writable. It's more common for records to be readable and writable instead of just writable. A writable record contains result data from the optimization engine. For the exercise machine example, the system calculates this data every time you request an exercise summary. For this reason, it is purely writable.
Scenario-Managed	Select to indicate that the record will contain data pertaining to multiple analytic instances. Note. Scenario-managed records must have a PROBINST key field. See Scenario Management.
Callback	Select to enable the optimization engine to update its working data whenever this record changes. Your analytic type definition might include a record that you expect to change during the course of the optimization. If you want those changes to be taken into account by the optimization, you can define it as a callback record, so you can use provided PeopleCode callback methods to dynamically propagate those changes to the optimization's derived data structures. A callback record must be readable and writable. Warning! If you select this check box for a record, you must ensure that you override all of the abstract callback placeholder methods that are defined in the extended PT_OPT_BASE:OptBase application class, even if it contains only a Return statement. Otherwise your Optimization PeopleCode plug-in will fail. See OptBase Application Class.
Record Fields	In the Record Fields list, select the fields in this record that need to be read into the optimization engine. These are the fields that the OPI can access. Key fields and the VERSION field (if it exists) are always selected automatically. To conserve memory used by the optimization engine, select only the necessary fields.

Configuring Models for Optimization

You need to specify and configure analytic type models for optimization only if both of the following are true:

You selected PeopleCode Plugin in the analytic type properties, indicating that your analytic type definition should use the Optimization PeopleCode plug-in.
Your application documentation indicates that an optimization model is necessary for the optimization application you're developing.

In the analytic type definition, select the Models tab, then select Insert, Optimization Model. The Analytic Type Optimization Model Property dialog box appears.

Note. Your application documentation discusses which models to specify, and what configuration settings to make for each model. You can access the properties of an existing analytic type model by right-clicking the model and selecting Analytic Type Model Properties.

Model Name

Select the optimization model required to implement an optimization application with this analytic type.

Solver Settings

A solver setting is a collection of solver parameters with default values that define a particular solver behavior suitable for the optimization model. Specify one or more solver settings to make available to your optimization application, including:

Solver Setting.

Enter the name of the solver setting.
Solver Type.

Select the solver type: LP (linear programming), MIP (mixed integer programming), or LPMIP (both).
Active.

Select the active solver setting — only one solver setting can be active at a time.

Configuring Solver Parameters

For each solver setting you specify, you can configure one or more solver parameters.

Double-click on a solver setting to access the Analytic Type Optimization Solver Property dialog box. This dialog box has a grid with two columns: Parameter ID and Parameter Value.

Each solver type has a different set of available parameters, and each parameter has a default value. When you select a solver parameter from the Parameter ID dropdown list, its default value appears in the Parameter Value cell, and a new row appears for adding another parameter. Your application documentation discusses which parameters to specify for each solver setting, and what value to specify for each parameter.

Creating Mathematical Formulation Files

In addition to the analytic server log files, you can also create a mathematical formulation file for debugging. This file is written in either MPS or LP format and maybe requested for technical debugging purpose. The file type is generally LP, however, if the system cannot create an LP file it creates an MPS file. The filename is either AnalyticType_AnalyticInst.LP or AnalyticType_AnalyticInst.MPS, with AnalyticType being the name of the analytic type and AnalyticInst being the name of the analytic instance ID. This file is generally written to the same directory as the application server log. Also, this directory can be configured in the application server configuration file.

You indicate whether or not to write this file or not by specifying a solver parameter.

Double-click on a solver setting to access the Analytic Type Optimization Solver Property dialog box. This dialog box has a grid with two columns: Parameter ID and Parameter Value.

Select WriteMPS for Parameter ID. In the Parameter Value column, specify a 1 to write the file or a 0 to not write the file.

Associating Analytic Types with Analytic Models

For PeopleSoft Analytic Calculation Engine, you only need to associate an analytic type with an analytic mode.

In the analytic type definition, select the Models tab, then select Insert, Analytic Model.

In the Analytic Type Analytic Model Property dialog box, select the name of the analytic model that you want to associate with the analytic type. If you specify to add all the record and fields used in the model, they are automatically added to the records on the Records tab.

Configuring Analytic Type Transactions

In the analytic type definition, select the Transactions tab, then select Insert, Transaction. The Analytic Type Transaction Property dialog box appears.

Note. You can access the properties of an existing analytic type transaction by right-clicking the transaction and selecting Analytic Type Transaction Properties.

Transaction Name

Enter the case-sensitive name of the transaction.

If the PeopleCode Plugin check box is selected in the analytic type properties, this value must match the name of a method defined in the application class you specified for this analytic type.

If the PeopleCode Plugin check box is not selected in the analytic type properties, this value must match the name of a service defined in the OPI that you selected in the analytic type properties.

The transaction name you specify must be distinct within an analytic type.

For the exercise machine example, three transactions are needed. The QEOPT.DLL OPI implements these transactions:

SOLVE solves the exercise machine problem.
GET_SUMMARY produces a summary of exercises for a person.
IS_MACHINE_AVAILABLE returns whether an exercise machine is available for a specified time.

The transaction name can contain up to 30 characters.

See OptBase Application Class.

Lock Flag

Enter this flag to prevent changes to the optimization application tables while this transaction runs. Typically, this flag should be set for extremely fast but critical transactions where data integrity is crucial. In the exercise planning example, optimization transactions do not need the lock flag.

Important! The lock flag can hamper performance, so use it with caution.

Parameter Attributes

Each transaction can have any number of parameters.

If the application class method corresponding to this transaction has parameters, you must define a row in this grid with equivalent attributes for each of the parameters.

Name	Enter the name of the parameter. The name must match the transaction parameter name defined in the OPI, or the equivalent method parameter defined in the application class you specified for this analytic type. The transaction parameter name can contain up to 20 characters, and it must be distinct within an analytic type.
Type	Select the parameter type (String, Integer, Double, Date, DateTime, Time, or arrays of these types, or Record Array). The type must match the transaction parameter type defined in the OPI, or the equivalent method parameter type defined in the application class you specified for this analytic type. Note. Do not pass an array of type Integer as a transaction parameter. Use an array of type Number instead.
Input/Output	Select Input, Output, or Both.
Attributes	Select Required, Optional, or Default (the parameter has a default value). This is not applicable to output parameters. Note. If an input parameter is required, it must be supplied when you use either the RunSynch or RunAsynch PeopleCode methods.
Value	If the Attributes field is set to Default, enter a default value for this parameter. If the type is Record Array, enter the name of the record. Otherwise, leave this blank.

Running the Optimization System Audit

After you have created the analytic type definition, run SYSAUDIT with the optimization options selected. This ensures that the definition is valid and consistent.

To run the optimization system audit:

From the PeopleTools Utilities menu, select Audit, Perform System Audit.
Enter a run control ID.
On the System Audit page, select Audit Optimization Integrity, and click Run.
On the Process Scheduler Request page, ensure that the System Audit check box is selected, select a server name, and click OK.
When the System Audit page reappears, click Process Monitor (to the left of the Run button).
On the Process List page, at the end of the line for SYSAUDIT, click Details.
On the Process Detail page, click View Log/Trace.
On the View Log/Trace page, click the SYSAUDIT_XX file name.

This file contains the audit report for your optimization.

Changing Existing Analytic Type Definitions

This section discusses how to change:

Optimization application records.
Optimization transactions.

Changing Optimization Application Records

To change optimization application records in an analytic type definition:

Shut down all the running optimization engines that use this analytic type definition.
Shut down other optimization engines if record definitions are being shared by other analytic type definitions.
Delete all existing analytic instances using the DeleteOptProbInst PeopleCode function.

See DeleteOptProbInst.
Empty the optimization application tables.
Make record definition changes and build the records in PeopleSoft Application Designer.

See Creating and Building Optimization Records.
Open the analytic type in PeopleSoft Application Designer, insert any new records or make appropriate changes to reflect changed record definitions, and save the analytic type.

Run SYSAUDIT with the optimization options selected.

Skip the steps about inserting transactions.
Change the OPI to reflect the changes to optimization application records.

If the records do not match the plug-in, the program will fail.
Call the InsertOptProbInst PeopleCode function to recreate analytic instances.

See InsertOptProbInst.

Changing Optimization Transactions

To change optimization transactions in an analytic type definition:

Shut down all the running optimization engines that use the analytic type definition.
Open the analytic type definition in PeopleSoft Application Designer, insert any new transactions or make appropriate changes to existing ones, and save the analytic type.

Skip the steps about inserting records.
Change the OPI to reflect the changes to optimization transactions.
Change optimization PeopleCode to reflect the changes (add, remove, and update parameters).

Administering Optimization Engines

An optimization engine is an instance of an analytic server.

See Managing Analytic Servers.

Setting Up Integration Broker

Before you can use lights-out mode and other optimization features, you must first configure PeopleSoft Integration Broker for basic messaging.

See Enterprise PeopleTools 8.49 PeopleBook: PeopleSoft Integration Broker.

The only PeopleSoft Integration Broker elements specific to optimization engine administration are two transactions delivered with your PeopleSoft application. One transaction is type InSync, the other is type OutSync, and both use the OPT_CALL message. Ensure that they're both active on the Transactions page of the default local node definition.

See Adding and Configuring Nodes.

Updating Solver Licenses

Use the Administer license page to update a solver software license. PeopleSoft Optimization Framework uses third-party solver software. In some cases, the solver software is activated by a license.

Note. Currently, no optimization application requires updating the solver license. You should update solver licenses only on instructions from PeopleSoft.

To update solver licenses:

In a browser, select PeopleTools, Utilities, Optimization, Solver Licenses.
Enter an optimization solver type, such as LP/MIP.

The optimization engine identifies the third-party solver software by its solver type.
On the Administer license page, enter the new license code in the Encrypted License Code field.

PeopleCode Plugin	Select to indicate that the analytic type should use the Optimization PeopleCode plug-in. Only select this check box if the analytic type is to be used with optimization. If the analytic type is to be used with the analytic calculation engine, do not select this check box. Psopidplugin is automatically entered in the Plugin Lib Name field, which is read-only. If you use this plug-in, you must also use the Package and Class fields to specify an application class that's been developed to adapt the Optimization PeopleCode plug-in to your optimization application. See Invoking the Optimization PeopleCode Plug-In.
Plugin Lib Name (plug-in library name)	Enter the name of the OPI library. Enter only the portion of the name that is specific to this library. Ignore operating system-specific prefixes (such as lib) and suffixes (such as .dll). In the exercise example, on Microsoft Windows, the library is libqeopt.dll. You would enter only qeopt here. If you selected the PeopleCode Plugin check box, this field contains the value psopidplugin, and is read-only.
Plugin Lib Version (plug-in library version)	Enter the application release version of the plug-in. The optimization engine uses this to confirm that the correct version of the plug-in library is used at runtime.
Message Set ID	Enter the message set ID in the message catalog containing the messages for the optimization application. The OPI uses this to access messages from the message catalog.
Plugin Application Class — Package	If you selected the PeopleCode Plugin check box, you must specify here the application package containing the application class to use with the Optimization PeopleCode plug-in for your optimization application.
Plugin Application Class — Class	If you selected the PeopleCode Plugin check box, you must specify here the application class containing the optimization PeopleCode program to use with the Optimization PeopleCode plug-in for your optimization application. This class must be a subclass of the PT_OPT_BASE:OptBase application class.
AnalyticInstance Application Class — Package	If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the application package name that should be associated with this analytic type, that contains the functionality to be used with the analytic type when it is created, deleted or copied. See Creating, Deleting, and Copying Analytic Instances.
AnalyticInstance Application Class — Class	If this analytic type is to be used with the PeopleSoft Analytic Calculation Engine, specify the name of the class in the application package that contains the Create, Copy and Delete classes.