Usage Examples

Topics covered in this chapter:

Simple Model

This is a version of the 'chess2' example, modified to be an Xpress Insight app. It demonstrates how to write a model so that Xpress Insight can capture or inject the model's input data, depending upon the run mode, while still allowing the model developer to run the model from outside of Xpress Insight, e.g. from the Mosel command line.

model Chess2
 uses "mmxprs"                     ! Load the Xpress Optimizer
 uses "mminsight"                  ! Load the Insight interface

 public declarations
  ! Model inputs
  UnitTypes: set of string
  ResourceTypes: set of string

  ResourceLimits: array(ResourceTypes) of real
  ProfitPerUnit: array(UnitTypes) of real
  UnitResourceRequirements: array(UnitTypes,ResourceTypes) of real

  ! Mathematical model objects (providing model results)
  unitstobuild: array(UnitTypes) of mpvar
  ResourceLimitConstraints: array(ResourceTypes) of linctr
  MaxProfit: linctr
 end-declarations

 ! Procedure to populate model with initial input data
 procedure loaddata
  ProfitPerUnit:: (["small","large"])[5,20]
  UnitResourceRequirements:: (["small"],["wood","mc_time"]) [1,3]
  UnitResourceRequirements:: (["large"],["wood","mc_time"]) [3,2]
  ResourceLimits:: (["wood","mc_time"])[200,400]

  finalize( UnitTypes )
  finalize( ResourceTypes )
 end-procedure

 ! Procedure to build and solve optimization problem
 procedure solvemodel
  ! Build whole units only
  forall(u in UnitTypes) unitstobuild(u) is_integer

  ! Define profit
  MaxProfit:= sum(u in UnitTypes) ProfitPerUnit(u)*unitstobuild(u)

  ! Don't use more than available resources
  forall(r in ResourceTypes)
   ResourceLimitConstraints(r) := ( sum(u in UnitTypes)
    UnitResourceRequirements(u,r)*unitstobuild(u) ) <= ResourceLimits(r)

  ! Solve the mixed integer problem
  insightmaximize(MaxProfit)

  ! Print the solution to the run log
  writeln("Solution:\n Objective: ", getobjval)
  forall(u in UnitTypes)
   writeln(u, ":", unitstobuild(u).sol)
 end-procedure

 ! Define actions to perform in 'load' execution mode
 !@insight.execmodes.LOAD
 public procedure doload
  ! Scenario is being 'loaded' through Xpress Insight
  ! Initialize input arrays and then terminate
  loaddata
 end-procedure

 ! Define actions to perform in 'run' execution mode
 !@insight.execmodes.RUN
 public procedure dorun
  ! Scenario is being 'run' through Xpress Insight
  ! Populate with Insight scenario data and then solve optimization
  insightpopulate
  solvemodel
 end-procedure

 ! Define actions to perform when model is run standalone (without Xpress Insight)
 !@insight.execmodes.NONE
 public procedure doloadandrun
  ! Model is being run outside of Xpress Insight, e.g. from the Mosel command-line tool
  ! Initialize input arrays then solve optimization
  loaddata
  solvemodel
 end-procedure

 ! Automatically call the procedure with annotation matching the current execution mode
 insightdispatch
end-model

Insight will by default manage all public entities of supported types in the scenario, with entities storing linctr and mpvar values in the result data and all others in the input, but you can change this by adding annotations as we'll describe in section Annotations.

Accessing Attachments

As described in the Developer Guide, Xpress Insight allows files to be attached to an app or scenario. While the model is running within Xpress Insight, the Mosel interface will allow you to query, read and edit attachments of the scenario being run, as well as query and read (but not edit) attachments of the app to which that scenario belongs.

To demonstrate the use of an app and scenario attachments, in this example we have a Distances array that we want to populate with distances between cities. As this data will not change, it would be very wasteful to store a copy of these in every scenario of the app, so we store them in a file distances.dat which is attached to the app. In the example, we call insightgetappattach to copy this file to the working directory and then populate the Distances array from this. (The Distances array is annotated as ignored by Xpress Insight, so it will not be part of the Insight scenario data model.)

