Library functions and the programming interface

Topics covered in this chapter:

Counting

All Xpress NonLinear entities are numbered from 1. The 0^th item is defined, and is an empty entity of the appropriate type. Therefore, whenever an Xpress NonLinear function returns a zero value, it means that there is no data of that type.

In parsed and unparsed function arrays, types XSLP_COL and XSLP_ROW use indices counted from zero, the same as the Xpress Optimizer library.

The Xpress NonLinear problem pointer

Xpress NonLinear uses the same concept as the Optimizer library, with a "pointer to a problem". The optimizer problem must be initialized first in the normal way. Then the corresponding Xpress NonLinear problem must be initialized, including a pointer to the underlying optimizer problem. For example:

{
	...
	XPRSprob prob=NULL;
	XSLPprob SLPprob=NULL;

	XPRSinit("");
	XSLPinit();
	XPRScreateprob(&prob);
	XSLPcreateprob(&SLPprob,&prob);
	...
}

At the end of the program, the Xpress NonLinear problem should be destroyed. You are responsible for destroying the underlying XPRSprob linear problem afterwards. For example:

{
...
  XSLPdestroyprob(SLPprob);
  XPRSdestroyprob(prob);
  XSLPfree();
  XPRSfree();
  ...
}

The following functions are provided to manage Xpress NonLinear problems. See the documentation below on the individual functions for more details.

XSLPcopycontrols(XSLPprob prob1, XSLPprob prob2)
   Copy the settings of control variables

XSLPcopycallbacks(XSLPprob prob1, XSLPprob prob2)
   Copy the callback settings

XSLPcopyprob(XSLPprob prob1, XSLPprob prob2, char *ProbName)
   Copy a problem completely

XSLPcreateprob(XSLPprob *prob1, XPRSprob *prob2)
   Create an Xpress NonLinear problem

XSLPdestroyprob(XSLPprob prob1)
   Delete an Xpress NonLinear problem from memory

XSLPrestore(XSLPprob prob1)
   Restore Xpress NonLinear data structures from file

XSLPsave(XSLPprob prob1)
   Save Xpress NonLinear data structures to file

The XSLPload... functions

The XSLPload... functions can be used to load an Xpress NonLinear problem directly into the Xpress data structures. Because there are so many additional items which can be loaded apart from the basic (linear) matrix, the loading process is divided into several functions.

The best practice is to load the linear part of the problem irst, using the normal Optimizer Library functions XPRSloadlp or XPRSloadmip. Then the appropriate parts of the Xpress NonLinear problem can be loaded. After all the XSLPload... functions have been called, XSLPconstruct should be called to create the SLP matrix and data structures. If XSLPconstruct is not invoked before a call to one of the Xpress NonLinear optimization routines, then it will be called by the optimization routine itself.

All of these functions initialize their data areas. Therefore, if a second call is made to the same function for the same problem, the previous data will be deleted. If you want to include additional data of the same type, then use the corresponding XSLPadd... function.

It is possible to remove parts of the SLP strcutures with the various XSLPdel functions, and XSLPunconstruct can also be used to remove the augmentation.

Xpress NonLinear is compatible with the Xpress quadratic programming optimizer. XPRSloadqp and XPRSloadmiqp can be used to load quadratic problems (or quadratically constrained problmes using XPRSloadqcqp and XPRSloadmiqcqp). The quadratic objective will be optimized using the Xpress quadratic optimizer; the nonlinear constraints will be handled with the normal SLP procedures. Please note, that this separation is only useful for a convex quadratic objective and convex quadratic inequality constraints. All nonconvex quadratic matrices should be handled as SLP strctures.

For a description on when it's more beneficial to use the XPRS library to solve QP or QCQP problems, please see Selecting the right algorithm for a nonlinear problem - when to use the XPRS library instead of XSLP.

Library functions

A large number of routines are available for Library users of Xpress NonLinear, ranging from simple routines for the input and solution of problems from matrix files to sophisticated callback functions and greater control over the solution process. Library users have access to a set of functions providing advanced control over their program's interaction with the SLP module and catering for more complicated problem development. When called from the SLP library, these functions have an XSLP prefix and take an SLP problem as their first argument. They are also exported to the XPRS library, where they can be called on an XPRSprob without having to explicitly create an XSLPprob first.