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, type XPRS_TOK_COL uses 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". In general, users are advised to use the XPRSnlp or XPRSslp versions of nonlinear functions which work directly on the optimizer XPRSprob. Alternatively, it is still possible to manually create an instance of an XSLPprob that can be provided to XSLP versions of these functions, which is explained in the following.

The optimizer problem must be initialized first in the normal way. Then the corresponding Xpress NonLinear problem can 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 load functions

The load 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 first, using the normal Optimizer Library functions XPRSloadlp or XPRSloadmip. Then the appropriate parts of the Xpress NonLinear problem can be loaded. After all the load functions have been called, XPRSslpconstruct can be called to manually create the SLP matrix and data structures. If XPRSslpconstruct 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 add function.

It is possible to remove parts of the SLP structures with the various del functions, and XPRSslpunconstruct can also be used to remove the augmentation.

Xpress NonLinear is compatible with the quadratic API functions within the Xpress Optimizer. XPRSloadqp and XPRSloadmiqp can be used to load quadratic problems (or quadratically constrained problems using XPRSloadqcqp and XPRSloadmiqcqp). With default values for the NLPREFORMULATE control, quadratic matrices and quadratic terms in formulas will be converted between the two as necessary so that all convex quadratic terms can be handled by the appropriate methods within the Xpress Optimizer while any non-convex quadratics are kept in formulas to be handled by Xpress XSLP, Xpress Global or Knitro. For more details on the distinction between convex and non-convex quadratics, 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. They are exported to the XPRS library, where they can be called on an XPRSprob without having to explicitly create an XSLPprob first. Alternatively, these functions also have an XSLP prefixed version that takes an SLP problem as their first argument.