Deployment to Xpress Insight

Xpress Insight embeds Mosel models into a multi-user application for deploying optimization models in a distributed client-server architecture. Through the Xpress Insight GUI, business users interact with Mosel models to evaluate different scenarios and model configurations without directly accessing to the model itself.

Preparing the model file

For embedding a Mosel model into Xpress Insight, we need to make a few edits to the Mosel model in order to establish the connection between Mosel and Xpress Insight.

Firstly, we need to load the package mminsight that provides the required additional functionality. Since Insight manages the data scenarios, we only need to read in data from the original sources when loading the scenario (also referred to as baseline run) into Insight (triggered by the test of the run mode with insightgetmode in the model below). Scenario data will otherwise be input directly from Xpress Insight at the insertion point marked with insightpopulate. All model entities that are to be managed by Xpress Insight need to be declared as public. Furthermore, the solver call to start the optimization is replaced by insightminimize / insightmaximize.

The resulting model file folioinsight.mos (based on foliodata.mos) has the following contents—this model can also simply be run standalone, e.g. from Workbench or the Mosel command line, this is the case handled by INSIGHT_MODE_NONE.

model "Portfolio optimization with LP"
 uses "mmxprs"                       ! Use Xpress Optimizer
 uses "mminsight"                    ! Use Xpress Insight

 parameters
  DATAFILE= "folio.dat"              ! File with problem data
  MAXRISK = 1/3                      ! Max. investment into high-risk values
  MAXVAL = 0.3                       ! Max. investment per share
  MINAM = 0.5                        ! Min. investment into N.-American values
 end-parameters

 public declarations
  SHARES: set of string              ! Set of shares
  RISK: set of string                ! Set of high-risk values among shares
  NA: set of string                  ! Set of shares issued in N.-America
  RET: array(SHARES) of real         ! Estimated return in investment
 end-declarations

 case insightgetmode of
  INSIGHT_MODE_LOAD: do              ! 'Load data' mode: Read data, then stop
       initializations from DATAFILE
        RISK RET NA
       end-initializations
       exit(0)
      end-do
  INSIGHT_MODE_RUN:                  ! 'Run' mode: Inject scen. data, continue
      insightpopulate
  INSIGHT_MODE_NONE:                 ! Standalone run: Read data and continue
      initializations from DATAFILE
       RISK RET NA
      end-initializations
  else
      writeln("Unknown execution mode")
      exit(1)
 end-case

 public declarations
  frac: array(SHARES) of mpvar       ! Fraction of capital used per share
  Return, LimitRisk, LimitAM, TotalOne: linctr   ! Constraints
 end-declarations

! Objective: total return
 Return:= sum(s in SHARES) RET(s)*frac(s)

! Limit the percentage of high-risk values
 LimitRisk:= sum(s in RISK) frac(s) <= MAXRISK

! Minimum amount of North-American values
 LimitAM:= sum(s in NA) frac(s) >= MINAM

! Spend all the capital
 TotalOne:= sum(s in SHARES) frac(s) = 1

! Upper bounds on the investment per share
 forall(s in SHARES) frac(s) <= MAXVAL

! Solve the problem through Xpress Insight
 insightmaximize(Return)

end-model

Note that we have removed all solution output from this model: we are going to use Xpress Insight for representing the results.

The app archive

Xpress Insight expects models to be provided in compiled form, that is, as BIM files—see Section BIM files on how to generate BIM files from the model source. Since Xpress Insight executes Mosel models in a distributed architecture (so, possibly not on the same machine from where the model file is input) we recommend to include any input data files used by the model in the Xpress Insight app archive. The app archive is a ZIP archive that contains the BIM file and the optional subdirectories model_resources (data files), client_resources (custom view definitions), and source (Mosel model source files). For our example, we create a ZIP archive folioinsight.zip with the file folioinsight.bim and the data file folio.dat in the subdirectory model_resources.

Figure 10.3: Creating a new Insight project

With Xpress Workbench, select the option 'Create project' followed by 'Create Insight project' at startup to create the directory structure expected by Xpress Insight and replace the template model (in subdirectory source), configuration (application.xml and subdirectory client_resources), and data files (in subdirectory model_resources) by the files of your Mosel project. In order to work with an existing app, select Open existing file or folder followed by Open project when starting up Workbench and browse to the desired folder or double click on a Mosel file in the source subdirectory and select 'Open Insight app' in the dialog box.

Figure 10.4: Default Xpress Insight app template

