Custom scenario provider and parallel execution sample details

Running this sample

To generate random data for a specific number of scenarios, create a simulation that uses the RandomData format for the usage scenarios.

Create the Random Simulation simulation:

1. If you signed out, sign in again to Decision Center using rtsConfig.

2. Click the Compose tab, select Simulation, and then click OK.

3. In Step 1: Properties, enter Random Simulation as the name of the simulation, and click Next.

4. In Step 2: Rules tested, click Next to test all the rules of the current project.

5. In Step 3: Scenarios, select RandomData from the Format list.

   The content of the Scenarios step changes to reflect the information required when using the RandomData format.

6. Enter 50 in the Number of scenarios field.

   This value sets the number of scenarios to use in the simulation.

7. Click Finish to create the simulation.

   Decision Center displays the details of the new simulation.

Run the Random Simulation simulation:

1. Click Run in the toolbar.

2. Select Sample as the server.

3. Click Run to run the simulation.

   The run takes a few seconds to complete.

The simulation uses the RandomData scenario provider to run 50 scenarios created from random input data.

The report displays a KPI that indicates the overall performance of the simulation:

Loan Approval Rate 26.666668 % for 15 borrowers with income < 60000
Simulation on 50 scenarios

From the 50 scenarios, 15 potential borrowers are found to have an income less than 60,000. The value of 60,000 is defined in the KPI. From the list of 15, only 4 are granted a loan based on the rules in the loan validation project. The loan success rate is 26.667%.

Create a History Simulation simulation:

Now, create a simulation that reads data from a database.

1. Click the Compose tab, select Simulation, and then click OK.

2. In Step 1: Properties, enter History Simulation as the name of the simulation, and click Next.

3. In Step 2: Rules tested, click Next.

4. Click Step 3: Scenarios, select HistoricalData from the Format list.

   The content of the Scenarios step changes to reflect the information required when using the HistoricalData format.

5. Enter 60000 in the Maximum income field.

   This value is used to query the database and make a preliminary selection of scenarios. The KPI that is used also tests for a maximum income of 60,000.

6. Click Finish to create the simulation.

   Decision Center displays the details of the new simulation.

Run the History Simulation simulation:

1. Click Run in the toolbar.

2. Select Sample as the server.

3. Click Run to run the simulation.

   The run takes a few seconds to complete.

   The simulation uses the HistoricalData scenario provider, which queries a database of historical data. From the database, 30 potential borrowers are found to have an income less than 60,000.

   The Decision Center displays the KPI results, which are also stored in the database.

   Key Performance Indicators

   Loan Approval Rate 30.000002 % for 30 borrowers with income < 60000 Simulation on 30 scenarios

   The result of running the rules in the loan validation project against these 30 borrowers is that only 9 of them are given a loan. The loan success rate is 30%.

4. Click the Report button to obtain a report with diagrams that represent the accepted and rejected loan requests.

   The run takes a few moments.

   Note: Due to issues with some web browsers, you must use Internet Explorer to obtain the report.

Create two simulations to demonstrate parallel execution:

To demonstrate parallel execution a different database is used, which contains 100,000 entries. This database contains similar scenarios to the HistoricalData database, but there are many more scenarios (rows). Parallel execution reduces the time it takes to run a simulation. Using a database with many records is a better demonstration of how a parallel scenario provider works.

1. Click the Compose tab, select Simulation, and then click OK.

2. In Step 1: Properties, enter Parallel One Part as the name of the simulation, and click Next.

3. In Step 2: Rules tested, click Next.

4. Click Step 3: Scenarios, select ParallelHistoricalData from the Format list.

   The content of the Scenarios step changes to reflect the information required when using the ParallelHistoricalData format.

5. Enter 90000 in the Maximum income field.

   This value is used to query the database and make a preliminary selection of scenarios. It shows how to pass a parameter from Decision Center to the scenario provider. The KPI is the same one that is used for the History Simulation, which tests for a maximum income of 60,000.

6. Enter 1 in the Number of parts field.