To demonstrate the use of scenario attachments, we then save the model's results to a file decorated with today's date, and attach this file to the current scenario.

model RoutePlanner
 uses "mmxprs"                     ! Load the Xpress Optimizer
 uses "mminsight"                  ! Load the Insight interface

 ! Input data - stored in Insight scenario
 !@insight.manage input
 public declarations
  EvaluationDate: string
  Cities: set of string
  TrafficLevels: array(Cities,Cities) of real
 end-declarations

 ! Result data - stored in Insight scenario
 !@insight.manage result
 public declarations
  routetaken: array(Cities,Cities) of mpvar
 end-declarations

 ! Data structures used internally in the model
 !@insight.manage ignore
 declarations
  Distances: array(Cities,Cities) of real
 end-declarations

 ! Procedure to build and solve optimization problem
 procedure runproblem
  ! Download app attachment
  if insightgetmode <> INSIGHT_MODE_NONE then
   ! Model is running within Insight, so download distances.dat from Insight server
   insightgetappattach("distances.dat")
   if insightattachstatus<>INSIGHT_ATTACH_OK then
    writeln("Failed to download app attachment")
    exit(1)
   end-if
  else
   ! Model is running outside of Insight, attachments are not accessible
   ! so copy from some other location
   fcopy( '/Users/me/myfiles/distances.dat', 'distances.dat' )
  end-if
  ! Load into model
  initializations from "distances.dat"
   Distances
  end-initializations

  ! Perform optimization
  buildproblem
  optimizeproblem

  ! Capture results to file
  ROUTES_FNAME := "result-"+EvaluationDate+".dat"
  fopen(ROUTES_FNAME,F_OUTPUT)
  forall (s in Cities, d in Cities | routetaken(s,d).sol=1)
   writeln(s,"->",d)
  fclose(F_OUTPUT)

  ! Store as scenario attachment
  if insightgetmode <> INSIGHT_MODE_NONE then
   ! Model is running within Insight, so upload distances.dat to Insight server
   insightputscenattach(ROUTES_FNAME)
   if insightattachstatus<>INSIGHT_ATTACH_OK then
    writeln("Failed to upload scenario attachment")
    exit(1)
   end-if
  end-if
 end-procedure

 !@insight.execmodes.LOAD
 public procedure doload
  loaddata
 end-procedure

 !@insight.execmodes.RUN
 public procedure dorun
  insightpopulate
  runproblem
 end-procedure

 !@insight.execmodes.NONE
 public procedure doloadandrun
  loaddata
  runproblem
 end-procedure

 insightdispatch

end-model

For clarity, the implementation of the loaddata, buildproblem and optimizeproblem procedures have been omitted from the example.

Inter-Scenario Data Access

You can also initialize your data structures with values from external scenarios using the mminsight.scenariodata I/O driver with a standard Mosel initializations-from block. For example, the following model initializes the array "Distances" from an array called "CityDrivingDistances" in a scenario "USDrivingDistances" in an app named "DrivingDistancesModel"

model RoutePlanner
 uses "mmxprs"                     ! Load the Xpress Optimizer
 uses "mminsight"                  ! Load the Insight interface

 ! Input data - stored in Insight scenario
 !@insight.manage input
 public declarations
  Cities: set of string
  TrafficLevels: array(Cities,Cities) of real
 end-declarations

 ! Result data - stored in Insight scenario
 !@insight.manage result
 public declarations
  routetaken: array(Cities,Cities) of mpvar
 end-declarations

 ! Data structures used internally in the model
 !@insight.manage ignore
 declarations
  Distances: array(Cities,Cities) of real
 end-declarations

 ! Procedure to build and solve optimization problem
 procedure runproblem
  ! Populate 'Distances' array
  if insightgetmode <> INSIGHT_MODE_NONE then
   ! Populate 'Distances' array from the remote scenario
   initializations from "mminsight.scenariodata:/DrivingDistancesModel/USDrivingDistances"
    Distances as "CityDrivingDistances"
   end-initializations
  else
   ! Model is running outside of Insight, so populate driving distances from local file
   initializations from "/Users/me/myfiles/distances.dat"
    Distances
   end-initializations
  end-if

  ! Perform optimization
  buildproblem
  optimizeproblem
 end-procedure

 !@insight.execmodes.LOAD
 public procedure doload
  loaddata
 end-procedure

 !@insight.execmodes.RUN
 public procedure dorun
  insightpopulate
  runproblem
 end-procedure

 !@insight.execmodes.NONE
 public procedure doloadandrun
  loaddata
  runproblem
 end-procedure

 insightdispatch

