mmxnlp

Topics covered in this chapter:

The mmxnlp module provides access to nonlinear solvers, extending the capabilities provided by the mmxprs and mmnl modules. In particular, this module allows existing linear or mixed integer (MIP) models to be upgraded to include nonlinearities, without requiring unnecessary changes to the formulation. To use this module, the following line must be included in the header of the Mosel model file:

 uses 'mmxnlp'

Problem type and module hierarchy

Module mmxprs provides

• linear models and
• mixed integer linear models.

Module mmnl adds support for

• convex quadratic models,
• convex quadratic mixed integer models,
• convex, quadratically constrained models, and
• convex, quadratically constrained mixed integer models.

Module mmxnlp adds support for

• general nonlinear problems and
• general nonlinear mixed integer problems.

If the mmxnlp module is used for a model which does not require a general nonlinear solver, this should be equivalent to using the appropriate mmxprs or mmnl module directly.

New functionality for the Mosel language

The userfunc type

A nonlinear model may employ one or more black box evaluation functions, which can be used to provide function evaluations to the solver. These are represented in mmxnlp by the new userfunc type. The implementation of each userfunc must be described by calling one of:

• userfuncMosel: to declare that a user function is implemented as a Mosel function

Note that user functions returning multiple arguments are support by the mmxnlp module. The F construction allows a userfunc to be included in any nonlinear ( nlctr) expression, and groups each occurrence of the userfunc with its parameters . During the solve, the parameters (which are of type nlctr themselves) will be evaluated at the current solution, and the real-valued results passed to the userfunc implementation. The function userfuncinfo can be used to find out which parameters the system has deduced it needs to pass to a particular userfunc.

The tolset type

The module provides a large number of configurable tolerances for users of the Xpress NonLinear SLP solver. A tolset describes a convergence tolerance set, which can be used for those nonlinear solvers supporting variable-specific convergence tolerances. The elements of a tolerance set are defined by using settol, and assigned to a variable or list of variables using settolset. For more details on tolerance sets, please refer to the Xpress NonLinear Reference Manual.

• XNLP_TOL_TC: The absolute closure tolerance
• XNLP_TOL_TA: The absolute delta tolerance
• XNLP_TOL_RA: The relative delta tolerance
• XNLP_TOL_TM: The absolute matrix tolerance
• XNLP_TOL_RM: The relative matrix tolerance
• XNLP_TOL_TI: The absolute impact tolerance
• XNLP_TOL_RI: The relative impact tolerance
• XNLP_TOL_TS: The relative slack impact tolerance
• XNLP_TOL_RS: The absolute slack impact tolerance

The mpproblem.xprs.xnlp problem type

When using the mmxnlp module, the type of the active Mosel problem is changed from mpproblem.xprs to the extended type mpproblem.xprs.xnlp. This means that all of the routines presented in this section operate in the context of the current Mosel problem.

mmxnlp and the other Mosel modules

mmxnlp is designed to provide seamless integration with other Mosel functionalities. However, the fundamentally different nature of nonlinear problems makes some compromises necessary; these are listed in this section.

Overloaded functions

The following functionality is modified or extended by the mmxnlp module:

• Retrieval of solution values with getsol, both for variables and nonlinear constraints. A detailed description of the behaviour of this function can be found in the documentation for the mmxprs and mmnl modules.
• Functions implemented in the mmnl module are extended for nonlinear solvers:
  • setinitval, clearinitvals and copysoltoinit to manage initial values.
  • Mathematical functions: abs, exp, ln, log, sqrt, cos, sin, tan, arccos, arcsin, arctan.
  • Mosel constraint and constraint visibility functions: gettype, settype, ishidden and sethidden.
• Functions implemented in the mmxprs module are extended for nonlinear solvers:
  • maximize and minimize to solve the problem.
  • getprobstat to return the problem solution status.
  • fixmipentities for managing integer problems.
  • Exporting the current status (for debugging purposes) with loadprob, writeprob and savestate.

Module compatibility

The mmquad module is incompatible with the mmxnlp module, and should not be used together with it.

The mmxprs and mmnl modules are automatically loaded when using the mmxnlp module.

The mmnl module defines several discontinuous functions for use with decision variables (mpvar), which are not supported by the mmxnlp module. These constructions should instead be modelled with integer constraints. The functions are: round, ceil, floor, idiv and mod.