7. Click Finish to create the simulation.

   Decision Center displays the details of the new simulation.

8. Click Copy in the menu bar.
9. Click OK to copy the file to the same location.
10. Select the check box next to Copy of Parallel One Part, and click Edit.
11. Enter Parallel Four Parts in the Name field, and click Next.
12. Click Next and enter 4 in the Number of parts field, then click Finish to save the simulation.

    Decision Center displays the details of the new simulation.

Run the Parallel One Part and Parallel Four Parts simulations:

1. Click the Explore tab, and click Simulations.

   Decision Center displays all of the simulations.

2. Select the check box next to Parallel One Part, and click the icon named Run this element.

3. Select Sample as the server, and unselect Create an Excel file for the results.

4. Click Run to run the simulation.

   The simulation is started.

5. Click Run in background.

6. Click the Explore tab, and click Simulations.

7. Select the check box next to Parallel Four Parts, and click the icon named Run this element.

8. Select Sample as the server, and unselect Create an Excel file for the results.

9. Click Run to run the simulation.

10. Click Run in background.

11. Click the Analyze tab, to see the two simulations running.

    The simulation with four parts completes before the simulation with one part.

12. Click get report for Parallel Four Parts when the link is active.

    In the KPI report, the results show that the simulation completed in 33 seconds.

    Key Performance Indicators

    Loan Approval Rate 33.333336 % for 30000 borrowers with income < 60000 Simulation on 80000 scenarios Total Execution Time 33304 ms

    The simulation executes in four threads using the ParallelHistoricalData scenario provider. The provider queries a database that includes 100,000 scenarios, and initially selects the scenarios (80,000) corresponding to borrowers with an income less than 90,000. From these 80,000 scenarios, the KPI results show that only 30,000 potential borrowers are found to have an income less than the KPI required threshold of 60,000. The result of running the rules in the loan validation project against these 30,000 borrowers is that 10,000 of them are given the loan. The loan success rate is 33.33%.

13. Click Analyze > View Running Test Suites / Simulations.
14. Click get report for Parallel One Part when the link is active.
15. Click Compare with in the menu bar.
16. Select the Parallel Four Parts report and click OK.

    Decision Center displays both of the reports on the same page. On the left is the report for Parallel One Part and on the right is the report for Parallel Four Parts.

    The reports are the same, except for the time the simulations took to run. The difference in time is a result of the number of parts. In the KPI for Parallel Four Parts, the results show that the simulation completed in 33 seconds, compared with the 52 seconds that it took to run Parallel One Part.

    Key Performance Indicators

    Loan Approval Rate 33.333336 % for 30000 borrowers with income < 60000 Simulation on 80000 scenarios Total Execution Time 51566 ms

    The simulation that is divided into four parts executed almost two times faster compared with the simulation that has only one part.

    Note:

    The actual time that it takes to run the simulations can vary depending on the computer you run it on, but the ratio remains the same.

Importing this sample into Rule Designer

You create the formats and custom scenario providers used in Decision Center in Rule Designer using a DVS project. For more information, see DVS Projects.

To look at the DVS project that contains the custom scenario providers, you can import it into Rule Designer.

To import the projects used in this sample:

1. In Rule Designer, switch to the Samples Console perspective.

2. In the Samples and Tutorials view, navigate to Decision Center > Samples > Testing > Custom scenario provider and KPI.

3. Click Import projects.

   The following projects are imported into your workspace:

   • DecisionCustomScenarioProvider Sample Report
   • DVSCustomizationProject
   • loanvalidation-rules
   • loanvalidation-xom

   The projects open in the Rule Explorer.

   Note:

   The BIRT report described in the DecisionCustomScenarioProvider Sample Report uses the database located in <InstallDir>/shared/data/derby/resdb-customdw. To be able to edit the report in the Report Design perspective in Rule Designer:

   1. Stop the sample server.
   2. Make sure that the database URL of the data source used in the report corresponds to your <InstallDir>.

4. In DVSCustomizationProject, double-click SampleCustomization.sspc to view the details of the customization.