end-model

For clarity, the implementation of the loaddata, buildproblem and optimizeproblem procedures have been omitted from the example.

Annotations

The handling of model (schema) entities by Insight and certain global settings such as execution modes are configured via annotations to the Mosel model. The following Mosel model extract shows some examples of annotation definitions.

 !@insight.manage=input
 public declarations        ! All entities declared here are managed as input
  !@insight.alias City Names
  !@insight.descr Set of all cities
  Cities: set of string
  TrafficLevels: array(Cities,Cities) of real
 end-declarations

 !@insight.manage result    ! All entities declared here are managed as results
 public declarations
  routetaken: array(Cities,Cities) of mpvar
 end-declarations

 ! Data structures used internally in the model
 !@insight.manage ignore    ! All entities declared here are not managed by Insight
 declarations
  Distances: array(Cities,Cities) of real
 end-declarations

 ! The 'insight.execmodes' annotations would normally immediately precede the subroutines
 ! that implement the execution mode.

 ! Define an execution mode 'analyzedata'

 (!@insight.execmodes.analyzedata.
   @descr Analyzing input data
   @clearinput false
   @threads 1
  !)
 public procedure doanalyze
  loaddata
  analyzedata
 end-procedure

 !@insight.execmodes.LOAD
 public procedure doload
  loaddata
 end-procedure

Type Marshalling

The Insight schema will usually contain entities of basic types (boolean, integer, real and string), and sets and arrays of these. The type marshalling features allow values of external types (types added to Mosel by modules such as mmsystem) to be stored as strings in the Insight schema. Type marshalling can be enabled globally for a type, e.g.:

 !@insight.marshal.type datetime string
 ! All values of type datetime will be represented by string in the Insight schema

 !@insight.manage=input
 public declarations
  today: datetime
  ! will be treated as 'string' in Insight schema

  alldatesin2000: set of constant datetime
  ! will be treated as 'set of string' in Insight schema

  birthdays: array(set of string) of datetime
  ! will be treated as 'array of string' in Insight schema

  now: time
  ! will not be in Insight schema; no annotation for type 'time'
 end-declarations

Or for individual entities, e.g.:

!@insight.manage=input
 public declarations
  !@insight.marshal.value string
  today: datetime
  ! will be treated as 'string' in Insight schema

  !@insight.marshal.value string
  alldatesin2000: set of constant datetime
  ! will be treated as 'set of string' in Insight schema

  !@insight.marshal.value string
  birthdays: array(set of string) of datetime
  ! will be treated as 'array of string' in Insight schema

  yesterday: datetime
  ! will not be in Insight schema; no marshalling annotation for this entity
 end-declarations

When applying the type marshalling to a set or array, the conversion will be applied to the values within the collection, not the collection itself (e.g. 'set of datetime' becomes 'set of string', not a scalar 'string' concatenating everything within the set.

The type marshalling annotations can be applied to any module type that supports conversion to and from string. In the standard Xpress installation, these are the types to which the annotation can be applied:

• date
• datetime
• text
• time

There are a few restrictions on using either type marshalling annotation:

• Marshalling can only be applied to module types as described above - not records, lists or nested types such as 'set of set of string'.
• When used with a set, the set must be declared set of constant to ensure it cannot contain duplicate values.
• For date/time/datetime types, the default string format will always be used, ignoring the datefmt, timefmt and datetimefmt parameters.
• Trying to marshal a native type that does not support conversion both to and from string will result in an error when running the scenario, not when loading the app into Insight.