Using the Xpress for MATLAB Toolbox

Please refer to the "Xpress Installation and Licensing User Guide" for instructions on Xpress installation. The MATLAB interface does not require a separate software license.

In order to make the Xpress functions available in MATLAB, the Xpress MATLAB path must be added to the MATLAB search path. This can be done either using the graphical 'Set Path' dialog box or the command line. Note that this step is the same one described for the Xpress Mosel MATLAB interface and need to be done only once.

Using the MATLAB graphical interface to set the search path

From the main MATLAB window, click on File » Set Path..., then on the 'Add Folder' button and select the matlab subfolder of your Xpress installation folder (on Windows platforms typically 'c:\xpressmp\matlab').

You can also make this change permanent by clicking on the 'Save' button.

Using the MATLAB command line to set the search path

The command to add the Xpress interface to MATLAB search path is:

>> addpath 'c:\xpressmp\matlab' 

(assuming you installed Xpress on 'c:\xpressmp'), and this can be made permanent with the command

>> savepath

Verifying if Xpress works

You can verify that the Xpress MATLAB interface is working properly by executing the command

>> xprsver

inside MATLAB. In case everything is fine you should get something like:

FICO Xpress Optimizer 64-bit v31.01.02 (Hyper capacity)
(c) Copyright Fair Isaac Corporation 1983-2017

Interface functions

The Xpress MATLAB interface is comprised of the following functions:

• 7 optimization functions (xprslp, xprsqp, xprsqcqp, xprsbip, xprsmip, xprsmiqp, xprsmiqcqp)
• 2 functions to set/get controls (xprsoptimset and xprsoptimget)
• 1 function to show the Xpress version (xprsver)

The next section documents each of these functions. Once the MATLAB search path has been configured, the same documentation will be also directly available in MATLAB, both from the drop down menu Help » Product Help, as a new Toolboxes section, and from the command line using the help command (e.g. with help xprslp).

Problem matrices

Differently from MATLAB Optimization Toolbox minimization functions, that take two distinct matrices in input: one for inequality constraints and the other for equality constraints, Xpress interface functions take only one matrix for both types of constraints plus a vector that specifies the constraint type.

Therefore, if matrices A and Aeq (with RHS, respectively, b and beq) are used to solve a linear problem with the Optimization Toolbox's linprog function:

>> x = linprog(f, A, b, Aeq, beq, lb, ub);

the same problem can be solved with Xpress using the commands

>> rtype = [repmat('L',[1 size(A,1)]) repmat('E',[1 size(Aeq,1)])];
>> x = xprslp(f, [A; Aeq], [b; beq], rtype, lb, ub);

where the rtype vector indicates that rows from matrix A are of type 'L' (less than or equal) and rows from matrix Aeq are of type 'E' (equalities).

Setting and querying controls and attributes

Optimization options can be specified with a mechanism similar to that used by the MATLAB Optimization Toolbox, that is via an options structure that specifies a list of Xpress controls and their values. See function xprsoptimset and the 'Control Parameters' section of the "Xpress Optimizer Reference Manual" for more details.

The xprsoptimset function also handles the conversion from the Optimization Toolbox options to the corresponding Xpress options for all cases where this makes sense.

Furthermore, after calling an Xpress optimization function, it is possible to retrieve the final value of any Xpress control or attribute. The list of control and attribute names to be returned must be specified in the 'XPRSGET' field of the option argument, separated by blanks. For example

>> options= xprsoptimset('XPRSGET', 'LPOBJVAL LPSTATUS')
>> [x,fval,ef,output] = xprslp(f, A, b, [], lb, ub, options);
>> fval, output.LPOBJVAL
fval =
   -78
output =
    LPOBJVAL: -78
    LPSTATUS: 1

It is also possible to request that the output structure be filled with all Xpress control and attribute values by setting 'XPRSGET' to 'ALL'.

In the Xpress MATLAB interface, control and attribute names are always all uppercase and without the XPRS prefix.

Special options

When calling an interface function, it is possible to pass one or more of the following additional options before the normal input arguments:

-v

Display the version of the called function.

-w[flags]

Write the problem to file; see the documentation for XPRSwriteprob in the Optimizer Reference Manual for more details (supported in all optimization functions).

-s

Save the optimizer data structures immediately before solving the problem; see the documentation for XPRSsave in the Optimizer Reference Manual for more details (supported in all optimization functions).

Both the -w and -s options create files in the current MATLAB directory/folder and with the same name as the name of the function being called.

For example, it is possible to export a MIP problem to a file in LP format by calling xprsmip with an additional -w option and flag l as follows (the file will be named xprsmip.lp):

>> x = xprsmip('-wl', f, A, b, rtype, ctype);