Writing a Mosel Model for Xpress Executor

You can develop and compile your Mosel model in Xpress Workbench or through other Xpress development tools. If your model compiles to a single .bim file, you should upload it through the configuration page. If it requires multiple files (for example if you use sub-models, or have some fixed data-files, Java class, or R scripts that are always required) you should place them in a Zip archive with the master model in a file called model.bim that can then be uploaded through the configuration page.

Input and Result

When your model is executed, it should read input data (as supplied by the execution web service request) from a file named "input" in the current work directory. There are no restrictions on the format of the input data; your model will be responsible for parsing it in whatever way is appropriate.

Any result data from your model should be written to a file named "result" in the current work directory. This file will be copied into the Executor repository and made available for download through web service requests.

The work directory

Normally, each execution is assigned a private work directory which will initially contain:

The compiled model (in a file named model.bim).
The content of the model zip file (if the model was uploaded as a zip file).
The execution input file (in a file named input).

The model is free to read/write other files to this directory, and should write its result data to a file named result.

If the "Re-use Mosel instances for multiple executions" feature is enabled from the Configuration screen, the work directory is not cleared when the execution completes, and may be re-used for a subsequent execution. In this configuration, you can use the work directory to locally cache files or data that are expensive to acquire, such as files downloaded from Internet websites. However, in this configuration your model must take care to leave the work directory in a state usable by the next execution.

Reporting Execution Progress

In general, a model should record its outputs in the result file, which is available after the execution completes. In some cases, Executor may start an execution multiple times, terminating some before completion, and only record the result from one of those executions. This means that you cannot see any definitive results of the execution until it completes. However, you may also want to view the progress of a long-running execution. There are two ways to do this:

The run log will contain all the lines written by the master model to the standard Mosel output and error streams; you can use this to emit progress messages:
```
writeln("Starting optimization")
maximize(x+y)
  writeln("Completed optimization")
```
The run log so far can be fetched through web service requests before the execution completes, but remember that if the execution is restarted then the run log from the old execution will be replaced with the new.

You can also set a numeric progress value, indicating how much work your model has done. The progress value is set to 0 at the start of the execution and you can update it by using the send procedure of the mmjobs module to send and event of class 38371, as shown here:

  uses "mmjobs"
…
  forall (optnum in 1..1000) do
    run_optimization(optnum)
    send(38371, optnum)
  end-do

The progress value can be read from the progress field of the ModelExecution structure of the web service API.

Note The class 38371 is an Executor convention, the progress number will not be updated if you use an event class other than 38371.

Model Exit Codes

The following model exit codes by convention have special meaning in Xpress Executor:

Code	Description
-97111	indicates that Executor should rerun this execution from the beginning
-97112	indicates that Executor should terminate the current Mosel instance, and rerun this execution from the beginning. This is typically used when the Re-use Mosel instances for multiple executions feature is activated, to force an instance to be discarded and the execution to be re-run in a fresh Mosel instance and work directory.

All other exit codes are treated normally; they are recorded in the repository and can be read from the web service API. There is no assumption in Executor that 0 represents success and non-zero represents an error.

Side Effects

When scaled across multiple gears, Executor may start multiple copies of the same execution at the same time. Normally only one of these will run through fully; the others will be cancelled during their execution, and so are invisible to the user. However, the developer should be aware that any side effects, such as writing to a database or external web service, will occur multiple times for each execution.

© 2001-2020 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.

Contents

Index