The following standard functionalities are not available for nonlinear problems:

• Functions for working with a basis: loadbasis, readbasis and savebasis.
• Logical constraints of the form logctr.
• Functions for working with multiple MIP solutions, the solution pool and the solution enumerator: selectsol, XPRS_enumduplpol, XPRS_enummaxsol and XPRS_enumsols.
• Functions for cut management, including model cuts and delayed rows: addcut, addcuts, loadcuts, storecut, storecuts, delcuts, dropcuts, getcnlist and getcplist.
• Functions for determining irreducible infeasible sets, and for repairing infeasibility: getiis, getiissense, getiistype, isiisvalid, resetiis and repairinfeas and getinfeas.

Control parameters

When using mmxnlp, getparam and setparam are extended to additionally provide access to all the control and problem parameters of the Xpress NonLinear SLP solver. The module also provides the following controls of its own:

XNLP_AUTOELIM	When set to true, Mosel uses the model's semantics to break down nonlinear formulas and feed the information to the solver for nonlinear eliminations and to detect network structures in the model.
XNLP_LOADASNL	When set to true, quadratic expressions will be treated as being of general nonlinear type. If they are known to be non-convex, the overhead of attempting to treat the expression as convex initially is avoided.
XNLP_LOADNAMES	When set to true, names from the Mosel file will be passed to the underlying solver to improve the readability of messages it generates. This is an alias for XPRS_LOADNAMES.
XNLP_NLPSTATUS	The solution status of the problem. For a detailed description of this value, please see the documentation for the XSLP_NLPSTATUS attribute in the Xpress NonLinear Reference Manual.
XNLP_SOLVER	Solver selection when available.
XNLP_VERBOSE	When set to true, informative messages from any underlying nonlinear solver will be displayed. This is an alias for XPRS_VERBOSE.

Error codes issued by mmxnlp

1   Out of memory

The system has run out of memory.

2   No purchase authorization found

No license found

3   Failed to initialize XSLP

Cannot initialize the XPRS library. There may be a licensing problem

4   Unsupported XSLP version

The version of the 'XSLP' library is incompatible with the current module. The Xpress installation may be corrupt

5   Failed to create the XSLP problem object

Cannot create the XSLP optimizer problem. There may be a licensing problem

6   Unexpected mmxnlp user function signature

The provided user functions' signature does not match any expected format.

7   Unexpected external token in mmxnlp

An unexpected external token found by the 'mmxnlp' module. Please contact support.

8   Unsupported operator

The provided operator is not supported by 'mmxnlp'.

9   Failed to load problem

Could not load the problem into the optimizer.

10   Variable bound conflict in problem

Inconsistent bounds provided for the variable.

11   Failed to load user function

The user function could not be loaded into the optimizer.

12   Error evaluating user function

Error while evaluation the user function. The user function likely to have returned an error code.

13   Unknown tolerance set

The provided tolerance set is invalid.

14   List tpype error in user function

The list provided to the user function is not valid for the function.

15   Failed to create save file

The savefile could not be created.

16   Error in optimization

An error has occured during optimization.

17   Cannot reoptimize using a different objective (use named linctr or nlctr)

The objective has unexpectedly changed

18   Internal error in mmxnlp. Please contact FICO support

An internal error has occurred. Please contact support.

20   Incompatible array definitions for user function arguments

The user function received incompatible arrays.

21   Non-Mosel user functions only take 'list of nlctr' type arguments

User functions that are not implemented as a Mosel function can only take list of 'nlctr' arguments (no arrays).

22   Invalid argument list for external function

The provided argument list is not valid for the external function.

23   Provided user function is not returning a single real

The provided user function was expected to return a single real value.

24   Provided user function is not returning an array indexed by integers

The provided user function was expected to return an array of reals indexed by integers.

25   User function must be loaded before it's properties can be retrieved

The user function must be loaded before it's properties are interrogated. Please use 'loadprob' to load the model including the user function.

26   Unexpected variable found. Please reload problem first using 'loadprob'

An unexpected variable has been used. Please reload the problem to load the variable.

27   Operation only supported on the main problem (e.g. not inside multi-start callbacks)

This operation is only supported in the main problem. It cannot be used on worker problems.

28   Math error while evaluating expression

A mathematical error has occurred while evaluating the expression.