5. In the Formats section, select HistoricalData and click Edit.

   The format editor opens.

   You can see the HistoricalData scenario provider main class, as well as the renderer class, and the KPI classes.

How this sample works

To define a custom scenario provider, you define an implementation for IlrScenarioProvider.

To define this implementation you:

• Initialize the provider

• Close the provider

• Provide the number of scenarios defined

• Build each scenario one by one

  The scenario is an IlrScenarioImpl object with its input parameters.

To define a parallel scenario provider you:

• Define an implementation of IlrParallelScenarioProvider.

  In this sample, the previous implementation of IlrScenarioProvider is extended to implement the IlrParallelScenarioProvider interface.

• Give the different scenario parts.

  A scenario part is an instance of IlrParallelScenarioProvider.IlrScenarioSuitePart.

To define a renderer for Decision Center that corresponds to the custom scenario provider, you define an implementation for IlrScenarioSuiteResourcesRenderer.

To define this implementation, you:

• Get the parameters for the provider

• Define the HTML to view the provider parameters

• Define the HTML to edit the provider parameters

In Decision Center, you define a parameter that associates the custom scenario provider to its renderer class. The new parameter is defined in the file rtsbin/preferences.properties.

To define a custom KPI, you define an implementation for IlrKPI.

To define an implementation for IlrKPI, you:

• Initialize the KPI

• Compute the KPI

• Provide KPI results

  The KPI result class implements IlrKPIResult. It defines how to encode and decode the result from the SSP to Decision Center. The KPI result can be a predefined type encoded to an array of bytes to be shown in Decision Center.

By default, the predefined IlrKPIResult classes have associated renderers. Define an implementation of IlrScenarioSuiteKPIRenderer to have a different KPI display from the Decision Center classic display. For example, in the ApprovedKPIRenderer class, the color of the KPI result is computed according to the KPI value and you use a Report button to access a BIRT report with diagrams that represent the accepted and rejected loan requests.

In Decision Center, you define a configuration parameter that associates the custom KPI to its renderer class. The new parameter is defined in the file rtsbin/preferences.properties.

To control the custom scenario provider, the Decision Center renderers, and the KPIs you create a DVS Project in Rule Designer. In this project you specify the format against which you want to execute tests and simulations. The customization includes a definition of the scenario provider, the rule project, and the KPIs. A DVS project can also contain a configuration that specifies the application server that is used to run the tests.

The Repackage feature, available through the DVS customization in the DVS project, generates a build.xml file. This file contains Ant targets to repackage the web applications for the Scenario Service Provider and Decision Center.

This sample uses a build.xml file that calls the generated build.xml.

You perform the deployment of the custom scenario provider in this sample using Ant. The sample includes the following Ant targets in the <InstallDir>/teamserver/samples/dvscustomscenarioprovider/build.xml file:

• build:
  • The required classes and .jar files
• repackage: Calls the build.xml file that is generated in the DVS project:
  • To repackage the scenario provider web application with the new formats, the XOM, and the extension classes
  • To repackage Decision Center with the new formats, the new renderer classes, the new messages and configuration parameters
• deploy: Redeploys the repackaged SSP and the teamserver EAR files in the sample server

Source files

This sample is located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider.

The provider classes are located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/DVSCustomizationProject/src/ilog/rules/dvs/samples.

The KPI classes are located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/DVSCustomizationProject/src/ilog/rules/dvs/samples/custom.

You must package the KPI result class in both Decision Validation Services and Decision Center. The KPI result class is located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/DVSCustomizationProject/src/ilog/rules/dvs/samples/custom.

The renderer classes are located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/DVSCustomizationProject/src/ilog/rules/dvs/samples/custom.

The utility classes are located in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/DVSCustomizationProject/src/ilog/rules/dvs/samples/derby.

The BIRT report approved_rejected_report.rptdesign that shows the contents of the database is defined in <InstallDir>/teamserver/samples/dvscustomscenarioprovider/report/reports.