Select the button to create the app archive or to publish the app directly to Insight. If the app has been published successfully the link 'Open in Xpress Insight' in the green message box will take you to the app loaded in the Insight web client opened with your default web browser.

Figure 10.5: Deploying an app to Xpres Insight

Working with the Xpress Insight Web Client

Open the Xpress Insight Web Client by directing your web browser to the Web Client entry page: with a default desktop installation of Xpress Insight this will be the page http://localhost:8860/insight

Figure 10.6: Xpress Insight web client entry page

If you have currently loaded any apps in Insight these will show up on the Web Client entry page, otherwise this page only displays the 'Upload app' icon. We now upload the app archive folioinsightxml.zip that adds a VDL view definition file and an XML configuration file to the archive folioinsight.zip. The Mosel model has been extended with the array CtrSol to store some result and data values in a convenient format for display (note the use of annotation marker !@insight.manage that is required to inform Xpress Insight that these data are not input but result values):

 !@insight.manage=result
 public declarations
  CTRS: set of string                            ! Constraint names
  CTRINFO: set of string                         ! Constraint info type
  CtrSol: dynamic array(CTRS,CTRINFO) of real    ! Solution values
 end-declarations

! Save solution values for GUI display
 CtrSol::("Limit high risk shares", ["Activity","Lower limit","Upper limit"])
          [LimitRisk.act,0,MAXRISK]
 CtrSol::("Limit North-American", ["Activity","Lower limit","Upper limit"])
          [LimitAM.act,MINAM,1]
 forall(s in SHARES | frac(s).sol>0) do
  CtrSol("Limit per value: "+s,"Activity"):= frac(s).sol
  CtrSol("Limit per value: "+s,"Upper limit"):= MAXVAL
  CtrSol("Limit per value: "+s,"Lower limit"):= 0
 end-do

Optionally, we can also add annotations to individual declarations in order to configure the GUI display of model entities:

 public declarations
  SHARES: set of string              !@insight.alias Shares
  RET: array(SHARES) of real         !@insight.alias Estimated return in investment
  frac: array(SHARES) of mpvar       !@insight.alias Fraction used
  Return: linctr                     !@insight.alias Total return
  TotalOne: linctr                   !@insight.hidden true
 end-declarations

Once you have successfully loaded the app archive, the app 'Portfolio Optimization' will show up as a new icon:

Figure 10.7: Xpress Insight web client after loading the Portfolio app

Select the 'Portfolio Optimization' app icon to open the app. Note that if you have deployed an app from Workbench and followed the link 'Open in Xpress Insight' you will immediately be taken to this page.

Figure 10.8: App entry page

Now click on the text Click here to select scenarios in the shelf to create a scenario. In the 'Scenario Explorer' window, select 'Scenario 1' and confirm with Close.

Figure 10.9: Scenario creation in the Xpress Insight web client

Use the Load entry from the drop-down menu on the scenario name in the shelf to load the baseline data.

Figure 10.10: Scenario menu in the Xpress Insight web client

After loading the scenario the view display changes, showing the input data of our optimization model. You can edit these data by entering new values into the input fields or table cells. Use the Run button on the view or the corresponding entry in the scenario menu to run the model with the data shown on screen.

Figure 10.11: Display after scenario loading

After a successful model run the placeholder message no results available in the lower half of our view is replaced by the results display, as shown below.

Figure 10.12: VDL view with input and result data elements

You can create new scenarios from existing ones (selecting 'Clone' in the scenario menu) or with the original input data by selecting 'New scenario' in the Scenario Explorer window. The results of multiple scenarios can be displayed in a single view for comparison.

Figure 10.13: VDL view comparing several scenarios

VDL

VDL (View Definition Language) is a markup language for the creation of views for Xpress Insight apps from a set of predefined components and built-in styling options. Optionally, VDL view definitions can be extended with HTML tags and Javascript code for further customization.

Xpress Workbench includes a drag-and-drop editor for the creation and editing of VDL views. Within Xpress Workbench, select menu File » New » Insight View (VDL) to launch the view creation dialog. Enter 'Portfolio data' as the view title and folio.vdl as the filename for the view and in the following screen select 'Basic view' layout before terminating the dialog with 'Finish'. In the drag-and-drop editor that now shows, drag objects from the palette on the left onto the central artboard area—when doing so the editor will provide guidance regarding which combinations of objects are permitted (for example, a 'row' needs to contain 'columns' into which you can then add objects like 'table', 'chart' or 'text').

