FICO Xpress OptimizationR

Last update 20 March 2020

version 36.01

FICO Xpress Nonlinear
R

Manual©1983–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, oras otherwise set forth in a written software license agreement between you and FICO (or a FICO afﬁliate).
Use of this documentation and the software described in it must conform strictly to the foregoing
permitted uses, and no other use is permitted.
The information in this documentation is subject to change without notice. If you ﬁnd any problems in thisdocumentation, please report them to us in writing. Neither FICO nor its afﬁliates warrant that thisdocumentation is error-free, nor are there any other warranties with respect to the documentation except
as may be provided in the license agreement. FICO and its afﬁliates speciﬁcally disclaim any warranties,
express or implied, including, but not limited to, non-infringement, merchantability and ﬁtness for aparticular purpose. Portions of this documentation and the software described in it may contain copyrightof various authors and may be licensed under certain third-party licenses identiﬁed in the software,
documentation, or both.
In no event shall FICO or its afﬁliates be liable to any person for direct, indirect, special, incidental, or
consequential damages, including lost proﬁts, arising out of the use of this documentation or the software
described in it, even if FICO or its afﬁliates have been advised of the possibility of such damage. FICO and
its afﬁliates have no obligation to provide maintenance, support, updates, enhancements, or modiﬁcations
except as required to licensed users under a license agreement.
FICO is a registered trademark of Fair Isaac Corporation in the United States and may be a registeredtrademark of Fair Isaac Corporation in other countries. Other product and company names herein may be
trademarks of their respective owners.
Xpress Nonlinear
Deliverable Version: A
Last Revised: 20 March 2020
Version version 36.01

Contents
I

Overview

1

1

Introduction
1.1 Mathematical programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Linear programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 Convex quadratic programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Convex quadratically constrained quadratic programs . . . . . . . . . . . . . . . .
1.1.4 Second order conic problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.5 General nonlinear optimization problems . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6 Mixed integer programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Technology Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 The Simplex Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 The Logarithmic Barrier Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3 Outer approximation schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 Successive Linear Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5 Second Order Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6 Mixed Integer Solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 API naming convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2
2
3
3
3
3
4
4
4
4
4
5
5
5
5
5

2 The Problem
2.1 Problem Deﬁnition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Problem Formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7773 Modeling in Mosel
3.1 Basic formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Setting up and solving the problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Looking at the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Parallel evaluation of Mosel user functions . . . . . . . . . . . . . . . . . . . . . . . . . . .

9
9
10
11
11

4 Modeling in Extended MPS Format
4.1 Basic formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Using the nonlinear optimizer console-based interface . . . . . . . . . . . . . . . . . . . .
4.3 Coefﬁcients and terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13
13
17
18

5 The Xpress NonLinear API Functions
5.1 Header ﬁles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4 Creating the linear part of the problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5 Adding the non-linear part of the problem . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6 Adding the non-linear part of the problem using character formulae . . . . . . . . . . . . .
5.7 Checking the data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.8 Solving and printing the solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.9 Closing the program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.10 Adding initial values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19
19
19
19
20
23
25
26
26
27
27

Fair Isaac Corporation Conﬁdential and Proprietary Informationi

Contents

6 The Nonlinear Console Program
6.1 The Console Nonlinear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1 The nonlinear console extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2 Common features of the Xpress Optimizer and the Xpress Nonlinear Optimizer console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

29
29
29

II

32

Advanced

30

7 Nonlinear Problems
7.1 Coefﬁcients and terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 SLP variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Local and global optimality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4 Convexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5 Converged and practical solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6 The duals of general, nonlinear program . . . . . . . . . . . . . . . . . . . . . . . . . . . .

33
33
34
34
34
35
35

8 Extended MPS ﬁle format
8.1 Formulae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 COLUMNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3 BOUNDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4 SLPDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.1 CV (Character variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.2 DR (Determining row) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.3 EC (Enforced constraint) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.4 FR (Free variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.5 FX (Fixed variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.6 IV (Initial value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.7 LO (Lower bounded variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.8 Rx, Tx (Relative and absolute convergence tolerances) . . . . . . . . . . . . . . . .
8.4.9 SB (Initial step bound) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.10 UF (User function) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.11 UP (Free variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.12 WT (Explicit row weight) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.13 DL (variable speciﬁc Determining row cascade iteration Limit) . . . . . . . . . . . .

37
37
38
39
39
39
40
40
40
41
41
41
41
42
42
43
43
43

9 Xpress-SLP Solution Process
9.1 Analyzing the solution process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2 The initial point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3 Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.1 Finite Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.2 Symbolic Differentiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.3.3 Automatic Differentiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4 Points of inﬂection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.5 Trust regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

44
45
45
45
46
46
46
46
47

10 Handling Infeasibilities
10.1 Infeasibility Analysis in the Xpress Optimizer . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2 Managing Infeasibility with Xpress Knitro . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.3 Managing Infeasibility with Xpress-SLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4 Penalty Infeasibility Breakers in XSLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

48
48
48
49
49

11 Cascading
11.1 Determining rows and determining columns . . . . . . . . . . . . . . . . . . . . . . . . . .

51
52

12 Convergence criteria

53

Fair Isaac Corporation Conﬁdential and Proprietary Informationii

Contents

12.1 Convergence criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2 Convergence overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.1 Strict Convergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.2 Extended Convergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.3 Stopping Criterion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.4 Step Bounding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3 Convergence: technical details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.1 Closure tolerance (CTOL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.2 Delta tolerance (ATOL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.3 Matrix tolerance (MTOL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.4 Impact tolerance (ITOL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.5 Slack impact tolerance (STOL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.6 Fixed variables due to determining columns smaller than threshold (FX) . . . . . .
12.3.7 User-deﬁned convergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.8 Static objective function (1) tolerance (VTOL) . . . . . . . . . . . . . . . . . . . . .
12.3.9 Static objective function (2) tolerance (OTOL) . . . . . . . . . . . . . . . . . . . . .
12.3.10 Static objective function (3) tolerance (XTOL) . . . . . . . . . . . . . . . . . . . . .
12.3.11 Extended convergence continuation tolerance (WTOL) . . . . . . . . . . . . . . . .

53
53
53
53
54
55
55
58
58
58
59
60
60
60
60
61
61
62

13 Xpress-SLP Structures
13.1 SLP Matrix Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.1 Augmentation of a nonlinear coefﬁcient . . . . . . . . . . . . . . . . . . . . . . . .
13.1.2 Augmentation of a nonlinear term . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.1.3 Augmentation of a user-deﬁned SLP variable . . . . . . . . . . . . . . . . . . . . .
13.1.4 SLP penalty error vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2 Xpress-SLP Matrix Name Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.3 Xpress-SLP Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.4 SLP Variable History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

64
64
64
66
67
68
68
69
71

14 Xpress NonLinear Formulae
14.1 Parsed and unparsed formulae . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.2 Example of an arithmetic formula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3 Example of a formula involving a simple function . . . . . . . . . . . . . . . . . . . . . . .

73
73
74
75

15 User Functions
15.1 Callbacks and user functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.2 User function interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.3 User Function declaration in native languages . . . . . . . . . . . . . . . . . . . . . . . . .
15.3.1 User function declaration in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4 Simple functions and general functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4.1 Simple user functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4.2 General user functions returning an array of values through a reference . . . . . .
15.4.3 General user functions returning an array of values through an argument . . . . . .
15.5 Programming Techniques for User Functions . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5.1 Deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5.2 Return values and ReturnArray . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5.3 Returning Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5.4 Function Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.6 Function Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.6.1 Analytic Derivatives of Instantiated User Functions not Returning their own Derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

77
77
78
78
78
79
79
79
80
81
82
82
82
82
83

16 Management of zero placeholder entries
16.1 The augmented matrix structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.2 Derivatives and zero derivatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3 Placeholder management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

86
86
86
87

Fair Isaac Corporation Conﬁdential and Proprietary Information

85

iii

Contents

17 Special Types of Problem
17.1 Nonlinear objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.2 Convex Quadratic Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3 Mixed Integer Nonlinear Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3.1 Mixed Integer SLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3.2 Heuristics for Mixed Integer SLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3.3 Fixing or relaxing the values of the SLP variables . . . . . . . . . . . . . . . . . . .
17.3.4 Iterating at each node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3.5 Termination criteria at each node . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.3.6 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17.4 Integer and semi-continuous delta variables . . . . . . . . . . . . . . . . . . . . . . . . . .

89
89
89
90
90
90
91
92
92
92
93

18 Xpress NonLinear multistart

95

III

96

Reference

19 Problem Attributes
19.1 Double problem attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CURRENTDELTACOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CURRENTERRORCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORCOSTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OBJVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYDELTATOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYDELTAVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYERRORTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYERRORVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRIMALINTEGRAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONINDEX_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONINDEX_K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONINDEX_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VSOLINDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.2 Integer problem attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_COEFFICIENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ECFCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EXPLOREDELTAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EQUALSCOLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_IFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_IMPLICITVARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_INTEGERDELTAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_INTERNALFUNCCALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ITER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_JOBID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_KEEPBESTITER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINORVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINUSPENALTYERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPITER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPNODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPSOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MODELCOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MODELROWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MSSTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_NLPSTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Conﬁdential and Proprietary Information

97
101
101
101
101
101
101
102
102
102
102
102
103
103
103
104
104
104
104
104
104
105
105
105
105
105
106
106
106
106
106
107
107
107
107
107
108
108

iv

Contents

XSLP_NONCONSTANTCOEFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_NONLINEARCONSTRAINTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ORIGINALCOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ORIGINALROWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYDELTACOLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYDELTAROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYDELTAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYERRORCOLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYERRORROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PLUSPENALTYERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEDELETEDDELTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEELIMINATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEFIXEDCOEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEFIXEDDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEFIXEDNZCOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEFIXEDSLPVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEFIXEDZCOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEPASSES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVESTATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVETIGHTENED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBXCONVERGED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SEMICONTDELTAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SOLVERSELECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SOLSTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_STOPSTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TOLSETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TOTALEVALUATIONERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UCCONSTRAINEDCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UFINSTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UNCONVERGED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_USEDERIVATIVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_USERFUNCCALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROESRESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROESRETAINED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROESTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.3 Reference (pointer) problem attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPPROBLEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SOLUTIONPOOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XPRSPROBLEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XSLPPROBLEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19.4 String problem attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VERSIONDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

108
109
109
109
109
109
110
110
110
110
110
111
111
111
111
112
112
112
112
113
113
113
113
114
114
114
116
116
116
116
117
117
117
117
118
118
118
118
118
119
120
120
120
120
120
121
121

20 Control Parameters122
20.1 Double control parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
XSLP_ATOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
XSLP_ATOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
XSLP_BARSTALLINGTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
XSLP_CASCADETOL_PA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
XSLP_CASCADETOL_PR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Fair Isaac Corporation Conﬁdential and Proprietary Informationv

Contents

XSLP_CDTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CDTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CLAMPSHRINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CLAMPVALIDATIONTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CLAMPVALIDATIONTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMPEXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMPMAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMPMIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMPSHRINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DEFAULTIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DEFAULTSTEPBOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTA_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTA_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTA_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTA_Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTA_ZERO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTACOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTACOSTFACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTAMAXCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DJTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DRCOLTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ECFTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ECFTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ENFORCECOSTSHRINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ENFORCEMAXCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORCOSTFACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORMAXCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERRORTOL_P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ESCALATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ETOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ETOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EVTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EVTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_FEASTOLTARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_GRANULARITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_INFINITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ITOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ITOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MATRIXTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MAXWEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MEMORYFACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MERITLAMBDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINSBFACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINWEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPCUTOFF_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPCUTOFF_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPERRORTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPERRORTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPOTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPOTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Conﬁdential and Proprietary Information

131
132
132
133
133
133
134
134
134
135
135
135
136
136
136
137
137
137
138
138
138
139
139
139
140
140
141
141
141
142
142
142
143
143
143
144
144
145
145
145
146
146
147
147
148
148
148
149
149
149
150
150
150
151
151

vi

Contents

XSLP_MSMAXBOUNDRANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MVTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OBJSENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OBJTOPENALTYCOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OPTIMALITYTOLTARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEZERO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRIMALINTEGRALREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SHRINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SHRINKBIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_STOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_STOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONTARGET_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONTARGET_K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VALIDATIONTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_WTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_WTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XTOL_A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XTOL_R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZERO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20.2 Integer control parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ALGORITHM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ANALYZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_AUGMENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_AUTOSAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_BARCROSSOVERSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_BARLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_BARSTALLINGLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_BARSTALLINGOBJLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_BARSTARTOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CALCTHREADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CASCADE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CASCADENLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CONVERGENCEOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DAMPSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DCLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DCLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELAYUPDATEROWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTAOFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTAZLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DERIVATIVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DETERMINISTIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ECFCHECK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ECHOXPRSMESSAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ERROROFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_EVALUATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_FILTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_FINDIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Conﬁdential and Proprietary Information

152
152
153
153
154
154
155
155
155
156
156
157
157
157
158
158
158
159
159
160
160
161
162
163
163
164
166
166
168
169
170
171
171
172
172
172
173
173
174
174
175
176
176
176
176
177
177
178
178
178
179
179
180
180
181

vii

Contents

XSLP_FUNCEVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_GRIDHEURSELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_HEURSTRATEGY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_HESSIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_INFEASLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ITERLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_JACOBIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LINQUADBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LSITERLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LSPATTERNLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LSSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_LSZEROLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MAXTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPALGORITHM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPCUTOFFCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPCUTOFFLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPDEFAULTALGORITHM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPFIXSTEPBOUNDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPITERLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPOCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MIPRELAXSTEPBOUNDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART_MAXSOLVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART_MAXTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART_POOLSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART_SEED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MULTISTART_THREADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_OCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYINFOSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_POSTSOLVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVELEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PRESOLVEPASSLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PROBING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_REFORMULATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SAMECOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SAMEDAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBROWOFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SCALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SCALECOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SOLVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SLPLOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_STOPOUTOFRANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_THREADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TIMEPRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_THREADSAFEUSERFUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TRACEMASKOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UNFINISHEDLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UPDATEOFFSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_VLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Conﬁdential and Proprietary Information

181
182
182
183
183
183
184
184
184
185
185
185
186
186
186
188
188
189
189
190
190
190
191
191
191
192
192
193
193
193
194
194
194
195
195
196
196
196
197
197
198
198
198
199
199
200
200
200
200
201
201
202
202
203
203

viii

Contents

XSLP_WCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_XLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROCRITERION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROCRITERIONCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ZEROCRITERIONSTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20.3 String control parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_CVNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_DELTAFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_ITERFALLBACKOPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_IVNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINUSDELTAFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_MINUSERRORFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYCOLFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PENALTYROWFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PLUSDELTAFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_PLUSERRORFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBLOROWFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_SBUPROWFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TOLNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_TRACEMASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLP_UPDATEFORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20.4 Knitro controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

204
205
205
206
207
207
208
208
208
208
209
209
210
210
210
211
211
211
212
212
212
213
213
213

21 Library functions and the programming interface
214
21.1 Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
21.2 The Xpress NonLinear problem pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
21.3 The XSLPload... functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
21.4 Library functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
XSLPaddcoefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
XSLPadddfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
XSLPaddtolsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
XSLPadduserfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
XSLPaddvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
XSLPcalcslacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
XSLPcascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
XSLPcascadeorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
XSLPchgcascadenlimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
XSLPchgccoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
XSLPchgcoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
XSLPchgdeltatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
XSLPchgdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
XSLPchgrowstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
XSLPchgrowwt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
XSLPchgtolset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
XSLPchgvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
XSLPconstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
XSLPcopycallbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
XSLPcopycontrols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
XSLPcopyprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
XSLPcreateprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
XSLPdelcoefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
XSLPdeltolsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
XSLPdeluserfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Fair Isaac Corporation Conﬁdential and Proprietary Informationix

Contents

XSLPdelvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPdestroyprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPevaluatecoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPevaluateformula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPﬁxpenalties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetbanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetccoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetcoefformula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetcoefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetcolinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetdblattrib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetdblcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetintattrib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetintcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetlasterror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetptrattrib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetrowinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetrowstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetrowwt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetslpsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetstrattrib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetstrcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgettolset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPgetvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPglobal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPimportlibfunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPinterrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPitemname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPloadcoefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPloaddfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPloadtolsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPloadvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPmaxim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPminim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPmsaddcustompreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPmsaddjob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPmsaddpreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPmsclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPnlpoptimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPpostsolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPpresolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPprintmemory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPprintevalinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPreadprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPremaxim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPreminim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPrestore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPreinitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsaveas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPscaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Conﬁdential and Proprietary Information

250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
278
279
280
281
282
283
285
286
287
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307

x

Contents

XSLPsetcbcascadeend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbcascadestart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbcascadevar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbcascadevarfail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbcoefevalerror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbconstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbdestroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbdrcol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbintsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbiterend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbiterstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbitervar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbmessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbmsjobend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbmsjobstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbmswinner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcboptnode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbprenode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbpreupdatelinearization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbslpend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbslpnode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcbslpstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetcurrentiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetdblcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetdefaultcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetdefaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetfunctionerror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetintcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetlogﬁle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPsetstrcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPunconstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPupdatelinearization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPvalidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPvalidatekkt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPvalidateprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPvalidaterow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPvalidatevector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPwriteprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XSLPwriteslxsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

308
309
310
311
312
313
315
316
317
318
319
320
321
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349

22 Internal Functions
350
22.1 Trigonometric functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
ARCCOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
ARCSIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
ARCTAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
COS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
SIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
TAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
22.2 Other mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
ABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
ERF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
ERFC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
EXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
LN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Fair Isaac Corporation Conﬁdential and Proprietary Informationxi

Contents

LOG, LOG10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PWL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SQRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23 Error Messages

364
365
366
367
368
369
370

24 Xpress Knitro Control Parameters376
24.1 Double control parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
XKTR_PARAM_BAR_FEASMODETOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
XKTR_PARAM_BAR_INITMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
XKTR_PARAM_DELTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
XKTR_PARAM_FEASTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
XKTR_PARAM_FEASTOLABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
XKTR_PARAM_INFEASTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
XKTR_PARAM_MIP_INTEGERTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
XKTR_PARAM_MIP_INTGAPABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
XKTR_PARAM_MIP_INTGAPREL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
XKTR_PARAM_OBJRANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
XKTR_PARAM_OPTTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
XKTR_PARAM_OPTTOLABS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
XKTR_PARAM_PRESOLVE_TOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
XKTR_PARAM_XTOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
24.2 Integer control parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
XKTR_PARAM_ALGORITHM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
XKTR_PARAM_BAR_DIRECTINTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
XKTR_PARAM_BAR_FEASIBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
XKTR_PARAM_BAR_INITPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
XKTR_PARAM_BAR_MAXBACKTRACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
XKTR_PARAM_BAR_MAXCROSSIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
XKTR_PARAM_BAR_MAXREFACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
XKTR_PARAM_BAR_MURULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
XKTR_PARAM_BAR_PENCONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
XKTR_PARAM_BAR_PENRULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
XKTR_PARAM_BAR_SWITCHRULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
XKTR_PARAM_GRADOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
XKTR_PARAM_HESSOPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
XKTR_PARAM_HONORBNDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
XKTR_PARAM_LMSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
XKTR_PARAM_MAXCGIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
XKTR_PARAM_MAXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
XKTR_PARAM_MIP_BRANCHRULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
XKTR_PARAM_MIP_GUB_BRANCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
XKTR_PARAM_MIP_HEURISTIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
XKTR_PARAM_MIP_HEURISTIC_MAXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
XKTR_PARAM_MIP_IMPLICATNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
XKTR_PARAM_MIP_KNAPSACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
XKTR_PARAM_MIP_LPALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
XKTR_PARAM_MIP_MAXNODES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
XKTR_PARAM_MIP_MAXSOLVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
XKTR_PARAM_MIP_METHOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
XKTR_PARAM_MIP_OUTINTERVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
XKTR_PARAM_MIP_OUTLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

Fair Isaac Corporation Conﬁdential and Proprietary Informationxii

Contents

XKTR_PARAM_MIP_PSEUDOINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_ROOTALG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_ROUNDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_SELECTRULE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_STRONG_CANDLIM . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_STRONG_LEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_STRONG_MAXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_MIP_TERMINATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_OUTLEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_PRESOLVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_SCALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XKTR_PARAM_SOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix

392
392
392
393
393
393
393
393
394
394
394
395

396

A The Xpress-SLP Log
397
A.0.1 Logging controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
A.0.2 The structure of the log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
B Selecting the right algorithm for a nonlinear problem - when to use the XPRS library instead of
XSLP
400
B.0.1 Convex Quadratic Programs (QPs) . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
B.0.2 Convex Quadratically Constrained Quadratic Programs (QCQPs) . . . . . . . . . . 400
B.0.3 Convexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
B.0.4 Characterizing Convexity in Quadratic Constraints . . . . . . . . . . . . . . . . . . . 401
C Files used by Xpress NonLinear

403

D Contacting FICO
404
Product support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Product education . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Sales and maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Related services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
FICO Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
About FICO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Index

Fair Isaac Corporation Conﬁdential and Proprietary Information

406

xiii

I. Overview

CHAPTER 1

Introduction
This part of the manual is intended to provide a general description of the facilities available formodeling with Xpress NonLinear. It is not an exhaustive list of possibilities, and it does not go into very
great depth on some of the more advanced topics. All the functions and formats are given in moredetail in the second part of this manual and the Xpress-Mosel Reference Manual (Module mmxnlp
section).
Xpress Nonlinear consists of the Xpress Optimizer to solve linear, mixed integer linear, and convex
quadratic problems, Xpress-SLP which uses Successive Linear Programming to solve non-linear
models, and as an plugin Knitro.
The functionalities of Xpres NonLinear extend those of the Xpress Optimizer. Almost any problem thatﬁts into the problem types supported by the Xpress Optimizer are automatically detected andconverted into the appropriate format to take advantage of the power of the optimizer’s purpose written
algorithms.
Xpress-SLP is in essence, is a technique which involves making a linear approximation of the original
problem at a chosen point, solving the linear approximation and seeing how "far away" the solution
point is from the original chosen point. If it is "sufﬁciently close" then the solution is said to have
converged and the process stops. Otherwise, a new point is chosen, based on the solution, and a newlinear approximation is made. This process repeats (iterates) until the solution converges. Although
this process will ﬁnd a solution which is the optimum for the linear approximation, there is no guaranteethat the solution will be the optimum for the original non-linear problem (that is to say: it may not be thebest possible solution to the original problem). Such a solution is called a "local optimum", because it isa better solution than any others in the immediate neighbourhood, but may not be better than one along way away.
The problem of local optima can be thought of as being like trying to ﬁnd the deepest valley in a rangeof mountains. You can ﬁnd a valley relatively easily (just keep going downhill). However, when you
reach it, you have no idea whether there is a deeper valley somewhere else, because the mountains
block your view. You have found a local optimum, but you do not know whether it is a global optimum.
Indeed, in general, there is no way to ﬁnd the global optimum except an exhaustive search (check every
valley in the mountain range).
While Xpress-SLP is most powerful for large or integer nonlinear problems, Knitro which can takeadvantage of using second order partial derivative information can be more beneﬁcial for hihgly
nonlinear models.

1.1

Mathematical programs
There are many specialised forms of model in mathematical programming, and if such a form can be
identiﬁed, there are usually much more efﬁcient solution techniques available. This section describes
some of the major types of problem that Xpress NonLinear can identify automatically.

Fair Isaac Corporation Conﬁdential and Proprietary Information2

Introduction

1.1.1

Overview

Linear programs
Linear programming (LP) involves solving problems of the form
minimizesubject to

cT x
Ax ≤ band in practice this encompasses, via transformations, any problem whose objective and constraints
are linear functions.
Such problems were traditionally solved with the simplex method, although recently interior point
methods have come to be favoured for larger instances. Linear programs can be solved quickly, andsolution techniques scale to enormous sizes of the matrix A. However, few applications are genuinely
linear. It was common in the past, however, to approximate general functions by linear counterparts
when LPs were the only class of problem with efﬁcient solution techniques.

1.1.2

Convex quadratic programs
Convex quadratic programming (QP) involves solving problems of the form
minimizesubject to

cT x + xT Qx
Ax ≤ bfor which the matrix Q is symmetric and positive semi-deﬁnite (that is, xT Qx ≥ 0 for all x). This
encompasses, via transformations, all problems with a positive semi-deﬁnite Q and linear constraints.
Such problems can be solved efﬁciently by interior point methods, and also by quadratic variants of thesimplex method.

1.1.3

Convex quadratically constrained quadratic programs
Convex quadratically constrained quadratic programming (QCQP) involves solving problems of theformminimizecT x + xT Qx
subject to Ax ≤ b
qTj x + xT Pj x ≤ dj , ∀jfor which the matrix Q and all matrices Pj are positive semi-deﬁnite. The most efﬁcient solution
techniques are based on interior point methods.

1.1.4

Second order conic problems
Second order conic problems is a special form of a convex quadratically constrained quadratic
program, where although the quadratic matrix is not positive semi-deﬁnite, the feasible range of the
problem is convex, and there are specialized algorithm to solve them.
minimizesubject to

cT x + xT Qx
Ax ≤ bx is in Cj , ∀jfor which the matrix Cj is a convex second order cone and Q is positive semi-deﬁnite. The standard
form of a second order cone is xT Ix ≤ y ∗ y where y is non-negative, or (a rotated second order cone)xT Ix ≤ y ∗ z where y and z are non-negative. Many quadratic problems can be formulated as a second
order convex conic problem, including any convex quadratically constrained quadratic programs.
Transformation happens automatically for most convertible problems.

Fair Isaac Corporation Conﬁdential and Proprietary Information

3

Introduction

1.1.5

Overview

General nonlinear optimization problems
Nonlinear programming (NLP) involves solving problems of the form
minimizesubject tof(x)gj (x) ≤ b, ∀jwhere f(x) is an arbitrary function, and g(x) are a set of arbitrary functions. This is the most general typeof problem, and any constrained model can be realised in this form via simple transformations.
Until recently, few practical techniques existed for tackling such problems, but it is now possible tosolve even large instances using Successive Linear Programming solvers (SLP) or second-ordermethods.

1.1.6

Mixed integer programs
Mixed-integer programming (MIP), in the most general case, involves solving problems of the form
minimizesubject tof(x)gj (x) ≤ b, ∀j
xk integral

It can be combined with any of the previous problem types, giving Mixed-Integer Linear Programming(MILP), Mixed-Integer Quadratic Programming (MIQP), Mixed-Integer Quadratically Constrained
Quadratic Programming (MIQCQP), Mixed-Integer Second Order Conic Problems (MISOCP) and
Mixed-Integer Nonlinear Programming (MINLP). Efﬁcient solution techniques now exist for all of theseclasses of problem.

1.2

Technology Overview
In real-world applications, it is vital to match the right optimization technology to your problem. The
FICO Xpress libraries provide dedicated, high performance implementations of optimization
technologies for the many model classes commonly appearing in practical applications. This includes
solvers for linear programming (LP), mixed integer programming (MIP), convex quadratic programming(QP), and convex quadratically constrained programming (QCQP), and general nonlinear programming(NLP).

1.2.1

The Simplex Method
The simplex method is one of the most well-developed and highly studied mathematical programming
tools. The solvers in the FICO Xpress Optimizer are the product of over 30 years of research, and include
high quality, competitive implementations of the primal and dual simplex methods for both linear andquadratic programs. A key advantage of the simplex method is that it can very quickly reoptimize a
problem after it has been modiﬁed, which is an important step in solving mixed integer programs.

1.2.2

The Logarithmic Barrier Method
The interior point method of the FICO Xpress Optimizer is a state of the art implementation, withleading performance across a variety of large models. It is capable of solving not only the largest andmost difﬁcult linear and convex quadratic programs, but also convex quadratically constrained
quadratic and second order conic programs. It includes optimized versions of both infeasible
logarithmic barrier methods, and also homogeneous self-dual methods.

Fair Isaac Corporation Conﬁdential and Proprietary Information

4

Introduction

1.2.3

Overview

Outer approximation schemes
A drawback of the barrier methods is that they are not efﬁciently warms-tarted. This makes thesemethods unattractive for solving several related problems, like the ones arising from a branch andbound search. While for linear and convex quadratic problems the simplex methods can be used, there
is no immediate such alternative for convex quadratic constrained and second order methods. To
bridge the gap, outer approximation cutting schemes are used, which themselves may be warm started
by a barrier solution.

1.2.4

Successive Linear Programming
For general nonlinear programs which are very large, highly structured, or contain a signiﬁcant linear
part, the FICO Xpress Sequential Linear Programming solver (XSLP) offers exceptional performance.
Successive linear programming is a ﬁrst order, iterative approach for solving nonlinear models. At each
iteration, a linear approximation to the original problem is solved at the current point, and the distanceof the result from the the selected point is examined. When the two points are sufﬁciently close, thesolution is said to have converged and the result is returned. This technique is thus based upon solving
a sequence of linear programming problems and beneﬁts from the advanced algorithmic andpresolving techniques available for linear problems. This makes XSLP scalable, as well as efﬁcient forlarge problems. In addition, the relatively simple core concepts make understanding the solution
process and subsequent tuning comparatively straightforward.

1.2.5

Second Order Methods
Also integrated into the Xpress suite is Knitro from Artelys, a second-order method which is particularly
suited to large-scale continuous problems containing high levels of nonlinearity. Second order methods
approximate a problem by examining quadratic programs ﬁtted to a local region. This can provide
information about the curvature of the solution space to the solver, which ﬁrst-order methods do not
have. Advanced implementations of such methods, like Knitro, may as a result be able to produce more
resilient solutions. This can be especially noticeable when the initial point is close to a local optimum.

1.2.6

Mixed Integer Solvers
The FICO Xpress MIP Solver is a highly scalable parallel branch and bound framework for all classes of
mixed integer programs. It is based on a branch and bound search utilizing continuous solvers,
advanced cutting planes in-tree presolving and multiple heuristics, for discovering primal solutions andtightening best bounds. The search is guided by advanced methods for selecting branching variables
and estimating sub-tree sizes/efforts. Mixed integer programming forms the basis of many important
applications, and the implementation in the FICO Xpress Suite has proven itself in operation for someof the world’s largest organizations. Both XSLP and Knitro are also able to solve mixed integer
nonlinear problems (MINLP).

1.3

API naming convention
Xpress Nonlinear has been developed as an extension to the XPRS library building on the SLP solver
technology, which is reﬂected in the naming convention. All XPRS API functions are used the same way
as normal to build the linear part of the problem, while the API functions preﬁxed with XSLP are used
for all nonlinear aspects, independently of how the problem is solved afterwards (convex quadratic
problems by a dedicated solver or Knitro instead of SLP). Some controls have both an XPRS and an
XSLP counterpart, for example "XPRS_PRESOLVE" and "XSLP_PRESOLVE". In such cases,"XSLP_PRESOLVE" refers to the nonlinear presolver (even if another solver than SLP is used to solve theproblem afterwards) and "XPRS_PRESOLVE" refers to problems that are not deemed as general

Fair Isaac Corporation Conﬁdential and Proprietary Information

5

Introduction

Overview

nonlinear (LP, MIP or convex quadratic); in such cases, if SLP solves one of such problems as part of its
iterative process, the XPRS control is respected for such sub-solves.

Fair Isaac Corporation Conﬁdential and Proprietary Information

6

CHAPTER 2

The Problem
2.1

Problem Deﬁnition
The diameter of a two-dimensional shape is the greatest distance between any two of its points. For acircle, this deﬁnition corresponds to the normal meaning of "diameter". For a polygon (with straightsides), it is equivalent to the greatest distance between any two vertices.
What is the greatest area of a polygon with N sides and a diameter of 1?

2.2

Problem Formulation
This formulation is one of two described by Prieto [1]. It is easy to visualize, and has advantages in later
examples. The pentagon is about the smallest model which can reasonably be used – it is non-trivial
but is still just about small enough to be written out in full.

Figure 2.1: Polygon Example

One vertex (the highest-numbered, VN ) is chosen as the "base" point, and all the other vertices aremeasured from it, using (r, θ) coordinates – that is, the distance ("r") is measured from the vertex, andthe angle or bearing of the vertex (" θ ") is measured from the X-axis.

Fair Isaac Corporation Conﬁdential and Proprietary Information

7

The Problem

Overview

We shall use ri and θi as the coordinates of vertex Vi . Then simple geometry and trigonometry gives:

The area of the triangle VN Vi Vj : area(VN Vi Vj ) = 21 · ri · rj · sin(θj – θi )The side Vi Vj is given by: (Vi Vj )2 = ri2 + rj2 – 2 · ri · rj · cos(θj – θi )

The total area of the polygon is:



PN–1
i=2

area(VN Vi Vi–1 )The maximum diameter of 1 requires that all the sides of all the triangles are ≤ 1 – that is:ri ≤ 1 for i = 1, ..., N – 1and
Vi Vj ≤ 1 for i = 1, ..., N – 2, j = i + 1, ..., N – 1

We have assumed in the diagram 2.1 and in the formulation that θ i ≤ θ i+1 – in other words, the vertices
are in order anti-clockwise. In fact, this is not just an assumption, and we need to include these
constraints as well.
In the diagram, we have assumed that the ﬁrst angle θ 1 is ≥ 0. This is not an additional restriction if we
use the normal modeling convention that all variables are non-negative. We also assumed that the lastvertex is still "above" the X-axis – that is, θ N–1 is ≤ 180◦ (or π radians).
The requirement is therefore:
PN–1
maximize
i=2 (ri · ri–1 · sin(θi – θi–1 )) ∗ 0.5
subject to:(area of the polygon)ri ≤ 1 for i = 1, ..., N – 1(distances betweem VN and other vertices)
ri2 + rj2 – 2 · ri · rj · cos(θj – θi ≤ 1 for i = 1, ..., N – 2, j = i + 1, ..., N – 1(distances between other pairs of vertices)θ1 ≥ 0(ﬁrst bearing is non-negative)
θi+1 – θi ≥ 0 for i = 1, ..., N – 2(bearings are in order)θN–1 ≤ π(last vertex is above X-axis)

Reference:(1) F.J. Prieto. Maximum area for unit-diameter polygon of N sides, ﬁrst model and second model (Netlib
AMPL programs in ftp://netlib.bell-labs.com/netlib/ampl/models).

Fair Isaac Corporation Conﬁdential and Proprietary Information

8

CHAPTER 3

Modeling in Mosel
3.1

Basic formulation
Nonlinear capabilities in Mosel are provided by the mmxnlp module. Please refer to the module
documentation for more details. This chapter provides a short introduction only.
The model uses the Mosel module mmxnlp which contains the extensions required for modeling
general non-linear expressions. This automatically loads the mmxprs module, so there is no need toinclude this explicitly as well.
model "Polygon"
uses "mmxnlp"

We can design the model to work for any number of sides, so one way to do this is to set the number ofsides of the polygon as a parameter.
parameters
N=5
end-parameters

The meanings of most of these declarations will become apparent as the modeling progresses.
declarations
area: nlctr
rho: array(1..N) of mpvar
theta: array(1..N) of mpvar
objdef: mpvar
D: array(1..N,1..N) of nlctr
end-declarations
The distances are described as "rho", to distinguish them from the default names for the rows in
the generated matrix (which are R1, R2, etc).
The types nlctr (nonlinear constraint) are deﬁned by the mmxnlp module.
area := sum(i in 2..N-1) (rho(i) ⁎ rho(i-1) ⁎ sin(theta(i)-theta(i-1)))⁎0.5

This uses the normal Mosel sum function to calculate the area. Notice that the formula is written in
essentially the same way as normal, including the use of the sin function. Because the argument to
the function is not a constant, Mosel will not try to evaluate the function yet; instead, it will be evaluatedas part of the optimization process.
area is a Mosel object of type nlctr.
objdef = area
objdef is_free

Fair Isaac Corporation Conﬁdential and Proprietary Information

9Modeling in Mosel

Overview

What we really want to do is to maximize area. However, although Xpress NonLinear is happy inprinciple with a non-linear objective function, the Xpress Optimizer is not, unless it is handled in a
special way. Xpress NonLinear therefore imposes the requirement that the objective function itself
must be linear. This is not really a restriction, because – as in this case – it is easy to reformulate a
non-linear objective function as an apparently linear one. Simply replace the function by a new mpvar
and then maximize the value of the mpvar. In general, because the objective could have a positive or
negative value, we make the variable free, so that it can take any value. In this example, we say:objdef = areadeﬁning the variable objdef to be equal to the non-linear expression area

objdef is_free

deﬁning objdef to be a free variablemaximize(objdef)

maximizing the linear objective

This is ﬁrstly setting the standard bounds on the variables rho and theta. To reduce problems withsides of zero length, we impose a minimum of 0.1 on rho(i) instead of the default minimum of zero.
forall (i in 1..N-1) do
rho(i) >= 0.1
rho(i) <= 1
setinitval(rho(i), 4⁎i⁎(N+1-i)/((N+1)^2))
setinitval(theta(i), M_PI⁎i/N)
end-doWe also give Xpress NonLinear initial values by using the setinitval procedure. The ﬁrst argument
is the name of the variable, and the second is the initial value to be used. The initial values for theta
are divided equally between 0 and π . The initial values for rho are designed to go from 0 (when i = 0 orN) to 1 (when i is about half way) and back.
forall (i in 1..N-2, j in i+1..N-1) do
D(i,j) := rho(i)^2 + rho(j)^2 - rho(i)⁎rho(j)⁎2⁎cos(theta(j)-theta(i)) <lt/>= 1
end-doThis is creating the general constraints D(i,j) which constrain the other sides of the triangles to be ≤1.
These constraints could be made anonymous – that is, the assignment to an object of type nlctr
could be omitted – but then it would not be possible to report the values.
forall (i in 2..N-1) dotheta(i) >= theta(i-1) + 0.01
end-doThese anonymous constraints put the values of the theta variables in non-decreasing order. To avoid
problems with triangles which have zero angles, we make each bearing at least 0.01 greater than its
predecessor.
This is the boundary condition on the bearing of the ﬁnal vertex.
theta(N-1) <= M_PI

3.2

Setting up and solving the problem
loadprob(objdef)
This procedure loads the currently-deﬁned non-linear problem into the Xpress NonLinear optimization
framework. This includes any purely linear part. Where a general constraint has a linear expression as

Fair Isaac Corporation Conﬁdential and Proprietary Information

10Modeling in Mosel

Overview

its left or right hand side, that linear expression will be retained as linear relationships (constantcoefﬁcients) in the matrix. Thus, for example, in the anonymous constraint deﬁning objdef, theobjdef coefﬁcient will be identiﬁed as a linear term and will appear as a separate item in the problem.
maximise
Optimization is carried out with the maximise or minimise procedures. They can take a string
parameter – for example maxmimise("b") – as described in the Xpress NonLinear and Xpress
Optimizer reference manuals.
With the default settings of the parameters, you will see usually nothing from the optimizer. The
following parameters affect what is produced:

3.3

xnlp_verbose

Normally set to false. If set to true, it produces standard Xpress
NonLinear iteration logging.

xprs_verbose

Normally set to false. If set to true, then information from theoptimizer will also be output.

xslp_log

Normally set to -1. If set to 0, limited information is output fromthe SLP iterations. Settings of 1 or greater produce progressively
more information for each SLP iteration.

xslp_slplog

If xslp_log is set to 0, this determines the frequency with which
SLP progress is reported. The default is 10, which means that itprints every 10 SLP iterations.

Looking at the results
Within Mosel, the values of the variables and named constraints can be obtained using the getsol,
getslack and similar functions. A simple report lists just the area and the positions of the vertices:
writeln("Area = ", getobjval)
forall (i in 1..N-1) dowriteln("V", i, ": r=", getsol(rho(i)), " theta=", getsol(theta(i)))
end-doThis produces the following result for the case N=5:
Area = 0.657166
V1: r=0.616416 theta=0.703301
V2: r=1 theta=1.33111
V3: r=1 theta=1.96079
V4: r=0.620439 theta=2.58648

3.4

Parallel evaluation of Mosel user functions
It is possible to use parallel evaluations of simple Mosel functions that return a single real value. These
functions may take an arbitrary array of nlctr expressions as input. It is the modeler’s responsibility toensure that the user functions to be called in parallel are thread-safe (i.e., they do not depend uponshared resources). Assuming the name of the user function is MyFunc, the user function before
enabling the parallel version is expected to be declared as usefuncMosel(’MyFunc’).
In order for mmxnlp to be able to utilize parallel user function evaluations, the user function must be
implemented as a public function in a Mosel package. Any initialization necessary to enable theFair Isaac Corporation Conﬁdential and Proprietary Information

11Modeling in Mosel

Overview

evaluation of the user function should be performed as part of the package initialization (which is thecode in in the main body of the package).
To enable parallel evaluations, a parallel enabled version of the user function needs to be generatedusing the mmxnlp procedure generateUFparallel, which takes two arguments: the compiled
package .bim name implementing the user function and the name of the user function within the
package. It is good practice to use a separate Mosel model to perform this generation, keeping it
separate from the main model. Multiple generated parallel user functions may be used within a single
model.
The generator will produce a single Mosel ﬁle, the Mosel package MyFunc_master. This package also
includes the worker model which will be responsible for the user function evaluations and will be
resident in memory during the execution. The package also implements the parallel version of the userfunction, called MyFunc_parallel.
After compiling and including the master package into your model, it is this function that should be
used in the actual model as userfuncMosel(’MyFunc_parallel’,XSLP_DELTAS). In mostcases, no other modiﬁcations are necessary, as the parallel function will detect the number of threads
in the system and will start that many worker threads automatically. These will be shut down when yourmodel ﬁnishes. Each worker’s initialization code is performed only once, at the time of its ﬁrst
execution.
It may be necessary to explicitly start the worker threads, either to control the number of threads used,or to pass speciﬁc parameter settings to the user function package. This can be done by the procedure
MyFunc_StartWorkers( ThreadCount : integer, UfPackageParameters : string ).
In case it is necessary to stop the workers, the procedure MyFunc_StopWorkers may be used.
In case the user functions are computationally very expensive, by modifying the connection string in thegenerated module it is possible to utilize distributed/cloud-based computation of the user functions.
The worker model will only be compiled into memory during execution, but may be modiﬁed asnecessary within the master model. For debugging purposes, it may be practical to redirect the worker
to a ﬁle.

Fair Isaac Corporation Conﬁdential and Proprietary Information

12

CHAPTER 4

Modeling in Extended MPS Format
4.1

Basic formulation
Standard MPS format uses a ﬁxed format text ﬁle to hold the problem information. Extended MPS
format has two main differences from the standard form:The records in the ﬁle are free-format – that is, the ﬁelds are not necessarily in ﬁxed columns orof ﬁxed size, and each ﬁeld is delimited by one or more spaces.
The standard MPS format allows only numbers to be used in the "coefﬁcient" ﬁelds – extended
MPS format allows the use of formulae.
There is an optional extra section in extended MPS format, holding additional data and structures
for Xpress NonLinear.

We shall tend to use a fairly ﬁxed format, to aid readability.
NAME POLYGON
The ﬁrst record of any MPS ﬁle is the NAME record, which has the name which may be used to createﬁle names where no other name is speciﬁed, and is also written into the matrix and solution ﬁles.
ROWS
The ROWS record introduces the list of rows of the problem – this includes the objective function as
well as all the constraints.
N OBJ
E OBJEQ
G T2T1
G T3T2
G T4T3
L V1V2
L V1V3
L V2V3
L V2V4L V3V4The ﬁrst character denotes the type of constraint. The possible values are:

Fair Isaac Corporation Conﬁdential and Proprietary Information

13

Modeling in Extended MPS Format

OverviewN

not constraining (always used for the objective function, but may
be used elsewhere).

Eequality: the left hand side (LHS) is equal to the right hand side(RHS).

L

less than or equal to: the LHS is less than or equal to the RHS.

G

greater than or equal to: the LHS is greater than or equal to the
RHS.

The second ﬁeld is the name used for the constraint. In MPS ﬁle format, everything has a name.
Therefore, within each type of entity (rows, columns, etc) each name must be unique. In general, you
should try to ensure that names are unique across all entities, to avoid possible confusion.
You should also try to make the names meaningful, so that you can understand what they mean.
In the example:
OBJ

is the objective function.

OBJEQ

is the "equality" version of the objective function which, as explained below, is required because we are trying to optimize a
non-linear objective.

TiTj

is the constraint that will ensure θi ≥ θj (j = i – 1).

ViVj

is the constraint that will ensure that the distance between Vi and
Vj is ≤ 1.

COLUMNSThe COLUMNS record introduces the list of columns and coefﬁcients in the matrix. In a normal linear
problem, all the variables will appear explicitly as columns in this section. However, in non-linear
problems, it is possible for variables to appear only in formulae and so they may not appear explicitly. In
the example, the variables THETA1 to THETA4 appear explicitly, the variables RHO1 to RHO4 appear only
in formulae. Constraints which involve only one variable in a linear way (that is, they limit the value of avariable to a minimum value, a maximum value or both – possibly equal – values) are usually put in a
separate "BOUNDS" section which appears later.
OBJX OBJ
1.0
OBJX OBJEQ -1.0

The ﬁrst ﬁeld is the name of the column. All "COLUMNS" records for a column must be together. The
second ﬁeld is the name of the row (which was deﬁned in the ROWS section). The third ﬁeld is the value.
It is not necessary to include zero values – only the non-zeros are required
If the coefﬁcients are constant, then it is possible to put two on each record, by putting a second row
name and value after the ﬁrst (as in the example for THETA2 and THETA3 below).
The constraints putting θ i in order are all linear – that is, the coefﬁcients are all constant.
THETA1
THETA2
THETA3
THETA4

T2T1
T2T1
T3T2
T4T3

-1
1
1
1

T3T2
T4T3

-1
-1

The RHS of any constraint must be constant. Therefore, to write THETA2 ≥ THETA1, we must actually
write THETA2 - THETA1 ≥ 0. The constraint T2T1 has coefﬁcient -1 in THETA1 and +1 in THETA2.
We want to maximise the area of the polygon. The formula for this is the sum of the areas of thetriangles with one vertex at V5 – i.e.:

Fair Isaac Corporation Conﬁdential and Proprietary Information

14

Modeling in Extended MPS Format

Overview

0.5 ⁎ RHO1 ⁎ RHO2 ⁎ SIN ( THETA2 - THETA1 ) +0.5 ⁎ RHO2 ⁎ RHO3 ⁎ SIN ( THETA3 - THETA2 ) +0.5 ⁎ RHO3 ⁎ RHO4 ⁎ SIN ( THETA4 - THETA3 )– which is a non-linear function. Xpress NonLinear does not itself have a problem with non-linear
objective functions, but Xpress distinguishes between the original N-type row which contains theobjective function coefﬁcients when the matrix is read in, and the objective function which is actually
optimized. To avoid any confusion between these two "objectives", Xpress NonLinear also requires thatthe objective function as passed to Xpress Optimizer is linear. What we want to do is:
maximize AREA, where AREA is a non-linear function.
We create a new variable – called in this example OBJX – and write:
OBJX = AREA (or, because the RHS must be constant, AREA – OBJX = 0)
and then: maximize OBJX, where OBJX is just a variable.
The constraint linking OBJX and AREA was deﬁned as the equality constraint OBJEQ in the ROWS
section, and AREA is the formula given above. This is where the coefﬁcient of -1 in column OBJX comesfrom.
Every item in the matrix has to be in a coefﬁcient – that is, it is the multiplier of a variable. However, theformula for area, as written, is not a coefﬁcient of anything. There are several ways of dealing with thissituation. We shall start by breaking the formula up into coefﬁcient form – that is, to write it as
X1*formula1 + X2*formula2 + .... Our formula could then be:
RHO1 ⁎ ( 0.5 ⁎ RHO2 ⁎ SIN ( THETA2 - THETA1 ) ) +RHO2 ⁎ ( 0.5 ⁎ RHO3 ⁎ SIN ( THETA3 - THETA2 ) ) +RHO3 ⁎ ( 0.5 ⁎ RHO4 ⁎ SIN ( THETA4 - THETA3 ) )which is of the right form and can be written in the COLUMNS section as follows:
RHO1 OBJEQ = 0.5 ⁎ RHO2 ⁎ SIN ( THETA2 - THETA1 )RHO2 OBJEQ = 0.5 ⁎ RHO3 ⁎ SIN ( THETA3 - THETA2 )RHO3 OBJEQ = 0.5 ⁎ RHO4 ⁎ SIN ( THETA4 - THETA3 )Notice that the formula begins with an equals sign. When this is used in the coefﬁcient ﬁeld, it always
means that a formula is being used rather than a constant. The formula must be written on one line – itdoes not matter how long it is – and each token (variable, constant, operator, bracket or function name)must be delimited by spaces.
When a formula is used, you can only write one coefﬁcient on the record – the option of a second
coefﬁcient only applies when both coefﬁcients are constants.
The constraints for the distances between pairs of vertices are relationships of the form:
RHO1 ⁎ RHO1 + RHO2 ⁎ RHO2 - 2 ⁎ RHO1 ⁎ RHO2 ⁎ COS ( THETA2 - THETA1 ) <= 1

These can again be split into coefﬁcients, for example:
RHO1 ⁎ ( RHO1 - 2 ⁎ RHO2 ⁎ COS ( THETA2 - THETA1 ) ) + RHO2 ⁎ ( RHO2 )This looks a little strange, because RHO2 appears as a coefﬁcient of itself, but that is perfectly all right.
This section of the matrix contains a set of records (one for each of the ViVj constraints) like this:
RHO1
RHO2

V1V2 = RHO1 - 2 ⁎ RHO2 ⁎ COS ( THETA2 - THETA1 )V1V2 = RHO2

Fair Isaac Corporation Conﬁdential and Proprietary Information

15

Modeling in Extended MPS Format

Overview

Note that because the records for each column must all appear together, the coefﬁcients for – forexample – RHO1 in this segment must be merged in with those in the previous (OBJEQ) segment.
RHS
The RHS record introduces the right hand side section.
The RHS section is formatted very much like a COLUMNS section with constant coefﬁcients. There is acolumn name – it is actually the name of the right hand side – and then one or two entries per record.
Again, only the non-zero entries are actually required.
RHS1 T2T1 .001
RHS1 T4T3 .001
RHS1 V1V3 1
RHS1 V2V3 1
RHS1 V3V4 1

T3T2 .001
V1V2 1
V1V4 1
V2V4 1

RHS1 is the name we have chosen for the right hand side. It is possible – although beyond the scope of
this guide – to have more than one right hand side, and to select the one you want. Note that, in order toensure we do have a polygon with N sides, we have made the relationship between theta(i) andtheta(i-1) a strict inequality by adding 0.001 as the right hand side. If we did not, then two of the vertices
could coincide and so the polygon would effectively lose one of its sides.
BOUNDS
The BOUNDS record introduces the BOUNDS section which typically holds the values of constraints
which involve single variables.
Like the RHS section, it is possible to have more than one set of BOUNDS, and to select the one you want
to use. There is therefore in each record a bound name which identiﬁes the set of bounds to which it
belongs. We shall be using only ones set of bounds, called BOUND1.
Bounds constrain a variable by providing a lower limit or an upper limit to its value. By providing a limitof - ∞ for the lower bound, it is possible to create a variable which can take on any value – a "free"variable. The following bound types are provided:LO

a lower bound.

UP
FX

an upper bound.
a ﬁxed bound (the upper and lower limits are equal).

FRa free variable (no lower or upper limit).

MIa "minus inﬁnity" variable – it can take on any non-positive value.

There are other types of bound which are used with integer programming, which is beyond the scope of
this guide.
FR BOUND1 OBJXLO BOUND1 RHO1UP BOUND1 RHO1
LO BOUND1 RHO2UP BOUND1 RHO2
LO BOUND1 RHO3
UP BOUND1 RHO3
LO BOUND1 RHO4UP BOUND1 RHO4UP BOUND1 THETA4

0.01
1
0.01
1
0.01
1
0.01
1
3.1415926

Fair Isaac Corporation Conﬁdential and Proprietary Information

16Modeling in Extended MPS Format

Overview

A record in a BOUNDS section can contain up to four ﬁelds. The ﬁrst one is the bound type (from the list
above). The second is the name of the BOUNDS set being used (ours is always BOUND1). The third is
the name of the variable or column being bounded. Unless the bound type is FR or MI, there is a fourthﬁeld which contains the value of the bound.
Although we know that the area is always positive (or at least non-negative), a more complicatedproblem might have an objective function which could be positive or negative – you could make a proﬁt
or a loss – and so OBJX needs to be able to take on po sitive and negative values. The fact that it ismarked as "free" here does not mean that it can actually take on any value, because it is still
constrained by the rest of the problem.
The upper bounds on RHO1 to RHO4 provide the rest of the restrictions which ensure that the distances
between any two vertices are = 1, and the limit on THETA4 ensures that the whole polygon is above theX-axis. Just to make sure that we do not "lose" a side because the value of RHOi becomes zero, we set
a lower bound of 0.01 on all the rhos, performing a similar function to the RHS values of .001 for TiTj.
ENDATAThe last record in the ﬁle is the ENDATA record.
Although this is sufﬁcient to deﬁne the model, it is usually better to give Xpress NonLinear some idea of
where to start – that is, to provide a set of initial values for the variables. You do not have to provide
values for everything, but you should try to provide them for every variable which appears in a non-linear
coefﬁcient, or which has a non-linear coefﬁcient. In our current example, that means everything except
OBJX.
SLPDATAThe SLPDATA record introduces a variety of different special items for Xpress NonLinear. It comes as
the last section in the model (before the ENDATA record). We are using it at this stage for deﬁning initialvalues. These are done with an IV record.
IV IVSET1 RHO1 0.555
IV IVSET1 RHO2 0.888
IV IVSET1 RHO3 1
IV IVSET1 RHO4 0.888

Just as with the RHS and BOUNDS sections, it is possible to have more than one set of initial values –perhaps because the same structure is used to solve a whole range of problems where the answers are
so different that it does not make much sense to start always from the same place. In this example, we
are using only one set – IVSET1.
The IV record contains four ﬁelds. The ﬁrst one is IV, which indicates the type of SLPDATA being
provided. The second is the name of the set of initial values. The third is the name of the variable andthe fourth is the value being provided.
In the case of IV records, it is possible – and indeed perhaps necessary – to provide initial values
which are zero. The default value (which is used if no value is provided) is not zero, so if you want tostart with a zero value you must say so.

4.2

Using the nonlinear optimizer console-based interface
The nonlinear console is a data-driven console-based interface for operating Xpress NonLinear, an
extension of the Xpress Optimizer console. The optimizer console switches to nonlinear is a valid
nonlinear license is detected.

Fair Isaac Corporation Conﬁdential and Proprietary Information17

Modeling in Extended MPS Format

Overview

The example will use screen-based input and output. You can also put the commands into a ﬁle andexecute it in batch mode, or use the embedded TCL scripting language.
Commands are not case-sensitive except where the case is important (for example, the name of theobjective function). We shall use upper case for commands and lower case for the arguments which
would change for other models. Each parameter in a command must be separated by at least one
space from the preceding parameter or command.
optimizer
This starts the optimizer program. This checks for the existence of the Xpress Optimizer DLLs. If you
are using an OEM version of the Xpress DLL, you may need a special password or license ﬁle from yourusual supplier.
READPROB polygon
This reads a non-linear problem from the ﬁle polygon.mat.
MAXIM
This form of the maximize command does a non-linear optimization with the default settings of all theparameters (it will recognise the problem as an SLP one automatically).
WRITEPRTSOLThis will use the normal Xpress function to write to solution in a text form to a ﬁle with the same nameas the input, but with a ".prt" sufﬁx.
Q
This (the abbreviation for the QUIT command) terminates the optimizer console program.

4.3

Coefﬁcients and terms
So far we have managed to express the formulae as coefﬁcients. However, there are constraints – forexample SIN(A) ≤ 0.5 – which cannot be expressed directly using coefﬁcients. The extended MPS
format has a special reserved column name – the equals sign – which is effectively a variable with aﬁxed value of 1.0, and which can be used to hold formulae of any type, whether they can be expressed
as coefﬁcients or not. The area formula and distance constraints could all be written in a morereadable form by using the "equals column". The area formula is rather long to write in this guide, but
the distance constraints look like this:= V1V2 RHO1 ⁎ RHO1 + RHO2 ⁎ RHO2 - 2 ⁎ RHO1 ⁎ RHO2 ⁎ COS ( THETA2 - THETA1 )= V1V3 RHO1 ⁎ RHO1 + RHO3 ⁎ RHO3 - 2 ⁎ RHO1 ⁎ RHO3 ⁎ COS ( THETA3 - THETA1 )Fair Isaac Corporation Conﬁdential and Proprietary Information18

CHAPTER 5

The Xpress NonLinear API Functions
Instead of writing an extended MPS ﬁle and reading in the model from the ﬁle, it is possible to embed
Xpress NonLinear directly into your application, and to create the problem, solve it and analyze thesolution entirely by using the Xpress NonLinear API functions. This example uses the C header ﬁles and
API calls. We shall assume you have some familiarity with the Xpress Optimizer API functions in
XPRS.DLL.
The structure of the model and the naming system will follow that used in the previous section, so you
should read the chapter 4 ﬁrst.

5.1

Header ﬁles
The header ﬁle containing the Xpress NonLinear deﬁnitions is xslp.h. This must be included together
with the Xpress Optimizer header xprs.h. xprs.h must come ﬁrst.
#include "xprs.h"#include "xslp.h"

5.2

Initialization
Xpress NonLinear and Xpress Optimizer both need to be initialized, and an empty problem created. All
Xpress NonLinear functions return a code indicating whether the function completed successfully. A
non-zero value indicates an error. For ease of reading, we have for the most part omitted the tests on
the return codes, but a well-written program should always test the values.
XPRSprob mprob;
XSLPprob sprob;
if (ReturnValue=XPRSinit(NULL)) goto ErrorReturn;if (ReturnValue=XSLPinit()) goto ErrorReturn;if (ReturnValue=XPRScreateprob(&mprob)) goto ErrorReturn;if (ReturnValue=XSLPcreateprob(&sprob, &mprob)) goto ErrorReturn;

5.3

Callbacks
It is good practice to set up at least a message callback, so that any messages produced by the systemappear on the screen or in a ﬁle. The XSLPsetcbmessage function sets both the Xpress NonLinear
and Xpress Optimizer callbacks, so that all messages appear in the same place.
XSLPsetcbmessage(sprob, XSLPMessage, NULL);

Fair Isaac Corporation Conﬁdential and Proprietary Information

19

The Xpress NonLinear API Functions

Overview

void XPRS_CC XSLPMessage(XSLPprob my_prob, void ⁎my_object, char ⁎msg, int len,int msg_type){switch (msg_type) {case 4: /⁎ error ⁎/case 3: /⁎ warning ⁎/case 2: /⁎ dialogue ⁎/case 1: /⁎ information ⁎/printf("%s\n", msg);
break;
default: /⁎ exiting ⁎/fflush(stdout);
break;}}

This is a simple callback routine, which prints any message to standard output.

5.4

Creating the linear part of the problem
The linear part of the problem, and the deﬁnitions of the rows and columns of the problem are carriedout using the normal Xpress Optimizer functions.
#define MAXROW 20#define MAXCOL 20#define MAXELT 50
int nRow, nCol, nSide, nRowName, nColName;
int Sin, Cos;char RowType[MAXROW];
double RHS[MAXROW], OBJ[MAXCOL], Element[MAXELT];
double Lower[MAXCOL], Upper[MAXCOL];
int ColStart[MAXCOL+1], RowIndex[MAXELT];
char RowNames[500], ColNames[500];

In this example, we have set the dimensions by using #define statements, rather than working out theactual sizes required from the number of sides and then allocating the space dynamically.
nSide = 5;
nRowName = 0;
nColName = 0;

By making the number of sides a variable (nSide) we can create other polygons by changing its value.
It is useful – at least while building a model – to be able to see what has been created. We will
therefore create meaningful names for the rows and columns. nRowName and nColName count along
the character buffers RowNames and ColNames.
nRow = nSide-2 + (nSide-1)⁎(nSide-2)/2 + 1;
nCol = (nSide-1)⁎2 + 2;
for (i=0; i<nRow; i++) RHS[i] = 0;

The number of constraints is:
nSide-2

for the relationships between adjacent thetas.

(nSide-1)⁎(nSide-2)/2

for the distances between pairs of vertices.

1

for the OBJEQ non-linear "objective function".

The number of columns is:Fair Isaac Corporation Conﬁdential and Proprietary Information

20

The Xpress NonLinear API Functions

nSide-1

for the thetas.

nSide-1

for the rhos.

1

for the OBJX objective function column.

1

for the "equals column".

Overview

We are using "C"-style numbering for rows and columns, so the counting starts from zero.
nRow = 0;
RowType[nRow++] = 'E'; /⁎ OBJEQ ⁎/nRowName = nRowName + 1 + sprintf(&RowNames[nRowName], "OBJEQ");
for (i=1; i<nSide-1; i++) {RowType[nRow++] = 'G'; /⁎ T2T1 .. T4T3 ⁎/RHS[i] = 0.001;
nRowName = nRowName + 1 + sprintf(&RowNames[nRowName], "T%dT%d", i+1, i);}This sets the row type indicator for OBJEQ and the theta relationships, with a right hand side of 0.001.
We also create row names in the RowNames buffer. Each name is terminated by a NULL character(automatically placed there by the sprintf function). sprintf returns the length of the string written,
excluding the terminating NULL character.
for (i=1; i<nSide-1; i++) {for (j=i+1; j<nSide; j++) {RowType[nRow] = 'L';
RHS[nRow++] = 1.0;
nRowName = nRowName + 1 + sprintf(&RowNames[nRowName], "V%dV%d", i, j);}}This deﬁnes the L-type rows which constrain the distances between pairs of vertices. The right handside is 1.0 (the maximum value) and the names are of the form ViVj.
for (i=0; i<nCol; i++) {OBJ[i] = 0;/⁎ objective function ⁎/Lower[i] = 0;/⁎ lower bound normally zero ⁎/Upper[i] = XPRS_PLUSINFINITY; /⁎ upper bound = infinity ⁎/}This sets up the standard column data, with objective function entries of zero, and default bounds ofzero to plus inﬁnity. We shall change these for the individual items as required.
nCol = 0;nElement = 0;
ColStart[nCol] = nElement;
OBJ[nCol] = 1.0;
Lower[nCol++] = XPRS_MINUSINFINITY; /⁎ free column ⁎/Element[nElement] = -1.0;
RowIndex[nElement++] = 0;
nColName = nColName + 1 + sprintf(&ColNames[nColName], "OBJX");

This starts the construction of the matrix elements. nElement counts through the Element and
RowIndex arrays, nCol counts through the ColStart, OBJ, Lower and Upper arrays. The ﬁrst
column, OBJX, has the objective function value of +1 and a value of -1 in the OBJEQ row. It is alsodeﬁned to be "free", by making its lower bound equal to minus inﬁnity.
iRow = 0
for (i=1; i<nSide; i++) {nColName = nColName + 1 + sprintf(&ColNames[nColName], "THETA%d", i);
ColStart[nCol++] = nElement;

Fair Isaac Corporation Conﬁdential and Proprietary Information

21

The Xpress NonLinear API Functions}

Overview

if (i < nSide-1) {Element[nElement] = -1;
RowIndex[nElement++] = iRow+1;}
if (i > 1) {Element[nElement] = 1;
RowIndex[nElement++] = iRow;}
iRow++;

This creates the relationships between adjacent thetas. The tests on i are to deal with the ﬁrst and last
thetas which do not have relationships with both their predecessor and successor.
Upper[nCol-1] = 3.1415926;

This sets the bound on the ﬁnal theta to be π . The column index is nCol-1 because nCol has alreadybeen incremented.
nColName = nColName + 1 + sprintf(&ColNames[nColName], "=");
ColStart[nCol] = nElement;
Lower[nCol] = Upper[nCol] = 1.0; /⁎ fixed at 1.0 ⁎/nCol++;

This creates the "equals column" – its name is "=" and it is ﬁxed at a value of 1.0.
for (i=1; i<nSide; i++) {Lower[nCol] = 0.01;/⁎ lower bound ⁎/Upper[nCol] = 1;
ColStart[nCol++] = nElement;
nColName = nColName + 1 + sprintf(&ColNames[nColName], "RHO%d", i);}
ColStart[nCol] = nElement;

The remaining columns – the rho variables – have only non-linear coefﬁcients and so they do notappear in the linear section except as empty columns. They are bounded between 0.01 and 1.0 but haveno entries. The ﬁnal entry in ColStart is one after the end of the last column.
XPRSsetintcontrol(mprob, XPRS_MPSNAMELENGTH, 16);

If you are creating your own names – as we are here – then you need to make sure that Xpress
Optimizer can handle both the names you have created and the names that will be created by Xpress
NonLinear. Typically, Xpress NonLinear will create names which are three characters longer than thenames you have used. If the longest name would be more than 8 characters, you should set the Xpress
Optimizer name length to be larger – it comes in multiples of 8, so we have used 16 here. If you do notmake the name length sufﬁciently large, then the XPRSaddnames function will return an error either
here or during the Xpress NonLinear "construct" phase.
XPRSloadlp(mprob, "Polygon", nCol, nRow, RowType, RHS, NULL,
OBJ, ColStart, NULL, RowIndex, Element, Lower, Upper);This actually loads the model into Xpress Optimizer. We are not using ranges or column element
counts, which is why the two arguments are NULL.
XPRSaddnames(mprob, 1, RowNames, 0, nRow-1);
XPRSaddnames(mprob, 2, ColNames, 0, nCol-1);

The row and column names can now be added.

Fair Isaac Corporation Conﬁdential and Proprietary Information

22

The Xpress NonLinear API Functions

5.5

Overview

Adding the non-linear part of the problem
Be warned – this section is complicated, but it is the most efﬁcient way – from SLP’s point of view – toinput formulae. See the next section for a much easier (but less efﬁcient) way of inputting the formulae
directly.
#define MAXTOKEN 200#define MAXCOEF 20...
int Sin, Cos;
ColIndex[MAXCOL];
FormulaStart[MAXCOEF];
Type[MAXTOKEN];
double Value[MAXTOKEN], Factor[MAXCOEF];

The arrays for the non-linear part can often be re-used from the linear part. The new arrays are
ColIndex (for the column index of the coefﬁcients), FormulaStart and Factor for the coefﬁcients,
and Type and Value to hold the internal forms of the formulae.
XSLPgetindex(sprob, XSLP_INTERNALFUNCNAMES, "SIN", &Sin);XSLPgetindex(sprob, XSLP_INTERNALFUNCNAMES, "COS", &Cos);

We will be using the Xpress NonLinear internal functions SIN and COS. The XSLPgetindex functionﬁnds the index of an Xpress NonLinear entity (character variable, internal or user function).
nToken = 0;nCoef = 0;
RowIndex[nCoef] = 0;
ColIndex[nCoef] = nSide;
Factor[nCoef] = 0.5;
FormulaStart[nCoef++] = nToken;

For each coefﬁcient, the following information is required:
RowIndex

the index of the row.

ColIndex

the index of the column.

FormulaStart

the beginning of the internal formula array for the coefﬁcient.

Factorthis is optional. If used, it holds a constant multiplier for the formula. This is particularly useful where the same formula appears
in several coefﬁcients, but with different signs or scaling. The formula can be used once, with different factors.

for (i=1; i<nSide-1; i++) {Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+i+1;
Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+i;Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MULTIPLY;
Type[nToken] = XSLP_RB;
Value[nToken++] = 0;
Type[nToken] = XSLP_COL;
Value[nToken++] = i+1;
Type[nToken] = XSLP_COL;
Value[nToken++] = i;Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MINUS;
Type[nToken] = XSLP_IFUN;
Value[nToken++] = Sin;

Fair Isaac Corporation Conﬁdential and Proprietary Information

23

The Xpress NonLinear API Functions}

Overview

Type[nToken] = XSLP_OP
Value[nToken++] = XSLP_MULTIPLY;
if (i>1) {Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_PLUS;}

This looks very complicated, but it is really just rather large. We are using the "reverse Polish" or "parsed"
form of the formula for area. The original formula, written in the normal way, would look like this:RHO2 ⁎ RHO1 ⁎ SIN ( THETA2 - THETA1 ) + .......
In reverse Polish notation, tokens are pushed onto the stack or popped from it. Typically, this meansthat a binary operation A x B is written as A B x (push A, push B, pop A and B and push the result). The
ﬁrst term of our area formula then becomes:
RHO2 RHO1 ⁎ ) THETA2 THETA1 - SIN ⁎Notice that the right hand bracket appears as an explicit token. This allows the SIN function to identify
where its argument list starts – and incidentally allows functions to have varying numbers ofarguments.
Each token of the formula is written as two items – Type and Value.
Type is an integer and is one of the deﬁned types of token, as given in the xslp.h header ﬁle.
XSLP_CON, for example, is a constant; XSLP_COL is a column.
Value is a double precision value, and its meaning depends on the corresponding Type. For a Type of
XSLP_CON, Value is the constant value; for XSLP_COL, Value is the column number; for XSLP_OP(arithmetic operation), Value is the operand number as deﬁned in xslp.h; for a function (type
XSLP_IFUN for internal functions, XSLP_FUN for user functions), Value is the function number.
A list of tokens for a formula is always terminated by a token of type XSLP_EOF.
The loop writes each term in order, and adds terms (using the XSLP_PLUS operator) after the ﬁrst passthrough the loop.
for (i=1; i<nSide-1; i++) {for (j=i+1; j<nSide; j++) {RowIndex[nCoef] = iRow++;
ColIndex[nCoef] = nSide;
Factor[nCoef] = 1.0;
FormulaStart[nCoef++] = nToken;
Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+i;Type[nToken] = XSLP_CON;
Value[nToken++] = 2;
Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_EXPONENT;
Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+j;
Type[nToken] = XSLP_CON;
Value[nToken++] = 2;
Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_PLUS;
Type[nToken] = XSLP_CON;
Value[nToken++] = 2;
Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+i;Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MULTIPLY;
Type[nToken] = XSLP_COL;
Value[nToken++] = nSide+j;
Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MULTIPLY;
Type[nToken] = XSLP_RB;
Value[nToken++] = 0;
Type[nToken] = XSLP_COL;
Value[nToken++] = j;

Fair Isaac Corporation Conﬁdential and Proprietary Information

24

The Xpress NonLinear API Functions}}

Overview

Type[nToken] = XSLP_COL;
Value[nToken++] = i;Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MINUS;
Type[nToken] = XSLP_IFUN;
Value[nToken++] = Cos;
Type[nToken] = XSLP_OP
Value[nToken++] = XSLP_MULTIPLY;
Type[nToken] = XSLP_OP;
Value[nToken++] = XSLP_MINUS;
Type[nToken] = XSLP_EOF;
Value[nToken++] = 0;This writes the formula for the distances between pairs of vertices. It follows the same principle as theprevious formula, writing the formula in parsed form as:
RHOi 2 RHOj 2 + 2 RHOi ⁎ RHOj ⁎ ) THETAj THETAi - COS ⁎ XSLPloadcoefs(sprob, nCoef, RowIndex, ColIndex, Factor,
FormulaStart, 1, Type, Value);
The XSLPloadcoefs is the most efﬁcient way of loading non-linear coefﬁcients into a problem. Thereis an XSLPaddcoefs function which is identical except that it does not delete any existing coefﬁcientsﬁrst. There is also an XSLPchgcoef function, which can be used to change individual coefﬁcients one
at a time. Because we are using internal parsed format, the "Parsed" ﬂag in the argument list is set to 1.

5.6

Adding the non-linear part of the problem using character formulae
Provided that all entities – in particular columns and user functions – have explicit and unique names,
the non-linear part can be input by writing the formulae as character strings. This is not as efﬁcient as
using the XSLPloadcoefs() function but is generally easier to understand.
/⁎ Build up nonlinear coefficients ⁎//⁎ Allow space for largest formula - approx 50 characters per side for area ⁎/CoefBuffer = (char ⁎) malloc(50⁎nSide);

We shall be using large formulae, so we need a character buffer large enough to hold the largest
formula we are using. The estimate here is 50 characters per side of the polygon for the area formula,which is the largest we are using.
/⁎ Area ⁎/Factor = 0.5;
BufferPos = 0;
for (i=1; i<nSide-1; i++) {if (i > 1) {BufferPos = BufferPos + sprintf(&CoefBuffer[BufferPos], " + ");}BufferPos = BufferPos + sprintf(&CoefBuffer[BufferPos], "RHO%d ⁎ RHO%d ⁎SIN ( THETA%d - THETA%d )", i+1, i, i+1, i);}
XSLPchgccoef(sprob, 0, nSide, &Factor, CoefBuffer);

The area formula is of the form:(RHO2⁎RHO1⁎SIN(THETA2-THETA1) + RHO3⁎RHO2⁎SIN(THETA3-THETA2) + ... ) / 2
The loop writes the product for each consecutive pair of vertices and also puts in the "+" sign after theﬁrst one.

Fair Isaac Corporation Conﬁdential and Proprietary Information

25

The Xpress NonLinear API Functions

Overview

The XSLPchgccoef function is a variation of XSLPchgcoef but uses a character string for theformula instead of passing it as arrays of tokens. The arguments to the function are:
RowIndex

the index of the row.

ColIndex

the index of the column.

Factorthis is optional. If used, it holds the address of a constant multiplier for the formula. This is particularly useful where the same
formula appears in several coefﬁcients, but with different signs or
scaling. The formula can be used once, but with different factors.
To omit it, use a NULL argument.

CoefBuffer

the formula, written in character form.

In this case, RowIndex is zero and ColIndex is nSide (the "equals" column).
/⁎ Distances ⁎/Factor = 1.0;
for (i=1; i<nSide-1; i++) {for (j=i+1; j<nSide; j++) {sprintf(CoefBuffer, "RHO%d ^ 2 + RHO%d ^ 2 - 2 ⁎ RHO%d ⁎ RHO%d ⁎COS ( THETA%d - THETA%d )", j, i, j, i, j, i);
XSLPchgccoef(sprob, iRow, nSide, &Factor, CoefBuffer);iRow++;}

This creates the formula for the distance between pairs of vertices and writes each into a new row inthe "equals" column.
Provided you have given names to any user functions in your program, you can use them in a formula inexactly the same way as SIN and COS have been used above.

5.7

Checking the data
Xpress NonLinear includes the function XSLPwriteprob which writes out a non-linear problem in text
form which can then be checked manually. Indeed, the problem can then be run using the XSLP console
program, provided there are no user functions which refer back into your compiled program. In
particular, this facility does allow small versions of a problem to be checked before moving on to thefull size ones.
XSLPwriteprob(sprob, "testmat", "");
The ﬁrst argument is the Xpress NonLinear problem pointer; the second is the name of the matrix to be
produced (the sufﬁx ".mat" will be added automatically). The last argument allows various different
types of output including "scrambled" names – that is, internally-generated names will be used rather
than those you have provided. For checking purposes, this is obviously not a good idea.

5.8

Solving and printing the solution
XSLPmaxim(sprob, "");The XSLPmaxim and XSLPminim functions perform a non-linear maximization or minimization on thecurrent problem. The second argument can be used to pass ﬂags as deﬁned in the Xpress NonLinear
Reference Manual.

Fair Isaac Corporation Conﬁdential and Proprietary Information

26

The Xpress NonLinear API Functions

Overview

XPRSwriteprtsol(mprob);
The standard Xpress Optimizer solution print can be obtained by using the XPRSwriteprtsol
function. The row and column activities and dual values can be obtained using the XPRSgetsol
function.
In addition, you can use the XSLPgetvar function to obtain the values of SLP variables – that is, ofvariables which are in non-linear coefﬁcients, or which have non-linear coefﬁcients. If you are using
cascading (see the Xpress NonLinear reference manual for more details) so that Xpress NonLinear
recalculates the values of the dependent SLP variables at each SLP iteration, then the value fromXSLPgetvar will be the recalculated value, whereas the value from XPRSgetsol will be the value
from the LP solution (before recalculation).

5.9

Closing the program
The XSLPdestroyprob function frees any system resources allocated by Xpress NonLinear for the
speciﬁc problem. The problem pointer is then no longer valid. XPRSdestroyprob performs a similarfunction for the underlying linear problem mprob. The XSLPfree function frees any system resources
allocated by Xpress NonLinear. You must then call XPRSfree to perform a similar operation for the
optimizer.
XSLPdestroyprob(sprob);
XPRSdestroyprob(mprob);
XSLPfree();
XPRSfree();If these functions are not called, the program may appear to have worked and terminated correctly.
However, in such a case there may be areas of memory which are not returned to the system when the
program terminates and so repeated executions of the program will result in progressive loss ofavailable memory to the system, which will manifest iself in poorer performance and could ultimately
produce a system crash.

5.10

Adding initial values
So far, Xpress NonLinear has started by using values which it estimates for itself. Because most of thevariables are bounded, these initial values are fairly reasonable, and the model will solve. However, ingeneral, you will need to provide initial values for at least some of the variables. Initial values, and otherinformation for SLP variables, are provided using the XSLPloadvars function.
int VarType[MAXCOL];
double InitialValue[MAXCOL];

To load initial values using XSLPloadvars, we need an array (InitialValue) to hold the initialvalues, and a VarType array which is a bitmap to describe what information is being set for eachvariable.
for(i=1; i<nSide; i++) {...
InitialValue[nCol] = 3.14159⁎((double)i) / ((double)nSide);
VarType[nCol] = 4;
...
}
...
for(i=1; i<nSide; i++) {Fair Isaac Corporation Conﬁdential and Proprietary Information

27

The Xpress NonLinear API Functions}

Overview

InitialValue[nCol] = 1;
VarType[nCol] = 4;

These sections extend the loops for the columns in the earlier example. We set initial values for thethetas so that the vertices are spaced at equal angles; the rhos are all started at 1. We do not need to
set a value for the equals column, because it is ﬁxed at one. However, it is good practice to do so. In
each case we set VarType to 4 because (as described in the Xpress NonLinear Reference Manual) Bit
2 of the type indicates that the initial value is being set.
for(i=0; i<nCol; i++) ColIndex[i] = i
XSLPloadvars(sprob, nCol-1, &ColIndex[1], &VarType[1], NULL, NULL, NULL,&InitialValue[1], NULL);XSLPloadvars can take several other arguments apart from the initial value. It is a general principle in
Xpress NonLinear that using NULL for an argument means that there is no information being provided,
and the current or default value will not be changed.
Because we built up the initial values as we went, the VarType and InitialValue arrays include
column 0, which is OBJX and is not an SLP variable. As all the rest are SLP variables, we can simply
start these arrays at the second item, and reduce the variable count by 1.

Fair Isaac Corporation Conﬁdential and Proprietary Information

28

CHAPTER 6

The Nonlinear Console Program
6.1

The Console Nonlinear
The nonlinear optimizer is an extension to the FICO Xpress Optimizer interactive console.
The console for nonlinear is started from the command line using the following syntax:
C:\> optimizer [problem_name] [@filename]

6.1.1

The nonlinear console extensions
The nonlinear console is an extension of the Xpress optimizer console. The optimizer automaticallyswitches to nonlinear mode if a nonlinear license is detected. All the optimizer console commands
work the same way as in the normal optimizer console. The active working problem for thosecommands is the actual linearization after augmentation, and the linear part of the problem before
augmentation.
Optimizer console commands with an extended effect:
readprob
minim
maxim
lpoptimize
mipoptimize
writeprob
dumpcontrols

Read in an MPS/MAT or LP ﬁleMinimize an LP, a MIP or an SLP problem
Maximize an LP, a MIP or an SLP problem
Minimize or maximize a problem
Solve the problem to MIP optimality
Export the problem into ﬁleDisplay controls which are at a non default value

The MPS ﬁle can be an extended MPS ﬁle containing an NLP model. The minim and maxim commands
will call XPRSminim or XPRSmaxim for LP and MIP problems, and XSLPminim and XSLPmaxim for
SLP problems respectively; with the same applying to lpoptimize and mipoptimize. All thesecommands accept the same ﬂags as the corresponding library function
New commands:

Fair Isaac Corporation Conﬁdential and Proprietary Information

29

The Nonlinear Console Programcascadecascadeorderconstructdumpattributes
reinitialize
setcurrentiv
slp_saveslp_scaling
unconstructvalidate
validatekkt

Overview

Perform cascading
Recalculate the cascading order
Construct the augmented problem
Display problem attributes
Reinitialize an augmented problem
Copy the current solution as initial value
XSLPsave
Display scaling statistics
Remove the augmentation
Validate the current solution
Validate the kkt conditions for the current solution

In order to separate XSLP controls and attributes for the XPRS ones, all XSLP controls and attributes
are pretagged as XSLP_ or SLP_, for example XSLP_ALGORITHM.

6.1.2

Common features of the Xpress Optimizer and the Xpress Nonlinear Optimizer console
All features of the Xpress optimizer console program is supported. For a full description, please refer tothe Xpress optimizer reference manual.
From the command line an initial problem name can be optionally speciﬁed together with an optional
second argument specifying a text "script" ﬁle from which the console input will be read as if it had
been typed interactively.
Note that the syntax example above shows the command as if it were input from the Windows
Command Prompt (i.e., it is preﬁxed with the command prompt string C:\>). For Windows users
Console XSLP can also be started by typing xslp into the "Run ..." dialog box in the Start menu.
The Console XSLP provides a quick and convenient interface for operating on a single problem loaded
into XSLP. The Console XSLP problem contains the problem data as well as (i) control variables forhandling and solving the problem and (ii) attributes of the problem and its solution information.
The Console SLP auto–completion feature is a useful way of reducing key strokes when issuingcommands. To use the auto–completion feature, type the ﬁrst part of an optimizer command namefollowed by the Tab key. For example, by typing "CONST" followed by the Tab key Console Xpress willcomplete to the "CONSTRUCT". Note that once you have ﬁnished inputting the command name portionof your command line, Console Xpress can also auto–complete on ﬁle names. Note that theauto–completion of ﬁle names is case–sensitive.
Console XSLP also features integration with the operating system’s shell commands. For example, by
typing "dir" (or "ls" under Unix) you will directly run the operating system’s directory listing command.
Using the "cd" command will change the working directory, which will be indicated in the prompt string:[xpress bin] cd \[xpress C:\]

Finally, note that when the Console XSLP is ﬁrst started it will attempt to read in an initialization ﬁlenamed optimizer.ini from the current working directory. This is an ASCII "script" ﬁle that may
contain commands to be run at start up, which are intended to setup a customized default Console
Xpress environment for the user (e.g., deﬁning custom controls settings on the Console Xpress
problem).
The Console XSLP interactive command line hosts a TCL script parser (http://www.tcl.tk). With TCL
scripting the user can program ﬂow control into their optimizer scripts. Also TCL scripting provides theuser with programmatic access to a powerful suite of functionality in the TCL library. With scripting
support the Console Xpress provides a high level of control and ﬂexibility well beyond that which can beachieved by combining operating system batch ﬁles with simple piped script ﬁles. Indeed, with

Fair Isaac Corporation Conﬁdential and Proprietary Information

30

The Nonlinear Console Program

Overview

scripting support the Console XSLP is ideal for (i) early application development, (ii) tuning of model
formulations and solving performance and (iii) analyzing difﬁculties and bugs in models.
Note that the TCL parser has been customized and simpliﬁed to handle intuitive access to the controls
and attributes of the Optimizer and XSLP. The following example shows how to proceed with write andread access to the XSLP_ALGROITHM control:[xpress C:\] xslp_algorithm=166[xpress C:\] xslp_algorithm
166

The following shows how this would usually be achieved using TCL syntax:[xpress C:\] set xslp_algorithm 166
166[xpress C:\] $miplog
166

For examples on how TCL can be used for scripting, tuning and testing models, please refer to theXpress Optimizer reference manual.
Console XSLP users may interrupt the running of the commands (e.g., minim) by typing Ctrl–C. Onceinterrupted Console Xpress will return to its command prompt. If an optimization algorithm has beeninterrupted in this way, any solution process will stop at the ﬁrst ’safe’ place before returning to theprompt.
When Console XSLP is being run with script input then Ctrl–C will not return to the command prompt
and the Console Xpress process will simply stop.
Lastly, note that "typing ahead" while the console is writing output to screen can cause Ctrl–C input tofail on some operating systems.
The XSLP console program can be used as a direct substitute for the Xpress Optimizer console
program. The one exception is the ﬁxed format MPS ﬁles, which is not supported by XSLP and thus
neither by the XSLP console.

Fair Isaac Corporation Conﬁdential and Proprietary Information31

II. Advanced

CHAPTER 7

Nonlinear Problems
Xpress NonLinear will solve nonlinear problems. In this context, a nonlinear problem is one in which
there are nonlinear relationships between variables or where there are nonlinear terms in the objectivefunction. There is no such thing as a nonlinear variable — all variables are effectively the same — but
there are nonlinear constraints and formulae. A nonlinear constraint contains terms which are notlinear. A nonlinear term is one which is not a constant and is not a variable with a constant coefﬁcient.
A nonlinear constraint can contain any number of nonlinear terms.
Xpress NonLinear will also solve linear problems — that is, if the problem presented to Xpress
NonLinear does not contain any nonlinear terms, then Xpress NonLinear will still solve it, using thenormal optimizer library.
The solution mechanism used by Xpress-SLP is Successive (or Sequential) Linear Programming. This
involves building a linear approximation to the original nonlinear problem, solving this approximation(to an optimal solution) and attempting to validate the result against the original problem. If the linear
optimal solution is sufﬁciently close to a solution to the original problem, then the SLP is said to have
converged, and the procedure stops. Otherwise, a new approximation is created and the process isrepeated. Xpress-SLP has a number of features which help to create good approximations to theoriginal problem and therefore help to produce a rapid solution.
When license, Xpress NonLinear may also utilize Knitro to solve nonlinear problems.
Note that although the solution is the result of an optimization of the linear approximation, there is no
guarantee that it will be an optimal solution to the original nonlinear problem. It may be a local optimum— that is, it is a better solution than any points in its immediate neighborhood, but there is a better
solution rather further away. However, a converged SLP solution will always be (to within deﬁned
tolerances) a self-consistent — and therefore practical — solution to the original problem.

7.1

Coefﬁcients and terms
Later in this manual, it will be helpful to distinguish between formulae written as coefﬁcients and thosewritten as terms.
If X is a variable, then in the formula X ∗ f(Y), f(Y) is the coefﬁcient of X.
If f(X) appears in a nonlinear constraint, then f(X) is a term in the nonlinear constraint.
If X ∗ f(Y) appears in a nonlinear constraint, then the entity X ∗ f(Y) is a term in the nonlinear constraint.
As this implies, a formula written as a variable multiplied by a coefﬁcient can always be viewed as aterm, but there are terms which cannot be viewed as variables multiplied by coefﬁcients. For example,
in the constraint
X – SIN(Y) = 0,
SIN(Y) is a term and cannot be written as a coefﬁcient.

Fair Isaac Corporation Conﬁdential and Proprietary Information

33

Nonlinear Problems

7.2

Advanced

SLP variables
A variable which appears in a nonlinear coefﬁcient or term is described as an SLP variable.
Normally, any variable which has a nonlinear coefﬁcient will also be treated as an SLP variable.
However, it is possible to set options so that variables which do not appear in nonlinear coefﬁcients or
terms are not treated as SLP variables.
Any variable, whether it is related to a nonlinear term or not, can be deﬁned by the user as an SLPvariable. This is most easily achieved by setting an initial value for the variable.

7.3

Local and global optimality
A globally optimal solution is a feasible solution with the best possible objective value. In general, theglobal optimum for a problem is not unique. By contrast, a locally optimal solution has the best
possible objective value within an open neighbourhood around it. For a convex problem, every local
optimum is a global optimum, but for general nonlinear problems, this is not the case.
For convex problems, which include linear, convex quadratic and convex quadratically constrained
programs, solvers in the FICO Xpress library will always provide a globally optimal solution when one
exists. This also holds true for mixed integer problems whose continuous relaxation is convex.
When a problem is of a more general nonlinear type, there will typically be many local optima, which arepotentially widely spaced, or even in parts of the feasible region which are not connected. For these
problems, both XSLP and Knitro guarantee only that they will return a locally optimal solution. That is,
the result of optimization will be a solution which is better than any others in its immediateneighborhood, but there might exist other solutions which are far distant which have a better objective
value.
Finding a guaranteed global optimum for an arbitrary nonlinear function requires an exhaustive search,which may be orders of magnitude more expensive. To use an analogy, it is the difference between
ﬁnding a valley in a range of mountains, and ﬁnding the deepest valley. When standing in a particularvalley, there is no way to know whether there is a deeper valley somewhere else.
Neither local nor global optima are typically unique. The solution returned by a solver will depend on thecontrol settings used and, particularly for non-convex problems, on the initial values provided. A
connected set of initial points yielding the same locally optimal solutions is sometimes referred to as aregion of attraction for the solution. These regions are typically both algorithm and setting dependent.

7.4

Convexity
Convex problems have many desirable characteristics from the perspective of mathematicaloptimization. Perhaps the most signiﬁcant of these is that should both the objective and the feasible
region be convex, any local optimally solutions found are also known immediately to be globally
optimal.
A constraint f(x) ≤ 0 is convex if the matrix of second derivatives of f, that is to say its Hessian, is
positive semi-deﬁnite at every point at which it exists. This requirement can be understoodgeometrically as requiring every point on every line segment which connects two points satisfying theconstraint to also satisfy the constraint. It follows trivially that linear functions always lead to convex
constraints, and that a nonlinear equality constraint is never convex.
For regions, a similar property must hold. If any two points of the region can be connected by a line
segment which lies fully in the region itself, the region is convex. This extension is straightforward

Fair Isaac Corporation Conﬁdential and Proprietary Information

34

Nonlinear Problems

Advanced

Figure 7.1: Two convex functions on the left, and two non-convex functions on the right.

when the the properties of convex functions are considered.

Figure 7.2: A convex region on the left and a non-convex region on the right.

It is important to note that convexity is necessary for some solution techniques and not for others. In
particular, some solvers require convexity of the constraints and objective function to hold only in thefeasible region, whilst others may require convexity to hold across the entire space, including infeasible
points. In the special case of quadratic and quadratically constrained programs, Xpress NonLinear
seamlessly migrates problems to solvers whose convexity requirements match the convexity of the
problem.

7.5

Converged and practical solutions
In a strict mathematical sense, an algorithm is said to have converged if repeated iterations do not alter
the coordinates of its solution signiﬁcantly. A more practical view of convergence, as used in the
nonlinear solvers of the Xpress suite, is to also consider the algorithm to have converged if repeatediterations have no signiﬁcant effect on either the objective value or upon feasibility. This will be called
extended convergence to distinguish it from the strict sense.
For some problems, a solver may visit points at which the local neighborhood is very complex, or evenmalformed due to numerical issues. In this situation, the best results may be obtained whenconvergence of some of the variables is forced. This leads to practical solutions, which are feasible
and converged in most variables, but the remaining variables have had their convergence forced by thesolver, for example by means of a trust region. Although these solutions are not locally optimal in astrict sense, they provide meaningful, useful results for difﬁcult problems in practice.

7.6

The duals of general, nonlinear program
The dual of a mathematical program plays a fundamental role in the theory of continuous optimization.
Each variable in a problem has a corresponding partner in that problem’s dual, and the values of those

Fair Isaac Corporation Conﬁdential and Proprietary Information

35

Nonlinear Problems

Advancedvariables are called the reduced costs and dual multipliers (shadow prices). Xpress NonLinear makes
estimates of these values available. These are normally deﬁned in a similar way to the usual linear
programming case, so that each value represents the rate of change of the objective when either
increasing the corresponding primal variable or relaxing the corresponding primal constraint.
From an algorithmic perspective, one of the most important roles of the dual variables is tocharacterize local optimality. In this context, the dual multipliers and reduced costs are called Lagrange
multipliers, and a solution with both primal and dual feasible variables satisﬁes the Karush-Kuhn-Tucker
conditions. However, it is important to note that for general nonlinear problems, there exist situations inwhich there are no such multipliers. Geometrically, this means that the slope of the objective function isorthogonal to the linearization of the active constraints, but that their curvature still prevents any
movement in the improving direction.
As a simple example, consider:minimizesubject toyx2 + y 2 ≤ 1(x – 2)2 + y2 ≤ 1

which is shown graphically in ﬁgure 7.3.

Figure 7.3: A problem admitting no dual values

This problem has a single feasible solution at (1,0). Reduced costs and dual multipliers could never bemeaningful indicators of optimality, and indeed are not well-deﬁned for this problem. Intuitively, thisarises because the feasible region lacks an interior, and the existence of an interior (also referred to as
the Slater condition) is one of several alternative conditions which can be enforced to ensure that suchsituations do not occur. The other common condition for well-deﬁned duals is that the gradients of theactive constraints are linearly independent.
Problems without valid duals do not often arise in practice, but it is important to be aware of thepossibility. Analytic detection of such issues is difﬁcult, and they manifest instead in the form of
unexpectedly large or otherwise implausible dual values.

Fair Isaac Corporation Conﬁdential and Proprietary Information

36

CHAPTER 8

Extended MPS ﬁle format
One method of inputting a problem to Xpress NonLinear is from a text ﬁle which is similar to the normal
MPS format matrix ﬁle. The Xpress NonLinear ﬁle uses free format MPS-style data. All the features ofnormal free-format MPS are supported. There are no changes to the sections except as indicatedbelow.
Note: the use of free-format requires that no name in the matrix contains any leading or embedded
spaces and that no name could be interpreted as a number. Therefore, the following names are invalid:

B 02

because it contains an embedded space;

1E02

because it could be interpreted as 100 (the scientiﬁc or ﬂoating-point format number,
1.0E02).

It is possible to use column and row names inlcuding mathematical operators. A variable name a+b is
valid. However, as an expression a + b would be interpreted as the addition of variables a and b - notethe spaces between the variable names - it is best practice to avoid such names when possible. SLP
will produce a warning if such names are encountered in the MPS ﬁle.

8.1

Formulae
One new feature of the Extended MPS format is the formula. A formula is written in much the same way
as it would be in any programming language or spreadsheet. It is made up of (for example) constants,functions, the names of variables, and mathematical operators. The formula always starts with anequals sign, and each item (or token) is separated from its neighbors by one or more spaces.
Tokens may be one of the following:

A constant;The name of a variable;An arithmetic operator "+", "-", "*", "/";

The exponentiation operator "**" or "ˆ";

An opening or closing bracket "(" or ")";

A comma "," separating a list of function arguments;



The name of a supported internal function such as LOG, SIN, EXP;The name of a user-supplied function;

Fair Isaac Corporation Conﬁdential and Proprietary Information

37

Extended MPS ﬁle format

AdvancedA colon ":" preceding the return argument indicator of a multi-valued function;



The name of a return argument from a multi-valued function.

The following are valid formulae:= SIN ( A / B ) SIN is a recognized internal function which takes one argument and returns one
result (the sin of its argument).
= AˆB

ˆis the exponentiation symbol. Note that the formula may have valid syntax but it still
may not be possible to evaluate it (for example if A = –1 and B = 0.5).

= MyFunc1 ( C1 , – C2 , C3 : 1 ) MyFunc1 must be a function which can take threearguments and which returns an array of results. This formula is asking for the ﬁrst itemin the array.
= MyFunc2 ( C1 , – C2 , C3 : RVP ) MyFunc1 must be a function which can take threearguments and which returns an array of results. This formula is asking for the item in
the array which is named RVP.
The following are not valid formulae:
SIN ( A )Missing the equals sign at the start= SIN(A)No spaces between adjacent tokens

= A ∗

∗ B

"**" is exponentiation, "* *" (with an embedded space) is not a recognized operation.

= MyFunc1 ( C1 , – C2 , C3 , 1 ) If MyFunc1 is as shown in the previous set of examples, it
returns an array of results. The last argument to the function must be delimited by acolon, not a comma, and is the name or number of the item to be returned as the valueof the function.

There is no limit in principle to the length of a formula. However, there is a limit on the length of a record
read by XSLPreadprob, which is 31000 characters. Parsing very long records can be slow, andconsideration should be given to pre-parsing them and passing the parsed formula to Xpress
NonLinear rather than asking it to parse the formula itself.

8.2

COLUMNS
Normal MPS-style records of the form
columnrow1

value1[

row2

value2 ]are supported. Non-linear relationships are modeled by using a formula instead of a constant in thevalue1 ﬁeld. If a formula is used, then only one coefﬁcient can be described in the record (that is, there
can be no row2 value2). The formula begins with an equals sign ("=") and is as described in theprevious section.
A formula must be contained entirely on one record. The maximum record length for ﬁles read by
XSLPreadprob is 31000. Note that there are limits applied by the Optimizer to the lengths of thenames of rows and columns.
Variables used in formulae may be included in the COLUMNS section as variables, or may exist only as
items within formulae. A variable which exists only within formulae is called an implicit variable.

Fair Isaac Corporation Conﬁdential and Proprietary Information

38

Extended MPS ﬁle format

Advanced

Sometimes the non-linearity cannot be written as a coefﬁcient. For example, in the constraint
Y – LOG(X) = 0,
LOG(X) cannot be written in the form of a coefﬁcient. In such a case, the reserved column name "="may be used in the ﬁrst ﬁeld of the record as shown:
Y

MyRow

1

=

MyRow

= – LOG ( X )Effectively, "=" is a column with a ﬁxed activity of 1.0 .
When a ﬁle is read by XSLPreadprob, more than one coefﬁcient can be deﬁned for the same
column/row intersection. As long as there is at most one constant coefﬁcient (one not written as aformula), the coefﬁcients will be added together. If there are two or more constant coefﬁcients for thesame intersection, they will be handled by the Optimizer according to its own rules (normally additive,
but the objective function retains only the last coefﬁcient).

8.3

BOUNDS
Bounds can be included for variables which are not deﬁned explicitly in the COLUMNS section of thematrix. If they are not in the COLUMNS section, they must appear as variables within formulae (implicit
variables). A BOUNDS entry for an item which is not a column or a variable will produce a warning
message and will be ignored.
Global entities (such as integer variables and members of Special Ordered Sets) must be deﬁned
explicitly in the COLUMNS section of the matrix. If a variable would otherwise appear only in formulae in
coefﬁcients, then it should be included in the COLUMNS section with a zero entry in a row (for example,
the objective function) which will not affect the result.

8.4

SLPDATASLPDATA is a new section which holds additional information for solving the non-linear problem using
SLP.
Many of the data items have a setname. This works in the same way as the BOUND, RANGE or RHS name,in that a number of different values can be given, each with a different set name, and the one which isactually used is then selected by specifying the appropriate setname before reading the problem.
Record type IV and the tolerance records Tx, Rx can have "=" as the variable name. This provides adefault value for the record type, which will be used if no speciﬁc information is given for a particularvariable.
Note that only linear BOUND types can be included in the SLPDATA section. Bound types for global
entities (discrete variables and special ordered sets) must be provided in the normal BOUNDS section
and the variables must also appear explicitly in the COLUMNS section.
All of the items in the SLPDATA section can be loaded into a model using Xpress NonLinear function
calls.

8.4.1

CV (Character variable)CV

setnamevariablevalue

The CV record deﬁnes a character variable. This is only required for user functions which havecharacter arguments (for example, ﬁle names). The value ﬁeld begins with the ﬁrst non-blank character
after the variable name, and the value of the variable is made up of all the characters from that point toFair Isaac Corporation Conﬁdential and Proprietary Information

39

Extended MPS ﬁle format

Advancedthe end of the record. The normal free-format rules do not apply in the value ﬁeld, and all spacing will
be retained exactly as in the original record.
Examples:CV CVSET1 MyCV1 Program Files\MyLibs\MyLib1
This deﬁnes the character variable named MyCV1. It is required because there is an embedded space inthe path name which it holds.
CV CVSET1 MyCV1 Program Files\MyLibs\MyLib1
CV CVSET2 MyCV1 Program Files\MyLibs\MyLib2
This deﬁnes the character variable named MyCV1. There are two deﬁnitions, and the appropriate one isselected by setting the string control variable XSLP_CVNAME before calling XSLPreadprob to load the
problem.

8.4.2

DR (Determining row)DR

variablerowname [weighting][limit]

The DR record deﬁnes the determining row for a variable.
In most non-linear problems, there are some variables which are effectively deﬁned by means of an
equation in terms of other variables. Such an equation is called a determining row. If Xpress NonLinear
knows the determining rows for the variables which appear in coefﬁcients, then it can provide betterlinear approximations for the problem and can then solve it more quickly. Optionally, a non-zero integer
value can be included in the weighting ﬁeld. Variables which have weights will generally be evaluated inorder of increasing weight. Variables without weights will generally be evaluated after those which dohave weights. However, if a variable A (with or without a weight) is dependent through its determining
row on another variable B, then B will always be evaluated ﬁrst. The optional limit ﬁeld provides avariable speciﬁc value for XSLP_CASCADENLIMIT.
Example:DR X Row1
This deﬁnes Row1 as the determining row for the variable X. If Row1 is
X–Y∗Z =6
then Y and Z will be recalculated ﬁrst before X is recalculated as Y ∗ Z + 6.

8.4.3

EC (Enforced constraint)EC

rownameThe EC record deﬁnes an enforced constraint. Penalty error vectors are never added to enforced
constraints, so the effect of such constraints is maintained at all times.
Note that this means the linearized version of the enforced constraint will be active, so it is important toappreciate that enforcing too many constraints can easily lead to infeasible linearizations which will
make it hard to solve the original nonlinear problem.
Example:EC Row1
This deﬁnes Row1 as an enforced constraint. When the SLP is augmented, no penalty error vectors will
be added to the constraint, so the linearized version of Row1 will constrain the linearized problem in thesame sense (L, G or E) as the nonlinear version of Row1 constrains the original nonlinear problem.

8.4.4

FR (Free variable)FRboundnamevariable

Fair Isaac Corporation Conﬁdential and Proprietary Information

40

Extended MPS ﬁle format

Advanced

An FR record performs the same function in the SLPDATA section as it does in the BOUNDS section. It
can be used for bounding variables which do not appear as explicit columns in the matrix.

8.4.5

FX (Fixed variable)
FX

boundnamevariablevalue

An FX record performs the same function in the SLPDATA section as it does in the BOUNDS section. It
can be used for bounding variables which do not appear as explicit columns in the matrix.

8.4.6

IV (Initial value)IV

setnamevariable [value |= formula]

An IV record speciﬁes the initial value for a variable. All variables which appear in coefﬁcients or terms,
or which have non-linear coefﬁcients, should have an IV record.
A formula provided as the initial value for a variable can contain references to other variables. It will be
evaluated based on the initial values of those variables (which may themselves be calculated byformula). It is the user’s responsibility to ensure that there are no circular references within theformulae. Formulae are typically used to calculate consistent initial values for dependent variables
based on the values of independent variables.
If an IV record is provided for the equals column (the column whose name is "=" and which has a ﬁxed
value of 1.0), the value provided will be used for all SLP variables which do not have an explicit initialvalue of their own.
If there is no explicit or implied initial value for an SLP variable, the value of control parameterXSLP_DEFAULTIV will be used.
If the initial value is greater than the upper bound of the variable, the upper bound will be used; if theinitial value is less than the lower bound of the variable, the lower bound will be used.
If both a formula and a value are provided, then the explicit value will be used.
Example:IV IVSET1 Col99 1.4971
IV IVSET2 Col99 2.5793
This sets the initial value of column Col99. The initial value to be used is selected using control
parameter XSLP_IVNAME. If no selection is made, the ﬁrst initial value set found will be used.
If Col99 is bounded in the range 1 ≤ Col99 ≤ 2 then in the second case (when IVSET2 isselected), an initial value of 2 will be used because the value given is greater than the upper bound.
IV IVSET2 Col98 = Col99 ⁎ 2This sets the value of Col98 to twice the initial value of Col99 when IVSET2 is the selected initialvalue set.

8.4.7

LO (Lower bounded variable)LOboundnamevariablevalue

A LO record performs the same function in the SLPDATA section as it does in the BOUNDS section. It
can be used for bounding variables which do not appear as explicit columns in the matrix.

8.4.8

Rx, Tx (Relative and absolute convergence tolerances)Rx

setnamevariablevalue

Fair Isaac Corporation Conﬁdential and Proprietary Information

41

Extended MPS ﬁle format

TxsetnameAdvancedvariablevalue

The Tx and Rx records (where "x" is one of the deﬁned tolerance types) deﬁne speciﬁc tolerances forconvergence of the variable. See the section "convergence criteria" for a list of convergence tolerances.
The same tolerance set name (setname) is used for all the tolerance records.
Example:RA TOLSET1 Col99 0.005
TA TOLSET1 Col99 0.05
RI TOLSET1 Col99 0.015
RA TOLSET1 Col01 0.01
RA TOLSET2 Col01 0.015
These records set convergence tolerances for variables Col99 and Col01. Tolerances RA (relative
convergence tolerance), TA (absolute convergence tolerance) and RI (relative impact tolerance) are set
for Col99 using the tolerance set named TOLSET1.
Tolerance RA is set for variable Col01 using tolerance sets named TOLSET1 and TOLSET2.
If control parameter XSLP_TOLNAME is set to the name of a tolerance set before the problem is readusing XSLPreadprob, then only the tolerances on records with that tolerance set will be used. If
XSLP_TOLNAME is blank or not set, then the name of the set on the ﬁrst tolerance record will be used.

8.4.9

SB (Initial step bound)SB

setnamevariablevalue

An SB record deﬁnes the initial step bounds for a variable. Step bounds are symmetric (i.e. the bounds
on the delta are –SB ≤ delta ≤ +SB). If a value of 1.0E+20 is used (equivalent to XPRS_PLUSINFINITY
in programming), the delta will never have step bounds applied, and will almost always be regarded asconverged.
If there is no explicit initial step bound for an SLP variable, a value will be estimated either from the sizeof the coefﬁcients in the initial linearization, or from the values of the variable during the early SLP
iterations. The value of control parameter XSLP_DEFAULTSTEPBOUND provides a lower limit for the
step bounds in such cases.
If there is no explicit initial step bound, then the closure convergence tolerance cannot be applied to thevariable.
Example:SB SBSET1 Col99 1.5
SB SBSET2 Col99 7.5This sets the initial step bound of column Col99. The value to be used is selected using control
parameter XSLP_SBNAME. If no selection is made, the ﬁrst step bound set found will be used.

8.4.10UF (User function)UFfuncname[= extname](arguments) linkage[= [param1][= [param2][= [param3]]]]

A UF record deﬁnes a user function.
The deﬁnition includes the list of required arguments, and the linkage or calling mechanism. For detailsof the ﬁelds, see the section on Function Declaration in Xpress NonLinear.
Example:UF MyFunc ( DOUBLE , INTEGER ) DLL = UserLib
This deﬁnes a user function called MyFunc. It takes two arguments (an array of type double precision
and an array of type integer). The linkage is DLL (free-standing user library or DLL) and the function is in
ﬁle UserLib.

Fair Isaac Corporation Conﬁdential and Proprietary Information

42

Extended MPS ﬁle format

8.4.11

Advanced

UP (Free variable)UPboundnamevariablevalue

An UP record performs the same function in the SLPDATA section as it does in the BOUNDS section. It
can be used for bounding variables which do not appear as explicit columns in the matrix.

8.4.12WT (Explicit row weight)
WT

rownamevalue

The WT record is a way of setting the initial penalty weighting for a row. If value is positive, then thedefault initial weight is multiplied by the value given. If value is negative, then the absolute value will
be used instead of the default weight.
Increasing the penalty weighting of a row makes it less attractive to violate the constraint during the
SLP iterations.
Examples:WT Row1 3
This changes the initial weighting on Row1 by multiplying by 3 the default weight calculated by
Xpress-SLP during problem augmentation.
WT Row1 -3
This sets the initial weighting on Row1 to 3.

8.4.13DL (variable speciﬁc Determining row cascade iteration Limit)
DL

columnnamelimit

A DL record speciﬁﬁes a variable speciﬁc iteration limit to be emposed on the number of iterations
when cascading the variable. This can be used to overwrite the setting of XSLP_CASCADENLIMIT for a
speciﬁc variable.

Fair Isaac Corporation Conﬁdential and Proprietary Information

43

CHAPTER 9

Xpress-SLP Solution ProcessThis section gives a brief overview of the sequence of operations within Xpress-SLP once the data has
been set up. The positions of the possible user callbacks are also shown.
Check if problem is an SLP problem or not. Call the appropriate XPRS library function if not, and DONE.
[Call out to user callback if set by XSLPsetcbslpstart]
Augment the matrix (create the linearized structure) if not already done
If determining row data supplied, calculate cascading order and detect determining columns
DO[Call out to user callback if set by XSLPsetcbiterstart]
If previous solution available, pre-process solution
Execute line search[Call out to user callback if set by XSLPsetcbcascadestart]
Sequentially update values of SLP variables (cascading) and re-calculate coefﬁcients
For each variable (in a suitable evaluation order):Update solution value (cascading) and re-calculate coefﬁcients[Call out to user callback if set by XSLPsetcbcascadevar][Call out to user callback if set by XSLPsetcbcascadeend]Update penalties
Update coefﬁcients, bounds and RHS in linearized matrix
Solve linearized problem using the Xpress Optimizer
Recover SLP variable and delta solution values
Test convergence against speciﬁed tolerances and other criteria
For each variable:
Test convergence against speciﬁed tolerances[Call out to user callback if set by XSLPsetcbitervar]
For each variable with a determining column:
Check value of determining column and ﬁx variable when necessary, or[Call out to user callback if set by XSLPsetcbdrcol]
Reset variable convergence status if a change is made to a variable
If not all variables have converged, check for other extended convergence criteria
If the solution has converged, then BREAK
For each SLP variable:
Update history
Reset step bounds[Call out to user callback if set by XSLPsetcbiterend]
Change row types for DC rows as required
If SLP iteration limit is reached, then BREAK
ENDDO[Call out to user callback if set by XSLPsetcbslpend]

For MISLP (mixed-integer SLP) problems, the above solution process is normally repeated at each

Fair Isaac Corporation Conﬁdential and Proprietary Information

44

Xpress-SLP Solution Process

Advancednode. The standard procedure for each node is as follows:
Initialize node[Call out to user callback if set by XSLPsetcbprenode]
Solve node using SLP procedure
If an optimal solution is obtained for the node then[Call out to user callback if set by XSLPsetcboptnode]
If an integer optimal solution is obtained for the node then[Call out to user callback if set by XSLPsetcbintsol]
When node is completed[Call out to user callback if set by XSLPsetcbslpnode]

When a problem is destroyed, there is a call out to the user callback set by XSLPsetcbdestroy.

9.1

Analyzing the solution process
Xpress-SLP provides a comprehensive set of callbacks to interact with, and to analyze the solution
process. However, there are a set of purpose build options that are intended to assist and make theanalysis more efﬁcient.
For infeasible problems, it often helps to identify the source of conﬂict by running XPRESS’ Irreducible
Infeasibiliy Set (IIS) ﬁnder tool. The set found by IIS often helps to either point to a problem in theoriginal model formulation, or if the infeasibility is a result of conﬂicting step bounds or linearization
updates; please see control XSLP_ANALYZE.
Xpress-SLP can collect the various solutions it generates during the solution pool to an XPRS solution
pool object. The solution pool is accessible using the XSLP_SOLUTIONPOOL pointer attribute. The
solutions to collect are deﬁned by XSLP_ANALYZE. It is also possible to let XSLP write the collected
solutions to disk for easier access.
It is often advantageous to trace a certain variable, constraint or a certain property through the solution
process. XSLP_TRACEMASK and XSLP_TRACEMASKOPS allows for collecting detailed information
during the solution process, without the need to stop XSLP between iterations.
For in depth debugging purposes or support requests, it is possible to create XSLP save ﬁles andlinearizations at verious iterations, controlled by XSLP_AUTOSAVE and XSLP_ANALYZE.

9.2

The initial point
The solution process is sensitive to the initial values which are selected for variables in the problem,and particularly so for non-convex problems. It is not uncommon for a general nonlinear problem tohave a feasible region which is not connected, and in this case the starting point may largely determine
which region, connected set, or basin of attraction the ﬁnal solution belongs to.
Note that it may not always be beneﬁcial to completely specify an initial point, as the solvers
themselves may be able to detect suitable starting values for some or all of the variables.

9.3

Derivatives
Both XSLP and Knitro require the availability of derivative information for the constraints and objectivefunction in order to solve a problem. In the Xpress NonLinear framework, several advanced approaches

Fair Isaac Corporation Conﬁdential and Proprietary Information

45

Xpress-SLP Solution Process

Advancedto the production of both ﬁrst and second order derivatives (the Jacobian and Hessian matrices) areavailable, and which approach is used can be controlled by the user.

9.3.1

Finite Differences
The simplest such method is the use of ﬁnite differences, sometimes called numerical derivatives. Thisis a relatively coarse approximation, in which the function is evaluated in a small neighborhood of thepoint in question. The standard argument from calculus indicates that an increasingly accurate
approximation to the derivative of the function will be found as the size of the neighborhood decreases.
This argument ignores the effects of ﬂoating point arithmetic, however, which can make it difﬁcult toselect values sufﬁciently small to give a good approximation to the function, and yet sufﬁciently large
to avoid substantial numerical error.
The high performance implementation in XSLP makes use of subexpression caching to improve
performance, but ﬁnite differences are inherently inefﬁcient. They may however be necessary when thefunction itself is not known in closed form. When analytic approaches cannot be used, due to the useof expensive black box functions which do not provide derivatives (note that XSLP does allow userfunctions to provide their own derivatives), the cost of function evaluations may become a dominantfactor in solve time. It is important to note that each second order numerical derivative costs twice asmuch as a ﬁrst order numerical derivative, and this can make XSLP more attractive than Knitro for suchproblems.

9.3.2

Symbolic Differentiation
Xpress NonLinear will instead provide analytic derivatives where possible, which are both moreaccurate and more efﬁcient. There are two major approaches to such calculations, and high quality
implementations of both are available in this framework.
A symbolic differentiation engine calculates the derivative of an expression in closed form, using its
formula representation. This is a very efﬁcient way of recalculating individual entries of the Jacobian,and is the default approach to providing derivative information to XSLP.

9.3.3

Automatic Differentiation
An automatic differentiation engine in contrast can simultaneously compute multiple derivatives by
repeated application of the chain rule. This is a very efﬁcient means of calculating large numbers ofHessian entries, and is the default approach to providing derivative information to Knitro.

9.4

Points of inﬂection
A point of inﬂection in a given variable occurs when the ﬁrst and second order partial derivatives withrespect to that variable become zero, but there exist nonzero derivatives of higher order. At such points,
the approximations the iterative nonlinear methods create do not encapsulate enough information
about the behavior of the function, and both ﬁrst and second order methods may experience
difﬁculties. For example, consider the following problem
minimizesubject tox3–1 ≤ x ≤ 1

for which the optimal solution is -1.
When the initial value of x is varied, XSLP and Knitro produce the solutions presented in Table 9.1 forthis problem:

Fair Isaac Corporation Conﬁdential and Proprietary Information

46

Xpress-SLP Solution Process

Advanced

Figure 9.1: Effect of an inﬂection point on solution values.

As a second order method, Knitro examines a local quadratic approximation to the function. Starting at
both 0 and 1, this approximation will closely resemble the x2 function, and so the solution will be
attracted to zero. For XSLP, which is a ﬁrst order method, the approximation at 0 will have a zero
gradient. However, XSLP can detect this situation and will perform the analysis required to substitutean appropriate small nonzero (placeholder) value for the derivative during the ﬁrst iterations. As can beseen, this allows XSLP ﬁnd an optimal solution in all three cases.
This is only one example of the behaviour of these solvers without further tuning. The long steps whichXSLP often takes can be both beneﬁcial and harmful in different contexts. For example, if the function
to be optimized includes many local minima, it is possible to see the opposite pattern for XSLP and
Knitro. Consider
minimizex sin(100x2 )subject to –1 ≤ x ≤ 1
which has many local minima. For this problem, the results obtained are presented in Table 9.2:

Figure 9.2: Local solutions for a function with several local optima

In this case the same long steps made by XSLP lead to it ﬁnding the an identical, but unfortunate, local
optimum no matter which initial point it begins from.

9.5

Trust regions
In a second order method like Knitro, there is a well-deﬁned merit function which can be used tocompare solutions, and which provides a measure of the progress being made by the algorithm. This isa signiﬁcant advantage over ﬁrst order methods, in which there is generally no such function.
Despite their speed and resilience to points of inﬂection, ﬁrst order methods can also experience
difﬁculties at points in which the current approximation is not well posed. Consider
minimizesubject tox2
x freeminimizesubject to2xx freeat x = 1. A naive linearization is simply

which is unbounded. To address such situations, XSLP will introduce trust regions to model theneighborhood in which the current approximation is believed to be applicable. When coupled with theuse of derivative placeholders described in the previous section, this can lead XSLP to initially makelarge moves from its starting position.

Fair Isaac Corporation Conﬁdential and Proprietary Information

47

CHAPTER 10

Handling Infeasibilities
By default, Xpress-SLP will include penalty error vectors in the augmented SLP structure. This featureadds explicit positive and negative slack vectors to all constraints (or, optionally, just to equality
constraints) which include nonlinear coefﬁcients. In many cases, this is itself enough to retain
feasibility. There is also an opportunity to add penalty error vectors to all constraints, but this is notnormally required.
During cascading (see next section), Xpress-SLP will ensure that the value of a cascaded variable isnever set outside its lower and upper bounds (if these have been speciﬁed).

10.1

Infeasibility Analysis in the Xpress Optimizer
For problems which can be solved using the Xpress Optimizer, that is LP, convex QP and QCQP andtheir MIP counterparts, there is normally no difﬁculty with establishing feasibility. This is because forthese convex problem classes, Xpress can produce global solutions, and any problem declaredinfeasible is globally infeasible. The concept of local infeasibility is primarily of use in the case of
nonlinear problems, and in particular non-convex, nonlinear problems.
When the Xpress Optimizer declares a problem to be infeasible, the tools provided with the Xpress
Optimizer console can be used to analyse the infeasibility, and hence to subsequently alter the model toovercome it. One important step in this respect is the ability to retrieve an irreducible infeasible set (IIS)(using the iis command). An IIS is a statement of a particular conﬂict in the model between a set of
constraints and bounds, which make the problem certainly infeasible. An IIS is minimal in the sensethat if any constraint or bound of the IIS were removed from the subproblem represented by the IIS, theresulting (relaxed) subproblem would be feasible. The Xpress Optimizer also contains a tool to identify
the minimum weighted violations of constraints or bounds that would make the problem feasible(called repairinfeas).
Both iis and repairinfeas can be applied to any LP, convex QP, or convex QCQP problem, as wellas to their mixed integer counterparts. Please refer to the Xpress Optimizer and Mosel reference
manuals for more information.

10.2

Managing Infeasibility with Xpress Knitro
Xpress Knitro has three major controls which govern feasibility.
XKTR_PARAM_FEASTOL

This is the relative feasibility tolerance applied to a problem.

XKTR_PARAM_FEASTOLABSThis is the corresponding absolute feasibility tolerance.

XKTR_PARAM_INFEASTOL

This is the tolerance for declaring a problem infeasible.

Fair Isaac Corporation Conﬁdential and Proprietary Information48

Handling Infeasibilities

Advanced

The feasibility emphasis control, XKTR_PARAM_BAR_FEASIBLE, can be set for models on which Knitro
has encountered difﬁculties in ﬁnding a feasible solution. If it is set to get or get_stay, particularemphasis will be placed upon obtaining feasibility, rather than balancing progress toward feasibility andoptimality as is the default.
If one of the built-in interior point methods is used, as determined by XKTR_PARAM_ALGORITHM, thefeasibility emphasis control can force the iterates to strictly satisfy inequalities. It does not, however,require Knitro to satisfy all equality constraints at intermediate iterates.
The migration between a pure search for feasibility, and a balanced approach to feasibility andoptimality, may be further ﬁne tuned by using the XKTR_PARAM_BAR_SWITCHRULE control. Should amodel still fail to converge to a feasible solution, the XKTR_PARAM_BAR_PENCONS control may be used
to instruct Knitro to introduce penalty breakers of its own. This option has similar behaviour to thecorresponding option in XSLP.

10.3

Managing Infeasibility with Xpress-SLP
There are two sources of infeasibility when XSLP is used
1. Infeasibility introduced by the error of the approximation, most noticeable when signiﬁcant steps
are made in the linearization.
2. Infeasibility introduced by the activation of penalty breakers, where it was not otherwise possible
to make a meaningful step in the linearization.
The infeasibility induced by the former diminishes as the solution converges, provided mild
assumptions regarding the continuity of the functions describing the model are satisﬁed. The focus of
any analysis of infeasibility in XSLP must therefore most often be on the penalty breakers (also called
error vectors).
For some problems, Xpress-SLP may terminate with a solution which is not sufﬁciently feasible for use
in a desired application. The ﬁrst controls to use to try to resolve such an issue are

10.4

XSLP_ECFTOL_A

The absolute linearization feasibility tolerance is compared for each constraint in
the original, nonlinear problem to its violation by the current solution.

XSLP_ECFTOL_R

The relative linearization feasibility tolerance is compared for each constraint in
the original, nonlinear problem to its violation by the current solution, relative tothe maximum absolute value of the positive and negative contributions to theconstraint.

Penalty Infeasibility Breakers in XSLPConvergence will automatically address any errors introduced by movement within the linearization.
When only small movements occur in the solution, then for differentiable functions the drift resulting
from motion on the linearization is also limited.
However, it is not always possible to stay within the linearization and still make an improving step.
XSLP is often able to resolve such situations automatically by the introduction of penalty infeasibility
breakers. These allow the solver to violate the linearized constraints by a small amount. Such variables
are associated with large cost penalties in the linearized problems, which prevents the solution processfrom straying too far from the approximated feasible region.
Note that if penalty breakers are required, the solution process may be very sensitive to the choice of
cost penalties placed on the breakers. In most cases, XSLP’s constraint analysis will automatically

Fair Isaac Corporation Conﬁdential and Proprietary Information

49

Handling Infeasibilities

Advanced

identify appropriate penalties as needed for each row, but for some problems additional tuning might
be required.
Xpress-SLP will attempt to force all penalty breakers to zero in the limit by associating a substantial
cost with them in the objective function. Such costs will be increased repeatedly should the penalty
breaker remain non-zero over a period of time. The current penalty cost for all such variables isavailable as XSLP_CURRENTERRORCOST. The control XSLP_ERRORCOST determines the initial value
for this cost, while the XSLP_ERRORCOSTFACTOR controls the factor by which it increases if active
error vectors remain. The maximum value of the penalty is determined by the control
XSLP_ERRORMAXCOST. If the maximum error cost is reached, it is unlikely that XSLP will converge. It is
possible in this situation to terminate the solve, by setting bit 11 of XSLP_ALGORITHM.
Some problems may be sensitive to the initial value of XSLP_ERRORCOST. If this value is too small
relative to the original objective in the model, feasibility will not be sufﬁciently strongly encouraged
during the solution process. This can cause SLP to explore highly infeasible solutions in the earlystages, since the original objective will dominate any consideration of feasibility. It is even possible inthis case for unboundedness of the linearizations to occur, although SLP is capable of automatic
recovery from such a situation.
When the initial penalty cost is too high, the penalty term will dominate the objective. This in turn will
may lead to initially low quality solutions being explored, with the attendant possibility of numericalerrors accumulating. The control XSLP_OBJTOPENALTYCOST guides the process which selects anautomatic value for XSLP_ERRORCOST, but determining such a value analytically can be difﬁcult. For
some difﬁcult problems, there may be signiﬁcant beneﬁts to selecting the value directly.
Often for infeasible problems, the contribution of the individual constraints to the overall infeasibility is
non-uniform. XSLP can automatically associate a weight with each row based upon the magnitude of
the terms in the constraint. It is both possible to reﬁne these weights, or alternatively to allow XSLP
update them dynamically. The latter case is called escalation, and is controlled by bit 8 of
XSLP_ALGORITHM.
Devising appropriate weights manually can be difﬁcult, and in most cases it is preferable to leave theidentiﬁcation of these values to Xpress-SLP. However if it is necessary to do, the output of XSLP may
provide hints as to appropriate values if detailed logging is enabled. This can be turned on withXSLP_LOG. The most important points in such output are the active error vectors at each iteration,
where the most attractive constraints to modify are those which occur regularly in the log in
association with non-zero error vectors.

Fair Isaac Corporation Conﬁdential and Proprietary Information50

CHAPTER 11

CascadingCascading is the process of recalculating the values of SLP variables to be more consistent with eachother. The procedure involves sequencing the designated variables in order of dependence and then,starting from the current solution values, successively recalculating values for the variables, andmodifying the stored solution values as required. Normal cascading is only possible if a determining
row can be identiﬁed for each variable to be recalculated. A determining row is an equality constraint
which uniquely determines the value of a variable in terms of other variables whose values are alreadyknown. Any variable for which there is no determining row will retain its original solution value. Deﬁning
a determining row for a column automatically makes the column into an SLP variable.
In extended MPS format, the SLPDATA record type "DR" is used to provide information about
determining rows.
In the Xpress NonLinear function library, functions XSLPaddvars, XSLPloadvars, and XSLPchgvar
allow the deﬁnition of a determining row for a column.
The cascading procedure is as follows:








Produce an order of evaluation to ensure that variables are cascaded after any variables on which
they are dependent.
After each SLP iteration, evaluate the columns in order, updating coefﬁcients only as required. If adetermining row cannot calculate a new value for the SLP variable (for example, because thecoefﬁcient of the variable evaluates to zero), then the current value may be left unchanged, or(optionally) the previous value can be used instead.
If a feedback loop is detected (that is, a determining row for a variable is dependent indirectly on
the value of the variable), the evaluation sequence is carried out in the order in which the variables
are weighted, or the order in which they are encountered if there is no explicit weighting.
Check the step bounds, individual bounds and cascaded values for consistency. Adjust thecascaded result to ensure it remains within any explicit or implied bounds.

Normally, the solution value of a variable is exactly equal to its assumed value plus the solution value ofits delta. Occasionally, this calculation is not exact (it may vary by up to the LP feasibility tolerance) andthe difference may cause problems with the SLP solution path. This is most likely to occur in aquadratic problem when the quadratic part of the objective function contains SLP variables. Xpress
NonLinear can re-calculate the value of an SLP variable to be equal to its assumed value plus its delta,
rather than using the solution value itself.
XSLP_CASCADE is a bitmap which determines whether cascading takes place and whether therecalculation of solution values is extended from the use of determining rows to recalculation of thesolution values for all SLP variables, based on the assumed value and the solution value of the delta.
In the following table, in the deﬁnitions under Category, error means the difference between thesolution value and the assumed value plus the delta value. Bit settings in XSLP_CASCADE are used todetermine which category of variable will have its value recalculated as follows:

Fair Isaac Corporation Conﬁdential and Proprietary Information

51

Cascading

Advanced

Bit

Constant nameCategory

0

XSLP_CASCADE_ALL

SLP variables with determining rows

1

XSLP_CASCADE_COEF_VAR

Variables appearing in coefﬁcients where the error
is greater than the feasibility tolerance

2

XSLP_CASCADE_ALL_COEF_VAR

Variables appearing in coefﬁcients where the error
is greater than 1.0E-14

3

XSLP_CASCADE_STRUCT_VAR

Variables not appearing in coefﬁcients where the error is greater than the feasibility tolerance

4

XSLP_CASCADE_ALL_STRUCT_VAR

Variables not appearing in coefﬁcients where the error is greater than 1.0E-14

In the presence of determining rows that include instantiated functions, SLP can attempt to group thecorresponding variables together in the cascading order. This can be achieved by setting

11.1

Bit

Constant name

Effect0

XSLP_CASCADE_SECONDARY_GROUPS

Create secondary order groupping DR rows with instantiated user functions together in the order

Determining rows and determining columns
Normally, Xpress-SLP automatically identiﬁes if the constraint selected as determining row for avariable deﬁnes the value of the SLP variable which it determines or not. However, in certain situations,the value of a single another column determines if the determing row deﬁnes the variable or not; such acolumn is called the determining column for the variable.
This situation is typical when the determined and determining column form a bilinear term: x * y + F( Z )= 0 where y is the determined variable, Z is a set of other variables not including x or y, and F is anarbitrary function; in this case x is the determining column. These variable pairs are detected
automatically. In case the absolute value of x is smaller than XSLP_DRCOLTOL, then variable y will not
be cascaded, instead its value will be ﬁxed and kept at its current value until the value of x becomeslarger than the threshold.
Alternatively, the handling of variables for which a determining column has been identiﬁed can becustomized by using a callback, see XSLPsetcbdrcol.

Fair Isaac Corporation Conﬁdential and Proprietary Information

52

CHAPTER 12

Convergence criteria
12.1

Convergence criteria
In Xpress-SLP there are two levels of convergence criteria. On the higher level, convergence is driven by
the target relative feasibility / validation control XSLP_VALIDATIONTARGET_R, and the target ﬁrst
order validation tolerance XSLP_VALIDATIONTARGET_K. These high level targets drive the traditional
SLP convergence measures, of which there are three types for testing test convergence:

Strict convergence tests on variablesExtended convergence tests on variablesConvergence tests on the solution overall

12.2

Convergence overview

12.2.1

Strict ConvergenceThree tolerances in XSLP are used to determine whether an individual variable has strictly converged,that is they describe the numerical behaviour of convergence in the formal, mathematical sense.

12.2.2XSLP_CTOL

The closure tolerance is compared against the movement of a variable relative to its
initial step bound.

XSLP_ATOL_A

The absolute delta tolerance is compared against the absolute movement of avariable.

XSLP_ATOL_R

The relative delta tolerance is compared against the movement of a variable relative
to its initial value.

Extended Convergence
There are six tolerances in XSLP used to determine whether an individual variable has converged
according to the extended deﬁnition. These tests essentially measure the quality of the linearization,
including the effect of changes to the nonlinear terms that contribute to a variable in the linearization.
In order to be deemed to have converged in the extended sense, all terms in which it appears mustsatisfy at least one of the following:
XSLP_MTOL_A

The absolute matrix tolerance is compared against the approximation error relative
only to the absolute value of the variable.

Fair Isaac Corporation Conﬁdential and Proprietary Information

53

Convergence criteria

12.2.3

AdvancedXSLP_MTOL_R

The relative matrix tolerance is compared against the approximation error relative tothe size of the nonlinear term before any step is taken.

XSLP_ITOL_A

The absolute impact tolerance is compared against the approximation error of thenonlinear term.

XSLP_ITOL_R

The relative impact tolerance is compared against the approximation error relative tothe positive and negative contributions to each constraint.

XSLP_STOL_A

The absolute slack impact tolerance is compared against the approximation error,
but only for non-binding constraints, which is to say those for which the marginalvalue is small (as deﬁned by XSLP_MVTOL).

XSLP_STOL_R

The relative slack impact tolerance is compared against the approximation error
relative to the term’s contribution to its constraints, but only for non-binding
constraints, which is to say those for which the marginal value is small (as deﬁned by
XSLP_MVTOL).

Stopping Criterion
The stopping criterion requires that all variables in the problem have converged in one of the threesenses. Detailed information regarding the conditions under which XSLP has terminated can beobtained from the XSLP_STATUS solver attribute. Note that a solution is deemed to have fully
converged if all variables have converged in the strict sense. If all variables have converged either in thestrict or extended sense, and there are no active step bounds, then the solution is called a practicalsolution. In contrast, the solution may be called converged if it is feasible and the objective is no longer
improving.
The following four control sets can be applied by XSLP to determine whether the objective is stationary,depending on the convergence control parameter XSLP_CONVERGENCEOPS:
VTOL

OTOL

This is the baseline static objective function tolerance, which is compared against thechange in the objective over a given number of iterations, relative to the average objective
value. Satisfaction of VTOL does not imply convergence of the variables.
XSLP_VCOUNTThis is the number of iterations over which to apply this measure ofstatic objective convergence.

XSLP_VLIMITThe static objective function test is applied only after at leastXSLP_VLIMIT + XSLP_SBSTART XSLP iterations have taken place.

XSLP_VTOL_A

This is the absolute tolerance which is compared to the range of theobjective over the last XSLP_VLIMIT iterations.

XSLP_VTOL_R

This is the used for a scaled version of the absolute test which
considers the average size of the absolute value of the objective overthe previous XSLP_VLIMIT iterations.

This static objective function tolerance is applied when there are no unconverged variables
in active constraints, although some variables with active step bounds might remain. It is
compared to the change in the objective over a given number of iterations, relative to theaverage objective value.
XSLP_OCOUNTThis is the number of iterations over which to apply this measure ofstatic objective convergence.

XSLP_OTOL_A

This is the absolute tolerance which is compared to the range of theobjective over the last XSLP_OCOUNT iterations.

Fair Isaac Corporation Conﬁdential and Proprietary Information

54

Convergence criteria

AdvancedXSLP_OTOL_R

XTOL

WTOL

12.2.4This is used for a scaled version of the absolute test which considers
the average size of the absolute value of the objective over theprevious XSLP_OCOUNT iterations.

This static objective function tolerance is applied when a practical solution has been found.
It is compared against the change in the objective over a given number of iterations, relative
to the average objective value.
XSLP_XCOUNTThis is the number of iterations over which to apply this measure ofstatic objective convergence.

XSLP_XLIMITThis is the maximum number of iterations which can have occurred
for this static objective function test to be applied. Once this number
is exceeded, the solution is deemed to have converged if all thevariables have converged by the strict or extended criteria.

XSLP_XTOL_A

This is the absolute tolerance which is compared to the range of theobjective function over the last XSLP_XLIMIT iterations.

XSLP_XTOL_R

This is used for a scaled version of the absolute test which considers
the average size of the absolute value of the objective over the lastXSLP_XLIMIT iterations.

The extended convergence continuation tolerance is applied when a practical solution has
been found. It is compared to the change in the objective during the previous iteration.
XSLP_WCOUNTThis is number of iterations over which to calculate this measure ofstatic objective convergence in the relative version of the test.

XSLP_WTOL_A

This is the absolute tolerance which is compared to the change in theobjective in the previous iteration.

XSLP_WTOL_R

This is used for a scaled version of the test which considers theaverage size of the absolute value of the objective over the lastXSLP_WCOUNT iterations.

Step Bounding
Step bounding in XSLP can be activated in two cases. It may be enabled adaptively in response tovariable oscillation, or it may be enabled by after XSLP_SBSTART iterations, by setting
XSLP_ALGORITHM appropriately. Two major controls deﬁne the behaviour of step bounds:

12.3

XSLP_SBSTART

This deﬁnes the number of iterations which must occur before XSLP
may apply non-essential step bounding. When a linearization isunbounded, XSLP will introduce step bounding regardless of the valueof this control.

XSLP_DEFAULTSTEPBOUND

This is the initial size of the step bounds introduced. Depending upon
the value of XSLP_ALGORITHM, XSLP may use the iterations before
XSLP_SBSTART to reﬁne this initial value on a per variable basis.

Convergence: technical details
In the following sections we shall use the subscript 0 to refer to values used to build the linear
approximation (the assumed value) and the subscript 1 to refer to values in the solution to the linear
approximation (the actual value). We shall also use δ to indicate the change between the assumed andthe actual values, so that for example:
δX = X1 – X0 .

Fair Isaac Corporation Conﬁdential and Proprietary Information

55

Convergence criteria

Advanced

The tests are described in detail later in this section. Tests are ﬁrst carried out on each variable in turn,according to the following sequence:
Strict convergence criteria:
1. Closure tolerance (CTOL).
This tests δX against the initial step bound of X.
2. Delta tolerance (ATOL)This tests δX against X0 .
If the strict convergence tests fail for a variable, it is tested against the extended convergence criteria:
3. Matrix tolerance (MTOL)This tests whether the effect of a matrix coefﬁcient is adequately approximated by thelinearization. It tests the error against the magnitude of the effect.
4. Impact tolerance (ITOL)
This tests whether the effect of a matrix coefﬁcient is adequately approximated by thelinearization. It tests the error against the magnitude of the contributions to the constraint.
5. Slack impact tolerance (STOL)This tests whether the effect of a matrix coefﬁcient is adequately approximated by thelinearization and is applied only if the constraint has a negligible marginal value (that is, it isregarded as "not constraining"). The test is the same as for the impact tolerance, but thetolerance values may be different.
The three extended convergence tests are applied simultaneously to all coefﬁcients involving thevariable, and each coefﬁcient must pass at least one of the tests if the variable is to be regarded asconverged. If any coefﬁcient fails the test, the variable has not converged.
Regardless of whether the variable has passed the system convergence tests or not, if a convergencecallback function has been set using XSLPsetcbitervar then it is called to allow the user todetermine the convergence status of the variable.
6. User convergence test
This test is entirely in the hands of the user and can return one of three conditions: the variable
has converged on user criteria; the variable has not converged; or the convergence status of thevariable is unchanged from that determined by the system.
Once the tests have been completed for all the variables, there are several possibilities for theconvergence status of the solution:(a) All variables have converged on strict criteria or user criteria.
(b) All variables have converged, some on extended criteria, and there are no active step bounds (thatis, there is no delta vector which is at its bound and has a signiﬁcant reduced cost).
(c) All variables have converged, some on extended criteria, and there are active step bounds (that is,there is at least one delta vector which is at its bound and has a signiﬁcant reduced cost).
(d) Some variables have not converged, but these have non-constant coefﬁcients only in constraints
which are not active (that is, the constraints do not have a signiﬁcant marginal value);(e) Some variables have not converged, and at least one has a non-constant coefﬁcient in an active
constraint (that is, the constraint has a signiﬁcant marginal value);

Fair Isaac Corporation Conﬁdential and Proprietary Information

56

Convergence criteria

Advanced

If (a) is true, then the solution has converged on strict convergence criteria.
If (b) is true, then the solution has converged on extended convergence criteria.
If (c) is true, then the solution is a practical solution. That is, the solution is an optimal solution to thelinearization and, within the deﬁned tolerances, it is a solution to the original nonlinear problem. It is
possible to accept this as the solution to the nonlinear problem, or to continue optimizing to see if abetter solution can be obtained.
If (d) or (e) is true, then the solution has not converged. Nevertheless, there are tests which can beapplied to establish whether the solution can be regarded as converged, or at least whether there is
beneﬁt in continuing with more iterations.
The ﬁrst convergence test on the solution simply tests the variation in the value of the objectivefunction over a number of SLP iterations:
7. Objective function convergence test 1 (VTOL)This test measures the range of the objective function (the difference between the maximum andminimum values) over a number of SLP iterations, and compares this against the magnitude of
the average objective function value. If the range is small, then the solution is deemed to have
converged.
Notice that this test says nothing about the convergence of the variables. Indeed, it is almost certainthat the solution is not in any sense a practical solution to the original nonlinear problem. However,experience with a particular type of problem may show that the objective function does settle into a
narrow range quickly, and is a good indicator of the ultimate value obtained. This test can therefore beused in circumstances where only an estimate of the solution value is required, not how it is made up.
One example of this is where a set of schedules is being evaluated. If a quick estimate of the value ofeach schedule can be obtained, then only the most proﬁtable or economical ones need be examinedfurther.
If the convergence status of the variables is as in (d) above, then it may be that the solution is practicaland can be regarded as converged:
8. Objective function convergence test 2 (XTOL)
If there are no unconverged values in active constraints, then the inaccuracies in the linearization(at least for small errors) are not important. If a constraint is not active, then deleting theconstraint does not change the feasibility or optimality of the solution. The convergence test
measures the range of the objective function (the difference between the maximum and minimum
values) over a number of SLP iterations, and compares this against the magnitude of the average
objective function value. If the range is small, then the solution is deemed to have converged.
The difference between this test and the previous one is the requirement for the convergence status of
the variables to be (d).
Unless test 7 (VTOL) is being applied, if the convergence status of the variables is (e) then the solution
has not converged and another SLP iteration will be carried out.
If the convergence status is (c), then the solution is practical. Because there are active step bounds inthe solution, a "better" solution would be obtained to the linearization if the step bounds were relaxed.
However, the linearization becomes less accurate the larger the step bounds become, so it might not
be the case that a better solution would also be achieved for the nonlinear problem. There are twoconvergence tests which can be applied to decide whether it is worth continuing with more SLP
iterations in the hope of improving the solution:
9. Objective function convergence test 3 (OTOL)
If all variables have converged (even if some are converged on extended criteria only, and some ofthose have active step bounds), the solution is a practical one. If the objective function has not

Fair Isaac Corporation Conﬁdential and Proprietary Information

57

Convergence criteria

Advancedchanged signiﬁcantly over the last few iterations, then it is reasonable to suppose that the solution
will not be signiﬁcantly improved by continuing with more SLP iterations. The convergence test
measures the range of the objective function (the difference between the maximum and minimum
values) over a number of SLP iterations, and compares this against the magnitude of the average
objective function value. If the range is small, then the solution is deemed to have converged.
10. Extended convergence continuation test (WTOL)
Once a solution satisfying (c) has been found, we have a practical solution against which tocompare solution values from later SLP iterations. As long as there has been a signiﬁcant
improvement in the objective function, then it is worth continuing. If the objective function overthe last few iterations has failed to improve over the practical solution, then the practical solution
is restored and the solution is deemed to have converged.
The difference between tests 9 and 10 is that 9 (OTOL) tests for the objective function being stable,
whereas 10 (WTOL) tests whether it is actually improving. In either case, if the solution is deemed tohave converged, then it has converged to a practical solution.

12.3.1

Closure tolerance (CTOL)
If an initial step bound is provided for a variable, then the closure test measures the signiﬁcance of themagnitude of the delta compared to the magnitude of the initial step bound. More precisely:
Closure test:
ABS(δX) ≤ B ∗ XSLP_CTOL
where B is the initial step bound for X. If no initial step bound is given for a particular variable, theclosure test is not applied to that variable, even if automatic step bounds are applied to it during thesolution process.
If a variable passes the closure test, then it is deemed to have converged.

12.3.2

Delta tolerance (ATOL)The simplest tests for convergence measure whether the actual value of a variable in the solution issigniﬁcantly different from the assumed value used to build the linear approximation.
The absolute test measures the signiﬁcance of the magnitude of the delta; the relative test measures
the signiﬁcance of the magnitude of the delta compared to the magnitude of the assumed value. Moreprecisely:
Absolute delta test:
ABS(δX) ≤ XSLP_ATOL_A
Relative delta test:
ABS(δX) ≤ X0 ∗ XSLP_ATOL_R
If a variable passes the absolute or relative delta tests, then it is deemed to have converged.

12.3.3Matrix tolerance (MTOL)
The matrix tests for convergence measure the linearization error in the effect of a coefﬁcient. The
effect of a coefﬁcient is its value multiplied by the activity of the column in which it appears.
E =V∗C
where V is the activity of the matrix column in which the coefﬁcient appears, and C is the value of thecoefﬁcient. The linearization approximates the effect of the coefﬁcient as
E = V ∗ C0 + δX ∗ C00

Fair Isaac Corporation Conﬁdential and Proprietary Information

58

Convergence criteria

Advanced

where V is as before, C0 is the value of the coefﬁcient C calculated using the assumed values for the∂C calculated using the assumed values for the variables.
variables and C00 is the value of ∂X
The error in the effect of the coefﬁcient is given by
δE = V1 ∗ C1 – (V1 ∗ C0 + δX ∗ C00 )Absolute matrix test:
ABS(δE) ≤ XSLP_MTOL_A
Relative matrix test:
ABS(δE) ≤ V0 ∗ X0 ∗ XSLP_MTOL_R
If all the coefﬁcients which involve a given variable pass the absolute or relative matrix tests, then thevariable is deemed to have converged.

12.3.4

Impact tolerance (ITOL)
The impact tests for convergence also measure the linearization error in the effect of a coefﬁcient. The
effect of a coefﬁcient was described in the previous section. Whereas the matrix test compares theerror against the magnitude of the coefﬁcient itself, the impact test compares the error against ameasure of the magnitude of the constraint in which it appears. All the elements of the constraint are
examined: for each, the contribution to the constraint is evaluated as the element multiplied by theactivity of the vector in which it appears; it is then included in a total positive contribution or total
negative contribution depending on the sign of the contribution. If the predicted effect of the coefﬁcientis positive, it is tested against the total positive contribution; if the effect of the coefﬁcient is negative, it
is tested against the total negative contribution.
As in the matrix tests, the predicted effect of the coefﬁcient is
V ∗ C0 + δX ∗ C00
and the error isδE = V1 ∗ C1 – (V1 ∗ C0 + δX ∗ C00 )Absolute impact test:
ABS(δE) ≤ XSLP_ITOL_A
Relative impact test:
ABS(δE) ≤ T0 ∗ XSLP_ITOL_R
where

T0 = ABS(X

v0 ∗ c0 )v∈V

c is the value of the constraint coefﬁcient in the vector v; V is the set of vectors such that v0 ∗ c0 > 0 if E
is positive, or the set of vectors such that v0 ∗ c0 < 0 if E is negative.
If a coefﬁcient passes the matrix test, then it is deemed to have passed the impact test as well. If all
the coefﬁcients which involve a given variable pass the absolute or relative impact tests, then thevariable is deemed to have converged.

Fair Isaac Corporation Conﬁdential and Proprietary Information

59

Convergence criteria

12.3.5

Advanced

Slack impact tolerance (STOL)This test is identical in form to the impact test described in the previous section, but is applied only toconstraints whose marginal value is less than XSLP_MVTOL. This allows a weaker test to be applied
where the constraint is not, or is almost not, binding.
Absolute slack impact test:
ABS(δE) ≤ XSLP_STOL_A
Relative slack impact test:
ABS(δE) ≤ T0 ∗ XSLP_STOL_R
where the items in the expressions are as described in the previous section, and the tests are applied
only whenABS(πi ) < XSLP_MVTOL
where πi is the marginal value of the constraint.
If all the coefﬁcients which involve a given variable pass the absolute or relative matrix, impact or slack
impact tests, then the variable is deemed to have converged.

12.3.6

Fixed variables due to determining columns smaller than threshold (FX)
Variables having a determining column, that are temporarily ﬁxed due to the absolute value of thedetermining column being smaller than the threshold XSLP_DRCOLTOL are regarded as converged.

12.3.7User-deﬁned convergence
Regardless of what the Xpress-SLP convergence tests have said about the status of an individual
variable, it is possible for the user to set the convergence status for a variable by using a function
deﬁned through the XSLPsetcbitervar callback registration procedure. The callback function
returns an integer result S which is interpreted as follows:
S<0mark variable as unconverged

S=0

leave convergence status of variable unchanged

S ≥ 11mark variable as converged with status S

Values of S in the range 1 to 10 are interpreted as meaning convergence on the standard
system-deﬁned criteria.
If a variable is marked by the user as converged, it is treated as if it has converged on strict criteria.

12.3.8

Static objective function (1) tolerance (VTOL)This test does not measure convergence of individual variables, and in fact does not in any way imply
that the solution has converged. However, it is sometimes useful to be able to terminate an
optimization once the objective function appears to have stabilized. One example is where a set of
possible schedules are being evaluated and initially only a good estimate of the likely objective function
value is required, to eliminate the worst candidates.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)

Fair Isaac Corporation Conﬁdential and Proprietary Information

60

Convergence criteria

Advanced

where Iter is the XSLP_VCOUNT most recent SLP iterations and Obj is the corresponding objectivefunction value.
Absolute static objective function (3) test:
ABS(δObj) ≤ XSLP_VTOL_A
Relative static objective function (3) test:
ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_VTOL_R
The static objective function (3) test is applied only after at least XSLP_VLIMIT + XSLP_SBSTARTSLP iterations have taken place. Where step bounding is being applied, this ensures that the test is notapplied until after step bounding has been introduced.
If the objective function passes the relative or absolute static objective function (3) test then thesolution will be deemed to have converged.

12.3.9Static objective function (2) tolerance (OTOL)This test does not measure convergence of individual variables. Instead, it measures the signiﬁcanceof the changes in the objective function over recent SLP iterations. It is applied when all the variables
interacting with active constraints (those that have a marginal value of at least XSLP_MVTOL) have
converged. The rationale is that if the remaining unconverged variables are not involved in active
constraints and if the objective function is not changing signiﬁcantly between iterations, then thesolution is more-or-less practical.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_OCOUNT most recent SLP iterations and Obj is the corresponding objectivefunction value.
Absolute static objective function (2) test:
ABS(δObj) ≤ XSLP_OTOL_A
Relative static objective function (2) test:
ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_OTOL_R
If the objective function passes the relative or absolute static objective function (2) test then thesolution is deemed to have converged.

12.3.10

Static objective function (3) tolerance (XTOL)
It may happen that all the variables have converged, but some have converged on extended criteria(MTOL, ITOL or STOL) and at least one of these is at its step bound. It is therefore possible that an
improved result could be obtained by taking another SLP iteration. However, if the objective function
has already been stable for several SLP iterations, then there is less likelihood of an improved result,and the converged solution can be accepted.
The static objective function (1) test measures the signiﬁcance of the changes in the objective function
over recent SLP iterations. It is applied when all the variables have converged, but some have convergedon extended criteria (MTOL, ITOL or STOL) and at least one of these is at its step bound. Because all

Fair Isaac Corporation Conﬁdential and Proprietary Information

61

Convergence criteria

Advancedthe variables have converged, the solution is already converged but the fact that some variables are attheir step bound limit suggests that the objective function could be improved by going further.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_XCOUNT most recent SLP iterations and Obj is the corresponding objectivefunction value.
Absolute static objective function (1) test:
ABS(δObj) ≤ XSLP_XTOL_A
Relative static objective function (1) test:
ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_XTOL_R
The static objective function (1) test is applied only until XSLP_XLIMIT SLP iterations have takenplace. After that, if all the variables have converged on strict or extended criteria, the solution isdeemed to have converged.
If the objective function passes the relative or absolute static objective function (1) test then thesolution is deemed to have converged.

12.3.11

Extended convergence continuation tolerance (WTOL)This test is applied after a converged solution has been found where at least one variable has
converged on extended criteria and is at its step bound limit. As described under XTOL above, it ispossible that by continuing with additional SLP iterations, the objective function might improve. The
extended convergence continuation test measures whether any improvement is being achieved. If not,then the last converged solution will be restored and the optimization will stop.
For a maximization problem, the improvement in the objective function at the current iterationcompared to the objective function at the last converged solution is given by:
δObj = Obj – ConvergedObj(for a minimization problem, the sign is reversed).
Absolute extended convergence continuation test:δObj > XSLP_WTOL_A
Relative extended convergence continuation test:δObj > ABS(ConvergedObj) ∗ XSLP_WTOL_R
A solution is deemed to have a signiﬁcantly better objective function value than the converged solution
if δObj passes the relative and absolute extended convergence continuation tests.
When a solution is found which converges on extended criteria and with active step bounds, thesolution is saved and SLP optimization continues until one of the following:a new solution is found which converges on some other criterion, in which case the SLP
optimization stops with this new solution

Fair Isaac Corporation Conﬁdential and Proprietary Information

62

Convergence criteriaAdvanceda new solution is found which converges on extended criteria and with active step bounds, andwhich has a signiﬁcantly better objective function, in which case this is taken as the new saved
solutionnone of the XSLP_WCOUNT most recent SLP iterations has a signiﬁcantly better objective function
than the saved solution, in which case the saved solution is restored and the SLP optimization
stops

Fair Isaac Corporation Conﬁdential and Proprietary Information

63

CHAPTER 13

Xpress-SLP Structures
13.1

SLP Matrix Structures
Xpress-SLP augments the original matrix to include additional rows and columns to model some or allof the variables involved in nonlinear relationships, together with ﬁrst-order derivatives.
The amount and type of augmentation is determined by the bit map control variable
XSLP_AUGMENTATION:
Bit 0

Minimal augmentation. All SLP variables appearing in coefﬁcients or matrix entries areprovided with a corresponding update row and delta vector.

Bit 1

Even-handed augmentation. All nonlinear expressions are converted into terms. All SLP
variables are provided with a corresponding update row and delta vector.

Bit 2

Create penalty error vectors (+ and -) for each equality row of the original problem
containing a nonlinear coefﬁcient or term. This can also be implied by the setting of bit
3.

Bit 3

Create penalty error vectors (+ and/or - as required) for each row of the original problem
containing a nonlinear coefﬁcient or term. Setting bit 3 to 1 implies the setting of bit 2 to
1 even if it is not explicitly carried out.

Bit 4

Create additional penalty delta vectors to allow the solution to exceed the step bounds
at a suitable penalty.

Bit 8

Implement step bounds as constraint rows.

Bit 9

Create error vectors (+ and/or - as required) for each constraining row of the original
problem.

If Bits 0-1 are not set, then Xpress-SLP will use standard augmentation: all SLP variables (appearing in
coefﬁcients or matrix entries, or variables with non constant coefﬁcients) are provided with acorresponding update row and delta vector.
To avoid too many levels of super- and sub- scripting, we shall use X, Y and Z as variables, F() as afunction, and R as the row name. In the matrix structure, column and row names are shown in italics.
X0 is the current estimate ("assumed value") of X. Fx0 (...) is the ﬁrst derivative of F with respect to X.

13.1.1

Augmentation of a nonlinear coefﬁcient
Original matrix structureR

X
F(Y, Z)

Fair Isaac Corporation Conﬁdential and Proprietary Information

64

Xpress-SLP Structures

Advanced

Matrix structure: minimal augmentation (XSLP_AUGMENTATION=1)
R
uY
uZ

X
F(Y0 , Z0 )

Y
1

Z
1

dY
X0 ∗ Fy0 (Y0 , Z0 )–1dZ
X0 ∗ Fz0 (Y0 , Z0 )
–1

=
=

Y0
Z0

The original nonlinear coefﬁcient (X,R) is replaced by its evaluation using the assumed values of the
independent variables.
Two vectors and one equality constraint for each independent variable in the coefﬁcient are created ifthey do not already exist.
The new vectors are:The SLP variable (e.g. Y)

The SLP delta variable (e.g. dY)

The new constraint is the SLP update row (e.g. uY) and is always an equality. The only entries in the
update row are the +1 and -1 for the SLP variable and delta variable respectively. The right hand side is
the assumed value for the SLP variable.
The entry in the original nonlinear constraint row for each independent variable is the ﬁrst-order partial
derivative of the implied term X ∗ F(Y, Z), evaluated at the assumed values.
The delta variables are bounded by the current values of the corresponding step bounds.

Matrix structure: standard augmentation (XSLP_AUGMENTATION=0)
R
uX
uY
uZ

X
F(Y0 , Z0 )
1

Y
1

Z

dX
–1

dY
X0 ∗ Fy0 (Y0 , Z0 )

1

–1

dZ
X0 ∗ Fz0 (Y0 , Z0 )
–1

=
=
=

X0
Y0
Z0

The original nonlinear coefﬁcient (X,R) is replaced by its evaluation using the assumed values of the
independent variables.
Two vectors and one equality constraint for each independent variable in the coefﬁcient are created ifthey do not already exist.
The new vectors are:The SLP variable (e.g. Y)

The SLP delta variable (e.g. dY)

The new constraint is the SLP update row (e.g. uY) and is always an equality. The only entries in the
update row are the +1 and -1 for the SLP variable and delta variable respectively. The right hand side is
the assumed value for the SLP variable.
The entry in the original nonlinear constraint row for each independent variable is the ﬁrst-order partial
derivative of the implied term X ∗ F(Y, Z), evaluated at the assumed values.
The delta variables are bounded by the current values of the corresponding step bounds.
One new vector and one new equality constraint are created for the variable containing the nonlinear
coefﬁcient.
The new vector is:

Fair Isaac Corporation Conﬁdential and Proprietary Information

65

Xpress-SLP Structures



Advanced

The SLP delta variable (e.g. dX)

The new constraint is the SLP update row (e.g. uX) and is always an equality. The only entries in the
update row are the +1 and -1 for the original variable and delta variable respectively. The right hand sideis the assumed value for the original variable.
The delta variable is bounded by the current values of the corresponding step bounds.

Matrix structure: even-handed augmentation (XSLP_AUGMENTATION=2)
R
uX
uY
uZ

=
X0 ∗ F(Y0 , Z0 )

X

Y

1

Z

1

dX
F(Y0 , Z0 )–1

dY
X0 ∗ Fy0 (Y0 , Z0 )

1

–1

dZ
X0 ∗ Fz0 (Y0 , Z0 )
–1

=
=
=

X0
Y0
Z0

The coefﬁcient is treated as if it was the term X ∗ F(Y, Z) and is expanded in the same way as anonlinear term.

13.1.2

Augmentation of a nonlinear term
Original matrix structure=F(X, Y, Z)R

The column name = is a reserved name for a column which has a ﬁxed activity of 1.0 and canconveniently be used to hold nonlinear terms, particularly those which cannot be expressed as
coefﬁcients of variables.

Matrix structure: all augmentations
R
uX
uY
uZ

=
F(X0 , Y0 , Z0 )

X
1

Y
1

Z

dX
Fx0 (X0 , Y0 , Z0 )
–1

1

dY
Fy0 (X0 , Y0 , Z0 )–1dZ
Fz0 (X0 , Y0 , Z0 )
–1

=
=
=

X0
Y0
Z0

The original nonlinear coefﬁcient (=,R) is replaced by its evaluation using the assumed values of the
independent variables.
Two vectors and one equality constraint for each independent variable in the coefﬁcient are created ifthey do not already exist.
The new vectors are:The SLP variable (e.g. Y)

The SLP delta variable (e.g. dY)

The new constraint is the SLP update row (e.g. uY) and is always an equality. The only entries in the
update row are the +1 and -1 for the SLP variable and delta variable respectively. The right hand side is
the assumed value for the SLP variable.
The entry in the original nonlinear constraint row for each independent variable is the ﬁrst-order partial
derivative of the term F(X, Y, Z), evaluated at the assumed values.
The delta variables are bounded by the current values of the corresponding step bounds.

Fair Isaac Corporation Conﬁdential and Proprietary Information

66

Xpress-SLP Structures

Advanced

One new vector and one new equality constraint are created for the variable containing the nonlinear
coefﬁcient.
The new vector is:

The SLP delta variable (e.g. dX)

The new constraint is the SLP update row (e.g. uX) and is always an equality. The only entries in the
update row are the +1 and -1 for the original variable and delta variable respectively. The right hand sideis the assumed value for the original variable.
The delta variable is bounded by the current values of the corresponding step bounds.
Note that if F(X,Y,Z) = X*F(Y,Z) then this translation is exactly equivalent to that for the nonlinear
coefﬁcient described earlier.

13.1.3

Augmentation of a user-deﬁned SLP variable
Typically, this will arise when a variable represents the result of a nonlinear function, and is required toconverge, or to be constrained by step-bounding to force convergence. In essence, it would arise from a
relationship of the form
X = F(Y, Z)

Original matrix structureR=
F(Y, Z)X–1

Matrix structure: all augmentations
R
uX
uY
uZ

=
F(Y0 , Z0 )

X
–1
1

Y
1

Z

dX
–1

dY
Fy0 (Y0 , Z0 )1dZ
Fz0 (Y0 , Z0 )

–1

–1

=
=
=

X0
Y0
Z0

The Y,Z structures are identical to those which would result from a nonlinear term or coefﬁcient. The X,
dX and uX structures effectively deﬁne dX as the deviation of X from X0 which can be controlled withstep bounds.
The augmented and even-handed structures include more delta vectors, and so allow for moremeasurement and control of convergence.
Type of structure
Type of variable
Variables in nonlinear coefﬁcients
Variables with nonlinear coefﬁcientsUser-deﬁned SLP variable
Nonlinear term

MinimalStandard

Even-handed

Y
N
Y
Y

Y
Y
Y
Y

Y
Y
Y
Y

Y

SLP variable has a delta vector which can be measured and/or controlled forconvergence.

N

SLP variable does not have a delta and cannot be measured and/or controlled forconvergence.

Fair Isaac Corporation Conﬁdential and Proprietary Information

67

Xpress-SLP Structures

Advanced

There is no mathematical difference between the augmented and even-handed structures.
The even-handed structure is more elegant because it treats all variables in an identical way. However,
the original coefﬁcients are lost, because their effect is transferred to the "=" column as a term and so it
is not possible to look up the coefﬁcient value in the matrix after the SLP solution process has ﬁnished(whether because it has converged or because it has terminated for some other reason). The values of
the SLP variables are still accessible in the usual way.
Some of the extended convergence criteria will be less effective because the effects of the individual
coefﬁcients may be amalgamated into one term (so, for example, the total positive and negative
contributions to a constraint are no longer available).

13.1.4

SLP penalty error vectors
Bits 2, 3 and 9 of control variable XSLP_AUGMENTATION determine whether SLP penalty error vectors
are added to constraints. Bit 9 applies penalty error vectors to all constraints; bits 2 and 3 apply them
only to constraints containing nonlinear terms. When bit 2 or bit 3 is set, two penalty error vectors areadded to each such equality constraint; when bit 3 is set, one penalty error vector is also added to eachsuch inequality constraint. The general form is as follows:

Original matrix structureR=
F(Y, Z)

Matrix structure with error vectors
R
P_ERRORX
F(Y, Z)

R++1+Weight

R–1+Weight

For equality rows, two penalty error vectors are added. These have penalty weights in the penalty error
row PE RROR, whose total is transferred to the objective with a cost of XSLP_CURRENTERRORCOST. For
inequality rows, only one penalty error vector is added — the one corresponding to the slack is omitted.
If any error vectors are used in a solution, the transfer cost from the cost penalty error row will be
increased by a factor of XSLP_ERRORCOSTFACTOR up to a maximum of XSLP_ERRORMAXCOST.
Error vectors are ignored when calculating cascaded values.
The presence of error vectors at a non-zero level in an SLP solution normally indicates that the solution
is not self-consistent and is therefore not a solution to the nonlinear problem.
Control variable XSLP_ERRORTOL_A is a tolerance on error vectors. Any error vector with a value lessthan XSLP_ERRORTOL_A will be regarded as having a value of zero.
Bit 9 controls whether error vectors are added to all constraints. If bit 9 is set, then error vectors areadded in the same way as for the setting of bit 3, but to all constraints regardless of whether or not they
have nonlinear coefﬁcients.

13.2

Xpress-SLP Matrix Name Generation
Xpress-SLP adds rows and columns to the nonlinear problem in order to create a linear approximation.
The new rows and columns are given names derived from the row or column to which they are related
as follows:

Fair Isaac Corporation Conﬁdential and Proprietary Information

68

Xpress-SLP Structures

Advanced

Row or column type
Update row
Delta vector
Penalty delta (below stepbound)
Penalty delta (above stepbound)
Penalty error (below RHS)
Penalty error (above RHS)
Row for total of all penalty vectors (error or delta)
Column for standard penalty
cost (error or delta)
LO step bound formulated as arow
UP step bound formulated as arow

Control parameter containing
formatXSLP_UPDATEFORMATXSLP_DELTAFORMATXSLP_MINUSDELTAFORMAT

Default format

XSLP_PLUSDELTAFORMATpD+c

XSLP_MINUSERRORFORMATXSLP_PLUSERRORFORMATXSLP_PENALTYROWFORMAT

pE-r
pE+r
pPR_x

XSLP_PENALTYCOLFORMATpPC_x

XSLP_SBLOROWFORMATpSB-cXSLP_SBUPROWFORMAT

pSB+c

pU_r
pD_c
pD-c

In the default formats:pa unique preﬁx (one or more characters not used as the beginning of any name in the
problem).

rthe original row name.

cthe original column name.

x

The penalty row and column vectors are sufﬁxed with "ERR" or "DELT" (for error anddelta respectively).

Other characters appear "as is".
The format of one of these generated names can be changed by setting the corresponding control
parameter to a formatting string using standard "C"-style conventions. In these cases, the unique preﬁx
is not available and the only obvious choices, apart from constant names, use "%s" to include theoriginal name — for example:
U_%s would create names like U_abcdefghi
U_%-8s would create names like U_abcdefgh (always truncated to 8 characters).
You can use a part of the name by using the XSLP_⁎OFFSET control parameters (such as
XSLP_UPDATEOFFSET) which will offset the start of the original name by the number of characters
indicated (so, setting XSLP_UPDATEOFFSET to 1 would produce the name U_bcdefghi).

13.3

Xpress-SLP Statistics
When a matrix is read in using XSLPreadprob, statistics on the model are produced. They should beinterpreted as described in the numbered footnotes:
Reading Problem xxx
Problem Statistics
1920 (
0 spare) rows899 (0 spare) structural columns
6683 (
3000 spare) non-zero elements
Global Statistics
0 entities
0 sets0 set members

Fair Isaac Corporation Conﬁdential and Proprietary Information

(1)
(2)
(3)
(4)
(5)

69

Xpress-SLP Structures
Xpress-SLP Statistics:
3632 coefficients
14 extended variable arrays
1 user functions
1011 SLP variables

Advanced

(6)
(7)
(8)
(9)

Notes:
1. Standard output from XPRSreadprob reading the linear part of the problem
2. Number of rows declared in the ROWS section
3. Number of columns with at least one constant coefﬁcient
4. Number of constant elements
5. Integer and SOS statistics if appropriate
6. Number of non-constant coefﬁcients
7. Number of XVs deﬁned
8. Number of user functions deﬁned
9. Number of variables identiﬁed as SLP variables (interacting with a non-linear coefﬁcient)
When the original problem is SLP-presolved prior to augmentation, the following statistics areproduced:
Xpress-SLP Presolve:
3 presolve passes
247 SLP variables newly identified as fixed
425 determining rows fixed
32 coefficients identified as fixed
58 columns fixed to zero (56 SLP variables)
367 columns fixed to nonzero (360 SLP variables)
139 column deltas deleted
34 column bounds tightened (6 SLP variables)

(10)
(11)
(12)
(13)
(14)
(15)
(16)
(17)

Notes:
10. Presolve is an iterative process. Each iteration reﬁnes the problem until no further progress ismade. The number of iterations (presolve passes) can be limited by using
XSLP_PRESOLVEPASSES
11. SLP variables which are deduced to be ﬁxed by virtue of constraints in the model (over and above
any which are ﬁxed by bounds in the original problem)
12. Number of determining rows which have ﬁxed variables and constant coefﬁcients
13. Number of coefﬁcients which are ﬁxed because they are functions of constants and ﬁxed
variables
14. Total number of columns ﬁxed to zero (number of ﬁxed SLP variables shown in brackets)
15. Total number of columns ﬁxed to nonzero values (number of ﬁxed SLP variables shown inbrackets)
16. Total number of deltas deleted because the SLP variable is ﬁxed
17. Total number of bounds tightened by virtue of constraints in the model.

Fair Isaac Corporation Conﬁdential and Proprietary Information

70

Xpress-SLP Structures

Advanced

If any of these items is zero, it will be omitted. Unless speciﬁcally requested by setting additional bits ofcontrol XSLP_PRESOLVE, newly ﬁxed variables and tightened bounds are not actually applied to themodel. However, they are used in the initial augmentation and during cascading to ensure that thestarting points for each iteration are within the tighter bounds.
When the original problem is augmented prior to optimization, the following statistics are produced:
Xpress-SLP Augmentation Statistics:
Columns:
754 implicit SLP variables(18)
1010 delta vectors(19)2138 penalty error vectors (1177 positive, 961 negative) (20)Rows:1370 nonlinear constraints(21)
1010 update rows
(22)
1 penalty error rows
(23)
Coefficients:
11862 non-constant coefficients(24)

Notes:
18. SLP variables appearing only in coefﬁcients and having no constant elements
19. Number of delta vectors created
20. Numbers of penalty error vectors
21. Number of constraints containing nonlinear terms
22. Number of update rows (equals number of delta vectors)
23. Number of rows totaling penalty vectors (error or delta)
24. Number of non-constant coefﬁcients in the linear augmented matrix

The total number of rows in the augmented matrix is (2) + (22) + (23)The total number of columns in the augmented matrix is (3) + (18) + (19) + (20) + (23)The total number of elements in the original matrix is (4) + (6)

The total number of elements in the augmented matrix is (4) + (24) + (19) + 2*(20) + 2*(23)If the matrix is read in using the XPRSloadxxx and XSLPloadxxx functions then these statistics may
not be produced. However, most of the values are accessible through Xpress NonLinear integer
attributes using the XSLPgetintattrib function.

13.4

SLP Variable History
Xpress-SLP maintains a history value for each SLP variable. This value indicates the direction in which
the variable last moved and the number of consecutive times it moved in the same direction. Allvariables start with a history value of zero.

Fair Isaac Corporation Conﬁdential and Proprietary Information

71

Xpress-SLP Structures

Current History

Advanced00>0Change in activity ofvariable
>0
<0
>0

>0
<0

<0
<0

<0
anything>00

New History
1-1
No change unless delta vector is at its bound. If it is,then new value is Current History + 1-1
No change unless delta vector is at its bound. If it is,then new value is Current History - 1
1
No change

Tests of variable movement are based on comparison with absolute and relative (and, if set, closure)tolerances. Any movement within tolerance is regarded as zero.
If the new absolute value of History exceeds the setting of XSLP_SAMECOUNT, then the step bound isreset to a larger value (determined by XSLP_EXPAND) and History is reset as if it had been zero.
If History and the change in activity are of opposite signs, then the step bound is reset to a smaller
value (determined by XSLP_SHRINK) and History is reset as if it had been zero.
With the default settings, History will normally be in the range -1 to -3 or +1 to +3.

Fair Isaac Corporation Conﬁdential and Proprietary Information72

CHAPTER 14

Xpress NonLinear Formulae
Xpress NonLinear can handle formulae described in three different ways:
Character strings The formula is written exactly as it would appear in, for example, the Extended
MPS format used for text ﬁle input.
Internal unparsed format The tokens within the formula are replaced by a{tokentype, tokenvalue} pair. The list of types and values is in the table below.
Internal parsed format The tokens are converted as in the unparsed format, but the order ischanged so that the resulting array forms a reverse-Polish execution stack for direct
evaluation by the system.

14.1

Parsed and unparsed formulae
All formulae input into Xpress NonLinear are parsed into a reverse-Polish execution stack. Tokens are
identiﬁed by their type and a value. The table below shows the values used in interface functions.
All formulae are provided in the interface functions as two parallel arrays:
an integer array of token types;
a double array of token values.
The last token type in the array should be an end-of-formula token (XSLP_EOF, which evaluates to zero).
If the value required is an integer, it should still be provided in the array of token values as a double
precision value.
Even if a token type requires no token value, it is best practice to initialize such values as zeros.

Fair Isaac Corporation Conﬁdential and Proprietary Information73

Xpress NonLinear Formulae

AdvancedType
XSLP_COLXSLP_CONXSLP_DEL

Description
columnconstantdelimiterXSLP_EOFXSLP_FUNXSLP_IFUNXSLP_LBXSLP_OPend of formulauser function
internal function
left bracket
operator

XSLP_RBXSLP_VAR

right bracket
variableValue
index of matrix column.
(double) value.
XSLP_COMMA (1) = comma (",")
XSLP_COLON (2) = colon (":")
not required: use zeroindex of function
index of function
not required: use zeroXSLP_UMINUS (1) = unary minus ("-")
XSLP_EXPONENT (2) = exponent ("**" or "ˆ")XSLP_MULTIPLY (3) = multiplication ("*")
XSLP_DIVIDE (4) = division ("/")
XSLP_PLUS (5) = addition ("+")
XSLP_MINUS (6) = subtraction ("-")
not required: use zeroindex of variable. Note that variables count from 1,
so that the index of matrix column n is n + 1.

Token type XSLP_COL is used only when passing formulae into Xpress NonLinear. Any formulae
recovered from Xpress NonLinear will use the XSLP_VAR token type which always count from 1.
When a formula is passed to Xpress NonLinear in "internal unparsed format" — that is, with the formula
already converted into tokens — the full range of token types is permitted.
When a formula is passed to Xpress NonLinear in "parsed format" — that is, in reverse Polish — thefollowing rules apply:XSLP_DEL
comma is optional.
XSLP_FUN
implies a following left-bracket, which is not included explicitly.
XSLP_IFUN
implies a following left-bracket, which is not included explicitly.
XSLP_LB
never used.
XSLP_RB
only used to terminate the list of arguments to a function.
Brackets are not used in the reverse Polish representation of the formula: the order of evaluation isdetermined by the order of the items on the stack. Functions which need the brackets — for example
XSLPgetccoef — ﬁll in brackets as required to achieve the correct evaluation order. The result may
not match the formula as originally provided.

14.2

Example of an arithmetic formulax2 + 4y(z – 3)
Written as an unparsed formula, each token is directly transcribed as follows:

Fair Isaac Corporation Conﬁdential and Proprietary Information

74

Xpress NonLinear Formulae

AdvancedType
XSLP_VARXSLP_OPXSLP_CONXSLP_OPXSLP_CONXSLP_OPXSLP_VARXSLP_OPXSLP_LBXSLP_VARXSLP_OPXSLP_CONXSLP_RBXSLP_EOF

Value
index of x
XSLP_EXPONENT2XSLP_PLUS
4
XSLP_MULTIPLY
index of y
XSLP_MULTIPLY
0
index of z
XSLP_MINUS
300

Written as a parsed formula (in reverse Polish), an evaluation order is established ﬁrst, for example:
x

2 ˆ 4

∗

y

z 3

–

∗

+

and this is then transcribed as follows:Type
XSLP_VARXSLP_CONXSLP_OPXSLP_CONXSLP_VARXSLP_OPXSLP_VARXSLP_CONXSLP_OPXSLP_OPXSLP_OPXSLP_EOF

Value
index of x
2
XSLP_EXPONENT
4
index of y
XSLP_MULTIPLY
index of z
3
XSLP_MINUSXSLP_MULTIPLYXSLP_PLUS
0

Notice that the brackets used to establish the order of evaluation in the unparsed formula are notrequired in the parsed form.

14.3

Example of a formula involving a simple functiony ∗ MyFunc(z, 3)
Written as an unparsed formula, each token is directly transcribed as follows:Type
XSLP_VARXSLP_OPXSLP_FUNXSLP_LBXSLP_VARXSLP_DELXSLP_CONXSLP_RBXSLP_EOF

Value
index of y
XSLP_MULTIPLY
index of MyFunc
0
index of z
XSLP_COMMA
30
0

Written as a parsed formula (in reverse Polish), an evaluation order is established ﬁrst, for example:

Fair Isaac Corporation Conﬁdential and Proprietary Information75

Xpress NonLinear Formulae

y

)

3

,

Advancedz

MyFunc(∗and this is then transcribed as follows:Type
XSLP_VARXSLP_RBXSLP_CONXSLP_DELXSLP_VARXSLP_FUNXSLP_OPXSLP_EOF

Value
index of y
0
3
XSLP_COMMA
index of z
index of MyFunc
XSLP_MULTIPLY
0

Notice that the function arguments are in reverse order, and that a right bracket is used as a delimiter toindicate the end of the argument list. The left bracket indicating the start of the argument list is impliedby the XSLP_FUN token.

Fair Isaac Corporation Conﬁdential and Proprietary Information76

CHAPTER 15

User Functions
15.1

Callbacks and user functions
Callbacks and user functions both provide mechanisms for connecting user-written functions to
Xpress NonLinear. However, they have different capabilities and are not interchangeable.
A callback is called at a speciﬁc point in the SLP optimization process (for example, at the start of each
SLP iteration). It has full access to all the problem data and can, in principle, change the values of any
items — although not all such changes will necessarily be acted upon immediately or at all.
A user function is essentially the same as any other mathematical function, used in a formula tocalculate the current value of a coefﬁcient. The function is called when a new value is needed; forefﬁciency, user functions are not usually called if the value is already known (for example, when thefunction arguments are the same as on the previous call). Therefore, there is no guarantee that a userfunction will be called at any speciﬁc point in the optimization procedure or at all.
Although a user function is normally free-standing and needs no access to problem or other data apartfrom that which it receives through its argument list, there are facilities to allow it to access the
problem and its data if required. The following limitations should be observed:
1. The function should not make use of any variable data which is not in its list of arguments;
2. The function should not change any of the problem data.
The reasons for these restrictions are as follows:
1. Xpress NonLinear determines which variables are linked to a formula by examining the list ofvariables and arguments to functions in the formula. If a function were to access and use thevalue of a variable not in this list, then incorrect relationships would be established, and incorrect
or incomplete derivatives would be calculated. The predicted and actual values of the coefﬁcient
would then always be open to doubt.
2. Xpress NonLinear generally allows problem data to be changed between function calls, and also
by callbacks called from within an Xpress NonLinear function. However, user functions are calledat various points during the optimization and no checks are generally made to see if any problem
data has changed. The effects of any such changes will therefore at best be unpredictable.
For a description of how to access the problem data from within a user function, see the section on"More complicated user functions" later in this chapter.

Fair Isaac Corporation Conﬁdential and Proprietary Information77

User Functions

15.2

Advanced

User function interface
In its simplest form, a user function is exactly the same as any other mathematical function: it takes a
set of arguments (constants or values of variables) and returns a value as its result. In this form, whichis the usual implementation, the function needs no information apart from the values of its arguments.
It is possible to create more complicated functions which do use external data in some form: these are
discussed at the end of this section.
Xpress NonLinear supports two basic forms of user function. The simple form of function returns asingle value, and is treated in essentially the same way as a normal mathematical function. The generalform of function returns an array of values and may also perform automatic differentiation.
The main difference between the simple and general form of a user function is in the way the value isreturned.




15.3

The simple function calculates and returns one value and is declared as such (for example,
double in C).
The general function calculates an array of values. It can either return the array itself (and isdeclared as such: double ⁎ ), or it can return the results in one of the function arguments, inwhich case the function itself returns a single (double precision) status value (and is declared as
such: double).

User Function declaration in native languages
This section describes how to declare a user function in C, Fortran and so on. The general shape of thedeclaration is shown. Not all the possible arguments will necessarily be used by any particular function,and the actual arguments required will depend on the way the function is declared to Xpress NonLinear.

15.3.1

User function declaration in C
The XPRS_CC calling convention (equivalent to __stdcall under Windows) must be used for thefunction. For example:
type XPRS_CC MyFunc(double ⁎InputValues, int ⁎FunctionInfo,char ⁎InputNames, char ⁎ReturnNames
double ⁎Deltas, double ⁎ReturnArray);where type is double or double⁎ depending on the nature of the function.
In C++, the function should be declared as having a standard C-style linkage. For example, with
Microsoft C++ under Windows:
extern "C" type _declspec(dllexport) XPRS_CC
MyFunc(double ⁎InputValues, int ⁎FunctionInfo,char ⁎InputNames, char ⁎ReturnNames
double ⁎Deltas, double ⁎ReturnArray);

If the function is placed in a library, the function name may need to be externalized. If the compiler adds
"decoration" to the name of the function, the function may also need to be given an alias which is theoriginal name. For example, with the Microsoft compiler, a deﬁnition ﬁle can be used, containing thefollowing items:
EXPORTSMyFunc=_MyFunc@12

Fair Isaac Corporation Conﬁdential and Proprietary Information78

User Functions

Advanced

where the name after the equals sign is the original function name preceded by an underscore andfollowed by the @ sign and the number of bytes in the arguments. As all arguments in Xpress
NonLinear external function calls are pointers, each argument represents 4 bytes on a 32-bit platform,and 8 bytes on a 64-bit platform.
A user function can be included in the executable program which calls Xpress NonLinear. In such acase, the user function is declared as usual, but the address of the program is provided using
XSLPchguserfuncaddress or XSLPsetuserfuncaddress. The same technique can also be used
when the function has been loaded by the main program and, again, its address is already known.
The InputNames and ReturnNames arrays, if used, contain a sequence of character strings which are
the names, each terminated by a null character.
Any argument omitted from the declaration in Xpress NonLinear will be omitted from the function call.
Any argument declared in Xpress NonLinear as of type NULL will generally be passed as a null pointerto the program.

15.4

Simple functions and general functions
A simple function is one which returns a single value calculated from its arguments, and does notprovide derivatives. A general function returns more than one value, because it calculates an array ofresults, or because it calculates derivatives, or both.
Because of restrictions in the various types of linkage, not all types of function can be declared andused in all languages. Any limitations are described in the appropriate sections.
For simplicity, the functions will be described using only examples in C. Implementation in otherlanguages follows the same rules.

15.4.1

Simple user functions
A simple user function returns only one value and does not calculate derivatives. It therefore does not
use the ReturnNames, Deltas or ReturnArray arguments.
The full form of the declaration is:double XPRS_CC MyFunc(double ⁎InputValues, int ⁎FunctionInfo,char ⁎InputNames);

FunctionInfo can be omitted if the number of arguments is not required, and access to problem
information and function objects is not required.
InputNames can be omitted if the input values are identiﬁed by position and not by name (see"Programming Techniques for User Functions" below).
The function supplies its single result as the return value of the function.
There is no provision for indicating that an error has occurred, so the function must always be able tocalculate a value.

15.4.2

General user functions returning an array of values through a reference
General user functions calculate more than one value, and the results are returned as an array. In theﬁrst form of a general function, the values are supplied by returning the address of an array which holds
the values. See the notes below for restrictions on the use of this method.
The full form of the declaration is:

Fair Isaac Corporation Conﬁdential and Proprietary Information79

User Functions

Advanceddouble ⁎ XPRS_CC MyFunc(double ⁎InputValues, int ⁎FunctionInfo,char ⁎InputNames, char ⁎ReturnNames
double ⁎Deltas);

FunctionInfo can be omitted if the number of arguments is not required, no derivatives are being
calculated, the number of return values is ﬁxed, and access to problem information and function
objects is not required. However, it is recommended that FunctionInfo is always included.
InputNames can be omitted if the input values are identiﬁed by position and not by name (see"Programming Techniques for User Functions" below).
ReturnNames can be omitted if the return values are identiﬁed by position and not by name (see"Programming Techniques for User Functions" below).
Deltas must be omitted if no derivatives are calculated.
The function supplies the address of an array of results. This array must be available after the function
has returned to its caller, and so is normally a static array. This may mean that the function cannot becalled from a multi-threaded optimization, or where multiple instances of the function are required,because the single copy of the array may be overwritten by another call to the function. An alternative
method is to use a function object which refers to an array speciﬁc to the thread or problem being
optimized.
Deltas is an array with the same number of items as InputValues. It is used as an indication ofwhich derivatives (if any) are required on a particular function call. If Deltas[i] is zero then aderivative for input variable i is not required and must not be returned. If Deltas[i] is nonzero then aderivative for input variable i is required and must be returned. The total number of nonzero entries in
Deltas is given in FunctionInfo[2]. In particular, if it is zero, then no derivatives are required at all.
When no derivatives are calculated, the array of return values simply contains the results (in the orderspeciﬁed by ReturnNames if used).
When derivatives are calculated, the array contains the values and the derivatives as follows (DVi is theith variable for which derivatives are required, which may not be the same as the ith input value):
Result1
Derivative of Result1 w.r.t. DV1
Derivative of Result1 w.r.t. DV2...
Derivative of Result1 w.r.t. DVn
Result2
Derivative of Result2 w.r.t. DV1
Derivative of Result2 w.r.t. DV2...
Derivative of Result2 w.r.t. DVn...
Derivative of Resultm w.r.t. DVn
It is therefore important to check whether derivatives are required and, if so, how many.

15.4.3General user functions returning an array of values through an argument
General user functions calculate more than one value, and the results are returned as an array. In thesecond form of a general function, the values are supplied by returning the values in an array provided
as an argument to the function by the calling program. See the notes below for restrictions on the useof this method.
The full form of the declaration is:double XPRS_CC MyFunc(double ⁎InputValues, int ⁎FunctionInfo,char ⁎InputNames, char ⁎ReturnNames
double ⁎Deltas, double ⁎ReturnArray);

Fair Isaac Corporation Conﬁdential and Proprietary Information

80

User Functions

Advanced

FunctionInfo can be omitted if the number of arguments is not required, no derivatives are being
calculated, the number of return values is ﬁxed, and access to problem information and function
objects is not required. However, it is recommended that FunctionInfo is always included.
InputNames can be omitted if the input values are identiﬁed by position and not by name (see"Programming Techniques for User Functions" below).
ReturnNames can be omitted if the return values are identiﬁed by position and not by name (see"Programming Techniques for User Functions" below).
Deltas must be omitted if no derivatives are calculated.
The function must supply the results in the array ReturnArray. This array is guaranteed to be large
enough to hold all the values requested by the calling program. No guarantee is given that the results
will be retained between function calls.
Deltas is an array with the same number of items as InputValues. It is used as an indication ofwhich derivatives (if any) are required on a particular function call. If Deltas[i] is zero then aderivative for input variable i is not required and must not be returned. If Deltas[i] is nonzero then aderivative for input variable i is required and must be returned. The total number of nonzero entries in
Deltas is given in FunctionInfo[2]. In particular, if it is zero, then no derivatives are required at all.
When no derivatives are calculated, the array of return values simply contains the results (in the orderspeciﬁed by ReturnNames if used).
When derivatives are calculated, the array contains the values and the derivatives as follows (DVi is theith variable for which derivatives are required, which may not be the same as the ith input value):
Result1
Derivative of Result1 w.r.t. DV1
Derivative of Result1 w.r.t. DV2...
Derivative of Result1 w.r.t. DVn
Result2
Derivative of Result2 w.r.t. DV1
Derivative of Result2 w.r.t. DV2...
Derivative of Result2 w.r.t. DVn...
Derivative of Resultm w.r.t. DVn
It is therefore important to check whether derivatives are required and, if so, how many.
The return value of the function is a status code indicating whether the function has completed
normally. Possible values are:

15.5

0

No errors: the function has completed normally.

1

The function has encountered an error. This will terminate the optimization.

-1

The calling function must estimate the function value from the last set of values calculated.
This will cause an error if no values are available.

Programming Techniques for User Functions
This section is principally concerned with the programming of large or complicated user functions,perhaps taking a potentially large number of input values and calculating a large number of results.
However, some of the issues raised are also applicable to simpler functions.
The ﬁrst part describes in more detail some of the possible arguments to the function. The remainderof the section looks at function instances, function objects and direct calls to user functions.

Fair Isaac Corporation Conﬁdential and Proprietary Information81

User Functions

15.5.1

Advanced

DeltasThe Deltas array has the same dimension as InputValues and is used to indicate which of the input
variables should be used to calculate derivatives. If Deltas[i] is zero, then no derivative should be
returned for input variable i. If Deltas[i] is nonzero, then a derivative is required for input variable i.
The value of Deltas[i] can be used as a suggested perturbation for numerical differentiation (anegative sign indicates that if a one-sided derivative is calculated, then a backward one is preferred). If
derivatives are calculated analytically, or without requiring a speciﬁc perturbation, then Deltas can beinterpreted simply as an array of ﬂags indicating which derivatives are required.

15.5.2Return values and ReturnArray
The ReturnArray array is provided for those user functions which return more than one value, either
because they do calculate more than one result, or because they also calculate derivatives. The
function must either return the address of an array which holds the values, or pass the values to thecalling program through the ReturnArray array.
The total number of values returned depends on whether derivatives are being calculated. The
FunctionInfo array holds details of the number of input values supplied, the number of return values
required (nRet) and the number of sets derivatives required (nDeriv). The total number of values (andhence the minimum size of the array) is nRet ∗ (nDeriv + 1). Xpress NonLinear guarantees that
ReturnArray will be large enough to hold the total number of values requested.
A function which calculates and returns a single value can use the ReturnArray array provided thatthe declarations of the function in Xpress NonLinear and in the native language both include theappropriate argument deﬁnition.
functions which use the ReturnArray array must also return a status code as their return value. Zerois the normal return value. A value of 1 or greater is an error code which will cause any formula
evaluation to stop and will normally interrupt any optimization or other procedure. A value of -1 asks
Xpress NonLinear to estimate the function values from the last calculation of the values and partial
derivatives. This will produce an error if there is no such set of values.

15.5.3Returning Derivatives
A multi-valued function which does not calculate its own derivatives will return its results as a
one-dimensional array.
As already described, when derivatives are calculated as well, the order is changed, so that the requiredderivatives follow the value for each result. That is, the order becomes:∂A , ∂A , ... ∂A , B, ∂B , ∂B , ... ∂B , ... ∂Z
A, ∂X
∂Xn
∂X1 ∂X2
∂Xn
∂Xn
1 ∂X2
where A, B, Z are the return values, and X1 , X2 , Xn , are the input (independent) variables (in order) for
which derivatives have been requested.
Not all calls to a user function necessarily require derivatives to be calculated. Check FunctionInfo
for the number of derivatives required (it will be zero if only a value calculation is needed), and Deltas
for the indications as to which independent variables are required to produce derivatives. Xpress
NonLinear will not ask for, nor will it expect to receive, derivatives for function arguments which are
actually constant in a particular problem. A function which provides uncalled-for derivatives will cause
errors in subsequent calculations and may cause other unexpected side-effects if it stores values
outside the expected boundaries of the return array.

15.5.4

Function Instances
Xpress NonLinear deﬁnes an instance of a user function to be a unique combination of function andarguments. For functions which return an array of values, the speciﬁc return argument is ignored when
determining instances. Thus, given the following formulae:

Fair Isaac Corporation Conﬁdential and Proprietary Information82

User Functions

Advanced

f(x) + f(y) + g(x, y : 1)
f(y) ∗ f(x) ∗ g(x, y : 2)f(z)the following instances are created:
f(x)
f(y)
f(z)
g(x, y)(A function reference of the form g(x, y : n) means that g is a multi-valued function of x and y, and wewant the nth return value.)
Xpress NonLinear regards as complicated any user function which returns more than one value, whichuses input or return names, or which calculates its own derivatives. All complicated functions give rise
to function instances, so that each function is called only once for each distinct combination ofarguments.
Functions which are not regarded as complicated are normally called each time a value is required. A
function of this type can still be made to generate instances by deﬁning its ExeType as creating
instances (set bit 9 when using the normal library functions, or use the "I" sufﬁx when using ﬁle-based
input through XSLPreadprob or when using SLPDATA in Mosel).
Note that conditional re-evaluation of the function is only possible if it generates function instances.
Using function instances can improve the performance of a problem, because the function is called
only once for each combination of arguments, and is not re-evaluated if the values have not changed
signiﬁcantly. If the function is computationally intensive, the improvement can be signiﬁcant.
There are reasons for not wanting to use function instances:






15.6

When the function is fast. It may be as fast to recalculate the value as to work out if evaluation isrequired.
When the function is discontinuous. Small changes are estimated by using derivatives. Thesebehave badly across a discontinuity and so it is usually better to evaluate the derivative of aformula by using the whole formula, rather than to calculate it from estimates of the derivatives ofeach term.
Function instances do use more memory. Each instance holds a full copy of the last input andoutput values, and a full set of ﬁrst-order derivatives. However, the only time when function
instances are optional is when there is only one return value, so the extra space is not normallysigniﬁcant.

Function Derivatives
Xpress NonLinear normally expects to obtain a set of partial derivatives from a user function at aparticular base-point and then to use them as required, depending on the evaluation settings for thevarious functions. If for any reason this is not appropriate, then the integer control parameterXSLP_EVALUATE can be set to 1, which will force re-evaluation every time.
A function instance is not re-evaluated if all of its arguments are unchanged.
A simple function which does not have a function instance is evaluated every time.
If XSLP_EVALUATE is not set, then it is still possible to by-pass the re-evaluation of a function if thevalues have not changed signiﬁcantly since the last evaluation. If the input values to a function have all
converged to within their strict convergence tolerance (CTOL, ATOL_A, ATOL_R), and bit 4 of
XSLP_FUNCEVAL is set to 1, then the existing values and derivatives will continue to be used. At theoption of the user, an individual function, or all functions, can be re-evaluated in this way or at each SLP
iteration. If a function is not re-evaluated, then all the required values will be calculated from the base

Fair Isaac Corporation Conﬁdential and Proprietary Information

83

User Functions

Advancedpoint and the partial derivatives; the input and return values used in making the original function
calculation are unchanged.
Bits 3-5 of integer control parameter XSLP_FUNCEVAL determine the nature of function evaluations.
The meaning of each bit is as follows:
Bit 3

evaluate functions whenever independent variables change.

Bit 4evaluate functions when independent variables change outside tolerances.

Bit 5

apply evaluation mode to all functions.

If bits 3-4 are zero, then the settings for the individual functions are used.
If bit 5 is zero, then the settings in bits 3-4 apply only to functions which do not have their own speciﬁc
evaluation modes set.
Examples:Bits 3-5 = 1 (set bit 3) Evaluate functions whenever their input arguments (independent variables)change, unless the functions already have their own evaluation options set.
Bits 3-5 = 5 (set bits 3 and 5) Evaluate all functions whenever their input arguments (independent
variables) change.
Bits 3-5 = 6 (set bits 4 and 5) Evaluate functions whenever input arguments (independent variables)change outside tolerance. Use existing calculation to estimate values otherwise.
Bits 6-8 of integer control parameter XSLP_FUNCEVAL determine the nature of derivative calculations.
The meaning of each bit is as follows:
Bit 6

tangential derivatives.

Bit 7

forward derivatives.

Bit 8

apply evaluation mode to all functions.

If bits 6-7 are zero, then the settings for the individual functions are used.
If bit 8 is zero, then the settings in bits 6-7 apply only to functions which do not have their own speciﬁcderivative calculation modes set.
Examples:Bits 6-8 = 1 (set bit 6) Use tangential derivatives for all functions which do not already have their own
derivative options set.
Bits 6-8 = 5 (set bits 6 and 8) Use tangential derivatives for all functions.
Bits 6-8 = 6 (set bits 7 and 8) Use forward derivatives for all functions.
The following constants are provided for setting these bits:
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8

XSLP_RECALCXSLP_TOLCALCXSLP_ALLCALCSXSLP_2DERIVATIVEXSLP_1DERIVATIVEXSLP_ALLDERIVATIVES

Fair Isaac Corporation Conﬁdential and Proprietary Information

84

User Functions

Advanced

A function can make its own determination of whether to re-evaluate. If the function has alreadycalculated and returned a full set of values and partial derivatives, then it can request Xpress NonLinear
to estimate the values required from those already provided.
The function must be deﬁned as using the ReturnArray argument, so that the return value from thefunction itself is a double precision status value as follows:

15.6.10

normal return. The function has calculated the values and they are in ReturnArray.

1

error return. The function has encountered an unrecoverable error. The values in
ReturnArray are ignored and the optimization will normally terminate.

-1

no calculation. Xpress NonLinear should recalculate the values from the previous results. The
values in ReturnArray are ignored.

Analytic Derivatives of Instantiated User Functions not Returning their own Derivatives
When analytical derivatives are used, SLP will calculate approximated derivatives using ﬁnite
differences for instantiated functions and use these values when deriving analytical derivatives.
Functions returning multiple arguments will always be instantiated, otherwise functions can be forced
to be instantiated on a per function basis.

Fair Isaac Corporation Conﬁdential and Proprietary Information

85

CHAPTER 16

Management of zero placeholder entries
16.1

The augmented matrix structure
During the augmentation process, Xpress-SLP builds additional matrix structure to represent the linear
approximation of the nonlinear constraints within the problem (see Xpress-SLP Structures). In effect, it
adds a generic structure which approximates the effect of changes to variables in nonlinear
expressions, over and above that which would apply if the variables were simply replaced by theircurrent values.
As a very simple example, consider the nonlinear constraint (R1, say)X ∗ Y ≤ 10
The variables X and Y are replaced by X0 + δX and Y0 + δY respectively, where X0 and Y0 are the valuesof X and Y at which the approximation will be made.
The original constraint is therefore(X0 + δX) ∗ (Y0 + δY) ≤ 10
Expanding this into individual terms, we have
X0 ∗ Y0 + X0 ∗ δY + Y0 ∗ δX + δX ∗ δY ≤ 10
The ﬁrst term is constant, the next two terms are linear in δY and δX respectively, and the last term isnonlinear.
The augmented structure deletes the nonlinear term, so that the remaining structure is a linear
approximation to the original constraint. The justiﬁcation for doing this is that if δX or δY (or both) aresmall, then the error involved in ignoring the term is also small.
The resulting matrix structure has entries of Y0 in the delta variable δX and X0 in the delta variable δY.
The constant entry X0 ∗ Y0 is placed in the special "equals" column which has a ﬁxed activity of 1. All
these entries are updated at each SLP iteration as the solution process proceeds and the problem islinearized at a new point. The positions of these entries – (R1, δX), (R1, δY) and (R1, =) – are known asplaceholders.

16.2

Derivatives and zero derivatives
At each SLP iteration, the values of the placeholders are re-calculated. In the example in the previous
section, the values X0 in the delta variable δY and Y0 in the delta variable δX were effectively
determined by analytic methods – that is, we differentiated the original formula to determine whatvalues would be required in the placeholders.
In general, analytic differentiation may not be possible: the formula may contain functions whichcannot be differentiated (because, for example, they are not smooth or not continuous), or for which
the analytic derivatives are not known (because, for example, they are functions providing values fromFair Isaac Corporation Conﬁdential and Proprietary Information

86

Management of zero placeholder entries

Advanced"black boxes" such as databases or simulators). In such cases, Xpress-SLP approximates thedifferentiation process by numerical methods. The example in the previous section would haveapproximate derivatives calculated as follows:
The current value of X (X0 ) is perturbed by a small amount (dX), and the value of the formula isrecalculated in each case.
fd = (X0 – dX) ∗ Y0
fu = (X0 + dX) ∗ Y0
derivative = (fu – fd )/(2 ∗ dX)
In this particular example, the value obtained by numerical methods is the same as the analytic
derivative. For more complex functions, there may be a slight difference, depending on the magnitude
of dX.
This derivative represents the effect on the constraint of a change in the value of X. Obviously, if Ychanges as well, then the combined effect will not be fully represented although, in general, it will bedirectionally correct.
The problem comes when Y0 is zero. In such a case, the derivative is calculated as zero, meaning thatchanging X has no effect on the value of the formula. This can impact in one of two ways: either thevalue of X never changes because there is no incentive to do so, or it changes by unreasonably large
amounts because there is no effect from doing so. If X and Y are linked in some other way, so that Y
becomes nonzero when X changes, the approximation using zero as the derivative can cause theoptimization process to behave badly.
Xpress-SLP tries to avoid the problem of zero derivatives by using small nonzero values for variables
which are in fact zero. In most cases this gives a small nonzero value for the derivative, and hence forthe placeholder entry. The model then contains some effect for the change in a variable, even if
instantaneously the effect is zero.
The same principle is applied to analytic derivatives, so that the values obtained by either method arebroadly similar.

16.3

Placeholder management
The default action of Xpress-SLP is to retain all the calculated values for all the placeholder entries.
This includes values which would be zero without the special handling described in the previous
section. We will call such values "zero placeholders".
Although retaining all the values gives the best chance of ﬁnding a good optimum, the presence of alarge dense area of small values often gives rise to considerable numerical instability which adversely
affects the optimization process. Xpress-SLP therefore offers a way of deleting small values which isless likely to affect the ﬁnal outcome whilst improving numerical stability.
Most of the candidate placeholders are in the delta variables (represented by the δX and δY variables
above). Various criteria can be selected for deletion of zero placeholder entries without affecting thevalidity of the basis (and so making the next SLP iteration more costly in time and stability). The criteria
are selected using the control parameter XSLP_ZEROCRITERION as follows:

Bit 0 (=1) Remove placeholders in nonbasic SLP variables
This criterion applies to placeholders which are in the SLP variable (not the delta). Any value canbe deleted from a nonbasic variable without upsetting the basis, so all eligible zero placeholders
can be deleted.
Bit 1 (=2) Remove placeholders in nonbasic delta variables
Any value can be deleted from a nonbasic variable without upsetting the basis, so all eligible zeroplaceholders can be deleted.

Fair Isaac Corporation Conﬁdential and Proprietary Information

87

Management of zero placeholder entries







Advanced

Bit 2 (=4) Remove placeholders in a basic SLP variable if its update row is nonbasic
If the update row is nonbasic, then generally the basic SLP variable can be pivoted in the updaterow, so the basis is still valid if other entries are deleted. The entry in the update row is always 1.0
and will never be deleted.
Bit 3 (=8) Remove placeholders in a basic delta variable if its update row is nonbasic and thecorresponding SLP variable is nonbasic
If the delta is basic and the corresponding SLP variable is nonbasic, then the delta will pivot in the
update row (the delta and the SLP variable are the only two variables in the update row), so thebasis is still valid if other entries are deleted. The entry in the update row is always -1.0 and will
never be deleted.
Bit 4 (=16) Remove placeholders in a basic delta variable if the determining row for thecorresponding SLP variable is nonbasic
If the delta variable is basic and the determining row for the corresponding SLP variable isnonbasic then it is generally possible (although not 100% guaranteed) to pivot the delta variable inthe determining row. so the basis is still valid if other entries are deleted. The entry in thedetermining row is never deleted even if it is otherwise eligible.

The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4

XSLP_ZEROCRTIERION_NBSLPVARXSLP_ZEROCRTIERION_NBDELTAXSLP_ZEROCRTIERION_SLPVARNBUPDATEROWXSLP_ZEROCRTIERION_DELTANBUPSATEROWXSLP_ZEROCRTIERION_DELTANBDRROW

There are two additional control parameters used in this procedure:

XSLP_ZEROCRITERIONSTART
This is the ﬁrst SLP iteration at which zero placeholders will be examined for eligibility. Use of thisparameter allows a balance to be made between optimality and numerical stability.
XSLP_ZEROCRITERIONCOUNTThis is the number of consecutive SLP iterations that a placeholder is a zero placeholder before it
is deleted. So, if in the earlier example XSLP_ZEROCRITERIONCOUNT is 2, the entry in the deltavariable dX will be deleted only if Y was also zero on the previous SLP iteration.

Regardless of the basis status of a variable, its delta, update row and determining row, if a zeroplaceholder was deleted on the previous SLP iteration, it will always be deleted in the current SLP
iteration (keeping a zero matrix entry at zero does not upset the basis).
If the optimization method is barrier, or the basis is not being used, then the bit settings of
XSLP_ZEROCRITERION are not used as such: if XSLP_ZEROCRITERION is nonzero, all zeroplaceholders will be deleted subject to XSLP_ZEROCRITERIONCOUNT andXSLP_ZEROCRITERIONSTART.

Fair Isaac Corporation Conﬁdential and Proprietary Information

88

CHAPTER 17

Special Types of Problem
17.1

Nonlinear objectives
Xpress NonLinear works with nonlinear constraints. If a nonlinear objective is required (except for the
special case of a quadratic objective — see below) then the objective should be provided using a
constraint in the problem. For example, to optimize f(x) where f is a nonlinear function and x is a setof one or more variables, create the constraint
f(x) – X = 0
where X is a new variable, and then optimize X.
In general, X should be made a free variable, so that the problem does not converge prematurely on thebasis of an unchanging objective function. It is generally important that the objective is not artiﬁciallyconstrained (for example, by bounding X) because this can distort the solution process. Also, as suchan objective transfer row is not a real constraint, no error vectors should be added (row can be
enforced); feasibility should be provided by the transfer variable X being free.

17.2

Convex Quadratic Programming
Convex quadratic programming (QP) is a special case of nonlinear programming where the constraints
are linear but the objective is quadratic (that is, it contains only terms which are constant, variables
multiplied by a constant, or products of two variables multiplied by a constant) and convex (convexity ischecked by the Xpress Optimizer). It is possible to solve convex quadratic problems using SLP, but it is
not usually the best way. The reason is that the solution to a convex QP problem is typically not at avertex. In SLP a non-vertex solution is achieved by applying step bounds to create additional
constraints which surround the solution point, so that ultimately the solution has been obtained withinsuitable tolerances. Because of the nature of the problem, successive solutions will often swing fromone step bound to the other; in such circumstances, the step bounds are reduced on each SLP iteration
but it will still take a long time before convergence. In addition, unless the linear approximation isadequately constrained, it will be unbounded because the linear approximation will not recognize thechange in direction of the relationship with the derivative as the variable passes through a stationary
point. The easiest way to ensure that the linear problem is constrained is to provide realistic upper andlower bounds on all variables.
In Xpress NonLinear, convex quadratic problems can be solved using the quadratic optimizer within the
Xpress optimizer package. For pure QP (or MIQP) problems, therefore, SLP is not required. However,the SLP algorithm can be used together with QP to solve problems with a quadratic objective and also
nonlinear constraints. The constraints are handled using the normal SLP techniques; the objective ishandled by the QP optimizer. If the objective is not convex (not semi-deﬁnite), the QP optimizer may notgive a solution (with default settings, it will produce an error message); SLP will ﬁnd a solution but — asalways — it may be a local optimum.

Fair Isaac Corporation Conﬁdential and Proprietary Information89Special Types of Problem

Advanced

If a QP problem is to be solved, then the quadratic component should be input in the normal way (using
QMATRIX or QUADOBJ in MPS ﬁle format, or the library functions XPRSloadqp or XPRSloadqglobal).
Xpress NonLinear will then automatically use the QP optimizer. If the problem is to be solved using the
SLP routines throughout, then the objective should be provided via a constraint as described in theprevious section.
This applies to quadratically constrained (QCQP and MIQCQP) problems as well.
For a description on when it’s more beneﬁcial 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.

17.3

Mixed Integer Nonlinear Programming
Mixed Integer Non-Linear Programming (MINLP) is the application of mixed integer techniques to thesolution of problems including non-linear relationships. Xpress NonLinear offers a set of components
to implement MINLP using Mixed Integer Successive Linear Programming (MISLP).

17.3.1

Mixed Integer SLP
The mixed integer successive linear programming (MISLP) solver is a generalization of the traditional
branch and bound procedure to nonlinear programming. The MIP engine is used to control the
branch-and-bound algorithm, with each node being evaluated using SLP. MIP then compares the SLP
solutions at each node to decide which node to explore next, and to decide when an integer feasible
and ultimately optimal solution have been obtained.
MISLP, also known as SLP within MIP, offers nonlinear speciﬁc root heuristics controlled by control
XSLP_HEURSTRATEGY.
Other generic heuristics are controlled by the respective XPRS heuristics controls.
The branch and bound tree exploration is executed in parallel. Use the XPRS control MIPTHREADS tolimit the number of threads used.
Normally, the relaxed problem is solved ﬁrst, using XSLPminim or XSLPmaxim with the -l ﬂag toignore the integer elements of the problem. It is possible to go straight into the XSLPglobal routine
and allow it to do the initial SLP optimization as well. In that case, ensure that the control parameterXSLP_OBJSENSE is set to +1 (minimization) or -1 (maximization) before calling XSLPglobal.
The actual algorithm employed is controlled by a number of control parameters, as well as offering thepossibility of direct user interaction through call-backs at key points in the solution process.

17.3.2

Heuristics for Mixed Integer SLP
For hard MINLP problems, or where a solution must quickly be generated, the root heuristics of MISLP
can be executed as stand alone methods. These approaches can be used by changing the value of thecontrol parameter XSLP_MIPALGORITHM.
there are two MISLP heuristics:
1. MIP within SLP. In this, each SLP iteration is optimized using MIP to obtain an integer optimal
solution to the linear approximation of the original problem. SLP then compares this MIP solution
to the MIP solution of the previous SLP iteration and determines convergence based on the
differences between the successive MIP solutions.
2. SLP then MIP. In this, SLP is used to ﬁnd a converged solution to the relaxed problem. The
resulting linearization is then ﬁxed (i.e. the base point and the partial derivatives do not change)

Fair Isaac Corporation Conﬁdential and Proprietary Information

90Special Types of Problem

Advanced

and MIP is run to ﬁnd an integer optimum. SLP is then run again to ﬁnd a converged solution tothe original problem with these integer settings.
The approach described in (1) seems potentially dangerous, in that changes in the integer variables
could have disproportionate effects on the solution and on the values of the SLP variables. There arealso question-marks over the use of step-bounding to control convergence, particularly if any of theinteger variables are also SLP variables.
The approach described in (2) has the big advantage that MIP is working on a linear problem and so
can take advantage of all of the special attributes of such a problem. This means that the solution time
is likely to be much faster than the alternatives. However, if the real problem is signiﬁcantly non-linear,
the integer solution to the initial SLP solution may not be a good integer solution to the original problem
and so a false optimum may occur.

17.3.3Fixing or relaxing the values of the SLP variables
The solution process may involve step-bounding to obtain the converged solution. Some MIP solution
strategies may want to ﬁx the values of some of the SLP variables before moving on to the MIP part ofthe process, or they may want to allow the child nodes more freedom than would be allowed by the ﬁnal
settings of the step bounds. Control parameters XSLP_MIPALGORITHM, XSLP_MIPFIXSTEPBOUNDS
and XSLP_MIPRELAXSTEPBOUNDS can be used to free, or ﬁx to zero, various categories of stepbounds, thus effectively freeing the SLP variables or ﬁxing them to their values in the initial solution.
At each node, step bounds may again be ﬁxed to zero or relaxed or left in the same state as in thesolution to the parent node.
XSLP_MIPALGORITHM uses bits 2-3 (for the root node) and 4-5 (for other nodes) to determine which
step bounds are ﬁxed to zero (thus ﬁxing the values of the corresponding variables) or freed (thusallowing the variables to change, possibly beyond the point they were restricted to in the parent node).
Set bit 2 (4) of XSLP_MIPALGORITHM to implement relaxation of deﬁned categories of step bounds asdetermined by XSLP_MIPRELAXSTEPBOUNDS at the root node (at each node).
Set bit 3 (5) of XSLP_MIPALGORITHM to implement ﬁxing of deﬁned categories of step bounds asdetermined by XSLP_MIPFIXSTEPBOUNDS at the root node (at each node).
Alternatively, speciﬁc actions on setting bounds can be carried out by the user callback deﬁned by
XSLPsetcbprenode.
The default setting of XSLP_MIPALGORITHM is 17 which relaxes step bounds at all nodes except theroot node. The step bounds from the initial SLP optimization are retained for the root node.
XSLP_MIPRELAXSTEPBOUNDS and XSLP_MIPFIXSTEPBOUNDS are bitmaps which determine which
categories of SLP variables are processed.
Bit 1

Process SLP variables which do not appear in coefﬁcients but which do have coefﬁcients(constant or variable) in the original problem.

Bit 2Process SLP variables which have coefﬁcients (constant or variable) in the original
problem.

Bit 3

Process SLP variables which appear in coefﬁcients but which do not have coefﬁcients(constant or variable) in the original problem.

Bit 4Process SLP variables which appear in coefﬁcients.

In most cases, the default settings (XSLP_MIPFIXSTEPBOUNDS=0,
XSLP_MIPRELAXSTEPBOUNDS=15) are appropriate.

Fair Isaac Corporation Conﬁdential and Proprietary Information91Special Types of Problem

17.3.4

Advanced

Iterating at each node
Any number of SLP iterations can be carried out at each node. The maximum number is set by control
parameter XSLP_MIPITERLIMIT and is activated by XSLP_MIPALGORITHM. The signiﬁcant values for
XSLP_MIPITERLIMIT are:0

Perform an LP optimization with the current linearization. This means that, subject to the stepbounds, the SLP variables can take on other values, but the coefﬁcients are not updated.

1

As for 0, but the model is updated after each iteration, so that each node starts with a newlinearization based on the solution of its parent.

n>1

Perform up to n SLP iterations, but stop when a termination criterion is satisﬁed. If no othercriteria are set, the SLP will terminate on XSLP_ITERLIMIT or XSLP_MIPITERLIMIT
iterations, or when the SLP converges.

After the last MIP node has been evaluated and the MIP procedure has terminated, the ﬁnal solution
can be re-optimized using SLP to obtain a converged solution. This is only necessary if the individual
nodes are being terminated on a criterion other than SLP convergence.

17.3.5

Termination criteria at each nodeBecause the intention at each node is to get a reasonably good estimate for the SLP objective function
rather than to obtain a fully converged solution (which is only required at the optimum), it may bepossible to set looser but practical termination criteria. The following are provided:
Testing for movement of the objective function
This functions in a similar way to the extended convergence criteria for ordinary SLP convergence, butdoes not require the SLP variables to have converged in any way. The test is applied once stepbounding has been applied (or XSLP_SBSTART SLP iterations have taken place if step bounding is not
being used). The node will be terminated at the current iteration if the range of the objective function
values over the last XSLP_MIPOCOUNT SLP iterations is within XSLP_MIPOTOL_A or within
XSLP_MIPOTOL_R ∗ OBJ where OBJ is the average value of the objective function over those iterations.
Related control parameters:
XSLP_MIPOTOL_AXSLP_MIPOTOL_R
XSLP_MIPOCOUNT

Absolute tolerance
Relative tolerance
Number of SLP iterations over which the movement is measured

Testing the objective function against a cutoff
If the objective function is worse by a deﬁned amount than the best integer solution obtained so far,then the SLP will be terminated (and the node will be cut off). The node will be cut off at the current SLP
iteration if the objective function for the last XSLP_MIPCUTOFFCOUNT SLP iterations are all worse thanthe best obtained so far, and the difference is greater than XSLP_MIPCUTOFF_A andXSLP_MIPCUTOFF_R ∗ OBJ where OBJ is the best integer solution obtained so far.
Related control parameters:
XSLP_MIPCUTOFF_AXSLP_MIPCUTOFF_R
XSLP_MIPCUTOFFCOUNTXSLP_MIPCUTOFFLIMIT

17.3.6

Absolute amount by which the objective function is worse
Relative amount by which the objective function is worse
Number of SLP iterations checked
Number of SLP iterations before which the cutoff takes effectCallbacks
User callbacks are provided as follows:

Fair Isaac Corporation Conﬁdential and Proprietary Information

92

Special Types of Problem

AdvancedXSLPsetcbintsol(XSLPprob Prob,
int (⁎UserFunc)(XSLPprob myProb, void ⁎myObject),void ⁎Object);

UserFunc is called when an integer solution has been obtained. The return value is ignored.
XSLPsetcboptnode(XSLPprob Prob,
int (⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas),
void ⁎Object);

UserFunc is called when an optimal solution is obtained at a node.
If the feasibility ﬂag ⁎feas is set nonzero or if the function returns a nonzero value, then further
processing of the node will be terminated (it is declared infeasible).
XSLPsetcbprenode(XSLPprob Prob,
int (⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas),
void ⁎Object);

UserFunc is called at the beginning of each node after the SLP problem has been set up but before
any SLP iterations have taken place.
If the feasibility ﬂag ⁎feas is set nonzero or if the function returns a nonzero value, then the node will
be declared infeasible and cut off. In particular, the SLP optimization at the node will not be performed.
XSLPsetcbslpnode(XSLPprob Prob,
int (⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas),
void ⁎Object);

UserFunc is called after each SLP iteration at each node, after the SLP iteration, and after theconvergence and termination criteria have been tested.
If the feasibility ﬂag ⁎feas is set nonzero or if the function returns a nonzero value, then the node will
be declared infeasible and cut off.

17.4

Integer and semi-continuous delta variables
Functions implementing piecewise linear expressions often lead to local stalling due to the partial
derivatives not capturing the true nature of the behaviour of the function. Such functions are often
implemented as user functions or expressions using the abs function. To provide the Xpress with abetter way of evaluating such expressions, it is possible to mark variables (typically the key
dependencies of the expression) as having a semi-continuous delta variable with a minimum
perturbation size associated, which means the value of any expression that involves this variable isexpected to meaningfully change if the variable’s value in the current solution is changed by at least of
the semi-continuous value of the delta. If a minimum meaningful perturbation is not known, thevariable’s delta may be set up to being of type explore, when SLP will trial several values up to theprovided maximum in case of zero partials are detected. Using exploration deltas may signiﬁcantly
increase the number the formulas the variable is used in are evaluated.
It is important to note that the value with a semi-continuous delta will still be allowed to take any value
and make arbitrary steps between iterations, the extra information of the delta variable is solely used asa means of better evaluating the effect of change per variable.
User functions that can only be evaluated at given values (e.g. lookup tables or simulations over integer
input) may be modelled with variables with an integer delta variable. If a variable’s delta variable isﬂagged as being integer, with a step value of ’delta’, then assuming the variable has an initial value of’x0’, the possible values of the variable are ’x0 + i * delta’ where ’i’ is an integer number. If no initial value
is provided, the lower bound (or zero if no lover bound) is used to start the possible values from.

Fair Isaac Corporation Conﬁdential and Proprietary Information

93Special Types of Problem

Advanced

Variables with a semi-continuous delta are not expected to be harder than the problem without, in fact,
the extra information usually aids the solve noticeably.
A model with variables with integer deltas is considered to be hard. An integer delta is expected to be
used to model the domain of user function, and should not be used to otherwise model integrality of theoriginal variable. Variables with an integer delta used in constraints tend to make the problem difﬁcult
to solve unless their use is balanced by the presence of infeasibility breaker variables (penalty slacks).
To change the type of a delta variable, use ’XSLPchgdeltatype’ in the API and the ’setdeltatype’ method
in Mosel.
If variables with integer deltas are present in the problem, then SLP will run a number of heuristics aspart of the solve, please refer to XSLP_GRIDHEURSELECT.

Fair Isaac Corporation Conﬁdential and Proprietary Information

94

CHAPTER 18

Xpress NonLinear multistart
The feature is an additive feature that minimizes the development overhead and effort of implementing
parallel multistart searches. The purpose of multistart is two-fold. Traditionally, multistart is a so called
globalization feature. It is important to correctly understand what this technology offers, and what it
does not. It offers a convenient and efﬁcient way of exploring a larger feasible space building on top ofexisting local solver algorithms by the means of perturbing initial points and/or parameters or even the
problem statement itself. Multistart can also be viewed as a left-alone feature. In a typical situation,versions of a model react favourably to a set of control settings, dependent on data. Multistart allows
for a simple way of combining different control setting scenarios, increasing the robustness of themodel.
The base problem is deﬁned as the baseline: as the model is normally loaded it without any multistart
information, including problem description, callbacks and controls. A run or a job is deﬁned as aproblem instance that needs to be solved as part of multistart.
On completion, the current problem is set up to match that of the winner, allowing examination of thewinning strategy and solution using the normal means.
The original prob object is not reused, all runs are mode on a copy of the problem, allowing fullcustomization from the callbacks, including changes to structre.
Callbacks are inherited to the multistart jobs from the master problem and can be customized from thethe multistart callbacks. XSLinterrupt has a global scope, and a calling it terminates the multistart
search.
Although not intended as the primary use, multistart allows the execution of all supported problem
classes, so for example alternate MIP strategies can be used in parallel.
The mutistart job pool is maintained and can be extended until the ﬁrst maxim / minim withXSLP_MULTISTART on. This allows for doing optimizations runs aimed at generating multistart jobs.
The multistart pool is dynamic and new jobs can be added on the ﬂy from the jobstart and jobend
callbacks.

Fair Isaac Corporation Conﬁdential and Proprietary Information95III. ReferenceCHAPTER 19

Problem Attributes
During the optimization process, various properties of the problem being solved are stored and madeavailable to users of the Xpress NonLinear Libraries in the form of problem attributes. These can beaccessed in much the same manner as the controls. Examples of problem attributes include the sizesof arrays, for which library users may need to allocate space before the arrays themselves are retrieved.
A full list of the attributes available and their types may be found in this chapter.
Library users are provided with the following functions for obtaining the values of attributes:
XSLPgetintattrib

XSLPgetdblattrib

XSLPgetptrattrib

XSLPgetstrattrib

The attributes listed in this chapter are all preﬁxed with XSLP_. It is possible to use the above functions
with attributes for the Xpress Optimizer (attributes preﬁxed with XPRS_). For details of the Optimizer
attributes, see the Optimizer manual.
Example of the usage of the functions:XSLPgetintattrib(Prob, XSLP_ITER, &nIter);printf("The number of SLP iterations is %d\n", nIter);XSLPgetdblattrib(Prob, XSLP_ERRORCOSTS, &Errors);
printf("and the total error cost is %lg\n", Errors);

The following is a list of all the Xpress NonLinear attributes:
XSLP_COEFFICIENTS

Number of nonlinear coefﬁcientsp. 104XSLP_CURRENTDELTACOST

Current value of penalty cost multiplier for penalty delta vectors

p. 101XSLP_CURRENTERRORCOST

Current value of penalty cost multiplier for penalty error vectors

p. 101XSLP_CVS

Number of character variables

p. 104XSLP_DELTAS

Number of delta vectors created during augmentation

p. 104XSLP_ECFCOUNT

Number of infeasible constraints found at the point of linearization

p. 104XSLP_EQUALSCOLUMN

Index of the reserved "=" column

p. 105XSLP_ERRORCOSTS

Total penalty costs in the solution

p. 101XSLP_EXPLOREDELTAS

Number of variables with an exploration-type delta set up in the problem
p. 104XSLP_IFS

Number of internal functions

XSLP_IMPLICITVARIABLES

Number of SLP variables appearing only in coefﬁcients

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 105
p. 10597

Problem Attributes

XSLP_INTEGERDELTAS

Reference

Number of variables set up with an integer delta in the problem

XSLP_INTERNALFUNCCALLS

Number of calls made to internal functions

p. 105
p. 105XSLP_ITERSLP iteration countp. 106XSLP_JOBID

Unique identiﬁer for the current job

p. 106XSLP_KEEPBESTITER

The iteration in which the returned solution has been found.

p. 106XSLP_MINORVERSION

Xpress NonLinear minor version number

p. 106XSLP_MINUSPENALTYERRORS

Number of negative penalty error vectors

p. 106XSLP_MIPITER

Total number of SLP iterations in MISLP

p. 107XSLP_MIPNODES

Number of nodes explored in MISLP. This includes any nodes for which a
non-linear solve has been carried out.
p. 107XSLP_MIPPROBLEM

The underlying Optimizer MIP problem. XSLP_MIPPROBLEM is a referenceof type XPRSprob, and should be used in MISLP callbacks to access
MIP-speciﬁc Optimizer values (such as node and parent numbers). p. 120

XSLP_MIPSOLS

Number of integer solutions found in MISLP. This includes solutions foundduring the tree search or any heuristics.
p. 107XSLP_MODELCOLS

Number of model columns in the problem

p. 107XSLP_MODELROWS

Number of model rows in the problem

p. 107XSLP_MSSTATUS

Status of the mutlistart searchp. 108XSLP_NLPSTATUS

The solution status of the problem.

p. 108XSLP_NONCONSTANTCOEFF Number of coefﬁcients in the augmented problem that might change
between SLP iterations
p. 108XSLP_NONLINEARCONSTRAINTS

Number of nonlinear constraints in the problem

p. 109XSLP_OBJVALObjective function value excluding any penalty costs

p. 101XSLP_ORIGINALCOLS

Number of model columns in the problem

p. 109XSLP_ORIGINALROWS

Number of model rows in the problem

p. 109XSLP_PENALTYDELTACOLUMN

Index of column costing the penalty delta row

p. 109XSLP_PENALTYDELTAROW

Index of equality row holding the penalties for delta vectors

p. 109XSLP_PENALTYDELTAS

Number of penalty delta vectors

p. 110XSLP_PENALTYDELTATOTAL

Total activity of penalty delta vectors

p. 101XSLP_PENALTYDELTAVALUE

Total penalty cost attributed to penalty delta vectors

p. 102XSLP_PENALTYERRORCOLUMN

Index of column costing the penalty error row

p. 110XSLP_PENALTYERRORROW

Index of equality row holding the penalties for penalty error vectors p. 110

XSLP_PENALTYERRORS

Number of penalty error vectors

p. 110XSLP_PENALTYERRORTOTAL

Total activity of penalty error vectors

p. 102XSLP_PENALTYERRORVALUE

Total penalty cost attributed to penalty error vectors

p. 102XSLP_PLUSPENALTYERRORS

Number of positive penalty error vectors

p. 110Fair Isaac Corporation Conﬁdential and Proprietary Information98

Problem Attributes

ReferenceXSLP_PRESOLVEDELETEDDELTA

Number of potential delta variables deleted by XSLPpresolve p. 111

XSLP_PRESOLVEELIMINATIONS

Number of SLP variables eliminated by XSLPpresolve

XSLP_PRESOLVEFIXEDCOEF
XSLP_PRESOLVEFIXEDDR

p. 111

Number of SLP coefﬁcients ﬁxed by XSLPpresolvep. 111

Number of determining rows ﬁxed by XSLPpresolvep. 111XSLP_PRESOLVEFIXEDNZCOL

Number of variables ﬁxed to a nonzero value by XSLPpresolve p. 112

XSLP_PRESOLVEFIXEDSLPVAR Number of SLP variables ﬁxed by XSLPpresolvep. 112XSLP_PRESOLVEFIXEDZCOL

p. 112

Number of variables ﬁxed at zero by XSLPpresolve

XSLP_PRESOLVEPASSES

Number of passes made by the SLP nonlinear presolve procedurep. 112XSLP_PRESOLVESTATE

Indicates if the problem is presolved

p. 113XSLP_PRESOLVETIGHTENED

Number of bounds tightened by XSLPpresolvep. 113XSLP_PRIMALINTEGRAL

Local primal integral of the solve

XSLP_SBXCONVERGED

Number of step-bounded variables converged only on extended criteriap. 113XSLP_SEMICONTDELTAS

Number of variables with a minimum perturbation step set up in the
problemp. 113XSLP_SOLSTATUS

Indicates the type of solution returned by the solver.

XSLP_SOLUTIONPOOL

The underlying solution pool. XSLP_SOLUTIONPOOL is a reference of type
XPRSmipsolpool. Change control XSLP_ANALYZE to record the solutions
into the pool.
p. 120XSLP_SOLVERSELECTED

Includes information of which Xpress solver has been used to solve theproblemp. 114XSLP_STATUS

Bitmap holding the problem convergence statusp. 114XSLP_STOPSTATUS

Status of the optimization process.

p. 116XSLP_TOLSETS

Number of tolerance sets

p. 116XSLP_TOTALEVALUATIONERRORSThe total number of evaluation errors during the solve

p. 102

p. 114

p. 116XSLP_UCCONSTRAINEDCOUNT Number of unconverged variables with coefﬁcients in constrainingrows
p. 116XSLP_UFINSTANCES

Number of user function instances

p. 117XSLP_UFS

Number of user functions

p. 117XSLP_UNCONVERGED

Number of unconverged values

p. 117XSLP_USEDERIVATIVES

Indicates whether numeric or analytic derivatives were used to create thelinear approximations and solve the problem
p. 117XSLP_USERFUNCCALLS

Number of calls made to user functions

p. 118XSLP_VALIDATIONINDEX_A

Absolute validation index

p. 102XSLP_VALIDATIONINDEX_K

Relative ﬁrst order optimality validation index

p. 103XSLP_VALIDATIONINDEX_R

Relative validation index

p. 103

Fair Isaac Corporation Conﬁdential and Proprietary Information99

Problem Attributes

ReferenceXSLP_VARIABLES

Number of SLP variables

p. 118XSLP_VERSION

Xpress NonLinear major version number

p. 118XSLP_VERSIONDATE

Date of creation of Xpress NonLinear

p. 121XSLP_VSOLINDEXVertex solution index

p. 103XSLP_XPRSPROBLEM

The underlying Optimizer problem

p. 120XSLP_XSLPPROBLEM

The Xpress NonLinear problem

p. 120XSLP_ZEROESRESET

Number of placeholder entries set to zerop. 118XSLP_ZEROESRETAINED Number of potentially zero placeholders left untouchedp. 118XSLP_ZEROESTOTAL

p. 119Number of potential zero placeholder entries

Fair Isaac Corporation Conﬁdential and Proprietary Information

100Problem Attributes

19.1

Reference

Double problem attributes

XSLP_CURRENTDELTACOST
Description

Current value of penalty cost multiplier for penalty delta vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_CURRENTERRORCOSTXSLP_CURRENTERRORCOST
Description

Current value of penalty cost multiplier for penalty error vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_CURRENTDELTACOSTXSLP_ERRORCOSTS
Description

Total penalty costs in the solution

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_OBJVAL
Description

Objective function value excluding any penalty costs

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_PENALTYDELTATOTAL
Description

Total activity of penalty delta vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

101

Problem Attributes

ReferenceXSLP_PENALTYDELTAVALUE
Description

Total penalty cost attributed to penalty delta vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_PENALTYERRORTOTAL
Description

Total activity of penalty error vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_PENALTYERRORVALUE
Description

Total penalty cost attributed to penalty error vectors

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_PRIMALINTEGRAL
Description

Local primal integral of the solve

Type

DoubleSet by routinesXSLPmaxim, XSLPminimXSLP_VALIDATIONINDEX_A
Description

Absolute validation index

Type

DoubleSet by routinesXSLPvalidate

Fair Isaac Corporation Conﬁdential and Proprietary Information

102

Problem Attributes

ReferenceXSLP_VALIDATIONINDEX_K
Description

Relative ﬁrst order optimality validation index

Type

DoubleSet by routinesXSLPvalidatekktXSLP_VALIDATIONINDEX_R
Description

Relative validation index

Type

DoubleSet by routinesXSLPvalidate

XSLP_VSOLINDEX
Description

Vertex solution index

Type

DoubleNotes

The vertex solution index (VSOLINDEX) is a measure of how nearly the converged solution toa problem is at a vertex (that is, at the intersection of a set of constraints) of the feasible
region.
Where the solution is in the middle of a face, the solution will in general have been achieved
through the use of step bounds. The VSOLINDEX is the fraction of delta vectors which are not
at a bound in the solution. Therefore, a value of 1.0 means that no delta is at a step bound andtherefore the solution is at a vertex of the feasible region. Smaller values indicate that there
are deltas at step bounds and so the solution is further from being a vertex solution.

Fair Isaac Corporation Conﬁdential and Proprietary Information

103

Problem Attributes

19.2

Reference

Integer problem attributes

XSLP_COEFFICIENTS
Description

Number of nonlinear coefﬁcientsType

Integer

Set by routinesXSLPaddcoefs, XSLPchgcoef, XSLPloadcoefs, XSLPreadprob

XSLP_CVS
Description

Number of character variables

Type

Integer

Set by routinesXSLPreadprob

XSLP_DELTASDescription

Number of delta vectors created during augmentation

Type

Integer

Set by routinesXSLPconstruct

XSLP_ECFCOUNT
Description

Number of infeasible constraints found at the point of linearization

Type

Integer

Set by routinesXSLPmaxim, XSLPminim

See also

XSLP_ECFCHECK, XSLP_ECFTOL_A, XSLP_ECFTOL_R

XSLP_EXPLOREDELTASDescription

Number of variables with an exploration-type delta set up in the problem

Type

Integer

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

104

Problem Attributes

ReferenceXSLP_EQUALSCOLUMN
Description

Index of the reserved "=" column

Type

Integer

Note

If there had been no "=" column present, it will be assumed that the user needs the index to
add nonlinear terms into the problem that are not coefﬁcients, and an "=" columns will be
added to the problem, whose index is then returned. Please note, that this means that a call to
XSLPgetintattrib with this attribute might make a slight modiﬁcation to the problem itself.

Set by routinesXSLPconstruct, XSLPreadprob

XSLP_IFS
Description

Number of internal functions

Type

Integer

Set by routinesXSLPcreateprob

XSLP_IMPLICITVARIABLES
Description

Number of SLP variables appearing only in coefﬁcientsType

Integer

Set by routinesXSLPconstruct

XSLP_INTEGERDELTASDescription

Number of variables set up with an integer delta in the problem

Type

Integer

Set by routinesXSLPconstruct

XSLP_INTERNALFUNCCALLS
Description

Number of calls made to internal functions

Type

Integer

Set by routinesXSLPcascade, XSLPconstruct, XSLPevaluatecoef, XSLPevaluateformula,
XSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

105

Problem Attributes

ReferenceXSLP_ITER
Description

SLP iteration countType

Integer

Set by routinesXSLPmaxim, XSLPminimXSLP_JOBID
Description

Unique identiﬁer for the current job

TypeInteger

Note

Assigned when a job is created, and can be used to identify jobs in callbacks. Note that all
callback receives an optional job name that can be assigned at job creation time.

Set by routinesXSLPmaxim, XSLPminimXSLP_KEEPBESTITER
Description

The iteration in which the returned solution has been found.

Type

IntegerNote

A zero value indicates no solution or the ﬁlter option is off. A value of ’-1’ indicates the initialsolution has been returned.

Set by routinesXSLPmaxim, XSLPminimXSLP_MINORVERSION
Description

Xpress NonLinear minor version number

Type

Integer

Set by routinesXSLPinitXSLP_MINUSPENALTYERRORS
Description

Number of negative penalty error vectors

Type

Integer

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

106

Problem Attributes

ReferenceXSLP_MIPITER
Description

Total number of SLP iterations in MISLP

Type

Integer

Set by routinesXSLPglobal

XSLP_MIPNODES
Description

Number of nodes explored in MISLP. This includes any nodes for which a non-linear solve has
been carried out.

Type

Integer

Set by routinesXSLPglobal

XSLP_MIPSOLS
Description

Number of integer solutions found in MISLP. This includes solutions found during the tree
search or any heuristics.

Type

Integer

Set by routinesXSLPglobal

XSLP_MODELCOLS
Description

Number of model columns in the problem

Type

Integer

Note

This is the number of columns currently in the problem without any augmentation, i.e. thenumber of columns that describe the algebraic deﬁnition of the problem. These columns
always precede the augmentation columns in order. If the problem is presolved, this may besmaller than the number of original columns in the problem. To access the number of originalcolumns, use XSLP_ORIGINALCOLS.

XSLP_MODELROWS
Description

Number of model rows in the problem

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information107

Problem Attributes

Note

Reference

This is the number of rows currently in the problem without any augmentation, i.e. the numberof rows that describe the algebraic deﬁnition of the problem. These rows always precede theaugmentation rows in order. If the problem is presolved, this may be smaller than the numberof original rows in the problem. To access the number of original rows, use
XSLP_ORIGINALROWS.

XSLP_MSSTATUS
Description

Status of the mutlistart search

Type

Integer

Note

The value matches that of the winner job if the multistart search completes and a feasible
solution has been found. If no solution is found, it is set to XSLP_NLPSTATUS_INFEASIBLE. If
the search is terminated early, it is set to XSLP_NLPSTATUS_UNFINISHED (thought in whichcase the winner if any is still synchronized to the base problem and the solution and
XSLP_NLPSTATUS is available).

XSLP_NLPSTATUS
Description

The solution status of the problem.

Type

Integer

Values

0
1
2
3
4
5
6
7

Optimization unstarted (XSLP_NLPSTATUS_UNSTARTED)
Solution found (XSLP_NLPSTATUS_SOLUTION)
Globally optimal (XSLP_NLPSTATUS_OPTIMAL)
No solution found (XSLP_NLPSTATUS_NOSOLUTION)
Proven infeasible (XSLP_NLPSTATUS_INFEASIBLE)
Locally unbounded (XSLP_NLPSTATUS_UNBOUNDED)
Problem could not be solved due to numerical issues.
(XSLP_NLPSTATUS_UNFINISHED)
Unsolved (XSLP_NLPSTATUS_UNSOLVED)

Default value0

Set by routinesXSLPminim, XSLPmaxim, XSLPglobal

XSLP_NONCONSTANTCOEFF
Description

Number of coefﬁcients in the augmented problem that might change between SLP iterations

Type

Integer

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

108

Problem Attributes

ReferenceXSLP_NONLINEARCONSTRAINTS
Description

Number of nonlinear constraints in the problem

Type

Integer

Set by routinesXSLPconstruct

XSLP_ORIGINALCOLS
Description

Number of model columns in the problem

Type

IntegerNote

The number of columns in the original matrix before presolveing without any augmentation
columns.

XSLP_ORIGINALROWS
Description

Number of model rows in the problem

Type

IntegerNote

The number of rows in the original matric before presolveing without any augmentation rows.

XSLP_PENALTYDELTACOLUMN
Description

Index of column costing the penalty delta row

Type

Integer

Note

This index always counts from 1. It is zero if there is no penalty delta row.

Set by routinesXSLPconstruct

XSLP_PENALTYDELTAROW
Description

Index of equality row holding the penalties for delta vectors

Type

Integer

Note

This index always counts from 1. It is zero if there are no penalty delta vectors.

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

109

Problem Attributes

ReferenceXSLP_PENALTYDELTASDescription

Number of penalty delta vectors

Type

Integer

Set by routinesXSLPconstruct

XSLP_PENALTYERRORCOLUMN
Description

Index of column costing the penalty error row

Type

Integer

Note

This index always counts from 1. It is zero if there is no penalty error row.

Set by routinesXSLPconstruct

XSLP_PENALTYERRORROW
Description

Index of equality row holding the penalties for penalty error vectors

Type

Integer

Note

This index always counts from 1. It is zero if there are no penalty error vectors.

Set by routinesXSLPconstruct

XSLP_PENALTYERRORS
Description

Number of penalty error vectors

Type

Integer

Set by routinesXSLPconstruct

XSLP_PLUSPENALTYERRORS
Description

Number of positive penalty error vectors

Type

Integer

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

110Problem Attributes

ReferenceXSLP_PRESOLVEDELETEDDELTA
Description

Number of potential delta variables deleted by XSLPpresolve

Type

IntegerNote

A potential delta variable is deleted when an SLP variable is identiﬁed as not interacting in anonlinear way with any constraints (that is, it appears only in linear constraints, or is ﬁxed).

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEFIXEDCOEF, XSLP_PRESOLVEFIXEDDR, XSLP_PRESOLVEFIXEDNZCOL,XSLP_PRESOLVEFIXEDSLPVAR, XSLP_PRESOLVEFIXEDZCOL,XSLP_PRESOLVETIGHTENED, XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEELIMINATIONS
Description

Number of SLP variables eliminated by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDSLPVAR,XSLP_PRESOLVEFIXEDZCOL, XSLP_PRESOLVETIGHTENEDXSLP_PRESOLVEFIXEDCOEF
Description

Number of SLP coefﬁcients ﬁxed by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDSLPVAR,XSLP_PRESOLVEFIXEDZCOL, XSLP_PRESOLVETIGHTENED,XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEFIXEDDR
Description

Number of determining rows ﬁxed by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information

111

Problem Attributes

See also

ReferenceXSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDCOEF,
XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDSLPVAR,XSLP_PRESOLVEFIXEDZCOL, XSLP_PRESOLVETIGHTENED,XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEFIXEDNZCOL
Description

Number of variables ﬁxed to a nonzero value by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDCOEF, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDSLPVAR, XSLP_PRESOLVEFIXEDZCOL,XSLP_PRESOLVETIGHTENED, XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEFIXEDSLPVAR
Description

Number of SLP variables ﬁxed by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDCOEF, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDZCOL, XSLP_PRESOLVETIGHTENED,XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEFIXEDZCOL
Description

Number of variables ﬁxed at zero by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDCOEF, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDSLPVAR,XSLP_PRESOLVETIGHTENED, XSLP_PRESOLVEELIMINATIONSXSLP_PRESOLVEPASSES
Description

Number of passes made by the SLP nonlinear presolve procedure

Type

Integer

Set by routinesXSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information

112

Problem Attributes

ReferenceXSLP_PRESOLVESTATE
Description

Indicates if the problem is presolved

Type

Integer

Values0
1
2

Set by routines

The problem is not presolved
The problem is presolved, but no columns or rows have been removed from the
problem
The problem is fully presolved, and the column and row indices do not match theoriginal problem

XSLPmaxim, XSLPminim, XSLPpresolve

XSLP_PRESOLVETIGHTENED
Description

Number of bounds tightened by XSLPpresolve

Type

Integer

Set by routinesXSLPpresolve

See also

XSLP_PRESOLVEDELETEDDELTA, XSLP_PRESOLVEFIXEDCOEF, XSLP_PRESOLVEFIXEDDR,XSLP_PRESOLVEFIXEDNZCOL, XSLP_PRESOLVEFIXEDSLPVAR,XSLP_PRESOLVEFIXEDZCOL, XSLP_PRESOLVEELIMINATIONSXSLP_SBXCONVERGED
Description

Number of step-bounded variables converged only on extended criteria

Type

Integer

Set by routinesXSLPmaxim, XSLPminimXSLP_SEMICONTDELTASDescription

Number of variables with a minimum perturbation step set up in the problem

Type

Integer

Set by routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

113

Problem Attributes

ReferenceXSLP_SOLVERSELECTED
Description

Includes information of which Xpress solver has been used to solve the problem

Type

Integer

Values-1
0
1
2

Default value-1

Set by routinesXSLPmaxim, XSLPminim

Note

The following constants are provided:
0
1
2

Unset
Xpress-SLP
Knitro (Artelys)
Xpress Optimizer

XSLP_SOLVER_XSLPXSLP_SOLVER_KNITROXSLP_SOLVER_OPTIMIZERXSLP_SOLSTATUS
Description

Indicates the type of solution returned by the solver.

Type

Integer

Values0
1
2
3
4Default value0

Set by routinesXSLPminim, XSLPmaxim, XSLPglobal

No solution available.
A solution with no dual information.
A locally optimal solution with dual information.
A globally optimal solution without dual information.
A globally optimal solution with dual information.

XSLP_STATUS
Description

Bitmap holding the problem convergence status

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

114

Problem Attributes

ValuesReference

Bit
0
1
2
3
4
5
6
7
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Note

Meaning
Converged on objective function with no unconverged values in active constraints.
Converged on objective function with some variables converged on extended criteria
only.
LP solution is infeasible.
LP solution is unﬁnished (not optimal or infeasible).
SLP terminated on maximum SLP iterations.
SLP is integer infeasible.
SLP converged with residual penalty errors.
Converged on objective.
SLP terminated on max time.
SLP terminated by user.
Some variables are linked to active constraints.
No unconverged values in active constraints.
OTOL is satisﬁed - range of objective change small, active step bounds.
VTOL is satisﬁed - range of objective change is small.
XTOL is satisﬁed - range of objective change small, no unconverged in active.
WTOL is satisﬁed - convergence continuation.
ERRORTOL satisﬁed - penalties not increased further.
EVTOL satisﬁed - penalties not increased further.
There were iterations where the solution had to be polished.
There were iterations where the solution polishing failed.
There were iterations where rows were enforced.
Terminated due to XSLP_INFEASLIMIT.

A value of zero after SLP optimization means that the solution is fully converged.
The following constants are provided for checking these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 9
Setting bit 10
Setting bit 11
Setting bit 12
Setting bit 13
Setting bit 14
Setting bit 15
Setting bit 16
Setting bit 17
Setting bit 18
Setting bit 19
Setting bit 20
Setting bit 21
Setting bit 22

XSLP_STATUS_CONVERGEDOBJUCCXSLP_STATUS_CONVERGEDOBJSBXXSLP_STATUS_LPINFEASIBLEXSLP_STATUS_LPUNFINISHEDXSLP_STATUS_MAXSLPITERATIONSXSLP_STATUS_INTEGERINFEASIBLEXSLP_STATUS_RESIDUALPENALTIESXSLP_STATUS_CONVERGEDOBJOBJXSLP_STATUS_MAXTIMEXSLP_STATUS_USERXSLP_STATUS_VARSLINKEDINACTIVEXSLP_STATUS_NOVARSINACTIVEXSLP_STATUS_OTOLXSLP_STATUS_VTOLXSLP_STATUS_XTOLXSLP_STATUS_WTOLXSLP_STATUS_ERROTOLXSLP_STATUS_EVTOLXSLP_STATUS_POLISHEDXSLP_STATUS_POLISH_FAILUREXSLP_STATUS_ENFORCEDXSLP_STATUS_CONSECUTIVE_INFEAS

Fair Isaac Corporation Conﬁdential and Proprietary Information

115

Problem Attributes

Set by routines

Reference

XSLPmaxim, XSLPminimXSLP_STOPSTATUS
Description

Status of the optimization process.

Type

Integer

Note

Possible values are:Set by routines

Value

Description

XSLP_STOP_NONE

no interruption - the solve completed normallyXSLP_STOP_TIMELIMIT

time limit hit

XSLP_STOP_CTRLC

control C hit

XSLP_STOP_NODELIMIT

node limit hit

XSLP_STOP_ITERLIMIT

iteration limit hit

XSLP_STOP_MIPGAPMIP gap is sufﬁciently small

XSLP_STOP_SOLLIMIT

solution limit hit

XSLP_STOP_USER

user interrupt.

XSLPnlpoptimize, XSLPmaxim, XSLPminim, XSLPglobal.

XSLP_TOLSETS
Description

Number of tolerance sets

Type

Integer

Set by routinesXSLPaddtolsets, XSLPchgtolset, XSLPloadtolsets, XSLPreadprob

XSLP_TOTALEVALUATIONERRORS
Description

The total number of evaluation errors during the solve

Type

Integer

Set by routines
Set by routinesXSLPnlpoptimize, XSLPmaxim, XSLPminim, XSLPglobal.

XSLP_UCCONSTRAINEDCOUNT
Description

Number of unconverged variables with coefﬁcients in constraining rows

Fair Isaac Corporation Conﬁdential and Proprietary Information

116

Problem Attributes

Reference

Type

Integer

Set by routinesXSLPmaxim, XSLPminimXSLP_UFINSTANCES
Description

Number of user function instances

Type

Integer

Set by routinesXSLPconstruct

XSLP_UFS
Description

Number of user functions

Type

Integer

Set by routinesXSLPadduserfunction, XSLPdeluserfunction, XSLPreadprob

XSLP_UNCONVERGED
Description

Number of unconverged values

Type

Integer

Note

Prior to the ﬁrst iteration this will return -1.

Set by routinesXSLPmaxim, XSLPminimXSLP_USEDERIVATIVES
Description

Indicates whether numeric or analytic derivatives were used to create the linear
approximations and solve the problem

Type

Integer

Values0
1

Set by routinesXSLPconstruct

numeric derivatives.
analytic derivatives for all formulae unless otherwise speciﬁed.

Fair Isaac Corporation Conﬁdential and Proprietary Information

117

Problem Attributes

ReferenceXSLP_USERFUNCCALLS
Description

Number of calls made to user functions

Type

Integer

Set by routinesXSLPcascade, XSLPconstruct, XSLPevaluatecoef, XSLPevaluateformula,
XSLPmaxim, XSLPminimXSLP_VARIABLES
Description

Number of SLP variables

Type

Integer

Set by routinesXSLPconstruct

XSLP_VERSION
Description

Xpress NonLinear major version number

Type

Integer

Set by routinesXSLPinitXSLP_ZEROESRESET
Description

Number of placeholder entries set to zeroType

Integer

Note

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.

Set by routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERIONCOUNT, XSLP_ZEROCRITERIONSTART, XSLP_ZEROESRETAINED,XSLP_ZEROESTOTAL, Management of zero placeholder entriesXSLP_ZEROESRETAINED
Description

Number of potentially zero placeholders left untouchedType

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

118

Problem Attributes

Reference

Note

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.

Set by routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERIONCOUNT, XSLP_ZEROCRITERIONSTART, XSLP_ZEROESRESET,XSLP_ZEROESTOTAL, Management of zero placeholder entriesXSLP_ZEROESTOTAL
Description

Number of potential zero placeholder entries

Type

Integer

Note

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.

Set by routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERIONCOUNT, XSLP_ZEROCRITERIONSTART, XSLP_ZEROESRESET,XSLP_ZEROESRETAINED, Management of zero placeholder entries

Fair Isaac Corporation Conﬁdential and Proprietary Information

119Problem Attributes

19.3

Reference

Reference (pointer) problem attributes
The reference attributes are void pointers whose size (32 or 64 bit) depends on the platform.

XSLP_MIPPROBLEM
Description

The underlying Optimizer MIP problem. XSLP_MIPPROBLEM is a reference of type XPRSprob,
and should be used in MISLP callbacks to access MIP-speciﬁc Optimizer values (such asnode and parent numbers).

Type

Reference

Set by routinesXSLPglobal

XSLP_SOLUTIONPOOL
Description

The underlying solution pool. XSLP_SOLUTIONPOOL is a reference of type XPRSmipsolpool.
Change control XSLP_ANALYZE to record the solutions into the pool.

Type

Reference

Set by routinesXSLPminim, XSLPmaxim

XSLP_XPRSPROBLEM
Description

The underlying Optimizer problem

Type

Reference

Set by routinesXSLPcreateprob

XSLP_XSLPPROBLEM
Description

The Xpress NonLinear problem

Type

Reference

Set by routinesXSLPcreateprob

Fair Isaac Corporation Conﬁdential and Proprietary Information120

Problem Attributes

19.4

Reference

String problem attributes

XSLP_VERSIONDATE
Description

Date of creation of Xpress NonLinear

Type

StringNote

The format of the date is dd mmm yyyy.

Set by routinesXSLPinit

Fair Isaac Corporation Conﬁdential and Proprietary Information

121

CHAPTER 20

Control Parameters
Various controls exist within Xpress NonLinear to govern the solution procedure and the form of theoutput. Some of these take integer values and act as switches between various types of behavior.
Many are tolerances on values related to the convergence criteria; these are all double precision. There
are also a few controls which are character strings, setting names for structures. Any of these may bealtered by the user to enhance performance of the SLP algorithm. In most cases, the default values
provided have been found to work well in practice over a range of problems and caution should be
exercised if they are changed.
Users of the Xpress NonLinear function library are provided with the following set of functions forsetting and obtaining control values:
XSLPgetintcontrol

XSLPgetdblcontrol

XSLPgetstrcontrol

XSLPsetintcontrol

XSLPsetdblcontrol

XSLPsetstrcontrol

All the controls as listed in this chapter are preﬁxed with XSLP_. It is possible to use the above
functions with control parameters for the Xpress Optimizer (controls preﬁxed with XPRS_). For detailsof the Optimizer controls, see the Optimizer manual.
Example of the usage of the functions:XSLPgetintcontrol(Prob, XSLP_PRESOLVE, &presolve);
printf("The value of PRESOLVE was %d\n", presolve);
XSLPsetintcontrol(Prob, XSLP_PRESOLVE, 1-presolve);
printf("The value of PRESOLVE is now %d\n", 1-presolve);

The following is a list of all the Xpress NonLinear controls:
XSLP_ALGORITHM

Bit map describing the SLP algorithm(s) to be usedXSLP_ANALYZE

Bit map activating additional options supporting model / solution pathanalyzis
p. 168XSLP_ATOL_A

Absolute delta convergence tolerance

p. 130XSLP_ATOL_R

Relative delta convergence tolerance

p. 130XSLP_AUGMENTATION

Bit map describing the SLP augmentation method(s) to be used

p. 169XSLP_AUTOSAVE

Frequency with which to save the model

p. 170XSLP_BARCROSSOVERSTARTXSLP_BARLIMIT

Default crossover activation behaviour for barrier start

Number of initial SLP iterations using the barrier method

p. 166

p. 171
p. 171XSLP_BARSTALLINGLIMIT Number of iterations to allow numerical failures in barrier before
switching to dual
p. 172

Fair Isaac Corporation Conﬁdential and Proprietary Information

122

Control Parameters

ReferenceXSLP_BARSTALLINGOBJLIMIT Number of iterations over which to measure the objective change
for barrier iterations with no crossoverp. 172XSLP_BARSTALLINGTOL Required change in the objective when progress is measured in barrier
iterations without crossoverp. 130XSLP_BARSTARTOPS

Controls behaviour when the barrier is used to solve the linearizations
p. 172XSLP_CALCTHREADS

Number of threads used for formula and derivatives evaluations

p. 173XSLP_CASCADE

Bit map describing the cascading to be used

p. 173XSLP_CASCADENLIMIT

Maximum number of iterations for cascading with non-linear determiningrows
p. 174XSLP_CASCADETOL_PA

Absolute cascading print tolerance

p. 131XSLP_CASCADETOL_PR

Relative cascading print tolerance

p. 131XSLP_CDTOL_A

Absolute tolerance for deducing constant derivatives

p. 131XSLP_CDTOL_R

Relative tolerance for deducing constant derivatives

p. 132XSLP_CLAMPSHRINK

Shrink ratio used to impose strict convergence on variables converged inextended criteria only
p. 132XSLP_CLAMPVALIDATIONTOL_A Absolute validation tolerance for applying XSLP_CLAMPSHRINK
p. 133XSLP_CLAMPVALIDATIONTOL_R Relative validation tolerance for applying XSLP_CLAMPSHRINK
p. 133XSLP_CONTROL

Bit map describing which Xpress NonLinear functions also activate thecorresponding Optimizer Library function
p. 174XSLP_CONVERGENCEOPS Bit map describing which convergence tests should be carried out

p. 175XSLP_CTOL

Closure convergence tolerance

p. 133XSLP_CVNAMEName of the set of character variables to be used

p. 208XSLP_DAMP

Damping factor for updating values of variables

p. 134XSLP_DAMPEXPAND

Multiplier to increase damping factor during dynamic damping

p. 134XSLP_DAMPMAX

Maximum value for the damping factor of a variable during dynamic
damping
p. 134XSLP_DAMPMIN

Minimum value for the damping factor of a variable during dynamic
damping
p. 135XSLP_DAMPSHRINK

Multiplier to decrease damping factor during dynamic damping

p. 135XSLP_DAMPSTARTSLP iteration at which damping is activated

p. 176XSLP_DCLIMIT

Default iteration delay for delayed constraints

p. 176XSLP_DCLOG

Amount of logging information for activcation of delayed constraints p. 176

XSLP_DEFAULTIVDefault initial value for an SLP variable if none is explicitly given

p. 135XSLP_DEFAULTSTEPBOUND Minimum initial value for the step bound of an SLP variable if none is
explicitly given
p. 136

Fair Isaac Corporation Conﬁdential and Proprietary Information

123

Control Parameters

ReferenceXSLP_DELAYUPDATEROWS

Number of SLP iterations before update rows are fully activated

p. 176XSLP_DELTA_A

Absolute perturbation of values for calculating numerical derivatives p. 136

XSLP_DELTA_R

Relative perturbation of values for calculating numerical derivatives p. 136

XSLP_DELTA_X

Minimum absolute value of delta coefﬁcients to be retained

p. 137XSLP_DELTA_Z

Tolerance used when calculating derivatives

p. 137XSLP_DELTA_ZERO

Absolute zero acceptance tolerance used when calculating derivatives
p. 137XSLP_DELTACOST

Initial penalty cost multiplier for penalty delta vectors

p. 138XSLP_DELTACOSTFACTOR

Factor for increasing cost multiplier on total penalty delta vectors

p. 138XSLP_DELTAFORMAT

Formatting string for creation of names for SLP delta vectors

p. 208XSLP_DELTAMAXCOST

Maximum penalty cost multiplier for penalty delta vectors

p. 138XSLP_DELTAOFFSET

Position of ﬁrst character of SLP variable name used to create name ofdelta vector
p. 177XSLP_DELTAZLIMIT

Number of SLP iterations during which to apply XSLP_DELTA_Z

p. 177XSLP_DERIVATIVES

Bitmap describing the method of calculating derivatives

p. 178XSLP_DETERMINISTIC

Determines if the parallel features of SLP should be guaranteed to be
deterministic
p. 178XSLP_DJTOL

Tolerance on DJ value for determining if a variable is at its step boundp. 139XSLP_DRCOLTOL

The minimum absolute magnitude of a determining column, for which thedetermined variable is still regarded as well deﬁned
p. 139XSLP_ECFCHECKCheck feasibility at the point of linearization for extended convergencecriteria
p. 178XSLP_ECFTOL_A

Absolute tolerance on testing feasibility at the point of linearization p. 139

XSLP_ECFTOL_R

Relative tolerance on testing feasibility at the point of linearization

p. 140XSLP_ECHOXPRSMESSAGES Controls if the XSLP message callback should relay messages from the
XPRS library.
p. 179XSLP_ENFORCECOSTSHRINK Factor by which to decrease the current penalty multiplier whenenforcing rows.
p. 140XSLP_ENFORCEMAXCOST Maximum penalty cost in the objective before enforcing most violatingrows
p. 141XSLP_ERRORCOST

Initial penalty cost multiplier for penalty error vectors

p. 141XSLP_ERRORCOSTFACTOR

Factor for increasing cost multiplier on total penalty error vectors

p. 141XSLP_ERRORMAXCOST

Maximum penalty cost multiplier for penalty error vectors

p. 142XSLP_ERROROFFSET

Position of ﬁrst character of constraint name used to create name ofpenalty error vectors
p. 179XSLP_ERRORTOL_A

Absolute tolerance for error vectors

p. 142XSLP_ERRORTOL_P

Absolute tolerance for printing error vectors

p. 142

Fair Isaac Corporation Conﬁdential and Proprietary Information

124

Control Parameters

ReferenceXSLP_ESCALATION

Factor for increasing cost multiplier on individual penalty error vectors
p. 143XSLP_ETOL_A

Absolute tolerance on penalty vectors

p. 143XSLP_ETOL_R

Relative tolerance on penalty vectors

p. 143XSLP_EVALUATE

Evaluation strategy for user functions

p. 180XSLP_EVTOL_A

Absolute tolerance on total penalty costs

p. 144XSLP_EVTOL_R

Relative tolerance on total penalty costs

p. 144XSLP_EXPAND

Multiplier to increase a step boundp. 145XSLP_FEASTOLTARGET

When set, this deﬁnes a target feasibility tolerance to which thelinearizations are solved top. 145XSLP_FILTER

Bit map for controlling solution updates

p. 180XSLP_FINDIV

Option for running a heuristic to ﬁnd a feasible initial point

p. 181XSLP_FUNCEVAL

Bit map for determining the method of evaluating user functions and theirderivatives
p. 181XSLP_GRANULARITY

Base for calculating penalty costs

p. 145XSLP_GRIDHEURSELECT Bit map selectin which heuristics to run if the problem has variable with an
integer delta
p. 182XSLP_HESSIAN

Second order differentiation mode when using analytical derivatives p. 183

XSLP_HEURSTRATEGY

Branch and Bound: This speciﬁes the MINLP heuristic strategy. On someproblems it is worth trying more comprehensive heuristic strategies by
setting HEURSTRATEGY to 2 or 3.
p. 182XSLP_INFEASLIMIT

The maximum number of consecutive infeasible SLP iterations which canoccur before Xpress-SLP terminates
p. 183XSLP_INFINITY

Value returned by a divide-by-zero in a formula

XSLP_ITERFALLBACKOPS

Alternative LP level control values for numerically challengeing problems
p. 208XSLP_ITERLIMIT

The maximum number of SLP iterations

p. 183XSLP_ITOL_A

Absolute impact convergence tolerance

p. 146XSLP_ITOL_R

Relative impact convergence tolerance

p. 147XSLP_IVNAMEName of the set of initial values to be used

p. 209XSLP_JACOBIANFirst order differentiation mode when using analytical derivatives

p. 184XSLP_LINQUADBR

Use linear and quadratic constraints and objective function to further
reduce bounds on all variables
p. 184XSLP_LOG

Level of printing during SLP iterations

p. 184XSLP_LSITERLIMIT

Number of iterations in the line searchp. 185

p. 146XSLP_LSPATTERNLIMIT Number of iterations in the pattern search preceding the line search p. 185
XSLP_LSSTART

Iteration in which to active the line search

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 185125

Control Parameters

ReferenceXSLP_LSZEROLIMIT

Maximum number of zero length line search steps before line search isdeactivated
p. 186XSLP_MATRIXTOLProvides an override value for XPRS_MATRIXTOL, which controls thesmallest magnitude of matrix coefﬁcentsp. 147XSLP_MAXTIMEThe maximum time in seconds that the SLP optimization will run before it
terminates
p. 186XSLP_MAXWEIGHT

Maximum penalty weight for delta or error vectors

p. 148XSLP_MEMORYFACTOR

Factor for expanding size of dynamic arrays in memory

p. 148XSLP_MERITLAMBDA

Factor by which the net objective is taken into account in the merit function
p. 148XSLP_MINSBFACTOR

Factor by which step bounds can be decreased beneath XSLP_ATOL_A
p. 149XSLP_MINUSDELTAFORMAT Formatting string for creation of names for SLP negative penalty delta
vectors
p. 209XSLP_MINUSERRORFORMAT Formatting string for creation of names for SLP negative penalty error
vectors
p. 210XSLP_MINWEIGHT

Minimum penalty weight for delta or error vectors

p. 149XSLP_MIPALGORITHM

Bitmap describing the MISLP algorithms to be used

p. 186XSLP_MIPCUTOFF_A

Absolute objective function cutoff for MIP termination

p. 149XSLP_MIPCUTOFF_R

Absolute objective function cutoff for MIP termination

p. 150XSLP_MIPCUTOFFCOUNT Number of SLP iterations to check when considering a node for cutting off
p. 188XSLP_MIPCUTOFFLIMIT Number of SLP iterations to check when considering a node for cutting off
p. 188XSLP_MIPDEFAULTALGORITHM Default algorithm to be used during the global search in MISLP
p. 189XSLP_MIPERRORTOL_A

Absolute penalty error cost tolerance for MIP cut-off

p. 150XSLP_MIPERRORTOL_R

Relative penalty error cost tolerance for MIP cut-off

p. 150XSLP_MIPFIXSTEPBOUNDS

Bitmap describing the step-bound ﬁxing strategy during MISLP

p. 189XSLP_MIPITERLIMIT

Maximum number of SLP iterations at each node

p. 190XSLP_MIPLOG

Frequency with which MIP status is printed

p. 190XSLP_MIPOCOUNT

Number of SLP iterations at each node over which to measure objectivefunction variation
p. 190XSLP_MIPOTOL_A

Absolute objective function tolerance for MIP termination

p. 151XSLP_MIPOTOL_R

Relative objective function tolerance for MIP termination

p. 151XSLP_MIPRELAXSTEPBOUNDS Bitmap describing the step-bound relaxation strategy during MISLP
p. 191XSLP_MSMAXBOUNDRANGE

Deﬁnes the maximum range inside which initial points are generated bymultistart presets
p. 152

Fair Isaac Corporation Conﬁdential and Proprietary Information

126

Control Parameters

ReferenceXSLP_MTOL_A

Absolute effective matrix element convergence tolerance

p. 152XSLP_MTOL_R

Relative effective matrix element convergence tolerance

p. 153XSLP_MULTISTART

The multistart master control. Deﬁnes if the multistart search is to be
initiated, or if only the baseline model is to be solved.
p. 191XSLP_MULTISTART_MAXSOLVES The maximum number of jobs to create during the multistart
search.
p. 191XSLP_MULTISTART_MAXTIMEThe maximum total time to be spent in the mutlistart search.

p. 192XSLP_MULTISTART_POOLSIZE The maximum number of problem objects allowed to pool up before
synchronization in the deterministic multistart.
p. 192XSLP_MULTISTART_SEED

Random seed used for the automatic generation of initial point whenloading multistart presets
p. 193XSLP_MULTISTART_THREADS

The maximum number of threads to be used in multistartp. 193XSLP_MVTOL

Marginal value tolerance for determining if a constraint is slackp. 153XSLP_OBJSENSE

Objective function sense

p. 154XSLP_OBJTOPENALTYCOSTXSLP_OCOUNT

Factor to estimate initial penalty costs from objective function

p. 154

Number of SLP iterations over which to measure objective function
variation for static objective (2) convergence criterion
p. 193XSLP_OPTIMALITYTOLTARGET When set, this deﬁnes a target optimality tolerance to which thelinearizations are solved top. 155XSLP_OTOL_A

Absolute static objective (2) convergence tolerance

p. 155XSLP_OTOL_R

Relative static objective (2) convergence tolerance

p. 155XSLP_PENALTYCOLFORMAT Formatting string for creation of the names of the SLP penalty transfer
vectors
p. 210XSLP_PENALTYINFOSTART

Iteration from which to record row penalty information

p. 194XSLP_PENALTYROWFORMAT Formatting string for creation of the names of the SLP penalty rows
p. 210XSLP_PLUSDELTAFORMAT

Formatting string for creation of names for SLP positive penalty delta
vectors
p. 211XSLP_PLUSERRORFORMAT

Formatting string for creation of names for SLP positive penalty error
vectors
p. 211XSLP_POSTSOLVEThis control determines whether postsolving should be performed
automaticallyXSLP_PRESOLVEThis control determines whether presolving should be performed prior tostarting the main algorithm
p. 194XSLP_PRESOLVELEVELThis control determines the level of changes presolve may carry out on the
problemp. 195XSLP_PRESOLVEOPS

Bitmap indicating the SLP presolve actions to be taken

p. 194

p. 195XSLP_PRESOLVEPASSLIMIT Maximum number of passes through the problem to improve SLP
boundsp. 196

Fair Isaac Corporation Conﬁdential and Proprietary Information

127

Control ParametersXSLP_PRESOLVEZERO

Reference

Minimum absolute value for a variable which is identiﬁed as nonzero
during SLP presolve
p. 156XSLP_PRIMALINTEGRALREF Reference solution value to take into account when calculating the
primal integral
p. 156XSLP_PROBING

This control determines whether probing on a subset of variables shouldbe performed prior to starting the main algorithm. Probing runs multiple
times bound reduction in order to further tighten the bounding box. p. 196

XSLP_REFORMULATE

Controls the problem reformulations carried out before augmentation. This
allows SLP to take advantage of dedicated algorithms for special problem
classes.
p. 196XSLP_SAMECOUNT

Number of steps reaching the step bound in the same direction before stepbounds are increased
p. 197XSLP_SAMEDAMP

Number of steps in same direction before damping factor is increased
p. 197XSLP_SBLOROWFORMAT

Formatting string for creation of names for SLP lower step bound rows
p. 211XSLP_SBNAME

Name of the set of initial step bounds to be usedXSLP_SBROWOFFSET

Position of ﬁrst character of SLP variable name used to create name of
SLP lower and upper step bound rows
p. 198XSLP_SBSTARTSLP iteration after which step bounds are ﬁrst appliedXSLP_SBUPROWFORMAT

Formatting string for creation of names for SLP upper step bound rows
p. 212XSLP_SCALE

When to re-scale the SLP problem

p. 198XSLP_SCALECOUNT

Iteration limit used in determining when to re-scale the SLP matrix

p. 199XSLP_SHRINK

Multiplier to reduce a step boundp. 157XSLP_SHRINKBIAS

Deﬁnes an overwrite / adjustment of step bounds for improving iterations
p. 157XSLP_SLPLOG

Frequency with which SLP status is printed

p. 200XSLP_SOLVER

First order differentiation mode when using analytical derivatives

p. 199XSLP_STOL_A

Absolute slack convergence tolerance

p. 157XSLP_STOL_R

Relative slack convergence tolerance

p. 158p. 212

p. 198XSLP_STOPOUTOFRANGE Stop optimization and return error code if internal function argument is outof range
p. 200XSLP_THREADSDefault number of threads to be usedXSLP_THREADSAFEUSERFUNC

Deﬁnes if user functions are allowed to be called in parallelp. 200p. 201XSLP_TIMEPRINT

Print additional timings during SLP optimization

p. 200XSLP_TOLNAME

Name of the set of tolerance sets to be used

p. 212XSLP_TRACEMASK

Mask of variable or row names that are to be traced through the SLP
iteratesp. 213

Fair Isaac Corporation Conﬁdential and Proprietary Information

128

Control Parameters

ReferenceXSLP_TRACEMASKOPS

Controls the information printed for XSLP_TRACEMASK. The order inwhich the information is printed is determined by the order of bits in
XSLP_TRACEMASKOPS.
p. 201XSLP_UNFINISHEDLIMIT

Number of times within one SLP iteration that an unﬁnished LP
optimization will be continued

p. 202XSLP_UPDATEFORMAT

Formatting string for creation of names for SLP update rows

p. 213XSLP_UPDATEOFFSET

Position of ﬁrst character of SLP variable name used to create name of
SLP update row
p. 202XSLP_VALIDATIONTARGET_K

Optimality target tolerance

p. 158XSLP_VALIDATIONTARGET_R

Feasiblity target tolerance

p. 158XSLP_VALIDATIONTOL_A

Absolute tolerance for the XSLPvalidate procedurep. 159XSLP_VALIDATIONTOL_R

Relative tolerance for the XSLPvalidate procedurep. 159XSLP_VCOUNT

Number of SLP iterations over which to measure static objective (3)convergencep. 203XSLP_VLIMIT

Number of SLP iterations after which static objective (3) convergencetesting starts
p. 203XSLP_VTOL_A

Absolute static objective (3) convergence tolerance

p. 160XSLP_VTOL_R

Relative static objective (3) convergence tolerance

p. 160XSLP_WCOUNT

Number of SLP iterations over which to measure the objective for theextended convergence continuation criterion
p. 204XSLP_WTOL_A

Absolute extended convergence continuation tolerance

p. 161XSLP_WTOL_R

Relative extended convergence continuation tolerance

p. 162XSLP_XCOUNT

Number of SLP iterations over which to measure static objective (1)convergencep. 205XSLP_XLIMIT

Number of SLP iterations up to which static objective (1) convergencetesting starts
p. 205XSLP_XTOL_A

Absolute static objective function (1) tolerance

p. 163XSLP_XTOL_R

Relative static objective function (1) tolerance

p. 163XSLP_ZERO

Absolute tolerance

p. 164XSLP_ZEROCRITERION

Bitmap determining the behavior of the placeholder deletion procedure
p. 206XSLP_ZEROCRITERIONCOUNT Number of consecutive times a placeholder entry is zero before being
considered for deletion
p. 207XSLP_ZEROCRITERIONSTART SLP iteration at which criteria for deletion of placeholder entries are
ﬁrst activated.
p. 207

Fair Isaac Corporation Conﬁdential and Proprietary Information

129

Control Parameters

20.1

Reference

Double control parametersXSLP_ATOL_A
Description

Absolute delta convergence tolerance

Type

DoubleNote

The absolute delta convergence criterion assesses the change in value of a variable (δX)
against the absolute delta convergence tolerance. If
δX < XSLP_ATOL_A
then the variable has converged on the absolute delta convergence criterion. When the value
is set to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-3 and
1e-6.

Default value-1.0

See also

Convergence Criteria, XSLP_ATOL_R

XSLP_ATOL_R
Description

Relative delta convergence tolerance

Type

DoubleNote

The relative delta convergence criterion assesses the change in value of a variable (δX)
relative to the value of the variable (X), against the relative delta convergence tolerance. If
δX < X ∗ XSLP_ATOL_R
then the variable has converged on the relative delta convergence criterion. When the value isset to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-3 and
1e-6.

Default value-1.0

See also

Convergence Criteria, XSLP_ATOL_AXSLP_BARSTALLINGTOL
Description

Required change in the objective when progress is measured in barrier iterations withoutcrossoverType

Double

Note

Minumum objective variability change required in relation to control
XSLP_BARSTALLINGOBJLIMIT for the iterations to be regarded as making progress. The
net objective, error cost and error sum are taken into account.

Default value

0.05

Fair Isaac Corporation Conﬁdential and Proprietary Information

130

Control Parameters

Reference

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARCROSSOVERSTART, XSLP_BARLIMIT, XSLP_BARSTARTOPS,XSLP_BARSTALLINGLIMIT, XSLP_BARSTALLINGOBJLIMITXSLP_CASCADETOL_PA
Description

Absolute cascading print tolerance

Type

DoubleNote

The change to the value of a variable as a result of cascading is only printed if the change isdeemed signiﬁcant. The change is tested against: absolute and relative convergence
tolerance and absolute and relative cascading print tolerance. The change is printed only if all
tests fail. The absolute cascading print criterion measures the change in value of a variable(δX) against the absolute cascading print tolerance. If
δX < XSLP_CASCADETOL_PA
then the change is within the absolute cascading print tolerance and will not be printed.
XSLP_LOG must be at least 5 for this control to have an effect.

Default value

0.01

See also

Cascading, XSLP_CASCADETOL_PR

Affects routinesXSLPcascadeXSLP_CASCADETOL_PR
Description

Relative cascading print tolerance

Type

DoubleNote

The change to the value of a variable as a result of cascading is only printed if the change isdeemed signiﬁcant. The change is tested against: absolute and relative convergence
tolerance and absolute and relative cascading print tolerance. The change is printed only if all
tests fail. The relative cascading print criterion measures the change in value of a variable(δX) relative to the value of the variable (X), against the relative cascading print tolerance. If
δX < X ∗ XSLP_CASCADETOL_PR
then the change is within the relative cascading print tolerance and will not be printed.
XSLP_LOG must be at least 5 for this control to have an effect.

Default value

0.01

See also

Cascading, XSLP_CASCADETOL_PA

Affects routinesXSLPcascadeXSLP_CDTOL_A
Description

Absolute tolerance for deducing constant derivatives

Fair Isaac Corporation Conﬁdential and Proprietary Information

131

Control Parameters

Reference

Type

DoubleNote

The absolute tolerance test for constant derivatives is used as follows:
If the value of the user function at point X0 is Y0 and the values at (X0 – δX) and (X0 + δX) are
Yd and Yu respectively, then the numerical derivatives at X0 are:"down" derivative Dd = (Y0 – Yd )/δX"up" derivative Du = (Yu – Y0 )/δX
If abs(Dd – Du ) ≤ XSLP_CDTOL_A
then the derivative is regarded as constant.

Default value

1.0e-08

See also

XSLP_CDTOL_R

XSLP_CDTOL_R
Description

Relative tolerance for deducing constant derivatives

Type

DoubleNote

The relative tolerance test for constant derivatives is used as follows:
If the value of the user function at point X0 is Y0 and the values at (X0 – δX) and (X0 + δX) are
Yd and Yu respectively, then the numerical derivatives at X0 are:"down" derivative Dd = (Y0 – Yd )/δX"up" derivative Du = (Yu – Y0 )/δX
If abs(Dd – Du ) ≤ XSLP_CDTOL_R ∗ abs(Yd + Yu )/2
then the derivative is regarded as constant.

Default value

1.0e-08

See also

XSLP_CDTOL_AXSLP_CLAMPSHRINKDescription

Shrink ratio used to impose strict convergence on variables converged in extended criteria
only

Type

DoubleNote

If the solution has converged but there are variables converged on extended criteria only, the
XSLP_CLAMPSHRINK acts as a shrinking ratio on the step bounds and the problem is
optimized (if necessary multiple times), with the purpose of expediting strict convergence on
all variables. XSLP_ALGORITHM controls if this shrinking is applied at all, and if shrinking isapplied to of the variables converged on extended criteria only with active step bounds only,or if on all variables.

Default value

0.3

See also

XSLP_ALGORITHM, XSLP_CLAMPVALIDATIONTOL_A, XSLP_CLAMPVALIDATIONTOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

132

Control Parameters

ReferenceXSLP_CLAMPVALIDATIONTOL_A
Description

Absolute validation tolerance for applying XSLP_CLAMPSHRINK

Type

DoubleNote

If set and the absolute validation value is larger than this value, then control
XSLP_CLAMPSHRINK is checked once the solution has converged, but there are variables
converged on extended criteria only.

Default value

0.0 (not set)

See also

XSLP_ALGORITHM, XSLP_CLAMPSHRINK, XSLP_CLAMPVALIDATIONTOL_R

XSLP_CLAMPVALIDATIONTOL_R
Description

Relative validation tolerance for applying XSLP_CLAMPSHRINK

Type

DoubleNote

If set and the relative validation value is larger than this value, then control
XSLP_CLAMPSHRINK is checked once the solution has converged, but there are variables
converged on extended criteria only.

Default value

0.0 (not set)

See also

XSLP_ALGORITHM, XSLP_CLAMPSHRINK, XSLP_CLAMPVALIDATIONTOL_AXSLP_CTOL
Description

Closure convergence tolerance

Type

DoubleNotes

The closure convergence criterion measures the change in value of a variable (δX) relative tothe value of its initial step bound (B), against the closure convergence tolerance. If
δX < B ∗ XSLP_CTOL
then the variable has converged on the closure convergence criterion.
If no explicit initial step bound is provided, then the test will not be applied and the variable
can never converge on the closure criterion. When the value is set to be negative, the value isadjusted automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R.
Good values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

See also

Convergence Criteria, XSLP_ATOL_A, XSLP_ATOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

133

Control Parameters

ReferenceXSLP_DAMP
Description

Damping factor for updating values of variables

Type

DoubleNote

The damping factor sets the next assumed value for a variable based on the previous
assumed value (X0 ) and the actual value (X1 ). The new assumed value is given by
X1 ∗ XSLP_DAMP + X0 ∗ (1 – XSLP_DAMP)

Default value1

See also

Xpress-SLP Solution Process, XSLP_DAMPEXPAND XSLP_DAMPMAX, XSLP_DAMPMIN,XSLP_DAMPSHRINK, XSLP_DAMPSTART

Affects routinesXSLPmaxim, XSLPminimXSLP_DAMPEXPAND
Description

Multiplier to increase damping factor during dynamic damping

Type

DoubleNote

If dynamic damping is enabled, the damping factor for a variable will be increased if
successive changes are in the same direction. More precisely, if there are XSLP_SAMEDAMP
successive changes in the same direction for a variable, then the damping factor (D) for thevariable will be reset toD ∗ XSLP_DAMPEXPAND + XSLP_DAMPMAX ∗ (1 – XSLP_DAMPEXPAND)

Default value1

See also

Xpress-SLP Solution Process, XSLP_ALGORITHM, XSLP_DAMP, XSLP_DAMPMAX,XSLP_DAMPMIN, XSLP_DAMPSHRINK, XSLP_DAMPSTART, XSLP_SAMEDAMP

Affects routinesXSLPmaxim, XSLPminimXSLP_DAMPMAX
Description

Maximum value for the damping factor of a variable during dynamic damping

Type

DoubleNote

If dynamic damping is enabled, the damping factor for a variable will be increased if
successive changes are in the same direction. More precisely, if there are XSLP_SAMEDAMP
successive changes in the same direction for a variable, then the damping factor (D) for thevariable will be reset toD ∗ XSLP_DAMPEXPAND + XSLP_DAMPMAX ∗ (1 – XSLP_DAMPEXPAND)

Default value1

See also

Xpress-SLP Solution Process, XSLP_ALGORITHM, XSLP_DAMP, XSLP_DAMPEXPAND,XSLP_DAMPMIN, XSLP_DAMPSHRINK, XSLP_DAMPSTART, XSLP_SAMEDAMP

Affects routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

134

Control Parameters

ReferenceXSLP_DAMPMIN
Description

Minimum value for the damping factor of a variable during dynamic damping

Type

DoubleNote

If dynamic damping is enabled, the damping factor for a variable will be decreased if
successive changes are in the opposite direction. More precisely, the damping factor (D) for
the variable will be reset toD ∗ XSLP_DAMPSHRINK + XSLP_DAMPMIN ∗ (1 – XSLP_DAMPEXPAND)

Default value1

See also

Xpress-SLP Solution Process, XSLP_ALGORITHM, XSLP_DAMP, XSLP_DAMPEXPAND,XSLP_DAMPMAX, XSLP_DAMPSHRINK, XSLP_DAMPSTART

Affects routinesXSLPmaxim, XSLPminimXSLP_DAMPSHRINKDescription

Multiplier to decrease damping factor during dynamic damping

Type

DoubleNote

If dynamic damping is enabled, the damping factor for a variable will be decreased if
successive changes are in the opposite direction. More precisely, the damping factor (D) for
the variable will be reset toD ∗ XSLP_DAMPSHRINK + XSLP_DAMPMIN ∗ (1 – XSLP_DAMPEXPAND)

Default value1

See also

Xpress-SLP Solution Process, XSLP_ALGORITHM, XSLP_DAMP, XSLP_DAMPEXPAND,XSLP_DAMPMAX, XSLP_DAMPMIN, XSLP_DAMPSTART

Affects routinesXSLPmaxim, XSLPminimXSLP_DEFAULTIV
Description

Default initial value for an SLP variable if none is explicitly given

Type

DoubleNote

If no initial value is given for an SLP variable, then the initial value provided for the "equals
column" will be used. If no such value has been provided, then XSLP_DEFAULTIV will be
used. If this is above the upper bound for the variable, then the upper bound will be used; if it
is below the lower bound for the variable, then the lower bound will be used.

Default value

100

Affects routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

135

Control Parameters

ReferenceXSLP_DEFAULTSTEPBOUND
Description

Minimum initial value for the step bound of an SLP variable if none is explicitly given

Type

DoubleNotes

If no initial step bound value is given for an SLP variable, this will be used as a minimum
value. If the algorithm is estimating step bounds, then the step bound actually used for avariable may be larger than the default.
A default initial step bound is ignored when testing for the closure tolerance XSLP_CTOL: if
there is no speciﬁc value, then the test will not be applied.

Default value

16

See also

XSLP_CTOL

Affects routinesXSLPconstruct

XSLP_DELTA_A
Description

Absolute perturbation of values for calculating numerical derivatives

Type

DoubleNote

First-order derivatives are calculated by perturbing the value of each variable in turn by a small
amount. The amount is determined by the absolute and relative delta factors as follows:
XSLP_DELTA_A + abs(X) ∗ XSLP_DELTA_R
where (X) is the current value of the variable. If the perturbation takes the variable outside abound, then the perturbation normally made only in the opposite direction.

Default value

0.001

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTA_R

XSLP_DELTA_R
Description

Relative perturbation of values for calculating numerical derivatives

Type

DoubleNote

First-order derivatives are calculated by perturbing the value of each variable in turn by a small
amount. The amount is determined by the absolute and relative delta factors as follows:
XSLP_DELTA_A + abs(X) ∗ XSLP_DELTA_R
where (X) is the current value of the variable. If the perturbation takes the variable outside abound, then the perturbation normally made only in the opposite direction.

Default value

0.001

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTA_A

Fair Isaac Corporation Conﬁdential and Proprietary Information

136

Control Parameters

ReferenceXSLP_DELTA_X
Description

Minimum absolute value of delta coefﬁcients to be retained

Type

DoubleNotes

If the value of a coefﬁcient in a delta column is less than this value, it will be reset to zero.
Larger values of XSLP_DELTA_X will result in matrices with fewer elements, which may beeasier to solve. However, there will be increased likelihood of local optima as some of thesmall relationships between variables and constraints are deleted. There may also be
increased difﬁculties with singular bases resulting from deletion of pivot elements from thematrix.

Default value

1.0e-6Affects routinesXSLPmaxim, XSLPminimXSLP_DELTA_Z
Description

Tolerance used when calculating derivatives

Type

DoubleNotes

If the absolute value of a variable is less than this value, then a value of XSLP_DELTA_Z will
be used instead for calculating derivatives.
If a nonzero derivative is calculated for a formula which always results in a matrix coefﬁcientless than XSLP_DELTA_Z, then a larger value will be substituted so that at least one of thecoefﬁcients is XSLP_DELTA_Z in magnitude.
If XSLP_DELTAZLIMIT is set to a positive number, then when that number of iterations havepassed, values smaller than XSLP_DELTA_Z will be set to zero.

Default value

0.00001

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTAZLIMIT, XSLP_DELTA_ZEROXSLP_DELTA_ZERO
Description

Absolute zero acceptance tolerance used when calculating derivatives

Type

Double

Notes

Provides an override value for the XSLP_DELTA_Z behavior. Derivatives smaller thanXSLP_DELTA_ZERO will not be substituted by XSLP_DELTA_Z, deﬁning a range in which
derivatives are deemed nonzero and are affected by XSLP_DELTA_Z.
A negative value means that this tolerance will not be applied.

Default value-1.0 (not applied)

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTAZLIMIT, XSLP_DELTA_Z

Fair Isaac Corporation Conﬁdential and Proprietary Information

137

Control Parameters

ReferenceXSLP_DELTACOST
Description

Initial penalty cost multiplier for penalty delta vectors

Type

DoubleNote

If penalty delta vectors are used, this parameter sets the initial cost factor. If there are active
penalty delta vectors, then the penalty cost may be increased.

Default value

200

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOSTFACTOR, XSLP_DELTAMAXCOST,XSLP_ERRORCOSTXSLP_DELTACOSTFACTOR
Description

Factor for increasing cost multiplier on total penalty delta vectors

Type

DoubleNote

If there are active penalty delta vectors, then the penalty cost multiplier will be increased by afactor of XSLP_DELTACOSTFACTOR up to a maximum of XSLP_DELTAMAXCOSTDefault value

1.3

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOST, XSLP_DELTAMAXCOST, XSLP_ERRORCOSTXSLP_DELTAMAXCOST
Description

Maximum penalty cost multiplier for penalty delta vectors

Type

DoubleNote

If there are active penalty delta vectors, then the penalty cost multiplier will be increased by afactor of XSLP_DELTACOSTFACTOR up to a maximum of XSLP_DELTAMAXCOSTDefault value

inﬁniteAffects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOST, XSLP_DELTACOSTFACTOR, XSLP_ERRORCOST

Fair Isaac Corporation Conﬁdential and Proprietary Information

138

Control Parameters

ReferenceXSLP_DJTOL
Description

Tolerance on DJ value for determining if a variable is at its step boundType

DoubleNote

If a variable is at its step bound and within the absolute delta tolerance XSLP_ATOL_A or
closure tolerance XSLP_CTOL then the step bounds will not be further reduced. If the DJ isgreater in magnitude than XSLP_DJTOL then the step bound may be relaxed if it meets thenecessary criteria.

Default value

1.0e-6Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ATOL_A, XSLP_CTOLXSLP_DRCOLTOL
Description

The minimum absolute magnitude of a determining column, for which the determinedvariable is still regarded as well deﬁned

TypeDouble

Notes

This control affects the cascading procedure. Please see Chapter Cascading for more
information.

Default value0

See also

XSLP_CASCADE

Affects routinesXSLPconstruct XSLPcascadeXSLP_ECFTOL_A
Description

Absolute tolerance on testing feasibility at the point of linearization

Type

Double

Notes

The extended convergence criteria test how well the linearization approximates the true
problem. They depend on the point of linearization being a reasonable approximation — inparticular, that it should be reasonably close to feasibility. Each constraint is tested at the
point of linearization, and the total positive and negative contributions to the constraint fromthe columns in the problem are calculated. A feasibility tolerance is calculated as the largest
of XSLPE CFTOLA andmax(abs(Positive), abs(Negative)) ∗ XSLP_ECFTOL_R
If the calculated infeasibility is greater than the tolerance, the point of linearization isregarded as infeasible and the extended convergence criteria will not be applied. When thevalue is set to be negative, the value is adjusted automatically by SLP, based on the feasibility
target XSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between
1e-1 and 1e-6.

Fair Isaac Corporation Conﬁdential and Proprietary Information

139

Control Parameters

Reference

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

Convergence criteria, XSLP_ECFCHECK, XSLP_ECFCOUNT, XSLP_ECFTOL_R

XSLP_ECFTOL_R
Description

Relative tolerance on testing feasibility at the point of linearization

Type

Double

Notes

The extended convergence criteria test how well the linearization approximates the true
problem. They depend on the point of linearization being a reasonable approximation — inparticular, that it should be reasonably close to feasibility. Each constraint is tested at the
point of linearization, and the total positive and negative contributions to the constraint fromthe columns in the problem are calculated. A feasibility tolerance is calculated as the largest
of XSLPE CFTOLA andmax(abs(Positive), abs(Negative)) ∗ XSLP_ECFTOL_R
If the calculated infeasibility is greater than the tolerance, the point of linearization isregarded as infeasible and the extended convergence criteria will not be applied. When thevalue is set to be negative, the value is adjusted automatically by SLP, based on the feasibility
target XSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between
1e-1 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

Convergence criteria, XSLP_ECFCHECK, XSLP_ECFCOUNT, XSLP_ECFTOL_AXSLP_ENFORCECOSTSHRINKDescription

Factor by which to decrease the current penalty multiplier when enforcing rows.

Type

DoubleNotes

When feasiblity of a row cannot be achieved by increasing the penalty cost on its error
variable, removing the variable (ﬁxing it to zero) can force the row to be satisﬁed, as set by
XSLP_ENFORCEMAXCOST. After the error variables have been removed (which is equivalent tosetting to row to be enforced) the penalties on the remaining error variables are rebalanced toallow for a reduction in the size of the penalties in the objective in order to achive better
numerical behaviour.

Default value

0.00001

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ENFORCEMAXCOSTFair Isaac Corporation Conﬁdential and Proprietary Information

140

Control Parameters

ReferenceXSLP_ENFORCEMAXCOST
Description

Maximum penalty cost in the objective before enforcing most violating rows

Type

DoubleNotes

When feasiblity of a row cannot be achieved by increasing the penalty cost on its error
variable, removing the variable (ﬁxing it to zero) can force the row to be satisﬁed. After theerror variables have been removed (which is equivalent to setting to row to be enforced) the
penalties on the remaining error variables are rebalanced to allow for a reduction in the sizeof the penalties in the objective in order to achive better numerical behaviour, controlled by
XSLP_ENFORCECOSTSHRINK.

Default value

10000000000

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ENFORCECOSTSHRINKXSLP_ERRORCOST
Description

Initial penalty cost multiplier for penalty error vectors

Type

DoubleNote

If penalty error vectors are used, this parameter sets the initial cost factor. If there are active
penalty error vectors, then the penalty cost may be increased.

Default value

200

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOST, XSLP_ERRORCOSTFACTOR,XSLP_ERRORMAXCOSTXSLP_ERRORCOSTFACTOR
Description

Factor for increasing cost multiplier on total penalty error vectors

Type

DoubleNote

If there are active penalty error vectors, then the penalty cost multiplier will be increased by afactor of XSLP_ERRORCOSTFACTOR up to a maximum of XSLP_ERRORMAXCOSTDefault value

1.3

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_ERRORMAXCOSTFair Isaac Corporation Conﬁdential and Proprietary Information

141

Control Parameters

ReferenceXSLP_ERRORMAXCOST
Description

Maximum penalty cost multiplier for penalty error vectors

Type

DoubleNote

If there are active penalty error vectors, then the penalty cost multiplier will be increased by afactor of XSLP_ERRORCOSTFACTOR up to a maximum of XSLP_ERRORMAXCOSTDefault value

inﬁniteAffects routinesXSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_ERRORCOSTFACTORXSLP_ERRORTOL_A
Description

Absolute tolerance for error vectors

Type

DoubleNote

The solution will be regarded as having no active error vectors if one of the following applies:
every penalty error vector and penalty delta vector has an activity less thanXSLP_ERRORTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_R ∗ Obj where Obj is the current objective function value.

Default value

0.00001

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_EVTOL_A, XSLP_EVTOL_R

XSLP_ERRORTOL_P
Description

Absolute tolerance for printing error vectors

Type

DoubleNote

The solution log includes a print of penalty delta and penalty error vectors with an activity
greater than XSLP_ERRORTOL_P.

Default value

0.0001Affects routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

142

Control Parameters

ReferenceXSLP_ESCALATION
Description

Factor for increasing cost multiplier on individual penalty error vectors

Type

DoubleNote

If penalty cost escalation is activated in XSLP_ALGORITHM then the penalty cost multiplier
will be increased by a factor of XSLP_ESCALATION for any active error vector up to a
maximum of XSLP_MAXWEIGHT.

Default value

1.25

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ALGORITHM, XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_MAXWEIGHTXSLP_ETOL_A
Description

Absolute tolerance on penalty vectors

Type

DoubleNote

For each penalty error vector, the contribution to its constraint is calculated, together with thetotal positive and negative contributions to the constraint from other vectors. If its
contribution is less than XSLP_ETOL_A or less than Positive ∗ XSLP_ETOL_R or less thanabs(Negative) ∗ XSLP_ETOL_R then it will be regarded as insigniﬁcant and will not have its
penalty increased. When the value is set to be negative, the value is adjusted automatically by
SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good values for thecontrol are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ETOL_R XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_ESCALATIONXSLP_ETOL_R
Description

Relative tolerance on penalty vectors

Type

DoubleNote

For each penalty error vector, the contribution to its constraint is calculated, together with thetotal positive and negative contributions to the constraint from other vectors. If its
contribution is less than XSLP_ETOL_A or less than Positive ∗ XSLP_ETOL_R or less thanabs(Negative) ∗ XSLP_ETOL_R then it will be regarded as insigniﬁcant and will not have its
penalty increased. When the value is set to be negative, the value is adjusted automatically by
SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good values for thecontrol are usually fall between 1e-3 and 1e-6.

Default value-1.0

Fair Isaac Corporation Conﬁdential and Proprietary Information

143

Control Parameters

Reference

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ETOL_A XSLP_DELTACOST, XSLP_ERRORCOST, XSLP_ESCALATIONXSLP_EVTOL_A
Description

Absolute tolerance on total penalty costs

Type

DoubleNote

The solution will be regarded as having no active error vectors if one of the following applies:
every penalty error vector and penalty delta vector has an activity less thanXSLP_ERRORTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_R ∗ Obj where Obj is the current objective function value. When the value isset to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-2 and
1e-6, but normally a magnitude larger than XSLP_ETOL_A.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ERRORTOL_A, XSLP_EVTOL_R

XSLP_EVTOL_R
Description

Relative tolerance on total penalty costs

Type

DoubleNote

The solution will be regarded as having no active error vectors if one of the following applies:
every penalty error vector and penalty delta vector has an activity less thanXSLP_ERRORTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_A;
the sum of the cost contributions from all the penalty error and penalty delta vectors is lessthan XSLP_EVTOL_R ∗ Obj where Obj is the current objective function value. When the value isset to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-2 and
1e-6, but normally a magnitude larger than XSLP_ETOL_R.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ERRORTOL_A, XSLP_EVTOL_A

Fair Isaac Corporation Conﬁdential and Proprietary Information

144

Control Parameters

ReferenceXSLP_EXPAND
Description

Multiplier to increase a step boundType

DoubleNote

If step bounding is enabled, the step bound for a variable will be increased if successivechanges are in the same direction. More precisely, if there are XSLP_SAMECOUNT successivechanges reaching the step bound and in the same direction for a variable, then the stepbound (B) for the variable will be reset to
B ∗ XSLP_EXPAND.

Default value

2

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SHRINK, XSLP_SHRINKBIAS, XSLP_SAMECOUNTXSLP_FEASTOLTARGET
Description

When set, this deﬁnes a target feasibility tolerance to which the linearizations are solved toType

DoubleNote

This is a soft version of XPRS_FEASTOL, and will dynamically revert back to XPRS_FEASTOL
if the desired accuracy could not be achieved.

Default value

0 (ignored, not set)

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_OPTIMALITYTOLTARGET,XSLP_GRANULARITY
Description

Base for calculating penalty costs

Type

DoubleNote

If XSLP_GRANULARITY >1, then initial penalty costs will be powers of XSLP_GRANULARITY.

Default value

4

Affects routinesXSLPconstruct

See also

XSLP_MAXWEIGHT, XSLP_MINWEIGHT

Fair Isaac Corporation Conﬁdential and Proprietary Information

145

Control Parameters

ReferenceXSLP_INFINITY
Description

Value returned by a divide-by-zero in a formulaType

DoubleDefault value

1.0e+10XSLP_ITOL_A
Description

Absolute impact convergence tolerance

Type

DoubleNote

The absolute impact convergence criterion assesses the change in the effect of a coefﬁcientin a constraint. The effect of a coefﬁcient is its value multiplied by the activity of the column
in which it appears.
E =X∗C
where X is the activity of the matrix column in which the coefﬁcient appears, and C is thevalue of the coefﬁcient. The linearization approximates the effect of the coefﬁcient as
E1 = X ∗ C0 + δX ∗ C00
where X is as before, C0 is the value of the coefﬁcient C calculated using the assumed values∂C calculated using the assumed values for thefor the variables and C00 is the value of ∂X
variables.
If C1 is the value of the coefﬁcient C calculated using the actual values for the variables, thenthe error in the effect of the coefﬁcient is given by
δE = X ∗ C1 – (X ∗ C0 + δX ∗ C00 )If δE < XSLP_ITOL_A
then the variable has passed the absolute impact convergence criterion for this coefﬁcient.
If a variable which has not converged on strict (closure or delta) criteria passes the (relative
or absolute) impact or matrix criteria for all the coefﬁcients in which it appears, then it isdeemed to have converged. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good
values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_R, XSLP_MTOL_A, XSLP_MTOL_R, XSLP_STOL_A, XSLP_STOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

146

Control Parameters

ReferenceXSLP_ITOL_R
Description

Relative impact convergence tolerance

Type

DoubleNote

The relative impact convergence criterion assesses the change in the effect of a coefﬁcient in
a constraint in relation to the magnitude of the constituents of the constraint. The effect of a
coefﬁcient is its value multiplied by the activity of the column in which it appears.
E =X∗C
where X is the activity of the matrix column in which the coefﬁcient appears, and C is thevalue of the coefﬁcient. The linearization approximates the effect of the coefﬁcient as
E1 = X ∗ C0 + δX ∗ C00
where X is as before, C0 is the value of the coefﬁcient C calculated using the assumed values∂C calculated using the assumed values for thefor the variables and C00 is the value of ∂X
variables.
If C1 is the value of the coefﬁcient C calculated using the actual values for the variables, thenthe error in the effect of the coefﬁcient is given by
δE = X ∗ C1 – (X ∗ C0 + δX ∗ C00 )All the elements of the constraint are examined, excluding delta and error vectors: for each,the contribution to the constraint is evaluated as the element multiplied by the activity of thevector in which it appears; it is then included in a total positive contribution or total negative
contribution depending on the sign of the contribution. If the predicted effect of thecoefﬁcient is positive, it is tested against the total positive contribution; if the effect of thecoefﬁcient is negative, it is tested against the total negative contribution. If T0 is the total
positive or total negative contribution to the constraint (as appropriate)and δE < T0 ∗ XSLP_ITOL_R
then the variable has passed the relative impact convergence criterion for this coefﬁcient.
If a variable which has not converged on strict (closure or delta) criteria passes the (relative
or absolute) impact or matrix criteria for all the coefﬁcients in which it appears, then it isdeemed to have converged. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good
values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_A, XSLP_MTOL_A, XSLP_MTOL_R, XSLP_STOL_A, XSLP_STOL_R

XSLP_MATRIXTOL
Description

Provides an override value for XPRS_MATRIXTOL, which controls the smallest magnitude ofmatrix coefﬁcentsType

DoubleFair Isaac Corporation Conﬁdential and Proprietary Information

147

Control Parameters

ReferenceNote

Any value smaller than XSLP_MATRIXTOL in magnitude will not be loaded into thelinearization. This only applies to the matrix coefﬁcients; bounds, right hand sides andobjectives are not affected.

Default value

1e-30

Affects routinesXSLPconstruct, XSLPmaxim, XSLPminimXSLP_MAXWEIGHT
Description

Maximum penalty weight for delta or error vectors

Type

DoubleNote

When penalty vectors are created, or when their weight is increased by escalation, themaximum weight that will be used is given by XSLP_MAXWEIGHT.

Default value

100

Affects routinesXSLPconstruct, XSLPmaxim, XSLPminim

See also

XSLP_ALGORITHM, XSLP_AUGMENTATION, XSLP_ESCALATION, XSLP_MINWEIGHTXSLP_MEMORYFACTOR
Description

Factor for expanding size of dynamic arrays in memory

Type

DoubleNote

When a dynamic array has to be increased in size, the new space allocated will be
XSLP_MEMORYFACTOR times as big as the previous size. A larger value may result in
improved performance because arrays need to be re-sized and moved less frequently;
however, more memory may be required under such circumstances because not all of theprevious memory area can be re-used efﬁciently.

Default value

1.6

See also

Memory control variables XSLP_MEM⁎ Memory control variables XSLP_MEM⁎

XSLP_MERITLAMBDA
Description

Factor by which the net objective is taken into account in the merit function

Type

DoubleNote

The merit function is evaluated in the original, non-augmented / linearized space of the
problem. A solution is deemed improved, if either feasibility improved, or if feasibility is notdeteriorated but the net objective is improved, or if the combination of the two is improved,
where the value of the XSLP_MERITLAMBDA control is used to combine the two measures. A
nonpositive value indicates that the combined effect should not be checked.

Fair Isaac Corporation Conﬁdential and Proprietary Information

148

Control Parameters

Reference

Default value

0.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_FILTER XSLP_LSITERLIMIT XSLP_LSPATTERNLIMITXSLP_MINSBFACTOR
Description

Factor by which step bounds can be decreased beneath XSLP_ATOL_A

Type

DoubleNote

Normally, step bounds are not decreased beneath XSLP_ATOL_A, as such variables aretreated as converged. However, it may be beneﬁcial to decrease step bounds further, as
individual variable value changes might affect the convergence of other variables in themodel, even if the variablke itself is deemed converged.

Default value

1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ATOL_AXSLP_MINWEIGHT
Description

Minimum penalty weight for delta or error vectors

Type

DoubleNote

When penalty vectors are created, the minimum weight that will be used is given by
XSLP_MINWEIGHT.

Default value

0.01

Affects routinesXSLPconstruct, XSLPmaxim, XSLPminim

See also

XSLP_AUGMENTATION, XSLP_MAXWEIGHTXSLP_MIPCUTOFF_A
Description

Absolute objective function cutoff for MIP termination

Type

DoubleNote

If the objective function is worse by a deﬁned amount than the best integer solution obtainedso far, then the SLP will be terminated (and the node will be cut off). The node will be cut off
at the current SLP iteration if the objective function for the last XSLP_MIPCUTOFFCOUNT SLP
iterations are all worse than the best obtained so far, and the difference is greater thanXSLP_MIPCUTOFF_A and OBJ ∗ XSLP_MIPCUTOFF_R where OBJ is the best integer solution
obtained so far.
The MIP cutoff tests are only applied after XSLP_MIPCUTOFFLIMIT SLP iterations at thecurrent node.

Fair Isaac Corporation Conﬁdential and Proprietary Information

149

Control Parameters

Reference

Default value

0.0001Affects routinesXSLPglobal

See also

XSLP_MIPCUTOFFCOUNT, XSLP_MIPCUTOFFLIMIT, XSLP_MIPCUTOFF_R

XSLP_MIPCUTOFF_R
Description

Absolute objective function cutoff for MIP termination

Type

DoubleNote

If the objective function is worse by a deﬁned amount than the best integer solution obtainedso far, then the SLP will be terminated (and the node will be cut off). The node will be cut off
at the current SLP iteration if the objective function for the last XSLP_MIPCUTOFFCOUNT SLP
iterations are all worse than the best obtained so far, and the difference is greater thanXSLP_MIPCUTOFF_A and OBJ ∗ XSLP_MIPCUTOFF_R where OBJ is the best integer solution
obtained so far.
The MIP cutoff tests are only applied after XSLP_MIPCUTOFFLIMIT SLP iterations at thecurrent node.

Default value

0.0001Affects routinesXSLPglobal

See also

XSLP_MIPCUTOFFCOUNT, XSLP_MIPCUTOFFLIMIT, XSLP_MIPCUTOFF_AXSLP_MIPERRORTOL_A
Description

Absolute penalty error cost tolerance for MIP cut-off

TypeDoubleNote

The penalty error cost test is applied at each node where there are active penalties in thesolution. If XSLP_MIPERRORTOL_A is nonzero and the absolute value of the penalty costs isgreater than XSLP_MIPERRORTOL_A, the node will be declared infeasible. If
XSLP_MIPERRORTOL_A is zero then no test is made and the node will not be declaredinfeasible on this criterion.

Default value

0 (inactive)

Affects routinesXSLPglobal

See also

XSLP_MIPERRORTOL_R

XSLP_MIPERRORTOL_R
Description

Relative penalty error cost tolerance for MIP cut-off

TypeDoubleFair Isaac Corporation Conﬁdential and Proprietary Information

150

Control Parameters

Reference

Note

The penalty error cost test is applied at each node where there are active penalties in thesolution. If XSLP_MIPERRORTOL_R is nonzero and the absolute value of the penalty costs isgreater than XSLP_MIPERRORTOL_R ∗ abs(Obj) where Obj is the value of the objectivefunction, then the node will be declared infeasible. If XSLP_MIPERRORTOL_R is zero then no
test is made and the node will not be declared infeasible on this criterion.

Default value

0 (inactive)

Affects routinesXSLPglobal

See also

XSLP_MIPERRORTOL_AXSLP_MIPOTOL_A
Description

Absolute objective function tolerance for MIP termination

Type

DoubleNote

The objective function test for MIP termination is applied only when step bounding has been
applied (or XSLP_SBSTART SLP iterations have taken place if step bounding is not beingused). The node will be terminated at the current SLP iteration if the range of the objectivefunction values over the last XSLP_MIPOCOUNT SLP iterations is within XSLP_MIPOTOL_A or
within OBJ ∗ XSLP_MIPOTOL_R where OBJ is the average value of the objective function overthose iterations.

Default value

0.00001

Affects routinesXSLPglobal

See also

XSLP_MIPOCOUNT XSLP_MIPOTOL_R XSLP_SBSTARTXSLP_MIPOTOL_R
Description

Relative objective function tolerance for MIP termination

Type

DoubleNote

The objective function test for MIP termination is applied only when step bounding has been
applied (or XSLP_SBSTART SLP iterations have taken place if step bounding is not beingused). The node will be terminated at the current SLP iteration if the range of the objectivefunction values over the last XSLP_MIPOCOUNT SLP iterations is within XSLP_MIPOTOL_A or
within OBJ ∗ XSLP_MIPOTOL_R where OBJ is the average value of the objective function overthose iterations.

Default value

0.00001

Affects routinesXSLPglobal

See also

XSLP_MIPOCOUNT XSLP_MIPOTOL_A XSLP_SBSTART

Fair Isaac Corporation Conﬁdential and Proprietary Information

151

Control Parameters

ReferenceXSLP_MSMAXBOUNDRANGE
Description

Deﬁnes the maximum range inside which initial points are generated by multistart presets

Type

DoubleNote

The is the maximum range in which initial points are generated; the actual range is expected
to be smaller as bounds are domains are also considered.

Default value

1000

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTARTXSLP_MTOL_A
Description

Absolute effective matrix element convergence tolerance

Type

DoubleNote

The absolute effective matrix element convergence criterion assesses the change in theeffect of a coefﬁcient in a constraint. The effect of a coefﬁcient is its value multiplied by theactivity of the column in which it appears.
E =X∗C
where X is the activity of the matrix column in which the coefﬁcient appears, and C is thevalue of the coefﬁcient. The linearization approximates the effect of the coefﬁcient as
E = X ∗ C0 + δX ∗ C00
where V is as before, C0 is the value of the coefﬁcient C calculated using the assumed values∂C calculated using the assumed values for thefor the variables and C00 is the value of ∂X
variables.
If C1 is the value of the coefﬁcient C calculated using the actual values for the variables, thenthe error in the effect of the coefﬁcient is given by
δE = X ∗ C1 – (X ∗ C0 + δX ∗ C00 )If δE < X ∗ XSLP_MTOL_A
then the variable has passed the absolute effective matrix element convergence criterion forthis coefﬁcient.
If a variable which has not converged on strict (closure or delta) criteria passes the (relative
or absolute) impact or matrix criteria for all the coefﬁcients in which it appears, then it isdeemed to have converged. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good
values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_A, XSLP_ITOL_R, XSLP_MTOL_R, XSLP_STOL_A, XSLP_STOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

152

Control Parameters

ReferenceXSLP_MTOL_R
Description

Relative effective matrix element convergence tolerance

Type

DoubleNote

The relative effective matrix element convergence criterion assesses the change in the effectof a coefﬁcient in a constraint relative to the magnitude of the coefﬁcient. The effect of a
coefﬁcient is its value multiplied by the activity of the column in which it appears.
E =X∗C
where X is the activity of the matrix column in which the coefﬁcient appears, and C is thevalue of the coefﬁcient. The linearization approximates the effect of the coefﬁcient as
E1 = X ∗ C0 + δX ∗ C00
where V is as before, C0 is the value of the coefﬁcient C calculated using the assumed values∂C calculated using the assumed values for thefor the variables and C00 is the value of ∂X
variables.
If C1 is the value of the coefﬁcient C calculated using the actual values for the variables, thenthe error in the effect of the coefﬁcient is given by
δE = X ∗ C1 – (X ∗ C0 + δX ∗ C00 )If δE < E1 ∗ XSLP_MTOL_R
then the variable has passed the relative effective matrix element convergence criterion forthis coefﬁcient.
If a variable which has not converged on strict (closure or delta) criteria passes the (relative
or absolute) impact or matrix criteria for all the coefﬁcients in which it appears, then it isdeemed to have converged. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good
values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_A, XSLP_ITOL_R, XSLP_MTOL_A, XSLP_STOL_A, XSLP_STOL_R

XSLP_MVTOL
Description

Marginal value tolerance for determining if a constraint is slack

Type

DoubleNote

If the absolute value of the marginal value of a constraint is less than XSLP_MVTOL, then
(1) the constraint is regarded as not constraining for the purposes of the slack tolerance
convergence criteria;(2) the constraint is not regarded as an active constraint when identifying unconverged
variables in active constraints. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the feasibility target XSLP_VALIDATIONTARGET_R. Good
values for the control are usually fall between 1e-3 and 1e-6.

Fair Isaac Corporation Conﬁdential and Proprietary Information

153

Control Parameters

Reference

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_STOL_A, XSLP_STOL_R

XSLP_OBJSENSE
Description

Objective function sense

Type

DoubleNote

XSLP_OBJSENSE is set to +1 for minimization and to -1 for maximization. It is automaticallyset by XSLPmaxim and XSLPminim; it must be set by the user before calling
XSLPnlpoptimize.

Set by routinesXSLPmaxim, XSLPminim

Default value+1

Affects routinesXSLPmaxim, XSLPminim, XSLPnlpoptimize

XSLP_OBJTOPENALTYCOST
Description

Factor to estimate initial penalty costs from objective function

Type

DoubleNotes

The setting of initial penalty error costs can affect the path of the optimization and, indeed,
whether a solution is achieved at all. If the penalty costs are too low, then unbounded
solutions may result although Xpress-SLP will increase the costs in an attempt to recover. If
the penalty costs are too high, then the requirement to achieve feasibility of the linearized
constraints may be too strong to allow the system to explore the nonlinear feasible region.
Low penalty costs can result in many SLP iterations, as feasibility of the nonlinear constraints
is not achieved until the penalty costs become high enough; high penalty costs force
feasibility of the linearizations, and so tend to ﬁnd local optima close to an initial feasible
point. Xpress-SLP can analyze the problem to estimate the size of penalty costs required to
avoid an initial unbounded solution. XSLP_OBJTOPENALTYCOST can be used in conjunction
with this procedure to scale the costs and give an appropriate initial value for balancing therequirements of feasibility and optimality.
Not all models are amenable to the Xpress-SLP analysis. As the analysis is initially concernedwith establishing a cost level to avoid unboundedness, a model which is sufﬁciently
constrained will never show unboundedness regardless of the cost. Also, as the analysis isdone at the start of the optimization to establish a penalty cost, signiﬁcant changes in the
coefﬁcients, or a high degree of nonlinearity, may invalidate the initial analysis.
A setting for XSLP_OBJTOPENALTYCOST of zero disables the analysis. A setting of 3 or 4 has
proved successful for many models. If XSLP_OBJTOPENALTYCOST cannot be used becauseof the problem structure, its effect can still be emulated by some initial experiments toestablish the cost required to avoid unboundedness, and then manually applying a suitablefactor. If the problem is initially unbounded, then the penalty cost will be increased until either
it reaches its maximum or the problem becomes bounded.

Default value0

Affects routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

154

Control Parameters

ReferenceXSLP_OPTIMALITYTOLTARGET
Description

When set, this deﬁnes a target optimality tolerance to which the linearizations are solved toType

DoubleNote

This is a soft version of XPRS_OPTIMALITYTOL, and will dynamically revert back to
XPRS_OPTIMALITYTOL if the desired accuracy could not be achieved.

Default value

0 (ignored, not set)

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_FEASTOLTARGET,XSLP_OTOL_A
Description

Absolute static objective (2) convergence tolerance

Type

DoubleNote

The static objective (2) convergence criterion does not measure convergence of individual
variables. Instead, it measures the signiﬁcance of the changes in the objective function overrecent SLP iterations. It is applied when all the variables interacting with active constraints(those that have a marginal value of at least XSLP_MVTOL) have converged. The rationale isthat if the remaining unconverged variables are not involved in active constraints and if theobjective function is not changing signiﬁcantly between iterations, then the solution is
more-or-less practical.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_OCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_OTOL_A
then the problem has converged on the absolute static objective (2) convergence criterion.
The static objective function (2) test is applied only if XSLP_OCOUNT is at least 2. When thevalue is set to be negative, the value is adjusted automatically by SLP, based on the optimality
target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall between
1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_OCOUNT, XSLP_OTOL_R

XSLP_OTOL_R
Description

Relative static objective (2) convergence tolerance

Fair Isaac Corporation Conﬁdential and Proprietary Information

155

Control Parameters

Reference

Type

DoubleNote

The static objective (2) convergence criterion does not measure convergence of individual
variables. Instead, it measures the signiﬁcance of the changes in the objective function overrecent SLP iterations. It is applied when all the variables interacting with active constraints(those that have a marginal value of at least XSLP_MVTOL) have converged. The rationale isthat if the remaining unconverged variables are not involved in active constraints and if theobjective function is not changing signiﬁcantly between iterations, then the solution is
more-or-less practical.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_OCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_OTOL_R
then the problem has converged on the relative static objective (2) convergence criterion.
The static objective function (2) test is applied only if XSLP_OCOUNT is at least 2. When thevalue is set to be negative, the value is adjusted automatically by SLP, based on the optimality
target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall between
1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_OCOUNT, XSLP_OTOL_AXSLP_PRESOLVEZERO
Description

Minimum absolute value for a variable which is identiﬁed as nonzero during SLP presolve

Type

DoubleNote

During the SLP (nonlinear)presolve, a variable may be identiﬁed as being nonzero (forexample, because it is used as a divisor). A bound of plus or minus XSLP_PRESOLVEZERO
will be applied to the variable if it is identiﬁed as non-negative or non-positive.

Default value

1.0E-09

Affects routinesXSLPpresolve

XSLP_PRIMALINTEGRALREF
Description

Reference solution value to take into account when calculating the primal integral

Type

DoubleNote

When a global optimum is known, this can used to calculate a globally valid primal integral. It
can also be used to indicate the target objective value still to be taken into account in the
integral.

Default value

XPRS_PLUSINFINITY

Affects routinesXSLPminim, XSLPmaxim

Fair Isaac Corporation Conﬁdential and Proprietary Information

156

Control Parameters

ReferenceXSLP_SHRINKDescription

Multiplier to reduce a step boundType

DoubleNote

If step bounding is enabled, the step bound for a variable will be decreased if successivechanges are in opposite directions. The step bound (B) for the variable will be reset to
B ∗ XSLP_SHRINK.
If the step bound is already below the strict (delta or closure) tolerances, it will not be reduced
further.

Default value

0.5

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_EXPAND, XSLP_SHRINKBIAS, XSLP_SAMECOUNTXSLP_SHRINKBIAS
Description

Deﬁnes an overwrite / adjustment of step bounds for improving iterations

Type

DoubleNote

Positive values overwrite XSLP_SHRINK only if the objective is improving. A negative value isused to scale all step bounds in improving iterations.

Default value

0 (ignored, not set)

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_SHRINK, XSLP_EXPAND, XSLP_SAMECOUNTXSLP_STOL_A
Description

Absolute slack convergence tolerance

Type

DoubleNote

The slack convergence criterion is identical to the impact convergence criterion, except thatthe tolerances used are XSLP_STOL_A (instead of XSLP_ITOL_A) and XSLP_STOL_R(instead of XSLP_ITOL_R). See XSLP_ITOL_A for a description of the test. When the value
is set to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-3 and
1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_A, XSLP_ITOL_R, XSLP_MTOL_A, XSLP_MTOL_R, XSLP_STOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

157

Control Parameters

ReferenceXSLP_STOL_R
Description

Relative slack convergence tolerance

Type

DoubleNote

The slack convergence criterion is identical to the impact convergence criterion, except thatthe tolerances used are XSLP_STOL_A (instead of XSLP_ITOL_A) and XSLP_STOL_R(instead of XSLP_ITOL_R). See XSLP_ITOL_R for a description of the test. When the value
is set to be negative, the value is adjusted automatically by SLP, based on the feasibility targetXSLP_VALIDATIONTARGET_R. Good values for the control are usually fall between 1e-3 and
1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ITOL_A, XSLP_ITOL_R, XSLP_MTOL_A, XSLP_MTOL_R, XSLP_STOL_AXSLP_VALIDATIONTARGET_R
Description

Feasiblity target tolerance

Type

DoubleNote

Primary feasiblity control for SLP. When the relevant feasibility based convergence controls
are left at their default values, SLP will adjust their value to match the target. The control
deﬁnes a target value, that may not necessarily be attainable.

Default value

1e-6

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_VALIDATIONTARGET_K

XSLP_VALIDATIONTARGET_K
Description

Optimality target tolerance

Type

DoubleNote

Primary optimality control for SLP. When the relevant optimality based convergence controls
are left at their default values, SLP will adjust their value to match the target. The control
deﬁnes a target value, that may not necessarily be attainable for problem with no strong
constraint qualiﬁcations.

Default value

1e-6

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_VALIDATIONTARGET_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

158

Control Parameters

ReferenceXSLP_VALIDATIONTOL_A
Description

Absolute tolerance for the XSLPvalidate procedure

Type

DoubleNote

XSLPvalidate checks the feasibility of a converged solution against relative and absolute
tolerances for each constraint. The left hand side and the right hand side of the constraint arecalculated using the converged solution values. If the calculated values imply that theconstraint is infeasible, then the difference (D) is tested against the absolute and relative
validation tolerances.
If D < XSLP_VALIDATIONTOL_A
then the constraint is within the absolute validation tolerance. The total positive (TPos) andnegative contributions (TNeg) to the left hand side are also calculated.
If D < MAX(ABS(TPos), ABS(TNeg)) ∗ XSLP_VALIDATIONTOL_A
then the constraint is within the relative validation tolerance. For each constraint which isoutside both the absolute and relative validation tolerances, validation factors are calculated
which are the factors by which the infeasibility exceeds the corresponding validation
tolerance; the smaller factor is printed in the validation report.
The validation index XSLP_VALIDATIONINDEX_A is the largest of these factors which is anabsolute validation factor multiplied by the absolute validation tolerance; the validation index
XSLP_VALIDATIONINDEX_R is the largest of these factors which is a relative validation
factor multiplied by the relative validation tolerance.

Default value

0.00001

Affects routinesXSLPvalidate

See also

XSLP_VALIDATIONINDEX_A, XSLP_VALIDATIONINDEX_R, XSLP_VALIDATIONTOL_R

XSLP_VALIDATIONTOL_R
Description

Relative tolerance for the XSLPvalidate procedure

Type

DoubleNote

XSLPvalidate checks the feasibility of a converged solution against relative and absolute
tolerances for each constraint. The left hand side and the right hand side of the constraint arecalculated using the converged solution values. If the calculated values imply that theconstraint is infeasible, then the difference (D) is tested against the absolute and relative
validation tolerances.
If D < XSLP_VALIDATIONTOL_A
then the constraint is within the absolute validation tolerance. The total positive (TPos) andnegative contributions (TNeg) to the left hand side are also calculated.
If D < MAX(ABS(TPos), ABS(TNeg)) ∗ XSLP_VALIDATIONTOL_R
then the constraint is within the relative validation tolerance. For each constraint which isoutside both the absolute and relative validation tolerances, validation factors are calculated
which are the factors by which the infeasibility exceeds the corresponding validation
tolerance; the smaller factor is printed in the validation report.
The validation index XSLP_VALIDATIONINDEX_A is the largest of these factors which is anabsolute validation factor multiplied by the absolute validation tolerance; the validation index

Fair Isaac Corporation Conﬁdential and Proprietary Information

159

Control Parameters

ReferenceXSLP_VALIDATIONINDEX_R is the largest of these factors which is a relative validation
factor multiplied by the relative validation tolerance.
Default value

0.00001

Affects routinesXSLPvalidate

See also

XSLP_VALIDATIONINDEX_A, XSLP_VALIDATIONINDEX_R, XSLP_VALIDATIONTOL_AXSLP_VTOL_A
Description

Absolute static objective (3) convergence tolerance

Type

DoubleNote

The static objective (3) convergence criterion does not measure convergence of individual
variables, and in fact does not in any way imply that the solution has converged. However, it issometimes useful to be able to terminate an optimization once the objective function appears
to have stabilized. One example is where a set of possible schedules are being evaluated andinitially only a good estimate of the likely objective function value is required, to eliminate theworst candidates.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_VCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_VTOL_A
then the problem has converged on the absolute static objective function (3) criterion.
The static objective function (3) test is applied only if after at least XSLP_VLIMIT +XSLP_SBSTART SLP iterations have taken place and only if XSLP_VCOUNT is at least 2.
Where step bounding is being used, this ensures that the test is not applied until after stepbounding has been introduced. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the optimality target XSLP_VALIDATIONTARGET_K. Good
values for the control are usually fall between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SBSTART, XSLP_VCOUNT, XSLP_VLIMIT, XSLP_VTOL_R

XSLP_VTOL_R
Description

Relative static objective (3) convergence tolerance

Type

DoubleNote

The static objective (3) convergence criterion does not measure convergence of individual
variables, and in fact does not in any way imply that the solution has converged. However, it issometimes useful to be able to terminate an optimization once the objective function appears
to have stabilized. One example is where a set of possible schedules are being evaluated andFair Isaac Corporation Conﬁdential and Proprietary Information

160

Control Parameters

Reference

initially only a good estimate of the likely objective function value is required, to eliminate theworst candidates.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_VCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_VTOL_R
then the problem has converged on the absolute static objective function (3) criterion.
The static objective function (3) test is applied only if after at least XSLP_VLIMIT +XSLP_SBSTART SLP iterations have taken place and only if XSLP_VCOUNT is at least 2.
Where step bounding is being used, this ensures that the test is not applied until after stepbounding has been introduced. When the value is set to be negative, the value is adjusted
automatically by SLP, based on the optimality target XSLP_VALIDATIONTARGET_K. Good
values for the control are usually fall between 1e-3 and 1e-6.
Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SBSTART, XSLP_VCOUNT, XSLP_VLIMIT, XSLP_VTOL_AXSLP_WTOL_A
Description

Absolute extended convergence continuation tolerance

Type

DoubleNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
The extended convergence continuation criterion is applied after a converged solution has
been found where at least one variable has converged on extended criteria and is at its stepbound limit. The extended convergence continuation test measures whether any
improvement is being achieved when additional SLP iterations are carried out. If not, then thelast converged solution will be restored and the optimization will stop.
For a maximization problem, the improvement in the objective function at the current iterationcompared to the objective function at the last converged solution is given by:
δObj = Obj – LastConvergedObj
For a minimization problem, the sign is reversed.
If δObj > XSLP_WTOL_A andδObj > ABS(ConvergedObj) ∗ XSLP_WTOL_R then the solution is deemed to have a signiﬁcantly
better objective function value than the converged solution.
When a solution is found which converges on extended criteria and with active step bounds,
the solution is saved and SLP optimization continues until one of the following:(1) a new solution is found which converges on some other criterion, in which case the SLP
optimization stops with this new solution;(2) a new solution is found which converges on extended criteria and with active step bounds,
and which has a signiﬁcantly better objective function, in which case this is taken as the new
saved solution;

Fair Isaac Corporation Conﬁdential and Proprietary Information

161

Control Parameters

Reference(3) none of the XSLP_WCOUNT most recent SLP iterations has a signiﬁcantly better objectivefunction than the saved solution, in which case the saved solution is restored and the SLP
optimization stops.
When the value is set to be negative, the value is adjusted automatically by SLP, based on the
optimality target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall
between 1e-3 and 1e-6.
Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_WCOUNT, XSLP_WTOL_R

XSLP_WTOL_R
Description

Relative extended convergence continuation tolerance

Type

DoubleNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
The extended convergence continuation criterion is applied after a converged solution has
been found where at least one variable has converged on extended criteria and is at its stepbound limit. The extended convergence continuation test measures whether any
improvement is being achieved when additional SLP iterations are carried out. If not, then thelast converged solution will be restored and the optimization will stop.
For a maximization problem, the improvement in the objective function at the current iterationcompared to the objective function at the last converged solution is given by:
δObj = Obj – LastConvergedObj
For a minimization problem, the sign is reversed.
If δObj > XSLP_WTOL_A andδObj > ABS(ConvergedObj) ∗ XSLP_WTOL_R then the solution is deemed to have a signiﬁcantly
better objective function value than the converged solution.
If XSLP_WCOUNT is greater than zero, and a solution is found which converges on extended
criteria and with active step bounds, the solution is saved and SLP optimization continues
until one of the following:(1) a new solution is found which converges on some other criterion, in which case the SLP
optimization stops with this new solution;(2) a new solution is found which converges on extended criteria and with active step bounds,
and which has a signiﬁcantly better objective function, in which case this is taken as the new
saved solution;(3) none of the XSLP_WCOUNT most recent SLP iterations has a signiﬁcantly better objectivefunction than the saved solution, in which case the saved solution is restored and the SLP
optimization stops.
When the value is set to be negative, the value is adjusted automatically by SLP, based on the
optimality target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall
between 1e-4 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

162

Control Parameters

See also

ReferenceXSLP_WCOUNT, XSLP_WTOL_AXSLP_XTOL_A
Description

Absolute static objective function (1) tolerance

Type

DoubleNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
However, if the objective function has already been stable for several SLP iterations, thenthere is less likelihood of an improved result, and the converged solution can be accepted.
The static objective function (1) test measures the signiﬁcance of the changes in theobjective function over recent SLP iterations. It is applied when all the variables have
converged, but some have converged on extended criteria and at least one of these variables
is at its step bound. Because all the variables have converged, the solution is alreadyconverged but the fact that some variables are at their step bound limit suggests that theobjective function could be improved by going further.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_XCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_XTOL_A
then the objective function is deemed to be static according to the absolute static objectivefunction (1) criterion.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_XTOL_R
then the objective function is deemed to be static according to the relative static objectivefunction (1) criterion.
The static objective function (1) test is applied only until XSLP_XLIMIT SLP iterations havetaken place. After that, if all the variables have converged on strict or extended criteria, thesolution is deemed to have converged.
If the objective function passes the relative or absolute static objective function (1) test thenthe solution is deemed to have converged.
When the value is set to be negative, the value is adjusted automatically by SLP, based on the
optimality target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall
between 1e-3 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_XCOUNT, XSLP_XLIMIT, XSLP_XTOL_R

XSLP_XTOL_R
Description

Relative static objective function (1) tolerance

Fair Isaac Corporation Conﬁdential and Proprietary Information

163

Control Parameters

Reference

Type

DoubleNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
However, if the objective function has already been stable for several SLP iterations, thenthere is less likelihood of an improved result, and the converged solution can be accepted.
The static objective function (1) test measures the signiﬁcance of the changes in theobjective function over recent SLP iterations. It is applied when all the variables have
converged, but some have converged on extended criteria and at least one of these variables
is at its step bound. Because all the variables have converged, the solution is alreadyconverged but the fact that some variables are at their step bound limit suggests that theobjective function could be improved by going further.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_XCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_XTOL_A
then the objective function is deemed to be static according to the absolute static objectivefunction (1) criterion.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_XTOL_R
then the objective function is deemed to be static according to the relative static objectivefunction (1) criterion.
The static objective function (1) test is applied only until XSLP_XLIMIT SLP iterations havetaken place. After that, if all the variables have converged on strict or extended criteria, thesolution is deemed to have converged.
If the objective function passes the relative or absolute static objective function (1) test thenthe solution is deemed to have converged.
When the value is set to be negative, the value is adjusted automatically by SLP, based on the
optimality target XSLP_VALIDATIONTARGET_K. Good values for the control are usually fall
between 1e-4 and 1e-6.

Default value-1.0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_XCOUNT, XSLP_XLIMIT, XSLP_XTOL_AXSLP_ZERO
Description

Absolute tolerance

Type

DoubleNote

If a value is below XSLP_ZERO in magnitude, then it will be regarded as zero in certain
formula calculations:an attempt to divide by such a value will give a "divide by zero" error;
an exponent of a negative number will produce a "negative number, fractional exponent" error
if the exponent differs from an integer by more than XSLP_ZERO.

Default value

1.0E-10

Fair Isaac Corporation Conﬁdential and Proprietary Information

164

Control Parameters

Affects routines

Reference

XSLPevaluatecoef, XSLPevaluateformula

Fair Isaac Corporation Conﬁdential and Proprietary Information

165

Control Parameters

20.2

Reference

Integer control parametersXSLP_ALGORITHM
Description

Bit map describing the SLP algorithm(s) to be used

Type

Integer

Values

Bit
0
1
2
3
4
5
6
7
8
9
11
12
13
14
15
16

Notes

Meaning
Do not apply step bounds.
Apply step bounds to SLP delta vectors only when required.
Estimate step bounds from early SLP iterations.
Use dynamic damping.
Do not update values which are converged within strict tolerance.
Retain previous value when cascading if determining row is zero.
Reset XSLP_DELTA_Z to zero when converged and continue SLP.
Quick convergence check.
Escalate penalties.
Use the primal simplex algorithm when all error vectors become inactive.
Continue optimizing after penalty cost reaches maximum.
Accept a solution which has converged even if there are still signiﬁcant active
penalty error vectors.
Skip the solution polishing step if the LP postsolve returns a slightly infeasible, but
claimed optimal solution.
Step bounds are updated to accomodate cascaded values (otherwise cascadedvalues are pushed to respect step bounds).
Apply clamping when converged on extended criteria only with some variables
having active step bounds.
Apply clamping when converged on extended criteria only.

Bit 0: Do not apply step bounds. The default algorithm uses step bounds to force
convergence. Step bounds may not be appropriate if dynamic damping is used.
Bit 1: Apply step bounds to SLP delta vectors only when required. Step bounds can beapplied to all vectors simultaneously, or applied only when oscillation of the delta vector(change in sign between successive SLP iterations) is detected.
Bit 2: Estimate step bounds from early SLP iterations. If initial step bounds are not being
explicitly provided, this gives a good method of calculating reasonable values. Values willtend to be larger rather than smaller, to reduce the risk of infeasibility caused by excessive
tightness of the step bounds.
Bit 3: Use dynamic damping. Dynamic damping is sometimes an alternative to stepbounding as a means of encouraging convergence, but it does not have the same power toforce convergence as do step bounds.
Bit 4: Do not update values which are converged within strict tolerance. Models which are
numerically unstable may beneﬁt from this setting, which does not update values which haveeffectively hardly changed. If a variable subsequently does move outside its strict
convergence tolerance, it will be updated as usual.
Bit 5: Retain previous value when cascading if determining row is zero. If the determining
row is zero (that is, all the coefﬁcients interacting with it are either zero or in columns with a

Fair Isaac Corporation Conﬁdential and Proprietary Information

166

Control Parameters

Referencezero activity), then it is impossible to calculate a new value for the vector being cascaded.
The choice is to use the solution value as it is, or to revert to the assumed value
Bit 6: Reset XSLP_DELTA_Z to zero when converged and continue SLP. One of themechanisms to avoid local optima is to retain small non-zero coefﬁcients between delta
vectors and constraints, even when the coefﬁcient should strictly be zero. If this option is set,
then a converged solution will be continued with zero coefﬁcients as appropriate.
Bit 7: Quick convergence check. Normally, each variable is checked against all
convergence criteria until either a criterion is found which it passes, or it is declared "notconverged". Later (extended convergence) criteria are more expensive to test and, once anunconverged variable has been found, the overall convergence status of the solution has
been established. The quick convergence check carries out checks on the strict criteria, butomits checks on the extended criteria when an unconverged variable has been found.
Bit 8: Escalate penalties. Constraint penalties are increased after each SLP iteration where
penalty vectors are present in the solution. Escalation applies an additional scaling factor to
the penalty costs for active errors. This helps to prevent successive solutions becoming"stuck" because of a particular constraint, because its cost will be raised so that otherconstraints may become more attractive to violate instead and thus open up a new region to
explore.
Bit 9: Use the primal simplex algorithm when all error vectors become inactive. The primal
simplex algorithm often performs better than dual during the ﬁnal stages of SLP optimization
when there are relatively few basis changes between successive solutions. As it is
impossible to establish in advance when the ﬁnal stages are being reached, thedisappearance of error vectors from the solution is used as a proxy.
Bit 11: Continue optimizing after penalty cost reaches maximum. Normally if the penalty
cost reaches its maximum (by default the value of XPRS_PLUSINFINITY), the optimization
will terminate with an unconverged solution. If the maximum value is set to a smaller value,then it may make sense to continue, using other means to determine when to stop.
Bit 12: Accept a solution which has converged even if there are still signiﬁcant active
penalty error vectors. Normally, the optimization will continue if there are active penalty
vectors in the solution. However, it may be that there is no feasible solution (and so active
penalties will always be present). Setting bit 12 means that, if other convergence criteria aremet, then the solution will be accepted as converged and the optimization will stop.
Bit 13: Due to the nature of the SLP linearizations, and in particular because of the large
differences in the objective function (model objective against penalty costs) some dual
reductions in the linear presolver might introduce numerically instable reductions that cause
slight infeasibilities to appear in postsolve. It is typically more efﬁcient to remove these
infeasibilities with an extra call to the linear optimizer; compared to switching these
reductions off, which usually has a signiﬁcant cost in performance. This bit is provided fornumerically very hard problems, when the polishing step proves to be too expensive (XSLP
will report these if any in the ﬁnal log summary).
Bit 14: Normally, cascading will respect the step bounds of the SLP variable being
cascaded. However, allowing the cascaded value to fall outside the step bounds (i.e.
expanding the step bounds) can lead to better linearizations, as cascading will set better
values for the SLP variables regarding their determining rows; note, that this later strategy
might interfere with convergence of the cascaded variables.
Bit 15: When clamping is applied, then in any iteration when the solution would normally
be deemed converged on extended criteria only, an extra step bound shrinking step is applied
to help imposing strict convergence. In this variant, clamping is only applied on variables thathave converged on extended criteria only and have active step bounds.
Bit 16: When clamping is applied, then in any iteration when the solution would normally
be deemed converged on extended criteria only, an extra step bound shrinking step is applied

Fair Isaac Corporation Conﬁdential and Proprietary Information

167

Control Parameters

Referenceto help imposing strict convergence. In this variant, clamping is applied on all variables thathave converged on extended criteria only.
The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8
Setting bit 9
Setting bit 11
Setting bit 12
Setting bit 13
Setting bit 14
Setting bit 15
Setting bit 16

XSLP_NOSTEPBOUNDSXSLP_STEPBOUNDSASREQUIREDXSLP_ESTIMATESTEPBOUNDSXSLP_DYNAMICDAMPINGXSLP_HOLDVALUESXSLP_RETAINPREVIOUSVALUEXSLP_RESETDELTAZXSLP_QUICKCONVERGENCECHECKXSLP_ESCALATEPENALTIESXSLP_SWITCHTOPRIMALXSLP_MAXCOSTOPTIONXSLP_RESIDUALERRORSXSLP_NOLPPOLISHINGXSLP_CASCADEDBOUNDSXSLP_CLAMPEXTENDEDACTIVESBXSLP_CLAMPEXTENDEDALL

Recommended setting: Bits 1, 2, 5, 7 and usually bits 8 and 9.
Default value

166 (sets bits 1, 2, 5, 7)

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTA_Z, XSLP_ERRORMAXCOST, XSLP_ESCALATION, XSLP_CLAMPSHRINKXSLP_ANALYZE
Description

Bit map activating additional options supporting model / solution path analyzis

TypeInteger

Values

Bit
0
1
2
3
4
5
6
7
8

Note

Meaning
Add solutions of the linearizations to the solution pool.
Add cascaded solutions to the solution pool.
Add line search solutions to the solution pool.
Include an extended iteration summary.
Run infeasibility analysis on infeasible iterations.
Save the solutions collected in the pool to disk.
Write the linearizations to disk at every XSLP_AUTOSAVE iterations.
Write the initial basis of the linearizations to disk at every XSLP_AUTOSAVE
iterations.
Create an XSLP save ﬁle at every XSLP_AUTOSAVE iterations.

The solution pool can be accessed using the memory attribute XSLP_SOLUTIONPOOL.
Normally, the value of this control does not affect the solution process itself. However, bit 3(extended summary) will cause SLP to do more function evaluations, and the presence of
non-deterministic user functions might cause changes in the solution process. These options
are off by default due to performance considerations. The following constants are provided
for setting these bits:

Fair Isaac Corporation Conﬁdential and Proprietary Information

168

Control Parameters

Reference

Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8

XSLP_ANALYZE_RECORDLINEARIZATIONXSLP_ANALYZE_RECORDCASCADEXSLP_ANALYZE_RECORDLINESEARCHXSLP_ANALYZE_EXTENDEDFINALSUMMARYXSLP_ANALYZE_INFEASIBLE_ITERATIONXSLP_ANALYZE_AUTOSAVEPOOLXSLP_ANALYZE_SAVELINEARIZATIONSXSLP_ANALYZE_SAVEITERBASISXSLP_ANALYZE_SAVEFILE

Default value0

See also

XSLP_AUTOSAVEXSLP_AUGMENTATION
Description

Bit map describing the SLP augmentation method(s) to be used

Type

Integer

Values

Bit
0
1
2
3
4
5
6
7
8
9
10

Notes

Bit 0: Minimum augmentation. Standard augmentation includes delta vectors for all
variables involved in nonlinear terms (in non-constant coefﬁcients or as vectors containing
non-constant coefﬁcients). Minimum augmentation includes delta vectors only for variables
in non-constant coefﬁcients. This produces a smaller linearization, but there is less control onconvergence, because convergence control (for example, step bounding) cannot be applied
to variables without deltas.

Meaning
Minimum augmentation.
Even handed augmentation.
Penalty error vectors on all non-linear equality constraints.
Penalty error vectors on all non-linear inequality constraints.
Penalty vectors to exceed step bounds.
Use arithmetic means to estimate penalty weights.
Estimate step bounds from values of row coefﬁcients.
Estimate step bounds from absolute values of row coefﬁcients.
Row-based step bounds.
Penalty error vectors on all constraints.
Intial values do not imply an SLP variable.

Bit 1: Even handed augmentation. Standard augmentation treats variables which appear in
non-constant coefﬁcients in a different way from those which contain non-constantcoefﬁcients. Even-handed augmentation treats them all in the same way by replacing each
non-constant coefﬁcient C in a vector V by a new coefﬁcient C ∗ V in the "equals" column(which has a ﬁxed activity of 1) and creating delta vectors for all types of variable in the sameway.
Bit 2: Penalty error vectors on all non-linear equality constraints. The linearization of anonlinear equality constraint is inevitably an approximation and so will not generally befeasible except at the point of linearization. Adding penalty error vectors allows the linear
approximation to be violated at a cost and so ensures that the linearized constraint is feasible.
Bit 3: Penalty error vectors on all non-linear inequality constraints. The linearization of anonlinear constraint is inevitably an approximation and so may not be feasible except at the

Fair Isaac Corporation Conﬁdential and Proprietary Information

169

Control Parameters

Referencepoint of linearization. Adding penalty error vectors allows the linear approximation to beviolated at a cost and so ensures that the linearized constraint is feasible.
Bit 4: Penalty vectors to exceed step bounds. Although it has rarely been found necessaryor desirable in practice, Xpress-SLP allows step bounds to be violated at a cost. This mayhelp with feasibility but it generally slows down or prevents convergence, so it should be used
only if found absolutely necessary.
Bit 5: Use arithmetic means to estimate penalty weights. Penalty weights are estimatedfrom the magnitude of the elements in the constraint or interacting rows. Geometric means
are normally used, so that a few excessively large or small values do not distort the weights
signiﬁcantly. Arithmetic means will value the coefﬁcients more equally.
Bit 6: Estimate step bounds from values of row coefﬁcients. If step bounds are to be
imposed from the start, the best approach is to provide explicit values for the bounds.
Alternatively, Xpress-SLP can estimate the values from the range of estimated coefﬁcientsizes in the relevant rows.
Bit 7: Estimate step bounds from absolute values of row coefﬁcients. If step bounds are to
be imposed from the start, the best approach is to provide explicit values for the bounds.
Alternatively, Xpress-SLP can estimate the values from the largest estimated magnitude of
the coefﬁcients in the relevant rows.
Bit 8: Row-based step bounds. Step bounds are normally applied as bounds on the deltavariables. Some applications may ﬁnd that using explicit rows to bound the delta vectors
gives better results.
Bit 9: Penalty error vectors on all constraints. If the linear portion of the underlying model
may actually be infeasible, then applying penalty vectors to all rows may allow identiﬁcationof the infeasibility and may also allow a useful solution to be found.
Bit 10: Having an initial value will not cause the augmentation to include the corresponding
delta variable; i.e. treat the variable as an SLP variable. Useful to provide initial values
necessary in the ﬁrst linearization in case of a minimal augmentation, or as a convenience
option when it’s easiest to set an initial value for all variables for some reason.
The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8
Setting bit 9
Setting bit 10

XSLP_MINIMUMAUGMENTATIONXSLP_EVENHANDEDAUGMENTATIONXSLP_EQUALITYERRORVECTORSXSLP_ALLERRORVECTORSXSLP_PENALTYDELTAVECTORSXSLP_AMEANWEIGHTXSLP_SBFROMVALUESXSLP_SBFROMABSVALUESXSLP_STEPBOUNDROWSXSLP_ALLROWERRORVECTORSXSLP_NOUPDATEIFONLYIV

The recommended setting is bits 2 and 3 (penalty vectors on all nonlinear constraints).
Default value

12 (sets bits 2 and 3)

Affects routinesXSLPconstruct

XSLP_AUTOSAVE
Description

Frequency with which to save the model

Fair Isaac Corporation Conﬁdential and Proprietary Information

170

Control Parameters

Reference

Type

Integer

Note

A value of zero means that the model will not automatically be saved. A positive value of n
will save model information at every nth SLP iteration as requested by XSLP_ANALYZIS.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ANALYZEXSLP_BARCROSSOVERSTART
Description

Default crossover activation behaviour for barrier startType

Integer

Note

When XSLP_BARLIMIT is set, XSLP_BARCROSSOVERSTART offers an overwrite control onwhen crossover is applied. A positive value indicates that crossover should be disabled in
iterations smaller than XSLP_BARCROSSOVERSTART and should be enabled afterwards, orwhen stalling is detected as described in XSLP_BARSTARTOPS. A value of 0 indicates torespect the value of XPRS_CROSSOVER and only overwrite its value when stalling is detected.
A value of -1 indicates to always rely on the value of XPRS_CROSSOVER.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARLIMIT, XSLP_BARSTARTOPS, XSLP_BARSTALLINGLIMIT,XSLP_BARSTALLINGOBJLIMIT, XSLP_BARSTALLINGTOLXSLP_BARLIMIT
Description

Number of initial SLP iterations using the barrier method

Type

Integer

Note

Particularly for larger models, using the Newton barrier method is faster in the earlier SLP
iterations. Later on, when the basis information becomes more useful, a simplex method
generally performs better. XSLP_BARLIMIT sets the number of SLP iterations which will be
performed using the Newton barrier method.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARCROSSOVERSTART, XSLP_BARSTARTOPS, XSLP_BARSTALLINGLIMIT,XSLP_BARSTALLINGOBJLIMIT, XSLP_BARSTALLINGTOL

Fair Isaac Corporation Conﬁdential and Proprietary Information

171

Control Parameters

ReferenceXSLP_BARSTALLINGLIMIT
Description

Number of iterations to allow numerical failures in barrier before switching to dual

Type

IntegerNote

On large problems, it may be beneﬁcial to warm start progress by running a number of
iterations with the barrier solver as speciﬁed by XSLP_BARLIMIT. On some numerically
difﬁcult problems, the barrier may stop prematurely due to numerical issues. Such solves cansometimes be ﬁnished if crossover is applied. After XSLP_BARSTALLINGLIMIT suchattempts, SLP will automatically switch to use the dual simplex.

Default value

3

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARCROSSOVERSTART, XSLP_BARLIMIT, XSLP_BARSTARTOPS,XSLP_BARSTALLINGOBJLIMIT, XSLP_BARSTALLINGTOLXSLP_BARSTALLINGOBJLIMIT
Description

Number of iterations over which to measure the objective change for barrier iterations with nocrossoverType

IntegerNote

On large problems, it may be beneﬁcial to warm start progress by running a number of
iterations with the barrier solver without crossover by setting XSLP_BARLIMIT to a positive
value and setting XPRS_CROSSOVER to 0. A potential drawback is slower convergence due tothe interior point provided by the barrier solve keeping a higher number of variables active.
This may lead to stalling in progress, negating the beneﬁt of using the barrier. When in the lastXSLP_BARSTALLINGOBJLIMIT iterations no signiﬁcant progress has been made, crossoveris automatically enabled.

Default value

3

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARCROSSOVERSTART, XSLP_BARLIMIT, XSLP_BARSTARTOPS,XSLP_BARSTALLINGLIMIT, XSLP_BARSTALLINGTOLXSLP_BARSTARTOPS
Description

Controls behaviour when the barrier is used to solve the linearizations

Type

Integer

ValuesBit
0
1
2

Meaning
Check objective progress when no crossover is applied.
Fall back to dual simplex if too many numerical problems are reported by the barrier.
If a non-vertex converged solution found by barrier without crossover can be
returned as a ﬁnal solution.

Fair Isaac Corporation Conﬁdential and Proprietary Information

172

Control Parameters

Note

Reference

The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2

BARSTARTOPS_STALLING_OBJECTIVE
BARSTARTOPS_STALLING_NUMERICALBARSTARTOPS_ALLOWINTERIORSOLUTION

Default value-1

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_BARCROSSOVERSTART, XSLP_BARLIMIT, XSLP_BARSTALLINGLIMIT,XSLP_BARSTALLINGOBJLIMIT, XSLP_BARSTALLINGTOLXSLP_CALCTHREADS
Description

Number of threads used for formula and derivatives evaluations

Type

Integer

Note

When beneﬁcial, SLP can calculate formula values and partial derivative information inparallel.

Default value-1 (automatically determined)

Affects routinesXSLPmaxim, XSLPmaxim

See also

XSLP_THREADS,XSLP_CASCADE
Description

Bit map describing the cascading to be used

Type

Integer

Values

Bit
0
1
2
3
4
5

Note

Meaning
Apply cascading to all variables with determining rows.
Apply cascading to SLP variables which appear in coefﬁcients and which wouldchange by more than XPRS_FEASTOL.
Apply cascading to all SLP variables which appear in coefﬁcients.
Apply cascading to SLP variables which are structural and which would change bymore than XPRS_FEASTOL.
Apply cascading to all SLP variables which are structural.
Create secondary order groupping DR rows with instantiated user functions together
in the order.

Normal cascading (bit 0) uses determining rows to recalculate the values of variables to beconsistent with values already available or already recalculated.
Other bit settings are normally required only in quadratic programming where some of the
SLP variables are in the objective function. The values of such variables may need to becorrected if the corresponding update row is slightly infeasible. The following constants areprovided for setting these bits:

Fair Isaac Corporation Conﬁdential and Proprietary Information

173

Control Parameters

Reference

Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Default value

1

Affects routinesXSLPcascadeXSLP_CASCADE_ALL
XSLP_CASCADE_COEF_VAR
XSLP_CASCADE_ALL_COEF_VAR
XSLP_CASCADE_STRUCT_VAR
XSLP_CASCADE_ALL_STRUCT_VAR
XSLP_CASCADE_SECONDARY_GROUPSXSLP_CASCADENLIMIT
Description

Maximum number of iterations for cascading with non-linear determining rows

Type

IntegerNote

Re-calculation of the value of a variable uses a modiﬁcation of the Newton-Raphson method.
The maximum number of steps in the method is set by XSLP_CASCADENLIMIT. If the
maximum number of steps is taken without reaching a converged value, the best value foundwill be used.

Default value

10

Affects routinesXSLPcascade

See also

XSLP_CASCADEXSLP_CONTROL
Description

Bit map describing which Xpress NonLinear functions also activate the corresponding
Optimizer Library function

Type

Integer

Values

Bit
0
1
2
3
4
5
6

Note

Meaning
Xpress NonLinear problem management functions do NOT invoke the corresponding
Optimizer Library function for the underlying linear problem.
XSLPcopycontrols does NOT invoke XPRScopycontrols.
XSLPcopycallbacks does NOT invoke XPRScopycallbacks.
XSLPcopyprob does NOT invoke XPRScopyprob.
XSLPsetdefaults does NOT invoke XPRSsetdefaults.
XSLPsave does NOT invoke XPRSsave.
XSLPrestore does NOT invoke XPRSrestore.

The problem management functions are:XSLPcopyprob to copy from an existing problem;XSLPcopycontrols and XSLPcopycallbacks to copy the current controls and callbacks
from an existing problem;XSLPsetdefaults to reset the controls to their default values;
XSLPsave and XSLPrestore for saving and restoring a problem.

Fair Isaac Corporation Conﬁdential and Proprietary Information

174

Control Parameters

Reference

Default value

0 (no bits set)

Affects routinesXSLPcopycontrols, XSLPcopycallbacks, XSLPcopyprob, XSLPrestore, XSLPsave,
XSLPsetdefaults

XSLP_CONVERGENCEOPS
Description

Bit map describing which convergence tests should be carried out

TypeInteger

Values

Bit
0
1
2
3
4
5
6
7
8
9
10
11
12

Note

Provides ﬁne tuned control (over setting the related convergence tolerances) of whichconvergence checks are carried out.

Meaning
Execute the closure tolerance checks.
Execute the delta tolerance checks.
Execute the matrix tolerance checks.
Execute the impact tolerance checks.
Execute the slack impact tolerance checks.
Check for user provided convergence.
Execute the objective range checks.
Execute the objective range + constraint activity check.
Execute the objective range + active step bound check.
Execute the convergence continuation check.
Take scaling of individual variables / rows into account.
Execute the validation target convergence checks.
Execute the ﬁrst order optimality target convergence checks.

The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8
Setting bit 9
Setting bit 10
Setting bit 11
Setting bit 12

XSLP_CONVERGEBIT_CTOLXSLP_CONVERGEBIT_ATOLXSLP_CONVERGEBIT_MTOLXSLP_CONVERGEBIT_ITOLXSLP_CONVERGEBIT_STOLXSLP_CONVERGEBIT_USERXSLP_CONVERGEBIT_VTOLXSLP_CONVERGEBIT_XTOLXSLP_CONVERGEBIT_OTOLXSLP_CONVERGEBIT_WTOLXSLP_CONVERGEBIT_EXTENDEDSCALINGCONVERGEBIT_VALIDATIONCONVERGEBIT_VALIDATION_K

Default value

7167 (bits 0-9 and 11-12 are set)

Affects routinesXSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

175

Control Parameters

ReferenceXSLP_DAMPSTART
Description

SLP iteration at which damping is activatedType

Integer

Note

If damping is used as part of the SLP algorithm, it can be delayed until a speciﬁed SLP
iteration. This may be appropriate when damping is used to encourage convergence after an
un-damped algorithm has failed to converge.

Default value0

Affects routinesXSLPmaxim, XSLPmaxim

See also

XSLP_ALGORITHM, XSLP_DAMPEXPAND, XSLP_DAMPMAX, XSLP_DAMPMIN,XSLP_DAMPSHRINKXSLP_DCLIMIT
Description

Default iteration delay for delayed constraints

Type

Integer

Note

If a delayed constraint does not have an explicit delay, then the value of XSLP_DCLIMIT will
be used.

Default value

5

Affects routinesXSLPmaxim, XSLPminimXSLP_DCLOG
Description

Amount of logging information for activcation of delayed constraints

Type

IntegerNote

If XSLP_DCLOG is set to 1, then a message will be produced for each DC as it is activated.

Default value0

Affects routinesXSLPmaxim, XSLPminimXSLP_DELAYUPDATEROWS
Description

Number of SLP iterations before update rows are fully activatedType

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

176

Control Parameters

Reference

Notes

Update rows are an integral part of the augmented matrix used to create linear
approximations of the nonlinear problem. However, if determining rows are present, then it ispossible for some updated values to be calculated during cascading, and the corresponding
update rows are then not required. When SLP variables have explicit bounds, and particularly
when step bounding is enforced, update rows become important to the solutions actuallyobtained. It is therefore normal practice to delay update rows for only a few initial SLP
iterations.
Update rows can only be delayed for variables which are not structural (that is, they do nothave explicit coefﬁcients in the original problem) and for which determining rows areprovided.

Default value

2

Affects routinesXSLPmaxim, XSLPminimXSLP_DELTAOFFSET
Description

Position of ﬁrst character of SLP variable name used to create name of delta vector

Type

Integer

Note

During augmentation, a delta vector, and possibly penalty delta vectors, are created for each
SLP variable. They are created with names derived from the corresponding SLP variable.
Customized naming is possible using XSLP_DELTAFORMAT etc to deﬁne a format and
XSLP_DELTAOFFSET to deﬁne the ﬁrst character (counting from zero) of the variable nameto be used.

Default value0

Affects routinesXSLPconstruct

See also

XSLP_DELTAFORMAT, XSLP_MINUSDELTAFORMAT, XSLP_PLUSDELTAFORMATXSLP_DELTAZLIMIT
Description

Number of SLP iterations during which to apply XSLP_DELTA_Z

Type

IntegerNote

XSLP_DELTA_Z is used to retain small derivatives which would otherwise be regarded aszero. This is helpful in avoiding local optima, but may make the linearized problem more
difﬁcult to solve because of the number of small nonzero elements in the resulting matrix.
XSLP_DELTAZLIMIT can be set to a nonzero value, which is then the number of iterations forwhich XSLP_DELTA_Z will be used. After that, small derivatives will be set to zero. A negativevalue indicates no automatic perturbations to the derivatives in any situation.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_DELTA_Z

Fair Isaac Corporation Conﬁdential and Proprietary Information

177

Control Parameters

ReferenceXSLP_DERIVATIVES
Description

Bitmap describing the method of calculating derivatives

Type

Integer

Values

Bit
0
1

Notes

If no bits are set then numerical derivatives are calculated using ﬁnite differences.
Analytic derivatives cannot be used for formulae involving discontinuous functions. They may
not work well with functions which are not smooth (such as MAX), or where the derivativechanges very quickly with the value of the variable (such as LOG of small values).
Both ﬁrst and second order analytic derivatives can either be calculated as symbolic
formulas, or by the means of auto-differentiation, with the exception that the second order
symbolic derivatives require that the ﬁrst order derivatives are also calculated using thesymbolic method.

Default value

1

Affects routinesXSLPconstruct, XSLPmaxim, XSLPminim

See also

XSLP_JACOBIAN, XSLP_HESSIAN

Meaninganalytic derivatives where possible
avoid embedding numerical derivatives of instantiated functions into analytic
derivatives

XSLP_DETERMINISTIC
Description

Determines if the parallel features of SLP should be guaranteed to be deterministic

Type

Integer

Note

Determinism can only be guaranteed if no callbacks are used, or if in the presence of
callbacks the effect of the callbacks only depend on local information provided by SLP.

Default value

1

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTART_POOLSIZE,XSLP_ECFCHECK
Description

Check feasibility at the point of linearization for extended convergence criteria

Type

Integer

Values0
1
2

no check (extended criteria are always used);check until one infeasible constraint is found;
check all constraints.

Fair Isaac Corporation Conﬁdential and Proprietary Information

178

Control Parameters

Reference

Notes

The extended convergence criteria measure the accuracy of the solution of the linear
approximation compared to the solution of the original nonlinear problem. For this to work,
the linear approximation needs to be reasonably good at the point of linearization. In
particular, it needs to be reasonably close to feasibility.
XSLP_ECFCHECK is used to determine what checking of feasibility is carried out at the pointof linearization. If the point of linearization at the start of an SLP iteration is deemed to be
infeasible, then the extended convergence criteria are not used to decide convergence at theend of that SLP iteration.
If all that is required is to decide that the point of linearization is not feasible, then the search
can stop after the ﬁrst infeasible constraint is found (parameter is set to 1). If the actual
number of infeasible constraints is required, then XSLP_ECFCHECK should be set to 2, and all
constraints will be checked.
The number of infeasible constraints found at the point of linearization is returned in
XSLP_ECFCOUNT.

Default value

1

Affects routines

Convergence criteria, XSLPmaxim, XSLPminim

See also

XSLP_ECFCOUNT, XSLP_ECFTOL_A, XSLP_ECFTOL_R

XSLP_ECHOXPRSMESSAGES
Description

Controls if the XSLP message callback should relay messages from the XPRS library.

Type

IntegerNote

In case the XSLP and XPRS logs are handled the same way by an application, setting thiscontrol to 1 makes it sufﬁcient to implement the XSLP messaging callback only.

Default value

0

XSLP_ERROROFFSET
Description

Position of ﬁrst character of constraint name used to create name of penalty error vectors

Type

Integer

Note

During augmentation, penalty error vectors may be created for some or all of the constraints.
The vectors are created with names derived from the corresponding constraint name.
Customized naming is possible using XSLP_MINUSERRORFORMAT andXSLP_PLUSERRORFORMAT to deﬁne a format and XSLP_ERROROFFSET to deﬁne the ﬁrst
character (counting from zero) of the constraint name to be used.

Default value0

Affects routinesXSLPconstruct

See also

XSLP_MINUSERRORFORMAT, XSLP_PLUSERRORFORMAT

Fair Isaac Corporation Conﬁdential and Proprietary Information

179

Control Parameters

ReferenceXSLP_EVALUATE
Description

Evaluation strategy for user functions

Type

Integer

Values01

Note

If a user function returns derivatives or returns more than one value, then it is possible for
Xpress NonLinear to estimate the value of the function from its derivatives if the new point ofevaluation is sufﬁciently close to the original. Setting XSLP_EVALUATE to 1 will force
re-evaluation of all functions regardless of how much or little the point of evaluation haschanged.

Default value0

Affects routinesXSLPevaluatecoef, XSLPevaluateformulaSee also

XSLP_FUNCEVAL

use derivatives where possible;
always re-evaluate.

XSLP_FILTER
Description

Bit map for controlling solution updates

Type

Integer

Values

Bit
0
1
2
3

Notes

Bits 0 determine if XSLPgetslpsol should return the ﬁnal converged solution, or thesolution which had the best value according to the merit function.
If bit 1 is set, a cascaded solution which does not improve the merit function will be rejected(XSLP will revert to the solution of the linearization).
Bits 2-3 determine the strategy for when the step direction is not improving according to themerit function.
The following constants are provided for setting these bits:

Meaning
retrain solution best according to the merit function.
check cascaded solutions against improvements in the merit function.
force minimum step sizes in line search.
accept the trust region step is the line search returns a zero step size.

Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3

XSLP_FILTER_KEEPBESTXSLP_FILTER_CASCADEXSLP_FILTER_ZEROLINESEARCHXSLP_FILTER_ZEROLINESEARCHTR

Default value

11 (bit 0,1,3)

Affects routinesXSLPmaxim, XSLPminim, XSLPcascade

See also

XSLP_MERITLAMBDA, XSLP_CASCADE, XSLP_LSSTART, XSLP_LSITERLIMIT,XSLP_LSPATTERNLIMIT

Fair Isaac Corporation Conﬁdential and Proprietary Information

180

Control Parameters

ReferenceXSLP_FINDIVDescription

Option for running a heuristic to ﬁnd a feasible initial pointType

Integer

Values

-1
0
1

Notes

The procedure uses bound reduction (and, up to an extent, probing) to obtain a point in theinitial bounding box that is feasible for the bound reduction techniques.
If an initial point is already speciﬁed and is found not to violate bound reduction, then theheuristic is not run and the given point is used as the initial solution.

Default value-1

Affects routinesXSLPmaxim, XSLPminim

Automatic (default).
Disable the heuristic.
Enable the heuristic.

XSLP_FUNCEVAL
Description

Bit map for determining the method of evaluating user functions and their derivatives

Type

Integer

Values

Bit
3
4
5
6
7
8

Notes

Meaning
evaluate function whenever independent variables change.
evaluate function when independent variables change outside tolerances.
application of bits 3-4: 0 = functions which do not have a deﬁned re-evaluation
mode;1 = all functions.
tangential derivatives.
forward derivatives
application of bits 6-7: 0 = functions which do not have a deﬁned derivative mode;1 =all functions.

Bits 3-4 determine the type of function re-evaluation. If both bits are zero, then the settings foreach individual function are used.
If bit 3 or bit 4 is set, then bit 5 deﬁnes which functions the setting applies to. If it is set to 1,
then it applies to all functions. Otherwise, it applies only to functions which do not have an
explicit setting of their own.
Bits 6-7 determine the type of calculation for numerical derivatives. If both bits are zero, thenthe settings for each individual function are used.
If bit 6 or bit 7 is set, then bit 8 deﬁnes which functions the setting applies to. If it is set to 1,
then it applies to all functions. Otherwise, it applies only to functions which do not have an
explicit setting of their own.
The following constants are provided for setting these bits:

Fair Isaac Corporation Conﬁdential and Proprietary Information

181

Control Parameters

Reference

Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8

XSLP_RECALCXSLP_TOLCALCXSLP_ALLCALCSXSLP_2DERIVATIVEXSLP_1DERIVATIVEXSLP_ALLDERIVATIVES

Default value0

Affects routinesXSLPevaluatecoef, XSLPevaluateformulaSee also

XSLP_EVALUATEXSLP_GRIDHEURSELECT
Description

Bit map selectin which heuristics to run if the problem has variable with an integer delta

Type

Integer

Values

Bit
0
1
2

Note

A value of 0 indicates that integer deltas are only taken into consideration during the SLP
iterations.

Note

The enumeration option can be useful for cases where the number of possible values of thevariables with an integer delta is small.

Default value

3 (bits 1-2 are set)

Affects routinesXSLPmaxim, XSLPminim

Meaning
Enumeration: try all combinations.
Simple search heuristics.
Simulated annealing.

XSLP_HEURSTRATEGY
Description

Branch and Bound: This speciﬁes the MINLP heuristic strategy. On some problems it is worth
trying more comprehensive heuristic strategies by setting HEURSTRATEGY to 2 or 3.

Type

Integer

Values

-1
0
1
2
3
4

Default value-1

Affects routinesXSLPminim, XSLPmaxim.

Automatic selection of heuristic strategy.
No heuristics.
Basic heuristic strategy.
Enhanced heuristic strategy.
Extensive heuristic strategy.
Run all heuristics without effort limits.

Fair Isaac Corporation Conﬁdential and Proprietary Information

182

Control Parameters

ReferenceXSLP_HESSIAN
Description

Second order differentiation mode when using analytical derivatives

Type

Integer

Values

-1,0
1
2
3

Note

Symbolic mode differentiation for the second order derivatives is only available when
XSLP_JACOBIAN is also set to symbolic mode.

Default value-1

See also

XSLP_DERIVATIVES, XSLP_JACOBIAN

automatic selection
numerical derivatives (ﬁnite difference)symbolic differentiation
automatic differentiationXSLP_INFEASLIMIT
Description

The maximum number of consecutive infeasible SLP iterations which can occur before
Xpress-SLP terminates

Type

Integer

Note

An infeasible solution to an SLP iteration means that is likely that Xpress-SLP will create apoor linear approximation for the next SLP iteration. Sometimes, small infeasibilities arise
because of numerical difﬁculties and do not seriously affect the solution process. However, if
successive solutions remain infeasible, it is unlikely that Xpress-SLP will be able to ﬁnd a
feasible converged solution. XSLP_INFEASLIMIT sets the number of successive SLP
iterations which must take place before Xpress-SLP terminates with a status of "infeasible
solution".

Default value

3

Affects routinesXSLPmaxim, XSLPminimXSLP_ITERLIMIT
Description

The maximum number of SLP iterations

Type

Integer

Note

If Xpress-SLP reaches XSLP_ITERLIMIT without ﬁnding a converged solution, it will stop.
For MISLP, the limit is on the number of SLP iterations at each node.

Default value

1000

Affects routinesXSLPglobal, XSLPmaxim, XSLPminim

Fair Isaac Corporation Conﬁdential and Proprietary Information

183

Control Parameters

ReferenceXSLP_JACOBIAN
Description

First order differentiation mode when using analytical derivatives

Type

Integer

Values

-1,0
1
2
3

Note

Symbolic mode differentiation for the second order derivatives is only available when
XSLP_JACOBIAN is set to symbolic mode.

Default value-1

See also

XSLP_DERIVATIVES, XSLP_HESSIAN

automatic selection
numerical derivatives (ﬁnite difference)symbolic differentiation
automatic differentiationXSLP_LINQUADBR
Description

Use linear and quadratic constraints and objective function to further reduce bounds on all
variables

Type

Integer

Values

-1
0
1

Note

While bound reduction is effective when performed on nonlinear, nonquadratic constraints
and objective function, it can be useful to obtain tightened bounds from linear and quadratic
constraints, as the corresponding variables may appear in other nonlinear constraints. This
option then allows for a slightly more expensive bound reduction procedure, at the beneﬁt offurther reduction in the problem’s bounds.

Default value-1

See also

XSLP_PRESOLVEOPS, XSLP_PROBING

automatic selection
disableenableXSLP_LOG
Description

Level of printing during SLP iterations

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

184

Control Parameters

ValuesReference

-1
0
1
2
3
4
5

none
minimalnormal: iteration, penalty vectors
omit from convergence log any variables which have converged
omit from convergence log any variables which have already converged (except
variables on step bounds)
include all variables in convergence log
include user function call communications in the log

Default value0

Affects routinesXSLPmaxim, XSLPminimXSLP_LSITERLIMIT
Description

Number of iterations in the line search

Type

Integer

Notes

The line search attempts to reﬁne the step size suggested by the trust region step bounds.
The line search is a local method; the control sets a maximum on the number of model
evaluations during the line search.

Default value0

See also

XSLP_LSPATTERNLIMIT, XSLP_LSSTART, XSLP_LSZEROLIMIT, XSLP_FILTER

Affects routinesXSLPmaxim, XSLPminimXSLP_LSPATTERNLIMIT
Description

Number of iterations in the pattern search preceding the line search

Type

Integer

Notes

When positive, deﬁnes the number of samples taken along the step size suggested by thetrust region step bounds before initiating the line search. Useful for highly non-convex
problems.

Default value0

See also

XSLP_LSITERLIMIT, XSLP_LSSTART, XSLP_LSZEROLIMIT, XSLP_FILTER

Affects routinesXSLPmaxim, XSLPminimXSLP_LSSTART
Description

Iteration in which to active the line search

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

185

Control Parameters

Reference

Notes
Default value

8

See also

XSLP_LSITERLIMIT, XSLP_LSPATTERNLIMIT, XSLP_LSZEROLIMIT, XSLP_FILTER

Affects routinesXSLPmaxim, XSLPminimXSLP_LSZEROLIMIT
Description

Maximum number of zero length line search steps before line search is deactivatedType

Integer

Notes

When the line search repeatedly returns a zero step size, counteracted by bits set on
XSLP_FILTER, the effort spent in line search is redundant, and line search will be deactivatedafter XSLP_LSZEROLIMIT consecutive such iteration.

Default value

5

See also

XSLP_LSITERLIMIT, XSLP_LSPATTERNLIMIT, XSLP_LSSTART, XSLP_FILTER

Affects routinesXSLPmaxim, XSLPminimXSLP_MAXTIME
Description

The maximum time in seconds that the SLP optimization will run before it terminates

Type

Integer

Notes

The (elapsed) time is measured from the beginning of the ﬁrst SLP optimization.
If XSLP_MAXTIME is negative, Xpress NonLinear will terminate after (-XSLP_MAXTIME)
seconds. If it is positive, Xpress NonLinear will terminate in MISLP after XSLP_MAXTIME
seconds or as soon as an integer solution has been found thereafter.

Default value0

Affects routinesXSLPglobal, XSLPmaxim, XSLPminimXSLP_MIPALGORITHM
Description

Bitmap describing the MISLP algorithms to be used

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

186

Control Parameters

ValuesReference

Bit

Meaning

0
2
3
4
5
6
7

Solve initial SLP to convergence.
Relax step bounds according to XSLP_MIPRELAXSTEPBOUNDS after initial node.
Fix step bounds according to XSLP_MIPFIXSTEPBOUNDS after initial node.
Relax step bounds according to XSLP_MIPRELAXSTEPBOUNDS at each node.
Fix step bounds according to XSLP_MIPFIXSTEPBOUNDS at each node.
Limit iterations at each node to XSLP_MIPITERLIMIT.
Relax step bounds according to XSLP_MIPRELAXSTEPBOUNDS after MIP solution isfound.
Fix step bounds according to XSLP_MIPFIXSTEPBOUNDS after MIP solution isfound.
Use MIP at each SLP iteration instead of SLP at each node.
Use MIP on converged SLP solution and then SLP on the resulting MIP solution.

8
9
10
Notes

XSLP_MIPALGORITHM determines the strategy of XSLPglobal for solving MINLP problems.
The recommended approach is to solve the problem ﬁrst without reference to the global
variables. This can be handled automatically by setting bit 0 of XSLP_MIPALGORITHM; ifdone manually, then optimize using the "l" option to prevent the Optimizer presolve fromchanging the problem.
Some versions of the optimizer re-run the initial node as part of the global search; it ispossible to initiate a new SLP optimization at this point by relaxing or ﬁxing step bounds (usebits 2 and 3). If step bounds are ﬁxed for a class of variable, then the variables in that classwill not change their value in any child node.
At each node, it is possible to relax or ﬁx step bounds. It is recommended that step bounds
are relaxed, so that the new problem can be solved starting from its parent, but without undue
restrictions cased by step bounding (use bit 4). Exceptionally, it may be preferable to restrict
the freedom of child nodes by relaxing fewer types of step bound or ﬁxing the values of someclasses of variable (use bit 5).
When the optimal node has been found, it is possible to ﬁx the global variables and thenre-optimize with SLP. Step bounds can be relaxed or ﬁxed for this optimization as well (usebits 7 and 8).
Although it is ultimately necessary to solve the optimal node to convergence, individual nodes
can be truncated after XSLP_MIPITERLIMIT SLP iterations. Set bit 6 to activate this feature.
The normal MISLP algorithm uses SLP at each node. One alternative strategy is to use the
MIP optimizer for solving each SLP iteration. Set bit 9 to implement this strategy ("MIP within
SLP").
Another strategy is to solve the problem to convergence ignoring the nature of the global
variables. Then, ﬁxing the linearization, use MIP to ﬁnd the optimal setting of the global
variables. Then, ﬁxing the global variables, but varying the linearization, solve to convergence.
Set bit 10 to implement this strategy ("SLP then MIP").
For mode details about MISLP algorithms and strategies, see the separate section.
The following constants are provided for setting these bits:

Fair Isaac Corporation Conﬁdential and Proprietary Information

187

Control Parameters

Reference

Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8
Setting bit 9
Setting bit 10
Setting bit 11

XSLP_MIPINITIALSLPXSLP_MIPFINALSLPXSLP_MIPINITIALRELAXSLPXSLP_MIPINITIALFIXSLPXSLP_MIPNODERELAXSLPXSLP_MIPNODEFIXSLPXSLP_MIPNODELIMITSLPXSLP_MIPFINALRELAXSLPXSLP_MIPFINALFIXSLPXSLP_MIPWITHINSLPXSLP_SLPTHENMIPXSLP_NOFINALROUNDING

Default value

17 (bits 0 and4 are set)

Affects routinesXSLPglobal

See also

XSLP_ALGORITHM, XSLP_MIPFIXSTEPBOUNDS, XSLP_MIPITERLIMIT,XSLP_MIPRELAXSTEPBOUNDSXSLP_MIPCUTOFFCOUNT
Description

Number of SLP iterations to check when considering a node for cutting off

TypeInteger

Notes

If the objective function is worse by a deﬁned amount than the best integer solution obtainedso far, then the SLP will be terminated (and the node will be cut off). The node will be cut off
at the current SLP iteration if the objective function for the last XSLP_MIPCUTOFFCOUNT SLP
iterations are all worse than the best obtained so far, and the difference is greater thanXSLP_MIPCUTOFF_A and OBJ ∗ XSLP_MIPCUTOFF_R where OBJ is the best integer solution
obtained so far.
The test is not applied until at least XSLP_MIPCUTOFFLIMIT SLP iterations have been
carried out at the current node.

Default value

5

Affects routinesXSLPglobal

See also

XSLP_MIPCUTOFF_A, XSLP_MIPCUTOFF_R, XSLP_MIPCUTOFFLIMITXSLP_MIPCUTOFFLIMIT
Description

Number of SLP iterations to check when considering a node for cutting off

TypeInteger

Notes

If the objective function is worse by a deﬁned amount than the best integer solution obtainedso far, then the SLP will be terminated (and the node will be cut off). The node will be cut off
at the current SLP iteration if the objective function for the last XSLP_MIPCUTOFFCOUNT SLP
iterations are all worse than the best obtained so far, and the difference is greater thanXSLP_MIPCUTOFF_A and OBJ ∗ XSLP_MIPCUTOFF_R where OBJ is the best integer solution
obtained so far.

Fair Isaac Corporation Conﬁdential and Proprietary Information

188

Control Parameters

Reference

The test is not applied until at least XSLP_MIPCUTOFFLIMIT SLP iterations have been
carried out at the current node.
Default value

10

Affects routinesXSLPglobal

See also

XSLP_MIPCUTOFF_A, XSLP_MIPCUTOFF_R, XSLP_MIPCUTOFFCOUNTXSLP_MIPDEFAULTALGORITHM
Description

Default algorithm to be used during the global search in MISLP

Type

IntegerNote

The default algorithm used within SLP during the MISLP optimization can be set using
XSLP_MIPDEFAULTALGORITHM. It will not necessarily be the same as the one best suited tothe initial SLP optimization.

Default value

3 (primal simplex)

Affects routinesXSLPglobal

See also

XPRS_DEFAULTALG, XSLP_MIPALGORITHM

XSLP_MIPFIXSTEPBOUNDS
Description

Bitmap describing the step-bound ﬁxing strategy during MISLP

Type

Integer

ValuesBit

Meaning0
1
2
3

Fix step bounds on structural SLP variables which are not in coefﬁcients.
Fix step bounds on all structural SLP variables.
Fix step bounds on SLP variables appearing only in coefﬁcients.
Fix step bounds on SLP variables appearing in coefﬁcients.

Note

At any node (including the initial and optimal nodes) it is possible to ﬁx the step bounds ofclasses of variables so that the variables themselves will not change. This may help withconvergence, but it does increase the chance of a local optimum because of excessive
artiﬁcial restrictions on the variables.

Default value0

Affects routinesXSLPglobal

See also

XSLP_MIPALGORITHM, XSLP_MIPRELAXSTEPBOUNDSFair Isaac Corporation Conﬁdential and Proprietary Information

189

Control Parameters

ReferenceXSLP_MIPITERLIMIT
Description

Maximum number of SLP iterations at each nodeType

IntegerNote

If bit 6 of XSLP_MIPALGORITHM is set, then the number of iterations at each node will belimited to XSLP_MIPITERLIMIT.

Default value0

Affects routinesXSLPglobal

See also

XSLP_ITERLIMIT, XSLP_MIPALGORITHM

XSLP_MIPLOG
Description

Frequency with which MIP status is printed

Type

IntegerNote

By default (zero or negative value) the MIP status is printed after syncronization points. If
XSLP_MIPLOG is set to a positive integer, then the current MIP status (node number, bestvalue, best bound) is printed every XSLP_MIPLOG nodes.

Default value

0 (deterministic logging)

Affects routinesXSLPglobal

See also

XSLP_LOG, XSLP_SLPLOGXSLP_MIPOCOUNT
Description

Number of SLP iterations at each node over which to measure objective function variation

Type

IntegerNote

The objective function test for MIP termination is applied only when step bounding has been
applied (or XSLP_SBSTART SLP iterations have taken place if step bounding is not beingused). The node will be terminated at the current SLP iteration if the range of the objectivefunction values over the last XSLP_MIPOCOUNT SLP iterations is within XSLP_MIPOTOL_A or
within OBJ ∗ XSLP_MIPOTOL_R where OBJ is the average value of the objective function overthose iterations.

Default value

5

Affects routinesXSLPglobal

See also

XSLP_MIPOTOL_A XSLP_MIPOTOL_R XSLP_SBSTART

Fair Isaac Corporation Conﬁdential and Proprietary Information

190

Control Parameters

ReferenceXSLP_MIPRELAXSTEPBOUNDS
Description

Bitmap describing the step-bound relaxation strategy during MISLP

Type

Integer

ValuesBit

Meaning0
1
2
3

Relax step bounds on structural SLP variables which are not in coefﬁcients.
Relax step bounds on all structural SLP variables.
Relax step bounds on SLP variables appearing only in coefﬁcients.
Relax step bounds on SLP variables appearing in coefﬁcients.

Note

At any node (including the initial and optimal nodes) it is possible to relax the step bounds ofclasses of variables so that the variables themselves are completely free to change. This mayhelp with ﬁnding a global optimum, but it may also increase the solution time, because more
SLP iterations are necessary at each node to obtain a converged solution.

Default value

15 (relax all types)

Affects routinesXSLPglobal

See also

XSLP_MIPALGORITHM, XSLP_MIPFIXSTEPBOUNDSXSLP_MULTISTART
Description

The multistart master control. Deﬁnes if the multistart search is to be initiated, or if only thebaseline model is to be solved.

Type

Integer

Values

-1
0
1

Note

By default, the multistart search will always be initiated if multistart jobs have been added tothe problem. The (original) base problem is not part of the multisearch job pool. To make itso, add an job with no extra settings (template job). It might be useful to load multiple
template jobs, and customize them from callbacks.

Default value-1

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTART_MAXSOLVES, XSLP_MULTISTART_MAXTIME

Depends on if any multistart jobs have been added.
Multistart is off.
Multistart is on.

XSLP_MULTISTART_MAXSOLVES
Description

The maximum number of jobs to create during the multistart search.

Fair Isaac Corporation Conﬁdential and Proprietary Information

191

Control Parameters

Reference

Type

Integer

Note

This control can be increased on the ﬂy during the mutlistart search: for example, if a job gets
refused by a user callback, the callback may increase this limit to account for the rejected job.

Default value

0 (no upper limit)

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTART, XSLP_MULTISTART_MAXTIMEXSLP_MULTISTART_MAXTIME
Description

The maximum total time to be spent in the mutlistart search.

Type

IntegerNote

XSLP_MAXTIME applies on a per job instance basis. There will be some time spent even after
XSLP_MULTISTART_MAXTIME has elapsed, while the running jobs get terminated and theirresults collected.

Default value

0 (no upper limit)

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTART, XSLP_MULTISTART_MAXSOLVESXSLP_MULTISTART_POOLSIZE
Description

The maximum number of problem objects allowed to pool up before synchronization in thedeterministic multistart.

Type

Integer

Default value

2

Note

Deterministic multistart is ensured by guaranteeing that the multistart solve results areevaluated in the same order every time. Solves that ﬁnish too soon can be pooled until all
earlier started solves ﬁnish, allowing the system to start solving other multistart instances in
the meantime on idle threads. Larger pool sizes will provide better speedups, but will requirelarger amounts of memory. Positive values are interpreted as a multiplier on the maximum
number of active threads used, while negative values are interpreted as an absolute limit (andthe absolute value is used). A value of zero will mean no result pooling.

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTART, XSLP_DETERMINISTIC

Fair Isaac Corporation Conﬁdential and Proprietary Information

192

Control Parameters

ReferenceXSLP_MULTISTART_SEED
Description

Random seed used for the automatic generation of initial point when loading multistart
presets

Type

Integer

Default value0

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTARTXSLP_MULTISTART_THREADS
Description

The maximum number of threads to be used in multistartType

Integer

Default value

-1

Note

The current hard upper limit on the number of threads to be sued in multistart is 64.

Affects routinesXSLPminim, XSLPmaxim

See also

XSLP_MULTISTARTXSLP_OCOUNT
Description

Number of SLP iterations over which to measure objective function variation for static
objective (2) convergence criterion

Type

Integer

Note

The static objective (2) convergence criterion does not measure convergence of individual
variables. Instead, it measures the signiﬁcance of the changes in the objective function overrecent SLP iterations. It is applied when all the variables interacting with active constraints(those that have a marginal value of at least XSLP_MVTOL) have converged. The rationale isthat if the remaining unconverged variables are not involved in active constraints and if theobjective function is not changing signiﬁcantly between iterations, then the solution is
more-or-less practical.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_OCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_OTOL_A
then the problem has converged on the absolute static objective (2) convergence criterion.
The static objective function (2) test is applied only if XSLP_OCOUNT is at least 2.

Fair Isaac Corporation Conﬁdential and Proprietary Information

193

Control Parameters

Reference

Default value

5

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_OTOL_A XSLP_OTOL_R

XSLP_PENALTYINFOSTART
Description

Iteration from which to record row penalty information

Type

Integer

Note

Information about the size (current and total) of active penalties of each row and the numberof times a penalty vector has been active is recorded starting at the SLP iteration number
given by XSLP_PENALTYINFOSTART.

Default value

3

XSLP_POSTSOLVE
Description

This control determines whether postsolving should be performed automaticallyType

Integer

Values0
1

Default value0

See also

XSLP_PRESOLVE

Do not automatically postsolve.
Postsolve automatically.

XSLP_PRESOLVE
Description

This control determines whether presolving should be performed prior to starting the mainalgorithm

Type

Integer

Values

0
1
2

Note

The Xpress NonLinear nonlinear presolve (which is carried out once, before augmentation) is
independent of the Optimizer presolve (which is carried out during each SLP iteration).

Default value

1

Affects routinesXSLPconstruct, XSLPpresolve

See also

XSLP_PRESOLVELEVEL, XSLP_PRESOLVEOPS, XSLP_REFORMULATE,XSLP_PRESOLVEPASSLIMITDisable SLP presolve.
Activate SLP presolve.
Low memory presolve. Original problem is not restored by postsolve and dual
solution may not be completely postsolved.

Fair Isaac Corporation Conﬁdential and Proprietary Information

194

Control Parameters

ReferenceXSLP_PRESOLVELEVEL
Description

This control determines the level of changes presolve may carry out on the problem

Type

Integer

ValuesXSLP_PRESOLVELEVEL_LOCALIZED Individual rows only presolve, no nonlinear
transformations.
XSLP_PRESOLVELEVEL_BASIC Individual rows and bounds only presolve, no nonlinear
transformations.
XSLP_PRESOLVELEVEL_LINEAR Presolve allowing changing problem dimension, nononlinear transformations.
XSLP_PRESOLVELEVEL_FULL Full presolve.

Note

XSLP_PRESOLVEOPS and XSLP_REFORMULATE controls the operations carried out inpresolve. XSLP_PRESOLVELEVEL controls how those operations may change the problem.

Default value

XSLP_PRESOLVELEVEL_FULL

Affects routinesXSLPconstruct, XSLPpresolve

See also

XSLP_PRESOLVE, XSLP_PRESOLVEOPS, XSLP_REFORMULATE,XSLP_PRESOLVEPASSLIMITXSLP_PRESOLVEOPS
Description

Bitmap indicating the SLP presolve actions to be taken

Type

Integer

Values

Bit
0
1
2
3
4
5
8
9
10
11

Note

The Xpress NonLinear nonlinear presolve (which is carried out once, before augmentation) is
independent of the Optimizer presolve (which is carried out during each SLP iteration).

Default value

24

Affects routinesXSLPconstruct, XSLPpresolve

See also

XSLP_PRESOLVELEVEL, XSLP_PRESOLVE, XSLP_PRESOLVEOPS,XSLP_PRESOLVEPASSLIMIT, XSLP_REFORMULATE

Meaning
Generic SLP presolve.
Explicitly ﬁx columns identiﬁed as ﬁxed to zero.
Explicitly ﬁx all columns identiﬁed as ﬁxed.
SLP bound tightening.
MISLP bound tightening.
Bound tightening based on function domains.
Do not presolve coefﬁcients.
Do not remove delta variables.
Avoid reductions that can not be dual postsolved.
Allow eliminations on determined variables.

Fair Isaac Corporation Conﬁdential and Proprietary Information

195

Control Parameters

ReferenceXSLP_PRESOLVEPASSLIMIT
Description

Maximum number of passes through the problem to improve SLP bounds

Type

Integer

Note

The Xpress NonLinear nonlinear presolve (which is carried out once, before augmentation) is
independent of the Optimizer presolve (which is carried out during each SLP iteration). The
procedure carries out a number of passes through the SLP problem, seeking to tighten
implied bounds or to identify ﬁxed values. XSLP_PRESOLVEPASSLIMIT can be used tochange the maximum number of passes carried out.

Default value

20

Affects routinesXSLPpresolve

See also

XSLP_PRESOLVEXSLP_PROBING
Description

This control determines whether probing on a subset of variables should be performed prior
to starting the main algorithm. Probing runs multiple times bound reduction in order to further
tighten the bounding box.

Type

Integer

Values

-1
0
1
2
3
4
5

Automatic.
Disable SLP probing.
Activate SLP probing only on binary variables.
Activate SLP probing only on binary or unbounded integer variables.
Activate SLP probing only on binary or integer variables.
Activate SLP probing only on binary, integer variables, and unbounded continuous
variables.
Activate SLP probing on any variable.

Default value-1: XSLP sets the probing level based on the problem size

Note

The Xpress NonLinear nonlinear probing, which is carried out once, is independent of the
Optimizer presolve (which is carried out during each SLP iteration). The probing level allows
for probing on an expanding set of variables, allowing for probing on all variables (level 5) or
only those for which probing is more likely to be useful (binary variables).

Affects routinesXSLPpresolve

See also

XSLP_PRESOLVEOPS,XSLP_REFORMULATE
Description

Controls the problem reformulations carried out before augmentation. This allows SLP to
take advantage of dedicated algorithms for special problem classes.

Fair Isaac Corporation Conﬁdential and Proprietary Information

196

Control Parameters

Reference

Type

Integer

Values

Bit
0
1
2
3
4

Default value-1: All structures are checked against reformulation

Note

The reformulation is part of XSLP presolve, and is only carried out if XSLP_PRESOLVE isnonzero. The following constants are provided for setting these bits:
Setting bit 0 XSLP_REFORMULATE_SLP2QP
Setting bit 1 XSLP_REFORMULATE_QP2SLP
Setting bit 2 XSLP_REFORMULATE_SLP2QCQP
Setting bit 3 XSLP_REFORMULATE_QCQP2SLP
Setting bit 4 XSLP_REFORMULATE_QPSOLVE

Affects routinesXSLPconstruct, XSLPminim, XSLPmaxim, XSLPreminim, XSLPremaxim,
XSLPnlpoptimize, XSLPglobal

Meaning
Solve convex quadratic objectives using the XPRS library .
Convert non-convex quadratic objectives to SLP constructs .
Solve convex quadratic constraints using the XPRS library.
Convert non-convex QCQP constraints to SLP constructs.
Convexity of a quadratic only problem may be checked by calling the optimizer tosolve the instance.

XSLP_SAMECOUNT
Description

Number of steps reaching the step bound in the same direction before step bounds are
increased

Type

IntegerNote

If step bounding is enabled, the step bound for a variable will be increased if successivechanges are in the same direction. More precisely, if there are XSLP_SAMECOUNT successivechanges reaching the step bound and in the same direction for a variable, then the stepbound (B) for the variable will be reset to
B ∗ XSLP_EXPAND.

Default value

3

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_EXPANDXSLP_SAMEDAMP
Description

Number of steps in same direction before damping factor is increased

Type

IntegerNote

If dynamic damping is enabled, the damping factor for a variable will be increased if
successive changes are in the same direction. More precisely, if there are XSLP_SAMEDAMP
successive changes in the same direction for a variable, then the damping factor (D) for thevariable will be reset toD ∗ XSLP_DAMPEXPAND + XSLP_DAMPMAX ∗ (1 – XSLP_DAMPEXPAND)

Fair Isaac Corporation Conﬁdential and Proprietary Information

197

Control Parameters

Reference

Default value3

See also

Xpress-SLP Solution Process, XSLP_ALGORITHM, XSLP_DAMP, XSLP_DAMPMAX

Affects routinesXSLPmaxim, XSLPminimXSLP_SBROWOFFSET
Description

Position of ﬁrst character of SLP variable name used to create name of SLP lower and upper
step bound rows

Type

Integer

Note

During augmentation, a delta vector is created for each SLP variable. Step bounds areprovided for each delta variable, either using explicit bounds, or by using rows to provide
lower and upper bounds. If such rows are used, they are created with names derived from thecorresponding SLP variable. Customized naming is possible using XSLP_SBLOROWFORMAT
and XSLP_SBUPROWFORMAT to deﬁne a format and XSLP_SBROWOFFSET to deﬁne the ﬁrst
character (counting from zero) of the variable name to be used.

Default value0

Affects routinesXSLPconstruct

See also

XSLP_SBLOROWFORMAT, XSLP_SBUPROWFORMATXSLP_SBSTART
Description

SLP iteration after which step bounds are ﬁrst applied

Type

IntegerNote

If step bounds are used, they can be applied for the whole of the SLP optimization process, orstarted after a number of SLP iterations. In general, it is better not to apply step bounds fromthe start unless one of the following applies:(1) the initial estimates are known to be good, and explicit values can be provided for initial
step bounds on all variables; or(2) the problem is unbounded unless all variables are step-bounded.

Default value

8

Affects routinesXSLPmaxim, XSLPminimXSLP_SCALE
Description

When to re-scale the SLP problem

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

198

Control Parameters

ValuesReference

0
1
2
3
4
5
6

No re-scaling.
Re-scale every SLP iteration up to XSLP_SCALECOUNT iterations after the end of
barrier optimization.
Re-scale every SLP iteration up to XSLP_SCALECOUNT iterations in total.
Re-scale every SLP iteration until primal simplex is automatically invoked.
Re-scale every SLP iteration.
Re-scale every XSLP_SCALECOUNT SLP iterations.
Re-scale every XSLP_SCALECOUNT SLP iterations after the end of barrier
optimization.

Note

During the SLP optimization, matrix entries can change considerably in magnitude, even when
the formulae in the coefﬁcients are not very nonlinear. Re-scaling of the matrix can reduce
numerical errors, but may increase the time taken to achieve convergence.

Default value

1

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SCALECOUNTXSLP_SCALECOUNT
Description

Iteration limit used in determining when to re-scale the SLP matrix

Type

Integer

Notes

If XSLP_SCALE is set to 1 or 2, then XSLP_SCALECOUNT determines the number of iterations(after the end of barrier optimization or in total) in which the matrix is automatically re-scaled.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SCALEXSLP_SOLVER
Description

First order differentiation mode when using analytical derivatives

Type

Integer

Values

-1
0
1

Note

The presence of Knitro is detected automatically. Knitro can be used to solve any problem
loaded into XSLP, independently from how the problem was loaded. XSLP_SOLVER is set toautomatic, XSLP will be selected if any SLP speciﬁc construct has been loaded (these are
ignored if Knitro is selcetd manually).

Default value-1

automatic selection, based on model characteristics and solver availability
use Xpress-SLP (always available)
use Knitro if available

Fair Isaac Corporation Conﬁdential and Proprietary Information

199

Control Parameters

ReferenceXSLP_SLPLOG
Description

Frequency with which SLP status is printed

Type

IntegerNote

If XSLP_LOG is set to zero (minimal logging) then a nonzero value for XSLP_SLPLOG deﬁnes
the frequency (in SLP iterations) when summary information is printed out.

Default value

1

Affects routinesXSLPglobal, XSLPmaxim, XSLPminim

See also

XSLP_LOG, XSLP_MIPLOGXSLP_STOPOUTOFRANGE
Description

Stop optimization and return error code if internal function argument is out of range

Type

IntegerNote

If XSLP_STOPOUTOFRANGE is set to 1, then if an internal function receives an argument which
is out of its allowable range (for example, LOG of a negative number), an error code is set andthe optimization is terminated.

Default value0

Affects routinesXSLPevaluatecoef, XSLPevaluateformula XSLPmaxim, XSLPminimXSLP_THREADS
Description

Default number of threads to be used

Type

Integer

Note

Overall thread control value, used to determine the number of threads used where parallel
calculations are possible.

Default value-1 (automatically determined)

Affects routinesXSLPmaxim, XSLPmaxim

See also

XSLP_CALCTHREADS, XSLP_MULTISTART_THREADS,XSLP_TIMEPRINT
Description

Print additional timings during SLP optimization

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

200

Control Parameters

Reference

Note

Date and time printing can be useful for identifying slow procedures during the SLP
optimization. Setting XSLP_TIMEPRINT to 1 prints times at additional points during the
optimization.

Default value0

Affects routinesXSLPmaxim, XSLPminimXSLP_THREADSAFEUSERFUNC
Description

Deﬁnes if user functions are allowed to be called in parallelType

Integer

Note

Date and time printing can be useful for identifying slow procedures during the SLP
optimization. Setting XSLP_TIMEPRINT to 1 prints times at additional points during the
optimization.

Values0
1

Default value

0 (no parallel user function calls)

Affects routinesXSLPmaxim, XSLPminim

user function are not thread safe, and will not be called in parallel
user functions are thread safe, and may be called in parallelXSLP_TRACEMASKOPS
Description

Controls the information printed for XSLP_TRACEMASK. The order in which the information isprinted is determined by the order of bits in XSLP_TRACEMASKOPS.

Type

Integer

Values

Bit
0
1
2
3
4
5
6
7
8
9
10
11
12
13

Default value-1: all bits are set

Meaning
The variable name is used as a mask, not as an exact ﬁt.
Use mask to trace rows.
Use mask to trace columns.
Use mask to trace cascaded SLP variables.
Show row / column category.
Trace slack values.
Trace dual values.
Trace row penalty multiplier.
Trace variable values (as returned by the lineariation).
Trace reduced costs.
Trace slp value (value used in linearization and cascaded).
Trace step bounds.
Trace convergence status.
Trace line search.

Fair Isaac Corporation Conﬁdential and Proprietary Information

201

Control Parameters

Note

Reference

The following constants are provided for setting these bits:
Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5
Setting bit 6
Setting bit 7
Setting bit 8
Setting bit 9
Setting bit 10
Setting bit 11
Setting bit 12
Setting bit 13

Affects routinesXSLP_TRACEMASK_GENERALFITXSLP_TRACEMASK_ROWSXSLP_TRACEMASK_COLS
XSLP_TRACEMASK_CASCADEXSLP_TRACEMASK_TYPE
XSLP_TRACEMASK_SLACKXSLP_TRACEMASK_DUALXSLP_TRACEMASK_WEIGHTXSLP_TRACEMASK_SOLUTIONXSLP_TRACEMASK_REDUCEDCOSTXSLP_TRACEMASK_SLPVALUEXSLP_TRACEMASK_STEPBOUNDXSLP_TRACEMASK_CONVERGEXSLP_TRACEMASK_LINESEARCHXSLPminim, XSLPmaxim, XSLPreminim, XSLPremaxim, XSLPnlpoptimize, XSLPglobal

XSLP_UNFINISHEDLIMIT
Description

Number of times within one SLP iteration that an unﬁnished LP optimization will be continued

Type

Integer

Note

If the optimization of the current linear approximation terminates with an "unﬁnished" status(for example, because it has reached maximum iterations), Xpress-SLP will attempt tocontinue using the primal simplex algorithm. This process will be repeated for up to
XSLP_UNFINISHEDLIMIT successive LP optimizations within any one SLP iteration. If thelimit is reached, Xpress-SLP will terminate with XSLP_STATUS set to XSLP_LPUNFINISHED

Default value

3

Affects routinesXSLPglobal, XSLPmaxim, XSLPminimXSLP_UPDATEOFFSET
Description

Position of ﬁrst character of SLP variable name used to create name of SLP update row

TypeInteger

Note

During augmentation, one or more delta vectors are created for each SLP variable. The valuesof these are linked to that of the variable through an update row which is created as part of
the augmentation procedure. Update rows are created with names derived from thecorresponding SLP variable. Customized naming is possible using XSLP_UPDATEFORMAT todeﬁne a format and XSLP_UPDATEOFFSET to deﬁne the ﬁrst character (counting from zero)of the variable name to be used.

Default value0

Affects routinesXSLPconstruct

See also

XSLP_UPDATEFORMAT

Fair Isaac Corporation Conﬁdential and Proprietary Information

202

Control Parameters

ReferenceXSLP_VCOUNT
Description

Number of SLP iterations over which to measure static objective (3) convergenceType

Integer

Note

The static objective (3) convergence criterion does not measure convergence of individual
variables, and in fact does not in any way imply that the solution has converged. However, it issometimes useful to be able to terminate an optimization once the objective function appears
to have stabilized. One example is where a set of possible schedules are being evaluated andinitially only a good estimate of the likely objective function value is required, to eliminate theworst candidates.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_VCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_VTOL_A
then the problem has converged on the absolute static objective function (3) criterion.
The static objective function (3) test is applied only if after at least XSLP_VLIMIT +XSLP_SBSTART SLP iterations have taken place and only if XSLP_VCOUNT is at least 2.
Where step bounding is being used, this ensures that the test is not applied until after stepbounding has been introduced.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SBSTART, XSLP_VLIMIT, XSLP_VTOL_A, XSLP_VTOL_R

XSLP_VLIMIT
Description

Number of SLP iterations after which static objective (3) convergence testing starts

Type

Integer

Note

The static objective (3) convergence criterion does not measure convergence of individual
variables, and in fact does not in any way imply that the solution has converged. However, it issometimes useful to be able to terminate an optimization once the objective function appears
to have stabilized. One example is where a set of possible schedules are being evaluated andinitially only a good estimate of the likely objective function value is required, to eliminate theworst candidates.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_VCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_VTOL_A
then the problem has converged on the absolute static objective function (3) criterion.

Fair Isaac Corporation Conﬁdential and Proprietary Information

203

Control Parameters

Reference

The static objective function (3) test is applied only if after at least XSLP_VLIMIT +XSLP_SBSTART SLP iterations have taken place and only if XSLP_VCOUNT is at least 2.
Where step bounding is being used, this ensures that the test is not applied until after stepbounding has been introduced.
Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_SBSTART, XSLP_VCOUNT, XSLP_VTOL_A, XSLP_VTOL_R

XSLP_WCOUNT
Description

Number of SLP iterations over which to measure the objective for the extended convergence
continuation criterion

Type

IntegerNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
The extended convergence continuation criterion is applied after a converged solution has
been found where at least one variable has converged on extended criteria and is at its stepbound limit. The extended convergence continuation test measures whether any
improvement is being achieved when additional SLP iterations are carried out. If not, then thelast converged solution will be restored and the optimization will stop.
For a maximization problem, the improvement in the objective function at the current iterationcompared to the objective function at the last converged solution is given by:
δObj = Obj – LastConvergedObj
For a minimization problem, the sign is reversed.
If δObj > XSLP_WTOL_A andδObj > ABS(ConvergedObj) ∗ XSLP_WTOL_R then the solution is deemed to have a signiﬁcantly
better objective function value than the converged solution.
When a solution is found which converges on extended criteria and with active step bounds,
the solution is saved and SLP optimization continues until one of the following:(1) a new solution is found which converges on some other criterion, in which case the SLP
optimization stops with this new solution;(2) a new solution is found which converges on extended criteria and with active step bounds,
and which has a signiﬁcantly better objective function, in which case this is taken as the new
saved solution;(3) none of the XSLP_WCOUNT most recent SLP iterations has a signiﬁcantly better objectivefunction than the saved solution, in which case the saved solution is restored and the SLP
optimization stops.
If XSLP_WCOUNT is zero, then the extended convergence continuation criterion is disabled.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_WTOL_A, XSLP_WTOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

204

Control Parameters

ReferenceXSLP_XCOUNT
Description

Number of SLP iterations over which to measure static objective (1) convergenceType

IntegerNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would
improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
However, if the objective function has already been stable for several SLP iterations, thenthere is less likelihood of an improved result, and the converged solution can be accepted.
The static objective function (1) test measures the signiﬁcance of the changes in theobjective function over recent SLP iterations. It is applied when all the variables have
converged, but some have converged on extended criteria and at least one of these variables
is at its step bound. Because all the variables have converged, the solution is alreadyconverged but the fact that some variables are at their step bound limit suggests that theobjective function could be improved by going further.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_XCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_XTOL_A
then the objective function is deemed to be static according to the absolute static objectivefunction (1) criterion.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_XTOL_R
then the objective function is deemed to be static according to the relative static objectivefunction (1) criterion.
The static objective function (1) test is applied only until XSLP_XLIMIT SLP iterations havetaken place. After that, if all the variables have converged on strict or extended criteria, thesolution is deemed to have converged.
If the objective function passes the relative or absolute static objective function (1) test thenthe solution is deemed to have converged.

Default value

5

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_XLIMIT, XSLP_XTOL_A, XSLP_XTOL_R

XSLP_XLIMIT
Description

Number of SLP iterations up to which static objective (1) convergence testing starts

Type

IntegerNote

It may happen that all the variables have converged, but some have converged on extended
criteria and at least one of these variables is at its step bound. This means that, at least in thelinearization, if the variable were to be allowed to move further the objective function would

Fair Isaac Corporation Conﬁdential and Proprietary Information

205

Control Parameters

Reference

improve. This does not necessarily imply that the same is true of the original problem, but it isstill possible that an improved result could be obtained by taking another SLP iteration.
However, if the objective function has already been stable for several SLP iterations, thenthere is less likelihood of an improved result, and the converged solution can be accepted.
The static objective function (1) test measures the signiﬁcance of the changes in theobjective function over recent SLP iterations. It is applied when all the variables have
converged, but some have converged on extended criteria and at least one of these variables
is at its step bound. Because all the variables have converged, the solution is alreadyconverged but the fact that some variables are at their step bound limit suggests that theobjective function could be improved by going further.
The variation in the objective function is deﬁned as
δObj = MAXIter (Obj) – MINIter (Obj)
where Iter is the XSLP_XCOUNT most recent SLP iterations and Obj is the corresponding
objective function value.
If ABS(δObj) ≤ XSLP_XTOL_A
then the objective function is deemed to be static according to the absolute static objectivefunction (1) criterion.
If ABS(δObj) ≤ AVGIter (Obj) ∗ XSLP_XTOL_R
then the objective function is deemed to be static according to the relative static objectivefunction (1) criterion.
The static objective function (1) test is applied only until XSLP_XLIMIT SLP iterations havetaken place. After that, if all the variables have converged on strict or extended criteria, thesolution is deemed to have converged.
If the objective function passes the relative or absolute static objective function (1) test thenthe solution is deemed to have converged.
Default value

100

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_XCOUNT, XSLP_XTOL_A, XSLP_XTOL_R

XSLP_ZEROCRITERION
Description

Bitmap determining the behavior of the placeholder deletion procedure

Type

Integer

Values

Bit
0
1
2
3
4
5

Note

Meaning(=1) Remove placeholders in nonbasic SLP variables(=2) Remove placeholders in nonbasic delta variables(=4) Remove placeholders in a basic SLP variable if its update row is nonbasic(=8) Remove placeholders in a basic delta variable if its update row is nonbasic andthe corresponding SLP variable is nonbasic(=16) Remove placeholders in a basic delta variable if the determining row for thecorresponding SLP variable is nonbasic(=32) Print information about zero placeholders

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.
The following constants are provided for setting these bits:

Fair Isaac Corporation Conﬁdential and Proprietary Information

206

Control Parameters

Reference

Setting bit 0
Setting bit 1
Setting bit 2
Setting bit 3
Setting bit 4
Setting bit 5

XSLP_ZEROCRTIERION_NBSLPVARXSLP_ZEROCRTIERION_NBDELTAXSLP_ZEROCRTIERION_SLPVARNBUPDATEROWXSLP_ZEROCRTIERION_DELTANBUPSATEROWXSLP_ZEROCRTIERION_DELTANBDRROWXSLP_ZEROCRTIERION_PRINT

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERIONCOUNT, XSLP_ZEROCRITERIONSTART, Management of zeroplaceholder entriesXSLP_ZEROCRITERIONCOUNT
Description

Number of consecutive times a placeholder entry is zero before being considered for deletion

Type

Integer

Note

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERION, XSLP_ZEROCRITERIONSTART, Management of zero placeholder
entriesXSLP_ZEROCRITERIONSTART
Description

SLP iteration at which criteria for deletion of placeholder entries are ﬁrst activated.

Type

Integer

Note

For an explanation of deletion of placeholder entries in the matrix see Management of zeroplaceholder entries.

Default value0

Affects routinesXSLPmaxim, XSLPminim

See also

XSLP_ZEROCRITERION, XSLP_ZEROCRITERIONCOUNT, Management of zero placeholder
entries

Fair Isaac Corporation Conﬁdential and Proprietary Information

207

Control Parameters

20.3

Reference

String control parametersXSLP_CVNAME
Description

Name of the set of character variables to be used

Type

String

Notes

This variable may be required for input from a ﬁle using XSLPreadprob if there is more than
one set of character variables in the ﬁle. If no name is set, then the ﬁrst set of character
variables will be used, and the name will be set accordingly.
This variable may also be required for output using XSLPwriteprob where character
variables are included in the problem. If it is not set, then a default name will be used.

Set by routinesXSLPreadprob

Default valuenone

Affects routinesXSLPreadprob, XSLPwriteprob

See also

XSLP_IVNAME, XSLP_SBNAME, XSLP_TOLNAMEXSLP_DELTAFORMAT
Description

Formatting string for creation of names for SLP delta vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for delta vectors. The structure
follows the normal C-style printf form, and can contain printing characters plus one %s string.
This will be replaced by sequential characters from the name of the variable starting at
position XSLP_DELTAOFFSET.

Default value

pD_%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_DELTAOFFSETXSLP_ITERFALLBACKOPS
Description

Alternative LP level control values for numerically challengeing problems

Type

String

Notes

When set, this control provides alternative ways of solving a linearization called adaptive
iteration solves. This can be useful for numerically challenging problems that either solve to anon-satisfactory accuracy (relative to XSLP_FEASTOLTARGET) with the default solves, or that
can incorrectly report infeasibility or unboundedness. In such cases, the solve will try the

Fair Isaac Corporation Conﬁdential and Proprietary Information

208

Control Parameters

Reference

controls listed by XSLP_ITERFALLBACKOPS until a satisfactory solution is found or all
options are exhausted.
The individual controls for each solve are separated by a comma (’,’), while the set of controls
for an attepmt by a colon (’:’) . Example: ’XPRS_DEFAULTALG=3 : XPRS_BARORDER = 2,
XPRS_PRESOVLE = 0’ will try primal in one solve, and the homogenous barrier with presolve
turned off in an other. Optimizer ﬂags are not inherited by the solve, so use
XPRS_DEFAULTALG for selecting an LP solver to use.
The resulting LP solves are carried out in a parallel manner, using
XSLP_MULTISTART_THREADS number of threads.
The result of the adaptive solves are always deterministic.
Once a satisfactory solution is found, remaining solves are progressed only as far asnecessary to guarantee determinism, so it is beneﬁcial to list more promising control sets
ﬁrst.
Default valuenone

Affects routinesXSLPminim, XSLPmaxim, XSLPnlpoptimize

See also

XSLP_FEASTOLTARGET,XSLP_IVNAME
Description

Name of the set of initial values to be used

Type

String

Notes

This variable may be required for input from a ﬁle using XSLPreadprob if there is more than
one set of initial values in the ﬁle. If no name is set, then the ﬁrst set of initial values will be
used, and the name will be set accordingly.
This variable may also be required for output using XSLPwriteprob where initial values areincluded in the problem. If it is not set, then a default name will be used.

Set by routinesXSLPreadprob

Default valuenone

Affects routinesXSLPreadprob, XSLPwriteprob

See also

XSLP_CVNAME, XSLP_SBNAME, XSLP_TOLNAMEXSLP_MINUSDELTAFORMAT
Description

Formatting string for creation of names for SLP negative penalty delta vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for negative penalty delta
vectors. The structure follows the normal C-style printf form, and can contain printing
characters plus one %s string. This will be replaced by sequential characters from the nameof the variable starting at position XSLP_DELTAOFFSET.

Default value

pD-%s
where p is a unique preﬁx for names in the current problem

Fair Isaac Corporation Conﬁdential and Proprietary Information

209

Control Parameters

Reference

Affects routinesXSLPconstruct

See also

XSLP_DELTAOFFSETXSLP_MINUSERRORFORMAT
Description

Formatting string for creation of names for SLP negative penalty error vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for negative penalty error
vectors. The structure follows the normal C-style printf form, and can contain printing
characters plus one %s string. This will be replaced by sequential characters from the nameof the variable starting at position XSLP_ERROROFFSET.

Default value

pE-%s
where p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_ERROROFFSETXSLP_PENALTYCOLFORMAT
Description

Formatting string for creation of the names of the SLP penalty transfer vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for the penalty transfer vectors
which transfer penalty costs into the objective. The structure follows the normal C-style printf
form, and can contain printing characters plus one %s string. This will be replaced by "DELT"
for the penalty delta transfer vector and "ERR" for the penalty error transfer vector.

Default value

pPC_%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

XSLP_PENALTYROWFORMAT
Description

Formatting string for creation of the names of the SLP penalty rows

Type

String

Note

This control can be used to create a speciﬁc naming structure for the penalty rows which
total the penalty costs for the objective. The structure follows the normal C-style printf form,and can contain printing characters plus one %s string. This will be replaced by "DELT" for the
penalty delta row and "ERR" for the penalty error row.

Default value

pPR_%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information

210

Control Parameters

ReferenceXSLP_PLUSDELTAFORMAT
Description

Formatting string for creation of names for SLP positive penalty delta vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for positive penalty delta
vectors. The structure follows the normal C-style printf form, and can contain printing
characters plus one %s string. This will be replaced by sequential characters from the nameof the variable starting at position XSLP_DELTAOFFSET.

Default value

pD+%s
where p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_DELTAOFFSETXSLP_PLUSERRORFORMAT
Description

Formatting string for creation of names for SLP positive penalty error vectors

Type

String

Note

This control can be used to create a speciﬁc naming structure for positive penalty error
vectors. The structure follows the normal C-style printf form, and can contain printing
characters plus one %s string. This will be replaced by sequential characters from the nameof the variable starting at position XSLP_ERROROFFSET.

Default value

pE+%s
where p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_ERROROFFSETXSLP_SBLOROWFORMAT
Description

Formatting string for creation of names for SLP lower step bound rows

Type

String

Note

This control can be used to create a speciﬁc naming structure for lower limits on step bounds
modeled as rows. The structure follows the normal C-style printf form, and can contain
printing characters plus one %s string. This will be replaced by sequential characters from thename of the variable starting at position XSLP_SBROWOFFSET.

Default value

pSB-%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_SBROWOFFSET

Fair Isaac Corporation Conﬁdential and Proprietary Information

211

Control Parameters

ReferenceXSLP_SBNAME
Description

Name of the set of initial step bounds to be used

Type

String

Notes

This variable may be required for input from a ﬁle using XSLPreadprob if there is more than
one set of initial step bounds in the ﬁle. If no name is set, then the ﬁrst set of initial stepbounds will be used, and the name will be set accordingly.
This variable may also be required for output using XSLPwriteprob where initial stepbounds are included in the problem. If it is not set, then a default name will be used.

Set by routinesXSLPreadprob

Default valuenone

Affects routinesXSLPreadprob, XSLPwriteprob

See also

XSLP_CVNAME, XSLP_IVNAME, XSLP_TOLNAMEXSLP_SBUPROWFORMAT
Description

Formatting string for creation of names for SLP upper step bound rows

Type

String

Note

This control can be used to create a speciﬁc naming structure for upper limits on step bounds
modeled as rows. The structure follows the normal C-style printf form, and can contain
printing characters plus one %s string. This will be replaced by sequential characters from thename of the variable starting at position XSLP_SBROWOFFSET.

Default value

pSB+%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_SBROWOFFSETXSLP_TOLNAME
Description

Name of the set of tolerance sets to be used

Type

String

Notes

This variable may be required for input from a ﬁle using XSLPreadprob if there is more than
one set of tolerance sets in the ﬁle. If no name is set, then the ﬁrst set of tolerance sets will be
used, and the name will be set accordingly.
This variable may also be required for output using XSLPwriteprob where tolerance sets
are included in the problem. If it is not set, then a default name will be used.

Set by routinesXSLPreadprob

Fair Isaac Corporation Conﬁdential and Proprietary Information

212

Control Parameters

Reference

Default valuenone

Affects routinesXSLPreadprob, XSLPwriteprob

See also

XSLP_CVNAME, XSLP_IVNAME, XSLP_SBNAMEXSLP_TRACEMASKDescription

Mask of variable or row names that are to be traced through the SLP iterates

Type

StringNotes

If the mask is nonempty, variables and rows matching the mask are listed after each SLP
iteration and each cascade, allowing for a convenient means to observe how certain variables
change through the iterates. This feasture is provided for tuning and model debugging
purposes. The actual information printed is controlled by XSLP_TRACEMASKOPS.
The string in the tracemask may contain several variable or row names, separated by awhitespace. Wildcards may also be used.

Default valuenone: no tracing

Affects routinesXSLPminim, XSLPmaxim, XSLPreminim, XSLPremaxim, XSLPnlpoptimize, XSLPglobal

See also

XSLP_TRACEMASKOPSXSLP_UPDATEFORMAT
Description

Formatting string for creation of names for SLP update rows

Type

String

Note

This control can be used to create a speciﬁc naming structure for update rows. The structure
follows the normal C-style printf form, and can contain printing characters plus one %s string.
This will be replaced by sequential characters from the name of the variable starting at
position XSLP_UPDATEOFFSET.

Default value

pU_%swhere p is a unique preﬁx for names in the current problem

Affects routinesXSLPconstruct

See also

XSLP_UPDATEOFFSET

20.4

Knitro controls
All Knitro controls are available with an ’X’ pre-tag. For example the Knitro integer control’KTR_PARAM_ALGORITHM’ can be set using XSLPsetintcontrol using the control ID deﬁned as’XKTR_PARAM_ALGORITHM’. Please refer to the Xpress Knitro manual for the description of the Knitro
controls.

Fair Isaac Corporation Conﬁdential and Proprietary Information

213

CHAPTER 21

Library functions and the programming interface
21.1

Counting
All Xpress NonLinear entities are numbered from 1. The 0th item is deﬁned, and is an empty entity of
the appropriate type. Therefore, whenever an Xpress NonLinear function returns a zero value, it meansthat there is no data of that type.
In parsed and unparsed function arrays, the indices always count from 1. This includes types
XSLP_VAR and XSLP_CONSTRAINT: the index is the matrix column or row index +1.
Note that for input of function arrays, types XSLP_COL and XSLP_ROW can be used, but will be
converted into standard XSLP_VAR or XSLP_CONSTRAINT references. When a function array isreturned from Xpress NonLinear, the XSLP_VAR or XSLP_CONSTRAINT type will always be used.

21.2

The Xpress NonLinear problem pointerXpress NonLinear uses the same concept as the Optimizer library, with a "pointer to a problem". The
optimizer problem must be initialized ﬁrst 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 fordestroying the underlying XPRSprob linear problem afterwards. For example:{...
XSLPdestroyprob(SLPprob);
XPRSdestroyprob(prob);
XSLPfree();
XPRSfree();...
}

Fair Isaac Corporation Conﬁdential and Proprietary Information

214

Library functions and the programming interface

Reference

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 ﬁleXSLPsave(XSLPprob prob1)
Save Xpress NonLinear data structures to ﬁle

21.3

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 Libraryfunctions XPRSloadlp or XPRSloadglobal. 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 thesame type, then use the corresponding XSLPadd... function.
It is possible to remove parts of the SLP strcutures with the various XSLPdel functions, andXSLPunconstruct can also be used to remove the augmentation.
Xpress NonLinear is compatible with the Xpress quadratic programming optimizer. XPRSloadqp and
XPRSloadqglobal can be used to load quadratic problems (or quadratically constrained problmes
using XPRSloadqcqp and XPRSloadqcqpglobal). 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 beneﬁcial 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.

21.4

Library functions
A large number of routines are available for Library users of Xpress NonLinear, ranging from simple

Fair Isaac Corporation Conﬁdential and Proprietary Information215

Library functions and the programming interface

Referenceroutines for the input and solution of problems from matrix ﬁles 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.
XSLPaddcoefs

Add non-linear coefﬁcients to the SLP problem

p. 221XSLPadddfs

Add a set of distribution factors

p. 223XSLPaddtolsets

Add sets of standard tolerance values to an SLP problem

p. 224XSLPadduserfunction Add user function deﬁnitions to an SLP problem.

p. 225XSLPaddvars

Add SLP variables deﬁned as matrix columns to an SLP problem

p. 226XSLPcalcslacks

Calculate the slack values for the provided solution in the non-linear
problem
p. 228XSLPcascade

Re-calculate consistent values for SLP variables based on the current
values of the remaining variables.
p. 229XSLPcascadeorder

Establish a re-calculation sequence for SLP variables with determiningrows.
p. 230XSLPchgcascadenlimit

Set a variable speciﬁc cascade iteration limit

XSLPchgccoef

Add or change a single matrix coefﬁcient using a character string for theformulap. 232XSLPchgcoef

Add or change a single matrix coefﬁcient using a parsed or unparsed
formulap. 233XSLPchgdeltatype

Changes the type of the delta assigned to a nonlinear variable

p. 234XSLPchgdf

Set or change a distribution factor

p. 235XSLPchgrowstatus

Change the status setting of a constraint

p. 236XSLPchgrowwt

Set or change the initial penalty error weight for a row

p. 237XSLPchgtolset

Add or change a set of convergence tolerances used for SLP variables
p. 238XSLPchgvar

Deﬁne a column as an SLP variable or change the characteristics andvalues of an existing SLP variable
p. 240XSLPconstruct

Create the full augmented SLP matrix and data structures, ready for
optimization
p. 242XSLPcopycallbacks

Copy the user-deﬁned callbacks from one SLP problem to another

XSLPcopycontrols

Copy the values of the control variables from one SLP problem to anotherp. 244XSLPcopyprob

Copy an existing SLP problem to anotherp. 245XSLPcreateprob

Create a new SLP problem

p. 246XSLPdelcoefs

Delete coefﬁcients from the current problem

p. 247XSLPdeltolsets

Delete tolerance sets from the current problem

p. 248XSLPdeluserfunction Delete a user function from the current problem

p. 249Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 231

p. 243216

Library functions and the programming interface

Reference

XSLPdelvars

Convert SLP variables to normal columns. Variables must not appear in
SLP structures
p. 250XSLPdestroyprob

Delete an SLP problem and release all the associated memory

p. 251XSLPevaluatecoef

Evaluate a coefﬁcient using the current values of the variables

p. 252XSLPevaluateformula Evaluate a formula using the current values of the variables

p. 253XSLPfixpenalties

Fixe the values of the error vectors

p. 254XSLPfreeFree any memory allocated by Xpress NonLinear and close any open
Xpress NonLinear ﬁlesp. 255XSLPgetbanner

Retrieve the Xpress NonLinear banner and copyright messages

XSLPgetccoef

Retrieve a single matrix coefﬁcient as a formula in a character string p. 257

XSLPgetcoefformula

Retrieve a single matrix coefﬁcient as a formula split into tokens

XSLPgetcoefs

Retrieve the list of positions of the nonlinear coefﬁcients in the problem
p. 259XSLPgetcolinfo

Get current column information.

p. 260XSLPgetdblattrib

Retrieve the value of a double precision problem attributep. 261XSLPgetdblcontrol

Retrieve the value of a double precision problem control

p. 262XSLPgetdf

Get a distribution factor

p. 263XSLPgetindex

Retrieve the index of an Xpress NonLinear entity with a given name p. 264

XSLPgetintattrib

Retrieve the value of an integer problem attributep. 265XSLPgetintcontrol

Retrieve the value of an integer problem control

p. 266XSLPgetlasterror

Retrieve the error message corresponding to the last Xpress NonLinear
error during an SLP run
p. 267XSLPgetptrattrib

Retrieve the value of a problem pointer attributep. 268XSLPgetrowinfo

Get current row information.

p. 269XSLPgetrowstatus

Retrieve the status setting of a constraint

p. 270XSLPgetrowwt

Get the initial penalty error weight for a row

p. 271XSLPgetslpsol

Obtain the solution values for the most recent SLP iteration

p. 272XSLPgetstrattrib

Retrieve the value of a string problem attribute

p. 273XSLPgetstrcontrol

Retrieve the value of a string problem control

p. 274XSLPgettolset

Retrieve the values of a set of convergence tolerances for an SLP problem
p. 275XSLPgetvar

Retrieve information about an SLP variable

XSLPglobal

Initiate the Xpress NonLinear mixed integer SLP (MISLP) algorithm p. 278

XSLPimportlibfunc

Imports a function from a library ﬁle to be called as a user function p. 279

XSLPinit

Initializes the Xpress NonLinear system

p. 280XSLPinterrupt

Interrupts the current SLP optimization

p. 281

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 256

p. 258

p. 276217

Library functions and the programming interface

Reference

XSLPitemname

Retrieves the name of an Xpress NonLinear entity or the value of a function
token as a character string.
p. 282XSLPloadcoefs

Load non-linear coefﬁcients into the SLP problem

p. 283XSLPloaddfs

Load a set of distribution factors

p. 285XSLPloadtolsets

Load sets of standard tolerance values into an SLP problem

p. 286XSLPloadvars

Load SLP variables deﬁned as matrix columns into an SLP problem p. 287

XSLPmaxim

Maximize an SLP problem

p. 289XSLPminim

Minimize an SLP problem

p. 290XSLPmsaddcustompreset A combined version of XSLPmsaddjob and XSLPmsaddpreset. The
preset described is loaded, topped up with the speciﬁc settings supplied
p. 291XSLPmsaddjob

Adds a multistart job to the multistart poolp. 292XSLPmsaddpreset

Loads a preset of jobs into the multistart job pool.

p. 293XSLPmsclear

Removes all scheduled jobs from the multistart job poolp. 294XSLPnlpoptimize

Maximize or minimize an SLP problem

p. 295XSLPpostsolve

Restores the problem to its pre-solve statep. 296XSLPpresolve

Perform a nonlinear presolve on the problem

p. 297XSLPprintevalinfo

Print a summary of any evaluation errors that may have occurred duringsolving a problem
p. 299XSLPprintmemory

Print the dimensions and memory allocations for a problem

XSLPreadprob

Read an Xpress NonLinear extended MPS format matrix from a ﬁle into an
SLP problem
p. 300XSLPreinitialize

Reset the SLP problem to match a just augmented system

p. 304XSLPremaxim

Continue the maximization of an SLP problem

p. 301XSLPreminim

Continue the minimization of an SLP problem

p. 302XSLPrestore

Restore the Xpress NonLinear problem from a ﬁle created by XSLPsave
p. 303XSLPsave

Save the Xpress NonLinear problem to ﬁlep. 305XSLPsaveas

Save the Xpress NonLinear problem to a named ﬁlep. 306XSLPscaling

Analyze the current matrix for largest/smallest coefﬁcients and ratios
p. 307

p. 298XSLPsetcbcascadeend Set a user callback to be called at the end of the cascading process, after
the last variable has been cascaded
p. 308XSLPsetcbcascadestart Set a user callback to be called at the start of the cascading process,before any variables have been cascaded
p. 309XSLPsetcbcascadevar Set a user callback to be called after each column has been cascaded
p. 310Fair Isaac Corporation Conﬁdential and Proprietary Information

218

Library functions and the programming interface

Reference

XSLPsetcbcascadevarfail Set a user callback to be called after cascading a column was not
successful
p. 311XSLPsetcbcoefevalerror Set a user callback to be called when an evaluation of a coefﬁcient
fails during the solvep. 312XSLPsetcbconstruct

Set a user callback to be called during the Xpress-SLP augmentation
process
p. 313XSLPsetcbdestroy

Set a user callback to be called when an SLP problem is about to be
destroyedp. 315XSLPsetcbdrcol

Set a user callback used to override the update of variables with small
determining column
p. 316XSLPsetcbintsol

Set a user callback to be called during MISLP when an integer solution is
obtained
p. 317XSLPsetcbiterend

Set a user callback to be called at the end of each SLP iteration

p. 318XSLPsetcbiterstart

Set a user callback to be called at the start of each SLP iteration

p. 319XSLPsetcbitervar

Set a user callback to be called after each column has been tested forconvergencep. 320XSLPsetcbmessage

Set a user callback to be called whenever Xpress NonLinear outputs a lineof text
p. 321XSLPsetcbmsjobend

Set a user callback to be called every time a new multistart job ﬁnishes.
Can be used to overwrite the default solution ranking function
p. 323XSLPsetcbmsjobstart Set a user callback to be called every time a new multistart job is created,
and the pre-loaded settings are applied
p. 324XSLPsetcbmswinnerSet a user callback to be called every time a new multistart job is created,
and the pre-loaded settings are applied
p. 325XSLPsetcboptnode

Set a user callback to be called during MISLP when an optimal SLP
solution is obtained at a node
p. 326XSLPsetcbprenodeSet a user callback to be called during MISLP after the set-up of the SLP
problem to be solved at a node, but before SLP optimization
p. 327XSLPsetcbpreupdatelinearization
updatedSet a user callback to be called before the linearization isp. 328XSLPsetcbslpend

Set a user callback to be called at the end of the SLP optimization

XSLPsetcbslpnode

Set a user callback to be called during MISLP after the SLP optimization ateach node.
p. 330XSLPsetcbslpstart

Set a user callback to be called at the start of the SLP optimization

p. 331XSLPsetcurrentiv

Transfer the current solution to initial values

p. 332XSLPsetdblcontrol

Set the value of a double precision problem control

p. 333XSLPsetdefaultcontrol

p. 329Set the values of one SLP control to its default valuep. 334XSLPsetdefaults

Set the values of all SLP controls to their default values

p. 335XSLPsetfunctionerror

Set the function error ﬂag for the problem

p. 336XSLPsetintcontrol

Set the value of an integer problem control

p. 337

Fair Isaac Corporation Conﬁdential and Proprietary Information219

Library functions and the programming interface

Reference

XSLPsetlogfile

Deﬁne an output ﬁle to be used to receive messages from Xpress
NonLinearp. 338XSLPsetparamSet the value of a control parameter by name

p. 339XSLPsetstrcontrol

Set the value of a string problem control

p. 340XSLPunconstruct

Removes the augmentation and returns the problem to its pre-linearizationstate
p. 341XSLPupdatelinearization

Updates the current linearization

p. 342XSLPvalidate

Validate the feasibility of constraints in a converged solution

p. 343XSLPvalidatekkt

Validates the ﬁrst order optimality conditions also known as the
Karush-Kuhn-Tucker (KKT) conditions versus the currect solution

p. 344XSLPvalidateprob

Validates the current problem formulation and statement

p. 345XSLPvalidaterow

Prints an extensive analysis on a given constraint of the SLP problem p. 346

XSLPvalidatevector

Validate the feasibility of constraints for a given solution

p. 347XSLPwriteprob

Write the current problem to a ﬁle in extended MPS or text format

p. 348XSLPwriteslxsol

Write the current solution to an MPS like ﬁle format

p. 349Fair Isaac Corporation Conﬁdential and Proprietary Information

220

Library functions and the programming interface

ReferenceXSLPaddcoefs
Purpose
Synopsis

Add non-linear coefﬁcients to the SLP problem
int XPRS_CC XSLPaddcoefs(XSLPprob Prob, int nSLPCoef, int ⁎RowIndex, int⁎ColIndex, double ⁎Factor, int ⁎FormulaStart, int Parsed, int ⁎Type,double ⁎Value);

Arguments
Prob
nSLPCoef
RowIndex
ColIndex
FactorThe current SLP problem.
Number of non-linear coefﬁcients to be added.
Integer array holding index of row for the coefﬁcient.
Integer array holding index of column for the coefﬁcient.
Double array holding factor by which formula is scaled. If this is NULL, then a value of
1.0 will be used.
FormulaStart Integer array of length nSLPCoef+1 holding the start position in the arrays Typeand Value of the formula for the coefﬁcients. FormulaStart[nSLPCoef] should be
set to the next position after the end of the last formula.
ParsedInteger indicating whether the token arrays are formatted as internal unparsed(Parsed=0) or internal parsed reverse Polish (Parsed=1).
Type
Array of token types providing the formula for each coefﬁcient.
Value
Array of values corresponding to the types in Type.

ExampleAssume that the rows and columns of Prob are named Row1, Row2 ..., Col1, Col2 ... The following
example adds coefﬁcients representing:
Col2 ⁎ Col3 + Col6 ⁎ Col2ˆ2 into Row1 andCol2 ˆ 2 into Row3.
int RowIndex[3], ColIndex[3], FormulaStart[4], Type[8];int n, nSLPCoef;
double Value[8];RowIndex[0] = 1; ColIndex[0] = 2;
RowIndex[1] = 1; ColIndex[1] = 6;
RowIndex[2] = 3; ColIndex[2] = 2;n = nSLPCoef = 0;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 3;
Type[n++] = XSLP_EOF;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 2;
Type[n] = XSLP_COL; Value[n++] = 2;
Type[n] = XSLP_OP; Value[n++] = XSLP_MULTIPLY;
Type[n++] = XSLP_EOF;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 2;
Type[n++] = XSLP_EOF;

Fair Isaac Corporation Conﬁdential and Proprietary Information

221

Library functions and the programming interface

Reference

FormulaStart[nSLPCoef] = n;
XSLPaddcoefs(Prob, nSLPCoef, RowIndex, ColIndex,
NULL, FormulaStart, 1, Type, Value);
The ﬁrst coefﬁcient in Row1 is in Col2 and has the formula Col3, so it represents Col2 ⁎ Col3.
The second coefﬁcient in Row1 is in Col6 and has the formula Col2 ⁎ Col2 so it represents Col6 ⁎Col2ˆ2. The formulae are described as parsed (Parsed=1), so the formula is written as
Col2 Col2 ⁎rather than the unparsed form
Col2 ⁎ Col2The last coefﬁcient, in Row3, is in Col2 and has the formula Col2, so it represents Col2 ⁎ Col2.
Further information
The jth coefﬁcient is made up of two parts: Factor and Formula. Factor is a constant multiplier,which can be provided in the Factor array. If Xpress NonLinear can identify a constant factor in
Formula, then it will use that as well, to minimize the size of the formula which has to be calculated.
Formula is made up of a list of tokens in Type and Value starting at FormulaStart[j]. The tokens
follow the rules for parsed or unparsed formulae as indicated by the setting of Parsed. The formula
must be terminated with an XSLP_EOF token. If several coefﬁcients share the same formula, they canhave the same value in FormulaStart. For possible token types and values see the chapter on"Formula Parsing".
The XSLPadd... functions load additional items into the SLP problem. The corresponding
XSLPload... functions delete any existing items ﬁrst.
The behaviour for existing coefﬁcients is additive: the formula deﬁned in the parameters are added toany existing formula coefﬁcients. However, due to performance considerations, such duplications
should be avoided when possible.
Related topics
XSLPchgcoef, XSLPchgccoef, XSLPdelcoefs, XSLPgetcoefformula, XSLPgetccoef,
XSLPloadcoefs

Fair Isaac Corporation Conﬁdential and Proprietary Information

222

Library functions and the programming interface

ReferenceXSLPadddfs
Purpose
Synopsis

Add a set of distribution factors
int XSLP_CC XSLPadddfs(XSLPprob Prob, int nDF, const int ⁎ColIndex, const
int ⁎RowIndex, const double ⁎Value)

Arguments
Prob
nDF
ColIndex
RowIndex
Value
ExampleThe current SLP problem.
The number of distribution factors.
Array of indices of columns whose distribution factor is to be changed.
Array of indices of the rows where each distribution factor applies.
Array of double precision variables holding the new values of the distribution factors.

The following example adds distribution factors as follows:column 282 in row 134 = 0.1
column 282 in row 136 = 0.15
column 285 in row 133 = 1.0.
int ColIndex[3], RowIndex[3];double Value[3];ColIndex[0] = 282; RowIndex[0] = 134; Value[0] = 0.1;
ColIndex[1] = 282; RowIndex[1] = 136; Value[1] = 0.15;
ColIndex[2] = 285; RowIndex[2] = 133; Value[2] = 1.0;
XSLPadddfs(prob,3,ColIndex,RowIndex,Value);

Further information
The distribution factor of a column in a row is the matrix coefﬁcient of the corresponding delta vector in
the row. Distribution factors are used in conventional recursion models, and are essentially normalizedﬁrst-order derivatives. Xpress-SLP can accept distribution factors instead of initial values, provided thatthe values of the variables involved can all be calculated after optimization using determining rows, orby a callback.
The XSLPadd... functions load additional items into the SLP problem. The corresponding
XSLPload... functions delete any existing items ﬁrst.
Related topics
XSLPchgdf, XSLPgetdf, XSLPloaddfs

Fair Isaac Corporation Conﬁdential and Proprietary Information223

Library functions and the programming interface

ReferenceXSLPaddtolsets
Purpose
Synopsis

Add sets of standard tolerance values to an SLP problem
int XPRS_CC XSLPaddtolsets(XSLPprob Prob, int nSLPTol, double ⁎SLPTol);

Arguments
Prob
nSLPTol
SLPTolExampleThe current SLP problem.
The number of tolerance sets to be added.
Double array of (nSLPTol ⁎ 9) items containing the 9 tolerance values for each set inorder.

The following example creates two tolerance sets: the ﬁrst has values of 0.005 for all tolerances; thesecond has values of 0.001 for relative tolerances (numbers 2,4,6,8), values of 0.01 for absolute
tolerances (numbers 1,3,5,7) and zero for the closure tolerance (number 0).
double SLPTol[18];for (i=0;i<9;i++) SLPTol[i] = 0.005;
SLPTol[9] = 0;
for (i=10;i<18;i=i+2) SLPTol[i] = 0.01;
for (i=11;i<18;i=i+2) SLPTol[i] = 0.001;
XSLPaddtolsets(Prob, 2, SLPTol);

Further information
A tolerance set is an array of 9 values containing the following tolerances:
Entry / Bit

ToleranceXSLP constantXSLP bit constant0

Closure tolerance (TC)XSLP_TOLSET_TC

XSLP_TOLSETBIT_TC

1

Absolute delta tolerance (TA)XSLP_TOLSET_TAXSLP_TOLSETBIT_TA

2

Relative delta tolerance (RA)XSLP_TOLSET_RAXSLP_TOLSETBIT_RA

3

Absolute coefﬁcient tolerance (TM)XSLP_TOLSET_TM

XSLP_TOLSETBIT_TM

4

Relative coefﬁcient tolerance (RM)XSLP_TOLSET_RM

XSLP_TOLSETBIT_RM

5

Absolute impact tolerance (TI)XSLP_TOLSET_TIXSLP_TOLSETBIT_TI

6

Relative impact tolerance (RI)XSLP_TOLSET_RIXSLP_TOLSETBIT_RI

7

Absolute slack tolerance (TS)XSLP_TOLSET_TSXSLP_TOLSETBIT_TS

8

Relative slack tolerance (RS)XSLP_TOLSET_RS

XSLP_TOLSETBIT_RSThe XSLP_TOLSET constants can be used to access the corresponding entry in the value arrays, while
the XSLP_TOLSETBIT constants are used to set or retrieve which tolerance values are used for a given
SLP variable.
Once created, a tolerance set can be used to set the tolerances for any SLP variable.
If a tolerance value is zero, then the default tolerance will be used instead. To force the use of atolerance, use the XSLPchgtolset function and set the Status variable appropriately.
See the section Convergence criteria for a fuller description of tolerances and their uses.
The XSLPadd... functions load additional items into the SLP problem. The corresponding
XSLPload... functions delete any existing items ﬁrst.
Related topics
XSLPchgtolset, XSLPdeltolsets, XSLPgettolset, XSLPloadtolsets

Fair Isaac Corporation Conﬁdential and Proprietary Information

224

Library functions and the programming interface

ReferenceXSLPadduserfunction
Purpose
Synopsis

Add user function deﬁnitions to an SLP problem.
int XPRS_CC XSLPadduserfunction(XSLPprob Prob, const char ⁎ FunctionName,
int FunctionType, int nInput, int nOutput, int Options, void ⁎FunctionPointer,void ⁎ UserContext, int ⁎ FunctionTokenId);

Arguments
Prob
The current SLP problem.
FunctionName The name of the function as it appears in text formula expressions.
FunctionType The type of the user function, one of
1 (XSLP_USERFUNCTION_MAP)
function takes double, returns
double.
2 (XSLP_USERFUNCTION_VECMAP)
function takes double array, returns
double.
3 (XSLP_USERFUNCTION_MULTIMAP)
function takes double array, returns
double array.
4 (XSLP_USERFUNCTION_MAPDELTA)
function takes double, returns
double and delta.
5 (XSLP_USERFUNCTION_VECMAPDELTA)
function takes double array, returns
double and deltas.
6 (XSLP_USERFUNCTION_MULTIMAPDELTA) function takes double array, returns
double array and deltas.
nInputNumber of arguments the user function takes.
nOutput
Number of return arguments for the function.
Options
Options as a bitmap to the user function
XSLP_INSTANCEFUNCTION always istantiate the function.
FunctionPointer Pointer of the suer function to call.
UserContext Context pointer to provide the user function with.
FunctionTokenId The token id of the user function added, to be used in the Value array when
deﬁning formulas and using with XSLP_USERFUNCTION.
Further information
The function declarations expected for the user functions are deﬁned by the FunctionType argument.
The function of type XSLP_USERFUNCTION_MAP expects a function in the form of ’double XPRS_CC
F(double Value, void *Context)’.
The function of type XSLP_USERFUNCTION_VECMAP expects a function in the form of ’double
XPRS_CC F(double *Value, void *Context)’.
The function of type XSLP_USERFUNCTION_MULTIMAP expects a function in the form of ’int XPRS_CC
F(double *Value, double *Out, void *Context)’.
The function of type XSLP_USERFUNCTION_MAPDELTA expects a function in the form of ’int XPRS_CC
F(double Value, double Delta, double *Evaluation, double *Partial, void *Context)’.
The function of type XSLP_USERFUNCTION_VECMAPDELTA expects a function in the form of ’int
XPRS_CC F(double *Value, double *Deltas, double *Evaluation, double *Partials, void *Context)’.
The function of type XSLP_USERFUNCTION_MULTIMAPDELTA expects a function in the form of ’int
XPRS_CC F(double *Value, double *Deltas, double *Out, void *Context)’.
Related topics
Function Declaration in Xpress NonLinear, XSLPdeluserfunction, XSLPimportlibfunc

Fair Isaac Corporation Conﬁdential and Proprietary Information225

Library functions and the programming interface

ReferenceXSLPaddvars
Purpose
Synopsis

Add SLP variables deﬁned as matrix columns to an SLP problem
int XPRS_CC XSLPaddvars(XSLPprob Prob, int nSLPVar, int ⁎ColIndex, int⁎VarType, int ⁎DetRow, int ⁎SeqNum, int ⁎TolIndex, double ⁎InitValue,
double ⁎StepBound);Arguments
Prob
nSLPVar
ColIndex
VarType

DetRow

SeqNumTolIndex

InitValue

StepBound

ExampleThe current SLP problem.
The number of SLP variables to be added.
Integer array holding the index of the matrix column corresponding to each SLP variable.
Bitmap giving information about the SLP variable as follows:
Bit 1
Variable has a delta vector;
Bit 2
Variable has an initial value;
Bit 14
Variable is the reserved "=" column;
May be NULL if not required.
Integer array holding the index of the determining row for each SLP variable (a negativevalue means there is no determining row)
May be NULL if not required.
Integer array holding the index sequence number for cascading for each SLP variable (azero value means there is no pre-deﬁned order for this variable)
May be NULL if not required.
Integer array holding the index of the tolerance set for each SLP variable (a zero valuemeans the default tolerances are used)
May be NULL if not required.
Double array holding the initial value for each SLP variable (use the VarType bit map to
indicate if a value is being provided)
May be NULL if not required.
Double array holding the initial step bound size for each SLP variable (a zero valuemeans that no initial step bound size has been speciﬁed). If a value of
XPRS_PLUSINFINITY is used for a value in StepBound, the delta will never have stepbounds applied, and will almost always be regarded as converged.
May be NULL if not required.

The following example loads two SLP variables into the problem. They correspond to columns 23 and25 of the underlying LP problem. Column 25 has an initial value of 1.42; column 23 has no speciﬁc
initial value
int ColIndex[2], VarType[2];double InitValue[2];ColIndex[0] = 23; VarType[0] = 0;
ColIndex[1] = 25; Vartype[1] = 2; InitValue[1] = 1.42;
XSLPaddvars(Prob, 2, ColIndex, VarType, NULL, NULL,
NULL, InitValue, NULL);InitValue is not set for the ﬁrst variable, because it is not used (VarType = 0). Bit 1 of VarType isset for the second variable to indicate that the initial value has been set.

Fair Isaac Corporation Conﬁdential and Proprietary Information

226

Library functions and the programming interface

Reference

The arrays for determining rows, sequence numbers, tolerance sets and step bounds are not used atall, and so have been passed to the function as NULL.
Further information
The XSLPadd... functions load additional items into the SLP problem. The corresponding
XSLPload... functions delete any existing items ﬁrst.
Related topics
XSLPchgvar, XSLPdelvars, XSLPgetvar, XSLPloadvars

Fair Isaac Corporation Conﬁdential and Proprietary Information

227

Library functions and the programming interface

Reference

XSLPcalcslacks
Purpose
SynopsisCalculate the slack values for the provided solution in the non-linear problem
int XPRS_CC XSLPcalcslacks(XSLPprob Prob, const double ⁎ dSol, double ⁎Slacks);Arguments
Prob
dSol
Slacks

The current SLP problem.
The solution for which the slacks are requested for.
Vector of length NROWS to return the slack in.

Related topics
XSLPvalidate, XSLPvalidaterow

Fair Isaac Corporation Conﬁdential and Proprietary Information

228

Library functions and the programming interface

Reference

XSLPcascade
Purpose
SynopsisRe-calculate consistent values for SLP variables based on the current values of the remaining variables.
int XPRS_CC XSLPcascade(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example changes the solution value for column 91, and then re-calculates the values of
those dependent on it.
int ColNum;
double Value;
ColNum = 91;
XSLPgetvar(Prob, ColNum, NULL, NULL, NULL, NULL,
NULL, NULL, &Value, NULL, NULL, NULL,
NULL, NULL, NULL, NULL, NULL);
Value = Value + 1.42;
XSLPchgvar(Prob, ColNum, NULL, NULL, NULL, NULL,
NULL, NULL, &Value, NULL, NULL, NULL,
NULL);XSLPcascade(Prob);
XSLPgetvar and XSLPchgvar are being used to get and change the current value of a single variable.
Provided no other values have been changed since the last execution of XSLPcascade, values will bechanged only for variables which depend on column 91.

Further information
See the section on cascading for an extended discussion of the types of cascading which can be
performed.
XSLPcascade is called automatically during the SLP iteration process and so it is not normallynecessary to perform an explicit cascade calculation.
The variables are re-calculated in accordance with the order generated by XSLPcascadeorder.
Related topics
XSLPcascadeorder, XSLP_CASCADE, XSLP_CASCADENLIMIT, XSLP_CASCADETOL_PA,
XSLP_CASCADETOL_PR

Fair Isaac Corporation Conﬁdential and Proprietary Information229

Library functions and the programming interface

Reference

XSLPcascadeorderPurpose
Synopsis

Establish a re-calculation sequence for SLP variables with determining rows.
int XPRS_CC XSLPcascadeorder(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

Assuming that all variables are SLP variables, the following example sets default values for thevariables, creates the re-calculation order and then calls XSLPcascade to calculate consistent values
for the dependent variables.
int ColNum;for (ColNum=1;ColNum<=nCol;ColNum++)
XSLPchgvar(Prob, ColNum, NULL, NULL, NULL, NULL,
NULL, NULL, &DefaultValue[ColNum], NULL, NULL, NULL,
NULL);XSLPcascadeorder(Prob);
XSLPcascade(Prob);

Further information
XSLPcascadeorder is called automatically at the start of the SLP iteration process and so it is notnormally necessary to perform an explicit cascade ordering.
Related topics
XSLPcascade

Fair Isaac Corporation Conﬁdential and Proprietary Information

230

Library functions and the programming interface

Reference

XSLPchgcascadenlimit
Purpose
Synopsis

Set a variable speciﬁc cascade iteration limit
int XPRS_CC XSLPchgcascadenlimit(XSLPprob Prob, int iCol, int
CascadeNLimit);

Arguments
Prob
iCol

The current SLP problem.
The index of the column corresponding to the SLP variable for which the cascading limit
is to be imposed.
CascadeNLimit The new cascading iteration limit.

Further information
A value set by this function will overwrite the value of XSLP_CASCADENLIMIT for this variable. To
remove any previous value set by this function, use an iteration limit of 0.
Related topics
XSLPcascadeorder, XSLP_CASCADE, XSLP_CASCADENLIMIT, XSLP_CASCADETOL_PA,
XSLP_CASCADETOL_PR

Fair Isaac Corporation Conﬁdential and Proprietary Information

231

Library functions and the programming interface

Reference

XSLPchgccoef
Purpose
Synopsis

Add or change a single matrix coefﬁcient using a character string for the formula
int XPRS_CC XSLPchgccoef(XSLPprob Prob, int RowIndex, int ColIndex, double⁎Factor, char ⁎Formula);

Arguments
Prob
RowIndex
ColIndex
FactorFormulaExampleThe current SLP problem.
The index of the matrix row for the coefﬁcient.
The index of the matrix column for the coefﬁcient.
Address of a double precision variable holding the constant multiplier for the formula. If
Factor is NULL, a value of 1.0 will be used.
Character string holding the formula with the tokens separated by spaces.

Assuming that the columns of the matrix are named Col1, Col2, etc, the following example puts theformula 2.5⁎sin(Col1) into the coefﬁcient in row 1, column 3.
char ⁎Formula="sin ( Col1 )";double Factor;
Factor = 2.5;
XSLPchgccoef(Prob, 1, 3, &Factor, Formula);
Note that all the tokens in the formula (including mathematical operators and separators) are
separated by one or more spaces.

Further information
If the coefﬁcient already exists as a constant or formula, it will be changed into the new coefﬁcient. If it
does not exist, it will be added to the problem.
A coefﬁcient is made up of two parts: Factor and Formula. Factor is a constant multiplier which
can be provided in the Factor variable. If Xpress NonLinear can identify a constant factor in the
Formula, then it will use that as well, to minimize the size of the formula which has to be calculated.
This function can only be used if all the operands in the formula can be correctly identiﬁed as
constants, existing columns, character variables or functions. Therefore, if a formula refers to a newcolumn, that new item must be added to the Xpress NonLinear problem ﬁrst.
Related topicsXSLPaddcoefs, XSLPdelcoefs, XSLPchgcoef, XSLPgetcoefformula, XSLPloadcoefs

Fair Isaac Corporation Conﬁdential and Proprietary Information232

Library functions and the programming interface

Reference

XSLPchgcoef
Purpose
Synopsis

Add or change a single matrix coefﬁcient using a parsed or unparsed formula
int XPRS_CC XSLPchgcoef(XSLPprob Prob, int RowIndex, int ColIndex, double⁎Factor, int Parsed, int ⁎Type, double ⁎Value);

Arguments
Prob
RowIndex
ColIndex
FactorParsedType
Value
ExampleThe current SLP problem.
The index of the matrix row for the coefﬁcient.
The index of the matrix column for the coefﬁcient.
Address of a double precision variable holding the constant multiplier for the formula. If
Factor is NULL, a value of 1.0 will be used.
Integer indicating the whether the token arrays are formatted as internal unparsed(Parsed=0) or internal parsed reverse Polish (Parsed=1).
Array of token types providing the description and formula for each item.
Array of values corresponding to the types in Type.

Assuming that the columns of the matrix are named Col1, Col2, etc, the following example puts theformula 2.5⁎sin(Col1) into the coefﬁcient in row 1, column 3.
int n, iSin, Type[4];double Value[4];double Factor;
XSLPgetindex(Prob, XSLP_INTERNALFUNCNAMESNOCASE,"sin", &iSin);n = 0;
Type[n] = XSLP_IFUN; Value[n++] = iSin;
Type[n] = XSLP_VAR; Value[n++] = 1;
Type[n++] = XSLP_RB;
Type[n++] = XSLP_EOF;
Factor = 2.5;
XSLPchgcoef(Prob, 1, 3, &Factor, 0, Type, Value);XSLPgetindex is used to retrieve the index for the internal function sin. The "nocase" version
matches the function name regardless of the (upper or lower) case of the name.
Token type XSLP_VAR always counts from 1, so Col1 is always 1.
The formula is written in unparsed form (Parsed = 0) and so it is provided as tokens in the same orderas they would appear if the formula were written in character form.

Further information
If the coefﬁcient already exists as a constant or formula, it will be changed into the new coefﬁcient. If it
does not exist, it will be added to the problem.
A coefﬁcient is made up of two parts: Factor and Formula. Factor is a constant multiplier which
can be provided in the Factor variable. If Xpress NonLinear can identify a constant factor in the
Formula, then it will use that as well, to minimize the size of the formula which has to be calculated.
Related topicsXSLPaddcoefs, XSLPchgccoef, XSLPdelcoefs, XSLPgetcoefformula, XSLPloadcoefs

Fair Isaac Corporation Conﬁdential and Proprietary Information233

Library functions and the programming interface

Reference

XSLPchgdeltatype
Purpose
Synopsis

Changes the type of the delta assigned to a nonlinear variable
int XPRS_CC XSLPchgdeltatype(XSLPprob Prob, int nVar, int Vars[], int
DeltaTypes[], double Values[]);Arguments
Prob
The current SLP problem.
nVar
The number of SLP variables to change the delta type for.
Vars
Indices of the variables to change the deltas for.
DeltaTypes Type if the delta variable:
0
Differentiable variable, default.
1
Variable deﬁned over the grid size given in Values.
2
Variable where a minimum perturbation size given in Values may berequired before a signiﬁcant change in the problem is achieved.
3
Variable where a meaningful step size should automatically be detected,
with an upper limit given in Values.
ValuesGrid or minimum step sizes for the variables.
Further information
Changing the delta type of a variables makes the variable nonlinear.
Related topics
XSLP_SEMICONTDELTAS, XSLP_INTEGERDELTAS, XSLP_EXPLOREDELTASFair Isaac Corporation Conﬁdential and Proprietary Information234

Library functions and the programming interface

Reference

XSLPchgdf
Purpose
Synopsis

Set or change a distribution factor
int XSLP_CC XSLPchgdf(XSLPprob Prob, int ColIndex, int RowIndex, const
double ⁎Value)

Arguments
Prob
ColIndex
RowIndex
Value
ExampleThe current SLP problem.
The index of the column whose distribution factor is to be set or changed.
The index of the row where the distribution applies.
Address of a double precision variable holding the new value of the distribution factor.
May be NULL if not required.

The following example retrieves the value of the distribution factor for column 282 in row 134 andchanges it to be twice as large.
double Value;
XSLPgetdf(prob,282,134,&Value);
Value = Value ⁎ 2;
XSLPchgdf(prob,282,134,&Value);

Further information
The distribution factor of a column in a row is the matrix coefﬁcient of the corresponding delta vector in
the row. Distribution factors are used in conventional recursion models, and are essentially normalizedﬁrst-order derivatives. Xpress NonLinear can accept distribution factors instead of initial values,
provided that the values of the variables involved can all be calculated after optimization using
determining rows, or by a callback.
Related topicsXSLPadddfs, XSLPgetdf, XSLPloaddfs

Fair Isaac Corporation Conﬁdential and Proprietary Information

235

Library functions and the programming interface

Reference

XSLPchgrowstatus
Purpose
Synopsis

Change the status setting of a constraint
int XPRS_CC XSLPchgrowstatus(XSLPprob Prob, int RowIndex, int ⁎Status);

Arguments
Prob
RowIndex
StatusExampleThe current SLP problem.
The index of the matrix row to be changed.
Address of an integer holding a bitmap with the new status settings. If the status is tobe changed, always get the current status ﬁrst (use XSLPgetrowstatus) and thenchange settings as required. The only settings likely to be changed are:Bit 11
Set if row must not have a penalty error vector. This is the equivalent of an
enforced constraint (SLPDATA type EC).

The following example changes the status of row 9 to be an enforced constraint.
int RowIndex, Status;
RowIndex = 9;
XSLPgetrowstatus(Prob,RowIndex,&Status);
Status = Status | (1<<11);
XSLPchgrowstatus(Prob,RowIndex,&Status);

Further information
If Status is NULL the current status will remain unchanged.
Related topics
XSLPgetrowstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

236

Library functions and the programming interface

Reference

XSLPchgrowwt
Purpose
Synopsis

Set or change the initial penalty error weight for a row
int XSLP_CC XSLPchgrowwt(XSLPprob Prob, int RowIndex, const double ⁎Value)

Arguments
Prob
RowIndex
Value
ExampleThe current SLP problem.
The index of the row whose weight is to be set or changed.
Address of a double precision variable holding the new value of the weight. May be
NULL if not required.

The following example sets the initial weight of row number 2 to a ﬁxed value of 3.6 and the initial
weight of row 4 to a value twice the calculated default value.
double Value;
Value = -3.6;
XSLPchgrowwt(Prob,2,&Value);
Value = 2.0;
XSLPchgrowwt(Prob,4,&Value);

Further information
A positive value is interpreted as a multiplier of the default row weight calculated by Xpress-SLP.
A negative value is interpreted as a ﬁxed value: the absolute value is used directly as the row weight.
The initial row weight is used only when the augmented structure is created.
Related topics
XSLPgetrowwt

Fair Isaac Corporation Conﬁdential and Proprietary Information

237

Library functions and the programming interface

Reference

XSLPchgtolset
Purpose
Synopsis

Add or change a set of convergence tolerances used for SLP variables
int XPRS_CC XSLPchgtolset(XSLPprob Prob, int nSLPTol, int ⁎Status, double⁎Tols);

Arguments
Prob
nSLPTolStatusTols
ExampleThe current SLP problem.
Tolerance set for which values are to be changed. A zero value for nSLPTol will create
a new set.
Address of an integer holding a bitmap describing which tolerances are active in thisset. See below for the settings.
Array of 9 double precision values holding the values for the corresponding tolerances.

The following example creates a new tolerance set with the default values for all tolerances except therelative delta tolerance, which is set to 0.005. It then changes the value of the absolute delta andabsolute impact tolerances in tolerance set 6 to 0.015
int Status;
double Tols[9];Tols[2] = 0.005;
Status = 1<<2;
XSLPchgtolset(Prob, 0, &Status, Tols);
Tols[1] = Tols[5] = 0.015;
Status = 1<<1 | 1<<5;
XSLPchgtolset(Prob, 6, &Status, Tols);

Further information
The bits in Status are set to indicate that the corresponding tolerance is to be changed in thetolerance set. The meaning of the bits is as follows:
Entry / Bit

ToleranceXSLP constantXSLP bit constant0

Closure tolerance (TC)XSLP_TOLSET_TC

XSLP_TOLSETBIT_TC

1

Absolute delta tolerance (TA)XSLP_TOLSET_TAXSLP_TOLSETBIT_TA

2

Relative delta tolerance (RA)XSLP_TOLSET_RAXSLP_TOLSETBIT_RA

3

Absolute coefﬁcient tolerance (TM)XSLP_TOLSET_TM

XSLP_TOLSETBIT_TM

4

Relative coefﬁcient tolerance (RM)XSLP_TOLSET_RM

XSLP_TOLSETBIT_RM

5

Absolute impact tolerance (TI)XSLP_TOLSET_TIXSLP_TOLSETBIT_TI

6

Relative impact tolerance (RI)XSLP_TOLSET_RIXSLP_TOLSETBIT_RI

7

Absolute slack tolerance (TS)XSLP_TOLSET_TSXSLP_TOLSETBIT_TS

8

Relative slack tolerance (RS)XSLP_TOLSET_RS

XSLP_TOLSETBIT_RSThe XSLP_TOLSET constants can be used to access the corresponding entry in the value arrays, while
the XSLP_TOLSETBIT constants are used to set or retrieve which tolerance values are used for a given
SLP variable. The members of the Tols array corresponding to nonzero bit settings in Status will be
used to change the tolerance set. So, for example, if bit 3 is set in Status, then Tols[3] will replace
the current value of the absolute coefﬁcient tolerance. If a bit is not set in Status, the value of thecorresponding element of Tols is unimportant.

Fair Isaac Corporation Conﬁdential and Proprietary Information

238

Library functions and the programming interface

Reference

Related topicsXSLPaddtolsets, XSLPdeltolsets, XSLPgettolset, XSLPloadtolsets

Fair Isaac Corporation Conﬁdential and Proprietary Information239

Library functions and the programming interface

Reference

XSLPchgvar
Purpose
SynopsisDeﬁne a column as an SLP variable or change the characteristics and values of an existing SLP variable
int XPRS_CC XSLPchgvar(XSLPprob Prob, int ColIndex, int ⁎DetRow, double⁎InitStepBound, double ⁎StepBound, double ⁎Penalty, double ⁎Damp,
double ⁎InitValue, double ⁎Value, int ⁎TolSet, int ⁎History, int⁎Converged, int ⁎VarType);

Arguments
Prob
ColIndex
DetRow

The current SLP problem.
The index of the matrix column.
Address of an integer holding the index of the determining row. Use -1 if there is no
determining row. May be NULL if not required.
InitStepBound Address of a double precision variable holding the initial step bound size. May be
NULL if not required.
StepBound Address of a double precision variable holding the current step bound size. Use zero todisable the step bounds. May be NULL if not required.
Penalty
Address of a double precision variable holding the weighting of the penalty cost forexceeding the step bounds. May be NULL if not required.
Damp
Address of a double precision variable holding the damping factor for the variable. May
be NULL if not required.
InitValue Address of a double precision variable holding the initial value for the variable. May be
NULL if not required.
Value
Address of a double precision variable holding the current value for the variable. May be
NULL if not required.
TolSetAddress of an integer holding the index of the tolerance set for this variable. Use zero if
there is no speciﬁc tolerance set. May be NULL if not required.
History
Address of an integer holding the history value for this variable. May be NULL if not
required.
Converged Address of an integer holding the convergence status for this variable. May be NULL if
not required.
VarType
Address of an integer holding a bitmap deﬁning the existence of certain properties forthis variable:
Bit 1:
Variable has a delta vector
Bit 2:
Variable has an initial value
Bit 14: Variable is the reserved "=" column
May be NULL if not required.

ExampleThe following example sets an initial value of 1.42 and tolerance set 2 for column 25 in the matrix.
double InitialValue;
int VarType, TolSet;
InitialValue = 1.42;
TolSet = 2;
VarType = 1<<1 | 1<<2;
XSLPchgvar(Prob, 25, NULL, NULL, NULL, NULL,
NULL, &InitialValue, NULL, &TolSet,

Fair Isaac Corporation Conﬁdential and Proprietary Information240

Library functions and the programming interface

Reference

NULL, NULL, &VarType);
Note that bits 1 and 2 of VarType are set, indicating that the variable has a delta vector and an initialvalue. For columns already deﬁned as SLP variables, use XSLPgetvar to obtain the current value of
VarType because other bits may already have been set by the system.
Further information
If any of the arguments is NULL then the corresponding information for the variable will be left
unaltered. If the information is new (i.e. the column was not previously deﬁned as an SLP variable) thenthe default values will be used.
Changing Value, History or Converged is only effective during SLP iterations.
Changing InitValue and InitStepBound is only effective before XSLPconstruct.
If a value of XPRS_PLUSINFINITY is used in the value for StepBound or InitStepBound, the delta
will never have step bounds applied, and will almost always be regarded as converged.
Related topicsXSLPaddvars, XSLPdelvars, XSLPgetvar, XSLPloadvars

Fair Isaac Corporation Conﬁdential and Proprietary Information241

Library functions and the programming interface

Reference

XSLPconstruct
Purpose
SynopsisCreate the full augmented SLP matrix and data structures, ready for optimization
int XPRS_CC XSLPconstruct(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example constructs the augmented matrix and then outputs the result in MPS format toa ﬁle called augment.mat/⁎ creation and/or loading of data ⁎//⁎ precedes this segment of code⁎/...
XSLPconstruct(Prob);
XSLPwriteprob(Prob,"augment","l");The "l" ﬂag causes output of the current linear problem (which is now the augmented structure and thecurrent linearization) rather than the original nonlinear problem.

Further information
XSLPconstruct adds new rows and columns to the SLP matrix and calculates initial values for the
non-linear coefﬁcients. Which rows and columns are added will depend on the setting of
XSLP_AUGMENTATION. Names for the new rows and columns are generated automatically, based on
the existing names and the string control variables XSLP_xxxFORMAT.
Once XSLPconstruct has been called, no new rows, columns or non-linear coefﬁcients can be added
to the problem. Any rows or columns which will be required must be added ﬁrst. Non-linear coefﬁcients
must not be changed; constant matrix elements can generally be changed after XSLPconstruct, but
not after XSLPpresolve if used.
XSLPconstruct is called automatically by the SLP optimization procedure, and so only needs to becalled explicitly if changes need to be made between the augmentation and the optimization.
Related topics
XSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information242

Library functions and the programming interface

Reference

XSLPcopycallbacks
Purpose
Synopsis

Copy the user-deﬁned callbacks from one SLP problem to anotherint XPRS_CC XSLPcopycallbacks(XSLPprob NewProb, XSLPprob OldProb);

Arguments
NewProb
OldProb
ExampleThe SLP problem to receive the callbacks.
The SLP problem from which the callbacks are to be copied.

The following example creates a new problem and copies only the Xpress NonLinear callbacks fromthe existing problem (not the Optimizer library ones).
XSLPprob nProb;
XPRSprob xProb;
int Control;
XSLPcreateprob(&nProb, &xProb);
Control = 1<<2;
XSLPsetintcontrol(Prob, XSLP_CONTROL, Control);
XSLPcopycallbacks(nProb, Prob);
Note that XSLP_CONTROL is set in the old problem, not the new one.

Further information
Normally XSLPcopycallbacks copies both the Xpress NonLinear callbacks and the Optimizer Library
callbacks for the underlying problem. If only the Xpress NonLinear callbacks are required, set the
integer control variable XSLP_CONTROL appropriately.
Related topics
XSLP_CONTROL

Fair Isaac Corporation Conﬁdential and Proprietary Information243Library functions and the programming interface

Reference

XSLPcopycontrols
Purpose
Synopsis

Copy the values of the control variables from one SLP problem to anotherint XPRS_CC XSLPcopycontrols(XSLPprob NewProb, XSLPprob OldProb);

Arguments
NewProb
OldProb
ExampleThe SLP problem to receive the controls.
The SLP problem from which the controls are to be copied.

The following example creates a new problem and copies only the Xpress NonLinear controls from theexisting problem (not the Optimizer library ones).
XSLPprob nProb;
XPRSprob xProb;
int Control;
XSLPcreateprob(&nProb, &xProb);
Control = 1<<1;
XSLPsetintcontrol(Prob, XSLP_CONTROL, Control);
XSLPcopycontrols(nProb, Prob);
Note that XSLP_CONTROL is set in the old problem, not the new one.

Further information
Normally XSLPcopycontrols copies both the Xpress NonLinear controls and the Optimizer Library
controls for the underlying problem. If only the Xpress NonLinear controls are required, set the integer
control variable XSLP_CONTROL appropriately.
Related topics
XSLP_CONTROL

Fair Isaac Corporation Conﬁdential and Proprietary Information244

Library functions and the programming interface

Reference

XSLPcopyprob
Purpose
Synopsis

Copy an existing SLP problem to anotherint XPRS_CC XSLPcopyprob(XSLPprob NewProb, XSLPprob OldProb, char
⁎ProbName);

Arguments
NewProb
OldProb
ProbName
ExampleThe SLP problem to receive the copy.
The SLP problem from which to copy.
The name to be given to the problem.

The following example creates a new Xpress NonLinear problem and then copies an existing problem
to it. The new problem is named "ANewProblem".
XSLPprob nProb;
XPRSprob xProb;
XSLPcreateprob(&nProb, &xProb);
XSLPcopyprob(nProb, Prob, "ANewProblem");

Further information
Normally XSLPcopyprob copies both the Xpress NonLinear problem and the underlying Optimizer
Library problem. If only the Xpress NonLinear problem is required, set the integer control variable
XSLP_CONTROL appropriately.
This function does not copy controls or callbacks. These must be copied separately using
XSLPcopycontrols and XSLPcopycallbacks if required.
Related topics
XSLP_CONTROL

Fair Isaac Corporation Conﬁdential and Proprietary Information

245

Library functions and the programming interface

Reference

XSLPcreateprob
Purpose
SynopsisCreate a new SLP problem
int XPRS_CC XSLPcreateprob(XSLPprob ⁎Prob, XPRSprob ⁎xProb);

Arguments
Prob
xProb
ExampleThe address of the SLP problem variable.
The address of the underlying Optimizer Library problem variable.

The following example creates an optimizer problem, and then a new Xpress NonLinear problem.
XSLPprob nProb;
XPRSprob xProb;
XPRScreateprob(&xProb);
XSLPcreateprob(&nProb, &xProb);

Further information
An Xpress NonLinear problem includes an underlying optimizer problem which is used to solve thesuccessive linear approximations. The user is responsible for creating and destroying the underlying
linear problem, and can also access it using the normal optimizer library functions. When an SLP
problem is to be created, the underlying problem is created ﬁrst, and the SLP problem is then created,knowing the address of the underlying problem.
Related topics
XSLPdestroyprob

Fair Isaac Corporation Conﬁdential and Proprietary Information

246

Library functions and the programming interface

Reference

XSLPdelcoefs
Purpose
Synopsis

Delete coefﬁcients from the current problem
int XPRS_CC XSLPdelcoefs(XSLPprob Prob, in nSLPCoef, int ⁎RowIndex, int⁎ColIndex);

Arguments
Prob
nSLPCoef
RowIndex
ColIndex

The current SLP problem.
Number of SLP coefﬁcients to delete.
Row indices of the SLP coefﬁcients to delete.
Column indices of the SLP coefﬁcients to delete.

Related topicsXSLPaddcoefs, XSLPchgcoef, XSLPchgccoef, XSLPgetcoefformula, XSLPgetccoef,
XSLPloadcoefs

Fair Isaac Corporation Conﬁdential and Proprietary Information

247

Library functions and the programming interface

Reference

XSLPdeltolsets
Purpose
Synopsis

Delete tolerance sets from the current problem
int XPRS_CC XSLPdeltolsets(XSLPprob Prob, int nTolSet, int ⁎TolSetIndex);

Arguments
Prob
The current SLP problem.
nTolSetNumber of tolerance sets to delete.
TolSetIndex Indices of tolerance sets to delete.
Related topicsXSLPaddtolsets, XSLPchgtolset, XSLPgettolset, XSLPloadtolsets

Fair Isaac Corporation Conﬁdential and Proprietary Information248

Library functions and the programming interface

Reference

XSLPdeluserfunction
Purpose
Synopsis

Delete a user function from the current problem
int XPRS_CC XSLPdeluserfunction(XSLPprob prob, int FunctionTokenId);

Arguments
Prob
The current SLP problem.
FunctionTokenId The identiﬁer of the user function as returned by XSLPadduserfunction.
Related topicsXSLPadduserfunction, XSLPimportlibfunc

Fair Isaac Corporation Conﬁdential and Proprietary Information249

Library functions and the programming interface

Reference

XSLPdelvars
Purpose
Synopsis

Convert SLP variables to normal columns. Variables must not appear in SLP structures
int XPRS_CC XSLPdelvars(XSLPprob prob, int nCol, int ⁎ColIndex);

Arguments
Prob
nCol
ColIndex

The current SLP problem.
Number SLP variables to be converted to linear columns.
Column indices of the SLP vars to be converted to linear ones.

Further information
The SLP variables to be converted to linear, non SLP columns must not be in use by any other SLP
structure (coefﬁcients, initial value formulae, delayed columns). Use the appropriate deletion or change
functions to remove them ﬁrst.
Related topicsXSLPaddvars, XSLPchgvar, XSLPgetvar, XSLPloadvars

Fair Isaac Corporation Conﬁdential and Proprietary Information250

Library functions and the programming interface

Reference

XSLPdestroyprob
Purpose
Synopsis

Delete an SLP problem and release all the associated memory
int XPRS_CC XSLPdestroyprob(XSLPprob Prob);

Argument
Prob
ExampleThe SLP problem.

The following example creates an SLP problem and then destroys it together with the underlying
optimizer problem.
XSLPprob nProb;
XPRSprob xProb;
XPRScreateprob(&xProb);
XSLPcreateprob(&nProb, &xProb);...
XSLPdestroyprob(nProb);
XPRSdestroyprob(xProb);

Further information
When you have ﬁnished with the SLP problem, it should be "destroyed" so that the memory used by the
problem can be released. Note that this does not destroy the underlying optimizer problem, so a call to
XPRSdestroyprob should follow XSLPdestroyprob as and when you have ﬁnished with theunderlying optimizer problem.
Related topics
XSLPcreateprob

Fair Isaac Corporation Conﬁdential and Proprietary Information251Library functions and the programming interface

Reference

XSLPevaluatecoef
Purpose
Synopsis

Evaluate a coefﬁcient using the current values of the variables
int XPRS_CC XSLPevaluatecoef(XSLPprob Prob, int RowIndex, int ColIndex,
double ⁎dValue);

Arguments
Prob
RowIndex
ColIndex
Value
ExampleThe current SLP problem.
Integer index of the row.
Integer index of the column.
Address of a double precision value to receive the result of the calculation.

The following example sets the value of column 5 to 1.42 and then calculates the coefﬁcient in row 2,
column 3. If the coefﬁcient depends on column 5, then a value of 1.42 will be used in the calculation.
double Value, dValue;
Value = 1.42;
XSLPchgvar(Prob, 5, NULL, NULL, NULL, NULL,
NULL, NULL, &Value, NULL, NULL, NULL,
NULL);XSLPevaluatecoef(Prob, 2, 3, &dValue);

Further information
The values of the variables are obtained from the solution, or from the Value setting of an SLP variable(see XSLPchgvar and XSLPgetvar).
Related topics
XSLPchgvar, XSLPevaluateformula XSLPgetvar

Fair Isaac Corporation Conﬁdential and Proprietary Information252

Library functions and the programming interface

Reference

XSLPevaluateformulaPurpose
Synopsis

Evaluate a formula using the current values of the variables
int XPRS_CC XSLPevaluateformula(XSLPprob Prob, int Parsed, int ⁎Type,double ⁎Value, double ⁎dValue);

Arguments
Prob
ParsedType
Value
dValueExampleThe current SLP problem.
integer indicating whether the formula of the item is in internal unparsed format(Parsed=0) or parsed (reverse Polish) format (Parsed=1).
Integer array of token types for the formula.
Double array of values corresponding to Type.
Address of a double precision value to receive the result of the calculation.

The following example calculates the value of column 3 divided by column 6.
int n, Type[10];double dValue, Value[10];n = 0;
Type[n] = XSLP_COL; Value[n++] = 3;
Type[n] = XSLP_COL; Value[n++] = 6;
Type[n] = XSLP_OP; Value[n++] = XSLP_DIVIDE;
Type[n++] = XSLP_EOF;
XSLPevaluateformula(Prob, 1, Type, Value, &dValue);

Further information
The formula in Type and Value must be terminated by an XSLP_EOF token.
The formula cannot include "complicated" functions, such as user functions which return more than
one value
Related topics
XSLPevaluatecoef

Fair Isaac Corporation Conﬁdential and Proprietary Information

253

Library functions and the programming interface

Reference

XSLPﬁxpenalties
Purpose
SynopsisFixe the values of the error vectors
int XPRS_CC XSLPfixpenalties(XSLPprob Prob, int ⁎Status);

Arguments
Prob
Status

The current SLP problem.
Return status after ﬁxing the penalty variables: 0 is successful, nonzero otherwise.

Further information
The function ﬁxes the values of all error vectors on their current values. It also removes their objective
cost contribution.
The function is intended to support post optimization analysis, by removing any possible direct effectof the error vectors from the dual and reduced cost values.
The XSLPﬁxpenalties will automatically reoptimize the linearization. However, as the XSLP
convergence and infeasibility checks (regarding the original non-linear problem) will not be carried out,
this function will not update the SLP solution itself. The updated values will be accessible using
XPRSgetlpsolution instead.

Fair Isaac Corporation Conﬁdential and Proprietary Information254

Library functions and the programming interface

Reference

XSLPfreePurpose
Synopsis
ExampleFree any memory allocated by Xpress NonLinear and close any open Xpress NonLinear ﬁlesint XPRS_CC XSLPfree(void);
The following code frees the Xpress NonLinear memory and then frees the optimizer memory:XSLPfree();
XPRSfree();

Further information
A call to XSLPfree only frees the items speciﬁc to Xpress NonLinear. XPRSfree must be called after
XSLPfree to free the optimizer structures.
Related topics
XSLPinit

Fair Isaac Corporation Conﬁdential and Proprietary Information

255

Library functions and the programming interface

Reference

XSLPgetbanner
Purpose
Synopsis

Retrieve the Xpress NonLinear banner and copyright messages
int XPRS_CC XSLPgetbanner(char ⁎Banner);

Argument
BannerExampleCharacter buffer to hold the banner. This will be at most 256 characters including thenull terminator.

The following example retrieves the Xpress NonLinear banner and prints it
char Buffer[260];XSLPgetbanner(Buffer];
printf("%s\n",Buffer);

Further information
Note that XSLPgetbanner does not take the normal Prob argument.
If XSLPgetbanner is called before XPRSinit, then it will return only the Xpress NonLinear
information; otherwise it will include the XPRSgetbanner information as well.

Fair Isaac Corporation Conﬁdential and Proprietary Information

256

Library functions and the programming interface

Reference

XSLPgetccoef
Purpose
Synopsis

Retrieve a single matrix coefﬁcient as a formula in a character string
int XPRS_CC XSLPgetccoef(XSLPprob Prob, int RowIndex, int ColIndex, double⁎Factor, char ⁎Formula, int fLen);

Arguments
Prob
RowIndex
ColIndex
FactorFormulafLen

The current SLP problem.
Integer holding the row index for the coefﬁcient.
Integer holding the column index for the coefﬁcient.
Address of a double precision variable to receive the value of the constant factor
multiplying the formula in the coefﬁcient.
Character buffer in which the formula will be placed in the same format as used for
input from a ﬁle. The formula will be null terminated.
Maximum length of returned formula.

Return value0
Normal return.
1
Formula is too long for the buffer and has been truncated.
other Error.
ExampleThe following example displays the formula for the coefﬁcient in row 2, column 3:char Buffer[60];double Factor;
int Code;
Code = XSLPgetccoef(Prob, 2, 3, &Factor, Buffer, 60);
switch (Code) {case 0: printf("\nFormula is %s",Buffer);
printf("\nFactor = %lg",Factor);
break;
case 1: printf("\nFormula is too long for the buffer");break;
default: printf("\nError accessing coefficient");
break;}

Further information
If the requested coefﬁcient is constant, then Factor will be set to 1.0 and the value will be formatted in
Formula.
If the length of the formula would exceed fLen-1, the formula is truncated to the last token that will ﬁt,
and the (partial) formula is terminated with a null character.
Related topics
XSLPchgccoef, XSLPchgcoef, XSLPgetcoefformula

Fair Isaac Corporation Conﬁdential and Proprietary Information

257

Library functions and the programming interface

Reference

XSLPgetcoefformulaPurpose
Synopsis

Retrieve a single matrix coefﬁcient as a formula split into tokens
int XPRS_CC XSLPgetcoefformula(XSLPprob Prob, int RowIndex, int ColIndex,
double ⁎Factor, int Parsed, int BufferSize, int ⁎TokenCount, int⁎Type, double ⁎Value);

Arguments
Prob
RowIndex
ColIndex
FactorThe current SLP problem.
Integer holding the row index for the coefﬁcient.
Integer holding the column index for the coefﬁcient.
Address of a double precision variable to receive the value of the constant factor
multiplying the formula in the coefﬁcient.
ParsedInteger indicating whether the formula of the item is to be returned in internal unparsed
format (Parsed=0) or parsed (reverse Polish) format (Parsed=1).
BufferSize Maximum number of tokens to return, i.e. length of the Type and Value arrays.
TokenCount Number of tokens returned in Type and Value.
Type
Integer array to hold the token types for the formula.
Value
Double array of values corresponding to Type.

ExampleThe following example displays the formula for the coefﬁcient in row 2, column 3 in unparsed form:
int n, Type[10];double Value[10];int TokenCount;
XSLPgetcoefformula(Prob, 2, 3, &Factor, 0, 10, &TokenCount, Type, Value);for (n=0;Type[n] != XSLP_EOF;n++)printf("\nType=%-3d Value=%lg",Type[n],Value[n]);Further information
The Type and Value arrays are terminated by an XSLP_EOF token.
If the requested coefﬁcient is constant, then Factor will be set to 1.0 and the value will be returned
with token type XSLP_CON.
Related topics
XSLPchgccoef, XSLPchgcoef, XSLPgetccoef

Fair Isaac Corporation Conﬁdential and Proprietary Information258

Library functions and the programming interface

Reference

XSLPgetcoefs
Purpose
Synopsis

Retrieve the list of positions of the nonlinear coefﬁcients in the problem
int XPRS_CC XSLPgetcoefs(XSLPprob Prob, int ⁎nCoef, int ⁎RowIndices, int⁎ColIndices);

Arguments
Prob
The current SLP problem.
nCoef
Integer used to return the total number of nonlinear coefﬁcients in the problem.
RowIndices Integer array used for returning the row positions of the coefﬁcients. May be NULL if
not required.
ColIndices Integer array used for returning the column positions of the coefﬁcients. May be NULL
if not required.
Related topics
XSLPgetccoef, XSLPgetcoefformula

Fair Isaac Corporation Conﬁdential and Proprietary Information259

Library functions and the programming interface

Reference

XSLPgetcolinfo
Purpose
Synopsis

Get current column information.
int XSLP_CC XSLPgetcolinfo(XSLPprob Prob, int InfoType, int ColIndex,
XSLPalltype ⁎Info);

Arguments
Prob
InfoType
ColIndex
Info

The current SLP problem
Type of information (see below)
Index of the column whose information is to be handled
Address of information to be set or retrieved

Further information
If the data is not available, the type of the returned Info is set to XSLPtype_undefined.
Please refer to the header ﬁle xslp.h for the deﬁnition of XSLPalltype.
The following constants are provided for column information handling:
XSLP_COLINFO_VALUE

Get the current value of the column

XSLP_COLINFO_RDJ

Get the current reduced cost of the column

XSLP_COLINFO_DELTAINDEX

Get the delta variable index associated to the column

XSLP_COLINFO_DELTA

Get the delta value (change since previous value) of the column

XSLP_COLINFO_DELTADJ

Get the delta variables reduced cost

XSLP_COLINFO_UPDATEROW

Get the index of the update (or step bound) row associated to thecolumnXSLP_COLINFO_SB

Get the step bound on the variable

XSLP_COLINFO_SBDUAL

Get the dual multiplier of the step bound row for the variable

Fair Isaac Corporation Conﬁdential and Proprietary Information260

Library functions and the programming interface

Reference

XSLPgetdblattrib
Purpose
Synopsis

Retrieve the value of a double precision problem attribute
int XPRS_CC XSLPgetdblattrib(XSLPprob Prob, int Param, double ⁎dValue);

Arguments
Prob
Param
dValueExampleThe current SLP problem.
attribute (SLP or optimizer) whose value is to be returned.
Address of a double precision variable to receive the value.

The following example retrieves the value of the Xpress NonLinear attribute
XSLP_CURRENTDELTACOST and of the optimizer attribute XPRS_LPOBJVAL:
double DeltaCost, ObjVal;
XSLPgetdblattrib(Prob, XSLP_CURRENTDELTACOST, &DeltaCost);
XSLPgetdblattrib(Prob, XPRS_LPOBJVAL, &ObjVal);

Further information
Both SLP and optimizer attributes can be retrieved using this function. If an optimizer attribute isrequested, the return value will be the same as that from XPRSgetdblattrib.
Related topics
XSLPgetintattrib, XSLPgetstrattrib

Fair Isaac Corporation Conﬁdential and Proprietary Information

261

Library functions and the programming interface

Reference

XSLPgetdblcontrol
Purpose
Synopsis

Retrieve the value of a double precision problem control
int XPRS_CC XSLPgetdblcontrol(XSLPprob Prob, int Param, double ⁎dValue);

Arguments
Prob
Param
dValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
Address of a double precision variable to receive the value.

The following example retrieves the value of the Xpress NonLinear control XSLP_CTOL and of the
optimizer control XPRS_FEASTOL:
double CTol, FeasTol;
XSLPgetdblcontrol(Prob, XSLP_CTOL, &CTol);XSLPgetdblcontrol(Prob, XPRS_FEASTOL, &FeasTol);

Further information
Both SLP and optimizer controls can be retrieved using this function. If an optimizer control isrequested, the return value will be the same as that from XPRSgetdblcontrol.
Related topics
XSLPgetintcontrol, XSLPgetstrcontrol, XSLPsetdblcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information

262

Library functions and the programming interface

Reference

XSLPgetdf
Purpose
Synopsis

Get a distribution factor
int XSLP_CC XSLPgetdf(XSLPprob Prob, int ColIndex, int RowIndex, double⁎Value)Arguments
Prob
ColIndex
RowIndex
Value
ExampleThe current SLP problem.
The index of the column whose distribution factor is to be retrieved.
The index of the row from which the distribution factor is to be taken.
Address of a double precision variable to receive the value of the distribution factor.
May be NULL if not required.

The following example retrieves the value of the distribution factor for column 282 in row 134 andchanges it to be twice as large.
double Value;
XSLPgetdf(prob,282,134,&Value);
Value = Value ⁎ 2;
XSLPchgdf(prob,282,134,&Value);

Further information
The distribution factor of a column in a row is the matrix coefﬁcient of the corresponding delta vector in
the row. Distribution factors are used in conventional recursion models, and are essentially normalizedﬁrst-order derivatives. Xpress-SLP can accept distribution factors instead of initial values, provided thatthe values of the variables involved can all be calculated after optimization using determining rows, orby a callback.
Related topicsXSLPadddfs, XSLPchgdf, XSLPloaddfs

Fair Isaac Corporation Conﬁdential and Proprietary Information

263

Library functions and the programming interface

Reference

XSLPgetindex
Purpose
Synopsis

Retrieve the index of an Xpress NonLinear entity with a given nameint XPRS_CC XSLPgetindex(XSLPprob Prob, int Type, char ⁎cName, int ⁎Index);

Arguments
Prob
Type

cName
Index
ExampleThe current SLP problem.
Type of entity. The following are deﬁned:
XSLP_CVNAMES(=3) Character variables;XSLP_USERFUNCNAMES(=5) User functions;XSLP_INTERNALFUNCNAMES(=6) Internal functions;XSLP_USERFUNCNAMESNOCASE(=7) User functions, case insensitive;XSLP_INTERNALFUNCNAMESNOCASE (=8) Internal functions, case insensitive;
The constants 1 (for row names) and 2 (for column names) may also be used.
Character string containing the name, terminated by a null character.
Integer to receive the index of the item.

The following example retrieves the index of the internal SIN function using both an upper-case and alower case version of the name.
int UpperIndex, LowerIndex;
XSLPgetindex(Prob, XSLP_INTERNALFUNCNAMESNOCASE,"SIN", &UpperIndex);XSLPgetindex(Prob, XSLP_INTERNALFUNCNAMESNOCASE,"sin", &LowerIndex);
UpperIndex and LowerIndex will contain the same value because the search was made usingcase-insensitive matching.

Further information
All entities count from 1. This includes the use of 1 or 2 (row or column) for Type. A value of zero
returned in Index means there is no matching item. The case-insensitive types will ﬁnd the ﬁrst match
regardless of the case of cName or of the deﬁned function.

Fair Isaac Corporation Conﬁdential and Proprietary Information264

Library functions and the programming interface

Reference

XSLPgetintattrib
Purpose
Synopsis

Retrieve the value of an integer problem attribute
int XPRS_CC XSLPgetintattrib(XSLPprob Prob, int Param, int ⁎iValue);

Arguments
Prob
Param
iValueExampleThe current SLP problem.
attribute (SLP or optimizer) whose value is to be returned.
Address of an integer variable to receive the value.

The following example retrieves the value of the Xpress NonLinear attribute XSLP_CVS and of the
optimizer attribute XPRS_COLS:
int nCV, nCol;
XSLPgetintattrib(Prob, XSLP_CVS, &nCV);XSLPgetintattrib(Prob, XPRS_COLS, &nCol);

Further information
Both SLP and optimizer attributes can be retrieved using this function. If an optimizer attribute isrequested, the return value will be the same as that from XPRSgetintattrib.
Related topics
XSLPgetdblattrib, XSLPgetstrattrib

Fair Isaac Corporation Conﬁdential and Proprietary Information

265

Library functions and the programming interface

Reference

XSLPgetintcontrol
Purpose
Synopsis

Retrieve the value of an integer problem control
int XPRS_CC XSLPgetintcontrol(XSLPprob Prob, int Param, int ⁎iValue);

Arguments
Prob
Param
iValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
Address of an integer variable to receive the value.

The following example retrieves the value of the Xpress NonLinear control XSLP_ALGORITHM and of
the optimizer control XPRS_DEFAULTALG:
int Algorithm, DefaultAlg;
XSLPgetintcontrol(Prob, XSLP_ALGORITHM, &Algorithm);
XSLPgetintcontrol(Prob, XPRS_DEFAULTALG, &DefaultAlg);

Further information
Both SLP and optimizer controls can be retrieved using this function. If an optimizer control isrequested, the return value will be the same as that from XPRSgetintcontrol.
Related topics
XSLPgetdblcontrol, XSLPgetstrcontrol, XSLPsetintcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information

266

Library functions and the programming interface

Reference

XSLPgetlasterror
Purpose
Synopsis

Retrieve the error message corresponding to the last Xpress NonLinear error during an SLP run
int XPRS_CC XSLPgetlasterror(XSLPprob Prob, int ⁎Code, char ⁎Buffer);

Arguments
Prob
Code
BufferExampleThe current SLP problem.
Address of an integer to receive the message number of the last error. May be NULL if
not required.
Character buffer to receive the error message. The error message will never be longer
than 256 characters. May be NULL if not required.

The following example checks the return code from reading a matrix. If the code is nonzero then anerror has occurred, and the error number is retrieved for further processing.
int Error, Code;if (Error=XSLPreadprob(Prob, "Matrix", "")) {XSLPgetlasterror(Prob, &Code, NULL);
MyErrorHandler(Code);}

Further information
In general, Xpress NonLinear functions return a value of 32 to indicate a non-recoverable error.
XSLPgetlasterror can retrieve the actual error number and message. In case no SLP error code
was retuned, the function will check the underlying XPRS libary for any errors reported.

Fair Isaac Corporation Conﬁdential and Proprietary Information

267

Library functions and the programming interface

Reference

XSLPgetptrattrib
Purpose
Synopsis

Retrieve the value of a problem pointer attribute
int XPRS_CC XSLPgetptrattrib(XSLPprob Prob, int Param, void ⁎⁎Value);

Arguments
Prob
Param
Value
ExampleThe current SLP problem.
attribute whose value is to be returned.
Address of a pointer to receive the value.

The following example retrieves the value of the Xpress NonLinear pointer attribute
XSLP_XPRSPROBLEM which is the underlying optimizer problem pointer:
XPRSprob xprob;XSLPgetptrattrib(Prob, XSLP_XPRSPROBLEM, &xprob);

Further information
This function is normally used to retrieve the underlying optimizer problem pointer, as shown in theexample.
Related topics
XSLPgetdblattrib, XSLPgetintattrib, XSLPgetstrattrib

Fair Isaac Corporation Conﬁdential and Proprietary Information

268

Library functions and the programming interface

Reference

XSLPgetrowinfo
Purpose
Synopsis

Get current row information.
int XSLP_CC XSLPgetrowinfo(XSLPprob Prob, int InfoType, int RowIndex,
XSLPalltype ⁎Info);

Arguments
Prob
InfoType
RowIndex
Info

The current SLP problem
Type of information (see below)
Index of the row whose information is to be handled
Address of information to be set or retrieved

Further information
If the data is not available, the type of the returned Info is set to XSLPtype_undefined.
Please refer to the header ﬁle xslp.h for the deﬁnition of XSLPalltype.
The following constants are provided for row information handling:
XSLP_ROWINFO_SLACK

Get the current slack value of the row

XSLP_ROWINFO_DUAL

Get the current dual multiplier of the row

XSLP_ROWINFO_NUMPENALTYERRORS Get the number of times the penalty error vector has been
active for the row
XSLP_ROWINFO_MAXPENALTYERROR Get the maximum size of the penalty error vector activity forthe rowXSLP_ROWINFO_TOTALPENALTYERROR
row

Get the total size of the penalty error vector activity for the

XSLP_ROWINFO_CURRENTPENALTYERROR Get the size of the penalty error vector activity in thecurrent iteration for the row
XSLP_ROWINFO_CURRENTPENALTYFACTOR Set the size of the penalty error factor for the current
iteration for the row
XSLP_ROWINFO_PENALTYCOLUMNPLUS

Get the index of the positive penalty column for the row (+)

XSLP_ROWINFO_PENALTYCOLUMNPLUSVALUE
row (+)

Get the value of the positive penalty column for the

XSLP_ROWINFO_PENALTYCOLUMNPLUSDJ Get the reduced cost of the positive penalty column for
the row (+)
XSLP_ROWINFO_PENALTYCOLUMNMINUS

Get the index of the negative penalty column for the row (-)

XSLP_ROWINFO_PENALTYCOLUMNMINUSVALUE
row (-)XSLP_ROWINFO_PENALTYCOLUMNMINUSDJ
the row (-)

Fair Isaac Corporation Conﬁdential and Proprietary Information

Get the value of the negative penalty column for the

Get the reduced cost of the negative penalty column for269

Library functions and the programming interface

Reference

XSLPgetrowstatus
Purpose
Synopsis

Retrieve the status setting of a constraint
int XPRS_CC XSLPgetrowstatus(XSLPprob Prob, int RowIndex, int ⁎Status);

Arguments
Prob
RowIndex
StatusExampleThe current SLP problem.
The index of the matrix row whose data is to be obtained.
Address of an integer holding a bitmap to receive the status settings.

This recovers the status of the rows of the matrix of the current problem and reports those which are
ﬂagged as enforced constraints.
int iRow, nRow, Status;
XSLPgetintattrib(Prob, XPRS_ROWS, &nRow);for (iRow=0;iRow<nRow;iRow++) {XSLPgetrowstatus(Prob, iRow, &Status);
if (Status & 0x800) printf("\nRow %d is enforced");}Further information
See the section on bitmap settings for details on the possible information in Status.
Related topics
XSLPchgrowstatus

Fair Isaac Corporation Conﬁdential and Proprietary Information

270

Library functions and the programming interface

Reference

XSLPgetrowwt
Purpose
Synopsis

Get the initial penalty error weight for a row
int XSLP_CC XSLPgetrowwt(XSLPprob Prob, int RowIndex, double ⁎Value)

Arguments
Prob
RowIndex
Value
ExampleThe current SLP problem.
The index of the row whose weight is to be retrieved.
Address of a double precision variable to receive the value of the weight.

The following example gets the initial weight of row number 2.
double Value;
XSLPgetrowwt(Prob,2,&Value)

Further information
The initial row weight is used only when the augmented structure is created. After that, the current
weighting can be accessed using XSLPgetrowinfo.
Related topics
XSLPchgrowwt, XSLPgetrowinfo

Fair Isaac Corporation Conﬁdential and Proprietary Information271

Library functions and the programming interface

Reference

XSLPgetslpsol
Purpose
Synopsis

Obtain the solution values for the most recent SLP iteration
int XPRS_CC XSLPgetslpsol(XSLPprob Prob, double ⁎x, double ⁎slack, double⁎dual, double ⁎dj);

Arguments
Prob
x
slack
dual
dj
ExampleThe current SLP problem.
Double array of length XSLP_ORIGINALCOLS to hold the values of the primal variables.
May be NULL if not required.
Double array of length XSLP_ORIGINALROWS to hold the values of the slack variables.
May be NULL if not required.
Double array of length XSLP_ORIGINALROWS to hold the values of the dual variables.
May be NULL if not required.
Double array of length XSLP_ORIGINALCOLS to hold the recuded costs of the primal
variables. May be NULL if not required.

The following code fragment recovers the values and reduced costs of the primal variables from themost recent SLP iteration:
XSLPprob prob;
int nCol;
double ⁎val, ⁎dj;
XSLPgetintattrib(prob,XSLP_ORIGINALCOLS,&nCol);val = malloc(nCol⁎sizeof(double));dj = malloc(nCol⁎sizeof(double));XSLPgetslpsol(prob,val,NULL,NULL,dj);

Further information
XSLPgetslpsol can be called at any time after an SLP iteration has completed, and will return thesame values even if the problem is subsequently changed. XSLPgetslpsol returns values for thecolumns and rows originally in the problem and not for any augmentation rows or columns. To accessthe values of any augmentation columns or rows, use XPRSgetlpsol; accessing the augmented
solution is only recommended if XSLP_PRESOLVELEVEL indicates that the problem dimensions
should not be changed in presolve.

Fair Isaac Corporation Conﬁdential and Proprietary Information272

Library functions and the programming interface

Reference

XSLPgetstrattrib
Purpose
Synopsis

Retrieve the value of a string problem attribute
int XPRS_CC XSLPgetstrattrib(XSLPprob Prob, int Param, char ⁎cValue);

Arguments
Prob
Param
cValueExampleThe current SLP problem.
attribute (SLP or optimizer) whose value is to be returned.
Character buffer to receive the value.

The following example retrieves the value of the Xpress NonLinear attribute XSLP_VERSIONDATE andof the optimizer attribute XPRS_MATRIXNAME:
char VersionDate[200], MatrixName[200];XSLPgetstrattrib(Prob, XSLP_VERSIONDATE, VersionDate);
XSLPgetstrattrib(Prob, XPRS_MATRIXNAME, MatrixName);

Further information
Both SLP and optimizer attributes can be retrieved using this function. If an optimizer attribute isrequested, the return value will be the same as that from XPRSgetstrattrib.
Related topics
XSLPgetdblattrib, XSLPgetintattrib

Fair Isaac Corporation Conﬁdential and Proprietary Information

273

Library functions and the programming interface

Reference

XSLPgetstrcontrol
Purpose
Synopsis

Retrieve the value of a string problem control
int XPRS_CC XSLPgetstrcontrol(XSLPprob Prob, int Param, char ⁎cValue);

Arguments
Prob
Param
cValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
Character buffer to receive the value.

The following example retrieves the value of the Xpress NonLinear control XSLP_CVNAME and of the
optimizer control XPRS_MPSOBJNAME:
char CVName[200], ObjName[200];XSLPgetstrcontrol(Prob, XSLP_CVNAME, CVName);XSLPgetstrcontrol(Prob, XPRS_MPSOBJNAME, ObjName);

Further information
Both SLP and optimizer controls can be retrieved using this function. If an optimizer control isrequested, the return value will be the same as that from XPRSgetstrcontrol.
Related topics
XSLPgetdblcontrol, XSLPgetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information274

Library functions and the programming interface

Reference

XSLPgettolset
Purpose
Synopsis

Retrieve the values of a set of convergence tolerances for an SLP problem
int XPRS_CC XSLPgettolset(XSLPprob Prob, int nSLPTol, int ⁎Status, double⁎Tols);

Arguments
Prob
nSLPTolStatusTols
ExampleThe current SLP problem.
The index of the tolerance set.
Address of integer to receive the bit-map of status settings. May be NULL if not required.
Array of 9 double-precision values to hold the tolerances. May be NULL if not required.

The following example retrieves the values for tolerance set 3 and prints those which are set:
double Tols[9];int i, Status;
XSLPgettolset(Prob, 3, &Status, Tols);for (i=0;i<9;i++)if (Status & (1<<i))printf("\nTolerance %d = %lg",i,Tols[i]);Further information
If Status or Tols is NULL, then the corresponding information will not be returned.
If Tols is not NULL, then a set of 9 values will always be returned. Status indicates which of thesevalues is active as follows. Bit n of Status is set if Tols[n] is active, where n is:
Entry / Bit

ToleranceXSLP constantXSLP bit constant0

Closure tolerance (TC)XSLP_TOLSET_TC

XSLP_TOLSETBIT_TC

1

Absolute delta tolerance (TA)XSLP_TOLSET_TAXSLP_TOLSETBIT_TA

2

Relative delta tolerance (RA)XSLP_TOLSET_RAXSLP_TOLSETBIT_RA

3

Absolute coefﬁcient tolerance (TM)XSLP_TOLSET_TM

XSLP_TOLSETBIT_TM

4

Relative coefﬁcient tolerance (RM)XSLP_TOLSET_RM

XSLP_TOLSETBIT_RM

5

Absolute impact tolerance (TI)XSLP_TOLSET_TIXSLP_TOLSETBIT_TI

6

Relative impact tolerance (RI)XSLP_TOLSET_RIXSLP_TOLSETBIT_RI

7

Absolute slack tolerance (TS)XSLP_TOLSET_TSXSLP_TOLSETBIT_TS

8

Relative slack tolerance (RS)XSLP_TOLSET_RS

XSLP_TOLSETBIT_RSThe XSLP_TOLSET constants can be used to access the corresponding entry in the value arrays, while
the XSLP_TOLSETBIT constants are used to set or retrieve which tolerance values are used for a given
SLP variable.
Related topics
Related topicsXSLPaddtolsets, XSLPchgtolset, XSLPdeltolsets, XSLPloadtolsets

Fair Isaac Corporation Conﬁdential and Proprietary Information275

Library functions and the programming interface

Reference

XSLPgetvar
Purpose
Synopsis

Retrieve information about an SLP variable
int XPRS_CC XSLPgetvar(XSLPprob prob, int ColIndex, int ⁎DetRow, double⁎InitStepBound, double ⁎StepBound, double ⁎Penalty, double ⁎Damp,
double ⁎InitValue, double ⁎Value, int ⁎TolSet, int ⁎History, int⁎Converged, int ⁎VarType, int ⁎Delta, int ⁎PenaltyDelta, int⁎UpdateRow, double ⁎OldValue);

Arguments
Prob
ColIndex
DetRow

The current SLP problem.
The index of the column.
Address of an integer to receive the index of the determining row. May be NULL if not
required.
InitStepBound Address of a double precision variable to receive the value of the initial step boundof the variable. May be NULL if not required.
StepBound Address of a double precision variable to receive the value of the current step bound of
the variable. May be NULL if not required.
Penalty
Address of a double precision variable to receive the value of the penalty delta
weighting of the variable. May be NULL if not required.
Damp
Address of a double precision variable to receive the value of the current damping factorof the variable. May be NULL if not required.
InitValue Address of a double precision variable to receive the value of the initial value of thevariable. May be NULL if not required.
Value
Address of a double precision variable to receive the current activity of the variable. May
be NULL if not required.
TolSetAddress of an integer to receive the index of the tolerance set of the variable. May be
NULL if not required.
History
Address of an integer to receive the SLP history of the variable. May be NULL if not
required.
Converged Address of an integer to receive the convergence status of the variable as deﬁned in the"Convergence Criteria" section (The returned value will match the numbering of thetolerances). May be NULL if not required.
VarType
Address of an integer to receive the status settings (a bitmap deﬁning the existence of
certain properties for this variable). The following bits are deﬁned:
Bit 1:
Variable has a delta vector
Bit 2:
Variable has an initial value
Bit 14: Variable is the reserved "=" column
Other bits are reserved for internal use. May be NULL if not required.
Delta
Address of an integer to receive the index of the delta vector for the variable. May be
NULL if not required.
PenaltyDelta Address of an integer to receive the index of the ﬁrst penalty delta vector for thevariable. The second penalty delta immediately follows the ﬁrst. May be NULL if not
required.
UpdateRow Address of an integer to receive the index of the update row for the variable. May be
NULL if not required.
OldValue
Address of a double precision variable to receive the value of the variable at theprevious SLP iteration. May be NULL if not required.

Fair Isaac Corporation Conﬁdential and Proprietary Information

276

Library functions and the programming interface

ExampleReference

The following example retrieves the current value, convergence history and status for column 3.
int Status, History;
double Value;
XSLPgetvar(Prob, 3, NULL, NULL, NULL,
NULL, NULL, NULL, &Value,
NULL, &History, &Converged,
NULL, NULL, NULL, NULL, NULL);

Further information
If ColIndex refers to a column which is not an SLP variable, then all the return values will indicate that
there is no corresponding data.
DetRow will be set to -1 if there is no determining row.
Delta, PenaltyDelta and UpdateRow will be set to -1 if there is no corresponding item.
Related topicsXSLPaddvars, XSLPchgvar, XSLPdelvars, XSLPloadvars

Fair Isaac Corporation Conﬁdential and Proprietary Information

277

Library functions and the programming interface

Reference

XSLPglobal
Purpose
Synopsis

Initiate the Xpress NonLinear mixed integer SLP (MISLP) algorithm
int XPRS_CC XSLPglobal(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example optimizes the problem and then ﬁnds the integer solution.
XSLPmaxim(Prob,"");XSLPglobal(Prob);

Further information
The current Xpress NonLinear mixed integer problem will be maximized or minimized using thealgorithm deﬁned by the control variable XSLP_MIPALGORITHM.
It is recommended that XSLPminim or XSLPmaxim is used ﬁrst to obtain a converged solution to therelaxed problem. If this is not done, ensure that XSLP_OBJSENSE is set appropriately.
See the chapter on Mixed Integer Non-Linear Programming for more information about the Xpress
NonLinear MISLP algorithms.
Related topics
XSLPmaxim, XSLPminim, XSLP_MIPALGORITHM, XSLP_OBJSENSE

Fair Isaac Corporation Conﬁdential and Proprietary Information

278

Library functions and the programming interface

Reference

XSLPimportlibfunc
Purpose
Synopsis

Imports a function from a library ﬁle to be called as a user function
int XPRS_CC XSLPimportlibfunc(XSLPprob Prob,const char ⁎ LibName, const
char ⁎ FunctionName, void ⁎⁎ FuncPointer, int ⁎ Status );Arguments
Prob
The current SLP problem.
LibName
Filename of the library.
FunctionName Fucntion anme inside the library.
FuncPointer Function pointer to return the loaded function.
StatusOutcome of the load operation0
success.
1
library ﬁle not found.
2
library function in library ﬁle not found.
Further information
On systems where necessary, Xpress will hold the handle of the library opened and free up when the
problem object Prob is destroyed.
Related topicsXSLPadduserfunction, XSLPdeluserfunction

Fair Isaac Corporation Conﬁdential and Proprietary Information279

Library functions and the programming interface

Reference

XSLPinit
Purpose
Synopsis

Initializes the Xpress NonLinear system
int XPRS_CC XSLPinit();Argumentnone
ExampleThe following example initiates the Xpress NonLinear system and prints the banner.
char Buffer[256];
XPRSinit();XSLPinit();XSLPgetbanner(Buffer);
XPRSinit initializes the Xpress optimizer; XSLPinit then initializes the SLP module, so that thebanner contains information from both systems.

Further information
XSLPinit must be the ﬁrst call to the Xpress NonLinear system except for XSLPgetbanner and
XSLPgetversion. It initializes any global parts of the system if required. The call to XSLPinit must
be preceded by a call to XPRSinit to initialize the Optimizer Library part of the system ﬁrst.
Related topics
XSLPfreeFair Isaac Corporation Conﬁdential and Proprietary Information280

Library functions and the programming interface

Reference

XSLPinterrupt
Purpose
SynopsisInterrupts the current SLP optimization
int XPRS_CC XSLPinterrupt(int Reason);Arguments
Prob
ReasonThe current SLP problem.
Interrupt code to be propagated.

Further information
Provides functionality to stop the SLP optimization process from inside a callback. The following
constants are provided for the paramter value:
Value 1
Value 2
Value 3
Value 4
Value 5
Value 6
Value 9XSLP_STOP_TIMELIMITXSLP_STOP_CTRLCXSLP_STOP_NODELIMITXSLP_STOP_ITERLIMITXSLP_STOP_MIPGAPXSLP_STOP_SOLLIMITXSLP_STOP_USER

Fair Isaac Corporation Conﬁdential and Proprietary Information281

Library functions and the programming interface

Reference

XSLPitemname
Purpose
Synopsis

Retrieves the name of an Xpress NonLinear entity or the value of a function token as a character string.
int XPRS_CC XSLPitemname(XSLPprob Prob, int Type, double Value, char
⁎Buffer);

Arguments
Prob
Type
Value
BufferExampleThe current SLP problem.
Integer holding the type of Xpress NonLinear entity. This can be any one of the token
types described in the section on Formula Parsing.
Double precision value holding the index or value of the token. The use and meaning of
the value is as described in the section on Formula Parsing.
Character buffer to hold the result, which will be terminated with a null character.

The following example displays the formula for the coefﬁcient in row 2, column 3 in unparsed form:
int n, Type[10];double Value[10];char Buffer[60];int TokenCount;
XSLPgetcoefformula(Prob, 2, 3, &Factor, 0, 10, &TokenCount, Type, Value);
printf("\n");for (n=0;Type[n] != XSLP_EOF;n++) {XSLPitemname(Prob, Type[n], Value[n], Buffer);
printf(" %s", Buffer);}

Further information
If a name has not been provided for an Xpress NonLinear entity, then an internally-generated name will
be used.
Numerical values will be formatted as ﬁxed-point or ﬂoating-point depending on their size.

Fair Isaac Corporation Conﬁdential and Proprietary Information282

Library functions and the programming interface

Reference

XSLPloadcoefs
Purpose
Synopsis

Load non-linear coefﬁcients into the SLP problem
int XPRS_CC XSLPloadcoefs(XSLPprob Prob, int nSLPCoef, int ⁎RowIndex, int⁎ColIndex, double ⁎Factor, int ⁎FormulaStart, int Parsed, int ⁎Type,double ⁎Value);

Arguments
Prob
nSLPCoef
RowIndex
ColIndex
FactorThe current SLP problem.
Number of non-linear coefﬁcients to be loaded.
Integer array holding index of row for the coefﬁcient.
Integer array holding index of column for the coefﬁcient.
Double array holding factor by which formula is scaled. If this is NULL, then a value of
1.0 will be used.
FormulaStart Integer array of length nSLPCoef+1 holding the start position in the arrays Typeand Value of the formula for the coefﬁcients. FormulaStart[nSLPCoef] should be
set to the next position after the end of the last formula.
ParsedInteger indicating whether the token arrays are formatted as internal unparsed(Parsed=0) or internal parsed reverse Polish (Parsed=1).
Type
Array of token types providing the formula for each coefﬁcient.
Value
Array of values corresponding to the types in Type.

ExampleAssume that the rows and columns of Prob are named Row1, Row2 ..., Col1, Col2 ... The following
example loads coefﬁcients representing:
Col2 ⁎ Col3 + Col6 ⁎ Col2ˆ2 into Row1 andCol2 ˆ 2 into Row3.
int RowIndex[3], ColIndex[3], FormulaStart[4], Type[8];int n, nSLPCoef;
double Value[8];RowIndex[0] = 1; ColIndex[0] = 2;
RowIndex[1] = 1; ColIndex[1] = 6;
RowIndex[2] = 3; ColIndex[2] = 2;n = nSLPCoef = 0;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 3;
Type[n++] = XSLP_EOF;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 2;
Type[n] = XSLP_COL; Value[n++] = 2;
Type[n] = XSLP_OP; Value[n++] = XSLP_MULTIPLY;
Type[n++] = XSLP_EOF;
FormulaStart[nSLPCoef++] = n;Type[n] = XSLP_COL; Value[n++] = 2;
Type[n++] = XSLP_EOF;

Fair Isaac Corporation Conﬁdential and Proprietary Information

283

Library functions and the programming interface

Reference

FormulaStart[nSLPCoef] = n;
XSLPloadcoefs(Prob, nSLPCoef, RowIndex, ColIndex,
NULL, FormulaStart, 1, Type, Value);
The ﬁrst coefﬁcient in Row1 is in Col2 and has the formula Col3, so it represents Col2 ⁎ Col3.
The second coefﬁcient in Row1 is in Col6 and has the formula Col2 ⁎ Col2 so it represents Col6 ⁎Col2ˆ2. The formulae are described as parsed (Parsed=1), so the formula is written as
Col2 Col2 ⁎rather than the unparsed form
Col2 ⁎ Col2The last coefﬁcient, in Row3, is in Col2 and has the formula Col2, so it represents Col2 ⁎ Col2.
Further information
The jth coefﬁcient is made up of two parts: Factor and Formula. Factor is a constant multiplier,which can be provided in the Factor array. If Xpress NonLinear can identify a constant factor in
Formula, then it will use that as well, to minimize the size of the formula which has to be calculated.
Formula is made up of a list of tokens in Type and Value starting at FormulaStart[j]. The tokens
follow the rules for parsed or unparsed formulae as indicated by the setting of Parsed. The formula
must be terminated with an XSLP_EOF token. If several coefﬁcients share the same formula, they canhave the same value in FormulaStart. For possible token types and values see the chapter on"Formula Parsing".
The XSLPload... functions load items into the SLP problem. Any existing items of the same type aredeleted ﬁrst. The corresponding XSLPadd... functions add or replace items leaving other items of
the same type unchanged.
Related topicsXSLPaddcoefs, XSLPchgcoef, XSLPchgccoef, XSLPgetcoefformula, XSLPgetccoef

Fair Isaac Corporation Conﬁdential and Proprietary Information284

Library functions and the programming interface

Reference

XSLPloaddfs
Purpose
Synopsis

Load a set of distribution factors
int XSLP_CC XSLPloaddfs(XSLPprob Prob, int nDF, const int ⁎ColIndex, const
int ⁎RowIndex, const double ⁎Value)

Arguments
Prob
nDF
ColIndex
RowIndex
Value
ExampleThe current SLP problem.
The number of distribution factors.
Array of indices of columns whose distribution factor is to be changed.
Array of indices of the rows where each distribution factor applies.
Array of double precision variables holding the new values of the distribution factors.

The following example loads distribution factors as follows:column 282 in row 134 = 0.1
column 282 in row 136 = 0.15
column 285 in row 133 = 1.0.
Any other ﬁrst-order derivative placeholders are set to XSLP_DELTA_Z.
int ColIndex[3], RowIndex[3];double Value[3];ColIndex[0] = 282; RowIndex[0] = 134; Value[0] = 0.1;
ColIndex[1] = 282; RowIndex[1] = 136; Value[1] = 0.15;
ColIndex[2] = 285; RowIndex[2] = 133; Value[2] = 1.0;
XSLPloaddfs(prob,3,ColIndex,RowIndex,Value);

Further information
The distribution factor of a column in a row is the matrix coefﬁcient of the corresponding delta vector in
the row. Distribution factors are used in conventional recursion models, and are essentially normalizedﬁrst-order derivatives. Xpress-SLP can accept distribution factors instead of initial values, provided thatthe values of the variables involved can all be calculated after optimization using determining rows, orby a callback.
The XSLPadd... functions load additional items into the SLP problem. The corresponding
XSLPload... functions delete any existing items ﬁrst.
Related topicsXSLPadddfs, XSLPchgdf, XSLPgetdf

Fair Isaac Corporation Conﬁdential and Proprietary Information

285

Library functions and the programming interface

Reference

XSLPloadtolsets
Purpose
Synopsis

Load sets of standard tolerance values into an SLP problem
int XPRS_CC XSLPloadtolsets(XSLPprob Prob, int nSLPTol, double ⁎SLPTol);

Arguments
Prob
nSLPTol
SLPTolExampleThe current SLP problem.
The number of tolerance sets to be loaded.
Double array of (nSLPTol ⁎ 9) items containing the 9 tolerance values for each set inorder.

The following example creates two tolerance sets: the ﬁrst has values of 0.005 for all tolerances; thesecond has values of 0.001 for relative tolerances (numbers 2,4,6,8), values of 0.01 for absolute
tolerances (numbers 1,3,5,7) and zero for the closure tolerance (number 0).
double SLPTol[18];for (i=0;i<9;i++) SLPTol[i] = 0.005;
SLPTol[9] = 0;
for (i=10;i<18;i=i+2) SLPTol[i] = 0.01;
for (i=11;i<18;i=i+2) SLPTol[i] = 0.001;
XSLPloadtolsets(Prob, 2, SLPTol);

Further information
A tolerance set is an array of 9 values containing the following tolerances:
Entry / Bit

ToleranceXSLP constantXSLP bit constant0

Closure tolerance (TC)XSLP_TOLSET_TC

XSLP_TOLSETBIT_TC

1

Absolute delta tolerance (TA)XSLP_TOLSET_TAXSLP_TOLSETBIT_TA

2

Relative delta tolerance (RA)XSLP_TOLSET_RAXSLP_TOLSETBIT_RA

3

Absolute coefﬁcient tolerance (TM)XSLP_TOLSET_TM

XSLP_TOLSETBIT_TM

4

Relative coefﬁcient tolerance (RM)XSLP_TOLSET_RM

XSLP_TOLSETBIT_RM

5

Absolute impact tolerance (TI)XSLP_TOLSET_TIXSLP_TOLSETBIT_TI

6

Relative impact tolerance (RI)XSLP_TOLSET_RIXSLP_TOLSETBIT_RI

7

Absolute slack tolerance (TS)XSLP_TOLSET_TSXSLP_TOLSETBIT_TS

8

Relative slack tolerance (RS)XSLP_TOLSET_RS

XSLP_TOLSETBIT_RSThe XSLP_TOLSET constants can be used to access the corresponding entry in the value arrays, while
the XSLP_TOLSETBIT constants are used to set or retrieve which tolerance values are used for a given
SLP variable.
Once created, a tolerance set can be used to set the tolerances for any SLP variable.
If a tolerance value is zero, then the default tolerance will be used instead. To force the use of atolerance, use the XSLPchgtolset function and set the Status variable appropriately.
See the section "Convergence Criteria" for a fuller description of tolerances and their uses.
The XSLPload... functions load items into the SLP problem. Any existing items of the same type aredeleted ﬁrst. The corresponding XSLPadd... functions add or replace items leaving other items of
the same type unchanged.
Related topicsXSLPaddtolsets, XSLPdeltolsets, XSLPchgtolset, XSLPgettolset

Fair Isaac Corporation Conﬁdential and Proprietary Information

286

Library functions and the programming interface

Reference

XSLPloadvars
Purpose
Synopsis

Load SLP variables deﬁned as matrix columns into an SLP problem
int XPRS_CC XSLPloadvars(XSLPprob Prob, int nSLPVar, int ⁎ColIndex, int⁎VarType, int ⁎DetRow, int ⁎SeqNum, int ⁎TolIndex, double ⁎InitValue,
double ⁎StepBound);Arguments
Prob
nSLPVar
ColIndex
VarType

DetRow

SeqNumTolIndex

InitValue

StepBound

ExampleThe current SLP problem.
The number of SLP variables to be loaded.
Integer array holding the index of the matrix column corresponding to each SLP variable.
Bitmap giving information about the SLP variable as follows:
Bit 1
Variable has a delta vector;
Bit 2
Variable has an initial value;
Bit 14
Variable is the reserved "=" column;
May be NULL if not required.
Integer array holding the index of the determining row for each SLP variable (a negativevalue means there is no determining row)
May be NULL if not required.
Integer array holding the index sequence number for cascading for each SLP variable (azero value means there is no pre-deﬁned order for this variable)
May be NULL if not required.
Integer array holding the index of the tolerance set for each SLP variable (a zero valuemeans the default tolerances are used)
May be NULL if not required.
Double array holding the initial value for each SLP variable (use the VarType bit map to
indicate if a value is being provided)
May be NULL if not required.
Double array holding the initial step bound size for each SLP variable (a zero valuemeans that no initial step bound size has been speciﬁed). If a value of
XPRS_PLUSINFINITY is used for a value in StepBound, the delta will never have stepbounds applied, and will almost always be regarded as converged.
May be NULL if not required.

The following example loads two SLP variables into the problem. They correspond to columns 23 and25 of the underlying LP problem. Column 25 has an initial value of 1.42; column 23 has no speciﬁc
initial value
int ColIndex[2], VarType[2];double InitValue[2];ColIndex[0] = 23; VarType[0] = 0;
ColIndex[1] = 25; Vartype[1] = 2; InitValue[1] = 1.42;
XSLPloadvars(Prob, 2, ColIndex, VarType, NULL, NULL,
NULL, InitValue, NULL);InitValue is not set for the ﬁrst variable, because it is not used (VarType = 0). Bit 1 of VarType isset for the second variable to indicate that the initial value has been set.

Fair Isaac Corporation Conﬁdential and Proprietary Information

287

Library functions and the programming interface

Reference

The arrays for determining rows, sequence numbers, tolerance sets and step bounds are not used atall, and so have been passed to the function as NULL.
Further information
The XSLPload... functions load items into the SLP problem. Any existing items of the same type aredeleted ﬁrst. The corresponding XSLPadd... functions add or replace items leaving other items of
the same type unchanged.
Related topicsXSLPaddvars, XSLPchgvar, XSLPdelvars, XSLPgetvar

Fair Isaac Corporation Conﬁdential and Proprietary Information288

Library functions and the programming interface

Reference

XSLPmaxim
Purpose
SynopsisMaximize an SLP problem
int XPRS_CC XSLPmaxim(XSLPprob Prob, char ⁎Flags);

Arguments
Prob The current SLP problem.
Flags These have the same meaning as for XPRSmaxim.
ExampleThe following example reads an SLP problem from ﬁle and then maximizes it using the primal simplex
optimizer.
XSLPreadprob("Matrix","");XSLPmaxim(Prob,"p");Related controls
Integer
XSLP_ALGORITHM Bit map determining the SLP algorithm(s) used in the optimization.
XSLP_AUGMENTATION Bit map determining the type of augmentation used to create the linearization.
XSLP_CASCADE
Bit map determining the type of cascading (recalculation of SLP variable values)
used during the SLP optimization.
XSLP_LOG
Determines the amount of iteration logging information produced.
XSLP_PRESOLVE Bit map determining the type of nonlinear presolve used before the SLP
optimization starts.
Further information
If XSLPconstruct has not already been called, it will be called ﬁrst, using the augmentation deﬁned by
the control variable XSLP_AUGMENTATION. If determining rows are provided, then cascading will be
invoked in accordance with the setting of the control variable XSLP_CASCADE.
Related topics
XSLPconstruct, XSLPglobal, XSLPminim, XSLPnlpoptimize, XSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information289

Library functions and the programming interface

Reference

XSLPminim
Purpose
Synopsis

Minimize an SLP problem
int XPRS_CC XSLPminim(XSLPprob Prob, char ⁎Flags);

Arguments
Prob The current SLP problem.
Flags These have the same meaning as for XPRSminim.
ExampleThe following example reads an SLP problem from ﬁle and then minimizes it using the Newton barrier
optimizer.
XSLPreadprob("Matrix","");XSLPminim(Prob,"b");Related controls
Integer
XSLP_ALGORITHM Bit map determining the SLP algorithm(s) used in the optimization.
XSLP_AUGMENTATION Bit map determining the type of augmentation used to create the linearization.
XSLP_CASCADE
Bit map determining the type of cascading (recalculation of SLP variable values)
used during the SLP optimization.
XSLP_LOG
Determines the amount of iteration logging information produced.
XSLP_PRESOLVE Bit map determining the type of nonlinear presolve used before the SLP
optimization starts.
Further information
If XSLPconstruct has not already been called, it will be called ﬁrst, using the augmentation deﬁned by
the control variable XSLP_AUGMENTATION. If determining rows are provided, then cascading will be
invoked in accordance with the setting of the control variable XSLP_CASCADE.
Related topics
XSLPconstruct, XSLPglobal, XSLPmaxim, XSLPnlpoptimize, XSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information

290

Library functions and the programming interface

Reference

XSLPmsaddcustompreset
Purpose

Synopsis

A combined version of XSLPmsaddjob and XSLPmsaddpreset. The preset described is loaded, topped
up with the speciﬁc settings supplied
int XSLP_CC XSLPmsaddcustompreset( XSLPprob Prob, const char ⁎sDescription,
const int Preset, const int Count, const int nIVs, const int ⁎IVCols,
const double ⁎IVValues, const int nIntControls, const int⁎IntControlIndices, const int ⁎IntControlValues, const int
nDblControls, const int ⁎DblControlIndices, const double⁎DblControlValues, void ⁎pJobObject);Arguments
Prob
The current SLP problem.
sDescription Text description of the job. Used for messaging, may be NULL if not required.
PresetWhich preset to load.
Count
Maximum number of jobs to be added to the multistart pool.
nIVs
Number of initial values to set.
IVColsIndices of the variables for which to set an initial value. May be NULL if nIVs is zero.
IVValues
Initial values for the variables for which to set an initial value. May be NULL if nIVs is
zero.
nIntControls Number of integer controls to set.
IntControlIndices The indices of the integer controls to be set. May be NULL if nIntControls is
zero.
IntControlValues The values of the integer controls to be set. May be NULL if nIntControls is zero.
nDblControls Number of double controls to set.
DblControlIndices The indices of the double controls to be set. May be NULL if nDblControls is
zero.
DblControlValues The values of the double controls to be set. May be NULL if nDblControls is
zero.
pJobObject Job speciﬁc user context pointer to be passed to the multistart callbacks.
Further information
This function allows for repeatedly calling the same multistart preset (e.g. initial values) using different
basic controls.
Related topics
XSLPmsaddpreset, XSLPmsaddjob, XSLPmsclear

Fair Isaac Corporation Conﬁdential and Proprietary Information

291

Library functions and the programming interface

Reference

XSLPmsaddjob
Purpose
Synopsis

Adds a multistart job to the multistart pool
int XSLP_CC XSLPmsaddjob( XSLPprob Prob, const char ⁎sDescription, const
int nIVs, const int ⁎IVCols, const double ⁎IVValues, const int
nIntControls, const int ⁎IntControlIndices, const int⁎IntControlValues, const int nDblControls, const int⁎DblControlIndices, const double ⁎DblControlValues, void
⁎pJobObject);Arguments
Prob
The current SLP problem.
sDescription Text description of the job. Used for messaging, may be NULL if not required.
nIVs
Number of initial values to set.
IVColsIndices of the variables for which to set an initial value. May be NULL if nIVs is zero.
IVValues
Initial values for the variables for which to set an initial value. May be NULL if nIVs is
zero.
nIntControls Number of integer controls to set.
IntControlIndices The indices of the integer controls to be set. May be NULL if nIntControls is
zero.
IntControlValues The values of the integer controls to be set. May be NULL if nIntControls is zero.
nDblControls Number of double controls to set.
DblControlIndices The indices of the double controls to be set. May be NULL if nDblControls is
zero.
DblControlValues The values of the double controls to be set. May be NULL if nDblControls is
zero.
pJobObject Job speciﬁc user context pointer to be passed to the multistart callbacks.
Further information
Adds a mutistart job, applying the speciﬁed initial point and option combinations on top of the baseproblem, i.e. the options and initial values speciﬁed to the function is applied on top of the existing
settigns.
This function allows for loading empty template jobs, that can then be identiﬁed using the pJobObject
variable.
Related topics
XSLPmsaddpreset, XSLPmsaddcustompreset, XSLPmsclear

Fair Isaac Corporation Conﬁdential and Proprietary Information292

Library functions and the programming interface

Reference

XSLPmsaddpreset
Purpose
Synopsis

Loads a preset of jobs into the multistart job pool.
int XSLP_CC XSLPmsaddpreset( XSLPprob Prob, const char ⁎sDescription, const
int Preset, const int Count, void ⁎pJobObject);Arguments
Prob
The current SLP problem.
sDescription Text description of the preset. Used for messaging, may be NULL if not required.
PresetWhich preset to load.
Count
Maximum number of jobs to be added to the multistart pool.
pJobObject Job speciﬁc user context pointer to be passed to the multistart callbacks.
Further information
The following presets are deﬁned:
XSLP_MSSET_INITIALVALUES: generate Count number of random base points.
XSLP_MSPRESET_SOLVERS: load all solvers.
XSLP_MSPRESET_SLPCONTROLSBASIC: load the most typical SLP tuning settings. A maximum ofCount jobs are loaded.
XSLP_MSPRESET_SLPCONROLSEXTENSIVE: load a comprehensive set of SLP tuning settings. A
maximum of Count jobs are loaded.
XSLP_MSPRESET_KNITROBASIC: load the most typical Knitro tuning settings. A maximum of Countjobs are loaded.
XSLP_MSPRESET_KNITROEXTENSIVE: load a comprehensive set of Knitro tuning settings. A
maximum of Count jobs are loaded.
XSLP_MSSET_INITIALFILTERED: generate Count number of random base points, ﬁltered by a merit
function centred on initial feasibility.
XSLP_MSSET_INITIALDYNAMIC: generate Count number of random base points, that are then reﬁned
and combined further by any solution found during the search.
See XSLP_MSMAXBOUNDRANGE for controlling the range in which initial values are generated.
Related topics
XSLPmsaddjob, XSLPmsaddcustompreset, XSLPmsclear

Fair Isaac Corporation Conﬁdential and Proprietary Information293

Library functions and the programming interface

Reference

XSLPmsclear
Purpose
Synopsis

Removes all scheduled jobs from the multistart job pool
int XSLP_CC XSLPmsclear( XSLPprob Prob);

Argument
Prob

The current SLP problem.

Related topics
XSLPmsaddjob, XSLPmsaddpreset, XSLPmsaddcustompreset

Fair Isaac Corporation Conﬁdential and Proprietary Information294

Library functions and the programming interface

Reference

XSLPnlpoptimize
Purpose
SynopsisMaximize or minimize an SLP problem
int XPRS_CC XSLPnlpoptimize(XSLPprob Prob, char ⁎Flags);

Arguments
Prob The current SLP problem.
Flags These have the same meaning as for XPRSmaxim and XPRSminim.
Related controls
DoubleXSLP_OBJSENSE

Determines the direction of optimization: +1 is for minimization, -1 is for
maximization.

Integer
XSLP_ALGORITHM Bit map determining the SLP algorithm(s) used in the optimization.
XSLP_AUGMENTATION Bit map determining the type of augmentation used to create the linearization.
XSLP_CASCADE
Bit map determining the type of cascading (recalculation of SLP variable values)
used during the SLP optimization.
XSLP_LOG
Determines the amount of iteration logging information produced.
XSLP_PRESOLVE Bit map determining the type of nonlinear presolve used before the SLP
optimization starts.
Further information
XSLPnlpoptimize is equivalent to XSLPmaxim (if XSLP_OBJSENSE = -1) or XSLPminim (ifXSLP_OBJSENSE = +1).
If XSLPconstruct has not already been called, it will be called ﬁrst, using the augmentation deﬁned by
the control variable XSLP_AUGMENTATION. If determining rows are provided, then cascading will be
invoked in accordance with the setting of the control variable XSLP_CASCADE.
Related topics
XSLPconstruct, XSLPglobal, XSLPmaxim, XSLPminim, XSLPpresolve

Fair Isaac Corporation Conﬁdential and Proprietary Information

295

Library functions and the programming interface

Reference

XSLPpostsolve
Purpose
Synopsis

Restores the problem to its pre-solve state
int XPRS_CC XSLPpostsolve(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Related controls
Integer
XSLP_POSTSOLVE

Determines if postsolve is applied automatically.

Further information
If Xpress-SLP was used to solve the problem, postsolve will unconstruct the problem before
postsolving (including any reformulation that might have been applied).
Related topics
XSLP_POSTSOLVE

Fair Isaac Corporation Conﬁdential and Proprietary Information

296

Library functions and the programming interface

Reference

XSLPpresolve
Purpose
Synopsis

Perform a nonlinear presolve on the problem
int XPRS_CC XSLPpresolve(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example reads a problem from ﬁle, sets the presolve control, presolves the problem andthen maximizes it.
XSLPreadprob(Prob, "Matrix", "");XSLPsetintcontrol(Prob, XSLP_PRESOLVE, 1);
XSLPpresolve(Prob);
XSLPmaximize(Prob,"");

Related controls
Integer
XSLP_PRESOLVE

Bitmap containing nonlinear presolve options.

Further information
If bit 1 of XSLP_PRESOLVE is not set, no nonlinear presolve will be performed. Otherwise, the presolve
will be performed in accordance with the bit settings.. XSLPpresolve is called automatically by
XSLPconstruct, so there is no need to call it explicitly unless there is a requirement to interrupt theprocess between presolve and optimization. XSLPpresolve must be called before XSLPconstruct
or any of the SLP optimization procedures..
Related topics
XSLP_PRESOLVE

Fair Isaac Corporation Conﬁdential and Proprietary Information

297

Library functions and the programming interface

Reference

XSLPprintmemory
Purpose
Synopsis

Print the dimensions and memory allocations for a problem
int XPRS_CC XSLPprintmemory(XSLPprob prob);

Argument
Prob
ExampleThe current SLP problem.

The following example loads a problem from ﬁle and then prints the dimensions of the arrays.
XSLPreadprob(Prob, "Matrix1", "");XSLPprintmemory(Prob);
The output is similar to the following:
Arrays and dimensions:
Array
Item Used Max AllocatedSize Items Items
MemoryMemList
28
103
129
4K
String
1 8779 13107
13K
Xv
16
2 1000
16K
Xvitem48
11 1000
47K....

MemoryControl
XSLP_MEM_STRINGXSLP_MEM_XVXSLP_MEM_XVITEM

Further information
XSLPprintmemory lists the current sizes and amounts used of the variable arrays in the current
problem. For each array, the size of each item, the number used and the number allocated are shown,
together with the size of memory allocated and, where appropriate, the name of the memory control
variable to set the array size. Loading and execution of some problems can be speeded up by setting
the memory controls immediately after the problem is created. If an array has to be moved tore-allocate it with a larger size, there may be insufﬁcient memory to hold both the old and new versions;pre-setting the memory controls reduces the number of such re-allocations which take place and may
allow larger problems to be solved.

Fair Isaac Corporation Conﬁdential and Proprietary Information

298

Library functions and the programming interface

Reference

XSLPprintevalinfo
Purpose
Synopsis

Print a summary of any evaluation errors that may have occurred during solving a problem
int XPRS_CC XSLPprintevalinfo(XSLPprob prob);

Argument
Prob

The current SLP problem.

Related topics
XSLPsetcbcoefevalerror

Fair Isaac Corporation Conﬁdential and Proprietary Information299

Library functions and the programming interface

Reference

XSLPreadprob
Purpose
Synopsis

Read an Xpress NonLinear extended MPS format matrix from a ﬁle into an SLP problem
int XPRS_CC XSLPreadprob(XSLPprob Prob, char ⁎Probname, char ⁎Flags);

Arguments
Prob
Probname
Flags
ExampleThe current SLP problem.
Character string containing the name of the ﬁle from which the matrix is to be read.
Character string containing any ﬂags needed for the input routine. No ﬂag settings are
currently recognized.

The following example reads the problem from ﬁle "Matrix.mat".
XSLPreadprob(Prob, "Matrix", "");

Further information
XSLPreadprob tries to open the ﬁle with an extension of "mat" or, failing that, an extension of "mps". If
both fail, the ﬁle name will be tried with no extension.
XSLPreadprob is capable to read most Ampl .nl ﬁles. To specify that a .nl ﬁle is to be read, provide thefull ﬁlename including the .nl extension.
For details of the format of the ﬁle, see the section on Extended MPS format.
Related topics
Extended MPS format, XSLPwriteprob

Fair Isaac Corporation Conﬁdential and Proprietary Information300

Library functions and the programming interface

Reference

XSLPremaxim
Purpose
Synopsis

Continue the maximization of an SLP problem
int XPRS_CC XSLPremaxim(XSLPprob Prob, char ⁎Flags);

Arguments
Prob
Flags
ExampleThe current SLP problem.
These have the same meaning as for XSLPmaxim.

The following example optimizes the SLP problem for up to 10 SLP iterations. If it has not converged, it
saves the ﬁle and continues for another 10.
int Status;
XSLPsetintcontrol(Prob, XSLP_ITERLIMIT, 10);XSLPmaxim(Prob,"");XSLPgetintattrib(Prob, XSLP_STATUS, &Status);
if (Status & XSLP_MAXSLPITERATIONS) {XSLPsave(Prob);
XSLPsetintcontrol(Prob, XSLP_ITERLIMIT, 20);XSLPremaxim(Prob,"");}

Further information
This allows Xpress NonLinear to continue the maximization of a problem after it has been terminated,without re-initializing any of the parameters. In particular, the iteration count will resume at the point
where it previously stopped, and not at 1.
Related topics
XSLPmaxim, XSLPreminim

Fair Isaac Corporation Conﬁdential and Proprietary Information301

Library functions and the programming interface

Reference

XSLPreminim
Purpose
Synopsis

Continue the minimization of an SLP problem
int XPRS_CC XSLPreminim(XSLPprob Prob, char ⁎Flags);

Arguments
Prob
Flags
ExampleThe current SLP problem.
These have the same meaning as for XSLPminim.

The following example optimizes the SLP problem for up to 10 SLP iterations. If it has not converged, it
saves the ﬁle and continues for another 10.
int Status;
XSLPsetintcontrol(Prob, XSLP_ITERLIMIT, 10);XSLPminim(Prob,"");XSLPgetintattrib(Prob, XSLP_STATUS, &Status);
if (Status & XSLP_MAXSLPITERATIONS) {XSLPsave(Prob);
XSLPsetintcontrol(Prob, XSLP_ITERLIMIT, 20);XSLPreminim(Prob,"");}

Further information
This allows Xpress NonLinear to continue the minimization of a problem after it has been terminated,without re-initializing any of the parameters. In particular, the iteration count will resume at the point
where it previously stopped, and not at 1.
Related topics
XSLPminim, XSLPremaxim

Fair Isaac Corporation Conﬁdential and Proprietary Information302

Library functions and the programming interface

Reference

XSLPrestore
Purpose
Synopsis

Restore the Xpress NonLinear problem from a ﬁle created by XSLPsave
int XPRS_CC XSLPrestore(XSLPprob Prob, char ⁎Filename);

Arguments
Prob
Filename
ExampleThe current SLP problem.
Character string containing the name of the problem which is to be restored.

The following example restores a problem originally saved on ﬁle "MySave"XSLPrestore(Prob, "MySave");

Further information
Normally XSLPrestore restores both the Xpress NonLinear problem and the underlying optimizer
problem. If only the Xpress NonLinear problem is required, set the integer control variable
XSLP_CONTROL appropriately.
The problem is saved into two ﬁles save.svf which is the optimizer save ﬁle, and save.svx which is the
SLP save ﬁle. Both ﬁles are required for a full restore; only the svx ﬁle is required when the underlying
optimizer problem is not being restored.
Related topics
XSLP_CONTROL, XSLPsave

Fair Isaac Corporation Conﬁdential and Proprietary Information303

Library functions and the programming interface

Reference

XSLPreinitialize
Purpose
Synopsis

Reset the SLP problem to match a just augmented system
int XPRS_CC XSLPreinitialize(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Further information
Can be used to rerun the SLP optimization process with updated parameters, penalties or initial values,
but unchanged augmentation.
Related topics
XSLPcreateprob, XSLPdestroyprob, XSLPunconstruct, XSLPsetcurrentiv,

Fair Isaac Corporation Conﬁdential and Proprietary Information304

Library functions and the programming interface

Reference

XSLPsave
Purpose
Synopsis

Save the Xpress NonLinear problem to ﬁleint XPRS_CC XSLPsave(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example saves the current problem to ﬁles named prob1.svf and prob1.svx.
XPRSprob xprob;XSLPgetptrattrib(Prob, XSLP_XPRSPROBLEM, &xprob);
XPRSsetprobname(xprob, "prob1");
XSLPsave(Prob);

Further information
The problem is saved into two ﬁles prob.svf which is the optimizer save ﬁle, and prob.svx which is the
SLP save ﬁle, where prob is the name of the problem. Both ﬁles are used in a full save; only the svx ﬁle
is required when the underlying optimizer problem is not being saved.
Normally XSLPsave saves both the Xpress NonLinear problem and the underlying optimizer problem.
If only the Xpress NonLinear problem is required, set the integer control variable XSLP_CONTROL
appropriately.
Related topics
XSLP_CONTROL, XSLPrestore XSLPsaveas

Fair Isaac Corporation Conﬁdential and Proprietary Information305Library functions and the programming interface

Reference

XSLPsaveas
Purpose
Synopsis

Save the Xpress NonLinear problem to a named ﬁleint XPRS_CC XSLPsaveas(XSLPprob Prob, const char ⁎Filename);

Arguments
Prob
Filename
ExampleThe current SLP problem.
The name of the ﬁle (without extension) in which the problem is to be saved.

The following example saves the current problem to ﬁles named MyProb.svf and MyProb.svx.
XSLPsaveas(Prob,"MyProb");

Further information
The problem is saved into two ﬁles ﬁlename.svf which is the optimizer save ﬁle, and ﬁlename.svx whichis the SLP save ﬁle, where ﬁlename is the second argument to the function. Both ﬁles are used in a fullsave; only the svx ﬁle is required when the underlying optimizer problem is not being saved.
Normally XSLPsaveas saves both the Xpress NonLinear problem and the underlying optimizer
problem. If only the Xpress NonLinear problem is required, set the integer control variable
XSLP_CONTROL appropriately.
Related topics
XSLP_CONTROL, XSLPrestore XSLPsave

Fair Isaac Corporation Conﬁdential and Proprietary Information

306

Library functions and the programming interface

Reference

XSLPscaling
Purpose
SynopsisAnalyze the current matrix for largest/smallest coefﬁcients and ratios
int XPRS_CC XSLPscaling(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example analyzes the matrix
XSLPscaling(Prob);

Further information
The current matrix (including augmentation if it has been carried out) is scanned for the absolute andrelative sizes of elements. The following information is reported: Largest and smallest elements in the matrix;
 Counts of the ranges of row ratios in powers of 10 (e.g. number of rows with ratio between

1.0E+01 and 1.0E+02);

 List of the rows (with largest and smallest elements) which appear in the highest range; Counts of the ranges of column ratios in powers of 10 (e.g. number of columns with ratio between

1.0E+01 and 1.0E+02);

 List of the columns (with largest and smallest elements) which appear in the highest range;
 Element ranges in powers of 10 (e.g. number of elements between 1.0E+01 and 1.0E+02).

Where any of the reported items (largest or smallest element in the matrix or any reported row orcolumn element) is in a penalty error vector, the results are repeated, excluding all penalty error vectors.

Fair Isaac Corporation Conﬁdential and Proprietary Information307

Library functions and the programming interface

Reference

XSLPsetcbcascadeend
Purpose

Synopsis

Set a user callback to be called at the end of the cascading process, after the last variable has beencascaded
int XPRS_CC XSLPsetcbcascadeend(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the end of the cascading process. UserFunc returns an
integer value. The return value is noted by Xpress-SLP but it has no effect on the
optimization.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbcascadeend.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the end of the cascading process whichchecks if any of the values have been changed signiﬁcantly:
double ⁎cSol;
XSLPsetcbcascadeend(Prob, CBCascEnd, &cSol);A suitable callback function might resemble this:int XPRS_CC CBCascEnd(XSLPprob MyProb, void ⁎Obj) {int iCol, nCol;
double ⁎cSol, Value;
cSol = ⁎ (double ⁎⁎) Obj;XSLPgetintcontrol(MyProb, XPRS_COLS, &nCol);for (iCol=0;iCol<nCol;iCol++) {XSLPgetvar(MyProb, iCol, NULL, NULL, NULL,
NULL, NULL, NULL, &Value,
NULL, NULL, NULL, NULL,
NULL, NULL, NULL, NULL);
if (fabs(Value-cSol[iCol]) > .01)
printf("\nCol %d changed from %lg to %lg",
iCol, cSol[iCol], Value);}
return 0;}
The Object argument is used here to hold the address of the array cSol which we assume has been
populated with the original solution values.

Further information
This callback can be used at the end of the cascading, when all the solution values have beenrecalculated.
Related topics
XSLPcascade, XSLPsetcbcascadestart, XSLPsetcbcascadevar,
XSLPsetcbcascadevarfail

Fair Isaac Corporation Conﬁdential and Proprietary Information308

Library functions and the programming interface

Reference

XSLPsetcbcascadestartPurpose

Synopsis

Set a user callback to be called at the start of the cascading process, before any variables have beencascaded
int XPRS_CC XSLPsetcbcascadestart(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the start of the cascading process. UserFunc returns an
integer value. If the return value is nonzero, the cascading process will be omitted forthe current SLP iteration, but the optimization will continue.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbcascadestart.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the start of the cascading process to savethe current values of the variables:
double ⁎cSol;
XSLPsetcbcascadestart(Prob, CBCascStart, &cSol);A suitable callback function might resemble this:int XPRS_CC CBCascStart(XSLPprob MyProb, void ⁎Obj) {int iCol, nCol;
double ⁎cSol;
cSol = ⁎ (double ⁎⁎) Obj;XSLPgetintcontrol(MyProb, XPRS_COLS, &nCol);for (iCol=0;iCol<nCol;iCol++) {XSLPgetvar(MyProb, iCol, NULL, NULL, NULL,
NULL, NULL, NULL, &cSol[iCol],
NULL, NULL, NULL, NULL,
NULL, NULL, NULL, NULL);}
return 0;}
The Object argument is used here to hold the address of the array cSol which we populate with thesolution values.

Further information
This callback can be used at the start of the cascading, before any of the solution values have beenrecalculated.
Related topics
XSLPcascade, XSLPsetcbcascadeend, XSLPsetcbcascadevar, XSLPsetcbcascadevarfail

Fair Isaac Corporation Conﬁdential and Proprietary Information309

Library functions and the programming interface

Reference

XSLPsetcbcascadevar
Purpose
Synopsis

Set a user callback to be called after each column has been cascaded
int XPRS_CC XSLPsetcbcascadevar(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ColIndex), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ColIndex
ObjectExampleThe current SLP problem.
The function to be called after each column has been cascaded. UserFunc returns an
integer value. If the return value is nonzero, the cascading process will be omitted for theremaining variables during the current SLP iteration, but the optimization will continue.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbcascadevar.
The number of the column which has been cascaded.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed after each variable has been cascaded:double ⁎cSol;
XSLPsetcbcascadevar(Prob, CBCascVar, &cSol);The following sample callback function resets the value of the variable if the cascaded value is of the
opposite sign to the original value:
int XPRS_CC CBCascVar(XSLPprob MyProb, void ⁎Obj, int iCol) {double ⁎cSol, Value;
cSol = ⁎ (double ⁎⁎) Obj;XSLPgetvar(MyProb, iCol, NULL, NULL, NULL,
NULL, NULL, NULL, &Value,
NULL, NULL, NULL, NULL,
NULL, NULL, NULL, NULL);
if (Value ⁎ cSol[iCol] < 0) {Value = cSol[iCol];XSLPchgvar(MyProb, ColNum, NULL, NULL, NULL, NULL,
NULL, NULL, &Value, NULL, NULL, NULL,
NULL);}
return 0;}
The Object argument is used here to hold the address of the array cSol which we assume has been
populated with the original solution values.

Further information
This callback can be used after each variable has been cascaded and its new value has been
calculated.
Related topics
XSLPcascade, XSLPsetcbcascadeend, XSLPsetcbcascadestart,XSLPsetcbcascadevarfail

Fair Isaac Corporation Conﬁdential and Proprietary Information

310

Library functions and the programming interface

Reference

XSLPsetcbcascadevarfail
Purpose
Synopsis

Set a user callback to be called after cascading a column was not successful
int XPRS_CC XSLPsetcbcascadevarfail(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ColIndex), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ColIndex
Object

The current SLP problem.
The function to be called after cascading a column was not successful. UserFunc
returns an integer value. If the return value is nonzero, the cascading process will beomitted for the remaining variables during the current SLP iteration, but the optimization
will continue.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbcascadevarfail.
The number of the column which has been cascaded.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

Further information
This callback can be used to provide user deﬁned updates for SLP variables having a determining row
that were not successfully cascaded due to the determining row being close to singular around thecurrent values. This callback will always be called in place of the cascadevar callback in such cases,
and in no situation will both the cascadevar and the cascadevarfail callback be called in the same
iteration for the same variable.
Related topics
XSLPcascade, XSLPsetcbcascadeend, XSLPsetcbcascadestart, XSLPsetcbcascadevar

Fair Isaac Corporation Conﬁdential and Proprietary Information

311

Library functions and the programming interface

Reference

XSLPsetcbcoefevalerror
Purpose
Synopsis

Set a user callback to be called when an evaluation of a coefﬁcient fails during the solve
int XPRS_CC XSLPsetcbcoefevalerror(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int RowIndex, int ColIndex), void
⁎Object);

Arguments
Prob
UserFunc
myProb
myObject
RowIndex
ColIndex
Object

The current SLP problem.
The function to be called when an evaluation fails.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbcoefevalerror.
The row position of the coefﬁcient.
The column position of the coefﬁcient.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

Further information
This callback can be used to capture when an evaluation of a coefﬁcient fails. The callback is called
only once for each coefﬁcient.
Related topics
XSLPprintevalinfo

Fair Isaac Corporation Conﬁdential and Proprietary Information

312Library functions and the programming interface

Reference

XSLPsetcbconstruct
Purpose
Synopsis

Set a user callback to be called during the Xpress-SLP augmentation process
int XPRS_CC XSLPsetcbconstruct(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called during problem augmentation. UserFunc returns an integer
value. See below for an explanation of the values.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbconstruct.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed during the Xpress-SLP problem augmentation:
double ⁎cValue;
cValue = NULL;XSLPsetcbconstruct(Prob, CBConstruct, &cValue);
The following sample callback function sets values for the variables the ﬁrst time the function is called
and returns to XSLPconstruct to recalculate the initial matrix. The second time it is called it frees the
allocated memory and returns to XSLPconstruct to proceed with the rest of the augmentation.
int XPRS_CC CBConstruct(XSLPprob MyProb, void ⁎Obj) {double ⁎cValue;
int i, n;/⁎ if Object is NULL, this is first-time entry ⁎/if (⁎(void⁎⁎)Obj == NULL) {XSLPgetintattrib(MyProb,XPRS_COLS,&n);cValue = malloc(n⁎sizeof(double));/⁎ ... initialize with values (not shown here) and then ... ⁎/for (i=0;i<n;i++)/⁎ store into SLP structures ⁎/XSLPchgvar(MyProb, i, NULL, NULL, NULL, NULL,
NULL, NULL, &cValue[i], NULL, NULL, NULL,
NULL);/⁎ set Object non-null to indicate we have processed data ⁎/⁎(void⁎⁎)Obj = cValue;
return -1;}
else {/⁎ free memory, clear marker and continue ⁎/free(⁎(void⁎⁎)Obj);⁎(void⁎⁎)Obj = NULL;}
return 0;}

Fair Isaac Corporation Conﬁdential and Proprietary Information

313

Library functions and the programming interface

Reference

Further information
This callback can be used during the problem augmentation, generally (although not exclusively) tochange the initial values for the variables.
The following return codes are accepted:0

Normal return: augmentation continues-1

Return to recalculate matrix values-2

Return to recalculate row weights and matrix entries

other

Error return: augmentation terminates, XSLPconstruct terminates with a nonzero
error code.

The return values -1 and -2 will cause the callback to be called a second time after the matrix has beenrecalculated. It is the responsibility of the callback to ensure that it does ultimately exit with a return
value of zero.
Related topics
XSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information314

Library functions and the programming interface

Reference

XSLPsetcbdestroy
Purpose
Synopsis

Set a user callback to be called when an SLP problem is about to be destroyed
int XPRS_CC XSLPsetcbdestroy(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called when the SLP problem is about to be destroyed. UserFunc
returns an integer value. At present the return value is ignored.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbdestroy.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed before the SLP problem is destroyed:
double ⁎cSol;
XSLPsetcbdestroy(Prob, CBDestroy, &cSol);The following sample callback function frees the memory associated with the user-deﬁned object:
int XPRS_CC CBDestroy(XSLPprob MyProb, void ⁎Obj) {if (⁎(void⁎⁎)Obj) free(⁎(void⁎⁎)Obj);
return 0;}
The Object argument is used here to hold the address of the array cSol which we assume was
assigned using one of the malloc functions.

Further information
This callback can be used when the problem is about to be destroyed to free any user-deﬁned
resources which were allocated during the life of the problem.
Related topics
XSLPdestroyprob

Fair Isaac Corporation Conﬁdential and Proprietary Information

315

Library functions and the programming interface

Reference

XSLPsetcbdrcol
Purpose
Synopsis

Set a user callback used to override the update of variables with small determining column
int XPRS_CC XSLPsetcbdrcol(XSLPprob Prob, int (XPRS_CC ⁎UserFunc) (XSLPprob
myProb, void ⁎myObject, int ColIndex, int DrColIndex, double
DrColValue, double ⁎ NewValue, double VLB, double VUB), void
⁎Object);

Arguments
Prob
UserFunc

The current SLP problem.
The function to be called after each column has been cascaded. UserFunc returns an
integer value. If the return value is positive, it will indicate that the value has been ﬁxed,
and cascading should be omitted for the variable. A negative value indicates that apreviously ﬁxed value has been relaxed. If no action is taken, a 0 return value should be
used.
myProb
The problem passed to the callback function.
myObject
The user-deﬁned object passed as Object to XSLPsetcbcascadevar.
ColIndex
The index of the column for which the determining columns is checked.
DrColIndex The index of the determining column for the column that is being updated.
DrColValue The value of the determining column in the current SLP iteration.
NewValue
Used to return the new value for column ColIndex, should it need to be updated, inwhich case the callback must return a positive value to indicate that this value should be
used.
VLB
The original lower bound of column ColIndex. The callback provides this value as areference, should the bound be updated or changed during the solution process.
VUB
The original upper bound of column ColIndex. The callback provides this value as areference, should the bound be updated or changed during the solution process.
ObjectAddress of a user-deﬁned object, which can be used for any purpose. by the function.
Object is passed to UserFunc as myObject.

Further information
If set, this callback is called as part of the cascading procedure. Please see Chapter Cascading for
more information.
Related topics
XSLP_DRCOLTOL, XSLPcascade, XSLPsetcbcascadeend, XSLPsetcbcascadestart

Fair Isaac Corporation Conﬁdential and Proprietary Information

316

Library functions and the programming interface

Reference

XSLPsetcbintsol
Purpose
Synopsis

Set a user callback to be called during MISLP when an integer solution is obtained
int XPRS_CC XSLPsetcbintsol(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called when an integer solution is obtained. UserFunc returns an
integer value. At present, the return value is ignored.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbintsol.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed whenever an integer solution is found during
MISLP:
double ⁎cSol;
XSLPsetcbintsol(Prob, CBIntSol, &cSol);The following sample callback function saves the solution values for the integer solution just found:
int XPRS_CC CBIntSol(XSLPprob MyProb, void ⁎Obj) {XPRSprob xprob;
double ⁎cSol;
cSol = ⁎ (double ⁎⁎) Obj;XSLPgetptrattrib(MyProb, XSLP_XPRSPROBLEM, &xprob);
XPRSgetsol(xprob, cSol, NULL, NULL, NULL);
return 0;}
The Object argument is used here to hold the address of the array cSol which we assume was
assigned using one of the malloc functions.

Further information
This callback must be used during MISLP instead of the XPRSsetcbintsol callback which is used for
MIP problems.
Related topics
XSLPsetcboptnode, XSLPsetcbprenode

Fair Isaac Corporation Conﬁdential and Proprietary Information

317

Library functions and the programming interface

Reference

XSLPsetcbiterend
Purpose
Synopsis

Set a user callback to be called at the end of each SLP iteration
int XPRS_CC XSLPsetcbiterend(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the end of each SLP iteration. UserFunc returns an integer
value. If the return value is nonzero, the SLP iterations will stop.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbiterend.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the end of each SLP iteration. It records thenumber of LP iterations in the latest optimization and stops if there were fewer than 10:
XSLPsetcbiterend(Prob, CBIterEnd, NULL);
A suitable callback function might resemble this:int XPRS_CC CBIterEnd(XSLPprob MyProb, void ⁎Obj) {int nIter;
XPRSprob xprob;XSLPgetptrattrib(MyProb, XSLP_XPRSPROBLEM, &xprob);
XSLPgetintattrib(xprob, XPRS_SIMPLEXITER, &nIter);if (nIter < 10) return 1;
return 0;}
The Object argument is not used here, and so is passed as NULL.

Further information
This callback can be used at the end of each SLP iteration to carry out any further processing and/or
stop any further SLP iterations.
Related topics
XSLPsetcbiterstart, XSLPsetcbitervar

Fair Isaac Corporation Conﬁdential and Proprietary Information

318

Library functions and the programming interface

Reference

XSLPsetcbiterstartPurpose
Synopsis

Set a user callback to be called at the start of each SLP iteration
int XPRS_CC XSLPsetcbiterstart(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the start of each SLP iteration. UserFunc returns an integer
value. If the return value is nonzero, the SLP iterations will stop.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbiterstart.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the start of the optimization to save to savethe values of the variables from the previous iteration:
double ⁎cSol;
XSLPsetcbiterstart(Prob, CBIterStart, &cSol);A suitable callback function might resemble this:int XPRS_CC CBIterStart(XSLPprob MyProb, void ⁎Obj) {XPRSprob xprob;
double ⁎cSol;
int nIter;cSol = ⁎ (double ⁎⁎) Obj;XSLPgetintattrib(MyProb, XSLP_ITER, &nIter);if (nIter == 0) return 0; /⁎ no previous solution ⁎/XSLPgetptrattrib(MyProb, XSLP_XPRSPROBLEM, &xprob);
XPRSgetsol(xprob, cSol, NULL, NULL, NULL);
return 0;}
The Object argument is used here to hold the address of the array cSol which we populate with thesolution values.

Further information
This callback can be used at the start of each SLP iteration before the optimization begins.
Related topics
XSLPsetcbiterend, XSLPsetcbitervar

Fair Isaac Corporation Conﬁdential and Proprietary Information319

Library functions and the programming interface

Reference

XSLPsetcbitervar
Purpose
Synopsis

Set a user callback to be called after each column has been tested for convergence
int XPRS_CC XSLPsetcbitervar(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ColIndex), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ColIndex
ObjectExampleThe current SLP problem.
The function to be called after each column has been tested for convergence.
UserFunc returns an integer value. The return value is interpreted as a convergencestatus. The possible values are:< 0
The variable has not converged;0
The convergence status of the variable is unchanged;
1 to 10 The column has converged on a system-deﬁned convergence criterion(these values should not normally be returned);> 10
The variable has converged on user criteria.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbitervar.
The number of the column which has been tested for convergence.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed after each variable has been tested forconvergence. The user object Important is an integer array which has already been set up and holds
a ﬂag for each variable indicating whether it is important that it converges.
int ⁎Important;
XSLPsetcbitervar(Prob, CBIterVar, &Important);
The following sample callback function tests if the variable is already converged. If not, then it checks if
the variable is important. If it is not important, the function returns a convergence status of 99.
int XPRS_CC CBIterVar(XSLPprob MyProb, void ⁎Obj, int iCol) {int ⁎Important, Converged;
Important = ⁎(int ⁎⁎) Obj;XSLPgetvar(MyProb, iCol, NULL, NULL, NULL,
NULL, NULL, NULL, NULL,
NULL, NULL, &Converged, NULL,
NULL, NULL, NULL, NULL);
if (Converged) return 0;
if (!Important[iCol]) return 99;
return -1;}
The Object argument is used here to hold the address of the array Important.

Further information
This callback can be used after each variable has been checked for convergence, and allows theconvergence status to be reset if required.
Related topics
XSLPsetcbiterend, XSLPsetcbiterstart

Fair Isaac Corporation Conﬁdential and Proprietary Information320Library functions and the programming interface

Reference

XSLPsetcbmessage
Purpose
Synopsis

Set a user callback to be called whenever Xpress NonLinear outputs a line of text
int XPRS_CC XSLPsetcbmessage(XSLPprob Prob, void (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, char ⁎msg, int len, int msgtype),
void ⁎Object);Arguments
Prob
UserFunc
myProb
myObjectmsg
lenmsgtypeObjectExampleThe current SLP problem.
The function to be called whenever Xpress NonLinear outputs a line of text. UserFunc
does not return a value.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbmessage.
Character buffer holding the string to be output.
Length in characters of msg excluding the null terminator.
Type of message. The following are system-deﬁned:
1
Information message
3
Warning message
4
Error message
A negative value indicates that the Optimizer is about to ﬁnish and any buffers should
be ﬂushed at this time.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example creates a log ﬁle into which all messages are placed. System messages arealso printed on standard output:
FILE ⁎logfile;
logfile = fopen("myLog","w");XSLPsetcbmessage(Prob, CBMessage, logfile);
A suitable callback function could resemble the following:
void XPRS_CC CBMessage(XSLPprob Prob, void ⁎Obj,
char ⁎msg, int len, int msgtype) {FILE ⁎logfile;
logfile = (FILE ⁎) Obj;if (msgtype < 0) {fflush(stdout);
if (logfile) fflush(logfile);
return;}switch (msgtype) {case 1: /⁎ information ⁎/case 3: /⁎ warning ⁎/case 4: /⁎ error ⁎/printf("%s\n",msg);
default: /⁎ user ⁎/if (logfile)fprintf(logfile,"%s\n",msg);
break;

Fair Isaac Corporation Conﬁdential and Proprietary Information321Library functions and the programming interface}

Reference}
return;Further information
If a user message callback is deﬁned then screen output is automatically disabled.
Output can be directed into a log ﬁle by using XSLPsetlogfile.
Related topics
XSLPsetlogfile,

Fair Isaac Corporation Conﬁdential and Proprietary Information322

Library functions and the programming interface

Reference

XSLPsetcbmsjobend
Purpose

Synopsis

Set a user callback to be called every time a new multistart job ﬁnishes. Can be used to overwrite thedefault solution ranking function
int XSLP_CC XSLPsetcbmsjobend(XSLPprob Prob, int (XSLP_CC⁎UserFunc)(XSLPprob myProb, void ⁎myObject,void ⁎pJobObject,const
char ⁎JobDescription,int ⁎Status), void ⁎Object);Arguments
Prob
The current SLP problem.
UserFunc
The function to be called when a new multistart job is created
myProb
The problem passed to the callback function.
myObject
The user-deﬁned object passed as Object to XSLPsetcbmsjobend.
pJobObject Job speciﬁc user-deﬁned object, as speciﬁed in by the multistart job creating API
functions.
JobDescription The description of the problem as speciﬁed in by the multistart job creating API
functions.
StatusUser return status variable:
0 - use the default evaluation of the ﬁnished job
1 - disregard the result and continue
2 - stop the multistart search
Further information
The multistart pool is dynamic, and this callback can be used to load new multistart jobs using thenormal API functions.
Related topics
XSLPsetcbmsjobstart, XSLPsetcbmswinner

Fair Isaac Corporation Conﬁdential and Proprietary Information

323

Library functions and the programming interface

Reference

XSLPsetcbmsjobstartPurpose

Synopsis

Set a user callback to be called every time a new multistart job is created, and the pre-loaded settings
are applied
int XSLP_CC XSLPsetcbmsjobstart(XSLPprob Prob, int (XSLP_CC⁎UserFunc)(XSLPprob myProb, void ⁎myObject,void ⁎pJobObject,const
char ⁎JobDescription,int ⁎Status), void ⁎Object);Arguments
Prob
The current SLP problem.
UserFunc
The function to be called when a new multistart job is created
myProb
The problem passed to the callback function.
myObject
The user-deﬁned object passed as Object to XSLPsetcbmsjobstart.
pJobObject Job speciﬁc user-deﬁned object, as speciﬁed in by the multistart job creating API
functions.
JobDescription The description of the problem as speciﬁed in by the multistart job creating API
functions.
StatusUser return status variable:
0 - normal return, solve the job,
1 - disregard this job and continue,
2 - Stop multistart.
Further information
All mulit-start jobs operation on an independent copy of the original problem, and any modiﬁcation to
the problem is allowed, including structural changes. Please note however, that any modiﬁcation will be
carried over to the base problem, should a modiﬁed problem be declared the winner prob.
Related topics
XSLPsetcbmsjobend, XSLPsetcbmswinner

Fair Isaac Corporation Conﬁdential and Proprietary Information324

Library functions and the programming interface

Reference

XSLPsetcbmswinnerPurpose

Synopsis

Set a user callback to be called every time a new multistart job is created, and the pre-loaded settings
are applied
int XSLP_CC XSLPsetcbmswinner(XSLPprob Prob, int (XSLP_CC⁎UserFunc)(XSLPprob myProb, void ⁎myObject,void ⁎pJobObject,const
char ⁎JobDescription), void ⁎Object);Arguments
Prob
The current SLP problem.
UserFunc
The function to be called when a new multistart job is created
myProb
The problem passed to the callback function.
myObject
The user-deﬁned object passed as Object to XSLPsetcbmswinner.
pJobObject Job speciﬁc user-deﬁned object, as speciﬁed in by the multistart job creating API
functions.
JobDescription The description of the problem as speciﬁed in by the multistart job creating API
functions.
Further information
The multistart pool is dynamic, and this callback can be used to load new multistart jobs using thenormal API functions.
Related topics
XSLPsetcbmsjobstart, XSLPsetcbmsjobend

Fair Isaac Corporation Conﬁdential and Proprietary Information

325

Library functions and the programming interface

Reference

XSLPsetcboptnode
Purpose
Synopsis

Set a user callback to be called during MISLP when an optimal SLP solution is obtained at a node
int XPRS_CC XSLPsetcboptnode(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObjectfeas
ObjectExampleThe current SLP problem.
The function to be called when an optimal SLP solution is obtained at a node.
UserFunc returns an integer value. If the return value is nonzero, or if the feasibility ﬂag
is set nonzero, then further processing of the node will be terminated (it is declaredinfeasible).
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcboptnode.
Address of an integer containing the feasibility ﬂag. If UserFunc sets the ﬂag nonzero,
the node is declared infeasible.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example deﬁnes a callback function to be executed at each node when an SLP optimal
solution is found. If there are signiﬁcant penalty errors in the solution, the node is declared infeasible.
XSLPsetcboptnode(Prob, CBOptNode, NULL);
A suitable callback function might resemble the following:
int XPRS_CC CBOptNode(XSLPprob myProb, void ⁎Obj, int ⁎feas) {double Total, ObjVal;
XSLPgetdblattrib(myProb, XSLP_ERRORCOSTS, &Total);
XSLPgetdblattrib(myProb, XSLP_OBJVAL, &ObjVal);if (fabs(Total) > fabs(ObjVal) ⁎ 0.001 &&fabs(Total) > 1) ⁎feas = 1;
return 0;

Further information
If a node is declared infeasible from the callback function, the cost of exploring the node further will be
avoided.
This callback must be used in place of XPRSsetcboptnode when optimizing with MISLP.
Related topics
XSLPsetcbprenode, XSLPsetcbslpnode

Fair Isaac Corporation Conﬁdential and Proprietary Information326

Library functions and the programming interface

Reference

XSLPsetcbprenode
Purpose

Synopsis

Set a user callback to be called during MISLP after the set-up of the SLP problem to be solved at anode, but before SLP optimization
int XPRS_CC XSLPsetcbprenode(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObjectfeas
ObjectExampleThe current SLP problem.
The function to be called after the set-up of the SLP problem to be solved at a node.
UserFunc returns an integer value. If the return value is nonzero, or if the feasibility ﬂag
is set nonzero, then further processing of the node will be terminated (it is declaredinfeasible).
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbprenode.
Address of an integer containing the feasibility ﬂag. If UserFunc sets the ﬂag nonzero,
the node is declared infeasible.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback function to be executed at each node before the SLP
optimization starts. The array IntList contains a list of integer variables, and the function prints thebounds on these variables.
int ⁎IntList;XSLPsetcbprenode(Prob, CBPreNode, IntList);
A suitable callback function might resemble the following:
int XPRS_CC CBPreNode(XSLPprob myProb, void ⁎Obj, int ⁎feas) {XPRSprob xprob;
int i, ⁎IntList;
double LO, UP;
IntList = (int ⁎) Obj;XSLPgetptrattrib(myProb, XSLP_XPRSPROBLEM, &xprob);for (i=0; IntList[i]>=0; i++) {XPRSgetlb(xprob,&LO,IntList[i],IntList[i]);XPRSgetub(xprob,&UP,IntList[i],IntList[i]);if (LO > 0 || UP < XPRS_PLUSINFINITY)
printf("\nCol %d: %lg <= %lg",LO,UP);}
return 0;}

Further information
If a node can be identiﬁed as infeasible by the callback function, then the initial optimization at thecurrent node is avoided, as well as further exploration of the node.
This callback must be used in place of XPRSsetcbprenode when optimizing with MISLP.
Related topics
XSLPsetcboptnode, XSLPsetcbslpnode

Fair Isaac Corporation Conﬁdential and Proprietary Information327

Library functions and the programming interface

Reference

XSLPsetcbpreupdatelinearization
Purpose
Synopsis

Set a user callback to be called before the linearization is updated
int XPRS_CC XSLPsetcbpreupdatelinearization(XSLPprob Prob, int (XPRS_CC⁎UserFunc) (XSLPprob myProb, void ⁎myObject, int ⁎ifRepeat), void
⁎Object);

Arguments
Prob
UserFunc

myProb
myObject
ifRepeat
Object

The current SLP problem.
The function to be called at the end of the SLP optimization. UserFunc returns an
integer value. If the return value is nonzero, the optimization will return an error codeand the "User Return Code" error will be set.
The problem passed to the callback function.
The user-deﬁned object passed as Object to
If returned nonzero, SLP restart the lienarization update. XSLPsetcbslpend.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

Further information
This callback is intended to be used with user functions, allowing to peak where the functions will be
evaluated, and then asked to redo the linearization. This is usefull for user functions returning their own
partial derivatives implemented in a parallel setup. The callback is called again after the linearization iscomplete with ifRepeat being initialzied to -1, to indicate that any further evaluations are no longer partof updating the linearization.

Fair Isaac Corporation Conﬁdential and Proprietary Information328

Library functions and the programming interface

Reference

XSLPsetcbslpend
Purpose
Synopsis

Set a user callback to be called at the end of the SLP optimization
int XPRS_CC XSLPsetcbslpend(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the end of the SLP optimization. UserFunc returns an
integer value. If the return value is nonzero, the optimization will return an error codeand the "User Return Code" error will be set.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbslpend.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the end of the SLP optimization. It frees thememory allocated to the object created when the optimization began:void ⁎ObjData;
ObjData = NULL;XSLPsetcbslpend(Prob, CBSlpEnd, &ObjData);
A suitable callback function might resemble this:int XPRS_CC CBSlpEnd(XSLPprob MyProb, void ⁎Obj) {void ⁎ObjData;
ObjData = ⁎ (void ⁎⁎) Obj;
if (ObjData) free(ObjData);⁎ (void ⁎⁎) Obj = NULL;
return 0;}

Further information
This callback can be used at the end of the SLP optimization to carry out any further processing orhousekeeping before the optimization function returns.
Related topics
XSLPsetcbslpstart

Fair Isaac Corporation Conﬁdential and Proprietary Information329

Library functions and the programming interface

Reference

XSLPsetcbslpnode
Purpose
Synopsis

Set a user callback to be called during MISLP after the SLP optimization at each node.
int XPRS_CC XSLPsetcbslpnode(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject, int ⁎feas), void ⁎Object);Arguments
Prob
UserFunc

myProb
myObjectfeas
ObjectExampleThe current SLP problem.
The function to be called after the set-up of the SLP problem to be solved at a node.
UserFunc returns an integer value. If the return value is nonzero, or if the feasibility ﬂag
is set nonzero, then further processing of the node will be terminated (it is declaredinfeasible).
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbslpnode.
Address of an integer containing the feasibility ﬂag. If UserFunc sets the ﬂag nonzero,
the node is declared infeasible.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback function to be executed at each node after the SLP
optimization ﬁnishes. If the solution value is worse than a target value (referenced through the user
object), the node is cut off (it is declared infeasible).
double OBJtarget;XSLPsetcbslpnode(Prob, CBSLPNode, &OBJtarget);A suitable callback function might resemble the following:
int XPRS_CC CBSLPNode(XSLPprob myProb, void ⁎Obj, int ⁎feas) {double TargetValue, LPValue;
XSLPgetdblattrib(prob, XPRS_LPOBJVAL, &LPValue);
TargetValue = ⁎ (double ⁎) Obj;
if (LPValue < TargetValue) ⁎feas = 1;
return 0;}

Further information
If a node can be cut off by the callback function, then further exploration of the node is avoided.
Related topics
XSLPsetcboptnode, XSLPsetcbprenode

Fair Isaac Corporation Conﬁdential and Proprietary Information330

Library functions and the programming interface

Reference

XSLPsetcbslpstartPurpose
Synopsis

Set a user callback to be called at the start of the SLP optimization
int XPRS_CC XSLPsetcbslpstart(XSLPprob Prob, int (XPRS_CC ⁎UserFunc)(XSLPprob myProb, void ⁎myObject), void ⁎Object);Arguments
Prob
UserFunc
myProb
myObject
ObjectExampleThe current SLP problem.
The function to be called at the start of the SLP optimization. UserFunc returns an
integer value. If the return value is nonzero, the optimization will not be carried out.
The problem passed to the callback function.
The user-deﬁned object passed as Object to XSLPsetcbslpstart.
Address of a user-deﬁned object, which can be used for any purpose by the function.
Object is passed to UserFunc as myObject.

The following example sets up a callback to be executed at the start of the SLP optimization. It
allocates memory to a user-deﬁned object to be used during the optimization:
void ⁎ObjData;
ObjData = NULL;XSLPsetcbslpstart(Prob, CBSlpStart, &ObjData);
A suitable callback function might resemble this:int XPRS_CC CBSlpStart(XSLPprob MyProb, void ⁎Obj) {void ⁎ObjData;
ObjData = ⁎ (void ⁎⁎) Obj;
if (ObjData) free(ObjData);⁎ (void ⁎⁎) Obj = malloc(99⁎sizeof(double));return 0;}

Further information
This callback can be used at the start of the SLP optimization to carry out any housekeeping before theoptimization actually starts. Note that a nonzero return code from the callback will terminate theoptimization immediately.
Related topics
XSLPsetcbslpend

Fair Isaac Corporation Conﬁdential and Proprietary Information331

Library functions and the programming interface

Reference

XSLPsetcurrentiv
Purpose
Synopsis

Transfer the current solution to initial values
int XPRS_CC XSLPsetcurrentiv(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Further information
Provides a way to set the current iterates solution as initial values, make changes to parameters or to
the underlying nonlinear problem and then rerun the SLP optimization process.
Related topics
XSLPreinitialize, XSLPunconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information332

Library functions and the programming interface

Reference

XSLPsetdblcontrol
Purpose
Synopsis

Set the value of a double precision problem control
int XPRS_CC XSLPsetdblcontrol(XSLPprob Prob, int Param, double dValue);

Arguments
Prob
Param
dValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
Double precision value to be set.

The following example sets the value of the Xpress NonLinear control XSLP_CTOL and of the optimizer
control XPRS_FEASTOL:XSLPsetdblcontrol(Prob, XSLP_CTOL, 0.001);XSLPgetdblcontrol(Prob, XPRS_FEASTOL, 0.005);

Further information
Both SLP and optimizer controls can be set using this function. If an optimizer control is set, the return
value will be the same as that from XPRSsetdblcontrol.
Related topics
XSLPgetdblcontrol, XSLPsetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information333Library functions and the programming interface

Reference

XSLPsetdefaultcontrol
Purpose
Synopsis

Set the values of one SLP control to its default value
int XPRS_CC XSLPsetdefaultcontrol(XSLPprob Prob, int Param);

Arguments
Prob
Param
ExampleThe current SLP problem.
The number of the control to be reset to its default.

The following example reads a problem from ﬁle, sets the XSLP_LOG control, optimizes the problem
and then reads and optimizes another problem using the default setting.
XSLPreadprob(Prob, "Matrix1", "");XSLPsetintcontrol(Prob, XSLP_LOG, 4);
XSLPmaxim(Prob, "");XSLPsetdefaultcontrol(Prob,XSLP_LOG);XSLPreadprob(Prob, "Matrix2", "");XSLPmaxim(Prob, "");

Further information
This function cannot reset the optimizer controls. Use XPRSsetdefaults or
XPRSsetdefaultcontrolas well to reset optimizer controls to their default values.
Related topics
XSLPsetdblcontrol, XSLPsetdefaults, XSLPsetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information334

Library functions and the programming interface

Reference

XSLPsetdefaults
Purpose
Synopsis

Set the values of all SLP controls to their default values
int XPRS_CC XSLPsetdefaults(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example reads a problem from ﬁle, sets some controls, optimizes the problem and thenreads and optimizes another problem using the default settings.
XSLPreadprob(Prob, "Matrix1", "");XSLPsetintcontrol(Prob, XSLP_LOG, 4);
XSLPsetdblcontrol(Prob, XSLP_CTOL, 0.001);XSLPsetdblcontrol(Prob, XSLP_ATOL_A, 0.005);
XSLPmaxim(Prob, "");XSLPsetdefaults(Prob);
XSLPreadprob(Prob, "Matrix2", "");XSLPmaxim(Prob, "");

Further information
This function does not reset the optimizer controls. Use XPRSsetdefaults as well to reset all thecontrols to their default values.
Related topics
XSLPsetdblcontrol, XSLPsetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information

335

Library functions and the programming interface

Reference

XSLPsetfunctionerror
Purpose
Synopsis

Set the function error ﬂag for the problem
int XPRS_CC XSLPsetfunctionerror(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Further information
Once the function error has been set, calculations generally stop and the routines will return to theircaller with a nonzero return code.

Fair Isaac Corporation Conﬁdential and Proprietary Information

336

Library functions and the programming interface

Reference

XSLPsetintcontrol
Purpose
Synopsis

Set the value of an integer problem control
int XPRS_CC XSLPsetintcontrol(XSLPprob Prob, int Param, int iValue);

Arguments
Prob
Param
iValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
The value to be set.

The following example sets the value of the Xpress NonLinear control XSLP_ALGORITHM and of the
optimizer control XPRS_DEFAULTALG:XSLPsetintcontrol(Prob, XSLP_ALGORITHM, 934);
XSLPsetintcontrol(Prob, XPRS_DEFAULTALG, 3);

Further information
Both SLP and optimizer controls can be set using this function. If an optimizer control is requested, thereturn value will be the same as that from XPRSsetintcontrol.
Related topics
XSLPgetintcontrol, XSLPsetdblcontrol, XSLPsetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information

337

Library functions and the programming interface

Reference

XSLPsetlogﬁlePurpose
SynopsisDeﬁne an output ﬁle to be used to receive messages from Xpress NonLinear
int XPRS_CC XSLPsetlogfile(XSLPprob Prob, char ⁎Filename, int Option);Arguments
Prob
FileName
OptionExampleThe current SLP problem.
Character string containing the name of the ﬁle to be used for output.
Option to indicate whether the output is directed to the ﬁle only (Option=0) or (inconsole mode) to the console as well (Option=1).

The following example deﬁnes a log ﬁle "MyLog1" and directs output to the ﬁle and to the console:XSLPsetlogfile(Prob, "MyLog1", 1);

Further information
If Filename is NULL, the current log ﬁle (if any) will be closed, and message handling will revert to thedefault mechanism.
Related topics
XSLPsetcbmessage

Fair Isaac Corporation Conﬁdential and Proprietary Information

338

Library functions and the programming interface

Reference

XSLPsetparam
Purpose
Synopsis

Set the value of a control parameter by nameint XPRS_CC XSLPsetparam(XSLPprob Prob, const char ⁎Param, const char⁎cValue);

Arguments
Prob
Param
cValueExampleThe current SLP problem.
Name of the control or attribute whose value is to be returned.
Character buffer containing the value.

The following example sets the value of XSLP_ALGORITHM:
XSLPprob Prob;
int Algorithm;
char Buffer[32];Algorithm = 934;
sprintf(Buffer,"%d",Algorithm);
XSLPsetparam(Prob, "XSLP_ALGORITHM", Buffer);

Further information
This function can be used to set any Xpress NonLinear or Optimizer control. The value is always
passed as a character string. It is the user’s responsibility to create the character string in an
appropriate format.
Related topics
XSLPsetdblcontrol, XSLPsetintcontrol, XSLPsetparam, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information339

Library functions and the programming interface

Reference

XSLPsetstrcontrol
Purpose
Synopsis

Set the value of a string problem control
int XPRS_CC XSLPsetstrcontrol(XSLPprob Prob, int Param, const char⁎cValue);

Arguments
Prob
Param
cValueExampleThe current SLP problem.
control (SLP or optimizer) whose value is to be returned.
Character buffer containing the value.

The following example sets the value of the Xpress NonLinear control XSLP_CVNAME and of the
optimizer control XPRS_MPSOBJNAME:XSLPsetstrcontrol(Prob, XSLP_CVNAME, "CharVars");
XSLPsetstrcontrol(Prob, XPRS_MPSOBJNAME, "_OBJ_");

Further information
Both SLP and optimizer controls can be set using this function. If an optimizer control is requested, thereturn value will be the same as that from XPRSsetstrcontrol.
Related topics
XSLPgetstrcontrol, XSLPsetdblcontrol, XSLPsetintcontrol, XSLPsetstrcontrol

Fair Isaac Corporation Conﬁdential and Proprietary Information340

Library functions and the programming interface

Reference

XSLPunconstruct
Purpose
Synopsis

Removes the augmentation and returns the problem to its pre-linearization state
int XPRS_CC XSLPunconstruct(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Further information
Only limited changes are allowed to an augmented problem.
Related topics
XSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information341

Library functions and the programming interface

Reference

XSLPupdatelinearization
Purpose
Synopsis

Updates the current linearization
int XPRS_CC XSLPupdatelinearization(XSLPprob Prob);

Argument
Prob

The current SLP problem.

Further information
Updates the augmented probem (the linearization) to match the current base point. The base point is
the current SLP solution. The values of the SLP variables can be changed using XSLPchgvar.
The linearization must be present, and this function can only be called after the problem has been
augmented by XSLPconstruct.
Related topics
XSLPconstruct

Fair Isaac Corporation Conﬁdential and Proprietary Information342

Library functions and the programming interface

Reference

XSLPvalidate
Purpose
Synopsis

Validate the feasibility of constraints in a converged solution
int XPRS_CC XSLPvalidate(XSLPprob Prob);

Argument
Prob
ExampleThe current SLP problem.

The following example sets the validation tolerance parameters, validates the converged solution andretrieves the validation indices.
double IndexA, IndexR;XSLPsetdblcontrol(Prob, XSLP_VALIDATIONTOL_A, 0.001);XSLPsetdblcontrol(Prob, XSLP_VALIDATIONTOL_R, 0.001);XSLPvalidate(Prob);
XSLPgetdblattrib(Prob, XSLP_VALIDATIONINDEX_A, &IndexA);XSLPgetdblattrib(Prob, XSLP_VALIDATIONINDEX_R, &IndexR);

Further information
XSLPvalidate checks the feasibility of a converged solution against relative and absolute tolerancesfor each constraint. The left hand side and the right hand side of the constraint are calculated using theconverged solution values. If the calculated values imply that the constraint is infeasible, then the
difference (D) is tested against the absolute and relative validation tolerances.
If D < XSLP_VALIDATIONTOL_A
then the constraint is within the absolute validation tolerance. The total positive (TPos) and negative
contributions (TNeg) to the left hand side are also calculated.
If D < MAX(ABS(TPos), ABS(TNeg)) ∗ XSLP_VALIDATIONTOL_R
then the constraint is within the relative validation tolerance. For each constraint which is outside boththe absolute and relative validation tolerances, validation factors are calculated which are the factors
by which the infeasibility exceeds the corresponding validation tolerance; the smallest factor is printed
in the validation report.
The validation index XSLP_VALIDATIONINDEX_A is the largest absolute validation factor multipliedby the absolute validation tolerance; the validation index XSLP_VALIDATIONINDEX_R is the largest
relative validation factor multiplied by the relative validation tolerance.
Related topics
XSLP_VALIDATIONINDEX_A, XSLP_VALIDATIONINDEX_R, XSLP_VALIDATIONTOL_A,XSLP_VALIDATIONTOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information343

Library functions and the programming interface

Reference

XSLPvalidatekkt
Purpose

Synopsis

Validates the ﬁrst order optimality conditions also known as the Karush-Kuhn-Tucker (KKT) conditions
versus the currect solution
int XPRS_CC XSLPvalidatekkt(XSLPprob Prob, int iCalculationMode, int
iRespectBasisStatus, int iUpdateMultipliers, double
dKKTViolationTarget);Arguments
Prob
The current SLP problem.
iCalculationMode The calculation mode can be:0recalculate the reduced costs at the current solution using the current dual
solution.
1minimize the sum of KKT violations by adjusting the dual solution.
2
perform both.
iRespectBasisStatus The following ways are deﬁned to assess if a constraint is active:
0
evaluate the recalculated slack activity versus XSLP_ECFTOL_R.
1
use the basis status of the slack in the linearized problem if available.
2
use both.
iUpdateMultipliers The calculated values can be:0
only used to calculate the XSLP_VALIDATIONINDEX_K measure.
1
used to update the current dual solution and reduced costs.
dKKTViolationTarget When calculating the best KKT multipliers, it is possible to enforce an even
distribution of reduced costs violations by enforcing a bound on them.
Further information
The bounds enforced by dKKTViolationTarget are automatically relaxed if the desired accuracy cannot
be achieved.

Fair Isaac Corporation Conﬁdential and Proprietary Information344

Library functions and the programming interface

Reference

XSLPvalidateprob
Purpose
Synopsis

Validates the current problem formulation and statement
int XPRS_CC XSLPvalidateprob(XSLPprob Prob, int ⁎nErrors, int ⁎nWarnings);

Arguments
Prob
nErrors
nWarnings

The current SLP problem.
Returns the number of errors found in the problem. Errors are expected to make theproblem not solve.
Returns the number of potential issues found in the problem. The solver may be able toautomatically recover during the solve.

Further information
This function is expected to be used in the development stage of a model.

Fair Isaac Corporation Conﬁdential and Proprietary Information

345

Library functions and the programming interface

Reference

XSLPvalidaterow
Purpose
Synopsis

Prints an extensive analysis on a given constraint of the SLP problem
int XPRS_CC XSLPvalidate(XSLPprob Prob, int Row);

Arguments
Prob
Row

The current SLP problem.
The index of the row to be analyzed

Further information
The analysis will include the readable format of the original constraint and the augmented constraint.
For infeasible constraints, the absolute and relative infeasibility is calculated. Variables in theconstraints are listed including their value in the solution of the last linearization, the internal value (e.g.
cascaded), reduced cost, step bound and convergence status. Scaling analysis is also provided.

Fair Isaac Corporation Conﬁdential and Proprietary Information

346

Library functions and the programming interface

Reference

XSLPvalidatevector
Purpose
Synopsis

Validate the feasibility of constraints for a given solution
int XPRS_CC XSLPvalidate(XSLPprob Prob, double ⁎Vector, double ⁎SumInf,
double ⁎SumScaledInf, double ⁎Objective);

Arguments
Prob
Vector
SumInf

The current SLP problem.
A vector of length XPRS_COLS containing the solution vector to be checked.
Pointer to double in which the sum of infeasibility will be returned. May be NULL if not
required.
SumScaledInf Pointer to double in which the sum of scaled (relative) infeasibility will be returned.
May be NULL if not required.
Objective Pointer to double in which the net objective will be returned. May be NULL if not required.

Further information
XSLPvalidatevector works the same way as XSLPvalidate, and will update
XSLP_VALIDATIONINDEX_A and XSLP_VALIDATIONINDEX_R.
Related topics
XSLP_VALIDATIONINDEX_A, XSLP_VALIDATIONINDEX_R, XSLP_VALIDATIONTOL_A,XSLP_VALIDATIONTOL_R

Fair Isaac Corporation Conﬁdential and Proprietary Information

347

Library functions and the programming interface

Reference

XSLPwriteprob
Purpose
SynopsisWrite the current problem to a ﬁle in extended MPS or text format
int XPRS_CC XSLPwriteprob(XSLPprob Prob, char ⁎Filename, char ⁎Flags);

Arguments
Prob
Filename

Flags

ExampleThe current SLP problem.
Character string holding the name of the ﬁle to receive the output. The extension ".mat"
will automatically be appended to the ﬁle name, except for "text" format when ".txt" will
be appended.
The following ﬂags can be used:awrite the current approximation (linearized) matrix (the default is to write
the non-linear matrix including formulae);o
one coefﬁcient per line (the default is up to two numbers or one formula
per line);lwrite the matrix in the tradition LP like format. Similar to the "text" format,
with more SLP speciﬁc informations"scrambled" names (the default is to use the names provided on input);twrite the matrix in "text" (the default is to write extended MPS format).

The following example reads a problem from ﬁle, augments it and writes the augmented (linearized)
matrix in text form to ﬁle "output.txt":
XSLPreadprob(Prob, "Matrix", "");XSLPconstruct(Prob);
XSLPwriteprob(Prob, "output", "lt");

Further information
The t ﬂag is used to produce a "human-readable" form of the problem. It is similar to the lp format of
XPRSwriteprob, but does not contain all the potential complexities of the Extended MPS Format, so
the resulting ﬁle cannot be used for input. A quadratic objective is written with its true coefﬁcients (notscaled by 2 as in the equivalent lp format).
Related topics
XSLPreadprob

Fair Isaac Corporation Conﬁdential and Proprietary Information348

Library functions and the programming interface

Reference

XSLPwriteslxsol
Purpose
SynopsisWrite the current solution to an MPS like ﬁle format
int XPRS_CC XSLPwriteslxsol(XSLPprob Prob, char ⁎Filename, char ⁎Flags);

Arguments
Prob
Filename

Flags

The current SLP problem.
Character string holding the name of the ﬁle to receive the output. The extension ".slx"
will automatically be appended to the ﬁle name, unless an extension is already speciﬁedin the ﬁlename.
The following ﬂags can be used:p
Use double precision numbers

Fair Isaac Corporation Conﬁdential and Proprietary Information

349

CHAPTER 22

Internal Functions
Xpress NonLinear provides a set of standard functions for use in formulae. Many are standard
mathematical functions; there are a few which are intended for specialized applications.
The following is a list of all the Xpress NonLinear internal functions:ABS

Absolute valuep. 359ARCCOS

Arc cosine trigonometric function

p. 352

ARCSIN

Arc sine trigonometric function

p. 353

ARCTAN

Arc tangent trigonometric function

p. 354COS

Cosine trigonometric function

p. 355ERF

The error function

p. 360ERFC

The complementary error function

p. 361

EXP

Exponential function (e raised to the power)p. 362LN

Natural logarithmp. 363

LOG, LOG10

Logarithm to base 10

p. 364MAX

Maximum value of two or more expressions

p. 365MIN

Minimum value of two or more expressions

p. 366PWL

The piecewise linear function

p. 367SIGN

The sign function

p. 368SIN

Sine trigonometric function

p. 356SQRT

Square rootp. 369TAN

Tangent trigonometric function

p. 357

Fair Isaac Corporation Conﬁdential and Proprietary Information

350

Internal Functions

22.1

Reference

Trigonometric functions
The trigonometric functions SIN, COS and TAN return the value corresponding to their argument inradians. SIN and COS are well-deﬁned, continuous and differentiable for all values of their arguments;
care must be exercised when using TAN because it is discontinuous.
The inverse trigonometric functions ARCSIN and ARCCOS are undeﬁned for arguments outside therange -1 to +1 and special care is required to ensure that no attempt is made to evaluate them outside
this range. Derivatives for the inverse trigonometric functions are always calculated numerically.

Fair Isaac Corporation Conﬁdential and Proprietary Information

351

Internal Functions

Reference

ARCCOS
Purpose
Synopsis

Arc cosine trigonometric function
ARCSIN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Return value
A value in the range 0 to +π.
Further information
value must be in the range -1 to +1. Values outside the range will return zero and produce anappropriate error message. If XSLP_STOPOUTOFRANGE is set then the function error ﬂag will be set.

Fair Isaac Corporation Conﬁdential and Proprietary Information

352

Internal Functions

Reference

ARCSIN
Purpose
Synopsis

Arc sine trigonometric function
ARCSIN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Return value
A value in the range –π/2 to +π/2.
Further information
value must be in the range -1 to +1. Values outside the range will return zero and produce anappropriate error message. If XSLP_STOPOUTOFRANGE is set then the function error ﬂag will be set.

Fair Isaac Corporation Conﬁdential and Proprietary Information

353

Internal Functions

Reference

ARCTAN
Purpose
Synopsis

Arc tangent trigonometric function
ARCTAN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Return value
A value in the range –π/2 to +π/2.

Fair Isaac Corporation Conﬁdential and Proprietary Information

354

Internal Functions

Reference

COS
Purpose
Synopsis

Cosine trigonometric function
COS(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

355

Internal Functions

Reference

SIN
Purpose
Synopsis

Sine trigonometric function
SIN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

356

Internal Functions

Reference

TAN
Purpose
SynopsisTangent trigonometric function
TAN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

357

Internal Functions

22.2

Reference

Other mathematical functions
Most of the mathematical functions are differentiable, although care should be taken in using analytic
derivatives where the derivative is changing rapidly.

Fair Isaac Corporation Conﬁdential and Proprietary Information

358

Internal Functions

Reference

ABS
Purpose
Synopsis

Absolute value
ABS(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Further information
ABS is not always differentiable and so alternative modeling approaches should be used where
possible.

Fair Isaac Corporation Conﬁdential and Proprietary Information

359

Internal Functions

Reference

ERF
Purpose
Synopsis

The error function
ERF(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

360

Internal Functions

Reference

ERFC
Purpose
Synopsis

The complementary error function
ERFC(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

361

Internal Functions

Reference

EXP
Purpose
SynopsisExponential function (e raised to the power)
EXP(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

362

Internal Functions

Reference

LN
Purpose
SynopsisNatural logarithm
LN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Further information
value must be strictly positive (greater than 1.0E-300).

Fair Isaac Corporation Conﬁdential and Proprietary Information

363

Internal Functions

Reference

LOG, LOG10
Purpose
Synopsis

Logarithm to base 10
LOG(value)
LOG10(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Further information
value must be strictly positive (greater than 1.0E-300).

Fair Isaac Corporation Conﬁdential and Proprietary Information

364

Internal Functions

ReferenceMAX
Purpose
SynopsisMaximum value of two or more expressions
MAX(value1, value2)

Argument
value1, value2 Each argument is one of the following: a constant; a variable; a formula evaluating
to a single value
Further information
MAX is not always differentiable and so alternative modeling approaches should be used where
possible.
In mmxnlp, fmax is used to represent the max function.

Fair Isaac Corporation Conﬁdential and Proprietary Information

365

Internal Functions

Reference

MIN
Purpose
Synopsis

Minimum value of two or more expressions
MIN(value1, value2)

Argument
value1, value2 Each argument is one of the following: a constant; a variable; a formula evaluating
to a single value
Further information
MIN is not always differentiable and so alternative modeling approaches should be used where
possible.
In mmxnlp, fmin is used to represent the min function.

Fair Isaac Corporation Conﬁdential and Proprietary Information

366

Internal Functions

Reference

PWL
Purpose
Synopsis

The piecewise linear function
PWL( variable, x1, y1, ..., xk, yk )Arguments
variable
is a single variable that describes where the pwl shold be evaluated.
x1,y2, ..., xk, yk are the k breakpoints of the piecewise linear function. The pwl is extended
to minus and plus inﬁnity using the ﬁrst and last 2 breakpoints respectively.

Fair Isaac Corporation Conﬁdential and Proprietary Information

367

Internal Functions

Reference

SIGN
Purpose
Synopsis

The sign function
SIGN(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Fair Isaac Corporation Conﬁdential and Proprietary Information

368

Internal Functions

Reference

SQRT
Purpose
SynopsisSquare root
SQRT(value)

Argumentvalue

One of the following: a constant; a variable; a formula evaluating to a single value

Further information
value must be non-negative.

Fair Isaac Corporation Conﬁdential and Proprietary Information

369

CHAPTER 23

Error Messages
If the optimization procedure or some other library function encounters an error, then the procedurenormally terminates with a nonzero return code and sets an error code. For most functions, the returncode is 32 for an error; those functions which can return Optimizer return codes (such as the functions
for accessing attributes and controls) will return the Optimizer code in such circumstances.
If an error message is produced, it will normally be output to the message handler; for console-based
output, it will appear on the console. The error message and the error code can also be obtained using
the function XSLPgetlasterror. This allows the user to retrieve the message number and/or themessage text. The format is:
XSLPgetlasterror(Prob, &ErrorCode, &ErrorMessage);

The following is a list of the error codes and an explanation of the message. In the list, error numbers
are preﬁxed by E- and warnings by W-. The printed messages are generally preﬁxed by Xpress
NonLinear error and Xpress NonLinear warning respectively.
E-12001

invalid parameter number num
This message is produced by the functions which access SLP or Optimizer controls andattributes. The parameter numbers for SLP are given in the header ﬁle xslp.h. The
parameter is of the wrong type for the function, or cannot be changed by the user.

E-12002

internal hash error
This is a non-recoverable program error. If this error is encountered, please contact your local
Xpress support ofﬁce.

E-12003

XSLPprob problem pointer is NULL
The problem pointer has not been initialized and contains a zero address. Initialize theproblem using XSLPcreateprob.

E-12004

XSLPprob is corrupted or is not a valid problem
The problem pointer is not the address of a valid problem. The problem pointer has beencorrupted, and no longer contains the correct address; or the problem has not been initialized
correctly; or the problem has been corrupted in memory. Check that your program is using thecorrect pointer and is not overwriting part of the memory area.

E-12005

memory manager error - allocation error
This message normally means that the system has run out of memory when trying to allocate
or reallocate arrays. Use XSLPprintmemory to obtain a list of the arrays and amounts ofmemory allocated by the system. Ensure that any memory allocated by user programs is
freed at the appropriate time.

E-12006

memory manager error - Array expansion size (num) ≤ 0This may be caused by incorrect setting of the XSLP_EXTRA⁎ control parameters to negative
numbers. Use XSLPprintmemory to obtain a list of the arrays and amounts of memory

Fair Isaac Corporation Conﬁdential and Proprietary Information

370

Error Messages

Reference

allocated by the system for the speciﬁed array. If the problem persists, please contact yourlocal Xpress support ofﬁce.
E-12007

memory manager error - object Obj size not deﬁned
This is a non-recoverable program error. If this error is encountered, please contact your local
Xpress support ofﬁce.

E-12008

cannot open ﬁle name
This message appears when Xpress NonLinear is required to open a ﬁle of any type andencounters an error while doing so. Check that the ﬁle name is spelt correctly (including thepath, directory or folder) and that it is accessible (for example, not locked by anotherapplication).

E-12009cannot open problem ﬁle name
This message is produced by XSLPreadprob if it cannot ﬁnd name.mat, name.mps orname. Note that "lp" format ﬁles are not accepted for SLP input.

E-12010internal I/O error
This error is produced by XSLPreadprob if it is unable to read or write intermediate ﬁlesrequired for input.

E-12011XSLPreadprob unknown record type name
This error is produced by XSLPreadprob if it encounters a record in the ﬁle which is not
identiﬁable. It may be out of place (for example, a matrix entry in the BOUNDS section), or it
may be a completely invalid record type.

E-12012XSLPreadprob invalid function argument type name
This error is produced by XSLPreadprob if it encounters a user function deﬁnition with anargument type that is not one of NULL, DOUBLE, INTEGER, CHAR or VARIANT.

E-12013XSLPreadprob invalid function linkage type name
This error is produced by XSLPreadprob if it encounters a user function with a linkage typethat is not one of DLL, XLS, XLF, MOSEL or COM.

E-12014XSLPreadprob unrecognized function name
This error is produced by XSLPreadprob if it encounters a function reference in a formulawhich is not a pre-deﬁned internal function nor a deﬁned user function. Check the formulaand the function name, and deﬁne the function if required.

E-12015

func: item num out of range
This message is produced by the Xpress NonLinear function func which is referencing the
SLP item (row, column variable, etc). The index provided is out of range (less than 1 unlesszero is explicitly allowed, or greater than the current number of items of that type). Rememberthat most Xpress NonLinear items count from 1.

E-12016

missing left bracket in formulaThis message is produced during parsing of formulae provided in character or unparsed
internal format. A right bracket is not correctly paired with a corresponding left bracket.
Check the formulae.

E-12017

missing left operand in formulaThis message is produced during parsing of formulae provided in character or unparsed
internal format. An operator which takes two operands is missing the left hand one (and so
immediately follows another operator or a bracket). Check the formulae.

E-12018

missing right operand in formulaThis message is produced during parsing of formulae provided in character or unparsed
internal format. An operator is missing the right hand (following) operand (and so isimmediately followed by another operator or a bracket). Check the formulae.

Fair Isaac Corporation Conﬁdential and Proprietary Information

371

Error Messages

Reference

E-12019

missing right bracket in formulaThis message is produced during parsing of formulae provided in character or unparsed
internal format. A left bracket is not correctly paired with a corresponding right bracket.
Check the formulae.

E-12020column #n is deﬁned more than once as an SLP variableThis message is produced by XSLPaddvars or XSLPloadvars if the same column appears
more than once in the list, or has already been deﬁned as an SLP variable. Although
XSLPchgvar is less efﬁcient, it can be used to set the properties of an SLP variable whether
or not it has already been declared.

E-12021row #num is deﬁned more than once as an SLP delayed constraint
This message is produced by the deprecated XSLPadddcs or XSLPloaddcs if the same row
appears more than once in the list, or has already been deﬁned as a delayed constraint.
Although XSLPchgdc is less efﬁcient, it can be used to set the properties of an SLP delayed
constraint whether or not it has already been declared.

E-12022

undeﬁned tolerance type name
This error is produced by XSLPreadprob if it encounters a tolerance which is not one of the
9 deﬁned types (TC, TA, TM, TI, TS, RA, RM, RI, RS). Check the two-character code for thetolerance.

W-12023

name has been given a tolerance but is not an SLP variableThis error is produced by XSLPreadprob if it encounters a tolerance for a variable which is
not an SLP variable (it is not in a coefﬁcient, it does not have a non-constant coefﬁcient and it
has not been given an initial value). If the tolerance is required (that is, if the variable is to bemonitored for convergence) then give it an initial value so that it becomes an SLP variable.
Otherwise, the tolerance will be ignored.

W-12024name has been given SLP data of type ty but is not an SLP variableThis error is produced by XSLPreadprob if it encounters SLPDATA for a variable which has
not been deﬁned as an SLP variable. Typically, this is because the variable would only appear
in coefﬁcients, and the relevant coefﬁcients are missing. The data item will be ignored.

E-12025

func has the same source and destination problems
This message is produced by XSLPcopycallbacks, XSLPcopycontrols and
XSLPcopyprob if the source and destination problems are the same. If they are the same,then there is no point in copying them.

E-12026

invalid or corrupt SAVE ﬁleThis message is produced by XSLPrestore if the SAVE ﬁle header is not valid, or if internalconsistency checks fail. Check that the ﬁle exists and was created by XSLPsave.

E-12027

SAVE ﬁle version is too oldThis message is produced by XSLPrestore if the SAVE ﬁle was produced by an earlier
version of Xpress NonLinear. In general, it is not possible to restore a ﬁle except with thesame version of the program as the one which SAVEd it.

W-12028

problem already has augmented SLP structureThis message is produced by XSLPconstruct if it is called for a second time for the sameproblem. The problem can only be augmented once, which must be done after all thevariables and coefﬁcients have been loaded. XSLPconstruct is called automatically by
XSLPmaxim and XSLPminim if it has not been called earlier.

E-12029

zero divisor
This message is produced by the formula evaluation routines if an attempt is made to divide
by a value less than XSLP_ZERO. A value of +/-XSLP_INFINITY is returned as the result andthe calculation continues.

Fair Isaac Corporation Conﬁdential and Proprietary Information

372

Error Messages

Reference

E-12030

negative number, fractional exponent - truncated to integer
This message is produced by the formula evaluation routines if an attempt is made to raise anegative number to a non-integer exponent. The exponent is truncated to an integer value andthe calculation continues.

E-12031binary search failed
This is a non-recoverable program error. If this error is encountered, please contact your local
Xpress support ofﬁce.

E-12032

wrong number (num) of arguments to function func
This message is produced by the formula evaluation routines if a formula contains the wrong
number of arguments for an internal function (for example, SIN(A, B)). Correct the formula.

E-12033

argument value out of range in function func
This message is produced by the formula evaluation routines if an internal function is calledwith an argument outside the allowable range (for example, LOG of a negative number). The
function will normally return zero as the result and, if XSLP_STOPOUTOFRANGE is set, will set
the function error ﬂag.

W-12034

terminated following user return code num
This message is produced by XSLPmaxim and XSLPminim if a nonzero value is returned by
the callback deﬁned by XSLPsetcbiterend or XSLPsetcbslpend.

E-12037

failed to load library/ﬁle/program "name" containing function "func"
This message is produced if a user function is deﬁned to be in a ﬁle, but Xpress NonLinear
cannot the speciﬁed ﬁle. Check that the correct ﬁle name is speciﬁed (also check the searchpaths such as $PATH and %path% if necessary).
This message may also be produced if the speciﬁed library exists but is dependent onanother library which is missing.

E-12038function "func" is not correctly deﬁned or is not in the speciﬁed location
This message is produced if a user function is deﬁned to be in a ﬁle, but Xpress NonLinear
cannot ﬁnd it in the ﬁle. Check that the number and type of the arguments is correct, and thatthe (external) name of the user function matches the name by which it is known in the ﬁle.

E-12084

Xpress NonLinear has not been initialized
An attempt has been made to use Xpress NonLinear functions without a previous call to
XSLPinit. Only a very few functions can be called before initialization. Check the sequenceof calls to ensure that XSLPinit is called ﬁrst, and that it completed successfully. This error
message normally produces return code 279.

E-12085

Xpress NonLinear has not been licensed for use here
Either Xpress NonLinear is not licensed at all (although the Xpress Optimizer may belicensed), or the particular feature (such as MISLP) is not licensed. Check the license andcontact the local Fair Isaac sales ofﬁce if necessary. This error message normally produces
return code 352.

E-12105

Xpress NonLinear error: I/O error on file
The message is produced by XSLPsave or XSLPwriteprob if there is an I/O error whenwriting the output ﬁle (usually because there is insufﬁcient space to write the ﬁle).

E-12107

Xpress NonLinear error: user function type name not supported on this platform
This message is produced if a user function deﬁned as being of type XLS, XLF or COM and is
run on a non-Windows platform.

E-12110

Xpress NonLinear error: unidentiﬁed section in REVISE: name
The ﬁle provided to XSLPrevise contains an unsupported MPS section.

E-12111

Xpress NonLinear error: unidentiﬁed row type in REVISE: name
The ﬁle provided to XSLPrevise contains an unsupported row type.

Fair Isaac Corporation Conﬁdential and Proprietary Information

373

Error Messages

Reference

E-12112

Xpress NonLinear error: unidentiﬁed row in REVISE: name
The ﬁle provided to XSLPrevise contains a row name not found in the current problem.

E-12113

Xpress NonLinear error: unidentiﬁed bound in REVISE: name
The ﬁle provided to XSLPrevise contains an unsupported bound type.

E-12114

Xpress NonLinear error: unidentiﬁed column in REVISE: name
The ﬁle provided to XSLPrevise contains a column name not found in the current problem.

E-12121

Xpress NonLinear error: bad return code num from user function func
This message is produced during evaluation of a complicated user function if it returns avalue (-1) indicating that the system should estimate the result from a previous function call,but there has been no previous function call.

E-12124

Xpress NonLinear error: augmented problem not set up
The message is produced by XSLPvalidate if an attempt is made to validate the problem
without a preceding call to XSLPconstruct. In fact, unless a solution to the linearized
problem is available, XSLPvalidate will not be able to give useful results.

E-12125

Xpress NonLinear error: user function func terminated with errors
This message is produced during evaluation of a user function if it sets the function error ﬂag(see XSLPsetfunctionerror).

W-12142

Xpress NonLinear warning: invalid record: text
This error is produced by XSLPreadprob if it encounters a record in the ﬁle which is
identiﬁable but invalid (for example, a BOUNDS record without a bound set name). The record
is ignored.

E-12147

Xpress NonLinear error: incompatible arguments in user function func
This message is produced if a user function is called by XSLPcalluserfunc but thefunction call does not provide the arguments required by the function.

E-12158

Xpress NonLinear error: unknown parameter name name
This message is produced if an attempt is made to set or retrieve a value for a control
parameter or attribute given by name where the name is incorrect.

E-12159

Xpress NonLinear error: unknown parameter type name
A parameter has an unexpected type and cannot be retrieved. This is an internal error, pleasecontanct FICO support.

E-12159

Xpress NonLinear error: parameter number is not writable
This message is produced if an attempt is made to set a value for an attribute.

E-12160

Xpress NonLinear error: parameter num is not available
This message is produced if an attempt is made to retrieve a value for a control or attributewhich is not readable

E-12161

Xpress NonLinear error: parameter num is not available
The parameter corresponding to the provided ID is aninternal, not readable parameter.

E-12192

Xpress NonLinear error: no problem or solution readNo problem or solution has been read. If a problem read fails, it is not valid to continue withany problem building or solving functions.

E-12193

Xpress NonLinear error: this version of SLP requires XPRS version num or newer
Altough not recommended, Xpress SLP can work with different xprs library versions. Thiserror is issued when a tool old xpres library is found.

E-12194

Xpress NonLinear error: provided buffer is too short
The provided buffer is too short. This error may occur if a formula is retrieved from Xpress,
into a buffer that is not large enough.

Fair Isaac Corporation Conﬁdential and Proprietary Information

374

Error Messages

Reference

E-12195

Xpress NonLinear error: type index value is invalid
The index provided is not valid for the this type.

E-12196

Xpress NonLinear error: error in problem transformation
An error occurred while the problem was attempted to be reformulated as part of thenonlinear presolver. Please contact FICO support.

E-12197

Xpress NonLinear error: request index invalid
The requested information cannot be retrieved as it is not valid or not availanble.

E-12198

Xpress NonLinear error: error while cascading. Cannot evaluate coefﬁcient at row rowname
column.
Evaluating an expression in cascading has returned an error. There is likely a user function in
the expression returning an error.

E-12199

Xpress NonLinear error: nonlinear coefﬁcient in neutral objective row ’rowname’. Pleaseuse an objective transfer row instead.
A nonlinear objective function in SLP needs to be modelled using an objective transfer row.

E-12200

Xpress NonLinear error: problem is not augmented.
The operation is only valid for augmented problems. Please call the construct method ﬁrst, or
solve using SLP.

E-12201

Xpress NonLinear error: an internal error has occured.
An internal error has occured that is not expected to have been caused by incorrect input.
Please contact FICO support.

E-12202

Xpress NonLinear error: attribute i cannot be changed.
Attributes normally cannot be changed, as they are set up by the solver. There are a few
exceptions to this rule, the requested attribute is not among the exceptions.

E-12203

Xpress NonLinear error: no problem or solution written.
No problem or solution was written to disk due to an error processing the data.

Fair Isaac Corporation Conﬁdential and Proprietary Information

375

CHAPTER 24

Xpress Knitro Control Parameters
This chapter provides a full list of the controls accepted by Xpress for setting Knitro parameters. Knitro
has a great number and variety of user option settings and although it tries to choose the best settings
by default, often signiﬁcant performance improvements can be realized by choosing some non-default
option settings.
XKTR_PARAM_ALGORITHM

Indicates which algorithm to use to solve the problem

p. 383

XKTR_PARAM_BAR_DIRECTINTERVAL Controls the maximum number of consecutive conjugate
gradient (CG) steps before Knitro will try to enforce that a step is takenusing direct linear algebra.
p. 383
XKTR_PARAM_BAR_FEASIBLE Speciﬁes whether special emphasis is placed on getting and staying
feasible in the interior-point algorithms.
p. 383
XKTR_PARAM_BAR_FEASMODETOL Speciﬁes the tolerance in equation that determines whether
Knitro will force subsequent iterates to remain feasible.
p. 379
XKTR_PARAM_BAR_INITMU Speciﬁes the initial value for the barrier parameter : used with the barrier
algorithms. This option has no effect on the Active Set algorithm.
p. 379
XKTR_PARAM_BAR_INITPT Indicates whether an initial point strategy is used with barrier
algorithms.

p. 384

XKTR_PARAM_BAR_MAXBACKTRACK Indicates the maximum allowable number of backtracks during
the linesearch of the Interior/Direct algorithm before reverting to a CG step.
p. 384
XKTR_PARAM_BAR_MAXCROSSIT Speciﬁes the maximum number of crossover iterations before
termination.
p. 384
XKTR_PARAM_BAR_MAXREFACTOR Indicates the maximum number of refactorizations of the KKT
system per iteration of the Interior/Direct algorithm before reverting to a
CG step.
p. 385
XKTR_PARAM_BAR_MURULE Indicates which strategy to use for modifying the barrier parameter mu
in the barrier algorithms.
p. 385
XKTR_PARAM_BAR_PENCONS Indicates whether a penalty approach is applied to the constraints.
p. 386
XKTR_PARAM_BAR_PENRULE Indicates which penalty parameter strategy to use for determining
whether or not to accept a trial iterate.
p. 386
XKTR_PARAM_BAR_SWITCHRULE Indicates whether or not the barrier algorithms will allow switchingfrom an optimality phase to a pure feasibility phase.
p. 386

Fair Isaac Corporation Conﬁdential and Proprietary Information

376

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_DELTA

Speciﬁes the initial trust region radius scaling factor used to determine theinitial trust region size.
p. 379

XKTR_PARAM_FEASTOL

Speciﬁes the ﬁnal relative stopping tolerance for the feasibility error. p. 379

XKTR_PARAM_FEASTOLABS Speciﬁes the ﬁnal absolute stopping tolerance for the feasibility error.
p. 380
XKTR_PARAM_GRADOPT

Speciﬁes how to compute the gradients of the objective and constraintfunctions.
p. 387

XKTR_PARAM_HESSOPT

Speciﬁes how to compute the (approximate) Hessian of the Lagrangian.
p. 387

XKTR_PARAM_HONORBNDS

Indicates whether or not to enforce satisfaction of simple variablebounds throughout the optimization.
p. 387

XKTR_PARAM_INFEASTOL

Speciﬁes the (relative) tolerance used for declaring infeasibility of amodel.
p. 380

XKTR_PARAM_LMSIZE

Speciﬁes the number of limited memory pairs stored when approximating
the Hessian using the limited-memory quasi-Newton BFGS option. p. 388

XKTR_PARAM_MAXCGITSpeciﬁes the number of limited memory pairs stored when approximating
the Hessian using the limited-memory quasi-Newton BFGS option. p. 388

XKTR_PARAM_MAXIT

Speciﬁes the maximum number of iterations before termination.

p. 388

XKTR_PARAM_MIP_BRANCHRULE Speciﬁes which branching rule to use for MIP branch and boundprocedure.
p. 389
XKTR_PARAM_MIP_GUB_BRANCH Speciﬁes whether or not to branch on generalized upper bounds(GUBs).
p. 389
XKTR_PARAM_MIP_HEURISTIC Speciﬁes which MIP heuristic search approach to apply to try to ﬁnd
an initial integer feasible point.
p. 389
XKTR_PARAM_MIP_HEURISTIC_MAXIT Speciﬁes the maximum number of iterations to allow for
MIP heuristic, if one is enabled.
p. 389
XKTR_PARAM_MIP_IMPLICATNS Speciﬁes whether or not to add constraints to the MIP derived
from logical implications.
p. 390
XKTR_PARAM_MIP_INTEGERTOL This value speciﬁes the threshold for deciding whether or not avariable is determined to be an integer.
p. 380
XKTR_PARAM_MIP_INTGAPABS The absolute integrality gap stop tolerance for MIP.

p. 380

XKTR_PARAM_MIP_INTGAPREL The relative integrality gap stop tolerance for MIP.

p. 380

XKTR_PARAM_MIP_KNAPSACK

p. 390

XKTR_PARAM_MIP_LPALG

Speciﬁes rules for adding MIP knapsack cuts.

Speciﬁes which algorithm to use for any linear programming (LP)subproblem solves that may occur in the MIP branch and bound procedure.
p. 390

XKTR_PARAM_MIP_MAXNODESSpeciﬁes the maximum number of nodes explored.

p. 391

XKTR_PARAM_MIP_MAXSOLVES Speciﬁes the maximum number of subproblem solves allowed (0means no limit).
p. 391
XKTR_PARAM_MIP_METHOD

Speciﬁes which MIP method to use.

Fair Isaac Corporation Conﬁdential and Proprietary Information

p. 391377

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_MIP_OUTINTERVAL Speciﬁes node printing interval for
XKTR_PARAM_MIP_OUTLEVEL when XKTR_PARAM_MIP_OUTLEVEL > 0.
p. 391
XKTR_PARAM_MIP_OUTLEVEL

Speciﬁes how much MIP information to print.

p. 392

XKTR_PARAM_MIP_PSEUDOINIT Speciﬁes the method used to initialize pseudo-costs
corresponding to variables that have not yet been branched on in the MIP
method.
p. 392
XKTR_PARAM_MIP_ROOTALG Speciﬁes which algorithm to use for the root node solve in MIP (sameoptions as XKTR_PARAM_ALGORITHM user option).
p. 392
XKTR_PARAM_MIP_ROUNDING

Speciﬁes the MIP rounding rule to apply.

p. 392

XKTR_PARAM_MIP_SELECTRULE Speciﬁes the MIP select rule for choosing the next node in the
branch and bound tree.
p. 393
XKTR_PARAM_MIP_STRONG_CANDLIM Speciﬁes the maximum number of candidates to explore for
MIP strong branching.
p. 393
XKTR_PARAM_MIP_STRONG_LEVEL Speciﬁes the maximum number of tree levels on which toperform MIP strong branching.
p. 393
XKTR_PARAM_MIP_STRONG_MAXIT Speciﬁes the maximum number of iterations to allow for MIP
strong branching solves.
p. 393
XKTR_PARAM_MIP_TERMINATE Speciﬁes conditions for terminating the MIP algorithm.

p. 393

XKTR_PARAM_OBJRANGE Speciﬁes the extreme limits of the objective function for purposes ofdetermining unboundedness.
p. 381
XKTR_PARAM_OPTTOL

Speciﬁes the ﬁnal relative stopping tolerance for the KKT (optimality) error.
p. 381

XKTR_PARAM_OPTTOLABSSpeciﬁes the ﬁnal absolute stopping tolerance for the KKT (optimality)
error.
p. 381

XKTR_PARAM_OUTLEVControls the level of output produced by Knitro.

p. 394

XKTR_PARAM_PRESOLVE Determine whether or not to use the Knitro presolver to try to simplify themodel by removing variables or constraints. Speciﬁes conditions forterminating the MIP algorithm.
p. 394
XKTR_PARAM_PRESOLVE_TOL Determines the tolerance used by the Knitro presolver to remove
variables and constraints from the model.
p. 381
XKTR_PARAM_SCALE

Performs a scaling of the objective and constraint functions based on theirvalues at the initial point.
p. 394

XKTR_PARAM_SOC

Speciﬁes whether or not to try second order corrections (SOC).

p. 395

XKTR_PARAM_XTOLThe optimization process will terminate if the relative change in allcomponents of the solution point estimate is less than xtol.

p. 382

Fair Isaac Corporation Conﬁdential and Proprietary Information

378

Xpress Knitro Control Parameters

24.1

Reference

Double control parameters
These double control parameters can be set using XSLPsetdblcontrol using the Xpress NonLinear API,XNLPsetsolverdoublecontrol using the XNLP API and setparam in Mosel using module mmxnlp.

XKTR_PARAM_BAR_FEASMODETOL
Description

Speciﬁes the tolerance in equation that determines whether Knitro will force subsequent
iterates to remain feasible.

Type

DoubleNote

The tolerance applies to all inequality constraints in the problem. This option only has aneffect if option XKTR_PARAM_BAR_FEASIBLE = stay or XKTR_PARAM_BAR_FEASIBLE =get_stay.

Default value

1.0e-4

XKTR_PARAM_BAR_INITMU
Description

Speciﬁes the initial value for the barrier parameter : µ used with the barrier algorithms. This
option has no effect on the Active Set algorithm.

Type

DoubleDefault value

1.0e-1

XKTR_PARAM_DELTA
Description

Speciﬁes the initial trust region radius scaling factor used to determine the initial trust region
size.

Type

DoubleDefault value

1.0e0

XKTR_PARAM_FEASTOL
Description

Speciﬁes the ﬁnal relative stopping tolerance for the feasibility error.

Type

DoubleNote

Smaller values of feastol result in a higher degree of accuracy in the solution with respect tofeasibility.

Default value

1.0e-6

Fair Isaac Corporation Conﬁdential and Proprietary Information

379

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_FEASTOLABS
Description

Speciﬁes the ﬁnal absolute stopping tolerance for the feasibility error.

Type

DoubleNote

Smaller values of feastol_abs result in a higher degree of accuracy in the solution withrespect to feasibility.

Default value

0.0e0

XKTR_PARAM_INFEASTOL
Description

Speciﬁes the (relative) tolerance used for declaring infeasibility of a model.

Type

DoubleNote

Smaller values of infeastol make it more difﬁcult to satisfy the conditions Knitro uses for
detecting infeasible models. If you believe Knitro incorrectly declares a model to be
infeasible, then you should try a smaller value for infeastol.

Default value

1.0e-8

XKTR_PARAM_MIP_INTEGERTOL
Description

This value speciﬁes the threshold for deciding whether or not a variable is determined to be
an integer.

Type

DoubleDefault value

1.0e-8

XKTR_PARAM_MIP_INTGAPABS
Description

The absolute integrality gap stop tolerance for MIP.

Type

DoubleDefault value

1.0e-6

XKTR_PARAM_MIP_INTGAPREL
Description

The relative integrality gap stop tolerance for MIP.

Type

DoubleDefault value

1.0e-6

Fair Isaac Corporation Conﬁdential and Proprietary Information

380

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_OBJRANGE
Description

Speciﬁes the extreme limits of the objective function for purposes of determining
unboundedness.

Type

DoubleNote

If the magnitude of the objective function becomes greater than objrange for a feasible
iterate, then the problem is determined to be unbounded and Knitro proceeds no further.

Default value

1.0e20

XKTR_PARAM_OPTTOL
Description

Speciﬁes the ﬁnal relative stopping tolerance for the KKT (optimality) error.

Type

DoubleNote

Smaller values of opttol result in a higher degree of accuracy in the solution with respect tooptimality.

Default value

1.0e-6

XKTR_PARAM_OPTTOLABS
Description

Speciﬁes the ﬁnal absolute stopping tolerance for the KKT (optimality) error.

Type

DoubleNote

Smaller values of opttol_abs result in a higher degree of accuracy in the solution with respect
to optimality.

Default value

0.0e0

XKTR_PARAM_PRESOLVE_TOL
Description

Determines the tolerance used by the Knitro presolver to remove variables and constraints
from the model.

Type

DoubleNote

If you believe the Knitro presolver is incorrectly modifying the model, use a smaller value forthis tolerance (or turn the presolver off).

Default value

1.0e-6

Fair Isaac Corporation Conﬁdential and Proprietary Information

381

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_XTOL
Description

The optimization process will terminate if the relative change in all components of thesolution point estimate is less than xtol.

Type

DoubleNote

If using the Interior/Direct or Interior/CG algorithm and the barrier parameter is still large,
Knitro will ﬁrst try decreasing the barrier parameter before terminating.

Default value

1.0e-15

Fair Isaac Corporation Conﬁdential and Proprietary Information

382

Xpress Knitro Control Parameters

24.2

Reference

Integer control parameters
These integer control parameters can be set using XSLPsetintcontrol using the Xpress NonLinear API,XNLPsetsolverintcontrol using the XNLP API and setparam in Mosel using module mmxnlp.

XKTR_PARAM_ALGORITHM
Description

Indicates which algorithm to use to solve the problem

Type

Integer

Values

0
1
2
3
4
5

Default value(auto) let Knitro automatically choose an algorithm, based on the problem
characteristics.
(direct) use the Interior/Direct algorithm.
(cg) use the Interior/CG algorithm.
(active) use the Active Set algorithm.
(sqp) use the SQP algorithm.
(multi) run all algorithms, perhaps in parallel.

0

XKTR_PARAM_BAR_DIRECTINTERVAL
Description

Controls the maximum number of consecutive conjugate gradient (CG) steps before Knitro
will try to enforce that a step is taken using direct linear algebra.

Type

Integer

Note

This option is only valid for the Interior/Direct algorithm and may be useful on problems
where Knitro appears to be taking lots of conjugate gradient steps. Setting bar_directinterval
to 0 will try to enforce that only direct steps are taken which may produce better results onsome problems.

Default value

10

XKTR_PARAM_BAR_FEASIBLE
Description

Speciﬁes whether special emphasis is placed on getting and staying feasible in theinterior-point algorithms.

Type

Integer

Values0123(no) No special emphasis on feasibility.
(stay) Iterates must satisfy inequality constraints once they become sufﬁciently
feasible.
(get) Special emphasis is placed on getting feasible before trying to optimize.
(get_stay) Implement both options 1 and 2 above.

Fair Isaac Corporation Conﬁdential and Proprietary Information

383

Xpress Knitro Control Parameters

Reference

Note

This option can only be used with the Interior/Direct and Interior/CG algorithms. If
bar_feasible = stay or bar_feasible = get_stay, this will activate the feasible version of Knitro.
The feasible version of Knitro will force iterates to strictly satisfy inequalities, but does not
require satisfaction of equality constraints at intermediate iterates. This option and thehonorbnds option may be useful in applications where functions are undeﬁned outside theregion deﬁned by inequalities. The initial point must satisfy inequalities to a sufﬁcient degree;
if not, Knitro may generate infeasible iterates and does not switch to the feasible version untila sufﬁciently feasible point is found. Sufﬁcient satisfaction occurs at a point x if it is true forall inequalities that cl + tol ≤ c(x) ≤ cu - tol The constant tol is determined by the option
bar_feasmodetol. If bar_feasible = get or bar_feasible = get_stay, Knitro will place special
emphasis on ﬁrst trying to get feasible before trying to optimize.

Default value

0

XKTR_PARAM_BAR_INITPT
Description

Indicates whether an initial point strategy is used with barrier algorithms.

Type

Integer

Values

0
1
2

Note

This option has no effect on the Active Set algorithm.

Default value0(auto) Let Knitro automatically choose the strategy.
(yes) Shift the initial slacks and multipliers to improve barrier algorithm performance.
(no) Do no alter the initial slacks and multipliers.

XKTR_PARAM_BAR_MAXBACKTRACK
Description

Indicates the maximum allowable number of backtracks during the linesearch of theInterior/Direct algorithm before reverting to a CG step.

Type

Integer

Note

Increasing this value will make the Interior/Direct algorithm less likely to take CG steps. If theInterior/Direct algorithm is taking a large number of CG steps (as indicated by a positive value
for ’Gits’ in the output), this may improve performance. This option has no effect on the
Active Set algorithm.

Default value

3

XKTR_PARAM_BAR_MAXCROSSIT
Description

Speciﬁes the maximum number of crossover iterations before termination.

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

384

Xpress Knitro Control Parameters

Reference

Note

If the value is positive and the algorithm in operation is Interior/Direct or Interior/CG, thenKnitro will crossover to the Active Set algorithm near the solution. The Active Set algorithm
will then perform at most bar_maxcrossit iterations to get a more exact solution. If the value
is 0, no Active Set crossover occurs and the interior-point solution is the ﬁnal result. If Active
Set crossover is unable to improve the approximate interior-point solution, then Knitro will
restore the interior-point solution. In some cases (especially on large-scale problems or
difﬁcult degenerate problems) the cost of the crossover procedure may be signiﬁcant - forthis reason, crossover is disabled by default. Enabling crossover generally provides a moreaccurate solution than Interior/Direct or Interior/CG.

Default value

0

XKTR_PARAM_BAR_MAXREFACTOR
Description

Indicates the maximum number of refactorizations of the KKT system per iteration of theInterior/Direct algorithm before reverting to a CG step.

Type

Integer

Note

These refactorizations are performed if negative curvature is detected in the model. Rather
than reverting to a CG step, the Hessian matrix is modiﬁed in an attempt to make thesubproblem convex and then the KKT system is refactorized. Increasing this value will makethe Interior/Direct algorithm less likely to take CG steps. If the Interior/Direct algorithm istaking a large number of CG steps (as indicated by a positive value for "CGits" in the output),
this may improve performance. This option has no effect on the Active Set algorithm.

Default value-1

XKTR_PARAM_BAR_MURULE
Description

Indicates which strategy to use for modifying the barrier parameter mu in the barrier
algorithms.

Type

Integer

Values

0
1
2
3
4

5

6

(auto) Let Knitro automatically choose the strategy.
(monotone) Monotonically decrease the barrier parameter. Available for both barrier
algorithms.
(adaptive) Use an adaptive rule based on the complementarity gap to determine thevalue of the barrier parameter. Available for both barrier algorithms.
(probing) Use a probing (afﬁne-scaling) step to dynamically determine the barrierparameter. Available only for the Interior/Direct algorithm.
(dampmpc) Use a Mehrotra predictor-corrector type rule to determine the barrierparameter, with safeguards on the corrector step. Available only for theInterior/Direct algorithm.
(fullmpc) Use a Mehrotra predictor-corrector type rule to determine the barrierparameter, without safeguards on the corrector step. Available only for theInterior/Direct algorithm.
(quality) Minimize a quality function at each iteration to determine the barrierparameter. Available only for the Interior/Direct algorithm.

Fair Isaac Corporation Conﬁdential and Proprietary Information

385

Xpress Knitro Control Parameters

Reference

Note

Not all strategies are available for both barrier algorithms. This option has no effect on the
Active Set algorithm.

Default value

0

XKTR_PARAM_BAR_PENCONS
Description

Indicates whether a penalty approach is applied to the constraints.

Type

Integer

Values

0
1
2

Note

Using a penalty approach may be helpful when the problem has degenerate or difﬁcult
constraints. It may also help to more quickly identify infeasible problems, or achieve feasibility
in problems with difﬁcult constraints. This option has no effect on the Active Set algorithm.

Default value0(auto) Let Knitro automatically choose the strategy.
(none) No constraints are penalized.
(all) A penalty approach is applied to all general constraints.

XKTR_PARAM_BAR_PENRULE
Description

Indicates which penalty parameter strategy to use for determining whether or not to accept a
trial iterate.

Type

Integer

Values012(auto) Let Knitro automatically choose the strategy.
(single) Use a single penalty parameter in the merit function to weight feasibility
versus optimality.
(ﬂex) Use a more tolerant and ﬂexible step acceptance procedure based on a rangeof penalty parameter values.

NoteThis option has no effect on the Active Set algorithm.

Default value

0

XKTR_PARAM_BAR_SWITCHRULE
Description

Indicates whether or not the barrier algorithms will allow switching from an optimality phase
to a pure feasibility phase.

Type

Integer

Values01
23(auto) Let Knitro determine the switching procedure.
(never) Never switch to feasibility phase.
(level1) Allow switches to feasibility phase.
(level2) Use a more aggressive switching rule.

Fair Isaac Corporation Conﬁdential and Proprietary Information

386

Xpress Knitro Control Parameters

Reference

Note

This option has no effect on the Active Set algorithm.

Default value

0

XKTR_PARAM_GRADOPT
Description

Speciﬁes how to compute the gradients of the objective and constraint functions.

Type

Integer

Values

1
2
3

Note

It is highly recommended to provide exact gradients if at all possible as this greatly impacts
the performance of the code.

Default value

1(exact) User provides a routine for computing the exact gradients.
(forward) Knitro computes gradients by forward ﬁnite-differences.
(central) Knitro computes gradients by central ﬁnite differences.

XKTR_PARAM_HESSOPT
Description

Speciﬁes how to compute the (approximate) Hessian of the Lagrangian.

Type

Integer

Values

1
2
3
4
5
6

Note

Options hessopt = 4 and hessopt = 5 are not available with the Interior/Direct algorithm.
Knitro usually performs best when the user provides exact Hessians (hessopt = 1) or exact
Hessian-vector products (hessopt = 5). If neither can be provided but exact gradients areavailable (i.e., gradopt = 1), then hessopt = 4 is recommended. This option is comparable interms of robustness to the exact Hessian option and typically not much slower in terms oftime, provided that gradient evaluations are not a dominant cost. If exact gradients cannot beprovided, then one of the quasi-Newton options is preferred. Options hessopt = 2 and hessopt= 3 are only recommended for small problems (n ≤ 1000) since they require working with adense Hessian approximation. Option hessopt = 6 should be used for large problems.

Default value

1(exact) User provides a routine for computing the exact Hessian.
(bfgs) Knitro computes a (dense) quasi-Newton BFGS Hessian.
(sr1) Knitro computes a (dense) quasi-Newton SR1 Hessian.
(ﬁnite_diff) Knitro computes Hessian-vector products using ﬁnite-differences.
(product) User provides a routine to compute the Hessian-vector products.
(lbfgs) Knitro computes a limited-memory quasi-Newton BFGS Hessian (its size isdetermined by the option lmsize).

XKTR_PARAM_HONORBNDS
Description

Indicates whether or not to enforce satisfaction of simple variable bounds throughout the
optimization.

Fair Isaac Corporation Conﬁdential and Proprietary Information

387

Xpress Knitro Control Parameters

Type

Integer

Values012Reference(no) Knitro does not require that the bounds on the variables be satisﬁed atintermediate iterates.
(always) Knitro enforces that the initial point and all subsequent solution estimatessatisfy the bounds on the variables.
(initpt) Knitro enforces that the initial point satisﬁes the bounds on the variables.

Note

This option and the bar_feasible option may be useful in applications where functions are
undeﬁned outside the region deﬁned by inequalities.

Default value

2

XKTR_PARAM_LMSIZE
Description

Speciﬁes the number of limited memory pairs stored when approximating the Hessian using
the limited-memory quasi-Newton BFGS option.

Type

Integer

Note

The value must be between 1 and 100 and is only used with XKTR_PARAM_HESSOPT = 6.
Larger values may give a more accurate, but more expensive, Hessian approximation. Smaller
values may give a less accurate, but faster, Hessian approximation. When using the limited
memory BFGS approach it is recommended to experiment with different values of thisparameter.

Default value

10

XKTR_PARAM_MAXCGIT
Description

Speciﬁes the number of limited memory pairs stored when approximating the Hessian using
the limited-memory quasi-Newton BFGS option.

Type

Integer

Values0nDefault value0

Let Knitro automatically choose a value based on the problem size.
At most n>0 CG iterations may be performed during one minor iteration of Knitro.

XKTR_PARAM_MAXIT
Description

Speciﬁes the maximum number of iterations before termination.

Type

Integer

Values0nDefault value

Let Knitro automatically choose a value based on the problem type. Currently Knitro
sets this value to 10000 for LPs/NLPs and 3000 for MIP problems.
At most n>0 iterations may be performed before terminating.

0

Fair Isaac Corporation Conﬁdential and Proprietary Information

388

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_MIP_BRANCHRULE
Description

Speciﬁes which branching rule to use for MIP branch and bound procedure.

Type

Integer

Values0
1
2
3

Default value0(auto) Let Knitro automatically choose the branching rule.
(most_frac) Use most fractional (most infeasible) branching.
(pseudcost) Use pseudo-cost branching.
(strong) Use strong branching (see options XKTR_PARAM_MIP_STRONG_CANDLIM,XKTR_PARAM_MIP_STRONG_LEVEL, XKTR_PARAM_MIP_STRONG_MAXIT for
further control of strong branching procedure).

XKTR_PARAM_MIP_GUB_BRANCH
Description

Speciﬁes whether or not to branch on generalized upper bounds (GUBs).

Type

Integer

Values0
1

Default value

0(no) Do not branch on GUBs.
(yes) Allow branching on GUBs.

XKTR_PARAM_MIP_HEURISTIC
Description

Speciﬁes which MIP heuristic search approach to apply to try to ﬁnd an initial integer feasible
point.

Type

Integer

Values

0
1
2
3

Note

If a heuristic search procedure is enabled, it will run for at most mip_heuristic_maxit
iterations, before starting the branch and bound procedure.

Default value0(auto) Let Knitro choose the heuristic to apply (if any).
(none) No heuristic search applied.
(feaspump) Apply feasibility pump heuristic.
(mpec) Apply heuristic based on MPEC formulation.

XKTR_PARAM_MIP_HEURISTIC_MAXIT
Description

Speciﬁes the maximum number of iterations to allow for MIP heuristic, if one is enabled.

Fair Isaac Corporation Conﬁdential and Proprietary Information

389

Xpress Knitro Control Parameters

Type

Integer

Default value

100

Reference

XKTR_PARAM_MIP_IMPLICATNS
Description

Speciﬁes whether or not to add constraints to the MIP derived from logical implications.

Type

Integer

Values0
1

Default value

1(no) Do not add constraints from logical implications.
(yes) Knitro adds constraints from logical implications.

XKTR_PARAM_MIP_KNAPSACK
Description

Speciﬁes rules for adding MIP knapsack cuts.

Type

Integer

Values0
1
2

Default value

1(none) Do not add knapsack cuts.
(ineqs) Add cuts derived from inequalities only.
(ineqs_eqs) Add cuts derived from both inequalities and equalities.

XKTR_PARAM_MIP_LPALG
Description

Speciﬁes which algorithm to use for any linear programming (LP) subproblem solves that
may occur in the MIP branch and bound procedure.

Type

Integer

Values01
23(auto) Let Knitro automatically choose an algorithm, based on the problem
characteristics.
(direct) Use the Interior/Direct (barrier) algorithm.
(cg) Use the Interior/CG (barrier) algorithm.
(active) Use the Active Set (simplex) algorithm.

Note

LP subproblems may arise if the problem is a mixed integer linear program (MILP), or if using
XKTR_PARAM_MIP_METHOD = HQG. (Nonlinear programming subproblems use the algorithm
speciﬁed by the algorithm option.)

Default value

0

Fair Isaac Corporation Conﬁdential and Proprietary Information390

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_MIP_MAXNODES
Description

Speciﬁes the maximum number of nodes explored.

Type

Integer

Note

Zero vealue means no limit.

Default value

100000

XKTR_PARAM_MIP_MAXSOLVES
Description

Speciﬁes the maximum number of subproblem solves allowed (0 means no limit).

Type

Integer

Default value

200000

XKTR_PARAM_MIP_METHOD
Description

Speciﬁes which MIP method to use.

Type

Integer

Values0
1
2

Default value0(auto) Let Knitro automatically choose the method.
(BB) Use the standard branch and bound method.
(HQG) Use the hybrid Quesada-Grossman method (for convex, nonlinear problems
only).

XKTR_PARAM_MIP_OUTINTERVAL
Description

Speciﬁes node printing interval for XKTR_PARAM_MIP_OUTLEVEL when
XKTR_PARAM_MIP_OUTLEVEL > 0.

Type

Integer

Values0
2
N

Default value

10

Print output every node.
Print output every 2nd node.
Print output every Nth node.

Fair Isaac Corporation Conﬁdential and Proprietary Information

391

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_MIP_OUTLEVEL
Description

Speciﬁes how much MIP information to print.

Type

Integer

Values0
1

Default value

1(none) Do not print any MIP node information.
(iters) Print one line of output for every node.

XKTR_PARAM_MIP_PSEUDOINIT
Description

Speciﬁes the method used to initialize pseudo-costs corresponding to variables that have notyet been branched on in the MIP method.

Type

Integer

Values0
1
2

Default value0

Let Knitro automatically choose the method.
Initialize using the average value of computed pseudo-costs.
Initialize using strong branching.

XKTR_PARAM_MIP_ROOTALG
Description

Speciﬁes which algorithm to use for the root node solve in MIP (same options as
XKTR_PARAM_ALGORITHM user option).

Type

Integer

Default value

0

XKTR_PARAM_MIP_ROUNDING
Description

Speciﬁes the MIP rounding rule to apply.

Type

Integer

Values0
1
2
3
4Default value0(auto) Let Knitro choose the rounding rule.
(none) Do not round if a node is infeasible.
(heur_only) Round using a fast heuristic only.
(nlp_sometimes) Round and solve a subproblem if likely to succeed.
(nlp_always) Always round and solve a subproblem.

Fair Isaac Corporation Conﬁdential and Proprietary Information

392

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_MIP_SELECTRULE
Description

Speciﬁes the MIP select rule for choosing the next node in the branch and bound tree.

Type

Integer

Values0
1
2
3

Default value0(auto) Let Knitro choose the node selection rule.
(depth_ﬁrst) Search the tree using a depth ﬁrst procedure.
(best_bound) Select the node with the best relaxation bound.
(combo_1) Use depth ﬁrst unless pruned, then best bound.

XKTR_PARAM_MIP_STRONG_CANDLIM
Description

Speciﬁes the maximum number of candidates to explore for MIP strong branching.

Type

Integer

Default value

10

XKTR_PARAM_MIP_STRONG_LEVEL
Description

Speciﬁes the maximum number of tree levels on which to perform MIP strong branching.

Type

Integer

Default value

10

XKTR_PARAM_MIP_STRONG_MAXIT
Description

Speciﬁes the maximum number of iterations to allow for MIP strong branching solves.

Type

Integer

Default value

1000

XKTR_PARAM_MIP_TERMINATE
Description

Speciﬁes conditions for terminating the MIP algorithm.

Type

Integer

Fair Isaac Corporation Conﬁdential and Proprietary Information

393

Xpress Knitro Control Parameters

Values0
1

Default value

0

Reference(optimal) Terminate at optimum.
(feasible) Terminate at ﬁrst integer feasible point.

XKTR_PARAM_OUTLEV
Description

Controls the level of output produced by Knitro.

Type

Integer

Values

0
1
2
3
4
5
6

Default value2(none) Printing of all output is suppressed.
(summary) Print only summary information.
(iter_10) Print basic information every 10 iterations.
(iter) Print basic information at each iteration.
(iter_verbose) Print basic information and the function count at each iteration.
(iter_x) Print all the above, and the values of the solution vector x.
(all) Print all the above, and the values of the constraints c at x and the Lagrange
multipliers lambda.

XKTR_PARAM_PRESOLVE
Description

Determine whether or not to use the Knitro presolver to try to simplify the model by removing
variables or constraints. Speciﬁes conditions for terminating the MIP algorithm.

Type

Integer

Values0
1

Default value

1(none) Do not use Knitro presolver.
(basic) Use the Knitro basic presolver.

XKTR_PARAM_SCALE
Description

Performs a scaling of the objective and constraint functions based on their values at theinitial point.

Type

Integer

Values01

Note

If scaling is performed, all internal computations, including the stopping tests, are based on
the scaled values.

Default value

1(no) No scaling is performed.
(yes) Knitro is allowed to scale the objective function and constraints.

Fair Isaac Corporation Conﬁdential and Proprietary Information

394

Xpress Knitro Control Parameters

Reference

XKTR_PARAM_SOC
Description

Speciﬁes whether or not to try second order corrections (SOC).

Type

Integer

Values

0
1
2

Note

A second order correction may be beneﬁcial for problems with highly nonlinear constraints.

Default value

1(no) No second order correction steps are attempted.
(maybe) Second order correction steps may be attempted on some iterations.
(yes) Second order correction steps are always attempted if the original step isrejected and there are nonlinear constraints.

Fair Isaac Corporation Conﬁdential and Proprietary Information

395

Appendix

APPENDIX A

The Xpress-SLP Log
The Xpress-SLP log consists of log lines of two different types: the output of the underlying XPRS
optimizer, and the log of XSLP itself.
Output is sent to the screen (stdout) by default, but may be intercepted by a user function using theuser output callback; see XSLPsetcbmessage. However, under Windows, no output from the
Optimizer DLL is sent to the screen. The user must deﬁne a callback function and print messages tothe screen them self if they wish output to be displayed.

A.0.1

Logging controls
General SLP logging
XPRS_OUTPUTLOG
XPRS_LPLOG
XPRS_MIPLOG

Logging level of the underlying XPRS problem
Logging frequency for solving the linearization
Logging frequency for the MIP solver

Logging for the underlying XPRS problem
XSLP_LOGXSLP_SLPLOGXSLP_MIPLOG

Level of SLP logging (iteration, penalty, convergence)
Logging frequency for SLP iterations
MI-SLP speciﬁc logging

Special logging settings
XPRS_DCLOGXSLP_ERRORTOL_P

A.0.2

Logging of delayed constraint activation
Absolute tolerance for printing error vectors

The structure of the log
The typical log with the default settings starts with statistics about the problem sizes. On thepolygon1.mps example, using the XSLP console program this looks like
[xpress mps] readprob Polygon1.mat
Reading Problem Polygon
Problem Statistics
11 (0 spare) rows
10 (4 spare) structural columns
8 (0 spare) non-zero elements
Global Statistics
0 entities
0 sets0 set members
PV:
0
DC:
0
DR:
0
EC:
IV:
0
RX:
0
TX:
0
SB:
UF:
0
WT:
0
XV:
0
Total:
Xpress-SLP Statistics:
7 coefficients
9 SLP variables

Fair Isaac Corporation Conﬁdential and Proprietary Information

0
0

0

397

The Xpress-SLP Log

Reference

The standard XPRS optimizer problem loading statistics is extended with a report about the special
structures possibly present in the problem, including DC (delayed constraints), DR (determining rows),
EC (enforced constraints), IV (initial values), RX/TX (relative and absolute tolerances), SB (initial stepbounds), UF (user functions), WT (initial row weights), followed by a statistics about the number of SLP
coefﬁcients and variables.
----------------------------------------------------------------SLP iteration 1, 0s
Minimizing LP Polygon
Original problem has:
20 rows
27 cols
68 elements
Presolved problem has:
0 rows0 cols0 elements
Its
Obj Value
S
Ninf Nneg
Sum Inf0828864.7136D00.000000
Uncrunching matrix
0828864.7136D00.000000
Optimal solution found
8 unconverged values (at least 1 in active constraints)
Total feasibility error costs 829100.765742
Penalty Error Vectors - Penalties scaled by 200
Variable
Activity
Penalty
BE-V1V4
1381.836001
1.000000
BE-V2V4
1381.834610
1.000000
BE-V3V4
1381.833218
1.000000
Total:
4145.503829
Error Costs: 829100.765742 Penalty Delta Costs: 0.000000

Time
0
0

Net Objective: -236.052107----------------------------------------------------------------SLP iteration 2, 0s
Minimizing LP Polygon
Original problem has:
20 rows
27 cols
73 elements
Presolved problem has:
0 rows0 cols0 elements
Its
Obj Value
S
Ninf Nneg
Sum Inf0-3.13860E-05
D00.000000
Uncrunching matrix0-3.13860E-05
D00.000000
Optimal solution found4 unconverged values (at least 1 in active constraints)

Time
0
0

----------------------------------------------------------------SLP iteration 3, 0s
Minimizing LP Polygon
Original problem has:
20 rows
27 cols
72 elements
Presolved problem has:
0 rows0 cols0 elements
Its
Obj Value0-1.56933E-05
Uncrunching matrix
0-1.56933E-05
Optimal solution found

S
D

Ninf
0

Nneg
0

Sum Inf.000000

Time
0

D

0

0

.000000

0

The default solution log consists of the optimizer output of solving the linearizations, followed bystatistics of the nonlinear infeasibilities, the penalty and the objective, and the convergence status.
----------------------------------------------------------------Iteration summary
Itr. LPS
NetObjErrorSum
ErrorCost
Unconv. Extended
1 O-236.052107
4145.503829
829100.7657
80Fair Isaac Corporation Conﬁdential and Proprietary Information

Action398

The Xpress-SLP Log

Reference2
3

OO-3.13860E-05-1.56932E-05.000000.000000.000000.000000

4
0

0
0

Xpress-SLP stopped after 3 iterations. 0 unconverged items
No unconverged values in active constraints

The ﬁnal iteration summary contains the following ﬁelds:
Itr: The iteration number.
LPS: The LP status of the linearization, which can take the following values:
O Linearization is optimal
I Linearization is infeasible
U Linearization is unbounded
X Solving the linearization was interupted
NetObj: The net objective of the SLP iteration.
ErrorSum: Sum of the error delta variables. A measure of infeasibility.
ErrorCost: The value of the weighted error delta variables in the objective. A measure of the effort
needed to push the model towards feasiblity.
Unconv: The number of SLP variables that are not converged.
Extended: The number of SLP variables that are converged, but only by extended criteria
Action: The special actions that happened in the iteration. These can be0
Failed line search (non-improving)
B
Enforcing step bounds
E
Some infeasible rows were enforcedG
Global variables were ﬁxed
P
The solution needed polishing, postsolve instability
P! Solution polishing failed
R
Penalty error vectors were removed
V
Feasiblity validation induces further iterations
K
Optimality validation induces further iterations
The presence of a P! suggests that the problem is particularly hard to solve without postsolve, and themodel might beneﬁt from setting XSLP_NOLPPOLISHING on XSLP_ALGORITHM (please note, that thisshould only be considered if the solution polishing features is very slow or fails, as the numericalinaccuracies it aims to remove can cause other problems to the solution process).

Fair Isaac Corporation Conﬁdential and Proprietary Information

399

APPENDIX B

Selecting the right algorithm for a nonlinear
problem - when to use the XPRS library instead of XSLPThis chapter focuses on the nonlinear capabilities of the Xpress XPRS optimizer. As a general rule ofthumb, problems that can be handled by the XPRS library do not require the use of XSLP; while XpressXSLP is able to efﬁciently solve most nonlinear problems, there are subclasses of nonlinear problems
for which the Xpress optimizer features specialized algorithms that are able to solve those problems
more efﬁciently and in larger sizes. These are notably the convex quadratic programming and theconvex quadratically constrained problems and their mixed integer counterparts.
It is also possible to separate the convex quadratic information from the rest of XSLP, and let theXpress XPRS optimizer handle those directly. Doing so is good modelling practice, but emphasis must
be placed on that the optimizer can only handle convex quadratic constraints.

B.0.1

Convex Quadratic Programs (QPs)
Convex Quadratic Programming (QP) problems are an extension of Linear Programming (LP) problems
where the objective function may include a second order polynomial. The FICO Xpress Optimizer canbe used directly for solving QP problems (and the Mixed Integer version MIQP).
If there are no other nonlinearities in the problem, the XPRS library povides specialized algorithms forthe solution of convex QP (MIQP) problems, that are much more efﬁcient than solving the problem as a
general nonlinear problem with XSLP.

B.0.2

Convex Quadratically Constrained Quadratic Programs (QCQPs)
Quadratically Constrained Quadratic Programs (QCQPs) are an extension of the Quadratic
Programming (QP) problem where the constraints may also include second order polynomials.
A QCQP problem may be written as:
minimize:c1 x1 +...+cn xn +xT Q0 x

subject to:

a11 x1 +...+a1n xn +xT Q1 x

≤

b1

≤

bm

...
am1 x1 +...+amn xn +xT Qm x
l1 ≤ x1 ≤ u1 ,...,ln ≤ xn ≤ un
where any of the lower or upper bounds li or ui may be inﬁnite.

Fair Isaac Corporation Conﬁdential and Proprietary Information

400

Selecting the right algorithm for a nonlinear problem - when to use the XPRS library instead of XSLPReference

If there are no other nonlinearities in the problem, the XPRS library povides specialized algorithms forthe solution of convex QCQP (and the integer counterpart MIQCQP) problems, that are much more
efﬁcient than solving the problem as a general nonlinear problem with XSLP.

B.0.3

Convexity
A fundamental property for nonlinear optimization problems, thus in QCQP as well, is convexity. A
region is called convex, if for any two points from the region the connecting line segment is also part of
the region.
The lack of convexity may give rise to several unfavorable model properties. Lack of convexity in theobjective may introduce the phenomenon of locally optimal solutions that are not global ones (a local
optimal solution is one for which a neighborhood in the feasible region exists in which that solution isthe best). While the lack of convexity in constraints can also give rise to local optimums, they may evenintroduce non–connected feasible regions as shown in Figure B.1.

Figure B.1: Non-connected feasible regions

In this example, the feasible region is divided into two parts. Over feasible region B, the objectivefunction has two alterative local optimal solutions, while over feasible region A the objective is not evenbounded.
For convex problems, each locally optimal solution is a global one, making the characterization of the
optimal solution efﬁcient.

B.0.4

Characterizing Convexity in Quadratic Constraints
A quadratic constraint of form

a1 x1 + ... + an xn + xT Qx ≤ bdeﬁnes a convex region if and only if Q is a so–called positive semi–deﬁnite (PSD) matrix.
A rectangular matrix Q is PSD by deﬁnition, if for any vector (not restricted to the feasible set of aproblem) x it holds that xT Qx ≥ 0.
It follows that for greater or equal constraints
a1 x1 + ... + an xn – xT Qx ≥ b
the negative of Q shall be PSD.

Fair Isaac Corporation Conﬁdential and Proprietary Information

401Selecting the right algorithm for a nonlinear problem - when to use the XPRS library instead of XSLPReference

A nontrivial quadratic equality constraint (one for which not every coefﬁcient is zero) always deﬁnes anonconvex region, therefore those must be modelled as XSLP structures.
There is no straightforward way of checking if a matrix is PSD or not. An intuitive way of checking thisproperty, is that the quadratic part shall always only make a constraint harder to satisfy (i.e. taking thequadratic part away shall always be a relaxation of the original problem).
There are certain constructs however, that can easily be recognized as being non convex:
1. the product of two variables say xy without having both x2 and y2 deﬁned;
2. having –x2 in any quadratic expression in a less or equal, or having x2 in any greater or equal row.
As a general rule, a convex quadratic objective and convex quadratic constraints are best handled by
the XPRS library; while all nonconvex counterparts should be modelled as XSLP structures.

Fair Isaac Corporation Conﬁdential and Proprietary Information

402

APPENDIX C

Files used by Xpress NonLinear
Most of the data used by Xpress NonLinear is held in memory. However, there are a few ﬁles which are
written, either automatically or on demand, in addition to those created by the Xpress Optimizer.
LOGFILE

Created by: XSLPsetlogfile
The ﬁle name and location are user-deﬁned.

NAME.mat

Created by: XSLPwriteprob
This is the matrix ﬁle in extended MPS format. The name is user-deﬁned. The
extension .mat is appended automatically.

NAME.txt

Created by: XSLPwriteprob
This is the matrix ﬁle in human-readable "text". The name is user-deﬁned. The
extension .txt is appended automatically.

PROBNAME.svx

Created by: XSLPsave
This is the SLP part of the save ﬁle (the linear part is in probname.svf). Used
by XSLPrestore.

Fair Isaac Corporation Conﬁdential and Proprietary Information

403

APPENDIX D

Contacting FICO
FICO provides clients with support and services for all our products. Refer to the following sections formore information.

Product support
FICO offers technical support and services ranging from self-help tools to direct assistance with a FICO
technical support engineer. Support is available to all clients who have purchased a FICO product andhave an active support or maintenance contract. You can ﬁnd support contact information and a link to
the Customer Self Service Portal (online support) on the Product Support home page(www.ﬁco.com/en/product-support).
The FICO Customer Self Service Portal is a secure web portal that is available 24 hours a day, 7 days aweek from the Product Support home page. The portal allows you to open, review, update, and close
cases, as well as ﬁnd solutions to common problems in the FICO Knowledge Base.
Please include ’Xpress’ in the subject line of your support queries.

Product education
FICO Product Education is the principal provider of product training for our clients and partners.
Product Education offers instructor-led classroom courses, web-based training, seminars, and training
tools for both new user enablement and ongoing performance support. For additional information, visit
the Product Education homepage at www.ﬁco.com/en/product-training or email
producteducation@ﬁco.com.

Product documentation
FICO continually looks for new ways to improve and enhance the value of the products and services weprovide. If you have comments or suggestions regarding how we can improve this documentation, let
us know by sending your suggestions to techpubs@ﬁco.com.
Please include your contact information (name, company, email address, and optionally, your phone
number) so we may reach you if we have questions.

Fair Isaac Corporation Conﬁdential and Proprietary Information

404

Contacting FICO

Reference

Sales and maintenanceIf you need information on other Xpress Optimization products, or you need to discuss maintenancecontracts or other sales-related items, contact FICO by:

Phone: +1 (408) 535-1500 or +44 207 940 8718



Web: www.ﬁco.com/optimization and use the available contact forms

Related services
Strategy Consulting: Included in your contract with FICO may be a speciﬁed amount of consulting time
to assist you in using FICO Optimization Modeler to meet your business needs. Additional consulting
time can be arranged by contract.
Conferences and Seminars: FICO offers conferences and seminars on our products and services. For
announcements concerning these events, go to www.ﬁco.com or contact your FICO accountrepresentative.

FICO Community
The FICO Community is a great resource to ﬁnd the experts and information you need to collaborate,
support your business, and solve common business challenges. You can get informal technicalsupport, build relationships with local and remote professionals, and improve your business practices.
For additional information, visit the FICO Community (community.ﬁco.com/welcome).

About FICO
FICO (NYSE:FICO) powers decisions that help people and businesses around the world prosper.
Founded in 1956 and based in Silicon Valley, the company is a pioneer in the use of predictive analytics
and data science to improve operational decisions. FICO holds more than 165 US and foreign patents
on technologies that increase proﬁtability, customer satisfaction, and growth for businesses inﬁnancial services, telecommunications, health care, retail, and many other industries. Using FICO
solutions, businesses in more than 100 countries do everything from protecting 2.6 billion payment
cards from fraud, to helping people get credit, to ensuring that millions of airplanes and rental cars arein the right place at the right time. Learn more at www.ﬁco.com.

Fair Isaac Corporation Conﬁdential and Proprietary Information

405

IndexSymbols= column, 39
A
ABS, 359
Absolute tolerance record
Tx, 42
ARCCOS, 352
ARCSIN, 353
ARCTAN, 354
Attributes, Problem, 97
Augmentation, 64
B
BOUNDS, 16
BOUNDS section in ﬁle, 39CCallbacks and user functions, 77
Callbacks in MISLP, 92
Cascading, 51
Character Variable record, 39
Closure convergence tolerance, 58
Coefﬁcientsand terms, 33
COLUMNS, 14
COLUMNS section in ﬁle, 38
Control parameters, 122
Convergenceclosure, 58
delta, 58
extended convergence continuation, 62
impact, 59
matrix, 58
slack impact, 60
static objective (1), 60
static objective (2), 61
static objective (3), 61
user-deﬁned, 60
Convergence criteria, 53
convex region, 401
COS, 355
Counting, 214
CV record in SLPDATA, 39
D
Delta convergence tolerance, 58
Derivatives
returning from user function, 82
user function, 83
Determining Row record, 40
DR record in SLPDATA, 40

Fair Isaac Corporation Conﬁdential and Proprietary Information

E
E-12001, 370
E-12002, 370
E-12003, 370
E-12004, 370
E-12005, 370
E-12006, 370
E-12007, 371
E-12008, 371
E-12009, 371
E-12010, 371
E-12011, 371
E-12012, 371
E-12013, 371
E-12014, 371
E-12015, 371
E-12016, 371
E-12017, 371
E-12018, 371
E-12019, 372
E-12020, 372
E-12021, 372
E-12022, 372
E-12025, 372
E-12026, 372
E-12027, 372
E-12029, 372
E-12030, 373
E-12031, 373
E-12032, 373
E-12033, 373
E-12037, 373
E-12038, 373
E-12084, 373
E-12085, 373
E-12105, 373
E-12107, 373
E-12110, 373
E-12111, 373
E-12112, 374
E-12113, 374
E-12114, 374
E-12121, 374
E-12124, 374
E-12125, 374
E-12147, 374
E-12158, 374
E-12159, 374
E-12160, 374
E-12161, 374
E-12192, 374
E-12193, 374

406

Index

Reference

E-12194, 374
E-12195, 375
E-12196, 375
E-12197, 375
E-12198, 375
E-12199, 375
E-12200, 375
E-12201, 375
E-12202, 375
E-12203, 375
EC record in SLPDATA, 40
ENDATA, 17
Enforced Constraint record, 40
Equals column, 39
ERF, 360
ERFC, 361
Error Messages, 370
Error vectors, penalty, 68
EXP, 362
Extended convergence continuation tolerance, 62
Extended MPS ﬁle format, 37F
ﬁles.ini, 30
Files used by Xpress NonLinear, 403
Fixing values of SLP variables in MISLP, 91
FormulaInitial Value record, 41
Formulae, 37, 73
Functions, internal, 350
Functions, library, 214
Functions, user, 77
Ggetslack, 11
getsol, 11H
Handling Infeasibilities, 48
History, 71
I
Impact convergence tolerance, 59
Implicit variable, 38
Infeasibilities, handling, 48
Initial Value formula, 41
Initial Value record, 41
Instanceuser function, 82
Internal Functions, 350
Iterating at each node in MISLP, 92
IV, 17
IV record in SLPDATA, 41
L
Library functions, 214, 215
LN, 363
loadprob, 10
LOG, 364
LOG10, 364

Fair Isaac Corporation Conﬁdential and Proprietary Information

M
Matrix convergence tolerance, 58
Matrix Name Generation, 68
Matrix Structures, 64
MAX, 365
MAXIM, 18
maximise, 11
MIN, 366
minimise, 11
MINLP, 90
MISLP
Callbacks, 92
Fixing or relaxing values of SLP variables, 91
Iterating at each node, 92
Termination criteria at each node, 92
Mixed Integer Non-Linear Programming, 90
mmxnlp, 9
mutlistart, 95
N
NAME, 13Name Generation, 68
nlctr, 9Nonlinear objectives, 89
Nonlinear problems, 33
O
Objectives, nonlinear, 89
Objectives, quadratic, 89
optimizer, 18
P
Parsed formula format, 73
Penalty error vectors, 68
Pointer (reference) attribute, 120
positive semi-deﬁnite matrix, 401
Problem attributes, 97
Problem pointer, 214
PWL, 367Q
Quadratic objectives, 89
QUIT, 18
R
Relative tolerance record Rx, 42
Relaxing values of SLP variables in MISLP, 91
RHS, 16
Row weight
Extended MPS record, 43
ROWS, 13
Rx record in SLPDATA, 42
S
SB record in SLPDATA, 42
Sequential Linear Programming, see Successive
Linear Programming
setinitval, 10
SIGN, 368
SIN, 356
Slack impact convergence tolerance, 60407

Index

Reference

SLP problem pointer, 214
SLP variable, 34
SLPDATACV record, 39
DR record, 40
EC record, 40
IV record, 41
Rx record, 42
SB record, 42
Tx record, 42
UF record, 42
WT record, 43
SLPDATA, 17
SLPDATA section in ﬁle, 39
solution, 400
Solution Process, 44
Special Types of Problem, see Problem, special types
Mixed Integer Non-Linear Programming, 90
Nonlinear objectives, 89
Quadratic objectives, 89
SQRT, 369
Static objective (1) convergence tolerance, 60
Static objective (2) convergence tolerance, 61
Static objective (3) convergence tolerance, 61
Statistics, Xpress-SLP, 69
Step Bound record, 42
Structures, SLP matrix, 64
Successive Linear Programming, 33
T
TAN, 357
Termination criteria at each node in MISLP, 92
Terms
and coefﬁcients, 33
Tolerance record
Rx, 42Tolerance record Tx, 42
Tolerances, convergence, 53
Tx record in SLPDATA, 42
U
UF record in SLPDATA, 42
Unparsed formula format, 73
User function, 77
declaration in native languages, 78
Deltas, 82
general, returning array by reference, 79
general, returning array through argument, 80
instance, 82
programming techniques, 81
ReturnArray, 82
returning derivatives, 82
simple, 79
User function Derivatives, 83
User function interface, 78
User Function record, 42User Functions, 77
User-deﬁned convergence, 60

Fair Isaac Corporation Conﬁdential and Proprietary Information

V
Values of SLP variables in MISLP, ﬁxing or relaxing,
91
Variable
implicit, 38
SLP, 34W
W-12023, 372
W-12024, 372
W-12028, 372
W-12034, 373
W-12142, 374
WRITEPRTSOL, 18
WT record in SLPDATA, 43
X
XKTR_PARAM_ALGORITHM, 383
XKTR_PARAM_BAR_DIRECTINTERVAL, 383
XKTR_PARAM_BAR_FEASIBLE, 383
XKTR_PARAM_BAR_FEASMODETOL, 379
XKTR_PARAM_BAR_INITMU, 379
XKTR_PARAM_BAR_INITPT, 384
XKTR_PARAM_BAR_MAXBACKTRACK, 384
XKTR_PARAM_BAR_MAXCROSSIT, 384
XKTR_PARAM_BAR_MAXREFACTOR, 385
XKTR_PARAM_BAR_MURULE, 385
XKTR_PARAM_BAR_PENCONS, 386
XKTR_PARAM_BAR_PENRULE, 386
XKTR_PARAM_BAR_SWITCHRULE, 386
XKTR_PARAM_DELTA, 379
XKTR_PARAM_FEASTOL, 379
XKTR_PARAM_FEASTOLABS, 380
XKTR_PARAM_GRADOPT, 387
XKTR_PARAM_HESSOPT, 387
XKTR_PARAM_HONORBNDS, 387
XKTR_PARAM_INFEASTOL, 380
XKTR_PARAM_LMSIZE, 388
XKTR_PARAM_MAXCGIT, 388
XKTR_PARAM_MAXIT, 388
XKTR_PARAM_MIP_BRANCHRULE, 389
XKTR_PARAM_MIP_GUB_BRANCH, 389
XKTR_PARAM_MIP_HEURISTIC, 389
XKTR_PARAM_MIP_HEURISTIC_MAXIT, 389
XKTR_PARAM_MIP_IMPLICATNS, 390
XKTR_PARAM_MIP_INTEGERTOL, 380
XKTR_PARAM_MIP_INTGAPABS, 380
XKTR_PARAM_MIP_INTGAPREL, 380
XKTR_PARAM_MIP_KNAPSACK, 390
XKTR_PARAM_MIP_LPALG, 390
XKTR_PARAM_MIP_MAXNODES, 391
XKTR_PARAM_MIP_MAXSOLVES, 391
XKTR_PARAM_MIP_METHOD, 391
XKTR_PARAM_MIP_OUTINTERVAL, 391
XKTR_PARAM_MIP_OUTLEVEL, 392
XKTR_PARAM_MIP_PSEUDOINIT, 392
XKTR_PARAM_MIP_ROOTALG, 392
XKTR_PARAM_MIP_ROUNDING, 392
XKTR_PARAM_MIP_SELECTRULE, 393
XKTR_PARAM_MIP_STRONG_CANDLIM, 393

408

Index

Reference

XKTR_PARAM_MIP_STRONG_LEVEL, 393
XKTR_PARAM_MIP_STRONG_MAXIT, 393
XKTR_PARAM_MIP_TERMINATE, 393
XKTR_PARAM_OBJRANGE, 381
XKTR_PARAM_OPTTOL, 381
XKTR_PARAM_OPTTOLABS, 381
XKTR_PARAM_OUTLEV, 394
XKTR_PARAM_PRESOLVE, 394
XKTR_PARAM_PRESOLVE_TOL, 381
XKTR_PARAM_SCALE, 394
XKTR_PARAM_SOC, 395
XKTR_PARAM_XTOL, 382
xnlp_verbose, 11
Xpress NonLinear problem pointer, 214
Xpress-SLP Statistics, 69
xprs_verbose, 11
XPRSdestroyprob, 27
XPRSfree, 27
XPRSgetsol, 27
XPRSwriteprtsol, 27
XSLP_ALGORITHM, 166
XSLP_ANALYZE, 168
XSLP_ATOL_A, 130
XSLP_ATOL_R, 130
XSLP_AUGMENTATION, 169
XSLP_AUTOSAVE, 170
XSLP_BARCROSSOVERSTART, 171
XSLP_BARLIMIT, 171
XSLP_BARSTALLINGLIMIT, 172
XSLP_BARSTALLINGOBJLIMIT, 172
XSLP_BARSTALLINGTOL, 130
XSLP_BARSTARTOPS, 172
XSLP_CALCTHREADS, 173
XSLP_CASCADE, 173
XSLP_CASCADENLIMIT, 174
XSLP_CASCADETOL_PA, 131
XSLP_CASCADETOL_PR, 131
XSLP_CDTOL_A, 131
XSLP_CDTOL_R, 132
XSLP_CLAMPSHRINK, 132
XSLP_CLAMPVALIDATIONTOL_A, 133
XSLP_CLAMPVALIDATIONTOL_R, 133
XSLP_COEFFICIENTS, 104
XSLP_COL, 24
XSLP_CON, 24
XSLP_CONTROL, 174
XSLP_CONVERGENCEOPS, 175
XSLP_CTOL, 133
XSLP_CURRENTDELTACOST, 101
XSLP_CURRENTERRORCOST, 101
XSLP_CVNAME, 208
XSLP_CVS, 104
XSLP_DAMP, 134
XSLP_DAMPEXPAND, 134
XSLP_DAMPMAX, 134
XSLP_DAMPMIN, 135
XSLP_DAMPSHRINK, 135
XSLP_DAMPSTART, 176
XSLP_DCLIMIT, 176
XSLP_DCLOG, 176

Fair Isaac Corporation Conﬁdential and Proprietary InformationXSLP_DEFAULTIV, 135
XSLP_DEFAULTSTEPBOUND, 136
XSLP_DELAYUPDATEROWS, 176
XSLP_DELTA_A, 136
XSLP_DELTA_R, 136
XSLP_DELTA_X, 137
XSLP_DELTA_Z, 137
XSLP_DELTA_ZERO, 137
XSLP_DELTACOST, 138
XSLP_DELTACOSTFACTOR, 138
XSLP_DELTAFORMAT, 208
XSLP_DELTAMAXCOST, 138
XSLP_DELTAOFFSET, 177
XSLP_DELTAS, 104
XSLP_DELTAZLIMIT, 177
XSLP_DERIVATIVES, 178
XSLP_DETERMINISTIC, 178
XSLP_DJTOL, 139
XSLP_DRCOLTOL, 139
XSLP_ECFCHECK, 178
XSLP_ECFCOUNT, 104
XSLP_ECFTOL_A, 139
XSLP_ECFTOL_R, 140
XSLP_ECHOXPRSMESSAGES, 179
XSLP_ENFORCECOSTSHRINK, 140
XSLP_ENFORCEMAXCOST, 141
XSLP_EOF, 24
XSLP_EQUALSCOLUMN, 105
XSLP_ERRORCOST, 141
XSLP_ERRORCOSTFACTOR, 141
XSLP_ERRORCOSTS, 101
XSLP_ERRORMAXCOST, 142
XSLP_ERROROFFSET, 179
XSLP_ERRORTOL_A, 142
XSLP_ERRORTOL_P, 142
XSLP_ESCALATION, 143
XSLP_ETOL_A, 143
XSLP_ETOL_R, 143
XSLP_EVALUATE, 180
XSLP_EVTOL_A, 144
XSLP_EVTOL_R, 144
XSLP_EXPAND, 145
XSLP_EXPLOREDELTAS, 104
XSLP_FEASTOLTARGET, 145
XSLP_FILTER, 180
XSLP_FINDIV, 181
XSLP_FUN, 24
XSLP_FUNCEVAL, 181
XSLP_GRANULARITY, 145
XSLP_GRIDHEURSELECT, 182
XSLP_HESSIAN, 183
XSLP_HEURSTRATEGY, 182
XSLP_IFS, 105
XSLP_IFUN, 24
XSLP_IMPLICITVARIABLES, 105
XSLP_INFEASLIMIT, 183
XSLP_INFINITY, 146
XSLP_INTEGERDELTAS, 105
XSLP_INTERNALFUNCCALLS, 105
XSLP_ITER, 106409

Index

ReferenceXSLP_ITERFALLBACKOPS, 208
XSLP_ITERLIMIT, 183
XSLP_ITOL_A, 146
XSLP_ITOL_R, 147
XSLP_IVNAME, 209
XSLP_JACOBIAN, 184
XSLP_JOBID, 106
XSLP_KEEPBESTITER, 106
XSLP_LINQUADBR, 184
XSLP_LOG, 184
xslp_log, 11
XSLP_LSITERLIMIT, 185
XSLP_LSPATTERNLIMIT, 185
XSLP_LSSTART, 185
XSLP_LSZEROLIMIT, 186
XSLP_MATRIXTOL, 147
XSLP_MAXTIME, 186
XSLP_MAXWEIGHT, 148
XSLP_MEMORYFACTOR, 148
XSLP_MERITLAMBDA, 148
XSLP_MINORVERSION, 106
XSLP_MINSBFACTOR, 149
XSLP_MINUSDELTAFORMAT, 209
XSLP_MINUSERRORFORMAT, 210
XSLP_MINUSPENALTYERRORS, 106
XSLP_MINWEIGHT, 149
XSLP_MIPALGORITHM, 186
XSLP_MIPCUTOFF_A, 149
XSLP_MIPCUTOFF_R, 150
XSLP_MIPCUTOFFCOUNT, 188
XSLP_MIPCUTOFFLIMIT, 188
XSLP_MIPDEFAULTALGORITHM, 189
XSLP_MIPERRORTOL_A, 150
XSLP_MIPERRORTOL_R, 150
XSLP_MIPFIXSTEPBOUNDS, 189
XSLP_MIPITER, 107
XSLP_MIPITERLIMIT, 190
XSLP_MIPLOG, 190
XSLP_MIPNODES, 107
XSLP_MIPOCOUNT, 190
XSLP_MIPOTOL_A, 151
XSLP_MIPOTOL_R, 151
XSLP_MIPPROBLEM, 120
XSLP_MIPRELAXSTEPBOUNDS, 191
XSLP_MIPSOLS, 107
XSLP_MODELCOLS, 107
XSLP_MODELROWS, 107
XSLP_MSMAXBOUNDRANGE, 152
XSLP_MSSTATUS, 108
XSLP_MTOL_A, 152
XSLP_MTOL_R, 153
XSLP_MULTISTART, 191
XSLP_MULTISTART_MAXSOLVES, 191
XSLP_MULTISTART_MAXTIME, 192
XSLP_MULTISTART_POOLSIZE, 192
XSLP_MULTISTART_SEED, 193
XSLP_MULTISTART_THREADS, 193
XSLP_MVTOL, 153
XSLP_NLPSTATUS, 108
XSLP_NONCONSTANTCOEFF, 108

Fair Isaac Corporation Conﬁdential and Proprietary InformationXSLP_NONLINEARCONSTRAINTS, 109
XSLP_OBJSENSE, 154
XSLP_OBJTOPENALTYCOST, 154
XSLP_OBJVAL, 101
XSLP_OCOUNT, 193
XSLP_OP, 24
XSLP_OPTIMALITYTOLTARGET, 155
XSLP_ORIGINALCOLS, 109
XSLP_ORIGINALROWS, 109
XSLP_OTOL_A, 155
XSLP_OTOL_R, 155
XSLP_PENALTYCOLFORMAT, 210
XSLP_PENALTYDELTACOLUMN, 109
XSLP_PENALTYDELTAROW, 109
XSLP_PENALTYDELTAS, 110
XSLP_PENALTYDELTATOTAL, 101
XSLP_PENALTYDELTAVALUE, 102
XSLP_PENALTYERRORCOLUMN, 110
XSLP_PENALTYERRORROW, 110
XSLP_PENALTYERRORS, 110
XSLP_PENALTYERRORTOTAL, 102
XSLP_PENALTYERRORVALUE, 102
XSLP_PENALTYINFOSTART, 194
XSLP_PENALTYROWFORMAT, 210
XSLP_PLUSDELTAFORMAT, 211
XSLP_PLUSERRORFORMAT, 211
XSLP_PLUSPENALTYERRORS, 110
XSLP_POSTSOLVE, 194
XSLP_PRESOLVE, 194
XSLP_PRESOLVEDELETEDDELTA, 111
XSLP_PRESOLVEELIMINATIONS, 111
XSLP_PRESOLVEFIXEDCOEF, 111
XSLP_PRESOLVEFIXEDDR, 111
XSLP_PRESOLVEFIXEDNZCOL, 112
XSLP_PRESOLVEFIXEDSLPVAR, 112
XSLP_PRESOLVEFIXEDZCOL, 112
XSLP_PRESOLVELEVEL, 195
XSLP_PRESOLVEOPS, 195
XSLP_PRESOLVEPASSES, 112
XSLP_PRESOLVEPASSLIMIT, 196
XSLP_PRESOLVESTATE, 113
XSLP_PRESOLVETIGHTENED, 113
XSLP_PRESOLVEZERO, 156
XSLP_PRIMALINTEGRAL, 102
XSLP_PRIMALINTEGRALREF, 156
XSLP_PROBING, 196
XSLP_REFORMULATE, 196
XSLP_SAMECOUNT, 197
XSLP_SAMEDAMP, 197
XSLP_SBLOROWFORMAT, 211
XSLP_SBNAME, 212
XSLP_SBROWOFFSET, 198
XSLP_SBSTART, 198
XSLP_SBUPROWFORMAT, 212
XSLP_SBXCONVERGED, 113
XSLP_SCALE, 198
XSLP_SCALECOUNT, 199
XSLP_SEMICONTDELTAS, 113
XSLP_SHRINK, 157
XSLP_SHRINKBIAS, 157

410

Index

ReferenceXSLP_SLPLOG, 200
xslp_slplog, 11
XSLP_SOLSTATUS, 114
XSLP_SOLUTIONPOOL, 120
XSLP_SOLVER, 199
XSLP_SOLVERSELECTED, 114
XSLP_STATUS, 114
XSLP_STOL_A, 157
XSLP_STOL_R, 158
XSLP_STOPOUTOFRANGE, 200
XSLP_STOPSTATUS, 116
XSLP_THREADS, 200
XSLP_THREADSAFEUSERFUNC, 201
XSLP_TIMEPRINT, 200
XSLP_TOLNAME, 212
XSLP_TOLSETS, 116
XSLP_TOTALEVALUATIONERRORS, 116
XSLP_TRACEMASK, 213
XSLP_TRACEMASKOPS, 201
XSLP_UCCONSTRAINEDCOUNT, 116
XSLP_UFINSTANCES, 117
XSLP_UFS, 117
XSLP_UNCONVERGED, 117
XSLP_UNFINISHEDLIMIT, 202
XSLP_UPDATEFORMAT, 213
XSLP_UPDATEOFFSET, 202
XSLP_USEDERIVATIVES, 117
XSLP_USERFUNCCALLS, 118
XSLP_VALIDATIONINDEX_A, 102
XSLP_VALIDATIONINDEX_K, 103
XSLP_VALIDATIONINDEX_R, 103
XSLP_VALIDATIONTARGET_K, 158
XSLP_VALIDATIONTARGET_R, 158
XSLP_VALIDATIONTOL_A, 159
XSLP_VALIDATIONTOL_R, 159
XSLP_VARIABLES, 118
XSLP_VCOUNT, 203
XSLP_VERSION, 118
XSLP_VERSIONDATE, 121
XSLP_VLIMIT, 203
XSLP_VSOLINDEX, 103
XSLP_VTOL_A, 160
XSLP_VTOL_R, 160
XSLP_WCOUNT, 204
XSLP_WTOL_A, 161
XSLP_WTOL_R, 162
XSLP_XCOUNT, 205
XSLP_XLIMIT, 205
XSLP_XPRSPROBLEM, 120
XSLP_XSLPPROBLEM, 120
XSLP_XTOL_A, 163
XSLP_XTOL_R, 163
XSLP_ZERO, 164
XSLP_ZEROCRITERION, 206
XSLP_ZEROCRITERIONCOUNT, 207
XSLP_ZEROCRITERIONSTART, 207
XSLP_ZEROESRESET, 118
XSLP_ZEROESRETAINED, 118
XSLP_ZEROESTOTAL, 119
XSLP_ATOL, 58

Fair Isaac Corporation Conﬁdential and Proprietary InformationXSLP_CTOL, 58
XSLP_ITOL, 59
XSLP_MTOL, 59
XSLP_OCOUNT, 61
XSLP_OTOL, 61
XSLP_STOL, 60
XSLP_VCOUNT, 61
XSLP_VLIMIT, 61
XSLP_VTOL, 61
XSLP_WCOUNT, 63
XSLP_WTOL, 62
XSLP_XCOUNT, 62
XSLP_XLIMIT, 62
XSLP_XTOL, 62
XSLPaddcoefs, 221
XSLPadddfs, 223
XSLPaddtolsets, 224
XSLPadduserfunction, 225
XSLPaddvars, 226
XSLPcalcslacks, 228
XSLPcascade, 229
XSLPcascadeorder, 230
XSLPchgcascadenlimit, 231
XSLPchgccoef, 232
XSLPchgcoef, 25, 233
XSLPchgdeltatype, 234
XSLPchgdf, 235
XSLPchgrowstatus, 236
XSLPchgrowwt, 237
XSLPchgtolset, 238
XSLPchgvar, 240
XSLPconstruct, 242
XSLPcopycallbacks, 243
XSLPcopycontrols, 244
XSLPcopyprob, 245
XSLPcreateprob, 246
XSLPdelcoefs, 247
XSLPdeltolsets, 248
XSLPdeluserfunction, 249
XSLPdelvars, 250
XSLPdestroyprob, 27, 251
XSLPevaluatecoef, 252
XSLPevaluateformula, 253
XSLPfixpenalties, 254
XSLPfree, 27, 255
XSLPgetbanner, 256
XSLPgetccoef, 257
XSLPgetcoefformula, 258
XSLPgetcoefs, 259
XSLPgetcolinfo, 260
XSLPgetdblattrib, 261
XSLPgetdblcontrol, 262
XSLPgetdf, 263
XSLPgetindex, 264
XSLPgetintattrib, 265
XSLPgetintcontrol, 266
XSLPgetlasterror, 267
XSLPgetptrattrib, 268
XSLPgetrowinfo, 269
XSLPgetrowstatus, 270

411

Index

Reference

XSLPgetrowwt, 271
XSLPgetslpsol, 272
XSLPgetstrattrib, 273
XSLPgetstrcontrol, 274
XSLPgettolset, 275
XSLPgetvar, 27, 276
XSLPglobal, 278
XSLPimportlibfunc, 279
XSLPinit, 280
XSLPinterrupt, 281
XSLPitemname, 282
XSLPload... functions, 215
XSLPloadcoefs, 25, 283
XSLPloaddfs, 285
XSLPloadtolsets, 286
XSLPloadvars, 27, 287
XSLPmaxim, 26, 289
XSLPminim, 26, 290
XSLPmsaddcustompreset, 291
XSLPmsaddjob, 292
XSLPmsaddpreset, 293
XSLPmsclear, 294
XSLPnlpoptimize, 295
XSLPpostsolve, 296
XSLPpresolve, 297
XSLPprintevalinfo, 299
XSLPprintmemory, 298
XSLPprob, 214
XSLPreadprob, 300
XSLPreinitialize, 304
XSLPremaxim, 301
XSLPreminim, 302
XSLPrestore, 303
XSLPsave, 305
XSLPsaveas, 306
XSLPscaling, 307
XSLPsetcbcascadeend, 308
XSLPsetcbcascadestart, 309
XSLPsetcbcascadevar, 310
XSLPsetcbcascadevarfail, 311
XSLPsetcbcoefevalerror, 312
XSLPsetcbconstruct, 313
XSLPsetcbdestroy, 315
XSLPsetcbdrcol, 316
XSLPsetcbintsol, 317
XSLPsetcbiterend, 318
XSLPsetcbiterstart, 319
XSLPsetcbitervar, 320
XSLPsetcbmessage, 19, 321
XSLPsetcbmsjobend, 323
XSLPsetcbmsjobstart, 324
XSLPsetcbmswinner, 325
XSLPsetcboptnode, 326
XSLPsetcbprenode, 327
XSLPsetcbpreupdatelinearization, 328
XSLPsetcbslpend, 329
XSLPsetcbslpnode, 330
XSLPsetcbslpstart, 331
XSLPsetcurrentiv, 332
XSLPsetdblcontrol, 333

Fair Isaac Corporation Conﬁdential and Proprietary Information

XSLPsetdefaultcontrol, 334
XSLPsetdefaults, 335
XSLPsetfunctionerror, 336
XSLPsetintcontrol, 337
XSLPsetlogfile, 338
XSLPsetparam, 339
XSLPsetstrcontrol, 340
XSLPunconstruct, 341
XSLPupdatelinearization, 342
XSLPvalidate, 343
XSLPvalidatekkt, 344
XSLPvalidateprob, 345
XSLPvalidaterow, 346
XSLPvalidatevector, 347
XSLPwriteprob, 26, 348
XSLPwriteslxsol, 349

412