Figure 10.14: VDL view designer in Xpress Workbench

The attributes for the currently selected element in the editor can be edited in the pane on the right hand side.

Figure 10.15: VDL view designer: editing view elements

For certain elements (table, chart) specific dialog windows will open to guide the user through their configuration.

Figure 10.16: VDL view designer: table definition wizard

Note that at any time during the editing of VDL views in Workbench the app can be published to Insight by selecting the button in order to inspect the actual appearance of the web views when they are populated with scenario data.

The view 'Portfolio data' shown as web view in Figure VDL view with input and result data elements and in the VDL designer in Figure VDL view designer: editing view elements is created entirely from the following VDL view definition (file folio.vdl in the subdirectory client_resources of the app archive). All data entities marked as 'editable' can be modified by the UI user.

<vdl version="4.7">
  <vdl-page>
  <!-- VDL header and 'page' must always be present -->

    <!-- Structural element 'section': print header text for a section -->
    <vdl-section heading="Configuration">

      <!-- Structural element 'row': arrange contents in rows -->
      <vdl-row>
        <!-- Several columns within a 'row' for display side-by-side,
             dividing up the total row width of 12 via 'size' setting
             on each column. -->
        <vdl-column size="5">
          <!-- A form groups several input elements -->
          <vdl-form>
            <!-- Input fields for constraint limits -->
            <vdl-field parameter="MAXRISK" size="3" label-size="9"
              label="Maximum investment into high-risk values"/>
            <vdl-field parameter="MAXVAL" size="3" label-size="9"
              label=" Maximum investment per share"/>
            <vdl-field parameter="MINAM" size="3" label-size="9"
              label="Minimum investment into North-American values" />
            <!-- default sizes: 2 units each -->
          </vdl-form>
        </vdl-column>
        <vdl-column size="4">
          <!-- Display editable input values, default table format -->
          <vdl-table>
            <vdl-table-column entity="RET" editable="true"/>
          </autotable>
        </vdl-column>
        <vdl-column size="3">
          <vdl-form>
            <!-- 'Run' button to launch optimization -->
            <vdl-execute-button caption="Run optimization"/>
          </vdl-form>
        </vdl-column>
      </vdl-row>
    </vdl-section>

    <!-- Placeholder message for 'Results' section -->
    <vdl-container vdl-if="=!scenario.summaryData.hasResultData">
      <span vdl-text="no results available"></span></vdl-container>

    <!-- Structural element 'section';
         display: with option 'none' nothing gets displayed by default
         if hasResultData: display section once result values become available
                           (after scenario execution) -->
    <vdl-section heading="Results"
         vdl-if="=scenario.summaryData.hasResultData" style="display: none">

      <vdl-row>
        <vdl-column>
          <!-- Display text element with the objective value -->
          <span vdl-text="='Total expected return: &#163;' +
              insight.Formatter.formatNumber(scenario.entities.Return.value,
              '##.00')"></span>
        </vdl-column>
      </vdl-row>

      <vdl-row>
        <vdl-column size="4" heading="Portfolio composition">
          <!-- Display the 'frac' solution values, default table format -->
          <vdl-table>
            <vdl-table-column entity="frac"></vdl-table-column>
          </vdl-table>
        </vdl-column>
        <vdl-column size="8">
          <!-- Display the 'frac' solution values as a pie chart -->
          <vdl-chart style="width:400px;">
            <vdl-chart-series entity="frac" type="pie"></vdl-chart-series>
          </vdl-chart>
        </vdl-column>
      </vdl-row>
    </vdl-section>
  </vdl-page>
</vdl> 

VDL views need to be declared in an app archive via an XML configuration file (the so-called companion file). When VDL views are created via the view designer in Workbench then the required entry is added automatically to this file. Companion files can also be created and edited using the Workbench editor (select File » New » Companion file ). The following companion file definition integrates the VDL view folio.vdl and a second view 'Scenario comparison' into our example app folioinsightxml.zip.

<?xml version="1.0" encoding="iso-8859-1"?>
<model-companion version="3.0"
 xmlns="http://www.fico.com/xpress/optimization-modeler/model-companion" >
  <client>
    <view-group title="Main">
      <vdl-view title="Portfolio data" default="true" path="folio.vdl" />
      <vdl-view title="Scenario comparison" default="false" path="foliocompare.vdl"/>
    </view-group>
  </client>
</model-companion>