Reference manual

FICO Xpress Optimization
R

FICO Xpress BCL
R

Reference manual
Release 4.8.11

Last update June 2017www.fico.com

Make every decision countTM

This material is the confidential, proprietary, and unpublished property of Fair Isaac Corporation.
Receipt or possession of this material does not convey rights to divulge, reproduce, use, or allow
others to use it without the specific written authorization of Fair Isaac Corporation and use must
conform strictly to the license agreement.
The information in this document is subject to change without notice. If you find any problems inthis documentation, please report them to us in writing. Neither Fair Isaac Corporation nor its
affiliates warrant that this documentation is error-free, nor are there any other warranties withrespect to the documentation except as may be provided in the license agreement.
©1999–2017 Fair Isaac Corporation. All rights reserved. Permission to use this software and its
documentation is governed by the software license agreement between the licensee and Fair Isaac
Corporation (or its affiliate). Portions of the program may contain copyright of various authors andmay be licensed under certain third-party licenses identified in the software, documentation, orboth.
In no event shall Fair Isaac Corporation or its affiliates be liable to any person for direct, indirect,
special, incidental, or consequential damages, including lost profits, arising out of the use of thissoftware and its documentation, even if Fair Isaac Corporation or its affiliates have been advised ofthe possibility of such damage. The rights and allocation of risk between the licensee and Fair Isaac
Corporation (or its affiliates) are governed by the respective identified licenses in the software,
documentation, or both.
Fair Isaac Corporation and its affiliates specifically disclaim any warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a particular purpose. The software andaccompanying documentation, if any, provided hereunder is provided solely to users licensed under
the Fair Isaac Software License Agreement. Fair Isaac Corporation and its affiliates have no
obligation to provide maintenance, support, updates, enhancements, or modifications except as
required to licensed users under the Fair Isaac Software License Agreement.
FICO and Fair Isaac are trademarks or registered trademarks of Fair Isaac Corporation in the UnitedStates and may be trademarks or registered trademarks of Fair Isaac Corporation in other countries.
Other product and company names herein may be trademarks of their respective owners.
FICO R Xpress BCL
Deliverable Version: A
Last Revised: June 2017
Version 4.8.11

Contents
1 Introduction
1.1 An overview of Xpress BCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Note for Optimizer library users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Structure of this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 Conventions used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
1
1
2
2

I

4

Modeling with BCL

2 Modeling with BCL
2.1 Problem handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Initialization and termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.2 Problem creation and deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.3 Other basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.4 Input and output settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.5 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.2 Variable arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Predefined constraint functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Objective function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Solving and solution information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 Model formulation using basic functions . . . . . . . . . . . . . . . . . . . . . .
2.5.2 Using variable arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3 Completing the example: problem solving and output . . . . . . . . . . . . . .

5
5
5
5
6
6
7
7
7
8
9
9
10
11
11
12
13
13
15

3 Further modeling topics
3.1 Data input and index sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Special Ordered Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Array-based SOS definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Loading solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 Output and printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Quadratic Programming with BCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 User error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Efficent modeling with BCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1 Names dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16
16
17
19
19
19
19
20
20
21
22
22
23
24
25
27
27

Fair Isaac Corporation Confidential and Proprietary Informationi

Contents

3.7.1.1 Disabling the names dictionary . . . . . . . . . . . . . . . . . . . . . . .
3.7.1.2 Setting the names dictionary size . . . . . . . . . . . . . . . . . . . . .
3.7.2 Handling of problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2.1 Resetting a problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2.2 Releasing a problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3 Constraint definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3.1 Object-oriented interfaces . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3.2 Order of enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IIBCL library and class reference

4 BCL C library functions
4.1 Layout for function descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddarrterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddcutarrterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddcutterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddidxel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddmipsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddqterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddsosarrel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddsosel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBaddterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBapparrvarel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBbegincb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBcleardir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdefcbdelvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdefcberr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdefcbmsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelbasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelcutterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelqterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelsolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelsos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelsosel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBdelterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBendarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBendcb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBexportprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBfinish, XPRBfree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBfixglobals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBfixvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetarrvarname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetarrvarsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetbounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetbyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetcoeff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XPRBgetcolnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Fair Isaac Corporation Confidential and Proprietary Information

27
28
28
28
28
28
28
29

30
31
31
33
34
35
37
38
39
40
41
42
43
44
45
46
47
48
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

ii

Contents

XPRBgetctrname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
XPRBgetctrrng . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
XPRBgetctrsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
XPRBgetctrtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
XPRBgetcutid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
XPRBgetcutrhs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
XPRBgetcuttype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
XPRBgetdelayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
XPRBgetdual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
XPRBgetidxel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
XPRBgetidxelname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
XPRBgetidxsetname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
XPRBgetidxsetsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
XPRBgetiis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
XPRBgetincvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
XPRBgetindicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
XPRBgetindvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
XPRBgetlim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
XPRBgetlpstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
XPRBgetmiis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
XPRBgetmipstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
XPRBgetnextterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
XPRBgetnextqterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
XPRBgetnextctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
XPRBgetmodcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
XPRBgetnumiis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
XPRBgetobjval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
XPRBgetprobname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
XPRBgetprobstat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
XPRBgetqcoeff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
XPRBgetrange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
XPRBgetrcost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
XPRBgetrhs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
XPRBgetrownum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
XPRBgetsense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
XPRBgetslack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
XPRBgetsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
XPRBgetsolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
XPRBgetsolsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
XPRBgetsosname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
XPRBgetsostype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
XPRBgettime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
XPRBgetvarlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
XPRBgetvarname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
XPRBgetvarrng . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
XPRBgetvartype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
XPRBgetversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
XPRBgetXPRSprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
XPRBinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
XPRBloadbasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
XPRBloadmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
XPRBloadmipsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
XPRBlpoptimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
XPRBmipoptimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
XPRBnewarrsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Fair Isaac Corporation Confidential and Proprietary Informationiii

Contents

XPRBnewarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
XPRBnewctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
XPRBnewcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
XPRBnewcutarrsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
XPRBnewcutprec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
XPRBnewcutsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
XPRBnewidxset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
XPRBnewname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
XPRBnewprec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
XPRBnewprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
XPRBnewsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
XPRBnewsos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
XPRBnewsosrc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
XPRBnewsosw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
XPRBnewsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
XPRBnewvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
XPRBprintarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
XPRBprintctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
XPRBprintcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
XPRBprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
XPRBprintidxset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
XPRBprintobj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
XPRBprintprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
XPRBprintsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
XPRBprintsos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
XPRBprintvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
XPRBreadarrlinecb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
XPRBreadbinsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
XPRBreadlinecb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
XPRBreadslxsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
XPRBresetprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
XPRBsavebasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
XPRBsetarrvarel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
XPRBsetcolorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
XPRBsetctrtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
XPRBsetcutid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
XPRBsetcutmode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
XPRBsetcutterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
XPRBsetcuttype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
XPRBsetdecsign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
XPRBsetdelayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
XPRBsetdictionarysize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
XPRBseterrctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
XPRBsetincvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
XPRBsetindicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
XPRBsetlb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
XPRBsetlim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
XPRBsetmodcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
XPRBsetmsglevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
XPRBsetobj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
XPRBsetprobname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
XPRBsetqterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
XPRBsetrange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
XPRBsetrealfmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
XPRBsetsense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Fair Isaac Corporation Confidential and Proprietary Informationiv

Contents

XPRBsetsosdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
XPRBsetsolarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
XPRBsetsolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
XPRBsetterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
XPRBsetub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
XPRBsetvardir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
XPRBsetvarlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
XPRBsetvartype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
XPRBstartarrvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
XPRBsync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
XPRBwritedir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
XPRBwritesol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
XPRBwritebinsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
XPRBwriteprtsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
XPRBwriteslxsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
5 BCL in C++
205
5.1 An overview of BCL in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5.1.2 QCQP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
5.1.3 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.2 C++ class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
XPRB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
getTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
getVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
setColOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
setMsgLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
setRealFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
XPRBbasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
XPRBbasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
XPRBctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
XPRBctr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
addTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
delTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
getAct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
getCoefficient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
getDual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
getIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
getIndVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
getRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
getRangeL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
getRangeU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
getRHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
getRNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
getRowNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
getSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
getSlack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Fair Isaac Corporation Confidential and Proprietary Informationv

Contents

isDelayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
isIncludeVars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
isIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
isModCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
nextTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
setDelayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
setIncludeVars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
setIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
setModCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
setRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
setTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
setType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
XPRBcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
XPRBcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
addTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
delTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
getID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
getRHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
setID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
setTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
setType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
XPRBexpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
XPRBexpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
addTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
delTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
getSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
mul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
neg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
setTerm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
sqr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
XPRBindexSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
XPRBindexSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
addElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
getIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
getIndexName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
getSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
XPRBprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
XPRBprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
addCuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Fair Isaac Corporation Confidential and Proprietary Informationvi

Contents

addMIPSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
beginCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
clearDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
delCtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
delCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
delSos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
endCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
exportProb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
fixGlobals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
getCtrByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
getIndexSetByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
getLPStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
getMIPStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
getNumIIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
getObjVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
getProbStat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
getSense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
getSosByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
getVarByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
getXPRSprob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
loadBasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
loadMat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
loadMIPSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
lpOptimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
mipOptimize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
nextCtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
newCtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
newCut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
newIndexSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
newSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
newSos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
newVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
printObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
readBinSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
readSlxSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
saveBasis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
setColOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
setCutMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
setDictionarySize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
setMsgLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
setObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
setName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
setRealFmt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
setSense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
writeDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
writeSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
writeBinSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
writePrtSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
writeSlxSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
XPRBrelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Fair Isaac Corporation Confidential and Proprietary Informationvii

Contents

XPRBrelation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
XPRBsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
XPRBsol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
delVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
getSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
getVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
setVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
XPRBsos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
XPRBsos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
addElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
delElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
setDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
XPRBvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
XPRBvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
fix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
getColNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
getCRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
getLB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
getLim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
getName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
getRCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getRNG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
getSol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
getType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
getUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
isValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
setDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
setLB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
setLim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
setType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
setUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
6 BCL in Java304
6.1 An overview of BCL in Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
6.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
6.1.2 QCQP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
6.1.3 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
6.2 Java class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
7 BCL in .NET313
7.1 An overview of BCL in .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
7.1.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
7.1.2 QCQP Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
7.1.3 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Fair Isaac Corporation Confidential and Proprietary Informationviii

Contents

7.2 .NET class reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Appendix

324

A BCL error messages

325

B Using BCL with the Optimizer library330
B.1 Switching between libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
B.1.1 BCL-compatible Optimizer functions . . . . . . . . . . . . . . . . . . . . . . . . . 330
B.1.2 Incompatible Optimizer functions . . . . . . . . . . . . . . . . . . . . . . . . . . 331
B.2 Initialization and termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
B.3 Loading the matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
B.4 Indices of matrix elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
B.5 Using BCL-compatible functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
B.6 Using the Optimizer with BCL C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
B.7 Using the Optimizer with BCL Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
B.8 Using the Optimizer with BCL .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
C Working with cuts in BCL
340
C.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
C.2 C++ version of the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
C.3 Java version of the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
C.4 .NET version of the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
D Contacting FICO
345
Product support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Product education . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Product documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Sales and maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Related services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
About FICO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Index

Fair Isaac Corporation Confidential and Proprietary Information

347

ix

C HAPTER 1

Introduction
1.1

An overview of Xpress BCL
The FICO R Xpress BCL Builder Component Library provides an environment in which the Xpress
user may readily formulate and solve linear, mixed integer and quadratic programming models.
Using BCL’s extensive collection of functions, complicated models may be swiftly and simply
constructed, preparing problems for optimization. Not merely limited to specific model
construction, however, BCL’s flexibility makes it the ideal engine for embedding in custom
applications for the construction of generic modeling software. In combination with the FICO R
Xpress Optimizer, the two form a powerful combination.
Model formulation using Xpress BCL is constraint-oriented. Such constraints may be built up
either coefficient-wise, incrementally adding linear or quadratic terms until the constraint iscomplete, or through use of arrays of variables, constructing the constraint through a scalar
product of variable and coefficient arrays. The former method allows for easier modification ofmodels once constructed, whilst the latter enables swifter construction of new constraints.
BCL supports the full range of variable types available to users of the Xpress Optimizer:
continuous, semi-continuous, binary, semi-continuous integer, general and partial integer
variables, as well as Special Ordered Sets of types 1 and 2 (SOS1 and SOS2). With additional
functions for specifying directives to aid the global search, BCL enables preparation of every
aspect of complicated (mixed) integer programming problems.
To complement the model construction routines, BCL supports a number of functions which allow
a completed model to be passed directly to the Xpress Optimizer, solved by the optimizer, andsolution information reported back directly from BCL. For situations where the BCL solutionfunctions do not provide enough capability to handle a particular user’s requirements, problems
may be manipulated using the Xpress Optimizer library functions. Such close interactivity
between BCL and the Xpress Optimizer make these two libraries a perfect partnership.
BCL also supports a number of functions allowing easy input and output of model and solution
data. In addition to a set of useful print functions, other functions also enable the export ofconstructed models as matrix files in a number of industry standard formats.

1.2

Note for Optimizer library users
BCL functions cover all aspects of modeling, and perform simple optimization tasks without
making reference to the problem representation (matrix) used by the underlying solution
algorithms. The more advanced Optimizer library user may nevertheless wish to access the
problem matrix directly. It is possible to use all Optimizer library functions with the matrix
generated by BCL. To this end, BCL provides several functions which specifically relate to thematrix representation.

Fair Isaac Corporation Confidential and Proprietary Information

1

Introduction

The function XPRBloadmat explicitly transforms the constraint-wise representation in BCL into thematrix representation required by the Optimizer library. It is usually not necessary to call thisfunction because BCL automatically carries out this transformation whenever required.
The functions XPRBgetcolnum and XPRBgetrownum return the column and row indices associatedwith BCL variables and constraints respectively. While loading the matrix with a call to
XPRBloadmat, all variables that do not occur in any constraint and all empty constraints are
ignored and variable and constraint indices are updated correspondingly (with negative indicesindicating that a variable or constraint is not part of the active matrix in the Optimizer).
It should be stressed that BCL, and thus the arrays storing references to problem variables, does
not keep track of any changes to the matrix occurring during the solution procedure within the
Optimizer. This implies that if linear presolve or integer preprocessing is used, the correct solution
information is available only after the postsolve has been carried out. This is usually done
automatically if the solution algorithm terminates correctly (see the description of
XPRBlpoptimize and XPRBmipoptimize in Chapter 4 for details).
If the matrix is altered directly with Optimizer library functions such as XPRSaddrows or
XPRSchgcoef it is not possible to retrieve the modifications in the BCL model. In order to maintaina coherent status, any such modification has to be carried out in BCL, followed by a call tofunction XPRBloadmat.
Appendix B explains in more detail how to use Optimizer library functions within a BCL program.
Interested users are directed there for details

1.3

Structure of this manual
The main body of the manual is essentially organized into two parts. It begins in Chapter 2, witha brief overview of common BCL functions and their usage, covering model management,
construction, solution and the output of information following optimization. These ideas areextended in Chapter 3, to cover some of the more advanced or less well-known features of thelibrary. The use of index sets, special ordered sets, quadratic programming and user error
handling are all covered here.
Following the first two chapters, the remainder forms the main reference section of the manual.
Chapter 4 details all functions in the library alphabetically, enabling swift access to information
about function syntax and usage, accompanied by examples. This is followed in Chapters 5, 6,
and 7 by a documentation of the C++ interface and summary descriptions of the Java and .NET
interfaces. A list of BCL error and return codes and an overview of usage of BCL with the Xpress
Optimizer library form the Appendices to the manual.
Please note that the full documentation of the Java and .NET interfaces is provided seperately,
see subdirectories docs/bcl/dhtml/javadoc and docs/bcl/bcl.net/HTML of the Xpress installation
directory.

1.4

Conventions used
Throughout the manual standard typographic conventions have been used, representing
computer code fragments with a fixed width font, whilst equations and equation variables
appear in italic type. Where several possibilities exist for the library functions, those with C syntax
have been used, and C style conventions have been used for structures such as arrays etc. Where
appropriate, the following have also been employed:square brackets [...] contain optional material;

curly brackets {...} contain optional material, of which one must be chosen;

Fair Isaac Corporation Confidential and Proprietary Information2

Introduction

entities in italics which appear in expressions stand for meta-variables. The description
following the meta-variable describes how it is to be used;the vertical bar symbol | is found on many keyboards as a vertical line with a small gap in the
middle, but often confusingly displays on screen without the small gap in the middle. In
UNIX it is referred to as the pipe symbol. Note that this symbol is not the same as thecharacter sometimes used to draw boxes on a PC screen. In ASCII, the | symbol is 7C inhexadecimal, 124 decimal.

Fair Isaac Corporation Confidential and Proprietary Information

3

I. Modeling with BCL

C HAPTER 2

Modeling with BCL
This chapter gives an introduction to common BCL functions using BCL in the C language.
Chapters 5 and 6 provide versions of the program examples in this chapter for the C++ and Java
interfaces of BCL respectively. Available functionality for building up constraint expressions withthe object-oriented interfaces differs from what is shown here for C and there are also somespecifities concerning the initialization of BCL with the different interfaces.

2.1

Problem handling

2.1.1

Initialization and termination
Prototypes for all BCL functions are contained in the header file, xprb.h, which needs to be
included at the top of any program which makes BCL function calls. The first stage in the modelbuilding process is to initialize BCL, either explicitly with a call to XPRBinit or implicitly bycreating a new problem with function XPRBnewprob (see below). During its initialization BCL also
initializes the Xpress Optimizer, so if the two are to be used together, a separate call to XPRSinit
is unnecessary (for further detail on using Optimizer functionality with BCL please refer toAppendix B). The initialization function checks for any necessary libraries, and runs security
checks to determine license information about your Xpress installation.
Once models have been constructed and BCL routines are no longer needed, the function
XPRBfree may be called to reset BCL.

2.1.2

Problem creation and deletion
BCL has an object-oriented design. A mathematical model is represented in BCL by a problem
that contains a collection of other objects (variables, constraints, index set etc). Every BCL
function takes as the first argument the object it operates on.
A problem reference in BCL is a variable of type XPRBprob. A problem is created using the
XPRBnewprob function, additionally providing a problem name, in the following way:
XPRBprob prob;...
prob = XPRBnewprob("MyProb");

The problem reference, prob, is subsequently provided as the first argument to functions
operating on the problem.
Once use of a particular problem has ended, the problem should be removed using XPRBdelprob,
freeing associated resources. It should be noted that resources associated with problems are notreleased with a call to XPRBfree, so failure to explicitly delete each problem may result in memory
leakage. It is also possible to delete just the solution information stored by BCL after an

Fair Isaac Corporation Confidential and Proprietary Information

5Modeling with BCL

Initialize a new model

XPRBprob pb1;...
pb1 = XPRBnewprob("Problem1");

Delete problem definition

XPRBdelprob(pb1);

Delete solution information

XPRBresetprob(pb1);

Load problem matrix

XPRBloadmat(pb1);

Fix column ordering

XPRBsetcolorder(pb1,1);

Get problem name

XPRBgetprobname(pb1);

Change problem name

XPRBsetprobname(pb1,"ProbOne");Figure 2.1: Creating, accessing and deleting problems in BCL

optimization run (including all problem-related information loaded in Xpress Optimizer), if thedefinition of the problem is to be kept for later re-use but its solution data is not required any
longer (function XPRBresetprob).
Note that for every BCL problem of type XPRBprob exists a corresponding Xpress Optimizer
problem (type XPRSprob). Although it is usually not necessary to access the optimizer problem
directly in BCL programs, this may be required for certain advanced uses (see Appendix B for
more detail).

2.1.3

Other basic functions
Other functions are also useful for problem handling and manipulation. With XPRBgetprobname,the name for a particular problem specified by a reference may be obtained, and with
XPRBchgprobname it can be changed.
The function XPRBloadmat is really only needed by Optimizer library users. It explicitly transforms
the BCL problem into the matrix representation in the Optimizer, passing the problem directly
into the Optimizer. Usually this is done automatically by BCL whenever required, but it may benecessary to load the matrix without optimizing immediately, e.g. so that an advance basis can beloaded before starting the optimization. The matrix generated by BCL remains unchanged in
repeated executions of the program; the column ordering criterion may be changed by setting
the ordering flag to 1 (function XPRBsetcolorder) before the matrix is loaded.

2.1.4

Input and output settings
BCL supports a number of functions for directing the input and output of a program. Thosefunctions are independent of the particular problem and consequently do not take the problem
pointer as an argument or may be used with a NULL argument. They may be called prior to thecreation of any problem using XPRBnewprob, and even prior to the initialization of BCL. Any other
BCL function will result in an error if it is executed before BCL has been initialized.
Printout of BCL status information, warnings or error messages may be turned off (function
XPRBsetmsglevel). With function XPRBdefcbmsg, the user may define the message callback
function to intercept all output printed by BCL (including messages from the Optimizer libraryand output from the user’s program printed with function XPRBprintf, the latter not being
influenced by the setting of the message print level). Section 3.6 in the next chapter shows anexample of a message callback.
The formating of real numbers used by the BCL output functions (including matrix export) can be
set with the function XPRBsetrealfmt.
For data input in BCL (using functions XPRBreadline and XPRBreadarrline), it is possible to switchfrom the (default) Anglo-American standard of using a decimal point to some other character,such as a decimal comma (XPRBsetdecsign).

Fair Isaac Corporation Confidential and Proprietary Information

6Modeling with BCL

Set number format

XPRBsetrealfmt(prob, "%8.4f");

Set decimal sign

XPRBsetdecsign(’,’);

Set printout level

XPRBsetmsglevel(prob,1);

Set error handling

XPRBseterrctrl(0);Error handling callback

void myerror(XPRBprob my_prob, void *my_object, int num,int type, const char *txt);
XPRBdefcberr(prob,myerror,object);Printing callback

void myprint(XPRBprob my_prob, void *my_object, const char *msgtext);
XPRBdefcbmsg(prob,myprint,object);Get version number

const char *version;
version = XPRBgetversion();Figure 2.2: Input and output settings, and error handling in BCL

2.1.5

Error handling
By default, BCL stops the program execution if an error occurs. With function XPRBseterrctrl theuser may change this behavior: the error messages are still produced but the user’s program has
to provide the error handling. This setting may be useful, for instance, if an BCL program isembedded into some other application or executed under Windows.
Error handling by the user’s program may either be implemented by checking the return valuesof all BCL functions, or preferably, by defining a callback (with function XPRBdefcberr) tointercept all warnings and errors produced by BCL. This function is not influenced by
XPRBsetmsglevel, that is the user may turn off message printing and still be notified about any
errors that occur. Section 3.6 in the next chapter shows an example of an error callback.
When reporting problems with the software, the user should always give the version of BCL. This
information can be obtained with the function XPRBgetversion.

2.2

Variables

2.2.1

Basic functions
In BCL, variables are created one-by-one with a call to the function XPRBnewvar. These variables
may belong to multi-dimensional arrays declared within C. Since one-dimensional arrays ofvariables are used as input to a number of functions, BCL also provides a specific object for thispurpose, the type XPRBarrvar. This object stores a one-dimensional array of variables together
with information about its size. That means such an array of variables may be used as aparameter to a function without having to specify its size separately. Details on specific functions
for creating and accessing variable arrays are given in the following Section 2.2.2.
The length of variable names (like the names of all BCL objects) is unlimited. If no name isspecified the system generates default names ("VAR" followed by an index). A name may occur
repeatedly and, if so, BCL starts indexing the name, commencing with an index of 0.
All types of branching directives available in Xpress can be set via the function XPRBsetvardir,
including priorities, choice of the preferred branching direction and definition of pseudo costs.
Bounds on variables are redefined by functions XPRBsetub, XPRBsetlb, XPRBfixvar, and
XPRBsetlim. Function XPRBsetlim only applies to partial integer, semi-continuous andsemi-integer variables, setting the lower bound of the continuous part or the semi-integer lower
bound. Function XPRBgetbyname retrieves variables or arrays of variables via their name.
Information on variables can be accessed with function XPRBgetvarname, XPRBgetvartype,
XPRBgetcolnum, XPRBgetbounds, and XPRBgetlim. Function XPRBsetvartype changes the variable
type. Figure 2.3 gives an overview of functions related to the creation, update and deletion of

Fair Isaac Corporation Confidential and Proprietary Information

7

Modeling with BCL

Creating variables

XPRBvar y, s[4];y = XPRBnewvar(prob,XPRB_PL,"y",1,10);for(i=0;i<4;i++)s[i]=XPRBnewvar(prob,XPRB_UI,"st",1,10);Creating variable arrays

XPRBarrvar av1, av2;
av1=XPRBnewarrvar(prob,5,XPRB_SC,"a1",0,7);
av2=XPRBstartarrvar(prob,3,"a2");
XPRBapparrvarel(av2,y);
XPRBsetarrvarel(av2,2,s[3]);
XPRBendarrvar(av2);

Accessing variables

double ubd, lbd, lim;
XPRBgetvarname(y);XPRBgetvartype(s[1]);XPRBgetcolnum(av2[0]);XPRBgetbounds(y,&lbd,&ubd);
XPRBgetlim(y,&lim);
XPRBsetvartype(av1[1],XPRB_BV);

Accessing arrays

XPRBgetarrvarname(av2);
XPRBgetarrvarsize(av1);

Delete a variable array

XPRBdelarrvar(av2);

Find by name

XPRBvar y1; XPRBarrvar a1;
y1 = XPRBgetbyname(prob,"y",XPRB_VAR);
a1 = XPRBgetbyname(prob,"a1",XPRB_ARR);

Branching directives

XPRBsetvardir(s[0],PR,1);
XPRBcleardir(prob);

Setting bounds

XPRBsetlb(y,4);
XPRBsetub(s[0],9);
XPRBfixvar(av[2],6);
XPRBsetlim(y,5);Figure 2.3: Functions for creation, update, deletion and access of variables within BCL

variables and arrays of variables.

2.2.2

Variable arrays
BCL provides a specific object for representing one-dimensional arrays of variables, as these areused as input to a number of functions. Variable arrays can be created either in one go, with asingle function call to XPRBnewarrvar, or incrementally by copying single references to previously
defined variables into an array of type XPRBarrvar.
If a variable array is created by a call to XPRBnewarrvar, all of the variables in the array receive thesame type and bounds (these can be modified individually following creation). Otherwise, if thearray is being defined incrementally, any previously defined variables (including elements ofvariable arrays) may be added to the array in an arbitrary order. In this case, the definition of thearray is started by indicating its model name and size in XPRBstartarrvar and terminated by
XPRBendarrvar. Entries can be positioned via XPRBsetarrvarel or simply placed at the firstavailable free position by XPRBapparrvarel. For instance, assume we have defined fourcontinuous variables s[0],..., s[3] and a binary variable b. We may then wish to create an arrayav with the following three elements: av[0] = b, av[1] = s[2], av[2] = s[0]. Regrouping
different variables this way into a single data structure may help render the formulation of
constraints or the access to information about model objects more transparent.
A variable may be copied into several arrays (function XPRBsetarrvarel or XPRBapparrvarel), but
it is created only once as a variable or part of a variable array (using function XPRBnewvar or
XPRBnewarrvar).
Function XPRBgetbyname retrieves arrays of variables via their name. It is also possible to obtainthe name of an array (XPRBgetarrvarname) and its size, that is, the number of variables it contains

Fair Isaac Corporation Confidential and Proprietary Information8Modeling with BCL

P3

XPRBctr ctr

XPRBnewsum(prob,"S1",s,XPRB_L,20);

ctr = XPRBnewctr(prob,"S1",XPRB_L);
for(i=0;i<=3;i++)
XPRBaddterm(ctr,s[i],1);
XPRBaddterm(ctr,NULL,20);i=0 si ≤ 20

P3

i=0 Di · si = 9

XPRBnewarrsum(prob,"S2",s,D, XPRB_E,9);

ctr = XPRBnewctr(prob,"S2",XPRB_E);
XPRBaddarrterm(ctr,s,D);
XPRBaddterm(ctr,NULL,9);s0 + D0 ≤ y(s0 − y ≤ −D0 )XPRBnewprec(prob,"Prc",s[0],D[0],y);

ctr=XPRBnewctr(prob,"Prc",XPRB_L);
XPRBaddterm(ctr,s[0],1);
XPRBaddterm(ctr,y,-1);
XPRBaddterm(ctr,NULL,-D[0]);Figure 2.4: Constraint definition using the constraint functions provided by BCL (left column) or by adding
coefficients (right column)(XPRBgetarrvarsize).
Note:

all variables that are added to an array of variables must belong to the same problem as
the array itself.

2.3

Constraints

2.3.1

Basic functions
Constraints are created either by a call to a specialized constraint function (see Section 2.3.2) orby subsequently adding all the desired terms to a constraint. In the latter case, a new constraint isstarted with function XPRBnewctr by indicating its type and (optionally) its name, variable andconstant terms are added with functions XPRBaddterm, XPRBsetterm and XPRBaddarrterm.
Function XPRBaddterm adds the indicated coefficient value to the coefficient of the variable,
whereas XPRBsetterm overrides any previously defined coefficient for the variable in theconstraint. It is also possible to add an entire array of variables at once to a constraint, together
with the corresponding coefficients (function XPRBaddarrterm). Figure 2.4 gives some examples of
constraint creation.
Currently defined coefficients of linear constraint terms can be retrieved with XPRBgetcoeff, for asingle term, or the terms can be enumerated with XPRBgetnextterm.
Since all functions for constraint definition identify the corresponding constraint via its model
name, constraint definitions may be nested.
The length of constraint names is unlimited. If no name is specified the system generates default
names ("CTR" followed by an index). A name may occur repeatedly and if so, BCL starts indexing
the name, commencing with an index of 0. Variables and variable arrays used in the definition ofa constraint must be defined previously. Any other variables not occurring in this constraint may
be defined later in the model.
After a constraint has been defined, its type may be changed to a range constraint by indicating
the lower and upper bounds in a call to function XPRBsetrange. Function XPRBgetbyname retrieves
constraints via their name and function XPRBgetnextctr can be used to enumerate all constraints
defined in a problem.
A coefficient can be deleted with XPRBdelterm, or an entire constraint definition by XPRBdelctr. It
is possible to retrieve the constraint name (XPRBgetctrname), the matrix row index

Fair Isaac Corporation Confidential and Proprietary Information

9Modeling with BCL(XPRBgetrownum), the constraint size (XPRBgetctrsize), the constraint type (XPRBgetctrtype), therange values (XPRBgetrange, only applicable to ranged constraints) and right hand side value(XPRBgetrhs), as well as changing the constraint type (XPRBsetctrtype). A constraint can betransformed into a model cut (XPRBsetmodcut) and function XPRBgetmodcut indicates whether aconstraint has been defined as a model cut. Similarly, a constraint can be transformed into adelayed row, include vars or indicator constraint with functions XPRBsetdelayed, XPRBsetincvars
or XPRBsetindicator; and it can be checked if a constraint is of these types with functions
XPRBgetdelayed, XPRBgetincvars and XPRBgetindicator.
In addition to the functions for handling linear constraints listed here, BCL also lets you define
quadratic constraints for the formulation of QP and QCQP problems, see Section 3.5 for further
detail.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Set objective function

XPRBctr c;
XPRBsetobj(prob,c);

Set objective sense

XPRBsetsense(prob,XPRB_MAXIM);

Access objective sense

int dir;
dir = XPRBgetsense(prob);

Locate constraint

XPRBctr c;
c = XPRBgetbyname(prob,"Sum1",XPRB_CTR);

Enumerate constraints

XPRBctr c = NULL;
c = XPRBgetnextctr(prob,c);

Define range constraint

XPRBsetrange(c,1,5,15);

Delete a constraint

XPRBdelctr(c);Delete a constraint term

XPRBvar y;
XPRBdelterm(c,y);Accessing constraints

double bdl, bdu;
XPRBgetctrname(c);XPRBgetrange(c,&bdl,&bdu);
XPRBgetrownum(c);XPRBgetctrsize(c);XPRBgetctrtype(c);XPRBsetctrtype(c,XPRB_L);

Enumerate constraint terms

double coeff; const void *ref;ref = XPRBgetnextterm(c,ref,&y,&coeff);

Special constraints

XPRBgetmodcut(c);XPRBsetmodcut(c,1);
XPRBgetdelayed(c);XPRBsetdelayed(c,1);
XPRBgetincvars(c);XPRBsetincvars(c,1);
XPRBgetindicator(c);XPRBgetindvar(c);XPRBsetindicator(c,1,y);Figure 2.5: Defining the objective function and functions for modifying and accessing constraints

2.3.2

Predefined constraint functions
Besides the functions described above for defining constraints incrementally, BCL also provides
some predefined constraint functions for formulating constraints ‘in one go’. The function
XPRBnewarrsum creates a standard linear constraint with the indicated coefficients. The function
XPRBnewsum creates a straight sum of the variables with each coefficient set to one. The function
XPRBnewprec creates a so-called precedence constraint in which a variable plus a constant are lessFair Isaac Corporation Confidential and Proprietary Information

10Modeling with BCL

Solve active problem

XPRBlpoptimize(prob,"p");
XPRBmipoptimize(prob,"");

Status information

XPRBgetprobstat(prob);
XPRBgetlpstat(prob);
XPRBgetmipstat(prob);Get objective value

XPRBgetobjval(prob);

Load solutions

int ncol; double *d; XPRBsol s;
XPRBloadmipsol(prob,d,ncol,1);
XPRBaddmipsol(prob,s);

Solution reading and writing

XPRBreadbinsol(prob,"","");
XPRBreadslxsol(prob,"","");XPRBwritesol(prob,"","");XPRBwritebinsol(prob,"","");XPRBwriteprtsol(prob,"","");XPRBwriteslxsol(prob,"","");

Solution information

XPRBvar y; XPRBctr c;
XPRBgetsol(y); XPRBgetdual(c);XPRBgetrcost(y); XPRBgetslack(c);XPRBgetact(c);Ranging information

XPRBgetvarrng(y,XPRB_UCOST);XPRBgetctrrng(c,XPRB_LOACT);Fix globals

XPRBfixglobals(prob,1);

Advanced bases

XPRBbasis b;
b=XPRBsavebasis(prob);
XPRBloadbasis(b);XPRBdelbasis(b):Figure 2.6: Solving and solution information

than or equal to a second variable (typically, this relation is established between start time
variables in scheduling problems, hence the name).

2.3.3

Objective function
The objective function (Figure 2.5) may be interpreted as a special type of constraint. It is defined
like any other constraint, usually choosing the constraint type XPRB_N. But it is also possible totake a constraint of any other type. In the latter case, the variable terms of the constraint form
the objective function but the equation or inequality expressed by the constraint also remains
part of the problem. The objective function is declared via functions XPRBsetobj. If a different
objective has been defined previously, it is replaced by the new choice.
The sense of the objective function can be set to be minimization (default) or maximization withfunction XPRBsetsense. Function XPRBgetsense returns the sense of the objective function.
All solution functions (XPRBlpoptimize, XPRBmipoptimize) and the problem output with
XPRBexportprob require the objective to be defined. If the sense of the optimization has not beenset, the problem is minimized by default.

2.4

Solving and solution information
As well as enabling model definition, BCL also provides common solving and solution information
functions, as summarized in Figure 2.6. For more advanced tasks the user may employ thecorresponding Optimizer library functions, once the matrix has been loaded into the Optimizer(function XPRBloadmat). However, only the BCL functions can reference the BCL model objects
when retrieving the solution information.
Before any solution function is called, the objective function must be selected using XPRBsetobj.

Fair Isaac Corporation Confidential and Proprietary Information

11Modeling with BCL

It is also required to set the sense of the objective, that is, whether to minimize (default) or to
maximize the objective. All solution functions XPRBlpoptimize, and XPRBmipoptimize can beparameterized to choose the type of solution algorithm. Once the problem has been solved, thefollowing solution information can be obtained: the optimal objective function value(XPRBgetobjval), values for all the problem variables (XPRBgetsol), slack values (XPRBgetslack),
reduced costs (XPRBgetrcost, LP only), constraint activity (XPRBgetact), and dual values(XPRBgetdual, LP only). It is also possible to obtain ranging information for variables(XPRBgetvarrng) and constraints (XPRBgetctrrng) after solving an LP problem.
If the objective function value or solution information for variables or constraints is accessed
during the optimization (for instance from Xpress Optimizer callbacks) the solution informationin BCL needs to be updated with a call to XPRBsync with the parameter XPRB_XPRS_SOL or
XPRB_XPRS_SOLMIP (see Appendix B for more detail).
Before solving or accessing solution information it may be helpful to check the current problem
and/or solution status (using functions XPRBgetprobstat, XPRBgetlpstat and XPRBgetmipstat). It
may happen that a variable defined in the model does not appear in any constraint, or aconstraint only contains 0-valued coefficients so that is ignored when loading the problem into
the Optimizer. In these cases the object’s column or row index is negative and no solution
information can be obtained. It is possible to force the loading of some variables into the
Optimizer by creating a type XPRB_N constraint, adding the variables to this constraint (with any
non-zero coefficients) and setting the constraint to be an include vars constraint with
XPRBsetincvars. Include vars constraints are not loaded into the Optimizer but all variables they
contain are always loaded (even if they don’t appear in other constraints).
When solving MIP problems, the function XPRBfixglobals fixes all the global entities to thevalues of the last found MIP solution. This is useful for example for finding the reduced costs ofthe continuous variables after the global variables have been fixed to their optimal values.
It is possible to load solutions from memory with function XPRBloadmipsol, which loads a solution
into BCL or the Optimizer, or XPRBaddmipsol which can also load partial or infeasible solutions
into the Optimizer. Solutions can also be written and read from file with XPRBwritesol,
XPRBwritebinsol, XPRBwriteprtsol, XPRBwriteslxsol, XPRBreadprtsol, XPRBreadslxsol.
With BCL, it is also possible to save the current basis of a problem in memory and reload (and/or
delete) it after some changes have been carried out to the problem. These changes may include,
for instance, the addition or deletion of variables and constraints.
For more advanced functionality using Optimizer library functions refer to the Optimizer
Reference Manual.

2.5

ExampleThe following example is an extract of a scheduling problem: four jobs with different durations
need to scheduled with the objective to minimize the makespan (= completion time of the lastjob). The complete model also includes resource constraints that are omitted here for clarity’ssake. For every job j its duration DURj is given. We define decision variables startj representing
the start time of jobs and binary variables deltajt indicating whether job j starts in time period t(deltajt = 1). We also define a variable z for the maximum makespan. The makespan can be
expressed as a ‘dummy job’ of duration 0 that is the successor of all other jobs (constraints
Makespan in the model below). We also formulate a precedence relation between two jobs
(constraint Prec). The start time variables need to be linked to the binary variables (constraints
Link). And finally, the binary variables are used to express that every job has a unique start time(constraints One).

Fair Isaac Corporation Confidential and Proprietary Information

12

Modeling with BCL

2.5.1

Model formulation using basic functions#include <stdio.h>#include "xprb.h"#define NJ#define NT410

double DUR[] = {3,4,2,2};
XPRBvar start[NJ];
XPRBvar delta[NJ][NT];XPRBvar z;
XPRBprob prob;/* Number of jobs *//* Time limit *//* Durations of jobs*//* Start times of jobs *//* Binaries for start times *//* Max. completion time *//* BCL problem */void jobs_model(void){
XPRBctr ctr;
int j,t;prob=XPRBnewprob("Jobs");/* Initialization */for(j=0;j<NJ;j++)/* Create start time variables */start[j] = XPRBnewvar(prob, XPRB_PL, "start", 0, NT);z = XPRBnewvar(prob, XPRB_PL, "z", 0, NT); /* Makespan var. */for(j=0;j<NJ;j++)/* Declare binaries for each job
for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] = XPRBnewvar(prob, XPRB_BV, "delta", 0, 1);*/for(j=0;j<NJ;j++)/* Calculate max. completion time */XPRBnewprec(prob, "Makespan", start[j], DUR[j], z);/* Precedence relation betw. jobs */XPRBnewprec(prob, "Prec", start[0], DUR[0], start[2]);for(j=0;j<NJ;j++)/* Linking start times & binaries{
ctr = XPRBnewctr(prob, "Link", XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++)
XPRBaddterm(ctr, delta[j][t], t+1);
XPRBaddterm(ctr, start[j], -1);}*/

for(j=0;j<NJ;j++)/* Unique start time for each job */{ctr = XPRBnewctr(prob, "One", XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++) XPRBaddterm(ctr, delta[j][t], 1);
XPRBaddterm(ctr, NULL, 1);}
ctr = XPRBnewctr(prob, "OBJ", XPRB_N);
XPRBaddterm(ctr, z, 1);
XPRBsetobj(prob, ctr);/* Set objective function *//* Upper bounds on start time variables */for(j=0;j<NJ;j++) XPRBsetub(start[j], NT-DUR[j]+1);
}

2.5.2

Using variable arrays
In the subsequent code, we replace the variables startj and deltajt by arrays of variables start anddeltaj . Note that the variables can still be addressed in the same way as before. The main
advantage of this formulation is that now some of the predefined constraint functions may be
used in the model definition. Changes to the previous version are highlighted in bold.
#include <stdio.h>#include "xprb.h"

Fair Isaac Corporation Confidential and Proprietary Information

13

Modeling with BCL#define NJ#define NT410

double DUR[] = {3,4,2,2};
XPRBarrvar start;
XPRBarrvar delta[NJ];
XPRBvar z;
XPRBprob prob;/* Number of jobs *//* Time limit *//* Durations of jobs*//* Start times of jobs *//* Sets of binaries *//* Maxi. completion time *//* BCL problem */void jobs_model_array(void){
XPRBctr ctr;
int j,t;double c[NT];prob=XPRBnewprob("Jobs");/* Initialization *//* Create start time variables */start = XPRBnewarrvar(prob, NJ, XPRB_PL, "start", 0, NT);z = XPRBnewvar(prob, XPRB_PL, "z", 0, NT); /* Makespan var. */for(j=0;j<NJ;j++)/* Set of binaries for each job */delta[j] = XPRBnewarrvar(prob, (NT-(int)(DUR[j])+1), XPRB_BV,"delta", 0, 1);for(j=0;j<NJ;j++)/* Calculate max. completion time */XPRBnewprec(prob, "Makespan", start[j], DUR[j], z);/* Precedence relation betw. jobs */XPRBnewprec(prob, "Prec", start[0], DUR[0], start[2]);for(j=0;j<NJ;j++)/* Linking start times & binaries{
ctr = XPRBnewctr(prob, "Link", XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++) c[t]=t+1;
XPRBaddarrterm(ctr, delta[j], c);
XPRBaddterm(ctr, start[j], -1);}/* Alternative constraint formulation:for(j=0;j<NJ;j++){ctr = XPRBnewsumc(prob, "Link", delta[j], 1, XPRB_E, 0);
XPRBaddterm(ctr, start[j], -1);
}
*/

*/

for(j=0;j<NJ;j++)/* Unique start time for each job */{ctr = XPRBnewctr(prob, "One", XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++) XPRBaddterm(ctr, delta[j][t], 1);
XPRBaddterm(ctr, NULL, 1);}
ctr = XPRBnewctr(prob, "OBJ", XPRB_N);
XPRBaddterm(ctr, z, 1);
XPRBsetobj(prob, ctr);/* Set objective function *//* Upper bounds on start time variables */for(j=0;j<NJ;j++) XPRBsetub(start[j], NT-DUR[j]+1);}

The set of constraints Link (linking start time variables and binaries) can also be formulated usingarrays and the constraint relation XPRBnewarrsum. These arrays are created by copying references
to previously defined variables. In the example below, they serve only to create this set of
constraints so that there is no need for storing them. If these arrays were to be used later on,
they should be given different names, perhaps using an array av[NJ].
Note that the example below works with both formulations of the model, using single variables

Fair Isaac Corporation Confidential and Proprietary Information

14

Modeling with BCL

or arrays of variables for start times start and indicator variables delta.
for(j=0;j<NJ;j++){double ind[NT];v = XPRBstartarrvar(prob, NT-(int)(DUR[j])+2, "v1");/* Define an array of size NT-DUR[j]+2 */for(t=0;t<(NT-(int)(DUR[j])+1);t++){
XPRBapparrvarel(v, delta[j][t]); /* Add a variable to v */ind[t]=t+1;/* Add a coefficient */}XPRBapparrvarel(v, start[j]);/* Add "start" variable */XPRBendarrvar(v);/* Terminate array def. */ind[NT-(int)DUR[j]+1]=-1;/* Add another coeff. */XPRBnewarrsum(prob, "Link", v, ind, XPRB_E, 0);/* Def. constraint using array v */XPRBdelarrvar(v);/* Free the allocated memory */
}

2.5.3

Completing the example: problem solving and output
We now want to solve the example problem and retrieve the solution values (objective function
and start times of all jobs). We do this with a separate function, jobs_solve. To complete theprogram we write a main that calls the model definition and the solution functions.
void jobs_solve(void){
int statmip;
int j;
XPRBsetsense(prob, XPRB_MINIM);
XPRBmipoptimize(prob, "");/* Solve the problem as MIP */statmip = XPRBgetmipstat();/* Get the problem status */if((statmip == XPRB_MIP_SOLUTION) ||(statmip == XPRB_MIP_OPTIMAL)){/* An integer solution has been found */printf("Objective: %g\n", XPRBgetobjval());
for(j=0;j<NJ;j++)printf("%s: %g\n", XPRBgetvarname(s[j]), XPRBgetsol(s[j]));/* Print out the solution for all start times */}}int main(int argc, char **argv){
jobs_model();jobs_solve();return 0;}/* Problem definition *//* Solve and print solution */If we want to influence the branch-and-bound tree search, we may try setting some branchingdirectives. To prioritize branching on variables that represent early start times the following lines
can be added to csolve before the solution algorithm is started.
for(j=0;j<NJ;j++)for(t=0;t<NT-DUR[j]+1;t++)
XPRBsetvardir(delta[j][t], XPRB_PR, 10*(t+1));/* Give highest priority to var.s for earlier start times */Fair Isaac Corporation Confidential and Proprietary Information

15

C HAPTER 3

Further modeling topics
3.1

Data input and index sets
BCL requires the user to read data into their own structures or data arrays by using standard C
functions for accessing data files. The functions XPRBreadarrline and XPRBreadline read datafrom data files in the diskdata format (see the documentation of the module mmetc in the
Xpress Mosel Language Reference Manual for details). The first function reads (dense) data tables
with all entries of the same type, the second reads tables with items of different types (such as
text strings and numbers). In particular, XPRBreadline is well suited to read sparse data tables
that are indexed by so-called index sets. Roughly speaking, an index set is a set of items such as
text strings that index data tables and other objects in the model in a clearer way than numericalvalues (for details refer to the ‘Xpress Mosel Language Reference Manual’).
A new index set is created by calling function XPRBnewidxset. Set elements are added withfunction XPRBaddidxel. An element of a set can be retrieved either by its name (XPRBgetidxel) orby its order number within the set (using the function XPRBgetidxelname). A data item may bepart of several index sets. Function XPRBgetidxsetsize returns the current size (i.e. the numberof set elements) of an index set.
The definition of index sets may be nested, that is while reading a data file the user may fill up
several index sets at a time. The size of index sets grows automatically as required. The user setssome initial size at the creation of the set, but if less elements are added the size returned by
XPRBgetidxsetsize will be smaller than this value and if more elements are added the size isincreased accordingly.
Data input from file

FILE *datafile;char name[50];double dval, dvals[5];
XPRBreadlinecb(XPRB_FGETS,datafile,200,"T,d",name,&dval);
XPRBreadarrlinecb(XPRB_FGETS,datafile,200,"d;",dvals,5);Create a new index set

XPRBidx set1;
set1 = XPRBnewidxset(prob,"Set1",100);

Add index to a set

XPRBaddidxel(set1,"Prob1");

Accessing index sets

int size, ind;ind = XPRBgetidxel(set1,"Prod1");
name = XPRBgetidxelname(set1,14);
name = XPRBgetidxsetname(set1);
size = XPRBgetidxsetsize(set1);

Figure 3.1: Data input from file and accessing index sets: creation of sets, addition of elements, retrieving elements, andthe index set size.

Fair Isaac Corporation Confidential and Proprietary Information

16

Further modeling topics

3.1.1

ExampleTaking the program example from the previous chapter, we now assume that we want to givenames to the jobs, such as ABC14, DE45F, GH9IJ99, KLMN789. We further assume that thesenames, together with the durations, are given in a separate data file, durations.dat:
ABC14, 3
DE45F, 4
GH9IJ99, 2
KLMN789, 2

If data is read with function XPRBreadline, it is possible to use comments (preceded by !) and line
continuation signs (&) in the data file. (Note that single strings and numbers may not be written
over several lines.) The input function also skips blanks and empty lines. If separator signs otherthan blanks are used, the value 0 may be omitted in the data file (for instance, a data line 0, 0,
0 could as well be written as , , or, using blanks as separators, 0 0 0). The following isfunctionally equivalent to the contents of durations.dat:
ABC14, 3
DE45F, &4
GH9IJ99, 2

!
!
!
!
!

product1, duration1
this line is continued
in the next line
blanks are skipped
as well as empty lines

KLMN789, 2

Separating the input data from the definition allows the same model to be rerun with different
data sets without having to recompile the program code. To accommodate data in this form themodel program must be written or edited appropriately. In the following program, a function fordata input is added to the code seen in the previous chapter. The space for the decision variable
arrays is allocated once the array sizes are known. Notice that we use the job names as the namesof the decision variables.
#include <stdio.h>#include <stdlib.h>#include "xprb.h"#define MAXNJ 4#define NT 10
int NJ=0;
double DUR[MAXNJ];/* Maximum number of jobs *//* Time limit *//* Number of jobs read in *//* Durations of jobs */XPRBidxset Jobs;
XPRBvar *start;
XPRBvar **delta;
XPRBvar z;
XPRBprob prob;/* Job names *//* Start times of jobs *//* Binaries for start times *//* Max. completion time *//* BCL problem */void read_data(void){char name[100];
FILE *datafile;
Jobs = XPRBnewidxset(prob,"jobs",MAXNJ);/* Create a new index set */datafile=fopen("durations.dat","r");/* Open data file for read access */while(NJ<MAXNJ) &&XPRBreadlinecb(XPRB_FGETS, datafile, 99, "T,d", name, &DUR[NJ])){ /* Read in all (non-empty) lines up to the end of the file */XPRBaddidxel(Jobs,name);/* Add job to the index set */NJ++;}
fclose(datafile);/* Close the input file */printf("Number of jobs read: %d\n", XPRBgetidxsetsize(Jobs));}

Fair Isaac Corporation Confidential and Proprietary Information

17

Further modeling topics

void jobs_model(void){
XPRBctr ctr;
int j,t;/* Create start time variables with bounds */start = (XPRBvar *)malloc(NJ * sizeof(XPRBvar));if(start==NULL){ printf("Not enough memory for ’start’ variables.\n");exit(0); }for(j=0;j<NJ;j++)start[j] = XPRBnewvar(prob,XPRB_PL,"start",0,NT-DUR[j]+1);
z = XPRBnewvar(prob,XPRB_PL,"z",0,NT); /* Makespan var. *//* Declare binaries for each job */delta = (XPRBvar **)malloc(NJ * sizeof(XPRBvar*));if(delta==NULL){ printf("Not enough memory for ’delta’ variables.\n");exit(0); }for(j=0;j<NJ;j++){delta[j] = (XPRBvar *)malloc(NT* sizeof(XPRBvar));if(delta[j]==NULL{ printf("Not enough memory for ’delta_j’ variables.\n");exit(0); }delta[j][t] = XPRBnewvar(XPRB_BV,
XPRBnewname("delta%s_%d",XPRBgetidxelname(Jobs,j),t+1),
0,1);}
for(j=0;j<NJ;j++)/* Calculate max. completion time */XPRBnewprec(prob,"Makespan",start[j],DUR[j],z);/* Precedence relation betw. jobs */XPRBnewprec(prob,"Prec",start[0],DUR[0],start[2]);for(j=0;j<NJ;j++)/* Linking start times & binaries{
ctr = XPRBnewctr(prob,"Link",XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++)
XPRBaddterm(ctr,delta[j][t],t+1);
XPRBaddterm(ctr,start[j],-1);}*/

for(j=0;j<NJ;j++)/* Unique start time for each job{
ctr = XPRBnewctr(prob,"One",XPRB_E);
for(t=0;t<(NT-DUR[j]+1);t++) XPRBaddterm(ctr,delta[j][t],1);
XPRBaddterm(ctr,NULL,1);}*/

ctr = XPRBnewctr(prob,"OBJ",XPRB_N);
XPRBaddterm(ctr,z,1);
XPRBsetobj(prob,ctr);/* Set objective function */jobs_solve();/* Solve the problem */free(start);
for(j=0;j<NJ;j++) free(delta[j]);free(delta);}
int main(int argc, char **argv){
prob=XPRBnewprob("Jobs");/* Initialization */read_data();/* Read data from file */jobs_model();/* Define & solve the problem */return 0;}

Fair Isaac Corporation Confidential and Proprietary Information

18

Further modeling topics

XPRBsos set1, set2;
XPRBarrvar s;
Immediate (ref. constraint)

XPRBctr c;
set1=XPRBnewsosrc(prob,"sA",XPRB_S2,s,c);

Immediate (coefficients)

double C[] = 1,2,3,4;
set2=XPRBnewsosw(prob,"sB",XPRB_S1,s,C);

Consecutive definition

set2=XPRBnewsos(prob,"sB",XPRB_S1);
XPRBaddsosarrel(set2,s,C);

Delete set definition

XPRBdelsos(set2);

Accessing sets

XPRBaddsosel(set2,s[2],4,5);
XPRBdelsosel(set1,s[0]);XPRBgetsosname(set1);
XPRBgetsostype(set2);

Figure 3.2: Defining and accessing SOS: immediate (single function) by indicating a reference constraint; or consecutive
definition by adding coefficients for all members.

3.2

Special Ordered Sets

3.2.1

Basic functions
Special Ordered Sets of type n (n=1, 2) are sets of variables of which at most n may be non-zero at
an integer feasible solution. Associated with each set member is a real number (weight),
establishing an ordering among the members of the set. In SOS of type 2, any positive variables
must be adjacent in the sense of this ordering.
In BCL, Special Ordered Sets may be defined in different ways as illustrated in Figure 3.2. As witharrays and constraints, they may be created either with a call to a single function (see Section
3.2.2), or by adding coefficients consecutively.
In the basic, incremental definition, function XPRBnewsos marks the beginning of the definition of
a set. Single members are added by function XPRBaddsosel and arrays by function
XPRBaddsosarrel, each time indicating the corresponding coefficients. Single elements, or an
entire set definition, can be deleted with functions XPRBdelsosel and XPRBdelsos respectively.
BCL also has functions to retrieve the name of a SOS and its type (XPRBgetsosname and
XPRBgetsostype). It is also possible to set branching directives for a SOS (function XPRBsetsosdir),including priorities, choice of the preferred branching direction and definition of pseudo costs.
Note:

3.2.2

all members that are added to a SOS must belong to the same problem as the SOS itself.

Array-based SOS definition
BCL provides two functions for creating Special Ordered Sets with a single function call:
XPRBnewsosrc and XPRBnewsosw. With both functions, a new SOS is created by indicating the type(1 or 2), an array of variables and the corresponding weight coefficients for establishing anordering among the set elements. With XPRBnewsosrc, these coefficients are taken from thevariables’ coefficients in the indicated reference constraint. When using function XPRBnewsosw,
the user directly provides an array of weight coefficients.

3.2.3

ExampleIn the previous examples, instead of defining the delta variables as binaries, the problem can also
be formulated using SOS of type 1. In this case, the delta variables are defined to be continuous
as the SOS1 property and their unit sum ensure that one and only one takes the value one.

Fair Isaac Corporation Confidential and Proprietary Information

19

Further modeling topics

XPRBprob prob;
XPRBvar delta[NJ][NT];XPRBsos set[NJ];/* BCL problem *//* Variables for start times */void jobs_model(void){...
for(j=0;j<NJ;j++)/* Declare a variable for each job */for(t=0;t<NT-DUR[j]+1;t++)/* and for each start time */delta[j][t] = XPRBnewvar(prob, XPRB_PL,
XPRBnewname("delta%d%d",j+1,t+1), 0, 1);for(j=0;j<NJ;j++){/* Create a new SOS1 */set[j] = XPRBnewsos(prob, "sosj", XPRB_S1);
for(t=0;t<NT-D[j]+1;t++)/* Add variables to the SOS */XPRBaddsosel(set[j], delta[j][t], t+1);}}

In order to simplify the definition of the SOS one can use the model formulation with variable
arrays presented in the previous chapter. The constraints Link are employed as the reference
constraints to determine the weight coefficient for each variable (the constraints need to be
stored in an array, Link).
XPRBprob prob;
XPRBarrvar delta[NJ];
XPRBsos set[NJ];/* BCL problem *//* Sets of var.s for start times*/

void jobs_model(void){
XPRBctr Link[NJ];/* "Link" constraints */...
for(j=0;j<NJ;j++)/* Declare a set of var.s for each job */delta[j] = XPRBnewarrvar(prob, (NT-(int)DUR[j]+1), XPRB_PL,
XPRBnewname("delta%d",j+1), 0, 1);for(j=0;j<NJ;j++)/* Linking start times & binaries{
Link[j] = XPRBnewsumc(prob,"Link",delta[j],1,XPRB_E,0);
XPRBaddterm(Link[j],start[j],-1);}*//* Create a SOS1 for each job using constraints "Link" asreference constraints */for(j=0;j<NJ;j++)set[j] = XPRBnewsosrc(prob, "sosj", XPRB_S1, delta[j], Link[j]);}Instead of setting directives on the binary variables, we may now define branching directives for
the SOS1.
for(j=0;j<NJ;j++) XPRBsetsosdir(set[j],XPRB_DN,0);/* First branch downwards on sets */3.3

Loading solutions

3.3.1

Basic functions
With the Xpress Optimizer, it is possible to load external MIP solutions from memory to help the
global search and heuristic algorithms. BCL replicates this same functionality with the
XPRBloadmipsol and XPRBaddmipsol functions. In both cases, with solution we mean just thevariable solution values: no objective value, slack or dual information is passed to the Optimizer

Fair Isaac Corporation Confidential and Proprietary Information

20

Further modeling topics

as part of the solutions . The first function, XPRBloadmipsol, can be used when the solution values
are known for all the model variables and the solution is feasible. The second one,
XPRBaddmipsol, can be used even when only a partial solution is known or the "solution" is not
feasible. If the provided solution is a partial solution or found to be infeasible, the Optimizer will
run a limited local search heuristic in an attempt to find a close feasible integer solution.
In order to be loaded with XPRBaddmipsol, a solution must first be defined as a XPRBsol object. A
new XPRBsol solution can be created with the XPRBnewsol function. Individual variables can thenbe added with function XPRBsetsolvar and arrays of variables with function XPRBsetsolarrvar,
each time indicating the corresponding solution values. The current solution size can be obtainedwith XPRBgetsolsize and assigned variables can be queried or removed with functions
XPRBgetsolvar and XPRBdelsolvar. Finally, the entire solution object can be deleted withfunction XPRBdelsol.
Note that it is also possible load external solutions from file with the XPRBreadbinsol and
XPRBreadslxsol functions.
all variables that are added to a solution must belong to the same problem as thesolution itself.

Note:

3.3.2

ExampleThe following code fragment shows how to create a partial solution and load it into the
Optimizer with XPRBaddmipsol. It also shows how to set a callback function to receive thenotification from the Optimizer on the solution loading outcome, which informs the user if thesolution has been accepted and if it has been found to be feasible or required a reoptimization or
local search heuristic (note that defining this callback is optional). The complete example can befound in file d1wagon2.c.
/* Callback function reporting loaded solution status */void XPRS_CC solnotify(XPRSprob my_prob, void* my_object, const char* solname, int status){
printf("Optimizer loaded solution %s with status=%d\n", solname, status);}
void d1w2_solve(XPRBprob prob){
int b;
XPRBsol sol;...
/* Create a BCL solution from the heuristic solution previously found */sol = XPRBnewsol(prob);/* Set the solution values for some discrete variables */for (b = 0; b < NBOXES; b++) XPRBsetsolvar(sol, load[b][HeurSol[b]], 1);/* Send the solution to the optimizer */XPRBaddmipsol(prob, sol, "heurSol");/* Free the solution object */XPRBdelsol(sol);/* Request notification of solution status after processing */XPRSaddcbusersolnotify(XPRBgetXPRSprob(prob), solnotify, NULL, 0);...
}

Fair Isaac Corporation Confidential and Proprietary Information

21

Further modeling topics

File output

XPRBexportprob(prob,XPRB_MPS,"expl2");

Print model objects

XPRBvar y;
XPRBprintvar(y);XPRBarrvar av;
XPRBprintarrvar(av);
XPRBctr c;
XPRBprintctr(c);XPRBsos s;
XPRBprintsos(s);XPRBidxset is;
XPRBprintidxset(is);XPRBsol sol;
XPRBprintsol(sol);

Print a given problem

XPRBprintprob(prob);

Print program output

XPRBprintf("Print this text");

Compose a name string

int i = 3;
XPRBnewname("abc%d",i);Figure 3.3: File output and printing.

3.4

Output and printing
BCL provides printing functions for variables, constraints, Special Ordered Sets, and index sets
(XPRBprintvar, XPRBprintarrvar, XPRBprintctr, XPRBprintsos, XPRBprintidxset, XPRBprintsol)
as well as the entire model definition (XPRBprintprob). Any program output may be printed with
XPRBprintf in a similar way to the C function printf. The output of all functions mentioned
above is intercepted by the callback XPRBdefcbmsg if this function has previously been defined by
the user.
It is also possible to output the problem to a file in extended LP format or as a matrix in extended
MPS format (function XPRBexportprob). Note that unlike standard LP format, the extended LP
format supports Special Ordered Sets and non-standard variable types (semi-continuous,semi-integer, or partial integers). Like the standard LP format it requires the sense of theobjective function to be defined.

3.4.1

ExampleWe may now augment the last few lines of the model definition (cmodel or cmodel_array) of our
example with some output functions. Note that these output functions may be added at any timeto print the current problem definition in BCL. The function XPRBprintprob prints the complete
BCL problem definition to the standard output. The function XPRBexportprob writes the problem
definition in LP format or as a matrix in extended MPS format to the indicated file.
XPRBprintprob(prob);/* Print out the problem definition */XPRBexportprob(prob,XPRB_MPS,"expl1");/* Output matrix to MPS file */Instead of printing the entire problem with function XPRBprintprob, it is also possible to display
single variables or constraints as soon as they have been defined. The following modified extractof the model definition may serve as an example.
#include <stdio.h>#include "xprb.h"#define NJ

4/* Number of jobs */Fair Isaac Corporation Confidential and Proprietary Information

22

Further modeling topics#define NT10/* Time limit */double DUR[] = {3,4,2,2};
XPRBvar start[NJ];
XPRBprob prob;...
void cmodel(void){
XPRBctr ctr;
int j,t;/* Durations of jobs*//* Start times of jobs *//* BCL problem */prob=XPRBnewprob("Jobs");/* Initialization */for(j=0;j<NJ;j++)/* Create start time variables */{start[j] = XPRBnewvar(prob,XPRB_PL,"start",0,NT);XPRBprintvar(start[j]);XPRBprintf(", ");}...
/* Precedence relation betw. jobs */ctr = XPRBnewprec(prob,"Prec",start[0],DUR[0],start[2]);XPRBprintctr(ctr);
...
}

3.5

Quadratic Programming with BCL
As an extension to LP and MIP, BCL also provides support for formulating and solving Quadratic
Programming (QP) and Mixed Integer Quadratic Programming (MIQP) problems, that is, problems
with linear constraints with a quadratic objective function of the formcT x + x T Qx
where x is the vector of decision variables, c is the cost vector, and Q is the quadratic costcoefficient matrix. The matrix Q must be symmetric. It should also be positive semi-definite if the
problem is to be minimized, and negative semi-definite if it is to be maximized, because theXpress Optimizer solves convex QP problems. If the problem is not convex, the solution
algorithms may not converge at all, or may only converge to a locally optimal solution.
Release 4.0 of BCL extends this functionality to Quadratically Constrained Quadratic
Programming (QCQP) problems, that is, problems that in addition to a quadratic objevctivefunction have constraints of the formaT x + x T Qx ≤ bwhere a is the coefficient vector for the linear terms, b the constant RHS value, and the same
conditions as in objective functions apply to the quadratic coefficient matrix Q (positive
semi-definite in ≤ constraints, and negative semi-definite in ≥ constraints). Quadratic constraints
in QCQP problems must be inequalities.
In BCL, the quadratic part of constraints is defined termwise, much like what we have seen forthe definition of linear constraints in Section 2.3. The coefficient of a quadratic term is either set
to a given value (XPRBsetqterm) or its value is augmented by the given value (XPRBaddqterm).
Quadratic objective functions are set in the same way as linear ones with a call to XPRBsetobj.
Note that the definition of the quadratic constraint terms should always be preceded by thedefinition of the corresponding variables.
The coefficient of a quadratic constraint term can be retrieved with XPRBgetqcoeff. The quadratic
terms of a constraint can be enumerated with XPRBgetnextqterm.

Fair Isaac Corporation Confidential and Proprietary Information

23

Further modeling topics

Add quadratic term

XPRBctr c;
XPRBvar x1;
XPRBaddqterm(c,x1,x1,3);

Set quadratic term

XPRBvar x2;
XPRBsetqterm(c,x1,x2,-7.2);

Delete a quadratic term

XPRBdelqterm(c,x2,x1);

Enumerate quadratic terms

double coeff;
const void *ref;ref = XPRBgetnextqterm(c,ref,&x1,&x1,&coeff);

Figure 3.4: Defining and accessing quadratic terms in BCL.

Unless BCL is used in Student Mode, functions XPRBprintprob, XPRBprintobj, XPRBexportprob, and
XPRBprintctr will print or output to a file the complete problem / constraint definition, including
the quadratic terms.

3.5.1

ExampleWe wish to distribute a set of points represented by tuples of x-/y-coordinates on a plane
minimizing the total squared distance between all pairs of points. For each point i we are given atarget location (CXi , CYi ) and the (square of the) maximum allowable distance Ri to this location.
In mathematical terms, we have two decision variables xi and yi for the coordinates of every point
i. The objective to minimize the total squared distance between all points is expressed by thefollowing sum.
N−1
N 
XX

xi − xj

2+ yi − yj2 

i=1 j=i+1

For every point i we have the following quadratic inequality.
22(xi − CXi ) + (yi − CYi ) ≤ Ri

The following BCL program (xbairport.c) implements and solves this problem.
#include <stdio.h>#include "xprb.h"#define N 42
double CX[N], CY[N], R[N];...
int main(int argc, char **argv){
int i,j;
XPRBprob prob;
XPRBvar x[N],y[N];XPRBctr cobj, c;
prob=XPRBnewprob("airport");/* Initialize the data arrays *//* x-/y-coordinates to determine *//* Initialize a new problem in BCL *//**** VARIABLES ****/
for(i=0;i<N;i++)x[i] = XPRBnewvar(prob, XPRB_PL, XPRBnewname("x(%d)",i), -10, 10);for(i=0;i<N;i++)y[i] = XPRBnewvar(prob, XPRB_PL, XPRBnewname("y(%d)",i), -10, 10);/****OBJECTIVE****//* Minimize the total distance between all points */Fair Isaac Corporation Confidential and Proprietary Information

24

Further modeling topics

cobj = XPRBnewctr(prob, "TotDist", XPRB_N);
for(i=0;i<N-1;i++)for(j=i+1;j<N;j++){
XPRBaddqterm(cobj, x[i], x[i], 1);
XPRBaddqterm(cobj, x[i], x[j], -2);
XPRBaddqterm(cobj, x[j], x[j], 1);
XPRBaddqterm(cobj, y[i], y[i], 1);
XPRBaddqterm(cobj, y[i], y[j], -2);
XPRBaddqterm(cobj, y[j], y[j], 1);}
XPRBsetobj(prob, cobj);/* Set the objective function *//**** CONSTRAINTS ****//* All points within given distance of their target location */for(i=0;i<N;i++){c = XPRBnewctr(prob, XPRBnewname("LimDist_%d",i), XPRB_L);
XPRBaddqterm(c, x[i], x[i], 1);
XPRBaddterm(c, x[i], -2*CX[i]);XPRBaddterm(c, NULL, -CX[i]*CX[i]);XPRBaddqterm(c, y[i], y[i], 1);
XPRBaddterm(c, y[i], -2*CY[i]);XPRBaddterm(c, NULL, -CY[i]*CY[i]);XPRBaddterm(c, NULL, R[i]);}/****SOLVING + OUTPUT****/
XPRBsetsense(prob, XPRB_MINIM);
XPRBlpoptimize(prob,"");/* Sense of optimization *//* Solve the problem */printf("Solution: %g\n", XPRBgetobjval(prob));for(i=0;i<N;i++)printf(" %d: %g, %g\n", i, XPRBgetsol(x[i]), XPRBgetsol(y[i]));return 0;}

3.6

User error handlingIn this section we use a small, infeasible problem to demonstrate how the error handling and all
printed messages produced by BCL can be intercepted by the user’s program. This is done bydefining the corresponding BCL callback functions and changing the error handling flag. If error
handling by BCL is disabled, then the definition of the error callback replaces the necessity tocheck for the return values of the BCL functions called by a program.
User error handling may be required if a BCL program is embedded in some larger application orif the program is run under Windows from an application with windows. In all other cases it willusually be sufficient to use the error handling provided by BCL.
#include <stdio.h>#include <setjmp.h>#include <string.h>#include "xprb.h"
jmp_buf model_failed;/* Marker for the longjump */void modinf(XPRBprob prob){
XPRBvar x[3];
XPRBctr ctr[2], cobj;
int i;
for(i=0;i<2;i++)/* Create two integer variables */x[i]=XPRBnewvar(prob, XPRB_UI, XPRBnewname("x_%d",i),0,100);

Fair Isaac Corporation Confidential and Proprietary Information

25

Further modeling topics/* Create the constraints:
C1: 2x0 + 3x1 >= 41
C2: x0 + 2x1 = 13 */ctr[0]=XPRBnewctr(prob,"C1",XPRB_G);
XPRBaddterm(ctr[0],x[0],2);
XPRBaddterm(ctr[0],x[1],3);
XPRBaddterm(ctr[0],NULL,41);
ctr[1]=XPRBnewctr(prob,"C2",XPRB_E);
XPRBaddterm(ctr[1],x[0],1);
XPRBaddterm(ctr[1],x[1],2);
XPRBaddterm(ctr[1],NULL,13);/* Uncomment the following line to cause an error in the modelthat triggers the user error handling: *//* x[2]=XPRBnewvar(prob, XPRB_UI, "x_2", 10, 1); *//* Objective: minimize x0+x1 */cobj = XPRBnewctr(prob,"OBJ",XPRB_N);
for(i=0;i<2;i++) XPRBaddterm(cobj, x[i], 1);
XPRBsetobj(prob,cobj);/* Select objective function */XPRBsetsense(prob,XPRB_MINIM);/* Obj. sense: minimization */XPRBprintprob(prob);/* Print current problem */XPRBlpoptimize(prob,"");/* Solve the LP */XPRBprintf(prob,"problem status: %d LP status: %d MIP status: %d\n",
XPRBgetprobstat(prob), XPRBgetlpstat(prob),
XPRBgetmipstat(prob));/* This problem is infeasible, that means the following command
will fail. It prints a warning if the message level is atleast 2 */XPRBprintf(prob, "Objective: %g\n", XPRBgetobjval(prob));for(i=0;i<2;i++)/* Print solution values */XPRBprintf(prob, "%s:%g, ", XPRBgetvarname(x[i]),XPRBgetsol(x[i]));
XPRBprintf(prob, "\n");}/**** User error handling function ****/
void XPRB_CC usererror(XPRBprob prob, void *vp, int num,int type, const char *t){
printf("BCL error %d: %s\n", num, t);if(type==XPRB_ERR) longjmp(model_failed,1);}/**** User printing function ****/
void XPRB_CC userprint(XPRBprob prob, void *vp, const char *msg){
static int rtsbefore=1;/* Print ’BCL output’ whenever a new output line starts,
otherwise continue to print the current line. */if(rtsbefore)
printf("BCL output: %s", msg);
else
printf("%s",msg);
rtsbefore=(msg[strlen(msg)-1]==’\n’);}int main(int argc, char **argv){
XPRBprob prob;
XPRBseterrctrl(0);/* Switch to error handling by the

Fair Isaac Corporation Confidential and Proprietary Information

26

Further modeling topics

user’s program *//* Set the printing flag toprinting errors and warnings */XPRBdefcbmsg(NULL, userprint, NULL);/* Define the printing callback func. */XPRBsetmsglevel(NULL,2);

if((prob=XPRBnewprob("ExplInf"))==NULL){/* Initialize a new problem in BCL */fprintf(stderr,"I cannot create the problem\n");return 1;}else
if(setjmp(model_failed))/* Set a marker at this point */{fprintf(stderr,"I cannot build the problem\n");XPRBdelprob(prob);/* Delete the part of the problem
that has been created */XPRBdefcberr(prob, NULL, NULL);/* Reset the error callback */return 1;}
else{
XPRBdefcberr(prob, usererror, NULL);/* Define the error handling callback */modinf(prob);/* Formulate and solve the problem */XPRBdefcberr(prob, NULL, NULL);/* Reset the error callback */return 0;}}

Since this example defines the printing level and the printing callback function before creating
the problem (that is, before BCL is initialized), we pass NULL as first argument.

3.7

Efficent modeling with BCL
This section discusses some recommendations for the efficient use of BCL. Such considerations are
particularly important when working with large-size optimization problems or when solving alarge number of models / model instances in a single application. Our criteria for measuring
efficiency are:model execution speed

memory consumption

Please note that this section is only concerned with modeling aspects. For issues relating to thesolving process, such as the performance of the underlying optimization algorithms, the reader isrefered to the Xpress Optimizer Reference Manual.

3.7.1

Names dictionaries
BCL works with two names dictionaries, the main names dictionary (storing the names of
constraints, decision variables, etc.) and a dedicated dictionary for index set elements. The former
is active by default wheras the latter gets activated only if a model uses index sets. The following
remarks refer principally to the names dictionary.
3.7.1.1

Disabling the names dictionary

If an application does not make use of the names of modeling objects the names dictionary canFair Isaac Corporation Confidential and Proprietary Information

27

Further modeling topics

be disabled to save memory. The function XPRBsetdictsize for resetting the dictionary size canonly be called immediately after the creation of the corresponding problem. Once the dictionary
has been disabled it cannot be enabled any more. All methods relative to the names cannot be
used if this dictionary has been disabled and BCL will not generate any unique names at thecreation of model objects.


C: XPRBsetdictsize(prob, XPRB_DICT_NAMES, 0);

C++: XPRBprob.setDictionarySize(XPRB_DICT_NAMES, 0);Java: XPRBprob.setDictionarySize(XPRB.DICT_NAMES, 0);

C#: XPRBprob.setDictionarySize(BCLconstant.DICT_NAMES, 0);

3.7.1.2

Setting the names dictionary size

If you wish to use the names dictionary we recommend to choose a size close to the number ofvariables+constraints in your problem, preferrably a prime number. (Too small values will slow
down access to the names dictionary, larger values imply higher memory usage.)

3.7.2

Handling of problems
3.7.2.1

Resetting a problem

You should reset a problem to free up memory if the solution information is no longer required(function XPRBresetprob). Resetting a problem deletes any solution information stored in BCL; italso deletes the corresponding Xpress Optimizer problem and removes any auxiliary files that
may have been created by optimization runs.


C: XPRBresetprob(prob);

C++/Java/C#: XPRBprob.reset();Other functions for freeing memory of auxiliary/intermediate structures:
XPRBcleardir, XPRBdelarrvar, XPRBdelbasis, XPRBdelcut
3.7.2.2

Releasing a problem

With C a problem may be deleted explicictly (XPRBdelprob) to free up all memory used by it. In
the object-oriented interfaces make sure to release all references to a problem to enable garbage
collection on the object.
The Java interface also publishes the problem finalizer: XPRBprob.finalize().

3.7.3

Constraint definition
3.7.3.1

Object-oriented interfaces

Overloaded operators and the more algebraic-style definition of constraints via expressions in theobject-oriented interfaces of BCL lead to more easily human-readable models but unfortunately,
they also create many intermediate objects, making them computationally less efficient. With
constraint/expression sizes upwards of 1000 terms a slowdown tends to become noticeable andalternative ways of constraint formulation should be sought.

Fair Isaac Corporation Confidential and Proprietary Information

28

Further modeling topics

The best alternative is to use the addTerm and setTerm methods for constraints or expressions(these avoid the creation of intermediate objects, such as terms or expressions, thus reducing
memory consumption and most often leading to a speed up).
Example:C++:
Replace
ctr += 17*x;by
ctr.addTerm(17, x);



Java:
Replace
ctr.add(x.mul(17));by
ctr.addTerm(x, 17); // or:3.7.3.2

ctr.addTerm(17, x);

Order of enumeration

In pre-Release 2008 versions of BCL it is recomended to enumerate / access decision variables
within loops in the order of their creation. This recommendation does not apply to BCL 4.0 andnewer.

Fair Isaac Corporation Confidential and Proprietary Information29

II. BCL library and class referenceC HAPTER 4

BCL C library functions
A large number of routines are available within the Xpress Builder Component Library, BCL,
ranging from simple routines for the creation and solution of problems to sophisticated callback
functions and interaction with the Xpress Optimizer library.
In BCL, references to modeling objects (problem definitions, variables, constraints, sets, andbases) have the following types:

4.1

XPRBproba problem definition;

XPRBvara variable;

XPRBarrvar

a one-dimensional array, with elements of type XPRBvar;

XPRBctra constraint;

XPRBcut

a cut;

XPRBsola solution;

XPRBsosa Special Ordered Set (SOS1 of SOS2);

XPRBidxset

an index set;

XPRBbasisa basis.

Layout for function descriptions
All functions mentioned in this chapter are described under the following set of headings:
Function name

The description of each routine starts on a new page for the sake of clarity.

PurposeA short description of the routine and its purpose begins the information
section.

Synopsis

A synopsis of the syntax for usage of the routine is provided. ’Optional’
arguments and flags may be specified as NULL if not required. Where thispossibility exists, it will be described alongside the argument, or in the
Further Information at the end of the routine’s description.

Arguments

A list of arguments to the routine with a description of possible values forthem follows.

Return value

A list of possible return values and their meaning.

Fair Isaac Corporation Confidential and Proprietary Information

31

BCL C library functions

ExamplesOne or two examples are provided which explain certain aspects of theroutine’s use.

Further information Additional information not contained elsewhere in the routine’s
description is provided at the end.
Related topics

Finally a list of related routines and topics is provided for comparison andreference.

Fair Isaac Corporation Confidential and Proprietary Information

32

BCL C library functions

XPRBaddarrterm
PurposeAdd multiple linear terms to a constraint.
Synopsis
int XPRBaddarrterm(XPRBctr ctr, XPRBarrvar av, double *coeff);
Arguments
ctr
av
coeff

Reference to a constraint.
Reference to an array of variables.
Values to be added to the coefficients of the variables in the array (the number ofcoefficients must correspond to the size of the array of variables).

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following adds the expression
2*ty1[0] + 13*ty1[1] + 15*ty1[2] + 6*ty1[3] +8.5*ty1[4]to the constraint ctr1.
XPRBprob prob;
XPRBctr ctr1;
XPRBarrvar ty1;
double cr[] = {2, 13, 15, 6, 8.5};...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBaddarrterm(ctr1, ty1, cr);Further information
This function adds multiple linear terms to a constraint, the variables coming from array av andthe corresponding coefficients from coeff. If the constraint already has a term with one of thevariables, the corresponding value from coeff is added to its coefficient.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBaddterm, XPRBdelctr, XPRBdelterm, XPRBnewctr.

Fair Isaac Corporation Confidential and Proprietary Information

33

BCL C library functions

XPRBaddcutarrterm
PurposeAdd multiple linear terms to a cut.
Synopsis
int XPRBaddcutarrterm(XPRBcut cut, XPRBarrvar av, double *coeff);
Arguments
cut
av
coeff

Reference to a cut.
Reference to an array of variables.
Values to be added to the coefficients of the variables in the array (the number ofcoefficients must correspond to the size of the array of variables).

Return value
0 if function executed successfully, 1 otherwise.
ExampleAdd the term

P4

i=0 cri · ty1i to the cut cut1.

XPRBcut cut1;
XPRBarrvar ty1;
double cr[] = {2.0, 13.0, 15.0, 6.0, 8.5};
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");ty1 = XPRBnewarrvar(expl1, 5, XPRB_PL, "arry1", 0, 500);
cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBaddcutarrterm(cut1, ty1, cr);Further information
This function adds multiple linear terms to a cut, the variables coming from array av and thecorresponding coefficients from coeff. If the cut already has a term with one of the variables, thecorresponding value from coeff is added to its coefficient.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutterm, XPRBdelcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

34

BCL C library functions

XPRBaddcuts
PurposeAdd cuts to a problem.
Synopsis
int XPRBaddcuts(XPRBprob prob, XPRBcut *cta, int num);
Arguments
prob
cta
num

Reference to a problem.
Array of previously defined cuts.
Number of cuts in cta.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe example shows how to set up the cut manager node callback to add three previously defined
cuts ca in node 2 of the MIP search. The function call is surrounded by the pair XPRBbegincb and
XPRBendcb to coordinate BCL with the local Optimizer subproblem in the case of a multi-threaded
MIP search.
XPRBcut ca[3];
XPRBprob expl1;
int XPRS_CC usrcme(XPRSprob oprob, void* vd){
int num;
XPRSgetintattrib(oprob, XPRS_NODES, &num);if(num == 2){
XPRBbegincb(expl1, oprob);
XPRBaddcuts(expl1, ca, 3);
XPRBendcb(expl1);}
return 0;}
int main(int argc, char **argv){
XPRSprob oprob;
expl1 = XPRBnewprob("cutexample");...
/* Define the problem and the cuts ’ca’ */XPRBsetcutmode(expl1, 1);/* Enable the cut mode */oprob = XPRBgetXPRSprob(expl1);/* Get Optimizer problem */XPRSsetcbcutmgr(oprob, usrcme, NULL); /* Set cut mgr. callback */XPRBmipoptimize(expl1, "");/* Solve the MIP problem */}Further information
This function adds previously defined cuts to the problem in Xpress Optimizer. It may only becalled from within the Xpress Optimizer cut manager callback functions. BCL does not check for
doubles, that is, if the user defines the same cut twice it will be added twice to the matrix. Cuts
added at a node during the branch and bound search remain valid for all child nodes but areremoved at all other nodes.

Fair Isaac Corporation Confidential and Proprietary Information

35

BCL C library functions

Related topics
XPRBbegincb, XPRBendcb, XPRBnewcut, XPRBdelcut, XPRBsetcutmode.

Fair Isaac Corporation Confidential and Proprietary Information

36

BCL C library functions

XPRBaddcutterm
PurposeAdd a term to a cut.
Synopsis
int XPRBaddcutterm(XPRBcut cut, XPRBvar var, double coeff);
Arguments
cut
var
coeff

Reference to a cut as resulting from XPRBnewcut.
Reference to a variable, may be NULL.
Value to be added to the coefficient of the variable var.

Return value
0 if function executed successfully, 1 otherwise.
ExampleAdd the term 5. 4 · x1 to the cut cut1.
XPRBcut cut1;
XPRBvar x1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");x1 = XPRBnewvar(expl1, XPRB_UI, "abc3", 0, 100);
cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBaddcutterm(cut1, x1, 5.4);
Further information
This function adds a new term to a cut, comprising the variable var with coefficient coeff. If the
cut already has a term with variable var, coeff is added to its coefficient. If var is set to NULL, thevalue coeff is added to the right hand side of the cut.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutarrterm XPRBdelcutterm, XPRBsetcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

37

BCL C library functions

XPRBaddidxel
PurposeAdd an index to an index set.
Synopsis
int XPRBaddidxel(XPRBidxset idx, const char *name);
Arguments
idx
name

A BCL index set.
Name of the index to be added to the set.

Return value
Sequence number of the index within the set, -1 in case of an error.
ExampleThe following defines an index set with space for 100 entries, adds an index to the set and thenretrieves its sequence number.
XPRBprob prob;
XPRBidxset iset;
int val;...
iset = XPRBnewidxset(prob, "Set", 100);val = XPRBaddidxel(iset, "first");Further information
This function adds an index entry to a previously defined index set. The new element is only
added to the set if no identical index already exists. Both in the case of a new index entry and an
existing one, the function returns the sequence number of the index in the index set. Note that,
according to the usual C convention, the numbering of index elements starts with 0.
Related topics
XPRBgetidxel, XPRBnewidxset.

Fair Isaac Corporation Confidential and Proprietary Information

38

BCL C library functions

XPRBaddmipsol
PurposeAdd a new feasible, infeasible or partial MIP solution to the Optimizer.
Synopsis
int XPRBaddmipsol(XPRBprob prob, XPRBsol sol, const char *name);
Arguments
prob
sol
name

Reference to a problem.
Reference to a solution.
An optional name to associate with the solution. Can be NULL.

Return value
0 if function executed successfully, 1 otherwise.
ExampleAdd a MIP solution for problem expl2 to the Optimizer.
XPRBprob expl2;
XPRBsol sol;...
XPRBaddmipsol(prob, sol, "myHeurSol");
XPRBdelsol(sol); /* Free the solution object *//* Request notification of solution status after processing */XPRSaddcbusersolnotify(XPRBgetXPRSprob(prob), solnotify, NULL, 0);
Further information
1. If the matrix loaded in the Optimizer does not correspond to the current state of the specified
problem definition, it is regenerated automatically before adding the solution.
2. The XPRBmipoptimize function by default resets problem status including eventual loadedsolutions; to avoid that, flag "c" should be specified for the alg argument of XPRBmipoptimize
when called after XPRBaddmipsol.
3. The function returns immediately after passing the solution to the Optimizer. The solution isplaced in a pool until the Optimizer is able to analyze the solution during a MIP solve.
4. If the provided solution is partial or found to be infeasible, a limited local search heuristic will be
run in an attempt to find a close feasible integer solution. Values provided for continuouscolumns in partial solutions are currently ignored.
5. The usersolnotify callback can be used to discover the outcome of a loaded solution. The optionalname provided as name will be returned in the callback.
Related topics
XPRBloadmipsol, XPRBloadmat.

Fair Isaac Corporation Confidential and Proprietary Information

39

BCL C library functions

XPRBaddqterm
PurposeAdd a quadratic term to a constraint.
Synopsis
int XPRBaddqterm(XPRBctr ctr, XPRBvar var1, XPRBvar var2,
double coeff);
Arguments
ctr
var1
var2
coeff

Reference to a constraint.
Reference to a variable.
Reference to a variable (not necessarily different).
Value to be added to the coefficient of the term var1 * var2.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following example adds the term -2*x2*x4 to the constraint ctr1:
XPRBctr ctr1;
XPRBvar x2,x4;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
x2 = XPRBnewvar(prob, XPRB_PL, "abc1", 0, XPRB_INFINITY);x4 = XPRBnewvar(prob, XPRB_PL, "abc5",0 , XPRB_INFINITY);XPRBaddqterm(ctr1, x2, x4, -2);
Further information
This function adds a new quadratic term to a constraint, comprising the product of the variables
var1 and var2 with coefficient coeff. If the constraint already has a term with variables var1 andvar2, coeff is added to its coefficient.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBdelqterm, XPRBsetqterm.

Fair Isaac Corporation Confidential and Proprietary Information

40

BCL C library functions

XPRBaddsosarrel
PurposeAdd multiple elements to a SOS.
Synopsis
int XPRBaddsosarrel(XPRBsos sos, XPRBarrvar av, double *weight);
Arguments
sos
av
weightA SOS of type 1 or 2.
An array of variables.
An array of weight coefficients. The number of weights must correspond to the size ofthe array of variables.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following adds an array ty1 with weights cr to the SOS set1.
XPRBprob prob;
XPRBsos set1;
XPRBarrvar ty1;
double cr[] = {2, 13, 15, 6, 8.5};...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBaddsosarrel(set1, ty1, cr);Further information
This function adds an array of variables and their corresponding weights (reference values) to a
SOS. If a variable is already contained in the set, the indicated value is added to its weight. Notethat all weight coefficients must be different from 0.
Note:

all members that are added to a SOS must belong to the same problem as the SOS itself.

Related topics
XPRBaddsosel, XPRBdelsos, XPRBdelsosel, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

41

BCL C library functions

XPRBaddsosel
PurposeAdd an element to a SOS.
Synopsis
int XPRBaddsosel(XPRBsos sos, XPRBvar var, double weight);
Arguments
sosvarweightA SOS of type 1 or 2.
Reference to a variable.
The corresponding weight or reference value.

Return value
0 if function executed successfully, 1 otherwise
ExampleXPRBprob prob;
XPRBsos set1;
XPRBvar x2;...
x2 = XPRBnewvar(prob, XPRB_PL," abc1",0 ,X PRB_INFINITY);
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBaddsosel(set1, x2, 9);This adds a variable x2 with weight 9 to the SOS set1.
Further information
This function adds a single variable and its weight coefficient to a Special Ordered Set. If thevariable is already contained in the set, the indicated value is added to its weight. Note thatweight coefficients must be different from 0.
Note:

all members that are added to a SOS must belong to the same problem as the SOS itself.

Related topics
XPRBaddsosarrel, XPRBdelsos, XPRBdelsosel, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

42

BCL C library functions

XPRBaddterm
PurposeAdd a linear term to a constraint.
Synopsis
int XPRBaddterm(XPRBctr ctr, XPRBvar var, double coeff);
Arguments
ctr
var
coeff

BCL reference to a constraint, resulting from XPRBnewctr.
BCL reference to a variable. May be NULL if not required.
Amount to be added to the coefficient of the variable var.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr1;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBaddterm(ctr1, x1, 5.4);
This adds the term 5.4*x1 to the constraint ctr1.
Further information
This function adds a new linear term to a constraint, comprising the variable var with coefficient
coeff. If the constraint already has a term with variable var, coeff is added to its coefficient. If
var is set to NULL, the value coeff is added to the right hand side of the constraint.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBaddarrterm, XPRBaddqterm, XPRBdelctr, XPRBdelterm, XPRBnewctr, XPRBsetterm.

Fair Isaac Corporation Confidential and Proprietary Information

43

BCL C library functions

XPRBapparrvarel
PurposeAdd an entry to a variable array.
Synopsis
int XPRBapparrvarel(XPRBarrvar av, XPRBvar var);
Argumentsavvar

BCL reference to an array.
The variable to be added.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following inserts the variable x1 in the first free position of the array av2.
XPRBprob prob;
XPRBarrvar av2;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
av2 = XPRBstartarrvar(prob, 5, "arr2");
XPRBapparrvarel(av2, x1);
Further information
This function inserts a variable in the first available position within an array.
Note:

all variables that are added to an array of variables must belong to the same problem as
the array itself.

Related topics
XPRBdelarrvar, XPRBendarrvar, XPRBnewarrvar, XPRBsetarrvarel, XPRBstartarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

44

BCL C library functions

XPRBbegincb
PurposeStart using the local optimizer problem with BCL in a callback.
Synopsis
int XPRBbegincb(XPRBprob bprob, XPRSprob oprob);
Arguments
bprob
oprob

Reference to a BCL problem.
Reference to an Xpress Optimizer problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe example shows how to set up the integer solution callback of Xpress Optimizer to use BCL todisplay the results.
XPRBprob bprob;
XPRBvar x;
void XPRS_CC printsol(XPRSprob oprob, void *my_object){
int num;
XPRSgetintattrib(oprob, XPRS_MIPSOLS, &num);/* Get number of the solution */XPRBbegincb(bprob, oprob);/* Use local Optimizer problem */XPRBsync(bprob, XPRB_XPRS_SOL); /* Update BCL solution values */XPRBprintf(bprob, "Solution %d: Objective value: %g\n",num, XPRBgetobjval(bprob));
XPRBprintf(bprob, "%s: %g\n", XPRBgetvarname(x), XPRBgetsol(x));
XPRBendcb(bprob);/* Reset BCL to main problem */}int main(int argc, char **argv){
XPRSprob oprob;
bprob = XPRBnewprob("cbexample");...
oprob = XPRBgetXPRSprob(bprob);
XPRSsetcbintsol(oprob, printsol, NULL);
XPRBmipoptimize(bprob, "");}/* Define the problem *//* Get Optimizer problem *//* Set the callback *//* Solve the MIP problem */Further information
This function switches from the original problem to the specified (local) optimizer problem for all
BCL accesses to Xpress Optimizer (in particular, for solution updates and the definition of cuts). A
call to this function must precede any call to such BCL functions in optimizer MIP callbacks when
the default multi-threaded MIP search is used for solving a problem. A call to XPRBbegincb must
always be matched by a call to XPRBendcb to reset the optimizer problem within BCL and torelease the BCL problem (access to the BCL problem is locked to the particular thread in between
the two function calls).
Related topics
XPRBendcb, XPRBgetsol, XPRBaddcuts.

Fair Isaac Corporation Confidential and Proprietary Information

45

BCL C library functions

XPRBcleardir
PurposeDelete all directives.
Synopsis
int XPRBcleardir(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBcleardir(expl2);This deletes all directives for the current problem, expl2.
Related topics
XPRBsetvardir, XPRBsetsosdir.

Fair Isaac Corporation Confidential and Proprietary Information

46

BCL C library functions

XPRBdefcbdelvar
PurposeCallback for interface update at deletion of variables.
Synopsis
int XPRBpdefcbdelvar(XPRBprob prob,
void (XPRB_CC *delinter)(XPRBprob eprob, void *evp,
XPRBvar var, void *link), void *vp);
Arguments
prob
delinter
eprob
evp
var
link
vp

Reference to a problem.
User variable interface update function
Problem from which the callback is called
Empty pointer for passing additional information
Reference to a BCL variable
Pointer to an interface object
Empty pointer for the user to pass additional information

Return value
0 if function executed successfully, 1 otherwise.
ExampleDefine the variable interface callback function:
XPRBprob prob;...
void mydelinter(XPRBprob prob, void *vp, XPRBvar var, void *adr){
printf("Deleted: %s", XPRBgetvarname(var));}...
XPRBdefcbdelvar(prob, mydelinter, NULL);
Further information
This function defines a callback function that is called at the deletion of any variable that is usedin an interface to an external program, (that means, if the interface pointer of the variable isdifferent from NULL).
Related topics
XPRBgetvarlink, XPRBsetvarlink.

Fair Isaac Corporation Confidential and Proprietary Information

47

BCL C library functions

XPRBdefcberr
PurposeCallback for user error handling.
Synopsis
int XPRBdefcberr(XPRBprob prob,
void (XPRB_CC *usererr)(XPRBprob my_prob, void *my_object,
int errnum, int type, const char *errtext), void *object);Arguments
prob
usererrmy_prob
my_objecterrnumtype

errtext
objectReference to a problem.
The user’s error handling function.
Problem pointer passed to the callback function.
User-defined object passed to the callback function.
The error number.
Type of the error. This will be one of:
XPRB_ERR
fatal error;
XPRB_WAR
warning.
Text of the error message.
User-defined object to be passed to the callback function.

Return value
0 if function executed successfully, 1 otherwise.
ExampleIn this example a function is defined for displaying errors and exiting if they are suitably severe.
This function is then set as the error-handling callback.
XPRBprob prob;...
void myerr(XPRBprob my_prob, void *my_object, int num, int type,
const char *t){
printf("BCL error %d: %s\n", num, t);if(type == XPRB_ERR) exit(0);}...
XPRBdefcberr(prob, myerror, NULL);

Fair Isaac Corporation Confidential and Proprietary Information

48

BCL C library functions

Further information
1. This function defines the error handling callback that returns the error number and text of error
messages and warnings produced by BCL for a given problem. A list of BCL error messages withsome explanations can be found in the Appendix A of this manual. If printing of error or warning
messages is enabled (see XPRBsetmsglevel) these are printed after the call to this function.
2. It is recommended to define this callback function if the error handling by BCL is disabled (forinstance in BCL programs integrated into larger applications or in BCL programs executed underWindows). Alternatively it is of course possible to test the return values of all BCL functions.
However, the callback provides more detailed information about the type of error that has
occurred.
3. This function may be used before any problems have been created and even before BCL has been
initialized (with first argument NULL). In this case the error handling function set by this callback
applies to all problems that are created subsequently. If this function is called after the creationof a problem, then the version without problem pointer will only influence the global BCL error
handling settings, to change the settings for the specific problem you need to use the problem as
its first argument. Global error handling settings apply to all cases of errors where no problem
information is known, for example in the case of a missing/uninitialized model object used asargument to certain BCL functions.
Related topics
XPRBdefcbmsg, XPRBgetversion, XPRBseterrctrl.

Fair Isaac Corporation Confidential and Proprietary Information

49

BCL C library functions

XPRBdefcbmsg
PurposeCallback for printed output.
Synopsis
int XPRBdefcbmsg(XPRBprob prob,
void (XPRB_CC *userprint)(XPRBprob my_prob, void *my_object,
const char *msgtext), void *object);Arguments
prob
Reference to a problem.
userprint A user message handling function.
my_prob
Problem pointer passed to the callback function.
my_object User-defined object passed to the callback function.
msgtext
The message text.
objectUSer-defined object to be passed to the callback function.
Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following defines a print function and then sets it as a callback.
XPRBprob prob;...
void myprint(XPRBprob prob, void *my_object, const char *msg);{
printf("BCL output: %s\n", msg);}...
XPRBdefcbmsg(prob, myprint, NULL);
Further information
1. This function defines a callback function that returns any messages enabled by the setting of
XPRBsetmsglevel, including warnings and error messages, any other output produced by BCL, andany messages from the Optimizer library. Independent of the message printing settings, thiscallback also returns output printed by the user’s program with function XPRBprintf. If thiscallback is not defined by the user, any program output is printed to standard output with the
exception of warnings and error messages which are printed to the standard error output
channel.
2. This function may be used before any problems have been created and even before BCL has been
initialized (with first argument NULL). In this case the printing function set by this callback applies
to all problems that are created subsequently. If this function is called after the creation of aproblem, then the version without problem pointer will only influence the global BCL message
handling settings, to change the settings for the specific problem you need to use the problem as
its first argument. Global message handling settings apply to all situations where no problem
information is available at the point from where the output is produced, otherwise theproblem-specific message handling will be used.
3. A BCL program must not reset the message callback XPRSsetcbmessage of Xpress Optimizer—
please use the callback chaining function XPRSaddcbmessage (however, all other logging callbacksof the Optimizer may be defined either way).
Related topics
XPRBdefcberr, XPRBsetmsglevel.

Fair Isaac Corporation Confidential and Proprietary Information

50

BCL C library functions

XPRBdelarrvar
PurposeDelete a variable array.
Synopsis
int XPRBdelarrvar(XPRBarrvar av);
Argumentav

BCL reference to an array in the model.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBarrvar av2;...
av2 = XPRBstartarrvar(prob, 5, "arr2");
XPRBendarrvar(av2);
XPRBdelarrvar(av2);
This deletes the array av2, although not any variables that may have been added to it.
Further information
This function deletes the reference to an array. Arrays may be used as auxiliary constructs fordefining constraints. This means it may not be necessary to keep them. If an array is only used in
the model, it can be deleted by a call to this function, thus freeing the corresponding memory
allocated to it. The variables belonging to the array are not deleted by this function if the arrayhas been created with XPRBstartarrvar.
Related topics
XPRBapparrvarel, XPRBendarrvar, XPRBnewarrvar, XPRBsetarrvarel, XPRBstartarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

51

BCL C library functions

XPRBdelbasis
PurposeDelete a previously saved basis.
Synopsisvoid XPRBdelbasis(XPRBbasis basis);Argument
basis

Reference to a previously saved basis.

ExampleThe following code demonstrates saving a basis prior to some matrix changes. Subsequently theold basis is reloaded and the redundant saved basis deleted.
XPRBprob expl2;
XPRBbasis basis;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "");
basis = XPRBsavebasis(expl2);...
XPRBloadmat(expl2);
XPRBloadbasis(basis);
XPRBdelbasis(basis);
XPRBlpoptimize(expl2,"");
Further information
This function deletes a basis that has been saved using function XPRBsavebasis. Typically, thereference to a basis should be deleted if it is not used any more.
Related topics
XPRBloadbasis, XPRBsavebasis.

Fair Isaac Corporation Confidential and Proprietary Information

52

BCL C library functions

XPRBdelctr
PurposeDelete a constraint.
Synopsis
int XPRBdelctr(XPRBctr ctr);
Argument
ctr

BCL reference to a constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBdelctr(ctr1);
This deletes the constraint ctr1.
Further information
Delete a constraint from the given problem. If this constraint has previously been selected as theobjective function (using function XPRBsetobj), the objective will be set to NULL. If the constraint
occurs in a previously saved basis that is to be (re)loaded later on you should change its type to
XPRB_N using XPRBsetctrtype instead of entirely deleting the constraint.
Related topics
XPRBnewctr, XPRBsetctrtype, XPRBloadbasis.

Fair Isaac Corporation Confidential and Proprietary Information

53

BCL C library functions

XPRBdelcut
PurposeDelete a cut definition.
Synopsis
int XPRBdelcut(XPRBcut cut);
Argument
cut

Reference to a cut.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe example shows how to delete cut cut1.
XPRBcut cut1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBdelcut(cut1);
Further information
This function deletes the definition of a cut in BCL, but not the cut itself if it has already been
added to the problem held in Xpress Optimizer (using function XPRBaddcuts).
Related topics
XPRBnewcut, XPRBaddcuts.

Fair Isaac Corporation Confidential and Proprietary Information

54

BCL C library functions

XPRBdelcutterm
PurposeDelete a term from a cut.
Synopsis
int XPRBdelcutterm(XPRBcut cut, XPRBvar var);
Arguments
cut
var

Reference to a cut as resulting from XPRBnewcut.
Reference to a variable in the cut.

Return value
0 if function executed successfully, 1 otherwise.
ExampleAdd the term 5. 4 · x1 to the cut cut1 and then delete it.
XPRBcut cut1;
XPRBvar x1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");x1 = XPRBnewvar(expl1, XPRB_UI, "abc3", 0, 100);
cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBaddcutterm(cut1, x1, 5.4);
XPRBdelcutterm(cut1, x1);
Further information
This function removes a variable term from a cut. The constant term (right hand side value) ischanged/reset with function XPRBsetcutterm.
Related topics
XPRBnewcut, XPRBaddcutarrterm XPRBaddcutterm, XPRBsetcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

55

BCL C library functions

XPRBdelprob
PurposeDelete a problem.
Synopsis
int XPRBdelprob(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleIn this example, the problem expl2 is deleted.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");
XPRBdelprob(expl2);
Further information
This function deletes the given problem in BCL, and the corresponding problem in the Optimizer.
It also deletes any remaining working files associated with this problem. All parameter settings
remain valid after deleting a problem. If the user does not wish to delete a problem but wants tofree some resources used for storing solution information he may call XPRBresetprob.
Related topics
XPRBnewprob, XPRBresetprob.

Fair Isaac Corporation Confidential and Proprietary Information

56

BCL C library functions

XPRBdelqterm
PurposeDelete a quadratic term from a constraint.
Synopsis
int XPRBdelqterm(XPRBctr ctr, XPRBvar var1, XPRBvar var2);
Arguments
ctr
var1
var2

Reference to a constraint.
Reference to a variable.
Reference to a variable (not necessarily different).

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following example first adds the term 5.2*x2*x2 to the constraint ctr1 and then deletes thisterm from the constraint:
XPRBctr ctr1;
XPRBvar x2,x4;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
x2 = XPRBnewvar(prob, XPRB_PL, "abc1", 0, XPRB_INFINITY);XPRBaddqterm(ctr1, x2, x2, 5.2);
XPRBdelqterm(ctr1, x2, x2);
Further information
This function deletes a quadratic term from a constraint, comprising the product of the variables
var1 and var2.
Related topics
XPRBaddqterm, XPRBsetqterm.

Fair Isaac Corporation Confidential and Proprietary Information

57

BCL C library functions

XPRBdelsol
PurposeDelete a solution.
Synopsis
int XPRBdelsol(XPRBsol sol);
Argument
sol

Reference to a previously defined solution.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following deletes the Ssolution sol1.
XPRBprob prob;
XPRBsol sol1;...
sol1 = XPRBnewsol(prob);
XPRBdelsol(sol1);
Further information
This function deletes an XPRBsol solution (without deleting the variables it contains).
Related topics
XPRBdelsolvar, XPRBnewsol, XPRBsetsolarrvar, XPRBsetsolvar.

Fair Isaac Corporation Confidential and Proprietary Information

58

BCL C library functions

XPRBdelsolvar
PurposeDelete a variable from a solution.
Synopsis
int XPRBdelsolvar(XPRBsol, XPRBvar var);
Argumentssolvar

BCL reference to a previously created solution.
BCL reference to a variable.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis code deletes the variable x1 from the solution sol1.
XPRBprob prob;
XPRBsol1 sol1;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);sol1 = XPRBnewsol(prob);
XPRBsetsolvar(sol1, x1, 5.4);...
XPRBdelsolvar(sol1, x1);
Further information
This function deletes a variable (assigned to a value) from the given solution.
Related topics
XPRBdelsol, XPRBnewsol, XPRBsetsolarrvar, XPRBsetsolvar.

Fair Isaac Corporation Confidential and Proprietary Information

59

BCL C library functions

XPRBdelsos
PurposeDelete a SOS.
Synopsis
int XPRBdelsos(XPRBsos sos);Argument
sos

Reference to a previously defined SOS of type 1 or 2.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following deletes the SOS set1.
XPRBprob prob;
XPRBsos set1;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBdelsos(set1);
Further information
This function deletes a SOS without deleting the variables it consists of.
Related topics
XPRBaddsosarrel, XPRBaddsosel, XPRBdelsosel, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

60

BCL C library functions

XPRBdelsosel
PurposeDelete an element from a SOS.
Synopsis
int XPRBdelsosel(XPRBsos sos, XPRBvar var);
Arguments
sosvar

A SOS of type 1 or 2.
Reference to a variable.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following removes the variable x2 from the SOS set1.
XPRBprob prob;
XPRBsos set1;
XPRBvar x2;...
x2 = XPRBnewvar(prob, XPRB_PL, "abc1", 0, XPRB_INFINITY);
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBaddsosel(set1, x2, 9.0);
XPRBdelsosel(set1, x2);
Further information
This function removes a variable from a Special Ordered Set.
Related topics
XPRBaddsosarrel, XPRBaddsosel, XPRBdelsos, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

61

BCL C library functions

XPRBdelterm
PurposeDelete a linear term from a constraint.
Synopsis
int XPRBdelterm(XPRBctr ctr, XPRBvar var);
Arguments
ctr
var

BCL reference to a previously created constraint.
BCL reference to a variable.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis code deletes the variable x1 from the constraint.
XPRBprob prob;
XPRBctr ctr1;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBaddterm(ctr1, x1, 5.4);
XPRBdelterm(ctr1, x1);
Further information
This function deletes a linear term from the given constraint.
Related topics
XPRBaddarrterm, XPRBaddterm, XPRBdelctr, XPRBnewctr, XPRBsetterm.

Fair Isaac Corporation Confidential and Proprietary Information

62

BCL C library functions

XPRBendarrvar
PurposeEnd the definition of a variable array.
Synopsis
int XPRBendarrvar(XPRBarrvar av);
Argumentav

BCL reference to an array.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBarrvar av2;...
av2 = XPRBstartarrvar(prob, 5, "arr2");
XPRBendarrvar(av2);
This terminates the definition of the array av2.
Further information
This function terminates the definition of the array. As the reference to the array is required bythis function in common with all other functions referring to the incremental definition of arrays
it is possible to define several arrays at a time.
Related topics
XPRBdelarrvar, XPRBnewarrvar, XPRBstartarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

63

BCL C library functions

XPRBendcb
PurposeReset BCL to the original optimizer problem in a callback.
Synopsis
int XPRBendcb(XPRBprob bprob);
Argument
bprob

Reference to a BCL problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe example shows how to set up the MIP solution callback to use BCL to display the results.
XPRBprob bprob;
XPRBvar x;
void XPRS_CC printsol(XPRSprob oprob,void *my_object){
int num;
XPRSgetintattrib(oprob, XPRS_MIPSOLS, &num);/* Get number of the solution */XPRBbegincb(bprob, oprob);/* Use local Optimizer problem */XPRBsync(bprob, XPRB_XPRS_SOL); /* Update BCL solution values */XPRBprintf(bprob, "Solution %d: Objective value: %g\n",num, XPRBgetobjval(bprob));
XPRBprintf(bprob, "%s: %g\n", XPRBgetvarname(x), XPRBgetsol(x));
XPRBendcb(bprob);/* Reset BCL to main problem */}int main(int argc, char **argv){
XPRSprob oprob;
bprob = XPRBnewprob("cbexample");...
oprob = XPRBgetXPRSprob(bprob);
XPRSsetcbintsol(oprob, printsol, NULL);
XPRBmipoptimize(bprob, "");}/* Define the problem *//* Get Optimizer problem *//* Set the callback *//* Solve the MIP problem */Further information
This function switches back to the original optimizer problem for all BCL accesses to Xpress
Optimizer. A call to this function terminates a block of calls to BCL functions in an optimizer
callback that is preceded by XPRBbegincb. The call to XPRBendcb releases the BCL problem (accessto the BCL problem is locked to the particular thread between the two function calls).
Related topics
XPRBbegincb.

Fair Isaac Corporation Confidential and Proprietary Information

64

BCL C library functions

XPRBexportprob
PurposePrint problem matrix to a file.
Synopsis
int XPRBexportprob(XPRBprob prob, int format, char *filename);
Arguments
prob
formatfilename

Reference to a problem.
The matrix output file format, which must be one of:
XPRB_LPLP file format (default);
XPRB_MPS
MPS file format.
Name of the output file, without extension.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob expl2;
expl2 = XPRBnewprob("example2");
XPRBexportprob(expl2, XPRB_MPS, "ex2");
This prints the problem in MPS format to the file ex2.mps.
Further information
1. This function prints the matrix to a file with an extended LP or extended MPS format. LP files
receive the extension .lp and MPS files receive the extension .mps. This function is not available
in the student version.
2. When exporting matrices semi-continuous and semi-continuous integer variables are
preprocessed: if a lower bound value greater than 0 is given, then the variable is treated like acontinuous (resp. integer) variable.
3. The precision used by BCL for printing real numbers can be changed with XPRBsetrealfmt toobtain more accurate output for very large or very small numbers. For full precision matrix
output the user is advised to switch to the Optimizer function XPRSwriteprob, preceded by a callto XPRBloadmat (see Appendix B for further detail).
Related topics
XPRBprintprob, XPRBprintf, XPRBsetrealfmt, XPRBloadmat.

Fair Isaac Corporation Confidential and Proprietary Information

65

BCL C library functions

XPRBfinish, XPRBfree
PurposeTerminate BCL and release system resources.
Synopsis
int XPRBfinish(void);
int XPRBfree(void);
Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following tidies up at the end of a BCL session:
XPRBprob prob;
prob = XPRBnewprob(NULL):...
XPRBdelprob(prob);
XPRBfinish();Further information
Importantly, XPRBfinish does not free memory associated with problems. These should all be
removed using the XPRBdelprob function. When running programs that are mainly based on BCL
there is no need to call this function since system resources are freed at the end of the program.
To the contrary, it may be interesting to be able to reset and free resources if a BCL program isembedded into some larger application that continues to work after the BCL part has finished. If
the user does not wish to delete a problem or terminate BCL but wants to free some resources
used for storing solution information he may call XPRBresetprob. Note that XPRBfinish also
terminates Xpress Optimizer if it has been started through BCL. If the Optimizer has been started
with an explicit call to XPRSinit before BCL has been started, then it is not terminated by
XPRBfinish.
Related topics
XPRBdelprob, XPRBresetprob, XPRBinit.

Fair Isaac Corporation Confidential and Proprietary Information

66

BCL C library functions

XPRBfixglobals
PurposeFixes all the global entities to the values of the last found MIP solution.
Synopsis
int XPRBfixglobals(XPRBprob prob, int ifround);Arguments
prob
ifroundReference to a problem.
If all global entities should be rounded to the nearest discrete value in the solution
before being fixed.

Return value
0 if function executed successfully, 1 otherwise.
ExamplePerforms a global search on problem expl2 and then uses XPRBfixglobals before solving theremaining linear problem.
XPRBprob expl2;...
XPRBmipoptimize(expl2, "");XPRBfixglobals(expl2, 1);
XPRBlpoptimize(expl2, "");XPRBwriteprtsol(expl2);
Further information
1. This is useful e.g. for finding the reduced costs for the continuous variables after the global
variables have been fixed to their optimal values. The global variables are fixed to the value ofthe MIP solution only in the Optimizer (not in BCL).
2. In order to eventually resync the bounds of global variables to their original values defined in BCL(i.e. unfix them), a call to XPRBsync with the flag XPRB_XPRS_PROB can be used.
Related topics
XPRBloadmat, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

67

BCL C library functions

XPRBfixvar
PurposeFix a variable.
Synopsis
int XPRBfixvar(XPRBvar var, double val);
Argumentsvarval

BCL reference to a variable.
The value to which the variable is to be fixed.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code sets the value of variable x1 to 20.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);
XPRBfixvar(x1, 20.0);
Further information
This function fixes a variable to the given value. It replaces calls to XPRBsetub and XPRBsetlb. The
value val may lie outside the original bounds of the variable.
Related topics
XPRBgetbounds, XPRBgetlim, XPRBsetlb, XPRBsetlim, XPRBsetub.

Fair Isaac Corporation Confidential and Proprietary Information

68

BCL C library functions

XPRBgetact
PurposeGet activity value for a constraint.
Synopsisdouble XPRBgetact(XPRBctr ctr);
Argument
ctr

Reference to a constraint.

Return value
Activity value for the constraint, 0 in case of an error.
ExampleXPRBprob expl2;
XPRBctr ctr2;
XPRBarrvar ty1;
double act...
expl2 = XPRBnewprob("example2");ty1 = XPRBnewarrvar(expl2, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(expl2, "r2", ty1, XPRB_E, 9);
XPRBlpoptimize(expl2, "");
act = XPRBgetact(ctr2);
This obtains the activity value for the constraint ctr2.
Further information
This function returns the activity value for a constraint. It may be used with constraints that are
not part of the problem (in particular, constraints without relational operators, that is, constraintsof type XPRB_N). In this case the function returns the evaluation of the constraint terms involving
variables that are in the problem. Otherwise, the constraint activity is calculated as activity = RHS– slack.
If this function is called after completion of a global search and an integer solution has beenfound (that is, if function XPRBgetmipstat returns values XPRB_MIP_SOLUTION or
XPRB_MIP_OPTIMAL), it returns the value corresponding to the best integer solution. If no solution
is available this function outputs a warning and returns 0. In all other cases it returns the activity
value in the last LP that has been solved. If this function is used during the execution of an
optimization process (for instance in Optimizer library callback functions) it needs to be precededby a call to XPRBsync with the flag XPRB_XPRS_SOL.
Related topics
XPRBgetdual, XPRBgetobjval, XPRBgetrcost, XPRBgetslack, XPRBgetsol, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

69

BCL C library functions

XPRBgetarrvarname
PurposeGet the name of an array of variables.
Synopsisconst char *XPRBgetarrvarname(XPRBarrvar av);
Argumentav

BCL reference to an array of variables.

Return value
Name of the array if function executed successfully, NULL otherwise.
ExampleXPRBprob prob;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 10, XPRB_PL, "arry1", 0, 500);
printf("%s\n", XPRBgetarrvarname(ty1));This prints the output arry1, the array variable name.
Further information
This function returns the name of an array of variables. If the name was not set by the user, this isa default name generated by BCL.
Related topics
XPRBdelarrvar, XPRBgetarrvarsize, XPRBnewarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

70

BCL C library functions

XPRBgetarrvarsize
PurposeGet the size of an array of variables.
Synopsis
int XPRBgetarrvarsize(XPRBarrvar av);
Argumentav

BCL reference to an array of variables.

Return value
Size (= number of variables) of the array, or -1 in case of an error.
ExampleXPRBprob prob;
XPRBarrvar ty1;
int tsize;...
ty1 = XPRBnewarrvar(prob, 10, XPRB_PL, "arry1", 0, 500);
tsize = XPRBgetarrvarsize(ty1);
This gets the size of the array ty1.
Further information
This function returns the size (i.e. the number of elements) of an array of variables. If thevariables have been added incrementally the returned value may be smaller than the maximum
size given at the creation of the array. The returned size represents the number of variables thathave actually been added to the array.
Related topics
XPRBdelarrvar, XPRBgetarrvarname, XPRBnewarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

71

BCL C library functions

XPRBgetbounds
PurposeGet the bounds on a variable.
Synopsis
int XPRBgetbounds(XPRBvar var, double *bdl, double *bdu);
Arguments
var
bdl
bdu

BCL reference to a variable.
Lower bound value. May be NULL if not required.
Upper bound value. May be NULL if not required.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBvar x1;
double ubound;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
XPRBgetbounds(x1, NULL, &ubound);This retrieves the upper bound of the variable x1.
Further information
This function returns the currently defined bounds on a variable. If bdl or bdu is set to NULL, novalue is returned into the corresponding argument.
Related topics
XPRBfixvar, XPRBgetlim, XPRBsetlb, XPRBsetlim, XPRBsetub.

Fair Isaac Corporation Confidential and Proprietary Information

72

BCL C library functions

XPRBgetbyname
PurposeRetrieve an object by its name.
Synopsisvoid *XPRBgetbyname(XPRBprob prob, const char *name, int type);
Arguments
prob
name
type

Reference to a problem.
The name of the object.
The type of the object sought. This is one of:
XPRB_VARa BCL variable;
XPRB_ARRa BCL array of variables;
XPRB_CTRa BCL constraint;
XPRB_SOSa BCL SOS;XPRB_IDXa BCL index set.

Return value
Reference to a BCL object of the indicated type if function executed successfully, NULL if object
not found or in case of an error.
ExampleThis example finds the variable with the name abc3.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBgetbyname(prob, "abc3", XPRB_VAR);
Further information
The function returns the reference to an object of the indicated type or NULL. The same namemay be used for objects of different types within one problem definition. This function can only
be used if the names dictionary is enabled (functions XPRBsetdictionarysize).
Related topics
XPRBsetdictionarysize, XPRBnewname.

Fair Isaac Corporation Confidential and Proprietary Information

73

BCL C library functions

XPRBgetcoeff
PurposeGet the coefficient of a linear constraint term.
Synopsisdouble XPRBgetcoeff(XPRBctr ctr, XPRBvar var);
Arguments
ctr
var

BCL reference to a previously created constraint.
BCL reference to a variable. May be NULL to indicate the constant term.

Return value
Coefficient of the variable in the specified constraint or 0 if the variable does not occur.
ExampleXPRBprob expl2;
XPRBctr ctr1;
XPRBvar x1;
double val;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 0, 100);
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);
XPRBaddterm(ctr1, x1, 5.4);
val = XPRBgetcoeff(ctr1, x1);
This retrieves the coefficient of the variable x1 in the constraint ctr1.
Further information
This function returns the coefficient of a given variable var in the constraint ctr. Return value 0
indicates that the variable is not contained in the constraint. If var is set to NULL, this function
returns the right hand side (constant term) of the constraint.
Related topics
XPRBaddterm, XPRBgetqcoeff, XPRBgetrhs, XPRBnewctr, XPRBsetterm.

Fair Isaac Corporation Confidential and Proprietary Information

74

BCL C library functions

XPRBgetcolnum
PurposeGet the column number for a variable.
Synopsis
int XPRBgetcolnum(XPRBvar var);
Argumentvar

BCL reference to a variable.

Return value
Column number (non-negative value), or a negative value.
ExampleXPRBprob expl2;
XPRBvar x1;
int vindex;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 0, 100);
vindex = XPRBgetcolnum(x1);This gets the column number for variable x1.
Further information
This function returns the column number of a variable in the matrix currently loaded in the
Xpress Optimizer. If the variable is not part of the matrix, or if the matrix has not yet been
generated, the function returns a negative value. To check whether the matrix has been
generated, use function XPRBgetprobstat. The counting of column numbers starts with 0.
Related topics
XPRBgetvarname, XPRBgetvartype.

Fair Isaac Corporation Confidential and Proprietary Information

75

BCL C library functions

XPRBgetctrname
PurposeGet the name of a constraint.
Synopsisconst char *XPRBgetctrname(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
Name of the constraint if function executed successfully, NULL otherwise
ExampleXPRBprob expl2;
XPRBctr ctr1;...
expl2 = XPRBnewprob("example2");
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);
printf("%s\n", XPRBgetctrname(ctr1));
This prints "r1" as its output.
Further information
This function returns the name of a constraint. If the user has not defined a name the default
name generated by BCL is returned.
Related topics
XPRBgetctrtype, XPRBnewctr.

Fair Isaac Corporation Confidential and Proprietary Information

76

BCL C library functions

XPRBgetctrrng
PurposeGet ranging information for a constraint.
Synopsisdouble XPRBgetctrrng(XPRBctr ctr, int rngtype);
Arguments
ctr
rngtype

Reference to a previously created constraint.
The type of ranging information sought. This is one of:
XPRB_UPACT
upper activity (= the level to which the constraint activity may be
increased at a cost per unit of increase given by the XPRB_UUP
value, ignoring the upper bound on the constraint as specified by
its RHS);
XPRB_LOACT
lower activity (= the level to which the constraint activity may bedecreased at a cost per unit of decrease given by the XPRB_UDN
value, ignoring the lower bound on the constraint as specified by
its RHS);
XPRB_UUP
upper unit cost;
XPRB_UDN
lower unit cost.

Return value
Ranging information of the required type.
ExampleThe following returns the upper activity value of the constraint ctr1.
XPRBprob expl2;
XPRBctr ctr1;
double upact;
expl2 = XPRBnewprob("example2");
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);...
XPRBlpoptimize(expl2, "");
upact = XPRBgetctrrng(ctr1, XPRB_UPACT);
Further information
This method can only be used after solving an LP problem. Ranging information for MIP problems
can be obtained by fixing all discrete variables to their solution values and re-solving the resulting
LP problem.
Related topics
XPRBnewctr,XPRBgetvarrng.

Fair Isaac Corporation Confidential and Proprietary Information

77

BCL C library functions

XPRBgetctrsize
PurposeGet the size of a constraint.
Synopsis
int XPRBgetctrsize(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
Size (= number of linear or quadratic terms with a non-zero coefficient) of the constraint, or -1 incase of an error.
ExampleThe following returns the size of the constraint ctr1.
XPRBprob expl2;
XPRBctr ctr1;
int size;...
expl2 = XPRBnewprob("example2");
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);...
size = XPRBgetctrsize(ctr1);
Related topics
XPRBgetctrname, XPRBngetctrtype, XPRBnewctr.

Fair Isaac Corporation Confidential and Proprietary Information

78

BCL C library functions

XPRBgetctrtype
PurposeGet the row type of a constraint.
Synopsis
int XPRBgetctrtype(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
XPRB_L
XPRB_G
XPRB_E
XPRB_N
XPRB_R-1’less than or equal to’ inequality;’greater than or equal to’ inequality;
equality;a non-binding row (objective function);a range constraint;
an error has occurred.

ExampleThe following returns the type of the constraint ctr1.
XPRBprob expl2;
XPRBctr ctr1;
char rtype;...
expl2 = XPRBnewprob("example2");
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);
rtype = XPRBgetctrtype(ctr1);
Further information
The function returns the constraint type if successful, and -1 in case of an error.
Related topics
XPRBgetctrname, XPRBgetctrsize, XPRBnewctr, XPRBsetctrtype.

Fair Isaac Corporation Confidential and Proprietary Information

79

BCL C library functions

XPRBgetcutid
PurposeGet the classification or identification number of a cut.
Synopsis
int XPRBgetcutid(XPRBcut cut);
Argument
cut

Reference to a previously created cut.

Return value
Classification or identification number.
ExampleGet the classification or identification number of the cut cut1.
XPRBcut cut1;
int cid;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
cid = XPRBgetcutid(cut1);
Further information
This function returns the classification or identification number of a previously defined cut.
Related topics
XPRBnewcut, XPRBgetcuttype, XPRBgetcutrhs, XPRBsetcutid.

Fair Isaac Corporation Confidential and Proprietary Information

80

BCL C library functions

XPRBgetcutrhs
PurposeGet the RHS value of a cut.
Synopsisdouble XPRBgetcutrhs(XPRBcut cut);
Argument
cut

Reference to a previously created cut.

Return value
Right hand side (RHS) value (default 0).
ExampleGet the RHS value of the cut cut1.
XPRBcut cut1;
double rhs;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
rhs = XPRBgetcutrhs(cut1);
Further information
This function returns the RHS value (= constant term) of a previously defined cut. The default RHS
value is 0.
Related topics
XPRBnewcut, XPRBaddcutterm, XPRBgetcutid, XPRBgetcuttype.

Fair Isaac Corporation Confidential and Proprietary Information

81

BCL C library functions

XPRBgetcuttype
PurposeGet the type of a cut.
Synopsis
int XPRBgetcuttype(XPRBcut cut);
Argument
cut

Reference to a previously created cut.

Return value
XPRB_L
XPRB_G
XPRB_E-1≤ (inequality)≥ (inequality)= (equation)
An error has occurred,

ExampleGet the type of cut1.
XPRBcut cut1;
int rtype;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
rtype = XPRBgetcuttype(cut1);
Further information
This function returns the type of the given cut.
Related topics
XPRBnewcut, XPRBgetcutid, XPRBgetcutrhs, XPRBsetcuttype.

Fair Isaac Corporation Confidential and Proprietary Information

82

BCL C library functions

XPRBgetdelayed
PurposeGet the delayed type of a constraint.
Synopsis
int XPRBgetdelayed(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value01-1

an ordinary constraint;
a delayed constraint;
an error has occurred.

ExampleXPRBprob prob;
XPRBctr ctr1;
int dstat;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
dstat = XPRBgetdelayed(ctr1);
This determines whether ctr1 is an ordinary constraint or a delayed constraint.
Further information
This function indicates whether the given constraint is a delayed constraint or an ordinary
constraint.
Related topics
XPRBsetdelayed.

Fair Isaac Corporation Confidential and Proprietary Information

83

BCL C library functions

XPRBgetdual
PurposeGet dual value.
Synopsisdouble XPRBgetdual(XPRBctr ctr);
Argument
ctr

Reference to a constraint.

Return value
Dual value for the constraint, 0 in case of an error.
ExampleXPRBprob expl2;
XPRBctr ctr2;
XPRBarrvar ty1;
double dval;...
expl2 = XPRBnewprob("example2");ty1 = XPRBnewarrvar(expl2, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(expl2, "r2", ty1, XPRB_E, 9);
XPRBlpoptimize(expl2, "");
dval = XPRBgetdual(ctr2);
This obtains the dual value for the constraint ctr2.
Further information
This function returns the dual value for a constraint. The user may wish to test first whether thisconstraint is part of the problem, for instance by checking that the row number is non-negative.
Dual information is available only after LP solving. To obtain dual values for a MIP solution (thatis, if function XPRBgetmipstat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), you needto fix the discrete variables to their solution values with a call to XPRSfixglobals, followed by acall to XPRBlpoptimize before calling XPRBgetdual. Otherwise, if this function is called when a
MIP solution is available it returns 0.
If no solution information is available this function outputs a warning and returns 0.
If this function is used during the execution of an optimization process (for instance in Optimizer
library callback functions) it needs to be preceded by a call to XPRBsync with the flag
XPRB_XPRS_SOL. In this case it returns the dual value in the last LP that has been solved.
Related topics
XPRBgetactivity, XPRBgetobjval, XPRBgetrcost, XPRBgetslack, XPRBgetsol, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

84

BCL C library functions

XPRBgetidxel
PurposeGet the index number of an index.
Synopsis
int XPRBgetidxel(XPRBidxset idx, char *name);
Arguments
idx
name

A BCL set nameName of an index in the set.

Return value
Sequence number of the index in the set, or -1 if not contained.
ExampleXPRBprob prob;
XPRBidxset iset;
int val;...
iset = XPRBnewidxset(prob,"Set",100);
XPRBaddidxel(iset, "first");val = XPRBgetidxel(iset, "first");This defines an index set , iset, with space for 100 entries, adds an index, first, to the set andsubsequently retrieves its sequence number.
Further information
An index element can be accessed either by its name or by its sequence number. This function
returns the sequence number of an index given its name.
Related topics
XPRBaddidxel, XPRBnewidxset.

Fair Isaac Corporation Confidential and Proprietary Information

85

BCL C library functions

XPRBgetidxelname
PurposeGet the name of an index.
Synopsisconst char *XPRBgetidxelname(XPRBidxset idx, int i);Arguments
idx
i

A BCL index set.
Index number.

Return value
Name of the ith element in the set if function executed successfully, NULL otherwise.
ExampleXPRBprob prob;
XPRBidxset iset;
const char *name;...
iset = XPRBnewidxset(prob, "Set", 100);
name = XPRBgetidxelname(iset, 0);This defines an index set, iset, with space for 100 entries and retrieves the name of the index set
element with sequence number 0.
Further information
An index element can be accessed either by its name or by its sequence number. This function
returns the name of an index set element given its sequence number.
Related topics
XPRBaddidxel, XPRBgetidxsetname, XPRBgetidxel, XPRBnewidxset.

Fair Isaac Corporation Confidential and Proprietary Information

86

BCL C library functions

XPRBgetidxsetname
PurposeGet the name of an index set.
Synopsisconst char *XPRBgetidxsetname(XPRBidxset idx);
Argument
idx

A BCL index set.

Return value
Name of the index set if function executed successfully, NULL otherwise.
ExampleThe following defines an index set, iset, with space for 100 entries and then retrieves its name.
XPRBprob prob;
XPRBidxset iset;
const char *name;...
iset = XPRBnewidxset(prob, "Set", 100);
name = XPRBgetidxsetname(iset);
Further information
This function returns the name of an index set.
Related topics
XPRBgetidxelname, XPRBgetidxsetsize, XPRBnewidxset.

Fair Isaac Corporation Confidential and Proprietary Information

87

BCL C library functions

XPRBgetidxsetsize
PurposeGet the size of an index set.
Synopsis
int XPRBgetidxsetsize(XPRBidxset idx);
Argument
idx

A BCL index set.

Return value
Size (= number of elements) of the set, -1 in case of an error.
ExampleThe following defines an index set with space for 100 elements and then retrieves its size.
XPRBprob prob;
XPRBidxset iset;
int size;...
iset = XPRBnewidxset(prob, "Set", 100);
size = XPRBgetidxsetsize(iset);
Further information
This function returns the current number of elements in an index set. This value does notnecessarily correspond to the size specified at the creation of the set. The returned value may besmaller if fewer elements than the originally reserved number have been added, or larger if moreelements have been added. (In the latter case, the size of the set is automatically increased.)
Related topics
XPRBaddidxel,XPRBgetidxsetname, XPRBnewidxset.

Fair Isaac Corporation Confidential and Proprietary Information

88

BCL C library functions

XPRBgetiis
PurposeGet the variables and constraints of an IIS.
Synopsis
int XPRBgetiis(XPRBprob prob, XPRBvar **arrvar, int *numv, XPRBctr **arrctr, int*numc, int numiis);
Arguments
prob
arrvarnumv
arrctrnumc
numiisReference to a problem.
Reference to a table of BCL variables (may be NULL).
Reference to an integer that gets assigned the number of variables returned by thefunction (may be NULL).
Reference to a table of BCL constraints (may be NULL).
Reference to an integer that gets assigned the number of constraints returned by thefunction (may be NULL).
Sequence number of the IIS or value 0 to access the IIS approximation.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following prints out the variable and constraint names of the first IIS found for an infeasible
LP problem.
XPRBprob expl2;
XPRBctr *iisctr;
XPRBvar *iisvar;
int numv, numc;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "");
if(XPRBgetlpstat(expl2)==XPRB_LP_INFEAS){
XPRBgetiis(expl2, &iisvar, &numv, &iisctr, &numc, 1);
printf("Variables: ");/* Print all variables */for(i=0;i<numv;i++) printf("%s ", XPRBgetvarname(iisvar[i]));printf("\n");
XPRBfreemem(iisvar);/* Free the array of variables */printf("Constraints: ");/* Print all constraints */for(i=0;i<numc;i++) printf("%s ", XPRBgetctrname(iisctr[i]));printf("\n");
XPRBfreemem(iisctr);/* Free the array of constraints */}Fair Isaac Corporation Confidential and Proprietary Information

89

BCL C library functions

Further information
1. This function returns the variables and constraints forming an IIS (irreducible infeasible set) in an
infeasible LP problem. The number of independent IIS identified by Xpress Optimizer can beobtained with function XPRBgetnumiis.
2. The arrays of variables and constraints that are allocated by this function must be freed by theuser’s program by calls to XPRBfreemem.
3. The counting of IIS starts at 1. Value 0 for the argument numiis returns the information about
the IIS approximation. Negative values or values larger than the number of IIS identified for the
problem return 0 for the numbers of variables and constraints.
Related topics
XPRBgetnumiis, XPRBgetlpstat, XPRBmiis.

Fair Isaac Corporation Confidential and Proprietary Information

90

BCL C library functions

XPRBgetincvars
PurposeGet the type of a constraint.
Synopsis
int XPRBgetincvars(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value01-1

an ordinary constraint;
an include vars special constraint;
an error has occurred.

ExampleXPRBprob prob;
XPRBctr ctr1;
int mcstat;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_N);
mcstat = XPRBgetincvars(ctr1);
This determines whether ctr1 is an ordinary constraint or an include vars special constraint.
Further information
This function indicates whether the given constraint is an include vars special constraint or an
ordinary constraint.
Related topics
XPRBsetincvars.

Fair Isaac Corporation Confidential and Proprietary Information

91

BCL C library functions

XPRBgetindicator
PurposeGet the type of an indicator constraint.
Synopsis
int XPRBgetindicator(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
0
1
-1
-2

an ordinary constraint;
an indicator constraint with condition b = 1;
an indicator constraint with condition b = 0;an error has occurred.

ExampleXPRBprob prob;
XPRBctr ctr1;
int istat;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
istat = XPRBgetindicator(ctr1);
This determines whether ctr1 is an ordinary constraint or an indicator constraint.
Further information
This function indicates whether the given constraint is an indicator constraint or an ordinary
constraint. In the case of an indicator constraint the return value also specifies the sense of thecondition.
Related topics
XPRBgetindvar, XPRBsetindicator.

Fair Isaac Corporation Confidential and Proprietary Information

92

BCL C library functions

XPRBgetindvar
PurposeGet the variable associated with an constraint.
Synopsis
XPRBvar XPRBgetindvar(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
The indicator variable or NULL in case of an error.
ExampleXPRBprob prob;
XPRBctr ctr1;
XPRBvar x;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
if(XPRBgetindicator(ctr1)==-1){
x = XPRBgetindvar(ctr1);
printf("%s=0 -> %s\n", XPRBgetvarname(x), XPRBgetctrname(ctr1));}
if(XPRBgetindicator(ctr1)==1){
x = XPRBgetindvar(ctr1);
printf("%s=1 -> %s\n", XPRBgetvarname(x), XPRBgetctrname(ctr1));}
This prints out the name of the indicator variable associated with the indicator constraint ctr1
and the sense of the implication.
Further information
This function returns the indicator variable associated with an indicator constraint.
Related topics
XPRBgetindicator, XPRBsetindicator.

Fair Isaac Corporation Confidential and Proprietary Information

93

BCL C library functions

XPRBgetlim
PurposeGet the integer limit for a partial integer or the semi-continuous limit for a semi-continuous orsemi-continuous integer variable.
Synopsis
int XPRBgetlim(XPRBvar var, double *lim);
Argumentsvarlim

BCL reference to a variable.
Limit value.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBvar x3;
double vlim;...
x3 = XPRBnewvar(prob, XPRB_SC, "abc4", 0, 50);
XPRBgetlim(x3, &vlim);
This obtains the lower bound of the continuous part of the variable x3.
Further information
This function returns the currently defined integer limit for a partial integer variable or the lower
semi-continuous limit for a semi-continuous or semi-continuous integer variable.
Related topics
XPRBfixvar, XPRBgetbounds, XPRBsetlb, XPRBsetlim, XPRBsetub.

Fair Isaac Corporation Confidential and Proprietary Information

94

BCL C library functions

XPRBgetlpstat
PurposeGet the LP status.
Synopsis
int XPRBgetlpstat(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0
XPRB_LP_OPTIMAL
XPRB_LP_INFEAS
XPRB_LP_CUTOFFXPRB_LP_UNFINISHED
XPRB_LP_UNBOUNDED
XPRB_LP_CUTOFF_IN_DUAL
XPRB_LP_UNSOLVED
XPRB_LP_NONCONVEX

the problem has not been loaded, or error;
LP optimal;
LP infeasible;
the objective value is worse than the cutoff;
LP unfinished;
LP unbounded;
LP cutoff in dual.
LP problem is not solved.
QP problem is nonconvex;

ExampleThe following returns the current LP status.
XPRBprob expl2;
int status;...
expl2 = XPRBnewprob("example2");
XPRBlpoptimize(expl2, "");
status = XPRBgetlpstat(expl2);
Further information
The return value of this function provides LP status information from the Xpress Optimizer.
Related topics
XPRBgetmipstat, XPRBgetprobstat.

Fair Isaac Corporation Confidential and Proprietary Information

95

BCL C library functions

XPRBgetmiis
PurposeGet the variables, constraints, and SOS of an IIS.
Synopsis
int XPRBgetmiis(XPRBprob prob, XPRBvar **arrvar, int *numv, XPRBctr **arrctr, int*numc, XPRBctr **arrsos, int *nums, int numiis);
Arguments
prob
arrvarnumv
arrctrnumc
arrsosnums
numiisReference to a problem.
Reference to a table of BCL variables (may be NULL).
Reference to an integer that gets assigned the number of variables returned by thefunction (may be NULL).
Reference to a table of BCL constraints (may be NULL).
Reference to an integer that gets assigned the number of constraints returned by thefunction (may be NULL).
Reference to a table of BCL SOS (may be NULL).
Reference to an integer that gets assigned the number of SOS returned by the function(may be NULL).
Sequence number of the IIS or value 0 to access the IIS approximation.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following prints out the variable and constraint names of the first IIS found for an infeasible
LP problem.
XPRBprob expl2;
XPRBctr *iisctr;
XPRBvar *iisvar;
XPRBvar *iissos;
int numv, numc, nums;
expl2 = XPRBnewprob("example2");...
XPRBmipoptimize(expl2, "");
if(XPRBgetmipstat(expl2)==XPRB_MIP_INFEAS){
XPRBgetmiis(expl2, &iisvar, &numv, &iisctr, &numc, &iissos, &nums, 1);
printf("Variables: ");/* Print all variables */for(i=0;i<numv;i++) printf("%s ", XPRBgetvarname(iisvar[i]));printf("\n");
XPRBfreemem(iisvar);/* Free the array of variables */printf("Constraints: ");/* Print all constraints */for(i=0;i<numc;i++) printf("%s ", XPRBgetctrname(iisctr[i]));printf("\n");
XPRBfreemem(iisctr);/* Free the array of constraints */printf("SOS: ");/* Print all SOS */for(i=0;i<nums;i++) printf("%s ", XPRBgetsosname(iissos[i]));printf("\n");
XPRBfreemem(iissos);/* Free the array of SOS */}Fair Isaac Corporation Confidential and Proprietary Information

96

BCL C library functions

Further information
1. This function returns the variables, constraints, and SOS forming an IIS (irreducible infeasible set)in an infeasible MIP problem. The number of independent IIS identified by Xpress Optimizer canbe obtained with function XPRBgetnumiis.
2. The arrays that are allocated by this function must be freed by the user’s program by calls to
XPRBfreemem.
3. The counting of IIS starts at 1. Value 0 for the argument numiis returns the information about
the IIS approximation. Negative values or values larger than the number of IIS identified for the
problem return 0 for the numbers of variables, constraints, and SOS.
Related topics
XPRBgetnumiis, XPRBgetmipstat, XPRBiis.

Fair Isaac Corporation Confidential and Proprietary Information

97

BCL C library functions

XPRBgetmipstat
PurposeGet the MIP status.
Synopsis
int XPRBgetmipstat(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
XPRB_MIP_NOT_LOADEDXPRB_MIP_LP_NOT_OPTIMAL
XPRB_MIP_LP_OPTIMAL
XPRB_MIP_NO_SOL_FOUNDXPRB_MIP_SOLUTIONXPRB_MIP_INFEAS
XPRB_MIP_OPTIMAL
XPRB_MIP_UNBOUNDED

problem has not been loaded, or error;
LP has not been optimized;
LP has been optimized;
global search incomplete — no integer solution found;global search incomplete, although an integer solution has beenfound;
global search complete, but no integer solution found;global search complete and an integer solution has been found.
LP unbounded;

ExampleThe following returns the current MIP status.
XPRBprob expl2;
int status;
expl2 = XPRBnewprob("example2");...
XPRBmipoptimize(expl2, "");
status = XPRBgetmipstat(expl2);
Further information
This function returns the global (MIP) status information from the Xpress Optimizer.
Related topics
XPRBgetlpstat, XPRBgetprobstat.

Fair Isaac Corporation Confidential and Proprietary Information

98

BCL C library functions

XPRBgetnextterm
PurposeGet the next linear term of a constraint.
Synopsisconst void *XPRBgetnextterm(XPRBctr ctr, const void *ref, XPRBvar *var, double*coeff);Arguments
ctr
ref
var
coeff

Constraint whose terms are to be enumerated.
Reference pointer or NULL.
BCL reference to a variable. May be NULL if not required.
Coefficient associated to variable var. May be NULL if not required.

Return value
Reference pointer for the next call to XPRBgetnextterm or NULL if there are no more terms.
ExampleXPRBprob prob;
XPRBctr ctr;
XPRBvar var;
double coeff;
const void *ref;...
ref = NULL;
while ((ref = XPRBgetnextterm(ctr, ref, &var, &coeff)) != NULL) {XPRBprintf("Variable %s has coefficient %g\n",
XPRBgetvarname(var), coeff);}
This code extract prints all linear terms of a constraint.
Further information
This function can be used to enumerate the linear terms of a constraint. The second parameter
serves to keep track of current location in the enumeration; if this parameter is NULL, the firstterm is returned. This function returns NULL if it is called with the reference to the last element.
Otherwise, the returned value can be used as the input parameter ref to retrieve the following
term of the same type. Note that the constant term of the constraint is not included in thisenumeration (it can be retrieved with XPRBgetcoeff)
Related topics
XPRBgetnextqterm, XPRBaddterm.

Fair Isaac Corporation Confidential and Proprietary Information

99

BCL C library functions

XPRBgetnextqterm
PurposeGet the next quadratic term of a constraint.
Synopsisconst void *XPRBgetnextqterm(XPRBctr ctr, const void *ref, XPRBvar *var1, XPRBvar*var2, double *coeff);
Arguments
ctr
ref
var1
var2
coeff

Constraint whose terms are to be enumerated.
Reference pointer or NULL.
BCL reference to a variable. May be NULL if not required.
BCL reference to a variable. May be NULL if not required.
Coefficient associated to the quadratic term var1 * var2. May be NULL if not required.

Return value
Reference pointer for the next call to XPRBgetnextqterm or NULL if there are no more terms.
ExampleXPRBprob prob;
XPRBctr ctr;
XPRBvar var1, var2;
double coeff;
const void *ref;...
ref = NULL;
while ((ref = XPRBgetnextqterm(ctr, ref, &var1, &var2, &coeff))!= NULL) {XPRBprintf("Quadratic term %s * %s has coefficient %g\n",
XPRBgetvarname(var1), XPRBgetvarname(var2), coeff);}
This example prints all quadratic terms of a constraint.
Further information
This function can be used to enumerate the quadratic terms of a constraint. The second
parameter serves to keep track of the current location inthe enumeration; if this parameter is
NULL, the first term is returned. This function returns NULL if it is called with the reference to thelast element. Otherwise, the returned value can be used as the input parameter ref to retrieve
the following term of the same type.
Related topics
XPRBgetnextterm, XPRBaddqterm.

Fair Isaac Corporation Confidential and Proprietary Information

100BCL C library functions

XPRBgetnextctr
PurposeGet the next constraint defined in the problem.
Synopsis
XPRBctr XPRBgetnextctr(XPRBprob prob, XPRBctr ref);Arguments
prob
refReference to a problem.
Reference constraint or NULL.

Return value
The next constraint in the enumeration order, or NULL .
ExampleXPRBprob prob;
XPRBctr ctr;...
ctr = NULL;
while ((ctr = XPRBgetnextctr(prob, ctr)) != NULL) {XPRBprintctr(ctr);}
This prints all constraints defined in the problem.
Further information
This function can be used to enumerate the constraints of a problem. The second parameter
serves to keep track of the current location in the enumeration; if this parameter is NULL, the first
constraint is returned, otherwise the constraint that follows it is returned. This function returns
NULL if ref is the last constraint (or if there are no constraints to enumerate).
Related topics
XPRBnewctr, XPRBgetnextterm.

Fair Isaac Corporation Confidential and Proprietary Information

101

BCL C library functions

XPRBgetmodcut
PurposeGet the model cut type of a constraint.
Synopsis
int XPRBgetmodcut(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value01-1

an ordinary constraint;
a model cut;an error has occurred.

ExampleXPRBprob prob;
XPRBctr ctr1;
int mcstat;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
mcstat = XPRBgetmodcut(ctr1);
This determines whether ctr1 is an ordinary constraint or a model cut.
Further information
This function indicates whether the given constraint is a model cut or an ordinary constraint.
Related topics
XPRBsetmodcut.

Fair Isaac Corporation Confidential and Proprietary Information

102

BCL C library functions

XPRBgetnumiis
PurposeGet the number of independent IIS in an infeasible LP problem.
Synopsis
int XPRBgetnumiis(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Number of independent IIS found by Xpress Optimizer, or a negative value in case of error.
ExampleThe following gets the number of IIS for a problem.
XPRBprob expl2;
int num;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "");
if(XPRBgetlpstat(expl2)==XPRB_LP_INFEAS)
num = XPRBgetnumiis(expl2);
Further information
This function returns the number of independent IIS (irreducible infeasible sets) of an infeasible
LP or MIP problem. After retrieving the number of IIS, the variables and constraints in each set
can be obtained with function XPRBgetiis.
Related topics
XPRBgetiis, XPRBgetlpstat.

Fair Isaac Corporation Confidential and Proprietary Information

103

BCL C library functions

XPRBgetobjval
PurposeGet the objective function value.
Synopsisdouble XPRBgetobjval(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Current objective function value, default and error return value: 0.
ExampleThe following provides an example of retrieving the objective function value.
XPRBprob expl2;
double objval;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "");
objval = XPRBgetobjval(expl2);
Further information
This function returns the current objective function value from the Xpress Optimizer. If it is called
after completion of a global search and an integer solution has been found (that is, if function
XPRBgetmipstat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), it returns the value ofthe best integer solution. In all other cases, including during a global search, it returns thesolution value of the last LP that has been solved. If this function is used during the execution ofan optimization process (for instance in Optimizer library callback functions) it needs to bepreceded by a call to XPRBsync with the flag XPRB_XPRS_SOL.
Related topics
XPRBgetdual, XPRBgetrcost, XPRBgetsol, XPRBgetslack, XPRBgetact, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

104

BCL C library functions

XPRBgetprobname
PurposeGet the name of the specified problem.
Synopsisconst char *XPRBgetprobname(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Name of the problem if function executed successfully, NULL otherwise.
ExampleXPRBprob expl2;
const char *pbname;expl2 = XPRBnewprob("example2");pbname = XPRBgetprobname(expl2);
printf("%s", pbname);
This returns the name of the active problem and prints as output, example2.
Related topics
XPRBdelprob, XPRBnewname, XPRBnewprob, XPRBsetprobname.

Fair Isaac Corporation Confidential and Proprietary Information

105

BCL C library functions

XPRBgetprobstat
PurposeGet the problem status.
Synopsis
int XPRBgetprobstat(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Bit-encoded BCL status information:
XPRB_GEN the matrix has been generated;
XPRB_DIR directives have been added;
XPRB_MOD the problem has been modified;
XPRB_SOL the problem has been solved.
ExampleThe following retrieves the current problem status and (re)solves the problem if it has been
modified.
XPRBprob expl2;
int status;...
expl2 = XPRBnewprob("example2");
status = XPRBgetprobstat(expl2);if((status&XPRB_MOD)==XPRB_MOD)
XPRBlpoptimize(expl2, "");
Further information
This function returns the current BCL problem status. Note that the problem status uses
bit-encoding contrary to the LP and MIP status information, because several states may apply at
the same time.
Related topics
XPRBgetlpstat, XPRBgetmipstat.

Fair Isaac Corporation Confidential and Proprietary Information

106

BCL C library functions

XPRBgetqcoeff
PurposeGet the coefficient of a quadratic constraint term.
Synopsisdouble XPRBgetqcoeff(XPRBctr ctr, XPRBvar var1, XPRBvar var2);
Arguments
ctr
var1
var2

BCL reference to a previously created constraint.
BCL reference to a variable.
BCL reference to a variable (not necessarily different from first variable).

Return value
Coefficient of the variable in the specified constraint or 0 if the variable does not occur.
ExampleXPRBprob expl2;
XPRBctr ctr1;
XPRBvar x1;
double val;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 0, 100);
ctr1 = XPRBnewctr(expl2, "r1", XPRB_E);
XPRBaddqterm(ctr1, x1, x1, 5.4);
val = XPRBgetqcoeff(ctr1, x1, x1);
This retrieves the coefficient of the quadratic term x1*x1 in the constraint ctr1.
Further information
This function returns the coefficient of a given quadratic term var1*var2 in the constraint ctr.
Return value 0 indicates that the term is not contained in the constraint.
Related topics
XPRBaddqterm, XPRBgetcoeff, XPRBgetrhs, XPRBnewctr, XPRBsetqterm.

Fair Isaac Corporation Confidential and Proprietary Information

107

BCL C library functions

XPRBgetrange
PurposeGet the range values for a range constraint.
Synopsis
int XPRBgetrange(XPRBctr ctr, double *bdl, double *bdu);
Arguments
ctr
bdl
bdu

Reference to a range constraint.
Lower bound on the range constraint. May be NULL if not required.
Upper bound on the range constraint. May be NULL if not required.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr2;
XPRBarrvar ty1;
double bdl, bdu;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(prob, "r2", ty1, XPRB_E, 9);
XPRBgetrange(ctr2, &bdl, &bdu);
This obtains the range values for ctr2.
Further information
This function returns the range values of the given constraint. If bdl or bdu is set to NULL, no value
is returned into the corresponding argument.
Related topics
XPRBsetrange.

Fair Isaac Corporation Confidential and Proprietary Information

108

BCL C library functions

XPRBgetrcost
PurposeGet reduced cost value for a variable.
Synopsisdouble XPRBgetrcost(XPRBvar var);
Argument
var

Reference to a variable.

Return value
Reduced cost value for the variable, 0 in case of an error.
ExampleXPRBprob expl2;
XPRBvar x1;
double rcval;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 1, 100);
XPRBlpoptimize(expl2, "");
rcval = XPRBgetrcost(x1);This retrieves the reduced cost value for the variable x1 in the solution to the LP problem.
Further information
This function returns the reduced cost value for a variable. The user may wish to test firstwhether this variable is part of the problem, for instance by checking that the column number is
non-negative.
Reduced cost information is available only after LP solving. To obtain reduced cost values for a
MIP solution (that is, if function XPRBgetmipstat returns values XPRB_MIP_SOLUTION or
XPRB_MIP_OPTIMAL), you need to fix the discrete variables to their solution values with a call to
XPRSfixglobals, followed by a call to XPRBlpoptimize before calling XPRBgetrcost. Otherwise, if
this function is called when a MIP solution is available it returns 0.
If no solution information is available this function outputs a warning and returns 0.
If this function is used during the execution of an optimization process (for instance in Optimizer
library callback functions) it needs to be preceded by a call to XPRBsync with the flag
XPRB_XPRS_SOL. In this case it returns the reduced cost value in the last LP that has been solved.
Related topics
XPRBgetdual, XPRBgetobjval, XPRBgetslack, XPRBgetsol, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

109

BCL C library functions

XPRBgetrhs
PurposeGet the right hand side value of a constraint.
Synopsisdouble XPRBgetrhs(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
Right hand side value of the constraint, 0 in case of an error.
ExampleThe following retrieves the right hand side value of the constraint ctr1.
XPRBprob prob;
XPRBctr ctr1;
double rhs;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
rhs = XPRBgetrhs(ctr1);
Further information
This function returns the right hand side value (i.e. the constant term) of a previously definedconstraint. The default right hand side value is 0. If the given constraint is a ranged constraint
this function returns its upper bound.
Related topics
XPRBaddterm, XPRBgetcoeff, XPRBgetctrtype, XPRBsetctrtype, XPRBsetterm.

Fair Isaac Corporation Confidential and Proprietary Information

110

BCL C library functions

XPRBgetrownum
PurposeGet the row number for a constraint.
Synopsis
int XPRBgetrownum(XPRBctr ctr);
Argument
ctr

Reference to a previously created constraint.

Return value
Row number (non-negative value), or a negative value.
ExampleThe following gets the row number of ctr1.
XPRBprob prob;
XPRBctr ctr1;...
int rindex;
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
rindex = XPRBgetrownum(ctr1);
Further information
This function returns the matrix row number of a constraint. If the matrix has not yet been
generated or the constraint is not part of the matrix (constraint type XPRB_N or no non-zeroterms) then the return value is negative. To check whether the matrix has been generated, usefunction XPRBgetprobstat. The counting of row numbers starts with 0.
Related topics
XPRBdelctr, XPRBnewctr.

Fair Isaac Corporation Confidential and Proprietary Information

111

BCL C library functions

XPRBgetsense
PurposeGet the sense of the objective function.
Synopsis
int XPRBgetsense(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
XPRB_MAXIM
XPRB_MINIM-1the objective function is to be maximized;
the objective function is to be minimized;
an error has occurred.

ExampleThe following returns the sense of the problem expl2.
XPRBprob expl2;
int dir;...
expl2 = XPRBnewprob("example2");
dir = XPRBgetsense(expl2);
Further information
This function returns the objective sense (maximization or minimization). The sense is set tominimization by default and may be changed with function XPRBsetsense.
Related topics
XPRBlpoptimize, XPRBmipoptimize, XPRBsetsense.

Fair Isaac Corporation Confidential and Proprietary Information

112

BCL C library functions

XPRBgetslack
PurposeGet slack value for a constraint.
Synopsisdouble XPRBgetslack(XPRBctr ctr);
Argument
ctr

Reference to a constraint.

Return value
Slack value for the constraint, 0 in case of an error.
ExampleXPRBprob expl2;
XPRBctr ctr2;
XPRBarrvar ty1;
double slack;...
expl2 = XPRBnewprob("example2");ty1 = XPRBnewarrvar(expl2, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(expl2, "r2", ty1, XPRB_E, 9);
XPRBlpoptimize(expl2, "");
slack = XPRBgetslack(ctr2);
This obtains the slack value for the constraint ctr2.
Further information
This function returns the slack value for a constraint. The user may wish to test first whether thisconstraint is part of the problem, for instance by checking that the row number is non-negative.
If this function is called after completion of a global search and an integer solution has beenfound (that is, if function XPRBgetmipstat returns values XPRB_MIP_SOLUTION or
XPRB_MIP_OPTIMAL), it returns the value in the best integer solution. If no integer solution isavailable after a global search this function outputs a warning and returns 0. In all other cases it
returns the slack value in the last LP that has been solved. If this function is used during theexecution of an optimization process (for instance in Optimizer library callback functions) it needs
to be preceded by a call to XPRBsync with the flag XPRB_XPRS_SOL.
Related topics
XPRBgetact, XPRBgetdual, XPRBgetobjval, XPRBgetrcost, XPRBgetsol, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

113

BCL C library functions

XPRBgetsol
PurposeGet solution value for a variable.
Synopsisdouble XPRBgetsol(XPRBvar var);
Argument
var

Reference to a variable.

Return value
Primal solution value for the variable, 0 in case of an error.
ExampleXPRBprob expl2;
XPRBvar x1;
double solval;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 1, 100);
XPRBlpoptimize(expl2, "");
solval = XPRBgetsol(x1);
The example retrieves the LP solution value for the variable x1.
Further information
1. This function returns the current solution value for a variable. The user may wish to test firstwhether this variable is part of the problem, for instance by checking that the column number is
non-negative.
If this function is called after completion of a global search and an integer solution has beenfound (that is, if function XPRBgetmipstat returns values XPRB_MIP_SOLUTION or
XPRB_MIP_OPTIMAL), it returns the value of the best integer solution. If no integer solution isavailable after a global search this function outputs a warning and returns 0. In all other cases it
returns the solution value in the last LP that has been solved. If this function is used during theexecution of an optimization process (for instance in Optimizer library callback functions) it needs
to be preceded by a call to XPRBsync with the flag XPRB_XPRS_SOL.
2. Note that “integer solution” means “solution within the integer feasibility limits”, that means forany comparison of solution values the current Optimizer tolerance settings have to be taken into
account. So care must be taken when handling the solution values of integer variables. For
example, you cannot simply treat the value as an integer, because a value such as 0.999998, may
well be truncated to zero. Instead, you must make sure you round the value to the nearest
integer.
Related topics
XPRBgetact, XPRBgetdual, XPRBgetobjval, XPRBgetrcost, XPRBgetslack, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

114

BCL C library functions

XPRBgetsolvar
PurposeGet the value assigned to a variable in a solution.
Synopsis
int XPRBgetsolvar(XPRBsol sol, XPRBvar var, double *val);
Arguments
sol
var
val

Reference to a previously created solution.
Reference to a previously created variable.
Pointer to a double where the value will be returned.

Return value
0-11

variable var is assigned a value in the solution and the value is returned in val;variable var is not assigned any value in the solution (val is left unmodified);
an error has occurred.

ExampleThe following example retrieves the value assigned to variable x1 in the solution sol1.
XPRBprob expl2;
XPRBsol sol1;
XPRBvar x1;
double val;...
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 0, 100);sol1 = XPRBnewsol(expl2);
XPRBsetsolvar(sol1, x1, 5.4);
XPRBgetsolvar(sol1, x1, &val);
Related topics
XPRBdelsolvar, XPRBnewsol, XPRBsetsolvar, XPRBsetsolarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

115

BCL C library functions

XPRBgetsolsize
PurposeGet the size of an XPRBsol solution.
Synopsis
int XPRBgetsolsize(XPRBsol sol);
Argument
sol

Reference to a previously created solution.

Return value
Size (= number of variables that have been assigned a value) of the solution, or -1 in case of anerror.
ExampleThe following returns the size of the solution sol1.
XPRBprob expl2;
XPRBsol sol1;
int size;...
expl2 = XPRBnewprob("example2");sol1 = XPRBnewsol(expl2);...
size = XPRBgetsolsize(sol1);
Related topics
XPRBdelsolvar, XPRBnewsol, XPRBsetsolvar, XPRBsetsolarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

116

BCL C library functions

XPRBgetsosname
PurposeGet the name of a SOS.
Synopsisconst char *XPRBgetsosname(XPRBsos sos);Argument
sos

Reference to a previously created SOS.

Return value
Name of the SOS if function executed successfully, NULL otherwise.
ExampleXPRBprob prob;
XPRBsos set1;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
printf("%s\n", XPRBgetsosname(set1));
The prints "sos1" as output.
Further information
This function returns the name of a SOS. If the user has not defined a name the default namegenerated by BCL is returned.
Related topics
XPRBdelsos, XPRBgetsostype, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

117

BCL C library functions

XPRBgetsostype
PurposeGet the type of a SOS.
Synopsis
int XPRBgetsostype(XPRBsos sos);Argumentsos
Return value
XPRB_S1
XPRB_S2-1

Reference to a previously created SOS.
a Special Ordered Set of type 1;
a Special Ordered Set of type 2;
an error has occurred.

ExampleXPRBprob prob;
XPRBsos set1;
char stype;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
stype = XPRBgetsostype(set1);
This returns the type of the SOS set1.
Further information
The function returns the type of a SOS.
Related topics
XPRBdelsos, XPRBgetsosname, XPRBnewsos.

Fair Isaac Corporation Confidential and Proprietary Information

118

BCL C library functions

XPRBgettime
PurposeGet the running time.
Synopsis
int XPRBgettime(void);
Return value
System time measure in milliseconds.
ExampleThe following provides an example of obtaining the running time for code.
int starttime;
starttime = XPRBgettime();...
printf("Time: \%g sec", (XPRBgettime()-starttime)/1000);Further information
This function returns the system time measure in milliseconds. The absolute value issystem-dependent. To measure the execution time of a program, this function can be used to
calculate the difference between the start time and the time at the desired point in the program.
Related topics
XPRBgetversion.

Fair Isaac Corporation Confidential and Proprietary Information

119

BCL C library functions

XPRBgetvarlink
PurposeGet the interface pointer of a variable.
Synopsisvoid *XPRBgetvarlink(XPRBvar var);
Argument
var

Reference to a BCL variable

Return value
Pointer to an interface object, or NULL.
ExampleSet the interface pointer of variable x1 to vlink:
XPRBprob prob;
XPRBvar x1;
void *vlink;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
vlink = XPRBsetvarlink(x1);
Further information
This function returns the interface pointer of a variable to the indicated object. It may be used toestablish a connection between a variable in BCL and some other external program.
Related topics
XPRBsetvarlink, XPRBdefcbdelvar.

Fair Isaac Corporation Confidential and Proprietary Information

120

BCL C library functions

XPRBgetvarname
PurposeGet the name of a variable.
Synopsisconst char *XPRBgetvarname(XPRBvar var);
Argumentvar

BCL reference to a variable.

Return value
Name of the variable if function executed successfully, NULL otherwise.
ExampleThis example prints the retrieved variable name.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);printf("%s\n", XPRBgetvarname(x1));
Further information
This function returns the name of a variable. If the user has not defined a name the default namegenerated by BCL is returned.
Related topics
XPRBgetarrvarname, XPRBgetvartype, XPRBnewvar, XPRBsetvartype.

Fair Isaac Corporation Confidential and Proprietary Information

121

BCL C library functions

XPRBgetvarrng
PurposeGet ranging information for a variable.
Synopsisdouble XPRBgetvarrng(XPRBvar var, int rngtype);
Argumentsvar
rngtype

BCL reference to a variable.
The type of ranging information sought. This is one of:
XPRB_UPACT
upper activity (= the activity level [solution value] that would result
from a cost coefficient increase from the input cost to the upper
cost XPRB_UCOST—assuming a minimization problem—ignoring
the upper bound on this variable);
XPRB_LOACT
lower activity (= the activity level [solution value] that would result
from a cost coefficient decrease from the input cost to the lower
cost XPRB_LCOST—assuming a minimization problem—ignoring
the upper bound on this variable);
XPRB_UUP
upper unit cost (= the change in the objective function per unit ofchange in the activity up to the upper activity XPRB_UPACT);XPRB_UDN
lower unit cost (= the change in the objective function per unit ofchange in the activity down to the lower activity XPRB_LOACT)XPRB_UCOST
upper cost;
XPRB_LCOST
lower cost.

Return value
Ranging information of the required type.
ExampleThis example retrieves the upper cost value for a variable.
XPRBprob expl2;
XPRBvar x1;
double ucval;
expl2 = XPRBnewprob("example2");x1 = XPRBnewvar(expl2, XPRB_UI, "abc3", 1, 100);...
XPRBlpoptimize("expl2, "");
ucval = XPRBgetvarrng(x1, XPRB_UCOST);
Further information
1. This method can only be used after solving an LP problem. Ranging information for MIP problems
can be obtained by fixing all discrete variables to their solution values (using XPRSfixglobals)
and re-solving the resulting LP problem.
2. For non-basic variables, the unit costs are always the (absolute) values of the reduced costs.
Related topics
XPRBnewvar, XPRBgetctrrng.

Fair Isaac Corporation Confidential and Proprietary Information

122

BCL C library functions

XPRBgetvartype
PurposeGet the type of a variable.
Synopsis
int XPRBgetvartype(XPRBvar var);
Argumentvar
Return value
XPRB_PL
XPRB_BVXPRB_UIXPRB_PI
XPRB_SC
XPRB_SI-1

BCL reference to a variable.
continuous;
binary;general integer;
partial integer;semi-continuous;semi-continuous integer;an error has occurred.

ExampleXPRBprob prob;
XPRBvar x1;
char vtype;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
vtype = XPRBgetvartype(x1);This returns the type of variable x1.
Further information
If the function exits successfully, the variable type is returned.
Related topics
XPRBnewvar, XPRBsetvartype.

Fair Isaac Corporation Confidential and Proprietary Information

123

BCL C library functions

XPRBgetversion
PurposeGet the version number of BCL.
Synopsisconst char *XPRBgetversion(void);
Return value
BCL version number if function executed successfully, NULL otherwise.
ExampleThe following obtains the BCL version number, displaying output similar to 1.1.0.
const char *version;
version = XPRBgetversion();printf("%s",version);
Further information
This function returns the version number of BCL. This information is required if the user isreporting a problem.
Related topics
XPRBgettime.

Fair Isaac Corporation Confidential and Proprietary Information

124

BCL C library functions

XPRBgetXPRSprob
PurposeReturns an XPRSprob problem reference for a problem defined in BCL and subsequently loaded
into the Xpress Optimizer.
Synopsis
XPRSprob XPRBgetXPRSprob(XPRBprob prob);
Argumentprob

The current BCL problem.

Return value
Reference to a problem in Xpress Optimizer if function executed successfully, NULL otherwise.
ExampleThe Xpress Optimizer problem reference needs to be retrieved to access control parameters andoptimizer problem attributes:
XPRBprob bcl_prob;
XPRSprob opt_prob;
bcl_prob = XPRBnewprob("MyProb");...
XPRBloadmat(bcl_prob);
opt_prob = XPRBgetXPRSprob(bcl_prob);
XPRSsetintcontrol(opt_prob, XPRS_PRESOLVE, 0);
Further information
The optimizer problem returned by this function may be different from the one loaded in BCL if
the solution algorithms have not been called (and the problem has not been loaded explicitly)
after the last modifications to the problem in BCL, or if any modifications have been carried out
directly on the problem in the optimizer.
Related topics
XPRBloadmat, XPRBnewprob, Chapter B.

Fair Isaac Corporation Confidential and Proprietary Information

125

BCL C library functions

XPRBinit
Purpose
Initialize BCL.
Synopsis
int XPRBinit(void);
Return value0132function executed successfully,
an error has occurred,
BCL has been set running in Student mode.

ExampleXPRBseterrctrl(0);if(XPRBinit())
printf("BCL has not been initialized correctly.
Please check your Xpress licenses.");This switches to user error handling and initializes BCL (or performs license test).
Further information
1. This function explicitly initializes BCL, that is it tests whether a license for running this software isavailable. It is possible to run BCL with a student license; this mode implies restrictions to theavailable functionality and to the accepted problem size.
2. With BCL C, the initialization is also performed by function XPRBnewprob so that it is not required
to call this explicit initialization, particularly for stand-alone model runs. This function may be
used if the embedding of BCL into some larger application requires a test of the license at an
earlier stage, before even creating any model.
3. In applications that create a large number of problems it is recommended to use the explicit
initialization—once only per process for highest efficiency.
4. Note that this function also initializes Xpress Optimizer, so that it is usually not necessary to call
XPRSinit separately (the latter is only required if one wishes to continue using the optimizer
after terminating BCL).
Related topics
XPRBfree, XPRBnewprob, XPRSinit (see Optimizer Reference Manual).

Fair Isaac Corporation Confidential and Proprietary Information

126

BCL C library functions

XPRBloadbasis
PurposeLoad a previously saved basis.
Synopsis
int XPRBloadbasis(XPRBbasis basis);Argument
basis

Reference to a previously saved basis.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code saves the current basis prior to some matrix changes, before subsequently
reloading the saved basis to solve the linear relaxation.
XPRBprob expl2;
XPRBbasis basis;...
expl2 = XPRBnewprob("example2");
XPRBlpoptimize(expl2, "");
basis = XPRBsavebasis(expl2);...
XPRBloadmat(expl2);
XPRBloadbasis(basis);
XPRBdelbasis(basis);
XPRBlpoptimize(expl2, "");
Further information
This function loads a basis for the current problem. The basis must have been saved using
function XPRBsavebasis. It is not possible to load a basis saved for any other problem than thecurrent one, even if the problems are similar. This function takes into account that the problem
may have been modified since the basis has been stored (addition of variables and constraints ishandled—deletion of constraints is not handled: instead of entirely deleting a constraint, change
its type to XPRB_N using XPRBsetctrtype if you wish to load the basis later on). For reading a basis
from a file, the Optimizer library function XPRSreadbasis may be used. Note that the problem has
to be loaded explicitly (function XPRBloadmat) before the basis is re-input with XPRBloadbasis.
Furthermore, if the reference to a basis is not used any more it should be deleted using function
XPRBdelbasis.
Related topics
XPRBdelbasis, XPRBsavebasis, XPRSreadbasis (see Optimizer Reference Manual), XPRSwritebasis(see Optimizer Reference Manual).

Fair Isaac Corporation Confidential and Proprietary Information

127

BCL C library functions

XPRBloadmat
PurposeLoad the problem into the Xpress Optimizer.
Synopsis
int XPRBloadmat(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleHere the matrix is generated for problem expl2.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBloadmat(expl2);
Further information
This function calls the Optimizer library functions XPRSloadlp, XPRSloadqp, XPRSloadglobal, or
XPRSloadqglobal to transform the current BCL problem definition into a matrix in the Xpress
Optimizer. Empty rows and columns are deleted before generating the matrix. Semi-continuous(integer) variables are preprocessed: if a lower bound value greater than 0 is given, then thevariable is treated like a continuous (resp. integer) variable. Variables that belong to the problem
but do not appear in the matrix receive negative column numbers. Usually, it is not necessary tocall this function explicitly because BCL automatically does this conversion whenever it isrequired. To force matrix reloading, a call to this function needs to be preceded by a call to
XPRBsync with the flag XPRB_XPRS_PROB.
Related topics
XPRBsync, XPRBgetXPRSprob, Appendix B.

Fair Isaac Corporation Confidential and Proprietary Information

128

BCL C library functions

XPRBloadmipsol
PurposeLoad an integer solution into BCL or the Optimizer.
Synopsis
int XPRBloadmipsol(XPRBprob prob, double *sol, int ncol, int ifopt);
Arguments
prob
sol
ncol
ifopt

Return value
0
1
2
3
-1
-2
-3

Reference to a problem.
Array of size ncol holding the solution values.
Number of variables (continuous+discrete) in the problem.
Whether to load the solution into the Optimizer:
0load into BCL only;
1
load solution into the Optimizer.
solution accepted,
solution rejected because it is infeasible,
solution rejected because it is cut off,solution rejected because the LP reoptimization was interrupted,
solution rejected because an error occurred,
the given solution array does not have the expected size,
error loading solution into BCL.

ExampleLoad a MIP solution for problem expl2 into BCL, but not into the Optimizer. We know that the
problem has 5 variables.
XPRBprob expl2;
double vals[] = {1.5, 1, 0, 4, 2.2};
expl2 = XPRBnewprob("example2");...
if (XPRBloadmipsol(expl2, vals, 5, 0)!=0)
printf("Loading the solution failed.\n");Further information
1. This function loads a MIP solution from an external source (e.g., the Xpress MIP Solution Pool)
into BCL or the Optimizer. The solution is given in the form of an array, indexed by the column
numbers of the decision variables. The size ncol of the array must correspond to the number ofcolumns in the matrix (generated by a call to XPRBloadmat or by starting an optimization run from
BCL). If the solution is loaded into BCL the values are accepted as is, if the solution is loaded into
the Optimizer (ifopt = 1), the Optimizer will check whether the solution is acceptable andrecalculates the values for the continuous variables in the solution. In the latter case the solution
is loaded into BCL only once it has been successfully loaded and validated by the Optimizer.
2. If the matrix loaded in the Optimizer does not correspond to the current state of the specified
problem definition, it is regenerated automatically before loading the solution.
Related topics
XPRBaddmipsol, XPRBgetcolnum, XPRBloadmat, XPRBgetobjval, XPRBgetsol.

Fair Isaac Corporation Confidential and Proprietary Information

129

BCL C library functions

XPRBlpoptimize
PurposeSolve as a continuous problem.
Synopsis
int XPRBlpoptimize(XPRBprob prob, char *alg);
Arguments
prob
alg

Reference to a problem.
Choice of the solution algorithm and options, as a string of flags. If no flag is specified,solve the problem using the default LP/QP algorithm; otherwise, if the argument
includes:"d" solve the problem using the dual simplex algorithm;"p" solve the problem using the primal simplex algorithm;"b" solve the problem using the Newton barrier algorithm;"n" use the network solver;"c" continue a previously interrupted optimization run;

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code uses the primal simplex algorithm to solve expl2 as a continuous problem.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "p");Further information
This function selects and starts the Xpress Optimizer LP/QP solution algorithm. The characters
indicating the algorithm choice may be combined where it makes sense, e.g. "pn. If the matrix
loaded in the Optimizer does not correspond to the current state of the specified problem
definition it is regenerated automatically prior to the start of the algorithm. Matrix reloading canalso be forced by calling XPRBsync before the optimization. The sense of the optimization(default: minimization) can be changed with function XPRBsetsense. Before solving a problem,the objective function must be selected with XPRBsetobj.
Related topics
XPRBgetsense, XPRBlpoptimize, XPRBsetobj, XPRBsetsense, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

130

BCL C library functions

XPRBmipoptimize
PurposeSolve as a discrete problem.
Synopsis
int XPRBmipoptimize(XPRBprob prob, char *alg);
Arguments
prob
alg

Reference to a problem.
Choice of the solution algorithm and options, as a string of flags. If no flag is specified,solve the problem using the default MIP/MIQP algorithm; otherwise, if the argument
includes:"d" solve the problem using the dual simplex algorithm;"p" solve the problem using the primal simplex algorithm;"b" solve the problem using the Newton barrier algorithm;"n" use the network solver (for the initial LP);"l" stop after solving the initial continuous relaxation (using MIP information inpresolve);"c" continue a previously interrupted optimization run;

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code uses the default algorithm to solve expl2 as a discrete problem.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBmipoptimize(expl2, "");
Further information
This function selects and starts the Xpress Optimizer MIP/MIQP solution algorithm. The characters
indicating the algorithm choice may be combined where it makes sense, e.g. "pn. If the matrix
loaded in the Optimizer does not correspond to the current state of the specified problem
definition it is regenerated automatically prior to the start of the algorithm. Matrix reloading canalso be forced by calling XPRBsync before the optimization. The sense of the optimization(default: minimization) can be changed with function XPRBsetsense. Before solving a problem,the objective function must be selected with XPRBsetobj. Note that if you use an incomplete
global search you should finish your program with a call to the Optimizer library function
XPRSpostsolve in order to remove all search tree information that has been stored.
Related topics
XPRBgetsense, XPRBlpoptimize, XPRBsetobj, XPRBsetsense, XPRBsync.

Fair Isaac Corporation Confidential and Proprietary Information

131

BCL C library functions

XPRBnewarrsum
PurposeCreate a sum constraint with individual coefficients.
Synopsis
XPRBctr XPRBnewarrsum(XPRBprob prob, const char *name,
XPRBarrvar av, double *cof, int qrtype, double rhs);
Arguments
prob
name
av
cof
qrtyperhs

Reference to a problem.
The constraint name (of unlimited length). May be NULL if not required.
Reference to an array of variables.
Array of constant coefficients for all elements of av. It must be at least the same size as
av.
Type of the constraint, which must be one of:
XPRB_L‘less than or equal to’ constraint;
XPRB_G‘greater than or equal to’ constraint;
XPRB_Eequality constraint;
XPRB_N
non-binding constraint (objective function).
The right hand side value of the constraint.

Return value
Reference to the new constraint if function executed successfully, NULL otherwise.
ExampleThe following creates the constraint

P4

i=0 ci · ty1i ≥ 7. 0.

XPRBprob prob;
XPRBctr ctr4;
XPRBarrvar ty1;
double c[] = {2.5, 4.0, 7.2, 3.0, 1.8};...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr4 = XPRBnewarrsum(prob, "r4", ty1, c, XPRB_G, 7.0);
Further information
This function creates a linear constraint consisting of the sum over variables multiplied by thecoefficients indicated by array cof. This function replaces XPRBnewctr and XPRBaddterm. If theindicated name is already in use, BCL adds an index to it. If no constraint name is given, BCL
generates a default name starting with CTR. (The generation of unique names will only take place
if the names dictionary is enabled, see XPRBsetdictionarysize.)Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBdelctr, XPRBnewctr, XPRBnewprec, XPRBnewsum, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

132

BCL C library functions

XPRBnewarrvar
PurposeCreate a one-dimensional array of variables.
Synopsis
XPRBarrvar XPRBnewarrvar(XPRBprob prob, int nbvar, int type,
const char *name, double bdl, double bdu);
Arguments
prob
nbvar
type

name
bdl
bdu

Reference to a problem.
Size of the array of variables.
Type of the variables, which may be one of:
XPRB_PL
continuous;
XPRB_BV
binary;XPRB_UI
general integer;
XPRB_PI
partial integer;
XPRB_SCsemi-continuous;
XPRB_SI
semi-continuous integer.
The array name. May be NULL if not required.
Variable lower bound.
Variable upper bound.

Return value
Reference to the new array of variables if function executed successfully, NULL otherwise.
ExampleThe following defines an array of ten continuous variables between 0 and 500, with names
beginning arry1 followed by a counter.
XPRBprob prob;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 10, XPRB_PL, "arry1", 0, 500);
Further information
1. This function creates a single-indexed array of variables. Individual bounds on variables may bechanged afterwards using XPRBsetlb and XPRBsetub, and variable types by using XPRBsetvartype.
The function returns the BCL reference to the array of variables. If name is defined, BCL generates
names for the variables in the array by adding an index to the string. If no array name is given,
BCL generates a default name starting with AV. (The generation of unique names will only takeplace if the names dictionary is enabled, see XPRBsetdictionarysize.)
2. Either of the bounds XPRB_INFINITY or -XPRB_INFINITY for plus or minus infinity may be used forthe arguments bdu and bdl.
Related topics
XPRBdelarrvar, XPRBendarrvar, XPRBstartarrvar, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

133

BCL C library functions

XPRBnewctr
PurposeCreate a new constraint.
Synopsis
XPRBctr XPRBnewctr(XPRBprob prob, const char *name, int qrtype);
Arguments
prob
name
type

Reference to a problem.
The constraint name (of unlimited length). May be NULL if not required.
Type of the constraint, which must be one of
XPRB_L‘less than or equal to’ inequality;
XPRB_G‘greater than or equal to’ inequality;
XPRB_Eequality;
XPRB_Na non-binding row (objective function).

Return value
Reference to the new constraint if function executed successfully, NULL otherwise.
ExampleThe following creates a new equality constraint.
XPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
Further information
This function creates a new constraint and returns the reference to this constraint, i.e., theconstraint’s model name. It has to be called before XPRBaddterm orXPRBaddqterm is used to add
terms to the constraint. Range constraints can first be created with any type and then converted
using the function XPRBsetrange. If the indicated name is already in use, BCL adds an index to it.
If no constraint name is given, BCL generates a default name starting with CTR. (The generationof unique names will only take place if the names dictionary is enabled, see
XPRBsetdictionarysize.)
Related topics
XPRBaddterm, XPRBdelctr, XPRBdelterm, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

134

BCL C library functions

XPRBnewcut
PurposeCreate a new cut.
Synopsis
XPRBcut XPRBnewcut(XPRBprob prob, int qrtype, int mtype);
Arguments
prob
qrtypemtype

Reference to a problem.
Type of the cut:
XPRB_L≤ (inequality)
XPRB_G≥ (inequality)
XPRB_E= (equation)
Cut classification or identification number.

Return value
Reference to the new cut of type xbcut if function executed successfully, NULL otherwise.
ExampleThe example shows how to create a new equality cut.
XPRBcut cut1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
Further information
This function creates a new cut and returns the reference to this cut, i.e. the cut’s model name. It
has to be called before XPRBaddcutterm is used to add terms to the cut.
Related topics
XPRBaddcutterm, XPRBdelcut, XPRBaddcuts.

Fair Isaac Corporation Confidential and Proprietary Information

135

BCL C library functions

XPRBnewcutarrsum
PurposeP
Create a sum cut with individual coefficients ( i ci · xi ).
Synopsis
XPRBcut XPRBnewcutarrsum(XPRBprob prob, XPRBarrvar av, double *cof, char qrtype,
double rhs, int mtype);
Arguments
prob
av
cof
qrtyperhs
mtype

Reference to a problem.
Reference to an array of variables.
Array of constant coefficients for all elements of (at least size of av).
Type of the cut:
XPRB_L≤ (inequality)
XPRB_G≥ (inequality)
XPRB_E= (equation)
RHS value of the cut.
Cut classification or identification number.

Return value
Reference to the new cut if function executed successfully, NULL otherwise.
ExampleThe following creates the inequality constraint

P4

i=0 ci · ty1i ≥ 7.

XPRBcut cut4;
XPRBarrvar ty1;
double c[] = {2.5, 4.0, 7.2, 3.0, 1.8};
ty1 = XPRBnewarrvar(5, XPRB_PL, "arry1", 0, 500);
cut4 = XPRBnewcutarrsum(ty1, c, XPRB_G, 7.0, 18);
Further information
This function creates a cut consisting of the sum over variables multiplied by the coefficients
indicated by array cof. This function replaces XPRBnewcut and XPRBaddcutterm.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

136

BCL C library functions

XPRBnewcutprec
PurposeCreate a precedence cut (v1 + dur ≤ v2 ).
Synopsis
XPRBcut XPRBnewcutprec(XPRBprob prob, XPRBvar v1, double dur, XPRBvar v2, int mtype);
Arguments
prob
v1,v2
dur
mtype

Reference to a problem.
References to two variables.
Double or integer constant.
Cut classification or identification number.

Return value
Reference to the newly created cut if function executed successfully, NULL otherwise.
ExampleThe following creates the inequality constraint ty12 + 5. 4 ≤ ty14 .
XPRBcut cut5;
XPRBarrvar ty1;
ty1 = XPRBnewarrvar(5, XPRB_PL, "arry1", 0, 500);
cut5 = XPRBnewcutprec(ty1[2], 5.4, ty1[4], 5);
Further information
This function creates a so-called precedence constraint (where the variable plus constant is notlarger than a second variable). This function replaces XPRBnewcut and XPRBaddcutterm.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

137

BCL C library functions

XPRBnewcutsum
PurposeP
Create a sum cut ( i xi ).
Synopsis
XPRBcut XPRBnewcutsum(XPRBprob prob, XPRBarrvar tv, char qrtype, double rhs, int
mtype);
Arguments
prob
av
qrtyperhs
mtype

Reference to a problem.
Reference to an array of variables.
Type of the cut:
XPRB_L≤ (inequality)
XPRB_G≥ (inequality)
XPRB_E= (equation)
RHS value of the cut.
Cut classification or identification number.

Return value
Reference to the new cut if function executed successfully, NULL otherwise.
ExampleCreate the equality constraint

P4

i=0 ty1i = 9.

XPRBcut cut2;
XPRBarrvar ty1;
ty1 = XPRBnewarrvar(5, XPRB_PL, "arry1", 0, 500);
cut2 = XPRBnewcutsum(ty1, XPRB_E, 9, 3);
Further information
This function creates a simple sum constraint over all entries of an array of variables. It replaces
calls to XPRBnewcut and XPRBaddcutterm.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

138

BCL C library functions

XPRBnewidxset
PurposeCreate a new index set.
Synopsis
XPRBidxset XPRBnewidxset(XPRBprob prob, const char *name, int maxsize);
Argumentsprob
namemaxsize

Reference to a problem.
Name of the index set to be created. May be NULL if not required.
Maximum size of the index set.

Return value
Reference to the new index set if function executed successfully, NULL otherwise.
ExampleThe following defines an index set with space for 100 entries.
XPRBprob prob;
XPRBidxset iset;...
iset = XPRBnewidxset(prob, "Set", 100);
Further information
This function creates a new index set. Note that the indicated size maxsize corresponds to thespace allocated initially to the set, but it is increased dynamically if need be. If the indicated set
name is already in use, BCL adds an index to it. If no name is given, BCL generates a default namestarting with IDX. (The generation of unique names will only take place if the names dictionary isenabled, see XPRBsetdictionarysize.)
Related topics
XPRBaddidxel, XPRBgetidxel, XPRBgetidxsetname, XPRBgetidxsetsize, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

139

BCL C library functions

XPRBnewname
PurposeCompose a name string.
Synopsisconst char *XPRBnewname(const char *format, ...);
Arguments
format...

String indicating the printing format using standard C conventions (see thedocumentation of printf in a C manual for a complete list of format options). Simple
formating options are of the form %n where n may be, for instance, one ofcsingle character;dinteger;gdouble;sstring of characters.
items composing the name string according to the format specification in the format
string; separated by commas.

Return value
String of characters.
ExampleThis example finds the variable with name xab15.
XPRBprob prob;
char a[] = "ab";int i = 15;
XPRBvar x1;...
x1 = XPRBgetbyname(prob, XPRBnewname("x%s%d",a,i), XPRB_VAR);
Further information
1. This function simplifies the composition of names for BCL objects. It is intended to be used as aparameter of other functions (wherever name strings are required). Unlike the standard C string
functions, this function does not require any memory allocation by the user, and the string
returned must not be freed by the user.
2. Names created with this function are limited to 128 characters. However, there is no restriction
on the length of names for BCL objects in general.
Related topics
XPRBdelprob, XPRBgetprobname, XPRBnewprob.

Fair Isaac Corporation Confidential and Proprietary Information

140

BCL C library functions

XPRBnewprec
PurposeCreate a precedence constraint v1 + dur ≤ v2.
Synopsis
XPRBctr XPRBnewprec(XPRBprob prob, const char *name, XPRBvar v1,
double dur, XPRBvar v2);
Arguments
prob
name
v1
dur
v2

Reference to a problem.
The constraint name (of unlimited length). May be NULL if not required.
Reference to a variable.
Double or integer constant.
Reference to a variable.

Return value
Reference to the new constraint if function executed successfully, NULL otherwise.
ExampleThe following creates the inequality constraint ty12 + 5. 4 ≤ ty14 .
XPRBprob prob;
XPRBctr ctr5;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr5 = XPRBnewprec(prob, "r5", ty1[2], 5.4, ty1[4]);Further information
This function creates a so-called precedence constraint (where the first variable plus constant is
not larger than a second variable). This function replaces XPRBnewctr and XPRBaddterm. If theindicated name is already in use, BCL adds an index to it. If no constraint name is given, BCL
generates a default name starting with CTR. (The generation of unique names will only take place
if the names dictionary is enabled, see XPRBsetdictionarysize.)Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBnewarrsum, XPRBnewsum, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

141

BCL C library functions

XPRBnewprob
Purpose
Initialize a new problem.
Synopsis
XPRBprob XPRBnewprob(const char *probname);
Argument
probname

The problem name. May be NULL if not required.

Return value
Reference to a problem definition in BCL if function executed successfully, NULL otherwise.
ExampleThis example begins the definition of a new problem with the name example2.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");
Further information
1. This function needs to be called to create and initialize a new problem. This function initializes
BCL and also Xpress Optimizer; it is not necessary to call XPRSinit from the user’s program. If theinitialization does not find a valid license, BCL does not initialize. It is possible to run BCL with astudent license; this mode implies restrictions to the available functionality and to the accepted
problem size.
2. The above remarks on initialization of BCL through this function apply when using BCL in C,
initialization for other interfaces may differ—please refer to the specific interface documentation.
3. The name given to a problem determines the name and the location of the working files of
Xpress Optimizer. At the creation of a problem any existing working files of the same name aredeleted. When solving several instances of a problem simultaneously the user must make sure toassign a different name to every instance. If no problem name is indicated, BCL creates a uniquename including the full path to the temporary directory (Xpress Optimizer creates its working
files in the temporary directory).
Related topics
XPRBdelprob, XPRBgetprobname, XPRBinit.

Fair Isaac Corporation Confidential and Proprietary Information

142

BCL C library functions

XPRBnewsol
PurposeCreate a solution.
Synopsis
XPRBsol XPRBnewsol(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Reference to the new solution if function executed successfully, NULL otherwise.
ExampleThe following creates a solution sol1.
XPRBprob prob;
XPRBsol sol1;...
sol1 = XPRBnewsol(prob);
Further information
This function creates an XPRBsol solution. It returns the address of the solution that is taken as aparameter in the functions for adding variables, such as XPRBsetsolvar, deleting variables
XPRBdelsolvar or the entire solution XPRBdelsol. Note that XPRBsol solutions represent
user-defined solutions to be passed to the Optimizer, not solutions retrieved from the Optimizer.
Related topics
XPRBdelsol, XPRBdelsolvar, XPRBgetsolsize, XPRBgetsolvar, XPRBprintsol, XPRBsetsolarrvar,
XPRBsetsolvar.

Fair Isaac Corporation Confidential and Proprietary Information

143

BCL C library functions

XPRBnewsos
PurposeCreate a SOS.
Synopsis
XPRBsos XPRBnewsos(XPRBprob prob, const char *name, int type);
Arguments
prob
name
type

Reference to a problem.
The name of the set.
The set type, which must be one of:
XPRB_S1
Special Ordered Set of type 1;
XPRB_S2Special Ordered Set of type 2.

Return value
Reference to the new SOS if function executed successfully, NULL otherwise.
ExampleThe following creates an SOS of type 1, called sos1.
XPRBprob prob;
XPRBsos set1;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
Further information
This function creates a Special Ordered Set (SOS) of type 1 or 2 (abbreviated SOS1 and SOS2). It
returns the address of the set that is taken as a parameter in the functions for adding set
members, such as XPRBaddsosel, deleting single elements XPRBdelsosel or the entire set
XPRBdelsos. If the indicated name is already in use, BCL adds an index to it. If no name is given
for the set, BCL generates a default name starting with SOS. (The generation of unique names will
only take place if the names dictionary is enabled, see XPRBsetdictionarysize.)
Related topics
XPRBdelsos, XPRBgetsosname, XPRBgetsostype, XPRBnewsosrc, XPRBnewsosw,
XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

144

BCL C library functions

XPRBnewsosrc
PurposeCreate a SOS, using a reference constraint.
Synopsis
XPRBsos XPRBnewsosrc(XPRBprob prob, const char *name, int type,
XPRBarrvar av, XPRBctr ctr);
Arguments
prob
name
type

av
ctr

Reference to a problem.
Name of the set.
The set type, which must be one of:
XPRB_S1
Special Ordered Set of type 1;
XPRB_S2Special Ordered Set of type 2.
Array of variables. May be NULL if not required.
Reference to a constraint which has been previously defined. May be NULL of not
required.

Return value
Reference to the new SOS if function executed successfully, NULL otherwise.
ExampleThe following creates an SOS of type 2 with variables from the array ty1, and their coefficients inthe constraint ctr4.
XPRBprob prob;
XPRBsos set2;
XPRBctr ctr4;
XPRBarrvar ty1;
double c[] = {2.5, 4.0, 7.2, 3.0, 1.8};...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr4 = XPRBnewarrsum(prob, "r4", ty1, c, XPRB_G, 7.0);
set2 = XPRBnewsosrc(prob, "sos2", XPRB_S2, ty1, ctr4);
Further information
This function can be used instead of a stepwise SOS definition if the variables are available in theform of a single array and the model contains a constraint with nonzero coefficients for all
variables which can serve as a reference constraint. If no reference constraint is indicated allweights are initialized to 1. If the indicated name is already in use, BCL adds an index to it. If noname is given for the set, BCL generates a default name starting with SOS. (The generation ofunique names will only take place if the names dictionary is enabled, see
XPRBsetdictionarysize.)Note:

all members that are added to a SOS must belong to the same problem as the SOS itself.

Related topics
XPRBdelsos, XPRBgetsosname, XPRBgetsostype, XPRBnewsos, XPRBnewsosw, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

145

BCL C library functions

XPRBnewsosw
PurposeCreate a SOS, using weights.
Synopsis
XPRBsos XPRBnewsosw(XPRBprob prob, const char *name, int type,
XPRBarrvar av, double *weight);
Arguments
prob
name
type

av
weightReference to a problem.
The set name.
The set type, which must be one of:
XPRB_S1
Special Ordered Set of type 1;
XPRB_S2Special Ordered Set of type 2.
An array of variables.
An array of weights. May be NULL if not required.

Return value
Reference to the new SOS if function executed successfully, NULL otherwise.
ExampleThe following creates an SOS of type 1, with the variables in array ty1 and weights, cr.
XPRBprob prob;
XPRBsos set1;
XPRBarrvar ty1;
double cr[] = {2.0, 13.0, 15.0, 6.0, 8.5};...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
set1 = XPRBnewsosw(prob, "sos1", XPRB_S1, ty1, cr);Further information
This function can be used instead of a stepwise SOS definition using functions XPRBnewsos and
XPRBaddsosarrel, that is if the variables and their weights are available in the form of two arrays.
If no weights are defined, the reference values of the variables are set to 1. If the indicated nameis already in use, BCL adds an index to it. If no name is given for the set, BCL generates a default
name starting with SOS. (The generation of unique names will only take place if the names
dictionary is enabled, see XPRBsetdictionarysize.)Note:

all members that are added to a SOS must belong to the same problem as the SOS itself.

Related topics
XPRBdelsos, XPRBgetsosname, XPRBnewsos, XPRBnewsosrc, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

146

BCL C library functions

XPRBnewsum
PurposeCreate a sum constraint.
Synopsis
XPRBctr XPRBnewsum(XPRBprob prob, const char *name, XPRBarrvar av,
int type, double rhs);
Arguments
prob
name
av
type

rhs

Reference to a problem.
The constraint name (of unlimited length). May be NULL if not required.
Reference to an array of variables.
Type of the constraint, which must be one of:
XPRB_L‘less than or equal to’ constraint;
XPRB_G’greater than or equal to’ constraint;
XPRB_Eequality;
XPRB_Na non-binding row (objective function).
Right hand side value of the constraint.

Return value
Reference to the new constraint if function executed successfully, NULL otherwise.
ExampleThe following creates a new constraint, ctr2, given by

P4

i=0 ty1i = 9.

XPRBprob prob;
XPRBctr ctr2;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(prob, "r2", ty1, XPRB_E, 9);
Further information
This function creates a simple sum constraint over all entries of an array of variables. It replaces
calls to XPRBnewctr and XPRBaddterm. If the indicated name is already in use, BCL adds an index toit. If no constraint name is given, BCL generates a default name starting with CTR. (Thegeneration of unique names will only take place if the names dictionary is enabled, see
XPRBsetdictionarysize.)Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBnewarrsum, XPRBnewctr, XPRBnewprec, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

147

BCL C library functions

XPRBnewvar
Purpose
Declare a single variable.
Synopsis
XPRBvar XPRBnewvar(XPRBprob prob, int type, const char *name, double bdl, double bdu);
Arguments
prob
type

name
bdl
bdu

Reference to a problem.
The variable type, which may be one of:
XPRB_PL
continuous;
XPRB_BV
binary;XPRB_UI
general integer;
XPRB_PI
partial integer;
XPRB_SCsemi-continuous;
XPRB_SI
semi-continuous integer.
The variable name (of unlimited length). May be NULL if not required.
The variable’s lower bound.
The variable’s upper bound.

Return value
Reference to the new variable if function executed successfully, NULL otherwise.
ExampleXPRBprob prob;
XPRBvar x1, x2;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);x2 = XPRBnewvar(prob, XPRB_SC, "klm2", 0, 20);
This defines an integer variable x1, taking values between 1 and 100, with the name abc3, and asemi-continuous variable x2, taking the value 0 or values between 1 and 20, with the name klm2.
Further information
1. The creation of a variable in BCL involves not only its name but also its type and bounds (which
may be infinite, defined by the corresponding Xpress constants). The function returns the BCL
reference to the variable (i.e. a model variable). If the indicated name is already in use, BCL adds
an index to it. If no variable name is given, BCL generates a default name starting with VAR. (Thegeneration of unique names will only take place if the names dictionary is enabled, see
XPRBsetdictionarysize.) If a partial integer, semi-continuous, or semi-continuous integer
variable is being created, the integer or semi-continuous limit (i.e. the lower bound of thecontinuous part for partial integer and semi-continuous, and of the semi-continuous integer partfor semi-continuous integer) is set to the maximum of 1 and bdl. This value can be subsequently
modified with the function XPRBsetlim.
2. The lower and upper bounds may take values of -XPRB_INFINITY and XPRB_INFINITY for minus
and plus infinity respectively.
Related topics
XPRBnewarrvar, XPRBsetvartype, XPRBstartarrvar, XPRBsetdictionarysize.

Fair Isaac Corporation Confidential and Proprietary Information

148

BCL C library functions

XPRBprintarrvar
PurposePrint out an array of variables.
Synopsis
int XPRBprintarrvar(XPRBarrvar av);
Argument
av

Reference to an array of variables.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
XPRBprintarrvar(ty1);
The above prints names and bounds for all variables in the array ty1.
Further information
This function prints out all variables in the array (names and bounds or solution values). It is notavailable in the student version.
Related topics
XPRBexportprob, XPRBprintctr, XPRBprintprob, XPRBprintvar.

Fair Isaac Corporation Confidential and Proprietary Information

149

BCL C library functions

XPRBprintctr
PurposePrint out a constraint.
Synopsis
int XPRBprintctr(XPRBctr ctr);
Argument
ctr

Reference to a constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following prints out the constraint ctr2.
XPRBprob prob;
XPRBctr ctr2;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(prob, "r2", ty1, XPRB_E, 9);
XPRBprintctr(ctr2);
Further information
This function prints out a constraint in LP format. It is not available in the student version.
Related topics
XPRBexportprob, XPRBprintprob, XPRBprintarrvar, XPRBprintvar.

Fair Isaac Corporation Confidential and Proprietary Information

150

BCL C library functions

XPRBprintcut
PurposePrint out a cut.
Synopsis
int XPRBprintcut(XPRBcut cut);
Argument
cut

Reference to a cut.

Return value
0 if function executed successfully, 1 otherwise.
ExamplePrint out the cut cut2.
XPRBcut cut2;
XPRBarrvar ty1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");ty1 = XPRBnewarrvar(epl1, 5, XPRB_PL, "arry1", 0, 500);
cut2 = XPRBnewcutsum(expl1, ty1, XPRB_E, 9, 3);
XPRBprintcut(cut2);
Further information
This function prints out a cut in LP-format. It is not available in the Student Edition.
Related topics
XPRBnewcut.

Fair Isaac Corporation Confidential and Proprietary Information

151

BCL C library functions

XPRBprintf
PurposePrint text and other program output.
Synopsis
int XPRBprintf(XPRBprob prob, const *format, ...);
Arguments
prob
format...

Reference to a problem.
String indicating the format of the text to be output. Format parameters are identicalto those of the C function printf.
Items to be printed according to the format specification in the format string, separated
by commas.

Return value
Number of characters printed, or -1 if output truncated.
ExampleThe following code outputs the string "New variable: abc3", followed by"A real number: 1.3, an integer: 5" on the next line.
XPRBprob prob;
XPRBvar x1;
double a=1.3;
int i=5;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);
XPRBprintf(prob, "New variable: %s\n", XPRBgetvarname(x1));
XPRBprintf(prob, "A real number: %g, an integer: %d", a, i);
Further information
This function prints out text, data etc. from the user’s program. It behaves like the C function
printf with the additional feature that whenever the printing callback XPRBdefcbmsg is defined,
this callback is executed instead of printing to the standard output channel.
Related topics
XPRBprintprob, XPRBreadlinecb.

Fair Isaac Corporation Confidential and Proprietary Information

152

BCL C library functions

XPRBprintidxset
PurposePrint out an index set.
Synopsis
int XPRBprintidxset(XPRBidxset idx);
Argument
idx

Reference to an index set.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBidxset iset;...
iset = XPRBnewidxset(prob, "Set", 100);
XPRBprintidxset(iset);
The above prints out the index set iset.
Further information
This function prints out an index set. It is not available in the student version.
Related topics
XPRBprintctr, XPRBprintf, XPRBprintsos, XPRBprintvar.

Fair Isaac Corporation Confidential and Proprietary Information

153

BCL C library functions

XPRBprintobj
PurposePrint out the current objective function of a problem.
Synopsis
int XPRBprintobj(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following prints out the objective function defined for problem expl2.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBprintobj(expl2);
Further information
This function prints out the objective function currently defined for the given problem. Thisfunction is not available in the student version.
Related topics
XPRBsetobj.

Fair Isaac Corporation Confidential and Proprietary Information

154

BCL C library functions

XPRBprintprob
PurposePrint out the specified problem.
Synopsis
int XPRBprintprob(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following prints out the current problem definition.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBprintprob(expl2);
Further information
This function prints out the complete problem definition currently held in BCL, that means, thelist of constraints, any Special Ordered Sets that have been defined, and the objective function.
This function is not available in the student version.
Related topics
XPRBexportprob, XPRBprintf.

Fair Isaac Corporation Confidential and Proprietary Information

155

BCL C library functions

XPRBprintsol
PurposePrint out a solution.
Synopsis
int XPRBprintsol(XPRBsol sol);
Argument
sol

Reference to a solution.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBsol sol1;...
sol1 = XPRBnewsol(prob);...
XPRBprintsol(sol1);
This prints out the solution sol1.
Further information
This function prints out an XPRBsol solution (note that XPRBsol solutions represent user-definedsolutions to be passed to the Optimizer, not solutions coming from the Optimizer). A solution isprinted as a sequence like "varname = value, ... ". If the solution doesn’t contain any variable,
only an empty line is printed. This function is not available in the student version.
Related topics
XPRBnewsol, XPRBprintctr, XPRBprintidxset, XPRBprintprob, XPRBprintvar.

Fair Isaac Corporation Confidential and Proprietary Information

156

BCL C library functions

XPRBprintsos
PurposePrint out a Special Ordered Set.
Synopsis
int XPRBprintsos(XPRBsos sos);Argument
sos

Reference to a Special Ordered Set.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBsos set1;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBprintsos(set1);
This prints out the SOS set1.
Further information
This function prints out a Special Ordered Set. It is not available in the student version.
Related topics
XPRBprintctr, XPRBprintidxset, XPRBprintprob, XPRBprintvar.

Fair Isaac Corporation Confidential and Proprietary Information

157

BCL C library functions

XPRBprintvar
PurposePrint out a variable.
Synopsis
int XPRBprintvar(XPRBvar var);
Argumentvar

BCL reference for a variable.

Return value
Number of characters printed.
ExampleThe following code outputs abc3[1.000,100.000], followed by abc4[0.000,5.000,50.000].
XPRBprob prob;
XPRBvar x1, x3;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);
XPRBprintvar(x1);x3 = XPRBnewvar(prob, XPRB_SC, "abc4", 0, 50);
XPRBsetlim(x3, 5);
XPRBprintvar(x3);
Further information
This function prints out a variable: name and bounds for continuous, binary and integer
variables; name, bounds and integer limit or lower semi-continuous limit for partial integer,semi-continuous, and semi-continuous integer variables; or, where a solution has been computed,name and solution value.
Related topics
XPRBprintctr, XPRBprintidxset, XPRBprintprob, XPRBprintsos.

Fair Isaac Corporation Confidential and Proprietary Information

158

BCL C library functions

XPRBreadarrlinecb
PurposeRead a line of an array from a data file.
Synopsis
int XPRBreadarrlinecb(char *(*fgs)(char *,int,void *), void *file,
int length, const char *format, void *arrc, int size);
Arguments
fgs
file
lengthformatarrc
size

The system’s fgets function (defined by XPRB_FGETS).
Pointer to a data file.
Maximum length of any text string to be read.
String indicating the format of the data file to be read, consisting of one of the listed
values followed by a separator sign:t[num ] text up to next separator sign or space (blank/tabulator/line break),optionally followed by the maximum string length to be read;s[num ] text marked by single quotes (’ ’), optionally followed by the maximum
string length to be read;S[num ] text marked by double quotes (" "), optionally followed by the maximum
string length to be read;T[num ] text, as for t, s, or S, depending on the first character read, optionallyfollowed by the maximum string length to be read;i
integer value;greal (float) value.
Array of size at least size that receives the data that are read.
Maximum number of data items to be read.

Return value
Number of data items read.
Exampledouble vlist[10];FILE *datafile;...
datafile=fopen("filename", "r");XPRBreadlinecb(XPRB_FGETS, datafile, 120, "g ", vlist, 6);
fclose(datafile);
This opens a data file and reads a line of six double values separated by spaces, before closing the
file.
Further information
This function reads tables from data files in a format compatible with the diskdata command of
mp-model and Mosel. Data lines in the input file may be continued over several lines by using theline continuation sign &. The input file may also contain comments (preceded by !) and empty
lines, both of which are skipped over. The data file is accessed with standard C functions (fopen,
fclose). The function reads up to size data items of the type indicated by the format parameter.
All string types in the format may (optionally) be followed by the maximum string length to beread. Otherwise the maximum length is assumed to be length. The type of separator signs (e.g. ,; :) used in the data file needs to be given after the format option(s). Array arrc is an array ofthe same type as the data to be read (int *, char *, or double *) and of size at least size. Withfunction XPRBsetdecsign the decimal sign used in the data input may be changed, for instance to
use a decimal comma.

Fair Isaac Corporation Confidential and Proprietary Information

159

BCL C library functions

Related topics
XPRBreadlinecb, XPRBsetdecsign.

Fair Isaac Corporation Confidential and Proprietary Information

160

BCL C library functions

XPRBreadbinsol
PurposeRead a solution from a binary solution, loading it into the Optimizer.
Synopsis
int XPRBreadbinsol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If omitted, the extension .sol will be appended.
Flags to control solution import. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSreadbinsol in the ‘Xpress Optimizer Reference
Manual’ for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example reads a solution from file example2.sol.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBreadbinsol(expl2, "", "");
Related topics
XPRBreadslxsol, XPRBwritebinsol.

Fair Isaac Corporation Confidential and Proprietary Information

161

BCL C library functions

XPRBreadlinecb
PurposeRead a fixed-format line from a data file.
Synopsis
int XPRBreadlinecb(char *(*fgs)(char *,int,void *), void *file,
int length, const char *format, ...);
Arguments
fgs
file
lengthformat...

The system’s fgets function (defined by XPRB_FGETS).
Pointer to a data file.
Maximum length of any text string to be read.
String indicating the format of the data line to be read, which may be one of:t[num ] text up to next separator sign or space (blank / tab / line break), optionallyfollowed by the maximum string length to be read;s[num ] text marked by single quotes, ’ ’, optionally followed by the maximum
string length to be read;S[num ] text marked by double quotes, " ", optionally followed by the maximum
string length to be read;T[num ] text as for t, s, or S, depending on the first character read, optionallyfollowed by the maximum string length to be read;i
integer value;greal (float) value.
The number of format parameters is arbitrary.
Addresses of items that are to be read, separated by commas.

Return value
Number of data items read.
ExampleThe following opens a data file for reading, reads a line with text and a double value, separated
by a semi-colon, and then reads a line with two integers and a string of up to ten charactersmarked by single quotes, all separated by blanks, before finally closing the file.
double value;
FILE *datafile;char name[100];
int i[2];...
datafile=fopen("filename", "r");XPRBreadlinecb(XPRB_FGETS, datafile, 99, "T;g", name, &value);
XPRBreadlinecb(XPRB_FGETS, datafile, 50, "i i s[10]", &i[0],&i[1], name);
fclose(datafile);
Further information
This function reads input data files in a format compatible with the diskdata command of
mp-model and Mosel. Data lines in the input file may be continued over several lines by using theline continuation sign &. The input file may also contain comments (preceded by !) and empty
lines, both of which are skipped over. The data file is accessed with standard C functions (fopen,
fclose). The format string gives the type of data item to be read. Each string type may(optionally) be followed by the maximum length to be read. Otherwise, the maximum length isassumed to be length. The type of separator signs (e.g. , ; :) used in the data file needs to be
indicated between each pair of format options. As with the C functions printf or scanf, theformat string is followed by the addresses where the data are stored. With function

Fair Isaac Corporation Confidential and Proprietary Information

162

BCL C library functions

XPRBsetdecsign the decimal sign used in the data input may be changed, for instance to use a
decimal comma.
Related topics
XPRBreadarrlinecb, XPRBsetdecsign.

Fair Isaac Corporation Confidential and Proprietary Information

163

BCL C library functions

XPRBreadslxsol
PurposeRead a solution from an ASCII solution file (.slx), loading it into the Optimizer.
Synopsis
int XPRBreadslxsol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If omitted, the extension .slx will be appended.
Flags to control solution import. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSreadslxsol in the ‘Xpress Optimizer Reference
Manual’ for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example reads a solution from file example2.slx.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBreadslxsol(expl2, "", "");
Related topics
XPRBreadbinsol, XPRBwriteslxsol.

Fair Isaac Corporation Confidential and Proprietary Information

164

BCL C library functions

XPRBresetprob
Purpose
Release system resources used for storing solution information.
Synopsis
int XPRBresetprob(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following resets and frees resources used by BCL and Xpress Optimizer for storing solution
information:
XPRBprob expl2;
expl2 = XPRBnewprob(NULL):...
XPRBlpoptimize(expl2, "");...
XPRBresetprob(expl2);
Further information
This function deletes any solution information stored in BCL; it also deletes the corresponding
Xpress Optimizer problem and removes any auxiliary files that may have been created by
optimization runs. It also resets the Optimizer control parameters for spare matrix elements(EXTRACOLS, EXTRAROWS, and EXTRAELEMS) to their default values. The BCL problem definition itself
remains. This function may be used to free up memory if the solution information is not required
any longer but the problem definition is to be kept for later (re)use. To completely delete a
problem the function XPRBdelprob needs to be used.
Related topics
XPRBdelprob, XPRBfinish.

Fair Isaac Corporation Confidential and Proprietary Information

165

BCL C library functions

XPRBsavebasis
PurposeSave the current basis.
Synopsis
XPRBbasis XPRBsavebasis(XPRBprob prob);
Argument
prob

Reference to a problem.

Return value
Reference to the saved basis.
ExampleXPRBprob expl2;
XPRBbasis basis;
expl2 = XPRBnewprob("example2");...
XPRBlpoptimize(expl2, "");
basis = XPRBsavebasis(expl2);This saves the current basis.
Further information
This function saves the current basis of a problem. The basis may be reinput using function
XPRBloadbasis. These two functions serve for storing bases in memory; for writing a basis to afile, the Optimizer library function XPRSwritebasis may be used. Note that there is no need toallocate space for the basis, but after its use, the basis should be deleted using function
XPRBdelbasis. You may have to switch linear presolve and integer preprocessing off (Optimizer
library controls PRESOLVE and MIPPRESOLVE) in order for the saving and reloading of bases to work
correctly.
Related topics
XPRBdelbasis, XPRBloadbasis, XPRSreadbasis (see Optimizer Reference Manual),
XPRSwritebasis (see Optimizer Reference Manual).

Fair Isaac Corporation Confidential and Proprietary Information

166

BCL C library functions

XPRBsetarrvarel
PurposeAdd an entry to a variable array in a given position.
Synopsis
int XPRBsetarrvarel(XPRBarrvar av, int ndx, XPRBvar var);
Arguments
av
ndx
var

BCL reference to an array.
Index within the array.
Variable to be added to the array.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBarrvar av2;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
av2 = XPRBstartarrvar(prob, 5, "arr2");
XPRBsetarrvarel(av2, 3, x1);
This inserts variable x1 at the fourth position of the array av2 (which is numbered from 0).
Further information
This function puts a variable in specified position within the array. If there is already a variable atthis position it is overwritten.
Note:

all variables that are added to an array of variables must belong to the same problem as
the array itself.

Related topics
XPRBapparrvarel, XPRBdelarrvar, XPRBendarrvar, XPRBnewarrvar, XPRBstartarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

167

BCL C library functions

XPRBsetcolorderPurposeSet a column ordering criterion for matrix generation.
Synopsis
int XPRBsetcolorder(XPRBprob prob, int num);
Arguments
prob
num

Reference to a problem.
The ordering flag, which must be one of:0
default ordering;1
alphabetical order.

Return value
0 if function executed successfully, 1 otherwise.
ExampleSet a fixed ordering for a single problem:
XPRBprob expl2;
expl2 = XPRBnewprob("example2");
XPRBsetcolorder(expl2, 1);
Further information
1. BCL runs reproduce always the same matrix for a problem. This function allows the user to choosea different ordering criterion than the default one. Note that this function only changes the orderof columns in what is sent to Xpress Optimizer, you do not see any effect when exporting thematrix with BCL. However you can control the effect by exporting the matrix from the Optimizer.
2. This function can be used before any problem has been created (with first argument NULL). In thiscase the setting applies to all problems that are created subsequently.
Related topics
XPRBloadmat, XPRBnewprob.

Fair Isaac Corporation Confidential and Proprietary Information

168

BCL C library functions

XPRBsetctrtype
PurposeSet the constraint type.
Synopsis
int XPRBsetctrtype(XPRBctr ctr, int qrtype);
Arguments
ctr
qrtypeReference to a previously created constraint.
The constraint type, which must be one of:
XPRB_L’less than or equal to’ constraint;
XPRB_G’greater than or equal to’ constraint;
XPRB_Ean equality;
XPRB_Na non-binding row (objective function).

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBsetctrtype(ctr1, XPRB_L);
This changes ctr1 to a ‘less than or equal to’ constraint.
Further information
This function changes the type of a previously defined constraint to inequality, equation or
non-binding. Function XPRBsetrange has to be used for changing the constraint to a ranged
constraint. If a ranged constraint is changed back to some other type with this function, its upperbound becomes the right hand side value.
Related topics
XPRBgetctrtype, XPRBnewctr, XPRBsetrange, XPRBsetterm.

Fair Isaac Corporation Confidential and Proprietary Information

169

BCL C library functions

XPRBsetcutid
PurposeSet the classification or identification number of a cut.
Synopsis
int XPRBsetcutid(XPRBcut cut, int id);
Arguments
cut
id

Reference to a previously created cut.
Classification or identification number.

Return value
0 if function executed successfully, 1 otherwise.
ExampleSet the classification or identification number of the cut cut1 to 10.
XPRBcut cut1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBsetcutid(cut1, 10);Further information
This function changes the classification or identification number of a previously defined cut. Thischange does not have any effect on the cut definition in Xpress Optimizer if the cut has alreadybeen added to the matrix with the function XPRBaddcuts.
Related topics
XPRBnewcut, XPRBgetcutid, XPRBsetcuttype.

Fair Isaac Corporation Confidential and Proprietary Information

170

BCL C library functions

XPRBsetcutmodePurposeSet the cut mode.
Synopsis
int XPRBsetcutmode(XPRBprob prob, int mode);
Arguments
prob
mode

Reference to a problem.
Cut mode indicator:
0switch cut mode off
1
switch cut mode on

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe example shows how to enable the cut mode.
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");XPRBsetcutmode(expl1, 1);
Further information
This function switches the cut mode on or off. It changes the settings of certain Optimizer
controls. Switching the cut mode off resets these controls to their default values.
Related topics
XPRBaddcuts.

Fair Isaac Corporation Confidential and Proprietary Information

171

BCL C library functions

XPRBsetcutterm
PurposeSet a cut term.
Synopsis
int XPRBsetcutterm(XPRBcut cut, XPRBvar var, double coeff);
Arguments
cut
var
coeff

Reference to a previously created cut.
Reference to a variable, may be NULL.
Value of the coefficient of the variable var.

Return value
0 if function executed successfully, 1 otherwise.
ExampleSet the RHS of the cut cut1 to 7.0.
XPRBcut cut1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBsetcutterm(cut1, NULL, 7.0);
Further information
This function sets the coefficient of a variable to the value coeff. If var is set to NULL, the righthand side of the cut is set to coeff.
Note:

all terms that are added to a cut must belong to the same problem as the cut itself.

Related topics
XPRBnewcut, XPRBaddcutterm, XPRBdelcutterm.

Fair Isaac Corporation Confidential and Proprietary Information

172

BCL C library functions

XPRBsetcuttype
PurposeSet the type of a cut.
Synopsis
int XPRBsetcuttype(XPRBcut cut, int type);
Arguments
cut
type

Reference to a previously created cut.
Type of the cut:
XPRB_L≤ (inequality)
XPRB_G≥ (inequality)
XPRB_E= (equation)

Return value
0 if function executed successfully, 1 otherwise.
ExampleSet the type of cut1 to ‘ ≤ ’.
XPRBcut cut1;
XPRBprob expl1;
expl1 = XPRBnewprob("cutexample");cut1 = XPRBnewcut(expl1, XPRB_E, 1);
XPRBsetcuttype(cut1, XPRB_L);
Further information
This function changes the type of the given cut. This change does not have any effect on the cut
definition in Xpress Optimizer if the cut has already been added to the matrix with the function
XPRBaddcuts.
Related topics
XPRBnewcut, XPRBgetcuttype, XPRBgetcutid.

Fair Isaac Corporation Confidential and Proprietary Information

173

BCL C library functions

XPRBsetdecsign
Purpose
Select the decimal sign for data input.
Synopsis
int XPRBsetdecsign(char sign);
Argumentsign

The decimal sign to be used. This is typically ’.’ (default), or ’,’.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBsetdecsign(’,’);
This switches to using a comma as the decimal point.
Further information
By default, BCL uses the Anglo-American decimal point when reading and writing real numbers.
With this function the decimal sign accepted by the data input functions XPRBreadlinecb and
XPRBreadarrlinecb can be changed to a comma or any other non-numerical ASCII character. Notethat all output still contains the decimal point.
Related topics
XPRBreadarrlinecb, XPRBreadlinecb.

Fair Isaac Corporation Confidential and Proprietary Information

174

BCL C library functions

XPRBsetdelayed
PurposeSet the constraint type.
Synopsis
int XPRBsetdelayed(XPRBctr ctr, int dstat);Arguments
ctr
dstat

Reference to a previously created constraint.
The constraint type, which must be one of:0
ordinary constraint;
1
delayed constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following turns the constraint ctr1 into a delayed costraint.
XPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBsetdelayed(ctr1, 1);
Further information
1. This function changes the type of a previously defined constraint from ordinary constraint todelayed constraint and vice versa.
2. Delayed or ’lazy’ constraints must be satisfied for any integer solution, but will not be loaded into
the active set of constraints until required.
3. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator constraint’
are mutually exclusive. When changing from one of these types to another you must first resetthe correponding type to 0.
Related topics
XPRBgetdelayed, XPRBnewctr, XPRBsetincvars, XPRBsetindicator, XPRBsetmodcut.

Fair Isaac Corporation Confidential and Proprietary Information

175

BCL C library functions

XPRBsetdictionarysize
PurposeSet the size of a dictionary.
Synopsis
int XPRBsetdictionarysize(XPRBprob prob, int dict, int size)
Arguments
prob
dict

size

Reference to a problem.
Choice of the dictionary. Possible values:
XPRB_DICT_NAMES
names dictionary
XPRB_DICT_IDX
indices dictionary
Non-negative value, preferrably a prime number; 0 disables the dictionary (for names
dictionary only).

Return value
0 if function executed successfully, 1 otherwise.
ExampleSwitch off the names dictionary:
XPRBprob expl2;
expl2 = XPRBnewprob("example2");
XPRBsetdictsize(expl2, XPRB_DICT_NAMES, 0);
Further information
1. This function sets the size of the hash table of the names or indices dictionaries of the given
problem. It can only be called immediately after the creation of the corresponding problem.
2. The names dictionary serves for storing and accessing the names of all modeling objects(variables, arrays of variables, constraints, SOS, index sets). Once it has been disabled it cannot beenabled any more. All methods relative to the names cannot be used if this dictionary has been
disabled and BCL will not generate any unique names at the creation of model objects. If this
dictionary is enabled (default setting) BCL automatically resizes this dictionary to a suitable sizefor your problem. If nevertheless you wish to set the size by yourself we recommend to choose avalue close to the number of variables+constraints in your problem.
3. The indices dictionary serves for storing all index set elements. The indices dictionary cannot bedisabled, it is created automatically once an index set element is defined.
Related topics
XPRBnewprob, XPRBgetbyname.

Fair Isaac Corporation Confidential and Proprietary Information

176

BCL C library functions

XPRBseterrctrl
Purpose
Select behavior in case of an error.
Synopsis
int XPRBseterrctrl(int flag)
Argumentflag

Indicator value for error handling. May be one of:0
no error handling by BCL;
1
program exit at error (default).

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following switches to error handling by the user’s own program.
XPRBseterrctrl(0);Further information
1. This function controls whether BCL performs error handling. By default, the execution is stopped
whenever an error occurs. If the error handling by BCL is disabled, the user needs to perform thechecking for errors in his program by testing the return values of all functions or using thecallback function XPRBdefcberr. It may be preferable to disable the error handling by BCL if a BCL
program is embedded into some larger application or executed under Windows. Callback
function XPRBdefcberr can be defined to retrieve the error messages and implement user error
handling.
2. This function can be used before BCL has been initialized.
Related topics
XPRBdefcberr, XPRBgetversion.

Fair Isaac Corporation Confidential and Proprietary Information

177

BCL C library functions

XPRBsetincvars
PurposeSet the include vars constraint type.
Synopsis
int XPRBsetincvars(XPRBctr ctr, int ivstat);Arguments
ctr
ivstatReference to a previously created constraint.
The constraint type, which must be one of:0
normal constraint;
1
include vars special constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following turns the constraint ctr1 into an include vars special constraint.
XPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_N);
XPRBsetincvars(ctr1, 1);
Further information
1. This function changes the type of a previously defined constraint from ordinary constraint to an
include vars special constraint. Include vars constraints are used to force the loading of all
variables they contain into the Optimizer (even if they don’t appear in any other constraint). Only
constraints of type XPRB_N can be changed into include vars constraints; the constraints
themselves are not loaded into the Optimizer (as all constraints of type XPRB_N), just the variables
they contain are loaded. The coefficients of the variables are also ignored as long as they are
non-zero.
2. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator constraint’
are mutually exclusive. When changing from one of these types to another you must first resetthe correponding type to 0.
Related topics
XPRBgetincvarst, XPRBnewctr, XPRBsetdelayed, XPRBsetindicator, XPRBsetmodcut.

Fair Isaac Corporation Confidential and Proprietary Information

178

BCL C library functions

XPRBsetindicator
PurposeSet the indicator constraint type.
Synopsis
int XPRBsetindicator(XPRBctr ctr, int dir, XPRBvar b);
Arguments
ctr
dstat

b

Reference to a previously created inequality or range constraint.
The indicator type, which must be one of:-1 indicator constraint with condition b = 0;0
ordinary constraint;
1
indicator constraint with condition b = 1.
Reference to a previously created binary variable.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following turns the constraint ctr1 into the indicator constraint b = 1 ⇒ ctr1.
XPRBprob prob;
XPRBctr ctr1;
XPRBvar b;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
b = XPRBnewvar(prob, XPRB_BV, "b", 0, 1);
XPRBsetindicator(ctr1, 1, b);
Further information
1. This function changes the type of a previously defined constraint from ordinary constraint toindicator constraint and vice versa.
2. Indicator constraints are defined by associating a binary variable and an implication sense with alinear inequality or range constraint.
3. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator constraint’
are mutually exclusive. When changing from one of these types to another you must first resetthe correponding type to 0.
Related topics
XPRBgetindicator, XPRBgetindvar, XPRBnewctr, XPRBsetincvars, XPRBsetdelayed, XPRBsetmodcut.

Fair Isaac Corporation Confidential and Proprietary Information

179

BCL C library functions

XPRBsetlb
PurposeSet a lower bound.
Synopsis
int XPRBsetlb(XPRBvar var, double bdl);
Arguments
varbdl

BCL reference to a variable.
The variable’s new lower bound.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code changes the lower bound of x1 to 3.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);
XPRBsetlb(x1, 3.0);
Further information
This function sets the lower bound on a variable.
Related topics
XPRBfixvar, XPRBgetbounds, XPRBgetlim, XPRBsetlim, XPRBsetub.

Fair Isaac Corporation Confidential and Proprietary Information

180

BCL C library functions

XPRBsetlim
PurposeSet the integer limit for a partial integer, or the lower semi-continuous limit for asemi-continuous or semi-continuous integer variable.
Synopsis
int XPRBsetlim(XPRBvar var, double c);
Arguments
varc

BCL reference to a variable.
Value of the integer limit.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBvar x3;...
x3 = XPRBnewvar(prob, XPRB_SC, "abc4", 0, 50);
XPRBsetlim(x3, 5);This sets the limit for variable x3 to 5. The possible values for x3 are thus reduced from x3 = 0 or
1 <= x3 <= 50 at the creation of this variable to x3 = 0 or 5 <= x3 <= 50.
Further information
This function sets the integer limit (i.e. the lower bound of the continuous part) of a partial
integer variable or the semi-continuous limit of a semi-continuous or semi-continuous integer
variable to the given value.
Related topics
XPRBfixvar, XPRBgetbounds, XPRBgetlim, XPRBsetlb, XPRBsetub.

Fair Isaac Corporation Confidential and Proprietary Information

181

BCL C library functions

XPRBsetmodcut
PurposeSet the constraint type.
Synopsis
int XPRBsetmodcut(XPRBctr ctr, int mcstat);Arguments
ctr
mcstatReference to a previously created constraint.
The constraint type, which must be one of:0
constraint;
1
model cut.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following turns the constraint ctr1 into a model cut.
XPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBsetmodcut(ctr1, 1);
Further information
1. This function changes the type of a previously defined constraint from ordinary constraint tomodel cut and vice versa.
2. Model cuts must be ’true’ cuts, in the sense that they are redundant at the optimal MIP solution.
The Optimizer does not guarantee to add all violated model cuts, so they must not be required todefine the optimal MIP solution.
3. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator constraint’
are mutually exclusive. When changing from one of these types to another you must first resetthe correponding type to 0.
Related topics
XPRBgetmodcut, XPRBnewctr, XPRBsetincvars, XPRBsetdelayed, XPRBsetindicator.

Fair Isaac Corporation Confidential and Proprietary Information

182

BCL C library functions

XPRBsetmsglevel
PurposeSet the message print level.
Synopsis
int XPRBsetmsglevel(XPRBprob prob, int level);Arguments
prob
level

Reference to a problem.
The message level, i.e. the type of messages printed by BCL. This may be one of:0
no messages printed;
1
error messages only printed;
2
warnings and errors printed;
3
warnings, errors, and Optimizer log printed (default);
4
all messages printed.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following statement switches to printing error messages only.
XPRBprob prob;...
XPRBsetmsglevel(prob, 1);
Further information
1. BCL can produce different types of messages; status information, warnings and errors. Thisfunction controls which of these are output. For settings 1 or higher, the corresponding
Optimizer output is also displayed. In addition to this setting, the amount of Optimizer output
can be modified through several Optimizer printing control parameters (see the “Xpress
Optimizer Reference Manual”).
2. This function may be used before any problem has been created and even before BCL has been
initialized (with first argument NULL). In this case the setting applies to all problems that are
created subsequently.
Related topics
XPRBdefcbmsg.

Fair Isaac Corporation Confidential and Proprietary Information

183

BCL C library functions

XPRBsetobj
Purpose
Select the objective function.
Synopsis
int XPRBsetobj(XPRBprob prob, XPRBctr ctr);
Arguments
prob
ctr

Reference to a problem.
Reference to a previously defined constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr3;
XPRBarrvar tobj;...
tobj = XPRBnewarrvar(prob, 10, XPRB_PL, "tabo", 0, 800);
ctr3 = XPRBnewsum(prob, "r3", tobj, XPRB_N, 0);
XPRBsetobj(prob, ctr3);
This defines a non-binding constraint, ctr3, and then sets it as the objective function.
Further information
This functions sets the objective function by selecting a constraint the variable terms of whichbecome the objective function. This must be done before any optimization task is carried out.
Typically, the objective constraint will have the type XPRB_N (non-binding), but any other type of
constraint may be chosen too. In the latter case, the equation or inequality expressed by theconstraint also remains part of the problem.
Related topics
XPRBgetsense, XPRBsetsense.

Fair Isaac Corporation Confidential and Proprietary Information

184

BCL C library functions

XPRBsetprobname
PurposeSet the name of the specified problem.
Synopsis
int XPRBsetprobname(XPRBprob prob, const char *name);
Arguments
prob
name

Reference to a problem.
A string of up to 1024 characters containing the new problem name.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob expl2;
const char *pbname;expl2 = XPRBnewprob("example2");
XPRBsetprobname(expl2, "example_two");pbname = XPRBgetprobname(expl2);
printf("%s", pbname);
This creates a new problem, than changes its name and prints the new name example_two.
Related topics
XPRBdelprob, XPRBgetprobname, XPRBnewname, XPRBnewprob.

Fair Isaac Corporation Confidential and Proprietary Information

185

BCL C library functions

XPRBsetqterm
PurposeSet a quadratic constraint term.
Synopsis
int XPRBsetqterm(XPRBctr ctr, XPRBvar var1, XPRBvar var2,
double coeff);
Arguments
ctr
var1
var2
coeff

Reference to a previously defined constraint.
Reference to a variable.
Reference to a variable (not necessarily different from first variable).
Value to be added to the coefficient of the term var1 * var2.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBvar x2;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_L);
x2 = XPRBnewvar(prob, XPRB_PL, "abc1", 0, XPRB_INFINITY);XPRBaddqterm(ctr1, x2, x2, 1);
XPRBsetqterm(ctr1, x2, x2, 5.2);
This sets the coefficient of the term x2*x2 to 5.2.
Further information
This function sets the coefficient of a quadratic term in a constraint to the value coeff.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBaddqterm, XPRBdelqterm.

Fair Isaac Corporation Confidential and Proprietary Information

186

BCL C library functions

XPRBsetrange
PurposeDefine a range constraint.
Synopsis
int XPRBsetrange(XPRBctr ctr, double bdl, double bdu);
Arguments
ctr
bdl
bdu

Reference to the constraint.
Lower bound on the range constraint.
Upper bound on the range constraint.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following transforms the equality constraint ctr2 into the ranged constraint 4.0 <=sum(i=0:4) ty1[i] <= 15.5.
XPRBprob prob;
XPRBctr ctr2;
XPRBarrvar ty1;...
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);
ctr2 = XPRBnewsum(prob, "r2", ty1, XPRB_E, 9);
XPRBsetrange(ctr2, 4.0, 15.5);
Further information
This function changes the type of a previously defined constraint to a range constraint within thebounds specified by bdl and bdu. The constraint type and right hand side value of the constraint
are replaced by the type XPRB_R (range) and the two bounds.
Related topics
XPRBgetctrtype, XPRBgetrange, XPRBsetctrtype.

Fair Isaac Corporation Confidential and Proprietary Information

187

BCL C library functions

XPRBsetrealfmt
PurposeSet the format for printing real numbers.
Synopsis
int XPRBsetrealfmt(XPRBprob prob, const char *fmt);
Arguments
prob
fmt

Reference to a problem.
Format string (as used by the C function printf). Simple format strings are of the form %n
where n may be, for instance, one ofgdefault printing format (precision: 6 digits; exponential notation if the exponent
resulting from the conversion is less than -4 or greater than or equal to theprecision).numf print real numbers in the style [-]d.d where the number of digits after thedecimal point is equal to the given precision num.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example sets the number printing format to 10 digits after the decimal point:
XPRBprob expl2;
expl2 = XPRBnewprob("example2");
XPRBsetrealfmt(expl2, "%.10f");
Further information
1. In problems with very large or very small numbers it may become necessary to change theprinting format to obtain a more exact output. In particular, by changing the precision it ispossible to reduce the difference between matrices loaded in memory into Xpress Optimizer andthe output produced by exporting them to a file.
2. This function can be used before any problem has been created (with first argument NULL). In thiscase the setting applies to all problems that are created subsequently.
Related topics
XPRBexportprob, XPRBloadmat, XPRBprintprob.

Fair Isaac Corporation Confidential and Proprietary Information

188

BCL C library functions

XPRBsetsense
PurposeSet the sense of the objective function.
Synopsis
int XPRBsetsense(XPRBprob prob, int dir);Arguments
prob
dir

Reference to a problem.
Sense of the objective function, which must be one of:
XPRB_MAXIM
maximize the objective;
XPRB_MINIM
minimize the objective.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob expl2;...
expl2 = XPRBnewprob("example2");
XPRBsetsense(expl2, XPRB_MAXIM);This sets expl2 as a maximization problem.
Further information
This functions sets the objective sense to maximization or minimization. It is set to minimization
by default.
Related topics
XPRBgetsense, XPRBsetobj.

Fair Isaac Corporation Confidential and Proprietary Information

189

BCL C library functions

XPRBsetsosdir
PurposeSet a branching directive for a SOS.
Synopsis
int XPRBsetsosdir(XPRBsos sos, int type, double val);
Arguments
sos
type

val

Reference to a previously created SOS.
The directive type, which must be one of:
XPRB_PRpriority;
XPRB_UP
first branch upwards;
XPRB_DN
first branch downwards;
XPRB_PU
pseudo cost on branching upwards;
XPRB_PD
pseudo cost on branching downwards.
An argument dependent on the type of the directive being defined. If type is:
XPRB_PRval will be the priority value, an integer between 1 (highest) and 1000
(lowest), the default;
XPRB_UPno input is required — choose any value, e.g. 0;
XPRB_DNno input is required — choose any value, e.g. 0;
XPRB_PUval will be the value of the pseudo cost for the upward branch;
XPRB_PDval will be the value of the pseudo cost for the downward branch.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBsos set1;...
set1 = XPRBnewsos(prob, "sos1", XPRB_S1);
XPRBsetsosdir(set1, 5);
XPRBsetsosdir(set1, XPRB_DN, 0);This gives a priority of 5 to the SOS set1 and sets branching downwards as the preferred direction
for set1.
Further information
This function sets any type of branching directive available in Xpress. This may be a priority forbranching on a SOS (type XPRB_PR), the preferred branching direction (types XPRB_UP, XPRB_DN) or
the estimated cost incurred when branching on a SOS (types XPRB_PU, XPRB_PD). Several directivesof different types may be set for a single set. Function XPRBsetvardir may be used to set a
directive for a variable.
Related topics
XPRBcleardir, XPRBsetvardir.

Fair Isaac Corporation Confidential and Proprietary Information

190

BCL C library functions

XPRBsetsolarrvar
PurposeSet the values assigned to multiple variables in a solution.
Synopsis
int XPRBsetsolarrvar(XPRBsol sol, const XPRBarrvar av, const double val[]);Arguments
sol
av
val

BCL reference to a previously created solution.
Reference to an array of variables.
Values to be assigned to the variables in the array (the number of coefficients mustcorrespond to the size of the array of variables).

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBsol sol1;
XPRBarrvar ty1;
double cr[] = {2, 13, 15, 6, 8.5};
ty1 = XPRBnewarrvar(prob, 5, XPRB_PL, "arry1", 0, 500);...
sol1 = XPRBnewsol(prob);
XPRBsetsolarrvar(sol1, ty1, cr);Further information
This function sets multiple variables to the given values in a solution, the variables coming fromarray av and the corresponding values from val. If a variable was already assigned a value in thatsolution, the value is overwritten.
Note:

all variables that are added to a solution must belong to the same problem as the solution
itself.

Related topics
XPRBdelsolvar, XPRBnewsol, XPRBsetsolvar.

Fair Isaac Corporation Confidential and Proprietary Information

191

BCL C library functions

XPRBsetsolvar
PurposeSet the value assigned to a variable in a solution.
Synopsis
int XPRBsetsolvar(XPRBsol sol, const XPRBvar var, double val);
Arguments
sol
var
val

BCL reference to a previously created solution.
BCL reference to a variable.
Value assigned to the variable var.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBsol sol1;
XPRBvar x1;
x1 = XPRBnewvar(expl1, XPRB_UI, "abc3", 0, 100);...
sol1 = XPRBnewsol(prob);
XPRBsetsolvar(sol1, x1, 7.0);
This example sets variable x1 to value 7.0 in solution sol1.
Further information
This function sets a variable to the given value in a solution. If the variable was already assigned avalue in that solution, the value is overwritten.
Note:

all variables that are added to a solution must belong to the same problem as the solution
itself.

Related topics
XPRBdelsolvar, XPRBnewsol, XPRBsetsolarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

192

BCL C library functions

XPRBsetterm
PurposeSet a linear constraint term.
Synopsis
int XPRBsetterm(XPRBctr ctr, XPRBvar var, double coeff);
Arguments
ctr
var
coeff

BCL reference to a previously created constraint.
BCL reference to a variable. May be NULL if not required.
Value of the coefficient of the variable var.

Return value
0 if function executed successfully, 1 otherwise.
ExampleXPRBprob prob;
XPRBctr ctr1;...
ctr1 = XPRBnewctr(prob, "r1", XPRB_E);
XPRBsetterm(ctr1, NULL, 7.0);
This sets the right hand side of the constraint ctr1 to 7.0.
Further information
This function sets the coefficient of a variable to the value coeff. If var is set to NULL, the righthand side of the constraint is set to coeff.
Note:

all terms that are added to a constraint must belong to the same problem as theconstraint itself.

Related topics
XPRBaddterm, XPRBdelctr, XPRBnewctr.

Fair Isaac Corporation Confidential and Proprietary Information

193

BCL C library functions

XPRBsetub
PurposeSet an upper bound.
Synopsis
int XPRBsetub(XPRBvar var, double bdu);
Arguments
varbdu

BCL reference to a variable.
The variable’s new upper bound.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code changes the upper bound of x1 to 200.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 1, 100);
XPRBsetub(x1, 200.0);
Further information
This function sets the upper bound on a variable.
Related topics
XPRBfixvar, XPRBgetbounds, XPRBgetlim, XPRBsetlb, XPRBsetlim.

Fair Isaac Corporation Confidential and Proprietary Information

194

BCL C library functions

XPRBsetvardir
PurposeSet a branching directive for a variable.
Synopsis
int XPRBsetvardir(XPRBvar var, int type, double c);
Arguments
var
type

c

BCL reference to a variable.
Directive type, which must be one of:
XPRB_PRpriority;
XPRB_UP
first branch upwards;
XPRB_DN
first branch downwards;
XPRB_PU
pseudo cost on branching upwards;
XPRB_PD
pseudo cost on branching downwards.
An argument dependent on the type of directive to be defined. Must be one of:
XPRB_PRpriority value — an integer between 1 (highest) and 1000 (least priority), thedefault;
XPRB_UPno input required — set to any value, e.g. 0;
XPRB_DNno input required — set to any value, e.g. 0;
XPRB_PUvalue of the pseudo cost on branching upwards;
XPRB_PD
value of the pseudo cost on branching downwards.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following example gives a priority of 10 to variable x1 and sets the preferred branchingdirection to be upwards.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
XPRBsetvardir(x1, XPRB_PR, 10);
XPRBsetvardir(x1, XPRB_UP, 0);
Further information
1. This function sets any type of branching directive available in Xpress. This may be a priority forbranching on a variable (type XPRB_PR), the preferred branching direction (types XPRB_UP,
XPRB_DN) or the estimated cost incurred when branching on a variable (types XPRB_PU, XPRB_PD).
Several directives of different types may be set for a single variable.
2. Note that it is only possibly to set branching directives for discrete variables (includingsemi-continuous and partial integer variables). Function XPRBsetsosdir may be used to set a
directive for a SOS.
Related topics
XPRBcleardir, XPRBsetsosdir.

Fair Isaac Corporation Confidential and Proprietary Information

195

BCL C library functions

XPRBsetvarlink
PurposeSet the interface pointer of a variable.
Synopsis
int XPRBsetvarlink(XPRBvar var, void *link);
Arguments
var
link

Reference to a BCL variable
Pointer to an interface object

Return value
0 if function executed successfully, 1 otherwise.
ExampleSet the interface pointer of variable x1 to vlink:
XPRBprob prob;
XPRBvar x1;
myinterfacetype *vlink;...
x1 = XPRBnewvar(prob, XB_UI, "abc3", 0, 100);
XPRBsetvarlink(x1, vlink);
Further information
This function sets the interface pointer of a variable to the indicated object. It may be used toestablish a connection between a variable in BCL and some other external program.
Related topics
XPRBgetvarlink, XPRBdefcbdelvar.

Fair Isaac Corporation Confidential and Proprietary Information

196

BCL C library functions

XPRBsetvartype
PurposeSet the variable type.
Synopsis
int XPRBsetvartype(XPRBvar var, int type);
Arguments
var
type

BCL reference to a variable.
The variable type, which is one of:
XPRB_PL
continuous;
XPRB_BV
binary;XPRB_UI
general integer;
XPRB_PI
partial integer;
XPRB_SCsemi-continuous;
XPRB_SI
semi-continuous integer.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following code changes the type of variable x1 from integer to binary, and consequently
reducing the upper bound to 1.
XPRBprob prob;
XPRBvar x1;...
x1 = XPRBnewvar(prob, XPRB_UI, "abc3", 0, 100);
XPRBsetvartype(x1, XPRB_BV);
Further information
This function changes the type of a variable that has been created previously.
Related topics
XPRBgetvarname, XPRBgetvartype, XPRBnewvar.

Fair Isaac Corporation Confidential and Proprietary Information

197

BCL C library functions

XPRBstartarrvar
PurposeStart the definition of a variable array.
Synopsis
XPRBarrvar XPRBstartarrvar(XPRBprob prob, int nbvar, const char *name);
Arguments
prob
nbvar
name

Reference to a problem.
The maximum number of variables in the array.
Name of the array. May be NULL if not required.

Return value
Reference to the new array if function executed successfully, NULL otherwise.
ExampleXPRBprob prob;
XPRBarrvar av2;...
av2 = XPRBstartarrvar(prob, 5, "arr2");
This starts the definition of an array with five elements, named arr2.
Further information
This function starts the definition of a variable array. It returns a reference to an array ofvariables that may be used, for instance, in the definition of constraints. Variables belonging toan array created by this function may stem from any LP-variables previously defined. They may beof different types, and can be positioned in any order. A variable may belong to several arrays,
but it is created only once (functions XPRBnewvar or XPRBnewarrvar). If the indicated name isalready in use, BCL adds an index to it. If no array name is given, BCL generates a default namestarting with AV.
Related topics
XPRBdelarrvar, XPRBendarrvar, XPRBnewarrvar.

Fair Isaac Corporation Confidential and Proprietary Information

198

BCL C library functions

XPRBsync
PurposeSynchronize BCL with the Optimizer.
Synopsis
int XPRBsync(XPRBprob prob, int synctype);
Arguments
prob
synctype

Reference to a problem.
Type of the synchronization. Possible values:
XPRB_XPRS_SOL
update the BCL solution information with the LP solution
currently held in the Optimizer;
XPRB_XPRS_SOLMIP
update the BCL solution information with the last MIP
solution found by the Optimizer;
XPRB_XPRS_PROB
force problem reloading.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThe following forces BCL to reload the matrix into the Optimizer even if there has been nochange other than bound changes to the problem definition in BCL since the preceding
optimization:
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBmipoptimize(expl2, "");...
XPRBsync(expl2, XPRB_XPRS_PROB);
XPRBmipoptimize(expl2, "");
Further information
1. This function resets the BCL problem status.
2. XPRB_XPRS_SOL: retrieves the current LP solution (through XPRSgetlpsol function and
XPRS_LPOBJVAL attribute); correctly used also in intsol callbacks as, when an integer solution isfound during a global search, it is always set up as an LP solution to the current node.
3. XPRB_XPRS_SOLMIP: retrieves the last MIP solution found (through XPRSgetmipsol function and
XPRS_MIPOBJVAL attribute); if used from an intsol callback, it will not necessarily return thesolution that caused the invocation of the callback (it is possible that another thread finds a new
integer solution before that one is retrieved).
4. XPRB_XPRS_SOL and XPRB_XPRS_SOLMIP: the solution information in BCL is updated with thesolution held in the Optimizer at the next solution access (only the objective value is updated
immediately).
5. XPRB_XPRS_PROB: at the next call to optimization or XPRBloadmat the problem is completely
reloaded into the Optimizer; bound changes are not passed on to the problem loaded in the
Optimizer any longer.
Related topics
XPRBgetsol, XPRBgetrcost, XPRBgetdual, XPRBgetslack, XPRBloadmat, XPRBlpoptimize,
XPRBmipoptimize.

Fair Isaac Corporation Confidential and Proprietary Information

199

BCL C library functions

XPRBwritedir
PurposeWrite directives to a file.
Synopsis
int XPRBwritedir(XPRBprob prob, const char *fname);
Arguments
prob
fname

Reference to a problem.
Name of the directives files. May be NULL if the problem name is to be used.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example writes all directives defined for the problem expl2 to the file example2.dir:
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBwritedir(expl2, NULL);
Further information
This function writes out to a file the directives defined for a problem. The extension .dir isappended to the given file name. When no file name is given, the name of the problem is used. If
a file of the given name exists already it is replaced.
Related topics
XPRBexportprob, XPRBsetvardir, XPRBsetsosdir.

Fair Isaac Corporation Confidential and Proprietary Information

200

BCL C library functions

XPRBwritesol
PurposeWrite the current Optimizer solution to a CSV format ASCII file, problem_name.asc (and .hdr).
Synopsis
int XPRBwritesol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If no file extension is specified, then extensions .hdr and .asc will be appended.
Flags to control output format. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSwritesol in the ‘Xpress Optimizer Reference Manual’for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example writes the current solution to the file example2.asc (and .hdr).
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBwritesol(expl2, "", "");
Further information
This function writes out to a file the current Optimizer solution. If no file extension is specified,then two files will be written with extensions .asc and .hdr appended to the given file name.
When no file name is given, the name of the problem is used. If a file of the given name exists
already it is replaced.
Related topics
XPRBwritebinsol, XPRBwriteprtsol, XPRBwriteslxsol.

Fair Isaac Corporation Confidential and Proprietary Information

201

BCL C library functions

XPRBwritebinsol
PurposeWrite the current Optimizer solution to a binary solution file for later input into the Optimizer.
Synopsis
int XPRBwritebinsol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If omitted, the extension .sol will be appended.
Flags to control output format. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSwritebinsol in the ‘Xpress Optimizer Reference
Manual’ for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example writes the current solution to the file example2.sol.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBwritebinsol(expl2, "", "");
Further information
This function writes out to a file the current Optimizer solution. If no file extension is specified,then the extension .sol is appended to the given file name. When no file name is given, the nameof the problem is used. If a file of the given name exists already it is replaced.
Related topics
XPRBreadbinsol, XPRBwritesol, XPRBwriteprtsol, XPRBwriteslxsol.

Fair Isaac Corporation Confidential and Proprietary Information

202

BCL C library functions

XPRBwriteprtsol
PurposeWrite the current Optimizer solution to a fixed format ASCII file, problem_name .prt.
Synopsis
int XPRBwriteprtsol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If omitted, the extension .prt will be appended.
Flags to control output format. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSwriteprtsol in the ‘Xpress Optimizer Reference
Manual’ for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example writes the current solution to the file example2.prt.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBwriteprtsol(expl2, "", "");
Further information
This function writes out to a file the current Optimizer solution. If no file extension is specified,then the extension .prt is appended to the given file name. When no file name is given, the nameof the problem is used. If a file of the given name exists already it is replaced.
Related topics
XPRBwritesol, XPRBwritebinsol, XPRBwriteslxsol.

Fair Isaac Corporation Confidential and Proprietary Information

203

BCL C library functions

XPRBwriteslxsol
PurposeWrite the current Optimizer solution to an ASCII solution file (.slx) using a similar format to MPS
files.
Synopsis
int XPRBwriteslxsol(XPRBprob prob, const char *fname, const char *flags);
Arguments
prob
fname
flags

Reference to a problem.
Name of the solution file. May be NULL or the empty string if the problem name is to be
used. If omitted, the extension .slx will be appended.
Flags to control output format. If no flags need to be specified, use either NULL or theempty string. Refer to function XPRSwriteslxsol in the ‘Xpress Optimizer Reference
Manual’ for details.

Return value
0 if function executed successfully, 1 otherwise.
ExampleThis example writes the current solution to the file example2.slx.
XPRBprob expl2;
expl2 = XPRBnewprob("example2");...
XPRBwriteslxsol(expl2, "", "");
Further information
This function writes out to a file the current Optimizer solution. If no file extension is specified,then the extension .slx is appended to the given file name. When no file name is given, the nameof the problem is used. If a file of the given name exists already it is replaced.
Related topics
XPRBreadslxsol, XPRBwritesol, XPRBwritebinsol, XPRBwriteprtsol.

Fair Isaac Corporation Confidential and Proprietary Information

204

C HAPTER 5

BCL in C++
5.1

An overview of BCL in C++
The C++ interface of BCL provides the full functionality of the C version except for the data input,
output and error handling for which the corresponding C functions may be used. The C modelingobjects, such as variables, constraints and problems, are converted into classes, and theirassociated functions into methods of the corresponding class in C++.
To use the C++ version of BCL, the C++ header file must be included at the beginning of the
program (and not the main BCL header file xprb.h).
#include "xprb_cpp.h"

Using C++, the termwise definition of constraints is even easier. This has been achieved byoverloading the algebraic operators like ’+‘, ’-‘, ’<=‘, or ’==‘. With these operators constraints may
be written in a form that is close to an algebraic formulation.
It should be noted that the names of classes and methods have been adapted to C++ naming
standards: All C++ classes that have a direct correspondence with modeling objects in BCL(namely XPRBprob, XPRBvar, XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBindexSet, XPRBbasis) takethe same names, with the exception of XPRBindexSet. In the names of the methods the prefix
XPRB has been dropped, as have been references to the type of the object. For example, function
XPRBgetvarname is turned into the method getName of class XPRBvar.
All C++ classes of BCL are part of the namespace dashoptimization. To use the (short) classnames, it is recommended to add the line
using namespace ::dashoptimization;at the beginning of every program that uses the C++ classes of BCL.
C++ functions can be used together with C functions, for instance when printing program output
or using Xpress Optimizer functions. However, it is not possible to mix BCL C and C++ objects in a
program.

5.1.1

ExampleAn example of use of BCL in C++ is the following, which constructs the scheduling example
described in Chapter 2:#include <iostream>#include "xprb_cpp.h"using namespace std;
using namespace ::dashoptimization;

Fair Isaac Corporation Confidential and Proprietary Information

205

BCL in C++#define NJ#define NT410// Number of jobs// Time limit

double DUR[] = {3,4,2,2};// Durations of jobs

XPRBvar start[NJ];
XPRBvar delta[NJ][NT];XPRBvar z;// Start times of jobs// Binaries for start times// Max. completion time

XPRBprob p("Jobs");// Initialize BCL & a new problem

void jobsModel(){XPRBexpr le;
int j,t;// Create start time variables
for(j=0;j<NJ;j++) start[j] = p.newVar("start");z = p.newVar("z",XPRB_PL,0,NT); // Makespan variablefor(j=0;j<NJ;j++)// Binaries for each job
for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] =p.newVar(XPRBnewname("delta%d%d",j+1,t+1),XPRB_BV);
for(j=0;j<NJ;j++)// Calculate max. completion timep.newCtr("Makespan", start[j]+DUR[j] <= z);// Precedence relation betw. jobs
p.newCtr("Prec", start[0]+DUR[0] <= start[2]);for(j=0;j<NJ;j++)// Linking start times & binaries{
le=0;
for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j][t];p.newCtr(XPRBnewname("Link_%d",j+1), le == start[j]);}for(j=0;j<NJ;j++)// Unique start time for each job{
le=0;
for(t=0;t<(NT-DUR[j]+1);t++) le += delta[j][t];p.newCtr(XPRBnewname("One_%d",j+1), le == 1);}
p.setObj(z);// Define and set objectivefor(j=0;j<NJ;j++) start[j].setUB(NT-DUR[j]+1);// Upper bounds on "start" var.s}
void jobsSolve(){
int j,t,statmip;
for(j=0;j<NJ;j++)for(t=0;t<NT-DUR[j]+1;t++)delta[j][t].setDir(XPRB_PR,10*(t+1));// Give highest priority to var.s for earlier start times
p.setSense(XPRB_MINIM);
p.mipOptimize();// Solve the problem as MIP
statmip = p.getMIPStat();// Get the MIP problem statusif((statmip == XPRB_MIP_SOLUTION) ||(statmip == XPRB_MIP_OPTIMAL)){// An integer solution has been foundcout << "Objective: " << p.getObjVal() << endl;
for(j=0;j<NJ;j++){// Print the solution for all start times
cout << start[j].getName() << ": " << start[j].getSol();cout << endl;

Fair Isaac Corporation Confidential and Proprietary Information

206

BCL in C++}}}
int main(int argc, char **argv){
jobsModel();// Problem definition
jobsSolve();// Solve and print solution
return 0;}

The definition of SOS is similar to the definition of constraints.
XPRBsos set[NJ];
void jobsModel(){...
for(j=0;j<NJ;j++)// Variables for each job
for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] =p.newVar(XPRBnewname("delta%d%d",j+1,t+1),XPRB_PL,0,1);
for(j=0;j<NJ;j++)// SOS definition{
le=0;
for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j][t];set[j] = p.newSos("sosj",XPRB_S1,le);}}Branching directives for the SOSs are added as follows.
for(j=0;j<NJ;j++) set[j].setDir(XPRB_DN);// First branch downwards on sets

Adding the following two lines during or after the problem definition will print the problem tothe standard output and export the matrix to a file respectively.
p.print();// Print out the problem def.
p.exportProb(XPRB_MPS,"expl1");// Output matrix to MPS file

Similarly to what has been shown for the problem formulation in C, we may read data from fileand use index sets in the problem formulation. The following changes and additions to the basicmodel formulation are required for the creation of index sets based on data input from file. The
function jobsSolve is left out in this listing since it remains unchanged from the previous one.
#include <iostream>#include <cstdio>#include <cstdlib>#include "xprb_cpp.h"using namespace std;
using namespace ::dashoptimization;#define MAXNJ 4#define NT
10// Max. number of jobs// Time limit

int NJ = 0;
double DUR[MAXNJ];// Number of jobs read in// Durations of jobs

XPRBindexSet Jobs;
XPRBvar *start;// Names of Jobs// Start times of jobs

Fair Isaac Corporation Confidential and Proprietary Information

207

BCL in C++

XPRBvar **delta;
XPRBvar z;// Binaries for start times// Max. completion time

XPRBprob p("Jobs");// Initialize BCL & a new problem

void readData(){
char name[100];
FILE *datafile;// Create a new index set
Jobs = p.newIndexSet("jobs", MAXNJ);// Open data file for read accessdatafile=fopen("durations.dat","r");// Read in all (non-empty) lines up to the end of the file
while(NJ<MAXNJ &&XPRBreadlinecb(XPRB_FGETS, datafile, 99, "T,d", name, &DUR[NJ])){
Jobs += name;// Add job to the index set
NJ++;}
fclose(datafile);// Close the input filecout << "Number of jobs read: " << Jobs.getSize() << endl;}
void jobsModel(){XPRBexpr le;
int j,t;// Create start time variables with bounds
start = new XPRBvar[NJ];if(start==NULL){ cout << "Not enough memory for ’start’ variables." << endl;
exit(0); }for(j=0;j<NJ;j++)start[j] = p.newVar("start",XPRB_PL,0,NT-DUR[j]+1));z = p.newVar("z",XPRB_PL,0,NT); // Makespan variabledelta = new XPRBvar*[NJ];if(delta==NULL){ cout << "Not enough memory for ’delta’ variables." << endl;
exit(0); }for(j=0;j<NJ;j++)// Binaries for each job{
delta[j] = new XPRBvar[NT];if(delta[j]==NULL){ cout <<"Not enough memory for ’delta_j’ variables." << endl;
exit(0); }for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] =p.newVar(XPRBnewname("delta%s_%d",Jobs[j],t+1), XPRB_BV);
for(j=0;j<NJ;j++)// Calculate max. completion timep.newCtr("Makespan", start[j]+DUR[j] <= z);// Precedence relation betw. jobs
p.newCtr("Prec", start[0]+DUR[0] <= start[2]);for(j=0;j<NJ;j++)// Linking start times & binaries{
le=0;
for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j][t];p.newCtr(XPRBnewname("Link_%d",j+1), le == start[j]);}for(j=0;j<NJ;j++)// Unique start time for each job{
le=0;
for(t=0;t<(NT-DUR[j]+1);t++) le += delta[j][t];p.newCtr(XPRBnewname("One_%d",j+1), le == 1);}

Fair Isaac Corporation Confidential and Proprietary Information

208

BCL in C++

p.setObj(z);jobsSolve();// Define and set objective// Solve the problem

delete [] start;for(j=0;j<NJ;j++) delete [] delta[j];delete [] delta;}
int main(int argc, char **argv){
readData();// Read in the data
jobsModel();// Problem definition
return 0;}

5.1.2

QCQP Example
The following is an implementation with BCL C++ of the QCQP example described in Section 3.5.1:#include <iostream>#include "xprb_cpp.h"using namespace std;
using namespace ::dashoptimization;#define N 42
double CX[N], CY[N], R[N];...
int main(int argc, char **argv){
int i,j;
XPRBvar x[N],y[N];XPRBexpr qe;
XPRBctr cobj, c;
XPRBprob prob("airport");// Initialize the data arrays// Initialize a new problem in BCL/**** VARIABLES ****/
for(i=0;i<N;i++)x[i] = prob.newVar(XPRBnewname("x(%d)",i+1), XPRB_PL, -10, 10);for(i=0;i<N;i++)y[i] = prob.newVar(XPRBnewname("y(%d)",i+1), XPRB_PL, -10, 10);/****OBJECTIVE****/// Minimize the total distance between all points
qe=0;
for(i=0;i<N-1;i++)for(j=i+1;j<N;j++) qe+= sqr(x[i]-x[j])+sqr(y[i]-y[j]);cobj = prob.newCtr("TotDist", qe);prob.setObj(cobj);// Set objective function/**** CONSTRAINTS ****/// All points within given distance of their target location
for(i=0;i<N;i++)c = prob.newCtr("LimDist", sqr(x[i]-CX[i])+sqr(y[i]-CY[i]) <= R[i]);/****SOLVING + OUTPUT****/
prob.setSense(XPRB_MINIM);
prob.lpOptimize();// Choose sense of optimization// Solve the problem

cout << "Solution: " << prob.getObjVal() << endl;
for(i=0;i<N;i++){cout << x[i].getName() << ": " << x[i].getSol() << ", ";cout << y[i].getName() << ": " << y[i].getSol() << endl;}

Fair Isaac Corporation Confidential and Proprietary Information

209

BCL in C++

return 0;}

5.1.3

Error handling
The default behavior of BCL in the case of an error is to output a message and terminate theprogram. However, in C++ applications it may be more convenient to raise exceptions instead ofsimply exiting from the program. With the BCL C++ interface the user has the possibility todisable the standard ’exit on error’ behavior replacing it, for instance, by C++ exceptions.
The C++ program below implements the example of user error handling from Section 3.6. The
default error handling of BCL is disabled (function XPRBseterrctrl) and the error handlingcallback is defined to raise C++ exceptions in the case of an error—the BCL C++ interface uses the
callback functions of the BCL C library. When using the BCL C functions with BCL C++ objects weneed to employ their C representation (obtained with method getCRef).
Besides the user error handling this example also shows how to work with the user message
printing callback to redirect the BCL output to a user-defined callback function (this includes
output from BCL and anything printed through XPRBprintf). By setting the BCL message printing
level (method setMsgLevel) you can control the amount of information output by BCL.
#include <iostream>#include <string>#include "xprb_cpp.h"using namespace std;
using namespace ::dashoptimization;
class bcl_exception{
public:string msg;
int code;
bcl_exception(int c,const char *m){
code=c;msg=string(m);cout << "EXCP:" << msg << "\n";}};/**** User error handling function ****/
void XPRB_CC usererror(xbprob* prob, void *vp, int num, int type,
const char *t){
throw bcl_exception(num, t);}/**** User printing function ****/
void XPRB_CC userprint(xbprob* prob, void *vp, const char *msg){
static int rtsbefore=1;/* Print ’BCL output’ whenever a new output line starts,
otherwise continue to print the current line. */if(rtsbefore)
cout << "BCL output: " << msg;
else
cout << msg;
rtsbefore=(msg[strlen(msg)-1]==’\n’);}/***********************************************************************/
void modexpl3(XPRBprob &p)

Fair Isaac Corporation Confidential and Proprietary Information

210

BCL in C++{
XPRBvar x[3];
XPRBlinExp le;int i;
for(i=0;i<2;i++) x[i]=p.newVar(XPRBnewname("x_%d",i), XPRB_UI, 0, 100);/* Create the constraints:
C1: 2x0 + 3x1 >= 41
C2: x0 + 2x1 = 13 */p.newCtr("C1", 2*x[0] + 3*x[1] >= 41);p.newCtr("C2", x[0] + 2*x[1] == 13);// Uncomment the following line to cause an error in the model that// triggers the user error handling:// x[2]=p.newVar("x_2", XPRB_UI, 10,1);
le=0;
for(i=0;i<2;i++) le += x[i];p.setObj(le);p.setSense(XPRB_MINIM);// Objective: minimize x0+x1// Select objective function// Set objective sense to minimization

p.lpOptimize();// Solve the LP
XPRBprintf(p.getCRef(), "problem status: %d LP status: %dp.getProbStat(), p.getLPStat(), p.getMIPStat());

MIP status: %d\n",// This problem is infeasible, that means the following command will fail.
// It prints a warning if the message level is at least 2
XPRBprintf(p.getCRef(), "Objective: %g\n", p.getObjVal());
for(i=0;i<2;i++)// Print solution values
XPRBprintf(p.getCRef(), "%s:%g, ", x[i].getName(), x[i].getSol());
XPRBprintf(p.getCRef(), "\n");}/***********************************************************************/
int main(){
XPRBprob *p;
XPRBseterrctrl(0);XPRB::setMsgLevel(2);// Switch to error handling by the user’s program// Set the printing flag. Try other values:// 0 - no printed output, 1 - only errors,// 2 - errors and warnings, 3 - all messages// Define the callback functions:
XPRBdefcbmsg(NULL, userprint, NULL);XPRBdefcberr(NULL, usererror, NULL);
try{
p=new XPRBprob("Expl3");// Initialize a new problem in BCL}
catch(bcl_exception &e){cout << e.code << ":" << e.msg;
return 1;}
try{
modexpl3(*p);// Formulate and solve the problem}
catch(bcl_exception &e){cout << e.code << ":" << e.msg << "\n";return 2;}

Fair Isaac Corporation Confidential and Proprietary Information

211

BCL in C++

catch(const char *m){cout << m << "\n";return 3;}
catch(...){
cout << "other exception\n";return 4;}
return 0;}

5.2

C++ class reference
The complete set of classes of the BCL C++ interface is summarized in the following list:
XPRB

Initialization and general settings.

p. 214

XPRBbasis

Methods for accessing bases.

p. 218

XPRBctr

Methods for modifying and accessing constraints and operators forconstructing them. Note that all terms in a constraint must belong to
the same problem as the constraint itself.
p. 220

XPRBcut

Methods for modifying and accessing cuts and operators forconstructing them. Note that all terms in a cut must belong to thesame problem as the cut itself.
p. 237

XPRBexpr

Methods and operators for constructing linear and quadratic
expressions. Note that all variables in an expression must belong to thesame problem.
p. 243

XPRBindexSet

Methods for accessing index sets and operators for adding andretrieving set elements.

p. 249

XPRBprob

Problem definition, including methods for creating and deleting themodeling objects, problem solving, changing settings, and retrieving
solution information.
p. 253

XPRBrelation

Methods and operators for constructing linear or quadratic relations
from expressions.
p. 284

XPRBsol

Methods for defining, modifying and accessing solutions. Note that all
variables in a solution must belong to the same problem as thesolution itself.
p. 286

XPRBsos

Methods for modifying and accessing Special Ordered Sets andoperators for constructing them. Note that all members in a SOS must
belong to the same problem as the SOS itself.
p. 290

XPRBvar

Methods for modifying and accessing variables.

p. 295The method isValid may require some explanation: it should be used in combination withmethods getVarByName, getCtrByName etc. These methods always return an object of the desired
type, unlike the corresponding functions in standard BCL which return a NULL pointer if the object
was not found. Only with method isValid it is possible to test whether the object is a valid
object, that is, whether it is contained in a problem definition.

Fair Isaac Corporation Confidential and Proprietary Information

212

BCL in C++

All C++ classes that have a direct correspondence with modeling objects in BCL (namely XPRBprob,
XPRBvar, XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBindexSet, XPRBbasis) take the same names,with the exception of XPRBindexSet. The corresponding BCL modeling object in C can be obtained
from each of these classes, with the method getCRef. It is also possible to obtain the Xpress
Optimizer problem corresponding to a BCL C++ problem by using method XPRBprob.getXPRSprob.
Please see Section B.6 for further detail on using BCL C++ with the Optimizer library.
Most of the methods of the classes with direct correspondence to C modeling objects callstandard BCL C functions, as indicated, and return their result.
The major difference between the C and C++ interfaces is in the way linear and quadratic
expressions and constraints are created. In C++, the algebraic operators like + or == areoverloaded so that constraints may be written in a form that is close to an algebraic formulation.
Some additional classes have been introduced to aid the termwise definition of constraints withoverloaded arithmetic operators. Linear and quadratic expressions (class XPRBexpr) are requiredin the definition of constraints and Special Ordered Sets. Linear and quadratic relations (class
XPRBrelation), may be used as an intermediary in the definition of constraints.
Another class that does not correspond to any standard BCL modeling object is the class XPRB that
contains methods relating to the initialization of BCL and the general status of the software.

Fair Isaac Corporation Confidential and Proprietary Information

213

BCL in C++

XPRB
Description
Initialization and general settings.
Methods

int getTime();Get the running time.
const char *getVersion();Get the version number of BCL.
int init();
Initialize BCL.
int setColOrder(int num);Set a column ordering criterion for matrix generation.
int setMsgLevel(int lev);Set the message print level.
int setRealFmt(String fmt);
Set the format for printing real numbers.

Method detail

getTime
Synopsis
int getTime();Return value

System time measure in milliseconds.

Description

This methods returns the system time measure in milliseconds. The absolute value issystem-dependent. To measure the execution time of a program, this methods can beused to calculate the difference between the start time and the time at the desired
point in the program.

ExampleThis example shows how to measure the elapsed time in a BCL program:int starttime;
XPRB::init();starttime = XPRB::getTime();...
cout << "Time: " << (XPRB::getTime()-starttime)/1000;
cout << " sec" << endl;

Related topics

Calls XPRBgettime

getVersion
Synopsisconst char *getVersion();Fair Isaac Corporation Confidential and Proprietary Information

214

BCL in C++

Return value

BCL version number if function executed successfully, NULL otherwise.

Description

The version number returned by this method is required if the user is reporting aproblem.

ExampleThe following example retrieves and prints out the BCL version number:const char *version;
XPRB::init();version = XPRB::getVersion();cout << "Xpress BCL version " << version << endl;

Related topics

Calls XPRBgetversion

init
Synopsis
int init();
Return value

0 if initialization executed successfully, 1 otherwise.

Description

This method explicitly initializes BCL, that is it tests whether a license for running thissoftware is available. Without this explicit initialization the initialization will be
performed at the creation of the first problem (see XPRBprob). There is no need to callthis explicit initialization unless you wish to separate the license check from problem
creation or perform some general settings before creating any problem. This method
also initializes Xpress Optimizer. In applications that create a large number of problems
it is recommended to use the explicit initialization—once only per process for highest
efficiency.

ExampleThis example shows how to initialize BCL explicitly before creating a problem.
XPRBprob *prob;
if (XPRB::init()){ cout << "Initialization failed" << endl; return 1; }prob = new XPRBprob("myprob");

Related topics

Calls XPRBinit

setColOrder
Synopsis
int setColOrder(int num);
The ordering flag, which must be one of:0
default ordering;1
alphabetical order.

Argumentnum

Return value

0 if method executed successfully, 1 otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

215

BCL in C++

Description

1. BCL runs reproduce always the same matrix for a problem. This method allows the user
to choose a different ordering criterion than the default one. Note that this method
only changes the order of columns in what is sent to Xpress Optimizer, you do not see
any effect when exporting the matrix with BCL. However you can control the effect byexporting the matrix from the Optimizer.
2. The setting applies to all problems that are created subsequently. It is also possible tochange the setting for a particular problem (see XPRBprob).
Calls XPRBsetcolorder

Related topics

setMsgLevel
Synopsis
int setMsgLevel(int lev);
The message level, i.e. the type of messages printed by BCL. This may be one of:0
no messages printed;
1
error messages only printed;
2
warnings and errors printed;
3
warnings, errors, and Optimizer log printed (default);
4
all messages printed.

Argumentlevel

Return value

0 if method executed successfully, 1 otherwise.

Description

1. BCL can produce different types of messages; status information, warnings and errors.
This function controls which of these are output. For settings 1 or higher, thecorresponding Optimizer output is also displayed. In addition to this setting, theamount of Optimizer output can be modified through several Optimizer printing
control parameters (see the ‘Xpress Optimizer Reference Manual’).
2. The setting applies to all problems that are created subsequently. It is also possible tochange the setting for a particular problem (see XPRBprob).

ExampleSee XPRBprob.setMsgLevel.

Related topics

Calls XPRBsetmsglevel

setRealFmt
Synopsis
int setRealFmt(String fmt);
Format string (as used by the C function printf). Simple format strings are of
the form %n where n may be, for instance, one ofgdefault printing format (precision: 6 digits; exponential notation if
the exponent resulting from the conversion is less than -4 or greaterthan or equal to the precision).numf print real numbers in the style [-]d.d where the number of digits
after the decimal point is equal to the given precision num.

Argument

fmt

Return value

0 if method executed successfully, 1 otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

216

BCL in C++

Description

1. In problems with very large or very small numbers it may become necessary to change
the printing format to obtain a more exact output. In particular, by changing the
precision it is possible to reduce the difference between matrices loaded in memory into
Xpress Optimizer and the output produced by exporting them to a file.
2. The setting applies to all problems that are created subsequently. It is also possible tochange the setting for a particular problem (see XPRBprob).

ExampleThis example sets the BCL number printing format to 8 digits after the decimal point. It
then creates a problem and changes the number printing format for this problem backto the default:
XPRBprob *prob;
XPRB::init();
XPRB::setRealFmt("%.10f");
prob = new XPRBprob("myprob");
prob->setRealFmt("%g");

Related topics

Calls XPRBsetrealfmt

Fair Isaac Corporation Confidential and Proprietary Information

217

BCL in C++

XPRBbasis
Description
Methods for accessing bases.
Constructors
XPRBbasis();XPRBbasis(xbbasis *bs);
Methods

xbbasis *getCRef();
Get the C modeling object.
bool isValid();
Test the validity of the basis object.
void reset();Reset the basis object.

Constructor detail

XPRBbasis
SynopsisArgument

XPRBbasis();XPRBbasis(xbbasis *bs);bs A basis in BCL C.

Description

Create a new basis object.

Method detail

getCRef
Synopsisxbbasis *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the basis object in BCL C that belongs to the C++ basis object.

isValid
Synopsisbool isValid();

Fair Isaac Corporation Confidential and Proprietary Information

218

BCL in C++

Return value

true if object is valid, false otherwise.

Description

This method checks whether the basis object is correctly defined.

reset
Synopsisvoid reset();Description

Clear the definition of the basis object; includes deletion of the underlying C object.

ExampleSee XPRBprob.saveBasis.

Related topics

Calls XPRBdelbasis

Fair Isaac Corporation Confidential and Proprietary Information

219

BCL in C++

XPRBctr
Description
Methods for modifying and accessing constraints and operators for constructing them. Note that
all terms in a constraint must belong to the same problem as the constraint itself.
Constructors
XPRBctr();
XPRBctr(xbctr *c);
XPRBctr(xbctr *c, XPRBrelation& r);
Methods

int add(XPRBexpr& e);
Add an expression to a constraint.
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
int addTerm(XPRBvar& var, XPRBvar& var2, double val);
int addTerm(double val, XPRBvar& var, XPRBvar& var2);
int addTerm(XPRBvar& var, XPRBvar& var2);
Add a term to a constraint.
int delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);
Delete a term from a constraint.
double getAct();
Get activity value for a constraint.
double getCoefficient(XPRBvar& var);
double getCoefficient(XPRBvar& var, XPRBvar& var2);
Get the coefficient of a constraint term.
xbctr *getCRef();
Get the C modeling object.
double getDual();Get dual value.
int getIndicator();Get the indicator type of a constraint.
XPRBvar getIndVar();Get the indicator variable of a constraint.
const char *getName();Get the name of a constraint.
int getRange(double *lw, double *up);
Get the range values for a range constraint.
double getRangeL();
Get the lower range bound for a range constraint.
double getRangeU();
Get the upper range bound for a range constraint.
double getRHS();Get the right hand side value of a constraint.
double getRNG(int rngtype);
Get ranging information for a constraint.

Fair Isaac Corporation Confidential and Proprietary Information

220

BCL in C++

int getRowNum();Get the row number for a constraint.
int getSize();Get the size of a constraint.
double getSlack();
Get slack value for a constraint.
int getType();Get the row type of a constraint.
bool isDelayed();Check the type of a constraint.
bool isIncludeVars();
Check the type of a constraint.
bool isIndicator();Check the type of a constraint.
bool isModCut();
Check the type of a constraint.
bool isValid();
Test the validity of the constraint object.
const void *nextTerm(const void *ref, XPRBvar& var, double *coeff);const void *nextTerm(const void *ref, XPRBvar& var, XPRBvar& v2, double *coeff);
Enumerate the terms of a constraint.
int print();
Print out a constraint.
void reset();Reset the constraint object.
int setDelayed(bool dstat);
Set the constraint type.
int setIncludeVars(bool ivstat);
Set the constraint type.
int setIndicator(ind dir, XPRBvar );Set the indicator constraint type.
int setModCut(bool mstat);
Set the constraint type.
int setRange(double lw, double up);Define a range constraint.
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(double val);
int setTerm(XPRBvar& var, XPRBvar& var2, double val);
int setTerm(double val, XPRBvar& var, XPRBvar& var2);
Set a constraint term.
int setType(int type);
Set the constraint type.
Operators
Assigning constraints and adding (linear or quadratic) expressions:
ctr = rel
ctr += expr
ctr -= expr

Fair Isaac Corporation Confidential and Proprietary Information

221

BCL in C++

Constructor detail

XPRBctrSynopsisArguments

Description

XPRBctr();
XPRBctr(xbctr *c);
XPRBctr(xbctr *c, XPRBrelation& r);c
A constraint in BCL C.
r
Relation defining the constraint.
Create a new constraint object.

Method detail

add
Synopsis
int add(XPRBexpr& e);
A linear or quadratic expression (may be just a single variable or a constant).

Argumente

Return value

0 if method executed successfully, 1 otherwise.

Description

This method adds a linear or quadratic expression to the left hand side of a constraint.
That means, if the expression contains a constant, this value is subtracted from theconstant representing the right hand side of the constraint.

ExampleSee XPRBctr.setTerm.

addTerm
Synopsis
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
int addTerm(XPRBvar& var, XPRBvar& var2, double val);
int addTerm(double val, XPRBvar& var, XPRBvar& var2);
int addTerm(XPRBvar& var, XPRBvar& var2);
Arguments

var
var2
val

A BCL variable.
A second BCL variable (may be the same as var).
Value of the coefficient of the variable var.

Fair Isaac Corporation Confidential and Proprietary Information

222

BCL in C++

Return value

0 if method executed successfully, 1 otherwise.

Description

This method adds a new term to a constraint, comprising the variable var (or the
product of variables var and var2) with coefficient val. If the constraint already has aterm with variable var (respectively variables var and var2), val is added to its
coefficient. If no variable is specified, the value val is added to the right hand side of
the constraint. Constraint terms can also be added with method XPRBctr.add.

ExampleSee XPRBctr.setTerm.

Related topics

Calls XPRBaddterm or XPRBaddqterm

delTerm
Synopsisint delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);
A BCL variable.
A second BCL variable (may be the same as var).

Arguments

var
var2

Return value

0 if method executed successfully, 1 otherwise.

Description

This function deletes a variable term from the given constraint. The constant term (righthand side value) is changed/reset with method XPRBctr.setTerm.

Related topics

Calls XPRBdelterm

getActSynopsisdouble getAct();
Return value

Activity value for the constraint, 0 in case of an error.

Description

This method returns the activity value for a constraint. It may be used with constraints
that are not part of the problem (in particular, constraints without relational operators,
that is, constraints of type XPRB_N). In this case the function returns the evaluation of theconstraint terms involving variables that are in the problem. Otherwise, the constraint
activity is calculated as activity = RHS – slack.
If this method is called after completion of a global search and an integer solution has
been found (that is, if method XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION
or XPRB_MIP_OPTIMAL), it returns the value corresponding to the best integer solution. If
no solution is available this function outputs a warning and returns 0. In all other cases
it returns the activity value in the last LP that has been solved. If this function is usedduring the execution of an optimization process (for instance in Optimizer library
callback functions) it needs to be preceded by a call to XPRBprob.sync with the flag
XPRB_XPRS_SOL.

ExampleThe following example shows how to retrieve solution values and some otherinformation for a constraint.

Fair Isaac Corporation Confidential and Proprietary Information

223

BCL in C++

XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);...

// Solve an LP problem

if (Ctr1.getRowNum() >= 0 && prob.getLPStat()==XPRB_LP_OPTIMAL){
cout << Ctr1.getName() << ": activity: " << Ctr1.getAct();cout << " = " << Ctr1.getRHS() << " - " << Ctr1.getSlack();cout << ", dual: " << Ctr1.getDual() << endl;}
else
cout << "No solution information available." << endl;
Related topics

Calls XPRBgetact

getCoefficient
Synopsisdouble getCoefficient(XPRBvar& var);
double getCoefficient(XPRBvar& var, XPRBvar& var2);
A BCL variable.
A second BCL variable (may be the same as var).

Arguments

var
var2

Return value

The coefficient of the given variable or pair of variables, 0 if the constraint does notcontain the term.

Description

This function returns the coefficient of a given variable var or of the quadratic term
var*var2 in the constraint ctr. Return value 0 indicates that the term is not contained in
the constraint. If var is set to NULL, this method returns the right hand side (constantterm) of the constraint.

ExampleSee XPRBctr.setTerm.

Related topics

Calls XPRBgetcoeff or XPRBgetqcoeff

getCRef
Synopsisxbctr *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the constraint object in BCL C that belongs to the C++ constraint
object.

Fair Isaac Corporation Confidential and Proprietary Information

224

BCL in C++

getDualSynopsisdouble getDual();Return value

Dual value for the constraint, 0 in case of an error.

Description

This function returns the dual value for a constraint. The user may wish to test firstwhether this constraint is part of the problem, for instance by checking that the row
number is non-negative.
Dual information is available only after LP solving. To obtain dual values for a MIP
solution (that is, if function XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or
XPRB_MIP_OPTIMAL), you need to fix the discrete variables to their solution values with acall to XPRSfixglobals, followed by a call to XPRBlpoptimize before calling XPRBgetdual.
Otherwise, if this function is called when a MIP solution is available it returns 0.
If no solution information is available this function outputs a warning and returns 0.
If this function is used during the execution of an optimization process (for instance in
Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync
with the flag XPRB_XPRS_SOL. In this case it returns the dual value in the last LP that has
been solved.

ExampleSee XPRBctr.getAct.

Related topics

Calls XPRBgetdual

getIndicator
Synopsis
int getIndicator();an ordinary constraint;
an indicator constraint with condition b = 1;
an indicator constraint with condition b = 0;an error has occurred.

Return value

0
1
-1
-2

Description

This method returns the indicator status of the given constraint.

ExampleSee XPRBctr.setIndicator.

Related topics

Calls XPRBgetindicator

getIndVar
Synopsis
XPRBvar getIndVar();
Return value

A BCL variable.

Fair Isaac Corporation Confidential and Proprietary Information

225

BCL in C++

Description

This method returns the indicator variable associated with the given constraint. Thismethod always returns a BCL variable the validity of which needs to be checked with
XPRBvar.isValid.

ExampleSee XPRBctr.setIndicator.

Related topics

Calls XPRBgetindvar

getName
Synopsisconst char *getName();Return value

Name of the constraint if function executed successfully, NULL otherwise

Description

This method returns the name of a constraint. If the user has not defined a name thedefault name generated by BCL is returned.

ExampleSee XPRBctr.getAct.

Related topics

Calls XPRBgetctrname

getRange
Synopsis
int getRange(double *lw, double *up);
Lower bound on the range constraint.
Upper bound on the range constraint.

Arguments

lw
up

Return value

0 if method executed successfully, 1 otherwise.

Description

This method returns the range values of the given constraint.

Related topics

Calls XPRBgetrange

getRangeL
Synopsisdouble getRangeL();
Return value

Lower bound on the range constraint.

Description

This method returns the lower bound on the range defined for the given constraint.

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBgetrange

Fair Isaac Corporation Confidential and Proprietary Information

226

BCL in C++

getRangeU
Synopsisdouble getRangeU();
Return value

Upper bound on the range constraint.

Description

This method returns the upper bound on the range defined for the given constraint.

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBgetrange

getRHS
Synopsisdouble getRHS();
Return value

Right hand side value of the constraint, 0 in case of an error.

Description

This method returns the right hand side value (i.e. the constant term) of a previously
defined constraint. The default right hand side value is 0. If the given constraint is aranged constraint this function returns its upper bound.

ExampleSee XPRBctr.getAct.

Related topics

Calls XPRBgetrhs

getRNG
Synopsisdouble getRNG(int rngtype);
The type of ranging information sought. This is one of:
XPRB_UPACT
upper activity (= the level to which the constraint activity
may be increased at a cost per unit of increase given by the
XPRB_UUP value, ignoring the upper bound on theconstraint as specified by its RHS);
XPRB_LOACT
lower activity (= the level to which the constraint activity
may be decreased at a cost per unit of decrease given by
the XPRB_UDN value, ignoring the lower bound on theconstraint as specified by its RHS);
XPRB_UUP
upper unit cost;
XPRB_UDN
lower unit cost.

Argument

rngtype

Return value

Ranging information of the required type.

Description

This method can only be used after solving an LP problem. Ranging information for MIP
problems can be obtained by fixing all discrete variables to their solution values andre-solving the resulting LP problem.

Fair Isaac Corporation Confidential and Proprietary Information

227

BCL in C++

ExampleThe following example displays the constraint activity and the activity range.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);...

// Solve the problem

cout << "C1: " << Ctr1.getAct() << " (activity range: ";cout << Ctr1.getRNG(XPRB_LOACT) << ", " ;cout << Ctr1.getRNG(XPRB_UPACT) << ")" << endl;
Related topics

Calls XPRBgetctrrng

getRowNum
Synopsis
int getRowNum();
Return value

Row number (non-negative value), or a negative value.

Description

This method returns the matrix row number of a constraint. If the matrix has not yet
been generated or the constraint is not part of the matrix (constraint type XPRB_N or nonon-zero terms) then the return value is negative. To check whether the matrix has been
generated, use method XPRBprob.getProbStat. The counting of row numbers starts with0.

ExampleSee XPRBctr.getAct.

Related topics

Calls XPRBgetrownum

getSize
Synopsis
int getSize();
Return value

Size (= number of linear or quadratic terms with a non-zero coefficient) of theconstraint, or -1 in case of an error.

Description

This method returns the size of a constraint (or -1 in case of an error).

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBgetctrsize

Fair Isaac Corporation Confidential and Proprietary Information

228

BCL in C++

getSlack
Synopsisdouble getSlack();
Return value

Slack value for the constraint, 0 in case of an error.

Description

This method returns the slack value for a constraint. The user may wish to test firstwhether this constraint is part of the problem, for instance by checking that the row
number is non-negative.
If this function is called after completion of a global search and an integer solution has
been found (that is, if method XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION
or XPRB_MIP_OPTIMAL), it returns the value in the best integer solution. If no integer
solution is available after a global search this function outputs a warning and returns 0.
In all other cases it returns the slack value in the last LP that has been solved. If thisfunction is used during the execution of an optimization process (for instance in
Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync
with the flag XPRB_XPRS_SOL.

ExampleSee XPRBctr.getAct.

Related topics

Calls XPRBgetslack

getType
Synopsis
int getType();’less than or equal to’ inequality;’greater than or equal to’ inequality;
equality;a non-binding row (objective function);a range constraint;
an error has occurred.

Return value

XPRB_L
XPRB_G
XPRB_E
XPRB_N
XPRB_R-1

Description

This method returns the constraint type if successful, and -1 in case of an error.

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBgetctrtype

isDelayed
Synopsisbool isDelayed();Return value

true if constraint is delayed constraint, false otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

229

BCL in C++

Description

This method indicates whether the given constraint is a delayed or an ordinary
constraint.

Related topics

Calls XPRBgetdelayed

isIncludeVars
Synopsisbool isIncludeVars();
Return value

true if constraint is an include vars special constraint, false otherwise.

Description

This method indicates whether the given constraint is an include varsspecial constraint
or an ordinary constraint.

Related topics

Calls XPRBgetincvars

isIndicator
Synopsisbool isIndicator();Return value

true if constraint is an indicator constraint, false otherwise.

Description

This method indicates whether the given constraint is an indicator or an ordinary
constraint.

Related topics

Calls XPRBgetindicator

isModCut
Synopsisbool isModCut();
Return value

true if constraint is a model cut, false otherwise.

Description

This method indicates whether the given constraint is a model cut or an ordinary
constraint.

Related topics

Calls XPRBgetmodcut

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

230

BCL in C++

Description

This method checks whether the constraint object is correctly defined. It should always
be used to test the result returned by XPRBprob.getCtrByName.

ExampleSee XPRBprob.getCtrByName.

nextTerm
Synopsisconst void *nextTerm(const void *ref, XPRBvar& var, double *coeff);const void *nextTerm(const void *ref, XPRBvar& var, XPRBvar& v2, double *coeff);
Reference pointer or NULL.
A BCL variable.
A second BCL variable (for enumeration of quadratic terms).
Coefficient associated to current term.

Arguments

ref
var
v2
coeff

Return value

Reference pointer for the next call to nextTerm or NULL if there are no more terms.

Description

These methods are used to enumerate the linear or quadratic terms of a constraint. The
first parameter ref serves to keep track of the current location in the enumeration; if
this parameter is NULL, the first term is returned. This function returns NULL if it is calledwith the reference to the last element. Otherwise, the returned value can be used as the
input parameter ref to retrieve the following term of the same type.

ExampleThe following example shows how to enumerate and display the linear terms of aconstraint.
XPRBprob prob("myprob");
XPRBctr Ctr1;...
XPRBvar var;
double coeff;
const void *ref = NULL;
while ((ref = Ctr1.nextTerm(ref, var, &coeff)) != NULL) {cout << " var " << var.getName() << " has coeff " << coeff << endl;}

Related topics

Calls XPRBgetnextterm or XPRBgetnextqterm

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out a constraint in LP format. It is not available in the student
version.

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBprintctr

Fair Isaac Corporation Confidential and Proprietary Information

231

BCL in C++

reset
Synopsisvoid reset();Clear the definition of the constraint object.

Description

setDelayed
Synopsis
int setDelayed(bool dstat);
The constraint type, which must be one of:
false
ordinary constraint;
true
delayed constraint.

Argument

dstat

Return value

0 if method executed successfully, 1 otherwise.

Description

1. This method changes the type of a previously defined constraint from ordinary
constraint to delayed constraint and vice versa. Delayed or ’lazy’ constraints must be
satisfied for any integer solution, but will not be loaded into the active set of constraints
until required.
2. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator
constraint’ are mutually exclusive. When changing from one of these types to another
you must first reset the correponding type to 0.

ExampleThe following example turns the constraint Ctr3 into a delayed constraint.
XPRBvar y,b;
XPRBctr Ctr3;
XPRBprob prob("myprob");
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Ctr3 = prob.newCtr("C3", y >= 50*b);
Ctr3.setDelayed(true);

Related topics

Calls XPRBsetdelayed

setIncludeVars
Synopsis
int setIncludeVars(bool ivstat);Argument

ivstat

The constraint type, which must be one of:
false
ordinary constraint;
true
include vars special constraint.

Fair Isaac Corporation Confidential and Proprietary Information

232

BCL in C++

0 if method executed successfully, 1 otherwise.

Return value
Description

1. This method changes the type of a previously defined constraint from ordinary
constraint to an include vars special constraint and vice versa. Include vars constraints
are used to force the loading of all variables they contain into the Optimizer (even if
they don’t appear in any other constraint). Only constraints of type XPRB_N can bechanged into include vars constraints; the constraints themselves are not loaded into the
Optimizer (as all constraints of type XPRB_N), just the variables they contain are loaded.
The coefficients of the variables are also ignored as long as they are non-zero.
2. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator
constraint’ are mutually exclusive. When changing from one of these types to another
you must first reset the correponding type to 0.
The following example turns the constraint CtrIV into an include vars special constraint.

ExampleXPRBvar y,b;
XPRBctr CtrIV;
XPRBprob prob("myprob");
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
CtrIV = prob.newCtr("IncVars", b+y);
CtrIV.setIncludeVars(true);Calls XPRBsetincvars

Related topics

setIndicator
Synopsis
int setIndicator(ind dir, XPRBvar );Arguments

dirb
Return value
Description

The indicator type, which must be one of:0
ordinary constraint;-1
indicator constraint with condition b = 0;1
indicator constraint with condition b = 1.
previously created binary variable.

0 if method executed successfully, 1 otherwise.
1. This method changes the type of a previously defined constraint from ordinary
constraint to indicator constraint and vice versa. Indicator constraints are defined byassociating a binary variable and an implication sense with a linear inequality or range
constraint.
2. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator
constraint’ are mutually exclusive. When changing from one of these types to another
you must first reset the correponding type to 0.

ExampleThe following example turns the constraint Ctr3 into the indicator constraint
b = 1 ⇒ Ctr3.
XPRBvar y,b;
XPRBctr Ctr3;

Fair Isaac Corporation Confidential and Proprietary Information

233

BCL in C++

XPRBprob prob("myprob");
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Ctr3 = prob.newCtr("C3", y >= 50);
Ctr3.setIndicator(1, b);
if (Ctr3.isIndicator())
cout << Ctr3.getIndVar().getName() << "->" << Ctr3.getName() << endl;
Calls XPRBsetindicator

Related topics

setModCut
Synopsis
int setModCut(bool mstat);
The constraint type, which must be one of:
false
constraint;
true
model cut.

Argument

mstat

Return value

0 if method executed successfully, 1 otherwise.

Description

1. This method changes the type of a previously defined constraint from ordinary
constraint to model cut and vice versa.
2. Model cuts must be ’true’ cuts, in the sense that they are redundant at the optimal MIP
solution. The Optimizer does not guarantee to add all violated model cuts, so they mustnot be required to define the optimal MIP solution.
3. Constraint properties ’include vars’, ’model cut’, ’delayed constraint’, and ’indicator
constraint’ are mutually exclusive. When changing from one of these types to another
you must first reset the correponding type to 0.

ExampleThe following example turns the constraint Ctr3 into a model cut.
XPRBvar y,b;
XPRBctr Ctr3;
XPRBprob prob("myprob");
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Ctr3 = prob.newCtr("C3", y >= 50*b);
Ctr3.setModCut(true);

Related topics

Calls XPRBsetmodcut

setRange
Synopsis
int setRange(double lw, double up);Fair Isaac Corporation Confidential and Proprietary Information

234

BCL in C++

Lower bound on the range constraint.
Upper bound on the range constraint.

Arguments

lw
up

Return value

0 if method executed successfully, 1 otherwise.

Description

This method changes the type of a constraint to a range constraint within the bounds
specified by lw and up. The constraint type and right hand side value of the constraint
are replaced by the type XPRB_R (range) and the two bounds.

ExampleThe following example defines a constraint with the range bounds 100 and 500, adds 5
to the range bounds and prints them out. The constraint is then changed to an
inequality constraint whereby the upper range bound is transformed into the righthand side. The output printed by this example is displayed in the commentaries.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);
Ctr1.setRange(100,500);
Ctr1.addTerm(5);if (Ctr1.getType() == XPRB_R){
cout << "C1 in [" << Ctr1.getRangeL() << ",";
cout << Ctr1.getRangeU() << "]" << endl;// C1 in [105,505]
cout << "C1 size: " << Ctr1.getSize() << endl;// C1 size: 2
Ctr1.setType(XPRB_G);
Ctr1.print();// C1: 3*x + 2*y >= 505}

Related topics

Calls XPRBsetrange

setTerm
Synopsis
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(double val);
int setTerm(XPRBvar& var, XPRBvar& var2, double val);
int setTerm(double val, XPRBvar& var, XPRBvar& var2);
A BCL variable.
A second BCL variable (may be the same as var).
Value of the coefficient of the variable var.

Arguments

var
var2
val

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets the coefficient of a variable (or of the product of the two given
variables) to the value val. If no variable is specified, the right hand side of theconstraint is set to val.

Fair Isaac Corporation Confidential and Proprietary Information

235

BCL in C++

ExampleThis example sets the coefficient of variable y in constraint Ctr1 to 5 and then adds a
linear expression and a constant term. The commentaries show the constraint
definitions resulting from the modifications. Please notice in particular the different
behavior of add and addTerm for the addition of constants.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);
Ctr1.setTerm(5, y);// C1: 3*x + 5*y <= 400
Ctr1.add(x+10);// C1: 4*x + 5*y <= 390
Ctr1.setTerm(400);// C1: 4*x + 5*y <= 400
Ctr1.addTerm(5);// C1: 4*x + 5*y <= 405
cout << "Coefficient of x in " << Ctr1.getName() << ": ";cout << Ctr1.getCoefficient(x) << endl;
cout << "Coefficient of x*y in " << Ctr1.getName() << ": ";cout << Ctr1.getCoefficient(x,y) << endl;

Related topics

Calls XPRBsetterm or XPRBsetqterm

setType
Synopsis
int setType(int type);
The constraint type, which must be one of:
XPRB_L’less than or equal to’ constraint;
XPRB_G’greater than or equal to’ constraint;
XPRB_Ean equality;
XPRB_Na non-binding row (objective function).

Argument

type

Return value

0 if method executed successfully, 1 otherwise.

Description

This method changes the type of a previously defined constraint to inequality, equation
or non-binding. Method XPRBctr.setRange has to be used for changing the constraint
to a ranged constraint. If a ranged constraint is changed back to some other type withthis method, its upper bound becomes the right hand side value.

ExampleSee XPRBctr.setRange.

Related topics

Calls XPRBsetctrtype

Fair Isaac Corporation Confidential and Proprietary Information

236

BCL in C++

XPRBcut
Description
Methods for modifying and accessing cuts and operators for constructing them. Note that all
terms in a cut must belong to the same problem as the cut itself.
Constructors
XPRBcut();
XPRBcut(xbcut *c);
XPRBcut(xbcut *c, XPRBrelation& r);
Methods

int add(XPRBexpr& le);Add a linear expression to a cut.
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
Add a term to a cut.
int delTerm(XPRBvar& var);
Delete a term from a cut.
xbcut *getCRef();
Get the C modeling object.
int getID();
Get the classification or identification number of a cut.
double getRHS();Get the RHS value of a cut.
int getType();Get the type of a cut.
bool isValid();
Test the validity of the cut object.
int print();
Print out a cut.
void reset();Reset the cut object.
int setID(int id);
Set the classification or identification number of a cut.
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(XPRBvar& var);
int setTerm(double val);
Set a cut term.
int setType(int type);
Set the type of a cut.

Operators
Assigning cuts and adding linear expressions:cut = linrel
cut += linexp
cut -= linexp

Fair Isaac Corporation Confidential and Proprietary Information

237

BCL in C++

Constructor detail

XPRBcut
SynopsisArguments

Description

XPRBcut();
XPRBcut(xbcut *c);
XPRBcut(xbcut *c, XPRBrelation& r);c
A cut in BCL C.
r
Linear relation defining the cut.
Create a new cut object.

Method detail

add
Synopsis
int add(XPRBexpr& le);A linear expression (may be a single variable or a constant).

ArgumentleReturn value

0 if method executed successfully, 1 otherwise.

Description

This method adds a linear expression to a cut. That means, if the linear expression
contains a constant, this value is subtracted from the constant representing the righthand side of the cut.

ExampleThis example defines a cut and then modifies its definition by adding a terms andchanging the coefficient of a variable. The resulting cut definitions (as displayed by
XPRBcut.print) are shown as comments. Please notice in particular the different
behavior of add and addTerm for the addition of constants.
XPRBvar x,y,b;
XPRBcut Cut2;
XPRBprob prob("myprob");x = prob.newVar("y", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Cut2 = prob.newCut(y <= 100*b, 1);
Cut2.add(x+2);// x + y - 100*b <= -2
Cut2.delTerm(x);//y - 100*b <= -2
Cut2.setTerm(0);//y - 100*b <= 0
Cut2 += x+2;// x + y - 100*b <= -2
Cut2.addTerm(2);// x + y - 100*b <= 0
Cut2.setTerm(y, -5);// x - 5*y - 100*b <= 0

Fair Isaac Corporation Confidential and Proprietary Information

238

BCL in C++

addTerm
Synopsis
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);A BCL variable.
Value of the coefficient of the variable var.

Arguments

var
val

Return value

0 if method executed successfully, 1 otherwise.

Description

This method adds a new term to a cut, comprising the variable var with coefficient val.
If the cut already has a term with variable var, val is added to its coefficient. If novariable is specified, the value val is added to the right hand side of the cut. Cut terms
can also be added with method XPRBcut.add.

ExampleSee XPRBcut.add.

Related topics

Calls XPRBaddcutterm

delTerm
Synopsisint delTerm(XPRBvar& var);
A BCL variable.

Argumentvar

Return value

0 if method executed successfully, 1 otherwise.

Description

This method removes a variable term from a cut. The constant term (right hand sidevalue) is changed/reset with method XPRBcut.setTerm.

ExampleSee XPRBcut.add.

Related topics

Calls XPRBdelcutterm

getCRef
Synopsisxbcut *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the cut object in BCL C that belongs to the C++ cut object.

Fair Isaac Corporation Confidential and Proprietary Information

239

BCL in C++

getID
Synopsis
int getID();
Return value

Classification or identification number.

Description

This method returns the classification or identification number of a cut.

ExampleSee XPRBcut.setID.

Related topics

Calls XPRBgetcutid

getRHS
Synopsisdouble getRHS();
Return value

Right hand side (RHS) value (default 0).

Description

This method returns the RHS value (= constant term) of a previously defined cut. The
default RHS value is 0.

Related topics

Calls XPRBgetcutrhs

getType
Synopsis
int getType();≤ (inequality)≥ (inequality)= (equation)
An error has occurred,

Return value

XPRB_L
XPRB_G
XPRB_E-1

Description

This method returns the type of the given cut.

Related topics

Calls XPRBgetcuttype

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Description

This method checks whether the cut object is correctly defined.

Fair Isaac Corporation Confidential and Proprietary Information

240

BCL in C++

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This function prints out a cut in LP format. It is not available in the student version.

ExampleSee XPRBcut.setID.

Related topics

Calls XPRBprintcut

reset
Synopsisvoid reset();Description

Clear the definition of the cut object.

setID
Synopsis
int setID(int id);
Classification or identification number.

Argument

id

Return value

0 if method executed successfully, 1 otherwise.

Description

This function changes the classification or identification number of a previously defined
cut. This change does not have any effect on the cut definition in Xpress Optimizer if
the cut has already been added to the matrix with XPRBprob.addCuts.

ExampleThis example defines a cut and then modifies its ID and relation type. The resulting
output is shown in the comment.
XPRBvar y,b;
XPRBcut Cut1;
XPRBprob prob("myprob");
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Cut1 = prob.newCut(y == 100*b);
Cut1.setID(1);if (Cut1.getID()>0) Cut1.setType(XPRB_G);
Cut1.print();// CUT(1): y - 100*b >= 0

Related topics

Calls XPRBsetcutid

Fair Isaac Corporation Confidential and Proprietary Information

241

BCL in C++

setTerm
Synopsis
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(XPRBvar& var);
int setTerm(double val);A BCL variable.
Value of the coefficient of the variable var.

Arguments

var
val

Return value

0 if method executed successfully, 1 otherwise.

Description

This function sets the coefficient of a variable to the value val. If no variable is specified,
the right hand side of the cut is set to val.

ExampleSee XPRBcut.add.

Related topics

Calls XPRBsetcutterm

setType
Synopsis
int setType(int type);
Type of the cut:
XPRB_L≤ (inequality)
XPRB_G≥ (inequality)
XPRB_E= (equation)

Argument

type

Return value

0 if method executed successfully, 1 otherwise.

Description

This function changes the type of the given cut. This change does not have any effect on
the cut definition in Xpress Optimizer if the cut has already been added to the matrix
with the method XPRBprob.addCuts.

ExampleSee XPRBcut.setID.

Related topics

Calls XPRBsetcuttype

Fair Isaac Corporation Confidential and Proprietary Information

242

BCL in C++

XPRBexpr
Description
Methods and operators for constructing linear and quadratic expressions. Note that all variables
in an expression must belong to the same problem.
Constructors
XPRBexpr(double d);
XPRBexpr(int i);
XPRBexpr(double d, XPRBvar& v);
XPRBexpr(double d, XPRBvar& v, XPRBvar& v2);
XPRBexpr(XPRBvar& v);
XPRBexpr(XPRBexpr& e);
Methods

XPRBexpr& add(XPRBexpr& e);
XPRBexpr& add(XPRBvar& v);
Addition to an expression
int addTerm(XPRBvar& var, XPRBvar& var2, double val);
int addTerm(double val, XPRBvar& var, XPRBvar& var2);
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
Add a term to an expression.
XPRBexpr& assign(XPRBexpr& e);
Copy an expression.
int delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);
Delete a term from an expression.
double getSol();Get evaluation of an expression.
XPRBexpr& mul(double d);
XPRBexpr& mul(XPRBexpr& e);Multiply an expression by a constant factor or an expression.
XPRBexpr& neg();
Negation of an expression.
int setTerm(XPRBvar& var, XPRBvar& var2, double val);
int setTerm(double val, XPRBvar& var, XPRBvar& var2);
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(double val);
Set a term in an expression.

Operators
Assigning (elements to) expressions:expr1 += expr2
expr1 -= expr2
expr1 = expr2
Composing expressions from other quadratic and linear expressions (expr), variables (var) andFair Isaac Corporation Confidential and Proprietary Information

243

BCL in C++

double values (val). The following operators are defined:- var- exprexpr1 + expr2
expr1 - expr2
expr * val
val * expr
var * val
val * var
var * val
var * expr
Throws exception ‘Non-quadratic expression’ if the result of the operation is notquadratic
expr * var
Throws exception ‘Non-quadratic expression’ if the result of the operation is notquadratic
expr1 * expr2
Throws exception ‘Non-quadratic expression’ if the result of the operation is notquadratic
Functions outside any class definition that generate quadratic expressions:
XPRBexpr sqr(XPRBexpr& e);
XPRBexpr sqr(XPRBvar& var);
Square of an expression or variable.

Constructor detail

XPRBexpr
SynopsisArguments

Description

XPRBexpr(double d);
XPRBexpr(int i);
XPRBexpr(double d, XPRBvar& v);
XPRBexpr(double d, XPRBvar& v, XPRBvar& v2);
XPRBexpr(XPRBvar& v);
XPRBexpr(XPRBexpr& e);dA real value.
i
An integer value.
v,v2
BCL variables (may be the same).
e
A linear or quadratic expression.
Create a new expression.

Method detail

Fair Isaac Corporation Confidential and Proprietary Information

244

BCL in C++

add
Synopsis
XPRBexpr& add(XPRBexpr& e);
XPRBexpr& add(XPRBvar& v);
A linear or quadratic expression (may be just a constant).
A BCL variable.

Argumentsev

Return value

The modified expression.

Description

This method adds an expression / constant / variable to the linear or quadratic
expression it is applied to.

ExampleSee XPRBexpr.setTerm.

addTerm
Synopsis
int addTerm(XPRBvar& var, XPRBvar& var2, double val);
int addTerm(double val, XPRBvar& var, XPRBvar& var2);
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
BCL decision variables (may be the same).
A real value (coefficient).

Arguments

var,var2
val

Return value

The modified expression.

Description

This method adds a new term to an expression comprising the variable var (or the
product of variables var and var2) with coefficient val. If the expression already has aterm with variable var (respectively variables var and var2), val is added to its
coefficient. If no variable is specified, the value val is added to the constant term of theexpression. Terms can also be added with method XPRBexpr.add.

ExampleSee XPRBexpr.setTerm.

assignSynopsis
XPRBexpr& assign(XPRBexpr& e);
Expression to be copied.

Argumente

Return value

Copy of the expression in the argument.

Description

This method copies the given expression.

Fair Isaac Corporation Confidential and Proprietary Information

245

BCL in C++

delTerm
Synopsisint delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);
BCL decision variables (may be the same).

Argument

var,var2

Return value

The modified expression.

Description

This function deletes a variable term from an expression. The constant term is changed
or reset with method XPRBexpr.setTerm.

ExampleSee XPRBexpr.setTerm.

getSolSynopsisdouble getSol();
Return value

Evaluation of the expression with the last solution.

Description

This method returns the evaluation of an expression with the solution values from thelast solution found. If this method is called after completion of a global search and an
integer solution has been found (that is, if method XPRBprob.getMIPStat returns values
XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), it returns the value corresponding to the best
integer solution. If no integer solution is available after a global search this method
outputs a warning and returns 0. In all other cases it returns the evaluation
corresponding to the last LP that has been solved. If this method is used during theexecution of an optimization process (for instance in Optimizer library callback
functions) it needs to be preceded by a call to XPRBprob.sync with the flag
XPRB_XPRS_SOL.

mul
Synopsis
XPRBexpr& mul(double d);
XPRBexpr& mul(XPRBexpr& e);
A constant.
An expression (may be just a constant or a single decision variable).

Argumentsde

Return value

The modified expression.

Error handlingArithmeticException ‘Non-quadratic expression’ if the result of the operation is notquadratic.

Description

This method multiplies an expression by a constant factor or another expression. This
operation succeeds if one of the expressions is just a constant or if both expressions have
only linear terms.

ExampleSee XPRBexpr.setTerm.

Fair Isaac Corporation Confidential and Proprietary Information

246

BCL in C++

neg
Synopsis
XPRBexpr& neg();
Return value

Negation of the expression.

Description

This method multiplies an expression with -1.

ExampleSee XPRBexpr.setTerm.

setTerm
Synopsis
int setTerm(XPRBvar& var, XPRBvar& var2, double val);
int setTerm(double val, XPRBvar& var, XPRBvar& var2);
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(double val);
BCL decision variables (may be the same).
A real value (coefficient).

Arguments

var,var2
val

Return value

The modified expression.

Description

This method sets the coefficient of a variable or of the product of the two specified
variables to the value val. If no variable is specified, the constant term of the expression
is set to val.

ExampleThis example shows different ways of defining and modifying a quadratic expression
and finally sets the resulting expression as objective function. The comments display thedefinition of qe after each modification.
XPRBvar x,y;
XPRBexpr qe;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
qe = x;qe.mul(3*x);
qe += x*2*y;qe.add(1);qe.setTerm(3, x);qe.setTerm(0, x, y);qe.delTerm(x, x);qe.setTerm(-1);
qe.addTerm(2, x);qe -= 3*sqr(3*y);qe.neg();

//
//
//
//
//
//
//
//
//
//
//

x
3*x^2
3*x^2 + 2*x*y
1 + 3*x^2 + 2*x*y
1 + 3*x + 3*x^2 + 2*x*y
1 + 3*x + 3*x^2
1 + 3*x- 1 + 3*x
- 1 + 5*x
- 1 + 5*x - 27*y^2
1 - 5*x + 27*y^2

prob.setObj(qe);Fair Isaac Corporation Confidential and Proprietary Information

247

BCL in C++

sqr
Synopsis
XPRBexpr sqr(XPRBexpr& e);
XPRBexpr sqr(XPRBvar& var);
An expression.
A BCL decision variable.

Argumentsevar

Return value

The square of the variable or expression in the argument.

Description

This function returns the square of the variable or expression passed in the argument if
the result is at most quadratic.

ExampleSee XPRBexpr.setTerm.

Fair Isaac Corporation Confidential and Proprietary Information

248

BCL in C++

XPRBindexSet
Description
Methods for accessing index sets and operators for adding and retrieving set elements.
Constructors
XPRBindexSet();
XPRBindexSet(xbidxset *iset);
Methods

int addElement(const char *text);
Add an index to an index set.
xbidxset *getCRef();
Get the C modeling object.
int getIndex(const char *text);
Get the index number of an index.
const char *getIndexName(int i);
Get the name of an index.
const char *getName();Get the name of an index set.
int getSize();Get the size of an index set.
bool isValid();
Test the validity of the index set object.
int print();
Print out an index set
void reset();Reset the index set object.

Operators
Adding an element to an index set:
iset += text
Accessing index set elements by their name or index number:
int iset[text]
const char *iset[val]Constructor detail

XPRBindexSet
SynopsisArgument

XPRBindexSet();
XPRBindexSet(xbidxset *iset);iset
An index set in BCL C.

Description

Create a new index set object.

Method detail

Fair Isaac Corporation Confidential and Proprietary Information

249

BCL in C++

addElement
Synopsis
int addElement(const char *text);
Name of the index to be added to the set.

Argumenttext

Return value

Sequence number of the index within the set, -1 in case of an error.

Description

This method adds an index entry to an index set. The new element is only added to theset if no identical index already exists. Both in the case of a new index entry and an
existing one, the method returns the sequence number of the index in the index set.
Note that the numbering of index elements starts with 0.

ExampleThe following example shows how to add an element to an index set and then retrieve
its index and its name, (a) using the corresponding functions and (b) using theoverloaded operators of this class.
XPRBprob prob("myprob");
XPRBindexSet ISet;
int ind;
ISet = prob.newIndexSet("IS");ind = ISet.addElement("a");cout << "First element: " << ISet.getIndexName(ind);cout << ", index of ’a’: " << ISet.getIndex("a") << endl;
ISet += "b";// Add a second elementcout << "Element 1: " << ISet[1];cout << ", index of ’b’: " << ISet["b"] << endl;

Related topics

Calls XPRBaddidxel

getCRef
Synopsisxbidxset *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the index set object in BCL C that belongs to the C++ index set
object.

getIndex
Synopsis
int getIndex(const char *text);
Argumenttext

Name of an index in the set.

Fair Isaac Corporation Confidential and Proprietary Information

250

BCL in C++

Return value

Sequence number of the index in the set, or -1 if not contained.

Description

An index element can be accessed either by its name or by its sequence number. Thismethod returns the sequence number of an index given its name.

ExampleSee XPRBindexSet.addElement.

Related topics

Calls XPRBgetidxel

getIndexName
Synopsisconst char *getIndexName(int i);
Index number.

Argumenti

Return value

Name of the ith element in the set if function executed successfully, NULL otherwise.

Description

An index element can be accessed either by its name or by its sequence number. Thismethod returns the name of an index set element given its sequence number.

ExampleSee XPRBindexSet.addElement.

Related topics

Calls XPRBgetidxelname

getName
Synopsisconst char *getName();Return value

Name of the index set if function executed successfully, NULL otherwise.

Description

This function returns the name of an index set.

ExampleSee XPRBindexSet.getSize.

Related topics

Calls XPRBgetidxsetname

getSize
Synopsis
int getSize();
Return value

Size (= number of elements) of the set, -1 in case of an error.

Description

This function returns the current number of elements in an index set. This value does
not necessarily correspond to the size specified at the creation of the set. The returned
value may be smaller if fewer elements than the originally reserved number have been
added, or larger if more elements have been added. (In the latter case, the size of theset is automatically increased.)

ExampleThis example displays the name, size, and complete contents of an index set.

Fair Isaac Corporation Confidential and Proprietary Information

251

BCL in C++

XPRBprob prob("myprob");
XPRBindexSet ISet;
ISet = prob.newIndexSet("IS");cout << ISet.getName() << " size: " << ISet.getSize() << endl;
ISet.print();
Related topics

Calls XPRBgetidxsetsize

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Description

This method checks whether the index set object is correctly defined. It should always be
used to test the result returned by XPRBprob.getIndexSetByName.

ExampleSee XPRBprob.getIndexSetByName.

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out an index set. It is not available in the student version.

ExampleSee XPRBindexSet.getSize.

Related topics

Calls XPRBprintidxset

reset
Synopsisvoid reset();Description

Clear the definition of the index set object.

Fair Isaac Corporation Confidential and Proprietary Information

252

BCL in C++

XPRBprob
Description
Problem definition, including methods for creating and deleting the modeling objects, problem
solving, changing settings, and retrieving solution information.
Constructors
XPRBprob();
XPRBprob(const char *name);
Methods

int addCuts(XPRBcut *cuts, int num);
Add cuts to a problem.
int addMIPSol(XPRBsol& sol, const char *name);
int addMIPSol(XPRBsol& sol);
Add a new feasible, infeasible or partial MIP solution to the Optimizer.
int beginCB(XPRSprob oprob);
Start using the local optimizer problem with BCL in a callback.
void clearDir();
Delete all directives.
void delCtr(XPRBctr& ctr);
Delete a constraint.
void delCut(XPRBcut& cut);
Delete a cut definition.
void delSos(XPRBsos& sos);Delete a SOS.
int endCB();
Reset BCL to the original optimizer problem in a callback.
int exportProb(int format, const char *filename);
int exportProb(int format);
Print problem matrix to a file.
int fixGlobals(int ifround = 1);
Fixes all the global entities to the values of the last found MIP solution.
xbprob *getCRef();
Get the C modeling object.
XPRBctr getCtrByName(const char *name);
Retrieve a constraint by its name.
XPRBindexSet getIndexSetByName(const char *name);
Retrieve an index set by its name.
int getLPStat();
Get the LP status.
int getMIPStat();
Get the MIP status.
const char *getName();Get the name of the problem.
int getNumIIS();Get the number of independent IIS in an infeasible LP problem.
double getObjVal();Get the objective function value.
int getProbStat();
Get the problem status.

Fair Isaac Corporation Confidential and Proprietary Information

253

BCL in C++

int getSense();Get the sense of the optimization.
XPRBsos getSosByName(const char *name);
Retrieve a SOS by its name.
XPRBvar getVarByName(const char *name);
Retrieve a variable by its name.
XPRSprob getXPRSprob();
Returns an XPRSprob problem reference for a problem defined in BCL.
int loadBasis(const XPRBbasis& bas);
Load a previously saved basis.
int loadMat();Load the problem into the optimizer.
int loadMIPSol(double *sol, int ncol, bool ifopt);
int loadMIPSol(double *sol, int ncol);Load an integer solution into BCL or the Optimizer.
int lpOptimize(const char *alg);
int lpOptimize();
Solve as a continuous problem.
int mipOptimize(const char *alg);
int mipOptimize();
Solve as a discrete problem.
bool nextCtr(XPRBctr& ref);Enumerate constraints.
XPRBctr newCtr(const char *name, XPRBrelation& ac);
XPRBctr newCtr(const char *name);
XPRBctr newCtr(XPRBrelation& ac);
XPRBctr newCtr();Create a new constraint.
XPRBcut newCut(int id);
XPRBcut newCut(XPRBrelation& ac);
XPRBcut newCut(XPRBrelation& ac, int id);
XPRBcut newCut();
Create a new cut.
XPRBindexSet newIndexSet();
XPRBindexSet newIndexSet(const char *name);
XPRBindexSet newIndexSet(const char *name, int maxsize);
Create a new index set.
XPRBsol newSol();Create a solution.
XPRBsos newSos(int type);
XPRBsos newSos(const char *name, int type);
XPRBsos newSos(int type, XPRBexpr& le);XPRBsos newSos(const char *name, int type, XPRBexpr& le);Create a SOS.
XPRBvar newVar(const char *name, int type, double lob, double upb);
XPRBvar newVar(const char *name, int type);
XPRBvar newVar(const char *name);

Fair Isaac Corporation Confidential and Proprietary Information

254

BCL in C++

XPRBvar newVar();Create a decision variable.
int print();
Print out the problem.
int printObj();
Print out the objective function of a problem.
int readBinSol(const char *filename = NULL, const char *flags = "");
>Read a solution from a binary solution file (.sol), loading it into the Optimizer.
int readSlxSol(const char *filename = NULL, const char *flags = "");
>Read a solution from an ASCII solution file (.slx), loading it into the Optimizer.
int reset();Release system resources used for storing solution information.
XPRBbasis saveBasis();Save the current basis.
int setColOrder(int num);Set a column ordering criterion for matrix generation.
int setCutMode(int mode);
Set the cut mode.
int setDictionarySize(int dict, int size);
Set the size of a dictionary.
int setMsgLevel(int lev);Set the message print level.
int setObj(XPRBctr ctr);
int setObj(XPRBexpr e);
int setObj(XPRBvar v);
Select the objective function.
int setName(const char *name);
Set the name of the problem.
int setRealFmt(const char *fmt);
Set the format for printing real numbers.
int setSense(int dir);
Set the sense of the optimization.
int sync(int synctype);
Synchronize BCL with the Optimizer.
int writeDir();
int writeDir(const char *filename);
Write directives to a file.
int writeSol(const char *filename = NULL, const char *flags = "");
>Write the current Optimizer solution to a CSV format ASCII file, problem_name.asc (and.hdr).
int writeBinSol(const char *filename = NULL, const char *flags = "");
>Write the current Optimizer solution to a binary solution file for later input into the
Optimizer.
int writePrtSol(const char *filename = NULL, const char *flags = "");
>Write the current Optimizer solution to a fixed format ASCII file, problem_name .prt.
int writeSlxSol(const char *filename = NULL, const char *flags = "");
>Write the current Optimizer solution to an ASCII solution file (.slx) using a similar format
to MPS files.

Fair Isaac Corporation Confidential and Proprietary Information

255

BCL in C++

Constructor detail

XPRBprob
Synopsis
XPRBprob();
XPRBprob(const char *name);
name
The problem name. If none specified, BCL creates a unique name.

Argument
Description

1. This method needs to be called to create and initialize a new problem. If BCL has notbeen initialized previously this method also initializes BCL and Xpress Optimizer. The
initialization / problem creation fails if no valid license is found.
2. When solving several instances of a problem simultaneously the user must make sure toassign a different name to every instance.

Related topics

Calls XPRBnewprob

Method detail

addCuts
Synopsis
int addCuts(XPRBcut *cuts, int num);Array of previously defined cuts.
Number of cuts in cuts.

Arguments

cuts
num

Return value

0 if method executed successfully, 1 otherwise.

Description

This function adds previously defined cuts to the problem in Xpress Optimizer. It may
only be called from within the Xpress Optimizer cut manager callback functions. BCL
does not check for doubles, that is, if the user defines the same cut twice it will be
added twice to the matrix. Cuts added at a node during the branch and bound searchremain valid for all child nodes but are removed at all other nodes.

ExampleThis example shows how to define the cut manager callback and add a cut to the
Optimizer problem. The function call adding the cut is surrounded by the pair
XPRBprob.beginCB and XPRBprob.endCB to coordinate BCL with the local Optimizer
subproblem in the case of a multi-threaded MIP search.
int XPRS_CC cbNode(XPRSprob oprob, void *bp){
XPRBprob *bprob = (XPRBprob*)bp;
XPRBcut aCut;
bprob->beginCB(oprob);...
// Define the cut ’aCut’
bprob->addCuts(&aCut, 1);

Fair Isaac Corporation Confidential and Proprietary Information

256

BCL in C++

bprob->endCB();
return 0;}// Call this function once per node

int main(int argc, char **argv){
XPRBprob prob("myprob");...
// Define the problem
prob.setCutMode(1);XPRSsetcbcutmgr(prob.getXPRSprob(), cbNode, &prob);prob.setSense(XPRB_MAXIM);
prob.mipOptimize();...
// Solution output}
Related topics

Calls XPRBaddcuts

addMIPSol
Synopsis
int addMIPSol(XPRBsol& sol, const char *name);
int addMIPSol(XPRBsol& sol);
A BCL solution.
An optional name to associate with the solution. Can be NULL.

Arguments

sol
name

Return value

0 if method executed successfully, 1 otherwise.

Description

1. If the matrix loaded in the Optimizer does not correspond to the current state of thespecified problem definition, it is regenerated automatically before adding the solution.
2. The XPRBprob.mipOptimize method by default resets problem status including eventual
loaded solutions; to avoid that, flag "c" should be specified for the alg argument of
XPRBprob.mipOptimize when called after XPRBprob.addMIPSol.
3. The function returns immediately after passing the solution to the Optimizer. The
solution is placed in a pool until the Optimizer is able to analyze the solution during a
MIP solve.
4. If the provided solution is partial or found to be infeasible, a limited local searchheuristic will be run in an attempt to find a close feasible integer solution. Values
provided for continuous columns in partial solutions are currently ignored.
5. The usersolnotify callback can be used to discover the outcome of a loaded solution. The
optional name provided as name will be returned in the callback.

ExampleAdd a MIP solution for problem prob to the Optimizer.
XPRBprob prob("myprob");
XPRBsol sol = prob.newSol();...
// Define + load the problem
prob.addMIPsol(sol, "myHeurSol");/* Request notification of solution status after processing */XPRSaddcbusersolnotify(prob.getXPRSprob(), solnotify_handler, &prob, 0);

Related topics

Calls XPRBaddmipsol

Fair Isaac Corporation Confidential and Proprietary Information

257

BCL in C++

beginCB
Synopsisint beginCB(XPRSprob oprob);
Reference to an Xpress Optimizer problem.

Argument

oprob

Return value

0 if method executed successfully, 1 otherwise.

Description

This function switches from the original problem to the specified (local) optimizer
problem for all BCL accesses to Xpress Optimizer (in particular, for solution updates andthe definition of cuts). A call to this function must precede any call to such BCL functionsin optimizer MIP callbacks when the default multi-threaded MIP search is used forsolving a problem. A call to beginCB must always be matched by a call to XPRBprob.endCB
to reset the optimizer problem within BCL and to release the BCL problem (access to the
BCL problem is locked to the particular thread in between the two function calls).

ExampleThe example shows how to set up the integer solution callback of Xpress Optimizer touse BCL to display the results.
void XPRS_CC printSol(XPRSprob oprob, void *my_object){
int num;
XPRBprob *bprob = (XPRBprob*)bp;
XPRBvar x;
XPRSgetintattrib(oprob, XPRS_MIPSOLS, &num);// Get number of the solution
bprob->beginCB(oprob); // Work with local optimizer problem
bprob->sync(XPRB_XPRS_SOL);// Update BCL solution values
cout << "Solution " << num << ": Objective value: ";cout << bprob->getObjVal() << endl;
x = bcl_prob->getVarByName("x_1");
cout << x.getName() << ": " << x.getSol() << endl;
bprob->endCB();}// Reset BCL to orig. optimizer problem

int main(int argc, char **argv){
XPRBprob prob("myprob");...
// Define the problem
XPRSsetcbintsol(prob.getXPRSprob(), printSol, &prob);prob.setSense(XPRB_MAXIM);
prob.mipOptimize();}
Related topics

Calls XPRBbegincb

Fair Isaac Corporation Confidential and Proprietary Information

258

BCL in C++

clearDir
Synopsisvoid clearDir();
Description

This method deletes all directives on decision variables and SOS defined for a problem.

ExampleThis example defines directives for a binary variable and a SOS, writes out the directives
to the file directout.dir and then deletes all directives.
XPRBvar b;
XPRBsos SO2;
XPRBprob prob("myprob");b = prob.newVar("b", XPRB_BV);
b.setDir(XPRB_UP);// Branch upwards firstSO2.setDir(XPRB_PR, 1);// Highest branching priority
prob.writeDir("directout");
prob.clearDir();

Related topics

Calls XPRBcleardirdelCtrSynopsisvoid delCtr(XPRBctr& ctr);
A BCL constraint.

Argument

ctr

Description

Delete a constraint from the given problem. If this constraint has previously been
selected as the objective function (using function XPRBprob.setObj), the objective will
be set to NULL. If the constraint occurs in a previously saved basis that is to be (re)loaded
later on you should change its type to XPRB_N using XPRBctr.setType instead of entirely
deleting the constraint.

Related topics

Calls XPRBdelctr

delCutSynopsisvoid delCut(XPRBcut& cut);A BCL cut.

Argument

cut

Description

This method deletes the definition of a cut in BCL, but not the cut itself if it has alreadybeen added to the problem held in Xpress Optimizer (using XPRBprob.addCuts).

ExampleSee XPRBprob.newCut.

Related topics

Calls XPRBdelcut

Fair Isaac Corporation Confidential and Proprietary Information

259

BCL in C++

delSosSynopsisvoid delSos(XPRBsos& sos);A previously defined SOS of type 1 or 2.

Argument

sos

Description

This method deletes a SOS without deleting the variables it consists of.

ExampleSee XPRBprob.newSos.

Related topics

Calls XPRBdelsos

endCB
Synopsis
int endCB();
Return value

0 if method executed successfully, 1 otherwise.

Description

This function switches back to the original optimizer problem for all BCL accesses toXpress Optimizer. A call to this function terminates a block of calls to BCL functions inan optimizer callback that is preceded by XPRBprob.beginCB. The call to XPRBprob.endCB
releases the BCL problem (access to the BCL problem is locked to the particular thread
between the two function calls).

ExampleSee XPRBprob.beginCB.

Related topics

Calls XPRBendcb

exportProb
Synopsis
int exportProb(int format, const char *filename);
int exportProb(int format);Arguments

formatfilename
Return value

The matrix output file format, which must be one of:
XPRB_LPLP file format (default);
XPRB_MPS
MPS file format.
Name of the output file, without extension.

0 if method executed successfully, 1 otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

260

BCL in C++

Description

1. This method prints the matrix to a file with an extended LP or extended MPS format. LP
files receive the extension .lp and MPS files receive the extension .mps. This function is
not available in the student version.
2. When exporting matrices semi-continuous and semi-continuous integer variables are
preprocessed: if a lower bound value greater than 0 is given, then the variable is treatedlike a continuous (resp. integer) variable.
3. The precision used by BCL for printing real numbers can be changed with
XPRB.setRealFmt to obtain more accurate output for very large or very small numbers.
For full precision matrix output the user is advised to switch to the Optimizer function
XPRSwriteprob, preceded by a call to XPRBprob.loadMat (see Appendix B for further
detail).

ExampleThe following sets the sense of the optimization to maximization before exporting the
problem matrix in LP format.
XPRBprob prob("myprob");prob.setSense(XPRB_MAXIM);
prob.exportProb(XPRB_LP);

Related topics

Calls XPRBexportprob

fixGlobals
Synopsis
int fixGlobals(int ifround = 1);
If all global entities should be rounded to the nearest discrete value in thesolution before being fixed.

Argument

ifroundReturn value

0 if method executed successfully, 1 otherwise.

Description

1. This is useful e.g. for finding the reduced costs for the continuous variables after the
global variables have been fixed to their optimal values. The global variables are fixed
to the value of the MIP solution only in the Optimizer (not in BCL).
2. In order to eventually resync the bounds of global variables to their original values
defined in BCL (i.e. unfix them), a call to XPRBsync with the flag XPRB_XPRS_PROB can be
used.

ExamplePerforms a global search on problem expl2 and then uses XPRBfixglobals before solving
the remaining linear problem:
XPRBprob prob("myprob");...
// Define + load the problem
prob.mipOptmize();prob.fixGlobals();prob.lpOptimize();

Related topics

Calls XPRBfixglobals

Fair Isaac Corporation Confidential and Proprietary Information

261

BCL in C++

getCRef
Synopsisxbprob *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the problem object in BCL C that belongs to the C++ problem
object.

getCtrByName
Synopsis
XPRBctr getCtrByName(const char *name);
The name of the constraint to find.

Argument

nameReturn value

A BCL constraint.

Description

This method always returns a BCL constraint the validity of which needs to be checkedwith XPRBctr.isValid. This method cannot be used if the names dictionary has been
disabled (see XPRBprob.setDictionarySize).

ExampleThe following retrieves a constraint by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBctr C2;
C2 = prob.getCtrByName("C2");
if (C2.isValid()) C2.print();

Related topics

Calls XPRBgetbyname

getIndexSetByName
Synopsis
XPRBindexSet getIndexSetByName(const char *name);
The name of the index set to find.

Argument

nameReturn value

A BCL index set.

Description

This method always returns a BCL index set the validity of which needs to be checkedwith XPRBindexSet.isValid. This method cannot be used if the names dictionary has
been disabled (see XPRBprob.setDictionarySize).

ExampleThe following retrieves an index by its name and if a set has been found prints it out.
XPRBprob prob("myprob");
XPRBindexSet I2;
I2 = prob.getIndexSetByName("IS");if (I2.isValid()) I2.print();

Related topics

Calls XPRBgetbyname

Fair Isaac Corporation Confidential and Proprietary Information

262

BCL in C++

getLPStat
Synopsis
int getLPStat();the problem has not been loaded, or error;
LP optimal;
LP infeasible;
the objective value is worse than the cutoff;
LP unfinished;
LP unbounded;
LP cutoff in dual.
LP problem is not solved.
QP problem is nonconvex.

Return value

0
XPRB_LP_OPTIMAL
XPRB_LP_INFEAS
XPRB_LP_CUTOFFXPRB_LP_UNFINISHED
XPRB_LP_UNBOUNDED
XPRB_LP_CUTOFF_IN_DUAL
XPRB_LP_UNSOLVED
XPRB_LP_NONCONVEX

Description

The return value of this method provides LP status information from the Xpress
Optimizer.

ExampleSee XPRBprob.mipOptimize, XPRBctr.getAct.

Related topics

Calls XPRBgetlpstat

getMIPStat
Synopsis
int getMIPStat();Return value

XPRB_MIP_NOT_LOADEDXPRB_MIP_LP_NOT_OPTIMAL
XPRB_MIP_LP_OPTIMAL
XPRB_MIP_NO_SOL_FOUNDXPRB_MIP_SOLUTIONXPRB_MIP_INFEAS
XPRB_MIP_OPTIMAL
XPRB_MIP_UNBOUNDED

problem has not been loaded, or error;
LP has not been optimized;
LP has been optimized;
global search incomplete — no integer solution found;global search incomplete, although an integer solution
has been found;global search complete, but no integer solution found;global search complete and an integer solution has
been found.
LP unbounded;

Description

This methods returns the global (MIP) status information from the Xpress Optimizer.

ExampleSee XPRBprob.mipOptimize.

Related topics

Calls XPRBgetmipstat

Fair Isaac Corporation Confidential and Proprietary Information

263

BCL in C++

getName
Synopsisconst char *getName();Return value

Name of the problem if function executed successfully, NULL otherwise.

Description

This method returns the problem name. If none was specified at the creation of the
problem, this is a unique name created by BCL.

Related topics

Calls XPRBgetprobname

getNumIIS
Synopsis
int getNumIIS();
Return value

Number of independent IIS found by Xpress Optimizer, or a negative value in case oferror.

Description

This function returns the number of independent IIS (irreducible infeasible sets) of an
infeasible LP problem.

Related topics

Calls XPRBgetnumiis

getObjVal
Synopsisdouble getObjVal();Return value

The current objective function value; default and error return value: 0.

Description

This method returns the current objective function value from the Xpress Optimizer. If it
is called after completion of a global search and an integer solution has been found(that is, if XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL),
it returns the value of the best integer solution. In all other cases, including during a
global search, it returns the solution value of the last LP that has been solved. If thisfunction is used during the execution of an optimization process (for instance in
Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync
with the flag XPRB_XPRS_SOL.

ExampleSee XPRBprob.mipOptimize.

Related topics

Calls XPRBgetobjval

getProbStat
Synopsis
int getProbStat();Fair Isaac Corporation Confidential and Proprietary Information

264

BCL in C++

Return value

Bit-encoded BCL status information:
XPRB_GEN the matrix has been generated;
XPRB_DIR directives have been added;
XPRB_MOD the problem has been modified;
XPRB_SOL the problem has been solved.

Description

This method returns the current BCL problem status. Note that the problem status uses
bit-encoding contrary to the LP and MIP status information, because several states may
apply at the same time.

ExampleSee XPRBprob.getXPRSprob.

Related topics

Calls XPRBgetprobstat

getSense
Synopsis
int getSense();the objective function is to be maximized;
the objective function is to be minimized;
an error has occurred.

Return value

XPRB_MAXIM
XPRB_MINIM-1

Description

This method returns the objective sense (maximization or minimization). The sense is set
to minimization by default and may be changed with XPRBprob.setSense,
XPRBprob.lpOptimize, and XPRBprob.mipOptimize.

Related topics

Calls XPRBgetsense

getSosByName
Synopsis
XPRBsos getSosByName(const char *name);
The name of the SOS to find.

Argument

nameReturn value

A BCL SOS.

Description

This method always returns a BCL SOS the validity of which needs to be checked with
XPRBsos.isValid. This method cannot be used if the names dictionary has been disabled(see XPRBprob.setDictionarySize).

ExampleThe following retrieves a SOS by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBsos S2;
S2 = prob.getSosByName("SO2");
if (S2.isValid()) S2.print();

Related topics

Calls XPRBgetbyname

Fair Isaac Corporation Confidential and Proprietary Information

265

BCL in C++

getVarByName
Synopsis
XPRBvar getVarByName(const char *name);
The name of the variable to find.

Argument

nameReturn value

A BCL variable.

Description

This method always returns a BCL variable the validity of which needs to be checkedwith XPRBvar.isValid. This method cannot be used if the names dictionary has been
disabled (see XPRBprob.setDictionarySize).

ExampleThe following retrieves a variable by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBvar b2;
b2 = prob.getVarByName("b");if (b2.isValid()){ b2.print(); cout << endl; }Related topics

Calls XPRBgetbyname

getXPRSprob
Synopsis
XPRSprob getXPRSprob();
Return value

Reference to a problem in Xpress Optimizer if executed successfully, NULL otherwise

Description

This method returns an XPRSprob problem reference for a problem defined in BCL andsubsequently loaded into the Xpress Optimizer. The optimizer problem may be different
from the problem loaded in BCL if the solution algorithms have not been called (and the
problem has not been loaded explicitly) after the last modifications to the problem in
BCL, or if any modifications have been carried out directly on the problem in the
optimizer. See Section B.6 for further detail.

ExampleThe following example shows how to change the setting of a control parameter of
Xpress Optimizer.
XPRBprob bclProb("myprob");
XPRSprob optProb;...
// Define the BCL problem
if ((prob.getProbStat()&XPRB_MOD) == XPRB_MOD)
optProb = bclProb.getXPRSprob();
XPRSsetintcontrol(optProb, XPRS_PRESOLVE, 0);

Related topics

prob.loadMat();

Calls XPRBgetXPRSprob

Fair Isaac Corporation Confidential and Proprietary Information

266

BCL in C++

loadBasis
Synopsis
int loadBasis(const XPRBbasis& bas);
A previously saved basis.

Argumentbas

Return value

0 if method executed successfully, 1 otherwise.

Description

This method loads a basis for the current problem. The basis must have been saved using
XPRBprob.saveBasis. It is not possible to load a basis saved for any other problem thanthe current one, even if the problems are similar. This function takes into account thatthe problem may have been modified since the basis has been stored (addition ofvariables and constraints is handled—deletion of constraints is not handled: instead ofentirely deleting a constraint, change its type to XPRB_N using XPRBctr.setType if you
wish to load the basis later on). For reading a basis from a file, the Optimizer libraryfunction XPRSreadbasis may be used. Note that the problem has to be loaded explicitly(method XPRBprob.loadMat) before the basis is re-input with XPRBprob.loadBasis.
Furthermore, if the reference to a basis is not used any more it should be deleted using
XPRBbasis.reset.

ExampleSee XPRBprob.saveBasis.

Related topics

Calls XPRBloadbasis

loadMatSynopsis
int loadMat();Return value

0 if method executed successfully, 1 otherwise.

Description

This method calls the Optimizer library functions XPRSloadlp, XPRSloadqp,
XPRSloadglobal, or XPRSloadqglobal to transform the current BCL problem definition
into a matrix in the Xpress Optimizer. Empty rows and columns are deleted before
generating the matrix. Semi-continuous (integer) variables are preprocessed: if a lower
bound value greater than 0 is given, then the variable is treated like a continuous (resp.
integer) variable. Variables that belong to the problem but do not appear in the matrix
receive negative column numbers. Usually, it is not necessary to call this function
explicitly because BCL automatically does this conversion whenever it is required. To
force matrix reloading, a call to this function needs to be preceded by a call to
XPRBprob.sync with the flag XPRB_XPRS_PROB.

ExampleSee XPRBprob.getXPRSprob.

Related topics

Calls XPRBloadmat

Fair Isaac Corporation Confidential and Proprietary Information

267

BCL in C++

loadMIPSol
Synopsis
int loadMIPSol(double *sol, int ncol, bool ifopt);
int loadMIPSol(double *sol, int ncol);Arguments

sol
ncol
ifopt

Return value

0
1
2
3
-1
-2
-3

Description

Array of size ncol holding the solution values.
Number of variables (continuous+discrete) in the problem.
Whether to load the solution into the Optimizer:
false
load into BCL only (default);
trueload solution into the Optimizer.
Solution accepted,
Solution rejected because it is infeasible,
Solution rejected because it is cut off,
Solution rejected because the LP reoptimization was interrupted,
Solution rejected because an error occurred,
The given solution array does not have the expected size,
Error loading solution into BCL.

1. This method loads a MIP solution from an external source (e.g., the Xpress MIP SolutionPool) into BCL or the Optimizer. The solution is given in the form of an array, indexed by
the column numbers of the decision variables. The size ncol of the array mustcorrespond to the number of columns in the matrix (generated by a call to
XPRBprob.loadMat or by starting an optimization run from BCL). If the solution is loaded
into BCL the values are accepted as is, if the solution is loaded into the Optimizer (ifopt= true), the Optimizer will check whether the solution is acceptable and recalculates thevalues for the continuous variables in the solution. In the latter case the solution isloaded into BCL only once it has been successfully loaded and validated by the
Optimizer.
2. If the matrix loaded in the Optimizer does not correspond to the current state of thespecified problem definition, it is regenerated automatically before loading the solution.

ExampleLoad a MIP solution for problem prob into BCL, but not into the Optimizer. We knowthat the problem has 5 variables.
XPRBprob prob("myprob");double vals[] = {1.5, 1, 0, 4, 2.2};...
// Define + load the problem
if (prob.loadMIPSol(vals, 5)!=0)
cout << "Loading the solution failed." << endl;

Related topics

Calls XPRBloadmipsol

lpOptimize
Synopsis
int lpOptimize(const char *alg);
int lpOptimize();

Fair Isaac Corporation Confidential and Proprietary Information

268

BCL in C++

Choice of the solution algorithm and options, as a string of flags. If no flag is
specified, solve the problem using the default LP/QP algorithm; otherwise, if theargument includes:"d" solve the problem using the dual simplex algorithm;"p" solve the problem using the primal simplex algorithm;"b" solve the problem using the Newton barrier algorithm;"n" use the network solver (LP only);"c" continue a previously interrupted optimization run.

Argumentalg

Return value

0 if method executed successfully, 1 otherwise.

Description

This method selects and starts the Xpress Optimizer LP/QP solution algorithm. The
characters indicating the algorithm choice may be combined where it makes sense, e.g.
"pn. If the matrix loaded in the Optimizer does not correspond to the current state of
the specified problem definition it is regenerated automatically prior to the start of thealgorithm. Matrix reloading can also be forced by calling XPRBprob.sync before theoptimization. The sense of the optimization (default: minimization) can be changed
with function XPRBprob.setSense. Before solving a problem, the objective function must
be selected with XPRBprob.setObj.

ExampleSee XPRBprob.saveBasis, XPRBprob.mipOptimize.

Related topics

Calls XPRBlpoptimize

mipOptimize
Synopsis
int mipOptimize(const char *alg);
int mipOptimize();
Choice of the solution algorithm and options, as a string of flags. If no flag is
specified, solve the problem using the default MIP/MIQP algorithm; otherwise, if
the argument includes:"d" solve the problem using the dual simplex algorithm;"p" solve the problem using the primal simplex algorithm;"b" solve the problem using the Newton barrier algorithm;"n" use the network solver (for the initial LP);"l" stop after solving the initial continuous relaxation (using MIP
information in presolve);"c" continue a previously interrupted optimization run.

Argumentalg

Return value

0 if method executed successfully, 1 otherwise.

Description

This method selects and starts the Xpress Optimizer MIP/MIQP solution algorithm. The
characters indicating the algorithm choice may be combined where it makes sense, e.g.
"pn. If the matrix loaded in the Optimizer does not correspond to the current state of
the specified problem definition it is regenerated automatically prior to the start of thealgorithm. Matrix reloading can also be forced by calling XPRBprob.sync before theoptimization. The sense of the optimization (default: minimization) can be changed
with function XPRBprob.setSense. Before solving a problem, the objective function must
be selected with XPRBprob.setObj.

ExampleThe following example first maximizes the LP relaxation of a problem and then solves
the problem as a MIP. After each optimization run the objective function value isdisplayed.

Fair Isaac Corporation Confidential and Proprietary Information

269

BCL in C++

XPRBprob prob("myprob");...
// Define the problem
prob.setSense(XPRB_MAXIM);
prob.lpOptimize();if (prob.getLPStat() == XPRB_LP_OPTIMAL)
cout << "LP solution: " << prob.getObjVal() << endl;
prob.mipOptimize();if (prob.getMIPStat() == XPRB_MIP_OPTIMAL ||prob.getMIPStat() == XPRB_MIP_SOLUTION)
cout << "MIP solution: " << prob.getObjVal() << endl;
Related topics

Calls XPRBmipoptimize

nextCtrSynopsisbool nextCtr(XPRBctr& ref);
Reference constraint or NULL.

ArgumentrefReturn value

true if more constraints can be retrieved, false if the end of the enumeration has beenreached.

Description

This method is used to enumerate the constraints of a problem. The argument refserves to keep track of the current location in the enumeration; if this parameter is NULL,
the first constraint is returned, otherwise the constraint that follows the reference
constraint is returned.

ExampleThis code extract prints all constraints of the problem prob.
XPRBprob prob("myprob");...
// Define + load the problem
XPRBctr iter = NULL;
while (prob.nextCtr(iter)) {iter.print();}

Related topics

Calls XPRBgetnextctr

newCtrSynopsis
XPRBctr newCtr(const char *name, XPRBrelation& ac);
XPRBctr newCtr(const char *name);
XPRBctr newCtr(XPRBrelation& ac);
XPRBctr newCtr();
The constraint name (of unlimited length). May be NULL if not required.
A linear or quadratic relation.

Arguments

nameacReturn value

A new BCL constraint.

Fair Isaac Corporation Confidential and Proprietary Information

270

BCL in C++

Description

This method creates a new constraint and returns the reference to this constraint, i.e.,the constraint’s model name. If the indicated name is already in use, BCL adds an index
to it. If no constraint name is given, BCL generates a default name starting with CTR.
(The generation of unique names will only take place if the names dictionary is enabled,see XPRBprob.setDictionarySize.)

ExampleThese are a few examples of constraint creation.
XPRBvar x,y;
XPRBctr Ctr1, Ctr2, Ctr4, Profit;
XPRBexpr le;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y >= 40);
Ctr2 = prob.newCtr("C2", 3*x*y + sqr(y) <= 500);
Profit = prob.newCtr("Profit", x+2*y);prob.setObj(Profit);le = x-5*y;Ctr4 = prob.newCtr(le == 10);

Related topics

Calls XPRBnewctr

newCutSynopsis
XPRBcut newCut(int id);
XPRBcut newCut(XPRBrelation& ac);
XPRBcut newCut(XPRBrelation& ac, int id);
XPRBcut newCut();
A linear relation defining the cut (default: equality constraint).
Cut classification or identification number (default 0).

Argumentsacid

Return value

A new BCL cut.

Description

This method creates a new cut. Cuts are loaded into the Optimizer by calling
XPRBprob.addCuts from the Optimizer cutmanager callback.

ExampleThe following example shows different possibilities of how to define cuts.
XPRBprob prob("myprob");
XPRBvar y,b;
XPRBcut Cut1, Cut2, Cut3;
y = prob.newVar("y", XPRB_PL, 0, 200);b = prob.newVar("b", XPRB_BV);
Cut1 = prob.newCut(y == 100*b);
Cut1.setID(1);Cut2 = prob.newCut(y <= 100*b, 2);

Fair Isaac Corporation Confidential and Proprietary Information

271

BCL in C++

Cut3 = prob.newCut(3);Cut3.setType(XPRB_L);
Cut3.add(y+2);
prob.delCut(Cut3);
Related topics

Calls XPRBnewcut

newIndexSet
Synopsis
XPRBindexSet newIndexSet();
XPRBindexSet newIndexSet(const char *name);
XPRBindexSet newIndexSet(const char *name, int maxsize);
Arguments

name
Name of the index set to be created. May be NULL if not required.
maxsize Maximum size of the index set.

Return value

A new BCL index set.

Description

This method creates a new index set. Note that the indicated size maxsize corresponds
to the space allocated initially to the set, but it is increased dynamically if need be. If theindicated set name is already in use, BCL adds an index to it. If no name is given, BCL
generates a default name starting with IDX. (The generation of unique names will only
take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.)

ExampleThe following example defines an index set of size 10 and then adds two elemnts to theset.
XPRBindexSet ISet;
XPRBprob prob("myprob");
int ind;
ISet = prob.newIndexSet("IS", 10);
ind = ISet.addElement("a"); ISet += "b";Related topics

Calls XPRBnewidxset

newSolSynopsis
XPRBsol newSol();
Return value

A new BCL solution.

Description

This method creates a new solution.

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBnewsol

Fair Isaac Corporation Confidential and Proprietary Information

272

BCL in C++

newSosSynopsis
XPRBsos newSos(int type);
XPRBsos newSos(const char *name, int type);
XPRBsos newSos(int type, XPRBexpr& le);XPRBsos newSos(const char *name, int type, XPRBexpr& le);Arguments

name
type

le

The name of the set.
The set type, which must be one of:
XPRB_S1
Special Ordered Set of type 1 (default);
XPRB_S2Special Ordered Set of type 2.
A linear expression.

Return value

A new BCL SOS.

Description

This method creates a Special Ordered Set (SOS) of type 1 or 2 (abbreviated SOS1 and
SOS2). If the indicated name is already in use, BCL adds an index to it. If no name isgiven for the set, BCL generates a default name starting with SOS. (The generation ofunique names will only take place if the names dictionary is enabled, see
XPRBprob.setDictionarySize.)

ExampleThe following example defines the SOS-1 SO1, prints is out (output displayed ascomment) and then deletes it. After this it defines an SOS-2 named SO2.
XPRBvar x,y,z;
XPRBsos SO1, SO2;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);z = prob.newVar("z", XPRB_PL, 0, 200);
SO1 = prob.newSos("SO1");
SO1.add(x+2*y+3*z);
SO1.print();//
prob.delSos(SO1);

SO1(1): x(+1) y(+2) z(+3)

SO2 = prob.newSos("SO2", XPRB_S2, 10*x+20*y);
Related topics

Calls XPRBnewsos

newVarSynopsis
XPRBvar newVar(const char *name, int type, double lob, double upb);
XPRBvar newVar(const char *name, int type);
XPRBvar newVar(const char *name);
XPRBvar newVar();Arguments

name

The variable name (of unlimited length). May be NULL if not required.

Fair Isaac Corporation Confidential and Proprietary Information

273

BCL in C++

type

lob
upb
Return value
Description

The variable type, which may be one of:
XPRB_PL
continuous (default);
XPRB_BV
binary;XPRB_UI
general integer;
XPRB_PI
partial integer;
XPRB_SCsemi-continuous;
XPRB_SI
semi-continuous integer.
The variable’s lower bound (default value: 0)
The variable’s upper bound (default value: XPRB_INFINITY)

A new BCL decision variable.
1. The creation of a variable in BCL involves not only its name but also its type and bounds.
The method returns the BCL reference to the variable (i.e., a model variable). If theindicated name is already in use, BCL adds an index to it. If no variable name is given,
BCL generates a default name starting with VAR. (The generation of unique names will
only take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.) If
a partial integer, semi-continuous, or semi-continuous integer variable is being created,
the integer or semi-continuous limit (i.e. the lower bound of the continuous part forpartial integer and semi-continuous, and of the semi-continuous integer part forsemi-continuous integer) is set to the maximum of 1 and bdl. This value can be
subsequently modified with the method XPRBvar.setLim.
2. The lower and upper bounds may take values of -XPRB_INFINITY and XPRB_INFINITY forminus and plus infinity respectively.

ExampleThis example shows how to define different types of variables.
XPRBvar x,b,s;
XPRBprob prob("myprob");x = prob.newVar("x");// Continuous with default bounds
b = prob.newVar("b", XPRB_BV);// Binary variables = prob.newVar("s", XPRB_SC, 0, 50); // Semi-cont. in [0,50]
s.setLim(10);// with limit value 10

Related topics

Calls XPRBnewvar

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out the complete problem definition currently held in BCL, thatmeans, the list of constraints, any Special Ordered Sets that have been defined, and theobjective function. This method is not available in the student version.

Related topics

Calls XPRBprintprob

Fair Isaac Corporation Confidential and Proprietary Information

274

BCL in C++

printObj
Synopsisint printObj();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out the objective function currently defined for a problem. Thismethod is not available in the student version.

Related topics

Calls XPRBprintobj

readBinSol
Synopsis
int readBinSol(const char *filename = NULL, const char *flags = "");
Arguments

fname
flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If omitted, the extension .bin will be appended.
Flags to control solution import. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSreadbinsol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function reads a solution from a binary solution file (.sol), loading it into the
Optimizer.

ExampleThis example the reads a solution from file example2.sol
XPRBprob prob("example2");...
// Define + load the problem
prob.readBinSol();
prob.mipOptimize();

Related topics

Calls XPRBreadbinsol

readSlxSol
Synopsis
int readSlxSol(const char *filename = NULL, const char *flags = "");
Arguments

fname
flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If omitted, the extension .slx will be appended.
Flags to control solution import. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSreadslxsol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function reads a solution from an ASCII solution file (.slx), loading it into the
Optimizer.

Fair Isaac Corporation Confidential and Proprietary Information

275

BCL in C++

ExampleThis example the reads a solution from file example2.slx
XPRBprob prob("example2");...
// Define + load the problem
prob.readSlxSol();
prob.mipOptimize();

Related topics

Calls XPRBreadslxsol

reset
Synopsis
int reset();Return value

0 if method executed successfully, 1 otherwise.

Description

This method deletes any solution information stored in BCL; it also deletes thecorresponding Xpress Optimizer problem and removes any auxiliary files that may havebeen created by optimization runs. It also resets the Optimizer control parameters forspare matrix elements (EXTRACOLS, EXTRAROWS, and EXTRAELEMS) to their default values.
The BCL problem definition itself remains. This method may be used to free up memory
if the solution information is not required any longer but the problem definition is to be
kept for later (re)use.

Related topics

Calls XPRBresetprob

saveBasis
Synopsis
XPRBbasis saveBasis();Return value

A BCL basis.

Description

This method saves the current basis of a problem. The basis may be reinput using
XPRBprob.loadBasis. These two methods serve for storing bases in memory; for writing
a basis to a file, the Optimizer library function XPRSwritebasis may be used. Note that
there is no need to allocate space for the basis, but after its use, the basis should bedeleted using XPRBbasis.reset. You may have to switch linear presolve and integer
preprocessing off (Optimizer library controls PRESOLVE and MIPPRESOLVE) in order for thesaving and reloading of bases to work correctly.

ExampleThe following saves a basis and after some modifications to the problem reloads the
problem and the saved basis into the Optimizer before re-solving the problem.
XPRBbasis bas;
XPRBprob prob("myprob");bas = prob.saveBasis();...
// Modify the problem
prob.loadMat();prob.loadBasis(bas);bas.reset();prob.lpOptimize();

Fair Isaac Corporation Confidential and Proprietary Information

276

BCL in C++

Calls XPRBsavebasis

Related topics

setColOrder
Synopsis
int setColOrder(int num);
The ordering flag, which must be one of:0
default ordering;1
alphabetical order.

Argumentnum

Return value

0 if method executed successfully, 1 otherwise.

Description

1. BCL runs reproduce always the same matrix for a problem. This method allows the user
to choose a different ordering criterion than the default one. Note that this method
only changes the order of columns in what is sent to Xpress Optimizer, you do not see
any effect when exporting the matrix with BCL. However you can control the effect byexporting the matrix from the Optimizer.
2. To change this setting for all problems that are created subsequently use thecorresponding method of class XPRB.

Related topics

Calls XPRBsetcolorder

setCutMode
Synopsis
int setCutMode(int mode);Cut mode indicator:
0switch cut mode off
1
switch cut mode on

Argumentmode

Return value

0 if method executed successfully, 1 otherwise.

Description

This function switches the cut mode on or off. It changes the settings of certain
Optimizer controls. Switching the cut mode off resets these controls to their default
values.

ExampleSee XPRBprob.addCuts.

Related topics

Calls XPRBsetcutmode

setDictionarySize
Synopsis
int setDictionarySize(int dict, int size);
Arguments

dictChoice of the dictionary. Possible values:
XPRB_DICT_NAMES
names dictionary
XPRB_DICT_IDX
indices dictionary

Fair Isaac Corporation Confidential and Proprietary Information

277

BCL in C++

size

0 if method executed successfully, 1 otherwise.

Return value
Description

Non-negative value, preferrably a prime number; 0 disables the dictionary (fornames dictionary only).

1. This function sets the size of the hash table of the names or indices dictionaries(defaults: names 2999, indices 1009) of the given problem. It can only be called
immediately after the creation of the corresponding problem.
2. The names dictionary serves for storing and accessing the names of all modeling objects(variables, arrays of variables, constraints, SOS, index sets). Once it has been disabled it
cannot be enabled any more. All methods relative to the names cannot be used if this
dictionary has been disabled and BCL will not generate any unique names at thecreation of model objects. If this dictionary is enabled (default setting) BCL
automatically resizes this dictionary to a suitable size for your problem. If neverthelessyou wish to set the size by yourself we recommend to choose a value close to thenumber of variables+constraints in your problem.
3. The indices dictionary serves for storing all index set elements. The indices dictionary
cannot be disabled, it is created automatically once an index set element is defined.
Calls XPRBsetdictionarysize

Related topics

setMsgLevel
Synopsis
int setMsgLevel(int lev);
The message level, i.e. the type of messages printed by BCL. This may be one of:0
no messages printed;
1
error messages only printed;
2
warnings and errors printed;
3
warnings, errors, and Optimizer log printed (default);
4
all messages printed.

Argumentlevel

Return value

0 if method executed successfully, 1 otherwise.

Description

1. BCL can produce different types of messages; status information, warnings and errors.
This function controls which of these are output. For settings 1 or higher, thecorresponding Optimizer output is also displayed. In addition to this setting, theamount of Optimizer output can be modified through several Optimizer printing
control parameters (see the ‘Xpress Optimizer Reference Manual’).
2. To change this setting for all problems that are created subsequently use thecorresponding method of class XPRB.

ExampleThe following example changes the global BCL message printing level to ’errors’ onlyand sets the printing level for problem prob back to the default. It also modifies thevalues of the Optimizer printing controls for simplex and MIP logging.
XPRBprob prob("myprob");
XPRB::setMsgLevel(1);prob.setMsgLevel(3);
XPRSsetintcontrol(prob.getXPRSprob(), XPRS_LPLOG, 0);
XPRSsetintcontrol(prob.getXPRSprob(), XPRS_MIPLOG, -500);

Related topics

Calls XPRBsetmsglevel

Fair Isaac Corporation Confidential and Proprietary Information

278

BCL in C++

setObjSynopsis
int setObj(XPRBctr ctr);
int setObj(XPRBexpr e);
int setObj(XPRBvar v);
A BCL constraint.
A linear or quadratic expression.
A BCL decision variable.

Arguments

ctrev

Return value

0 if method executed successfully, 1 otherwise.

Description

This functions sets the objective function by selecting a constraint the variable terms ofwhich become the objective function. This must be done before any optimization task iscarried out. Typically, the objective constraint will have the type XPRB_N (non-binding),
but any other type of constraint may be chosen too. In the latter case, the equation orinequality expressed by the constraint also remains part of the problem.

ExampleSee XPRBprob.newCtr.

Related topics

Calls XPRBsetobj

setName
Synopsis
int setName(const char *name);
A string of up to 1024 characters containing the new problem name.

Argument

nameReturn value

0 if method executed successfully, 1 otherwise.

Description

This method sets the problem name.

Related topics

Calls XPRBsetprobname

setRealFmt
Synopsis
int setRealFmt(const char *fmt);
Format string (as used by the C function printf). Simple format strings are of
the form %n where n may be, for instance, one ofgdefault printing format (precision: 6 digits; exponential notation if
the exponent resulting from the conversion is less than -4 or greaterthan or equal to the precision).numf
print real numbers in the style [-]d.d where the number of digits
after the decimal point is equal to the given precision num.

Argument

fmt

Return value

0 if method executed successfully, 1 otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

279

BCL in C++

Description

1. In problems with very large or very small numbers it may become necessary to change
the printing format to obtain a more exact output. In particular, by changing the
precision it is possible to reduce the difference between matrices loaded in memory into
Xpress Optimizer and the output produced by exporting them to a file.
2. To change this setting for all problems that are created subsequently use thecorresponding method of class XPRB.

ExampleSee XPRB.setRealFmt.

Related topics

Calls XPRBsetrealfmt

setSense
Synopsis
int setSense(int dir);
Sense of the objective function, which must be one of:
XPRB_MAXIM maximize the objective;
XPRB_MINIM minimize the objective.

Argument

dir

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets the optimization sense to maximization or minimization. It is set tominimization by default.

ExampleSee XPRBprob.exportProb.

Related topics

Calls XPRBsetsense

sync
Synopsis
int sync(int synctype);
Type of the synchronization. Possible values:
XPRB_XPRS_SOL
update the BCL solution information with the LP
solution currently held in the Optimizer;
XPRB_XPRS_SOLMIP
update the BCL solution information with the last
MIP solution found by the Optimizer;
XPRB_XPRS_PROB
force problem reloading.

Argument

synctype

Return value

0 if method executed successfully, 1 otherwise.

Fair Isaac Corporation Confidential and Proprietary Information

280

BCL in C++

Description

1. This method resets the BCL problem status.
2. XPRB_XPRS_SOL: retrieves the current LP solution (through XPRSgetlpsol function and
XPRS_LPOBJVAL attribute); correctly used also in intsol callbacks as, when an integer
solution is found during a global search, it is always set up as an LP solution to thecurrent node.
3. XPRB_XPRS_SOLMIP: retrieves the last MIP solution found (through XPRSgetmipsol
function and XPRS_MIPOBJVAL attribute); if used from an intsol callback, it will notnecessarily return the solution that caused the invocation of the callback (it is possiblethat another thread finds a new integer solution before that one is retrieved).
4. XPRB_XPRS_SOL and XPRB_XPRS_SOLMIP: the solution information in BCL is updated withthe solution held in the Optimizer at the next solution access (only the objective value isupdated immediately).
5. XPRB_XPRS_PROB: at the next call to optimization or XPRBloadmat the problem iscompletely reloaded into the Optimizer; bound changes are not passed on to the
problem loaded in the Optimizer any longer.

ExampleThe following forces BCL to reload the matrix into the Optimizer even if there has been
no change other than bound changes to the problem definition in BCL since thepreceding optimization / matrix loading.
XPRBprob prob("myprob");...
// Define + load the problem
prob.sync(XPRB_XPRS_PROB);
prob.mipOptimize();

Related topics

Calls XPRBsync

writeDir
Synopsis
int writeDir();
int writeDir(const char *filename);
Name of the directives files.

Argument

filename

Return value

0 if method executed successfully, 1 otherwise.

Description

This method writes out to a file the directives defined for a problem. If the given filename does not include an extension the extension .dir is appended to it. When no filename is given, the name of the problem is used. If a file of the given name exists alreadyit is replaced.

ExampleSee XPRBprob.clearDir.

Related topics

Calls XPRBwritedir

writeSol
Synopsis
int writeSol(const char *filename = NULL, const char *flags = "");

Fair Isaac Corporation Confidential and Proprietary Information

281

BCL in C++

Arguments

fname

flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If no file extension is specified, then extensions .hdr and .asc will
be appended.
Flags to control output format. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSwritesol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function writes out, to a CSV format ASCII file, the current Optimizer solution. If no
file extension is specified, then two files will be written with extensions .asc and .hdr
appended to the given file name. When no file name is given, the name of the problem
is used. If a file of the given name exists already it is replaced.

ExampleThis example the writes current solution to the file example2.asc (and .hdr).
XPRBprob prob("example2");...
// Define + load the problem
prob.mipOptimize();prob.writeSol();

Related topics

Calls XPRBwritesol

writeBinSol
Synopsis
int writeBinSol(const char *filename = NULL, const char *flags = "");
Arguments

fname
flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If omitted, the extension .sol will be appended.
Flags to control output format. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSwritebinsol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function writes out, to a binary file, the current Optimizer solution. If no fileextension is specified, then the extension .sol is appended to the given file name. Whenno file name is given, the name of the problem is used. If a file of the given name exists
already it is replaced.

ExampleThis example the writes current solution to the file example2.sol.
XPRBprob prob("example2");...
// Define + load the problem
prob.mipOptimize();prob.writeBinSol();

Related topics

Calls XPRBwritebinsol

writePrtSol
Synopsis
int writePrtSol(const char *filename = NULL, const char *flags = "");

Fair Isaac Corporation Confidential and Proprietary Information

282

BCL in C++

Arguments

fname
flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If omitted, the extension .prt will be appended.
Flags to control output format. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSwriteprtsol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function writes out, to a fixed format ASCII file, the current Optimizer solution. If
no file extension is specified, then the extension .prt is appended to the given file name.
When no file name is given, the name of the problem is used. If a file of the given nameexists already it is replaced.

ExampleThis example the writes current solution to the file example2.prt.
XPRBprob prob("example2");...
// Define + load the problem
prob.mipOptimize();prob.writePrtSol();

Related topics

Calls XPRBwriteprtsol

writeSlxSol
Synopsis
int writeSlxSol(const char *filename = NULL, const char *flags = "");
Arguments

fname
flags

Name of the solution file. May be NULL or the empty string if the problem nameis to be used. If omitted, the extension .slx will be appended.
Flags to control output format. If no flags need to be specified, use either NULL
or the empty string. Refer to function XPRSwriteslxsol in the ‘Xpress Optimizer
Reference Manual’ for details.

Return value

0 if method executed successfully, 1 otherwise.

Description

This function writes out, to an ASCII solution file (using a similar format to MPS files) the
current Optimizer solution. If no file extension is specified, then the extension .slx isappended to the given file name. When no file name is given, the name of the problem
is used. If a file of the given name exists already it is replaced.

ExampleThis example the writes current solution to the file example2.slx.
XPRBprob prob("example2");...
// Define + load the problem
prob.mipOptimize();prob.writeSlxSol();

Related topics

Calls XPRBwriteslxsol

Fair Isaac Corporation Confidential and Proprietary Information

283

BCL in C++

XPRBrelation(extends XPRBexpr)

Description
Methods and operators for constructing linear or quadratic relations from expressions.
Constructors
XPRBrelation(const XPRBexpr& e, int type);
XPRBrelation(const XPRBexpr& e);
XPRBrelation(const XPRBvar& v);
Methods

int getType();Get the relation type.

Operators
Creating relations by establishing relations between linear or quadratic expressions. The
following operators are defined outside any class definition:
expr1 <= expr2
expr1 >= expr2
expr1 == expr2

Constructor detail

XPRBrelation
SynopsisArguments

Description

XPRBrelation(const XPRBexpr& e, int type);
XPRBrelation(const XPRBexpr& e);
XPRBrelation(const XPRBvar& v);eA linear or quadratic expression.
type
The relation type, which must be one of:
XPRB_L’less than or equal to’ constraint;
XPRB_G’greater than or equal to’ constraint;
XPRB_Ean equality;
XPRB_Na non-binding row (default).
v
A BCL variable.
Create a new linear or quadratic relation.

Method detail

getType
Synopsis
int getType();
Return value

XPRB_L’less than or equal to’ inequality;

Fair Isaac Corporation Confidential and Proprietary Information

284

BCL in C++

XPRB_G
XPRB_E
XPRB_N-1
Description’greater than or equal to’ inequality;
equality;a non-binding row (objective function);
an error has occurred.

This method returns the relation type if successful, and -1 in case of an error.

Fair Isaac Corporation Confidential and Proprietary Information

285

BCL in C++

XPRBsol
Description
Methods for defining, modifying and accessing solutions. Note that all variables in a solution
must belong to the same problem as the solution itself.
Constructors
XPRBsol();
XPRBsos(xbsol *s);
Methods

int delVar(XPRBvar& var);
Delete a variable from a solution.
int getSize();Get the size of a solution.
int getVar(XPRBvar& var, double *val);
Get the value assigned to a variable in a solution.
bool isValid();
Test the validity of the solution object.
int print();
Print out a solution
void reset();Reset the solution object.
int setVar(XPRBvar& var, double val);
Set a variable to the given value in a solution.

Constructor detail

XPRBsol
SynopsisArgument

XPRBsol();
XPRBsos(xbsol *s);s
A solution in BCL C.

Description

Create a new solution object.

Method detaildelVarSynopsisint delVar(XPRBvar& var);
Argumentvar

A BCL variable.

Fair Isaac Corporation Confidential and Proprietary Information

286

BCL in C++

Return value

0 if method executed successfully, 1 otherwise.

Description

This function deletes a variable (assigned to a value) from the given solution.

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBdelsolvar

getSize
Synopsis
int getSize();
Return value

Size (= number of variables assigned to a value) of the solution, or -1 in case of an error.

Description

This method returns the size of a solution (or -1 in case of an error).

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBgetsolsize

getVarSynopsis
int getVar(XPRBvar& var, double *val);
Arguments

var
val

A BCL variable.
Pointer to a double where the value will be returned.

Return value

0-11

variable var is assigned a value in the solution and the value is returned in val;variable var is not assigned any value in the solution (val is left unmodified);
an error has occurred.

Description

This method retrieves the value assigned to the given variable in a solution.

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBgetsolvar

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Description

This method checks whether the solution object is correctly defined.

Fair Isaac Corporation Confidential and Proprietary Information

287

BCL in C++

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out a solution (note that XPRBsol solutions represent user-definedsolutions to be passed to the Optimizer, not solutions coming from the Optimizer). A
solution is printed as a sequence like "varname = value, ... ". If the solution doesn’t
contain any variable, only an empty line is printed.. It is not available in the student
version.

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBprintsol

reset
Synopsisvoid reset();Description

This method clears the definition of the solution object; includes deletion of theunderlying C object. This may be useful to free the memory used for storing the solution(note that this would be freed in any case when the problem is destroyed).

ExampleSee XPRBsol.setVar.

Related topics

Calls XPRBdelsol

setVarSynopsis
int setVar(XPRBvar& var, double val);A BCL variable.
Value assigned to variable var in this solution.

Arguments

var
val

Return value

0 if method executed successfully, 1 otherwise.

Description

This function sets a variable to the given value in a solution. If the variable was alreadyassigned a value, the value is overwritten.

ExampleThis example sets variable x and y in solution sol1 and then changes them.
XPRBvar x, y;
XPRBsol sol1;
XPRBprob prob("myprob");double d;Fair Isaac Corporation Confidential and Proprietary Information

288

BCL in C++

x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);sol1 = prob.newSol();
sol1.setVar(x, 7.0);
sol1.setVar(y, 15.0);
cout << "Sol1: ";sol1.print();// Sol1: x = 7, y = 15
sol1.setVar(x, 10.0);
sol1.getVar(x, &d);cout << "In sol1, x = " << d << endl; // In sol1, x = 10
sol1.delVar(y);cout << "Sol1: ";sol1.print();// Sol1: x = 10
sol1.reset();Related topics

Calls XPRBsetsolvar

Fair Isaac Corporation Confidential and Proprietary Information

289

BCL in C++

XPRBsos
Description
Methods for modifying and accessing Special Ordered Sets and operators for constructing them.
Note that all members in a SOS must belong to the same problem as the SOS itself.
Constructors
XPRBsos();
XPRBsos(xbsos *s);
XPRBsos(xbsos *s, XPRBexpr& l);
Methods

int add(const XPRBexpr& le);Add a linear expression to a SOS.
int addElement(XPRBvar& var, double val);
int addElement(double val, XPRBvar& var);
Add an element to a SOS.
int delElement(XPRBvar& var);
Delete an element from a SOS.
xbsos *getCRef();
Get the C modeling object.
const char *getName();Get the name of a SOS.
int getType();Get the type of a SOS.
bool isValid();
Test the validity of the SOS object.
int print();
Print out a SOS
int setDir(int type, double val);
int setDir(int type);
Set a branching directive for a SOS.

Operators
Assigning and adding linear expressions to Special Ordered Sets:
set = linexp
set += linexp

Constructor detail

XPRBsos
SynopsisArguments

XPRBsos();
XPRBsos(xbsos *s);
XPRBsos(xbsos *s, XPRBexpr& l);s
A SOS in BCL C.
lLinear expression defining the SOS.

Fair Isaac Corporation Confidential and Proprietary Information

290

BCL in C++

Description

Create a new SOS object.

Method detail

add
Synopsis
int add(const XPRBexpr& le);A linear expression.

ArgumentleReturn value

0 if method executed successfully, 1 otherwise.

Description

This method adds the variables of a linear expression to a SOS, using their coefficients inthe linear expression as weights.

ExampleThis example shows different ways of defining SOS and modifying their contents. The
resulting SOS definitions (as obtained with XPRBsos.print) and the output printed by
the program are displayed as comments.
XPRBvar x,y,z;
XPRBsos SO1, SO2;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);y = prob.newVar("y", XPRB_PL, 0, 200);z = prob.newVar("z", XPRB_PL, 0, 200);
SO1 = prob.newSos("SO1", XPRB_S1);
SO1.add(x+2*y+3*z);// SO1(1): x(+1) y(+2) z(+3)
SO1 += 2*z-x;// SO1(1): y(+2) z(+5)
cout << SO1.getName() << " type: ";cout << (SO1.getType()==XPRB_S1?1:2) << endl;// SO1 type: 1
SO2 = prob.newSos("SO2", XPRB_S2, 10*x+20*y);SO2.addElement(z, 5);// SO2(2): x(+10) y(+20) z(+5)
SO2.delElement(x);// SO2(2): y(+20) z(+5)

addElement
Synopsis
int addElement(XPRBvar& var, double val);
int addElement(double val, XPRBvar& var);
Reference to a variable.
The corresponding weight or reference value.

Arguments

var
val

Return value

0 if function executed successfully, 1 otherwise

Fair Isaac Corporation Confidential and Proprietary Information

291

BCL in C++

Description

This method adds a single variable and its weight coefficient to a Special Ordered Set. If
the variable is already contained in the set, the indicated value is added to its weight.
Note that weight coefficients must be different from 0.

ExampleSee XPRBsos.add.

Related topics

Calls XPRBaddsosel

delElement
Synopsisint delElement(XPRBvar& var);
A BCL variable.

Argumentvar

Return value

0 if method executed successfully, 1 otherwise.

Description

This function removes a variable from a Special Ordered Set.

ExampleSee XPRBsos.add.

Related topics

Calls XPRBdelsosel

getCRef
Synopsisxbsos *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the SOS object in BCL C that belongs to the C++ SOS object.

getName
Synopsisconst char *getName();Return value

Name of the SOS if executed successfully, NULL otherwise.

Description

This method returns the name of a SOS. If the user has not defined a name the default
name generated by BCL is returned.

ExampleSee XPRBsos.add.

Related topics

Calls XPRBgetsosname

Fair Isaac Corporation Confidential and Proprietary Information

292

BCL in C++

getType
Synopsis
int getType();a Special Ordered Set of type 1;
a Special Ordered Set of type 2;
an error has occurred.

Return value

XPRB_S1
XPRB_S2-1

Description

This method returns the type of a SOS.

ExampleSee XPRBsos.add.

Related topics

Calls XPRBgetsostype

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Description

This method checks whether the SOS object is correctly defined. It should always be used
to test the result returned by XPRBprob.getSosByName.

ExampleSee XPRBprob.getSosByName.

print
Synopsisint print();
Return value

0 if function executed successfully, 1 otherwise.

Description

This method prints out a SOS. It is not available in the student version.

ExampleSee XPRBprob.getSosByName.

Related topics

Calls XPRBprintsos

setDirSynopsis
int setDir(int type, double val);
int setDir(int type);

Fair Isaac Corporation Confidential and Proprietary Information

293

BCL in C++

Arguments

type

val

The directive type, which must be one of:
XPRB_PRpriority;
XPRB_UP
first branch upwards;
XPRB_DN
first branch downwards;
XPRB_PU
pseudo cost on branching upwards;
XPRB_PD
pseudo cost on branching downwards.
An argument dependent on the type of the directive being defined. If type is:
XPRB_PRval will be the priority value, an integer between 1 (highest) and1000 (lowest), the default;
XPRB_UPno input is required;
XPRB_DNno input is required;
XPRB_PUval will be the value of the pseudo cost for the upward branch;
XPRB_PDval will be the value of the pseudo cost for the downward branch.

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets any type of branching directive available in Xpress. This may be apriority for branching on a SOS (type XPRB_PR), the preferred branching direction (types
XPRB_UP, XPRB_DN) or the estimated cost incurred when branching on a SOS (types
XPRB_PU, XPRB_PD). Several directives of different types may be set for a single set.
Method XPRBvar.setDir may be used to set a directive for a variable.

ExampleSee XPRBprob.clearDir.

Related topics

Calls XPRBsetsosdir

Fair Isaac Corporation Confidential and Proprietary Information

294

BCL in C++

XPRBvar
Description
Methods for modifying and accessing variables.
Constructors
XPRBvar();
XPRBvar(xbvar *v);
Methods

int fix(double val);
Fix a variable.
int getColNum();Get the column number for a variable.
xbvar *getCRef();
Get the C modeling object.
double getLB();
Get the lower bound on a variable.
double getLim();
Get the integer limit for a partial integer or the semi-continuous limit for asemi-continuous or semi-continuous integer variable.
const char *getName();Get the name of a variable.
double getRCost();Get the reduced cost value.
double getRNG(int rngtype);
Get ranging information.
double getSol();
Get the solution value.
int getType();Get the type of a variable.
double getUB();
Get the upper bound on a variable.
bool isValid();
Test the validity of the variable object.
int print();
Print out a variable.
int setDir(int type, double val);
int setDir(int type);
Set a branching directive for a variable.
int setLB(double val);
Set a lower bound.
int setLim(double val);
Set the integer limit for a partial integer, or the lower semi-continuous limit for asemi-continuous or semi-continuous integer variable.
int setType(int type);
Set the variable type.
int setUB(double val);
Set an upper bound.

Fair Isaac Corporation Confidential and Proprietary Information

295

BCL in C++

Constructor detail

XPRBvar
SynopsisArgument

XPRBvar();
XPRBvar(xbvar *v);v
A variable in BCL C.

Description

Create a new variable object.

Method detailfix
Synopsis
int fix(double val);
The value to which the variable is to be fixed.

Argumentval

Return value

0 if method executed successfully, 1 otherwise.

Description

This method fixes a variable to the given value. It replaces calls to XPRBvar.setLB and
XPRBvar.setUB. The value val may lie outside the original bounds of the variable. If the
problem is loaded in the Optimizer, the bound change is passed on immediately without
any need to reload the problem.

Related topics

Calls XPRBfixvar

getColNum
Synopsis
int getColNum();
Return value

Column number (non-negative value), or a negative value.

Description

This method returns the column number of a variable in the matrix currently loaded in
the Xpress Optimizer. If the variable is not part of the matrix, or if the matrix has not yet
been generated, the function returns a negative value. To check whether the matrix has
been generated, use function XPRBprob.getProbStat. The counting of column numbers
starts with 0.

ExampleSee XPRBvar.getSol.

Related topics

Calls XPRBgetcolnum

Fair Isaac Corporation Confidential and Proprietary Information

296

BCL in C++

getCRef
Synopsisxbvar *getCRef();
Return value

The underlying modeling object in BCL C.

Description

This method returns the variable object in BCL C that belongs to the C++ variable object.

getLB
Synopsisdouble getLB();
Return value

Lower bound on the variable (default 0).

Description

This method returns the currently defined lower bound on a variable.

ExampleSee XPRBvar.getName.

Related topics

Calls XPRBgetbounds

getLimSynopsisdouble getLim();Return value

Limit value (default 1):

Description

This method returns the currently defined integer limit for a partial integer variable or
the lower semi-continuous limit for a semi-continuous or semi-continuous integer
variable.

ExampleSee XPRBvar.getName.

Related topics

Calls XPRBgetlim

getName
Synopsisconst char *getName();Return value

Name of the variable if executed successfully, NULL otherwise.

Description

This method returns the name of a variable. If the user has not defined a name thedefault name generated by BCL is returned.

Fair Isaac Corporation Confidential and Proprietary Information

297

BCL in C++

ExampleThe following example displays information about a semi-continuous variable. The
output printed by this program extract is shown in the comment.
XPRBvar s;
XPRBprob prob("myprob");s = prob.newVar("s", XPRB_SC, 0, 200);s.setLim(10);if (s.getType()==XPRB_SC || s.getType()==XPRB_SI){
cout << s.getName() << " in {" << s.getLB() << "}+[";
cout << s.getLim() << "," << s.getUB() << "]" << endl;}// s in {0}+[10,200]

Related topics

Calls XPRBgetvarname

getRCost
Synopsisdouble getRCost();Return value

Reduced cost value for the variable, 0 in case of an error.

Description

This method returns the reduced cost value for a variable. The user may wish to test firstwhether this variable is part of the problem, for instance by checking that the column
number is non-negative.
Reduced cost information is available only after LP solving. To obtain reduced costvalues for a MIP solution (that is, if function XPRBprob.getMIPStat returns values
XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), you need to fix the discrete variables to theirsolution values with a call to XPRSfixglobals, followed by a call to XPRBlpoptimize
before calling XPRBgetrcost. Otherwise, if this function is called when a MIP solution isavailable it returns 0.
If no solution information is available this function outputs a warning and returns 0.
If this function is used during the execution of an optimization process (for instance in
Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync
with the flag XPRB_XPRS_SOL. In this case it returns the reduced cost value in the last LP
that has been solved.

ExampleSee XPRBvar.getSol.

Related topics

Calls XPRBgetrcost

getRNG
Synopsisdouble getRNG(int rngtype);

Fair Isaac Corporation Confidential and Proprietary Information

298

BCL in C++

The type of ranging information sought. This is one of:
XPRB_UPACT
upper activity (= the activity level [solution value] thatwould result from a cost coefficient increase from the input
cost to the upper cost XPRB_UCOST—assuming aminimization problem—ignoring the upper bound on thisvariable);
XPRB_LOACT
lower activity (= the activity level [solution value] thatwould result from a cost coefficient decrease from the
input cost to the lower cost XPRB_LCOST—assuming aminimization problem—ignoring the upper bound on thisvariable);
XPRB_UUP
upper unit cost (= the change in the objective function perunit of change in the activity up to the upper activity
XPRB_UPACT);XPRB_UDN
lower unit cost (= the change in the objective function perunit of change in the activity down to the lower activity
XPRB_LOACT)XPRB_UCOST
upper cost;
XPRB_LCOST
lower cost.

Argument

rngtype

Return value

Ranging information of the required type.

Description

1. This method can only be used after solving an LP problem. Ranging information for MIP
problems can be obtained by fixing all discrete variables to their solution values andre-solving the resulting LP problem.
2. For non-basic variables, the unit costs are always the (absolute) values of the reduced
costs.

ExampleThis example retrieves ranging information (lower and upper activity) for a variable.
XPRBvar x;
XPRBprob prob("myprob");x = prob.newVar("x", XPRB_PL, 0, 200);...

// Define and solve an LP problem

cout << "x: " << x.getSol();cout << " (act. range: " << x.getRNG(XPRB_LOACT) << ", " ;cout << x.getRNG(XPRB_UPACT) << ")" << endl;
Related topics

Calls XPRBgetvarrng

getSolSynopsisdouble getSol();
Return value

Primal solution value for the variable, 0 in case of an error.

Description

This function returns the current solution value for a variable. The user may wish to test
first whether this variable is part of the problem, for instance by checking that thecolumn number is non-negative.

Fair Isaac Corporation Confidential and Proprietary Information

299

BCL in C++

If this function is called after completion of a global search and an integer solution has
been found (that is, if function XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION
or XPRB_MIP_OPTIMAL), it returns the value of the best integer solution. If no integer
solution is available after a global search this function outputs a warning and returns 0.
In all other cases it returns the solution value in the last LP that has been solved. If thisfunction is used during the execution of an optimization process (for instance in
Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync
with the flag XPRB_XPRS_SOL.
ExampleThis example retrieves the solution information for the variable x after solving an LP
problem.
XPRBprob prob("myprob");
XPRBvar x;...
x = prob.newVar("x", XPRB_PL, 0, 200);
prob.lpOptimize();
if (x.getColNum() >= 0 && prob.getLPStat()==XPRB_LP_OPTIMAL){
cout << x.getName() << ": solution: " << x.getSol();cout << " reduced cost: " << x.getRCost() << endl;}
else
cout << "No solution information available." << endl;

Related topics

Calls XPRBgetsol

getType
Synopsis
int getType();
continuous;
binary;general integer;
partial integer;semi-continuous;semi-continuous integer;an error has occurred.

Return value

XPRB_PL
XPRB_BVXPRB_UIXPRB_PI
XPRB_SC
XPRB_SI-1

Description

If the function exits successfully, the variable type is returned.

ExampleSee XPRBvar.getName.

Related topics

Calls XPRBgetvartype

getUB
Synopsisdouble getUB();

Fair Isaac Corporation Confidential and Proprietary Information

300

BCL in C++

Return value

Upper bound on the variable (default XPRB_INFINITY).

Description

This method returns the currently defined upper bound on a variable.

ExampleSee XPRBvar.getName.

Related topics

Calls XPRBgetbounds

isValid
Synopsisbool isValid();
Return value

true if object is valid, false otherwise.

Description

This method checks whether the variable object is correctly defined. It should always be
used to test the result returned by XPRBprob.getVarByName.

ExampleSee XPRBprob.getVarByName.

print
Synopsisint print();
Return value

The number of characters printed.

Description

This method prints out a variable. It is not available in the student version.

ExampleSee XPRBprob.getVarByName.

Related topics

Calls XPRBprintvar

setDirSynopsis
int setDir(int type, double val);
int setDir(int type);
Arguments

type

val

Directive type, which must be one of:
XPRB_PRpriority;
XPRB_UP
first branch upwards;
XPRB_DN
first branch downwards;
XPRB_PU
pseudo cost on branching upwards;
XPRB_PD
pseudo cost on branching downwards.
An argument dependent on the type of directive to be defined. Must be one of:
XPRB_PRpriority value — an integer between 1 (highest) and 1000 (least
priority), the default;
XPRB_UPno input required;
XPRB_DNno input required;
XPRB_PUvalue of the pseudo cost on branching upwards;
XPRB_PD
value of the pseudo cost on branching downwards.

Fair Isaac Corporation Confidential and Proprietary Information

301

BCL in C++

Return value
Description

0 if method executed successfully, 1 otherwise.
1. This method sets any type of branching directive available in Xpress. This may be apriority for branching on a variable (type XPRB_PR), the preferred branching direction(types XPRB_UP, XPRB_DN) or the estimated cost incurred when branching on a variable(types XPRB_PU, XPRB_PD). Several directives of different types may be set for a single
variable.
2. Note that it is only possibly to set branching directives for discrete variables (includingsemi-continuous and partial integer variables). Method XPRBsos.setDir may be used to
set a directive for a SOS.

ExampleSee XPRBprob.clearDir.

Related topics

Calls XPRBsetvardir

setLB
Synopsis
int setLB(double val);
The variable’s new lower bound.

Argumentval

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets the lower bound on a variable. If the problem is loaded in the
Optimizer, the bound change is passed on immediately without any need to reload the
problem.

Related topics

Calls XPRBsetlb

setLimSynopsis
int setLim(double val);
Value of the integer limit.

Argumentval

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets the integer limit (i.e. the lower bound of the continuous part) of apartial integer variable or the semi-continuous limit of a semi-continuous orsemi-continuous integer variable to the given value.

ExampleSee XPRBvar.getName, XPRBprob.newVar.

Related topics

Calls XPRBsetlim

setType
Synopsis
int setType(int type);

Fair Isaac Corporation Confidential and Proprietary Information

302

BCL in C++

The variable type, which is one of:
XPRB_PL
continuous;
XPRB_BV
binary;XPRB_UI
general integer;
XPRB_PI
partial integer;
XPRB_SCsemi-continuous;
XPRB_SI
semi-continuous integer.

Argument

type

Return value

0 if method executed successfully, 1 otherwise.

Description

This method changes the type of a variable that has been created previously.

Related topics

Calls XPRBsetvartype

setUB
Synopsis
int setUB(double val);
The variable’s new upper bound.

Argumentval

Return value

0 if method executed successfully, 1 otherwise.

Description

This method sets the upper bound on a variable. If the problem is loaded in the
Optimizer, the bound change is passed on immediately without any need to reload the
problem.

Related topics

Calls XPRBsetub

Fair Isaac Corporation Confidential and Proprietary Information

303

C HAPTER 6

BCL in Java
6.1

An overview of BCL in Java
Much as for the C++ interface, the Java interface of BCL provides the full functionality of the C
version except for the data input, output and error handling for which the standard Java system
functions can be used. The C modeling objects, such as variables, constraints and problems, areagain converted into classes, and their associated functions into methods of the correspondingclass in Java.
Whereas in C++ it is possible to use C functions, such as printf or XPRBprintf for printing output,
all code in Java programs must be written in Java itself. In addition, in Java it is not possible tooverload the algebraic operators as has been done for the definition of constraints in C++.
Instead, the Java interface provides a set of simple methods like add or eql that have been
overloaded to accept various types and numbers of parameters.
The names for classes and methods in Java have been formed in the same way as those of theircounterparts in C++: All Java classes that have a direct correspondence with modeling objects in
BCL (namely XPRBprob, XPRBvar, XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBindexSet, XPRBbasis)take the same names, with the exception of XPRBindexSet. In the names of the methods theprefix XPRB has been dropped, as have references to the type of the object. For example, function
XPRBgetvarname is turned into the method getName of class XPRBvar.
All Java BCL classes are contained in the package com.dashoptimization. To use the (short) classnames, it is recommended to add the line
import com.dashoptimization.*;at the beginning of every program that uses the Java classes of BCL.
The C++ classes and their methods documented in section 5.2 correspond to a large extend to theclasses defined by the Java interface, with some additional classes in the Java version. A
comprehensive documentation of the BCL Java interface is available as a separate ‘Java on-line
documentation’ located in subdirectory docs/bcl/dhtml/javadoc of the Xpress installation
directory.

6.1.1

ExampleAn example of use of BCL in Java is the following, which again constructs the example describedin Chapter 2. Contrary to the C and C++ versions, BCL Java needs to be initialized explicitly bycreating an instance of XPRB.
If a BCL Java model is embedded into an application we recommend to use explicit finalization on
the XPRBprob object once it is no longer needed to free up the memory used by it (particularly, thememory used by the underlying C structures that are not taken into account by the automatedFair Isaac Corporation Confidential and Proprietary Information

304

BCL in Javagarbage collection in Java). Alternatively, a problem can be reset to free up the memory used by
the optimization and solution data without removing the problem definition itself.
import com.dashoptimization.*;public class xbexpl1{
static final int NJ = 4;
static final int NT = 10;/* Number of jobs *//* Time limit */static final double[] DUR = {3,4,2,2};
static XPRBvar[] start;
static XPRBvar[][] delta;
static XPRBvar z;/* Durations of jobs *//* Start times of jobs *//* Binaries for start times *//* Max. completion time */static XPRB bcl;
static XPRBprob p;
static void jobsModel(){XPRBexpr le;
int j,t;start = new XPRBvar[NJ];/* Start time variables */for(j=0;j<NJ;j++) start[j] = p.newVar("start");z = p.newVar("z",XPRB.PL,0,NT); /* Makespan variable */delta = new XPRBvar[NJ][NT];for(j=0;j<NJ;j++)/* Binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] = p.newVar("delta"+(j+1)+(t+1), XPRB.BV);
for(j=0;j<NJ;j++)/* Calculate max. completion time */p.newCtr("Makespan", start[j].add(DUR[j]).lEql(z) );p.newCtr("Prec", start[0].add(DUR[0]).lEql(start[2]) );/* Precedence rel. between jobs */for(j=0;j<NJ;j++)/* Linking start times & binaries */{le = new XPRBexpr();for(t=0;t<(NT-DUR[j]+1);t++)le.add(delta[j][t].mul((t+1)));p.newCtr("Link_"+(j+1), le.eql(start[j]) );}for(j=0;j<NJ;j++)/* Unique start time for each job */{le = new XPRBexpr();for(t=0;t<(NT-DUR[j]+1);t++) le.add(delta[j][t]);p.newCtr("One_"+(j+1), le.eql(1));}
p.setObj(z);/* Define and set objective */for(j=0;j<NJ;j++) start[j].setUB(NT-DUR[j]+1);/* Upper bounds on "start" var.s */}static void jobsSolve(){
int j,t,statmip;
for(j=0;j<NJ;j++)for(t=0;t<NT-DUR[j]+1;t++)delta[j][t].setDir(XPRB.PR, 10*(t+1));/* Give highest priority to var.s for earlier start times */Fair Isaac Corporation Confidential and Proprietary Information

305

BCL in Javap.setSense(XPRB.MINIM);
p.mipOptimize();statmip = p.getMIPStat();/* Solve the problem as MIP *//* Get the MIP problem status */if((statmip == XPRB.MIP_SOLUTION) ||(statmip == XPRB.MIP_OPTIMAL)){/* An integer solution has been found */System.out.println("Objective: "+ p.getObjVal());/* Print solution for all start times */for(j=0;j<NJ;j++)System.out.println(start[j].getName() + ": "+start[j].getSol());}}
public static void main(String[] args){
bcl = new XPRB();/* Initialize BCL */p = bcl.newProb("Jobs");/* Create a new problem */jobsModel();jobsSolve();p.finalize();
p=null;}}/* Problem definition *//* Solve and print solution *//* Delete the problem (optional) */The definition of SOS is similar to the definition of constraints.
static XPRBsos[] set;static XPRBprob p;
static void jobsModel(){...
delta = new XPRBvar[NJ][NT];for(j=0;j<NJ;j++)/* Variables for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] = p.newVar("delta"+(j+1)+(t+1), XPRB.PL, 0, 1);
set = new XPRBsos[NJ];
for(j=0;j<NJ;j++)/* SOS definition */{le = new XPRBexpr();for(t=0;t<(NT-DUR[j]+1);t++)le.add(delta[j][t].mul((t+1)));
set[j] = p.newSos("sosj", XPRB.S1, le);}}Branching directives for the SOSs are added as follows.
for(j=0;j<NJ;j++) set[j].setDir(XPRB.DN);/* First branch downwards on sets */Adding the following two lines during or after the problem definition will print the problem tothe standard output and export the matrix to a file respectively.
p.print();/* Print out the problem def. */p.exportProb(XPRB.MPS,"expl1");/* Output matrix to MPS file */Similarly to what has been shown for the problem formulation in C and C++, we may read datafrom file and use index sets in the problem formulation. Only a few changes and additions to the

Fair Isaac Corporation Confidential and Proprietary Information

306

BCL in Java

basic model formulation are required for the creation and use of index sets. However, if we want
to read in a data file in the format accepted by the C functions XPRBreadline and
XPRBreadarrline (that is, using ’!’ as commentary sign, and ’,’ as separators, and skip blanks andempty lines), we need to configure the data file access in Java.
In the following program listing we leave out the method jobsSolve because it remains
unchanged from the previous.
import java.io.*;import com.dashoptimization.*;public class xbexpl1i{
static final int MAXNJ = 4;
static final int NT = 10;/* Max. number of jobs *//* Time limit */static int NJ = 0;
static final double[] DUR;/* Number of jobs read in *//* Durations of jobs */static XPRBindexSet Jobs;
static XPRBvar[] start;
static XPRBvar[][] delta;
static XPRBvar z;/* Job names *//* Start times of jobs *//* Binaries for start times *//* Max. completion time */static XPRB bcl;
static XPRBprob p;/**** Initialize the stream tokenizer ****/
static StreamTokenizer initST(FileReader file){
StreamTokenizer st=null;
st= new StreamTokenizer(file);st.commentChar(’!’);
st.eolIsSignificant(true);st.ordinaryChar(’,’);
st.parseNumbers();
return st;}/* Use character ’!’ for comments *//* Return end-of-line character *//* Use ’,’ as separator *//* Read numbers as numbers (not strings)*//**** Read data from files ****/
static void readData() throws IOException{
FileReader datafile=null;
StreamTokenizer st;
int i;/* Create a new index set */Jobs = p.newIndexSet("Jobs", MAXNJ);
DUR = new double[MAXNJ];
datafile = new FileReader("durations.dat");st = initST(datafile);
do
{
do
{
st.nextToken();} while(st.ttype==st.TT_EOL);/* Skip empty lines */if(st.ttype != st.TT_WORD) break;i=Jobs.addElement(st.sval);if(st.nextToken() != ’,’) break;if(st.nextToken() != st.TT_NUMBER) break;DUR[i] = st.nval;
NJ+=1;} while( st.nextToken() == st.TT_EOL && NJ<MAXNJ);
datafile.close();
System.out.println("Number of jobs read: " + Jobs.getSize());}

Fair Isaac Corporation Confidential and Proprietary Information

307

BCL in Javastatic void jobsModel(){XPRBexpr le;
int j,t;start = new XPRBvar[NJ];
for(j=0;j<NJ;j++)/* Start time variables with bounds */start[j] = p.newVar("start",XPRB.PL,0,NT-DUR[j]+1);
z = p.newVar("z",XPRB.PL,0,NT); /* Makespan variable */delta = new XPRBvar[NJ][NT];for(j=0;j<NJ;j++)/* Binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j][t] =p.newVar("delta"+Jobs.getIndexName(j)+"_"+(t+1),
XPRB.BV);
for(j=0;j<NJ;j++)/* Calculate max. completion time */p.newCtr("Makespan", start[j].add(DUR[j]).lEql(z) );p.newCtr("Prec", start[0].add(DUR[0]).lEql(start[2]) );/* Precedence rel. between jobs */for(j=0;j<NJ;j++)/* Linking start times & binaries */{le = new XPRBexpr();for(t=0;t<(NT-DUR[j]+1);t++)le.add(delta[j][t].mul((t+1)));p.newCtr("Link_"+(j+1), le.eql(start[j]) );}for(j=0;j<NJ;j++)/* Unique start time for each job */{le = new XPRBexpr();for(t=0;t<(NT-DUR[j]+1);t++) le.add(delta[j][t]);p.newCtr("One_"+(j+1), le.eql(1));}
p.setObj(z);}/* Define and set objective */public static void main(String[] args){
bcl = new XPRB();/* Initialize BCL */p = bcl.newProb("Jobs");/* Create a new problem */try{readData();/* Data input from file */}catch(IOException e){
System.err.println(e.getMessage());
System.exit(1);}jobsModel();/* Problem definition */jobsSolve();/* Solve and print solution */p.finalize();
p=null;}}6.1.2/* Delete the problem (optional) */QCQP Example
The following is an implementation with BCL Java of the QCQP example described in Section
3.5.1:

Fair Isaac Corporation Confidential and Proprietary Information

308

BCL in Java

import java.io.*;import com.dashoptimization.*;public class xbairport{
static final int N = 42;/* Initialize the data tables:
static final double CX[] = ...
static final double CY[] = ...
static final double R[] = ...
*/public static void main(String[] args) throws IOException{
XPRB bcl;
XPRBprob prob;
int i,j;
XPRBvar[] x,y;/* x-/y-coordinates to determine */XPRBexpr qe;
XPRBctr cobj, c;bcl = new XPRB();
prob = bcl.newProb("airport");/* Initialize BCL *//* Create a new problem in BCL *//**** VARIABLES ****/
x = new XPRBvar[N];for(i=0;i<N;i++)x[i] = prob.newVar("x(" + (i+1) + ")", XPRB.PL, -10, 10);y = new XPRBvar[N];for(i=0;i<N;i++)y[i] = prob.newVar("y(" + (i+1) + ")", XPRB.PL, -10, 10);/****OBJECTIVE****//* Minimize the total distance between all points */qe = new XPRBexpr();for(i=0;i<N-1;i++)for(j=i+1;j<N;j++) qe .add((x[i].add(x[j].mul(-1))).sqr()).add((y[i].add(y[j].mul(-1))).sqr());
cobj = prob.newCtr("TotDist", qe);prob.setObj(cobj);/* Set objective function *//**** CONSTRAINTS ****//* All points within given distance of their target location */for(i=0;i<N;i++)c = prob.newCtr("LimDist", (x[i].add(-CX[i])).sqr().add( (y[i].add(-CY[i])).sqr()) .lEql(R[i]) );/****SOLVING + OUTPUT****/
prob.setSense(XPRB.MINIM);
prob.lpOptimize();/* Sense of optimization *//* Solve the problem */System.out.println("Solution: " + prob.getObjVal());
for(i=0;i<N;i++)System.out.println(x[i].getName() + ": " + x[i].getSol() +", " + y[i].getName() + ": " + y[i].getSol());
p.finalize();
p=null;}}6.1.3/* Delete the problem */Error handlingIf an error occurs, BCL Java raises exceptions. A large majority of these execeptions are of class
XPRBerror, during initialization of class XPRBlicenseError, and if file access is involved (such as inmethod exportProb) of class IOException. For simplicity’s sake most of the Java program
examples in this manual omit the error handling. Below we show a Java implementation of theexample of user error handling with BCL from Section 3.6. Other features demonstrated by thisFair Isaac Corporation Confidential and Proprietary Information

309

BCL in Java

example include

redirection of the BCL output stream for the whole program and for an individual problem;setting the BCL message printing level;forcing garbage collection for a problem after explicitly finalizing it to free up memory;

finalization of BCL to release the license.
import java.io.*;import com.dashoptimization.*;public class xbexpl3{
static XPRB bcl;/***********************************************************************/
public static void modexpl3(XPRBprob prob) throws XPRBerror{
XPRBvar[] x;
XPRBexpr cobj;
int i;
x = new XPRBvar[3];/* Create the variables */for(i=0;i<2;i++) x[i] = prob.newVar("x_"+i, XPRB.UI, 0, 100);/* Create the constraints:
C1: 2x0 + 3x1 >= 41
C2: x0 + 2x1 = 13 */prob.newCtr("C1", x[0].mul(2).add(x[1].mul(3)) .gEql(41));prob.newCtr("C2", x[0].add(x[1].mul(2)) .eql(13));/* Uncomment the following line to cause an error in the model thattriggers the error handling: *///x[2] = prob.newVar("x_2", XPRB.UI, 10, 1);/* Objective: minimize x0+x1 */cobj = new XPRBexpr();for(i=0;i<2;i++) cobj.add(x[i]);prob.setObj(cobj);/* Select objective function */prob.setSense(XPRB.MINIM);/* Set objective sense to minimization */prob.print();/* Print current problem definition */prob.lpOptimize();/* Solve the LP */System.out.println("Problem status: " + prob.getProbStat() +" LP status: " + prob.getLPStat() +" MIP status: " + prob.getMIPStat());/* This problem is infeasible, that means the following command will fail.
It prints a warning if the message level is at least 2 */System.out.println("Objective: " + prob.getObjVal());
for(i=0;i<2;i++)/* Print solution values */System.out.print(x[i].getName() + ":" + x[i].getSol() + ", ");System.out.println();}/***********************************************************************/
public static void main(String[] args){
FileWriter f;
XPRBprob prob;

Fair Isaac Corporation Confidential and Proprietary Information

310

BCL in Javatry{bcl = new XPRB();/* Initialize BCL */}catch(XPRBlicenseError e){
System.err.println("BCL error "+ e.getErrorCode() + ": " + e.getMessage());
System.exit(1);}bcl.setMsgLevel(2);/* Set the printing flag. Try other values:
0 - no printed output,
2 - print warnings, 3 - all messages */try{
f=new FileWriter("expl3out.txt");
bcl.setOutputStream(f);/* Redirect all output from BCL to a file */prob = bcl.newProb("Expl3");
prob.setOutputStream();modexpl3(prob);/* Create a new problem *//* Output for this prob. on standard output *//* Formulate and solve the problem */prob.setOutputStream(f);prob.print();
prob.setOutputStream();bcl.setOutputStream();f.close();/* Redirect problem output to file *//* Write to the output file *//* Re-establish standard output for prob *//* Re-establish standard output for BCL */prob.finalize();
prob=null;/* Delete the problem */bcl.finalize();bcl=null;/* Release license */System.gc();
System.runFinalization();/* Force garbage collection */System.err.flush();}catch(IOException e){
System.err.println(e.getMessage());
System.exit(1);}catch(XPRBerror e){
System.err.println("BCL error "+ e.getErrorCode() + ": " + e.getMessage());
System.exit(1);
}
}
}

6.2

Java class reference
The complete set of classes of the BCL Java interface is summarized in the following list. For adetailed documentation of the Java interface the reader is referred to the BCL Javadoc that ispart of the Xpress distribution (located in subdirectory docs/bcl/dhtml/javadoc of the Xpress
installation directory).
XPRB

Initialization and general settings, definition of all parameters.

XPRBprob

Problem definition, including methods for creating and deleting themodeling objects, problem solving, changing settings, and retrieving
solution information.

Fair Isaac Corporation Confidential and Proprietary Information

311

BCL in Java

XPRBvar

Methods for modifying and accessing variables.

XPRBctr

Methods for constructing, modifying and accessing constraints.

XPRBcut

Methods for constructing, modifying and accessing cuts.

XPRBsol

Methods for constructing, modifying and accessing solutions.

XPRBsos

Methods for constructing, modifying and accessing Special Ordered
Sets.

XPRBindexSet

Methods for constructing and accessing index sets and accessing set
elements.

XPRBbasis

Methods for accessing bases.

XPRBexpr

Methods for constructing linear and quadratic expressions.

XPRBrelation

Methods for constructing linear or quadratic relations from expressions(extends XPRBexpr).

XPRBerror

Exception raised by BCL errors (extends Error).

XPRBlicenseError

Exception raised by BCL licensing errors (extends XPRBerror).

XPRBlicense

For OEM licensing.

All Java classes that have a direct correspondence with modeling objects in BCL (namely XPRBprob,
XPRBvar, XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBindexSet, XPRBbasis) take the same names,with the exception of XPRBindexSet. It is possible to obtain the Xpress Optimizer problem
corresponding to a BCL Java problem by using method getXPRSprob of class XPRBprob, please see
Section B.7 for further detail on using BCL with the Optimizer library.
Most of the methods of the classes with direct correspondence with C modeling objects callstandard BCL C functions and return their result. Where the C functions return 0 or 1 to indicate
success or failure of the execution of a function the Java methods have return type void, raising
an exception if an error occurs.
An important class that does not correspond to any standard BCL modeling object is class XPRB
that contains methods relating to the initialization and the general status of the software andalso the definition of all parameters. This means, any parameter with the prefix XPRB_ in standard
BCL is referred to as a constant of the Java class XPRB. For example, XPRB_BV in standard BCL
becomes XPRB.BV in Java.
In Java, it is not possible to overload operators as this is the case in the C++ interface; instead, aset of simple methods is provided, for example, add or eql that have been overloaded to accept
various types and numbers of parameters. Some additional classes have been introduced to aid
the termwise definition of constraints. Linear and quadratic expressions (class XPRBexpr) are
required in the definition of constraints and Special Ordered Sets. Linear or quadratic relations(class XPRBrelation), may be used as an intermediary in the definition of constraints.
A few other additional classes are related to error handling and licensing, namely XPRBerror,
XPRBlicense, and XPRBlicenseError (overloads XPRBerror). License errors are raised by the
initialization of BCL, all other BCL errors are handled by exceptions of the type XPRBerror. Output
functions involving file access (in particular matrix output with exportProb) may also generate
exceptions of type IOException. The class XPRBlicense only serves for OEM licensing; for further
detail please see the Xpress OEM licensing documentation.

Fair Isaac Corporation Confidential and Proprietary Information

312

C HAPTER 7

BCL in .NET
7.1

An overview of BCL in .NET
The .NET interface of BCL provides the full functionality of the C version, targeting .NET
framework version 2.0 or higher. The C modeling objects, such as variables, constraints andproblems, are again converted into classes, and their associated functions into methods of thecorresponding class in .NET.
In .NET, the termwise definition of constraints is simplified by the overloading of the algebraic
operators like ’+‘, ’-‘, ’<=‘, or ’==‘ as in the C++ interface. With these operators constraints may be
written in a form that is close to an algebraic formulation. Also, for printing output, it is possible
to use both .NET native IO functions or the XPRBprob.printF BCL function (which corresponds to
the BCL C XPRBprintf function).
The names of classes and methods have been adapted to .NET naming standards: all .NET classes
that have a direct correspondence with modeling objects in BCL (namely XPRBprob, XPRBvar,
XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBbasis) take the same names, with the exception of
XPRBidxset which becomes XPRBindexSetin .NET. The names of the methods are also changed bydropping the prefix XPRB and references to the type of the object, and each word is capitalized.
For example, function XPRBgetvarname is turned into the method getName of class XPRBvar. Two
exceptions are XPRBreadline and XPRBreadarrline which maintain these names as methods ofthe XPRBprob class and thus become XPRBprob.XPRBreadline and XPRBprob.XPRBreadarrline. The
auto-completion feature in Visual Studio .NET can be used to obtain a full list of class methods
and properties and prototypes of each method.
The BCL functionality is exposed through the XPRB and XPRBprob classes, which reside in the BCL
namespace, which resides in the xprbdn.dll assembly.
Each source file that uses BCL should import the BCL namespace and should be compiled with areference to xprbdn.dll. To add a reference to a Visual Studio .NET project, select Add Reference
from the Project menu. Click the Browse button and locate xprbdn.dll in the XpressMP/bin folder.
Users of the .NET command line compilers, for example, csc for C#, or vbc for Visual Basic, canadd a reference with the /reference option:
csc /reference:<path to xprbdn.dll> <your source file>

The C++ classes and their methods documented in section 5.2 correspond to a large extend to theclasses defined by the .NET interface, with some additional classes in the .NET version. A
comprehensive documentation of the BCL .NET interface is available as a separate ‘HTML on-line
documentation’ located in subdirectory docs/bcl/bcl.net/HTML of the Xpress installation
directory.

Fair Isaac Corporation Confidential and Proprietary Information

313

BCL in .NET

7.1.1

ExampleAn example of the use of BCL in .NET is the following, which again constructs the example
described in Chapter 2. Contrary to the C and C++ versions, BCL .NET needs to be initialized
explicitly by calling the static method XPRB.init().
BCL models can take up large amounts of memory therefore, if a BCL .NET model is embedded
into an application, we recommend to explicitly release the resources used by the XPRBprob
object, once it is no longer needed, by calling XPRB.Dispose()(particularly, the memory used by
the underlying C structures that are not taken into account by the automated garbage collection
in .NET). Alternatively, a problem can be reset to free up the memory used by the optimizationand solution data without removing the problem definition itself.
using BCL;
namespace Examples{
public class xbexpl1{
const int NJ = 4;
const int NT = 10;/* Number of jobs *//* Time limit */static double[] DUR = {3,4,2,2};/* Durations of jobs*/

static XPRBvar[] start = new XPRBvar[NJ];/* Start times of jobs */static XPRBvar[,] delta = new XPRBvar[NJ,NT];/* Binaries for start times */static XPRBvar z;/* Maximum completion time (makespan) */static XPRBprob p;
static void jobsModel(){XPRBexpr le;
int j,t;/****VARIABLES****//* Create start time variables */for(j=0;j<NJ;j++) start[j] = p.newVar("start");z = p.newVar("z",BCLconstant.XPRB_PL,0,NT); /* Declare the makespan variable */for(j=0;j<NJ;j++)/* Declare binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j,t] = p.newVar("delta" + (j+1) + (t+1),BCLconstant.XPRB_BV);/****CONSTRAINTS****/
for(j=0;j<NJ;j++)/* Calculate maximal completion time */p.newCtr("Makespan", start[j]+DUR[j] <= z);p.newCtr("Prec", start[0]+DUR[0] <= start[2]);/* Precedence relation between jobs */for(j=0;j<NJ;j++)/* Linking start times and binaries{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j,t];p.newCtr("Link_" + (j+1), le == start[j]);}*/for(j=0;j<NJ;j++)/* One unique start time for each job{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += delta[j,t];p.newCtr("One_" + (j+1), le == 1);}*//****OBJECTIVE****//* Define and set objective function */Fair Isaac Corporation Confidential and Proprietary Information

314

BCL in .NET

p.setObj(p.newCtr("OBJ", new XPRBrelation(z)));/****BOUNDS****/
for(j=0;j<NJ;j++) start[j].setUB(NT-DUR[j]+1);/* Upper bounds on start time variables */}static void jobsSolve(){
int j,t,statmip;
for(j=0;j<NJ;j++)for(t=0;t<NT-DUR[j]+1;t++)delta[j,t].setDir(BCLconstant.XPRB_PR,10*(t+1));/* Give highest priority to variables for earlier start times */p.setSense(BCLconstant.XPRB_MINIM);
p.mipOptimize();/* Solve the problem as MIP */statmip = p.getMIPStat();/* Get the MIP problem status */if((statmip == BCLconstant.XPRB_MIP_SOLUTION) ||(statmip == BCLconstant.XPRB_MIP_OPTIMAL)){ /* An integer solution has been found */Console.WriteLine("Objective: {0}", p.getObjVal());
for(j=0;j<NJ;j++){ /* Print the solution for all start times */System.Console.WriteLine("{0}: {1}", start[j].getName(), start[j].getSol());
for(t=0;t<NT-DUR[j]+1;t++)System.Console.Write("{0}: {1} ",delta[j,t].getName(),delta[j,t].getSol());
System.Console.WriteLine();}}}public static void Main(){
XPRB.init();p = new XPRBprob("Jobs");
jobsModel();jobsSolve();return;}/* Initialize BCL *//* Create a new problem *//* Basic problem definition *//* Solve and print solution */}}The definition of SOS is similar to the definition of constraints.
static XPRBsos[] set = new XPRBsos[NJ]; /* Sets regrouping start times for jobs */static XPRBprob p;public static void jobsModel(){...
for(j=0;j<NJ;j++)/* Declare binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j,t] = p.newVar("delta" + (j+1) + (t+1),BCLconstant.XPRB_PL,0,1);/****SETS****/
for(j=0;j<NJ;j++){le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j,t];set[j] = p.newSos("sosj",BCLconstant.XPRB_S1,le);}}Branching directives for the SOSs are added as follows.

Fair Isaac Corporation Confidential and Proprietary Information

315

BCL in .NETfor(j=0;j<NJ;j++)set[j].setDir(BCLconstant.XPRB_DN); /* First branch downwards on sets */Adding the following two lines during or after the problem definition will print the problem tothe standard output and export the matrix to a file respectively.
p.print();/* Print out the problem definition */p.exportProb(BCLconstant.XPRB_MPS,"expl1"); /* Output matrix to MPS file */Similarly to what has been shown for the problem formulation in C and C++, we may read datafrom file and use index sets in the problem formulation. Only a few changes and additions to thebasic model formulation are required for the creation and use of index sets. However, if we want
to read in a data file in the format accepted by the C functions XPRBreadline and
XPRBreadarrline (that is, using ’!’ as commentary sign, and ’,’ as separators, and skip blanks andempty lines), we need to configure the data file access in .NET.
In the following program listing we leave out the method jobsSolve because it remains
unchanged from the previous.
using System.IO;
using BCL;
namespace Examples{
public class xbexpl1i{
const int MAXNJ = 4;
const int NT = 10;/* Max. number of jobs *//* Time limit *///Define XPRBDATAPATH to whatever folder you wish.
const string XPRBDATAPATH = "../../data";
const string DATAFILE = XPRBDATAPATH + "/jobs/durations.dat";/**** DATA ****/
static int NJ = 0;/* Number of jobs read in */static double[] DUR = new double[MAXNJ]; /* Durations of jobs*/
static XPRBindexSet Jobs;
static XPRBvar[] start;
static XPRBvar[,] delta;
static XPRBvar z;/* Job names *//* Start times of jobs *//* Binaries for start times *//* Maximum completion time (makespan) */XPRBprob p;/* BCL problem */static void readData(){
string name;
FileStream file;
StreamReader fileStreamIn;/* Create a new index set */Jobs = p.newIndexSet("jobs", MAXNJ);

file = new FileStream(DATAFILE, FileMode.Open, FileAccess.Read);
fileStreamIn = new StreamReader(file);
object[] tempobj = new object[2];while((NJ<MAXNJ) &&(p.XPRBreadarrline(fileStreamIn, 99, "{t} , {g} ", out tempobj, 1) == 2)){
int dummy;
name = (string)tempobj[0];DUR[NJ] = (double)tempobj[1];dummy = Jobs + name;
NJ++;

Fair Isaac Corporation Confidential and Proprietary Information

316

BCL in .NET}
fileStreamIn.Close();file.Close();
System.Console.WriteLine("Number of jobs read: " + Jobs.getSize());}
static void jobsModel(){XPRBexpr le;
int j,t;/****VARIABLES****//* Create start time variables (incl. bounds) */start = new XPRBvar[NJ];if(start==null){
System.Console.WriteLine("Not enough memory for ’start’ variables.");return;}for (j = 0; j < NJ; j++)start[j] = p.newVar("start", BCLconstant.XPRB_PL, 0, NT - DUR[j] + 1);
z = p.newVar("z",BCLconstant.XPRB_PL,0,NT); /* Declare the makespan variable */delta = new XPRBvar[NJ, NT];for(j=0;j<NJ;j++)/* Declare binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j,t] = p.newVar("delta"+Jobs.getIndexName(j)+"_"+(t+1),
BCLconstant.XPRB_BV);/****CONSTRAINTS****/
for(j=0;j<NJ;j++)/* Calculate maximal completion time */p.newCtr("Makespan", start[j]+DUR[j] <= z);p.newCtr("Prec", start[0]+DUR[0] <= start[2]);/* Precedence relation between jobs */for(j=0;j<NJ;j++)/* Linking start times and binaries{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j,t];p.newCtr("Link_" + (j+1), le == start[j]);}*/for(j=0;j<NJ;j++)/* One unique start time for each job{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += delta[j,t];p.newCtr("One_" + (j+1), le == 1);}/****OBJECTIVE****/
p.setObj(p.newCtr(z));
jobsSolve();*//* Define and set objective function *//* Solve the problem */}public static void Main(){
XPRB.init();p = new XPRBprob("Jobs");
readData();jobsModel();}/* Create a new problem *//* Read in the data *//* Basic problem definition */}}Fair Isaac Corporation Confidential and Proprietary Information

317

BCL in .NET

7.1.2

QCQP Example
The following is an implementation with BCL .Net of the QCQP example described in Section
3.5.1:
using BCL;
namespace Examples{
public class xbexpl1i{
const int MAXNJ = 4;
const int NT = 10;/* Max. number of jobs *//* Time limit *///Define XPRBDATAPATH to whatever folder you wish.
const string XPRBDATAPATH = "../../data";
const string DATAFILE = XPRBDATAPATH + "/jobs/durations.dat";/**** DATA ****/
static int NJ = 0;/* Number of jobs read in */static double[] DUR = new double[MAXNJ]; /* Durations of jobs*/
static XPRBindexSet Jobs;
static XPRBvar[] start;
static XPRBvar[,] delta;
static XPRBvar z;/* Job names *//* Start times of jobs *//* Binaries for start times *//* Maximum completion time (makespan) */XPRBprob p;/* BCL problem */static void readData(){
string name;
FileStream file;
StreamReader fileStreamIn;/* Create a new index set */Jobs = p.newIndexSet("jobs", MAXNJ);

file = new FileStream(DATAFILE, FileMode.Open, FileAccess.Read);
fileStreamIn = new StreamReader(file);
object[] tempobj = new object[2];while((NJ<MAXNJ) &&(p.XPRBreadarrline(fileStreamIn, 99, "{t} , {g} ", out tempobj, 1) == 2)){
int dummy;
name = (string)tempobj[0];DUR[NJ] = (double)tempobj[1];dummy = Jobs + name;
NJ++;}
fileStreamIn.Close();file.Close();
System.Console.WriteLine("Number of jobs read: " + Jobs.getSize());}
static void jobsModel(){XPRBexpr le;
int j,t;/****VARIABLES****//* Create start time variables (incl. bounds) */start = new XPRBvar[NJ];if(start==null)

Fair Isaac Corporation Confidential and Proprietary Information

318

BCL in .NET{
System.Console.WriteLine("Not enough memory for ’start’ variables.");return;}for (j = 0; j < NJ; j++)start[j] = p.newVar("start", BCLconstant.XPRB_PL, 0, NT - DUR[j] + 1);
z = p.newVar("z",BCLconstant.XPRB_PL,0,NT); /* Declare the makespan variable */delta = new XPRBvar[NJ, NT];for(j=0;j<NJ;j++)/* Declare binaries for each job */for(t=0;t<(NT-DUR[j]+1);t++)delta[j,t] = p.newVar("delta" + Jobs.getIndexName(j) + "_" + (t+1),
BCLconstant.XPRB_BV);/****CONSTRAINTS****/
for(j=0;j<NJ;j++)/* Calculate maximal completion time */p.newCtr("Makespan", start[j]+DUR[j] <= z);p.newCtr("Prec", start[0]+DUR[0] <= start[2]);/* Precedence relation between jobs */for(j=0;j<NJ;j++)/* Linking start times and binaries{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += (t+1)*delta[j,t];p.newCtr("Link_" + (j+1), le == start[j]);}*/for(j=0;j<NJ;j++)/* One unique start time for each job{
le = new XPRBexpr(0);for(t=0;t<(NT-DUR[j]+1);t++) le += delta[j,t];p.newCtr("One_" + (j+1), le == 1);}/****OBJECTIVE****/
p.setObj(p.newCtr(z));
jobsSolve();*//* Define and set objective function *//* Solve the problem */}void jobsSolve(){
int j,t,statmip;
for(j=0;j<NJ;j++)for(t=0;t<NT-DUR[j]+1;t++)delta[j,t].setDir(BCLconstant.XPRB_PR,10*(t+1));/* Give highest priority to variables for earlier start times */p.setSense(BCLconstant.XPRB_MINIM);
p.mipOptimize();/* Solve the problem as MIP */statmip = p.getMIPStat();/* Get the MIP problem status */if((statmip == BCLconstant.XPRB_MIP_SOLUTION) ||(statmip == BCLconstant.XPRB_MIP_OPTIMAL)){ /* An integer solution has been found */System.Console.WriteLine("Objective: " + p.getObjVal());
for(j=0;j<NJ;j++){/* Print the solution for all start times */System.Console.WriteLine(start[j].getName() + ": " + start[j].getSol());
for(t=0;t<NT-DUR[j]+1;t++)System.Console.Write(delta[j,t].getName()+ ": "+delta[j,t].getSol()+" ");System.Console.WriteLine();}}}public static void Main()

Fair Isaac Corporation Confidential and Proprietary Information

319

BCL in .NET{
XPRB.init();p = new XPRBprob("Jobs");
readData();jobsModel();/* Create a new problem *//* Read in the data *//* Basic problem definition */

}
}
}

7.1.3

Error handlingIf an error occurs, BCL .NET behaves like the C interface, that is, it prints an error message andterminates the program. Alternatively, if BCL error handling is disabled by calling
XPRBprob.setErrCtrl(0), then all error messages are sent to the user-defined error callback
without terminating the program; the user can both check these error messages and the return
codes of each method to verify if it has completed correctly. The only case where a BCLExceptions
is raised is when an error occurs while constructing a BCLexpr object. Below we show a .NET
implementation of the example of user error handling with BCL from Section 3.6. Other features
demonstrated by this example include

redirection of the BCL output stream for the whole program and for an individual problem;setting the BCL message printing level;using System;
using BCL;
namespace Examples{
public class UGExpl3{
public static int rtsbefore = 1;
public void modexpl3(ref XPRBprob prob){
XPRBvar[] x = new XPRBvar[3];
XPRBctr[] ctr = new XPRBctr[2];
XPRBexpr cobj;
int i;
for(i=0;i<2;i++)x[i] = prob.newVar("x_"+i, BCLconstant.XPRB_UI, 0, 100);/* Create the constraints:
C1: 2x0 + 3x1 >= 41
C2: x0 + 2x1 = 13 */XPRBexpr C1linexp = new XPRBexpr();
XPRBexpr C2linexp = new XPRBexpr();C1linexp = 2 * x[0] + 3 * x[1];C2linexp = x[0] + 2 * x[1];prob.newCtr("C1", C1linexp >= 41);prob.newCtr("C2", C2linexp == 13);/* Uncomment the following line to cause an error in the model thattriggers the user error handling: */// x[3] = prob.newVar("x_2", BCLconstant.XPRB_UI, 10, 1);/* Objective: minimize x0+x1 */cobj = new XPRBexpr(0);for(i=0;i<2;i++) cobj += x[i];prob.setObj(prob.newCtr("OBJ", cobj));prob.setSense(BCLconstant.XPRB_MINIM); /* Set objective sense to minimization */prob.print();/* Print current problem definition */Fair Isaac Corporation Confidential and Proprietary Information

320

BCL in .NET

prob.lpOptimize();/* Solve the LP */prob.printF("Problem status: " + prob.getProbStat() +" LP status: " + prob.getLPStat() + " MIP status: " +prob.getMIPStat() + "\n");/* This problem is infeasible, that means the following command will fail.
* It prints a warning if the message level is at least 2 */prob.printF("Objective: " + prob.getObjVal() + "\n");/* Print solution values */for(i=0;i<2;i++)prob.printF(x[i].getName() + ":" + x[i].getSol() + ", ");prob.printF("\n");}/***********************************************************************//**** User error handling function ****/
public static void usererror(IntPtr prob, object vp, int num, int type, string t){
Exception eBCL = new Exception("Error in usererror().");
System.Console.WriteLine("BCL error " +num+ ": " + t);if(type==BCLconstant.XPRB_ERR) throw eBCL;}/**** User printing function ****/
public static void userprint(IntPtr prob, object vp, string msg){/* Print ’BCL output’ whenever a new output line starts,
otherwise continue to print the current line. */if(rtsbefore==1) System.Console.Write("BCL output: " + msg);
else System.Console.Write(msg);
rtsbefore = (msg.Length>0 && msg[msg.Length-1]==’\n’) ? 1 : 0;}/***********************************************************************/// This is where one might add custom logging
static void DoSomeErrorLogging(string msg){
Console.WriteLine("Here’s an error message! {0}", msg);}
public static int Main(){try{/* Switch to error handling by the user’s program */XPRB.setErrCtrl(0); // no auto quit on error
int initCode = XPRB.init();if (initCode != 0 && initCode != 32) // both values are valid{
DoSomeErrorLogging(Optimizer.XPRS.GetLicErrMsg());
return initCode;}
UGExpl3 TestInstance = new UGExpl3();
XPRBprob prob = new XPRBprob("EXPL3");
if (!prob.isValid()){
DoSomeErrorLogging("Unable to create XPRBprob \"EXPL3\"");
return 1;}/* Set the printing flag. Try other values:
0 - no printed output, 1 - only errors,
2 - errors and warnings, 3 - all messages */prob.setMsgLevel(2);Fair Isaac Corporation Confidential and Proprietary Information

321

BCL in .NET/* Define the printing callback function */prob.MessageCallbacks += new XPRBMessageCallback(userprint);
try{
prob.ErrorCallbacks += new XPRBErrorCallback(usererror);
TestInstance.modexpl3(ref prob); /* Formulate and solve the problem */System.Console.WriteLine("I’m about to exit cleanly");
return 0;}
catch{
System.Console.WriteLine("I cannot build the problem");return 1;
}
}
catch
{
System.Console.WriteLine("I cannot create the problem");return 1;
}
}
}
}

7.2

.NET class reference
The complete set of classes of the BCL .NET interface is summarized in the following list. For adetailed documentation of the .NET interface the reader is referred to the BCL .NET HTML NDoc
that is part of the Xpress distribution (located in subdirectory docs/bcl/bcl.net/HTML of theXpress installation directory).
XPRB

Initialization and general settings, definition of all parameters.

XPRBprob

Problem definition, including methods for creating and deleting themodeling objects, problem solving, changing settings, and retrieving
solution information.

XPRBvar

Methods for modifying and accessing variables.

XPRBctr

Methods for constructing, modifying and accessing constraints.

XPRBcut

Methods for constructing, modifying and accessing cuts.

XPRBsol

Methods for constructing, modifying and accessing solutions.

XPRBsos

Methods for constructing, modifying and accessing Special Ordered
Sets.

XPRBindexSet

Methods for constructing and accessing index sets and accessing set
elements.

XPRBbasis

Methods for accessing bases.

XPRBexpr

Methods for constructing linear and quadratic expressions.

XPRBrelation

Methods for constructing linear or quadratic relations from expressions(extends XPRBexpr).

XPRBterm

Methods for initialisation and handling of XPRBterm objects.

XPRBVersion

Version number in its encoded form.

Fair Isaac Corporation Confidential and Proprietary Information

322

BCL in .NET

BCLconstant

All BCL related constants.

BCLExceptions

Methods for BCL Exceptions.

ScannerClass for reading file data in to objects in a similar manner to scanf().

All .NET classes that have a direct correspondence with modeling objects in BCL (namely
XPRBprob, XPRBvar, XPRBctr, XPRBcut, XPRBsol, XPRBsos, XPRBindexSet, XPRBbasis) take the samenames, with the exception of XPRBindexSet. It is possible to obtain the Xpress Optimizer problem
corresponding to a BCL .NET problem by using method getXPRSprob of class XPRBprob, please see
Section B.8 for further detail on using BCL with the Optimizer library.
Most of the methods of the classes with direct correspondence with C modeling objects callstandard BCL C functions and return the same result codes.
Two important classes that do not correspond to any standard BCL modeling object is class XPRB
that contains methods relating to the initialization and the general status of the software andclass BCLconstant that contains the definition of all constant parameters. This means, any
parameter with the prefix XPRB_ in standard BCL is referred to as a constant member of the .NET
class BCLconstant. For example, XPRB_BV in standard BCL becomes BCLconstant.XPRB_BV in .NET.
In .NET, some additional classes have been introduced to aid the termwise definition of
constraints. Linear and quadratic expressions (class XPRBexpr) are required in the definition of
constraints and Special Ordered Sets. Linear or quadratic relations (class XPRBrelation), may be
used as an intermediary in the definition of constraints.
A couple of other additional classes are related to error handling and data input, namely
BCLExceptions which represent exceptions raised when errors occur while building constraints;
and Scanner which is used internally to implement the XPRBprob.XPRBreadline and
XPRBprob.XPRBreadarrline methods.

Fair Isaac Corporation Confidential and Proprietary Information

323

Appendix

A PPENDIX A

BCL error messages
There are two types of error messages displayed by BCL. Those marked ‘E’ (for Error) in thefollowing list stop the execution of the program. Those marked ‘W’ (for Warning) do notinterrupt the program. The marker ‘fct’ indicates that the name of the function where the error
occurred will be printed out.
E-1501(fct) No active problem.
Function fct has been called with an invalid problem argument. Check whether the
problem has been created (function XPRBnewprob).

E-1502Not enough memory.
It is not possible to allocate the required amount of memory needed for BCL objects.

E-1504

Dictionary cannot be re-initialized.
Dictionary sizes can only be set immediately after the creation of a problem.

E-1505(fct) No variable given.
Function fct requires a variable of type XPRBvar as an input parameter. Check whether
the variable has been created (functions XPRBnewvar or XPRBnewarrvar).

E-1506(fct) No array of variables given.
Function fct requires an array of variables of type XPRBarrvar as an input parameter.
Check whether the array has been created (function XPRBnewarrvar or alternativelyfunctions XPRBstartarrvar and XPRBendarrvar).

E-1507(fct) No constraint given.
Function fct requires a constraint of type XPRBctr as an input parameter. Check whether
the constraint has been created (functions XPRBnewctr, XPRBnewsum, XPRBnewarrsum, or
XPRBnewprec).

E-1508(fct) No SOS given.
Function fct requires a SOS of type XPRBsos as an input parameter. Check whether theset has been created (functions XPRBnewsos, XPRBnewsosrc, or XPRBnewsosw).

E-1509(fct) No cut given.
Function fct requires a cut of type XPRBcut as an input parameter. Check whether the
cut has been created (functions XPRBnewcut, XPRBnewcutsum, XPRBnewcutarrsum, or
XPRBnewcutprec).

E-1510(fct) No basis given.
Function fct requires a basis of type XPRBbasis as an input parameter. Check whether
the basisi has been saved (function XPRBsavebasis).

E-1512(fct) No array of constants given.
Function fct requires an array of constants as an input parameter.

Fair Isaac Corporation Confidential and Proprietary Information

325

BCL error messages

W-1513(fct) No variable given.
Function fct requires a variable of type XPRBvar as an input parameter. The command isbeing ignored.

W-1514(fct) No constraint given.
Function fct requires a constraint of type XPRBctr as an input parameter. The commandis being ignored.

E-1515(fct) Problem has no ‘name’.
The problem definition is incomplete (at least one variable and one constraint or one
non-zero objective coefficient must be defined).

W-1516(fct) Problem has no ‘name’.
The problem definition may be incomplete (at least one variable and one constraint or
one non-zero objective coefficient must be defined).

W-1518(fct) No SOS given.
Function fct requires a Special Ordered Set of type XPRBsos as an input parameter. The
command is being ignored.

W-1519(fct) No cut given.
Function fct requires a cut of type XPRBcut as an input parameter. The command is being
ignored.

W-1520(fct) No solution available or problem modified since last solved.
Function fct is trying to access solution information which is not available for the current
problem.

E-1521

Xpress Optimizer error getting objective function value.
The objective function value cannot be obtained from Xpress Optimizer.

E-1522

Xpress Optimizer error getting ‘name’ status.
Xpress Optimizer solution status information cannot be obtained.

E-1523

Unknown solution option ‘char’.
Possible options for XPRBlpoptimize or XPRBmipoptimize include ’b’, ’d’, ’g’, ’l’, ’n’,’p’, ’c’. Refer to the reference manual for details.

E-1524(fct) Xpress Optimizer error num during ‘name’. Return value: val.
An Xpress Optimizer error has occurred while executing the Optimizer function name.
Refer to the Optimizer Reference Manual for details on the error number num andreturn value val.

W-1525(fct) Different problem loaded in Xpress Optimizer.
(Solution) information is being sought from the Xpress Optimizer on a problem that is
not the active problem in Xpress Optimizer. It may be necessary to (re)solve the problem
to access this information, or at least, reload the matrix.

E-1526(fct) Empty problem or problem not loaded in Xpress Optimizer.
(Solution) information is being sought on a problem that has not yet been loaded into
Xpress Optimizer. It may be necessary to solve the problem to access this information, orat least, load the matrix into Xpress Optimizer.

W-1527

Loading MIP solution failed. Return value: val.
The specified MIP solution has not been loaded into BCL. Please see the documentationof function XPRBloadmipsol for an explanation of the return values.

E-1530(fct) Inconsistent bounds for variable ‘name’ (bdl,bdu).
The lower bound is greater than the upper bound for the given variable.

Fair Isaac Corporation Confidential and Proprietary Information

326

BCL error messages

E-1531(fct) Incorrect type for variable ‘name’.
No type, or an incorrect type, has been specified for a variable. See the list of possible
values in the reference manual (function XPRBsetvartype).

E-1535(fct) Incorrect type for constraint ‘name’.
No type, or an incorrect type, has been specified for a constraint. See the list of possible
values in the reference manual (function XPRBsetctrtype).

E-1536(fct) Inconsistent range for constraint ‘name’ (bdl,bdu).
The lower range bound is greater than the upper bound for the given constraint.

E-1538(fct) Setting ‘descr’ can only be applied to standard constraints.
’Model cut’, ’delayed constraint’, ’include vars’ and ’indicator constraint’ are mutually
exclusive flags. A constraint for which one of these flags is set cannot be turned into oneof the other types without previously resetting the corresponding flag (using theappropriate function XPRBsetincvars, XPRBsetmodcut, XPRBsetdelayed, or
XPRBsetindicator with argument value 0).

E-1539(fct) Incorrect constraint type for indicator constraint ‘name’.
Indicator constraints must be inequalities or range constraints.

E-1540(fct) Trying to modify a closed array of variables (‘name’).
It is not possible to make changes to an array of variables after its definition has been
terminated with XPRBendarrvar.

E-1541(fct) Index num1 out of range for an array of variables (‘name’ max = num2).
Trying to store too many elements in an array of variables or addressing an index
beyond its size.

E-1542(fct) Trying to add an entry (‘name’) to a complete array of variables (‘name’).
If the number of elements of the array of variables corresponds to its size, it is notpossible to add any further variables.

E-1543(fct) Trying to close an incomplete array of variables (‘name’).
Not all elements of an array of variables that is being closed with XPRBendarrvar havebeen defined.

E-1545(fct) Wrong type for SOS ‘name’.
No type, or an incorrect type, has been specified for a SOS. See the list of possible values
in the reference manual (function XPRBgetsostype).

E-1546(fct) Name too long (max = num ‘name’).
A user-defined name exceeds the maximum length (see documentation of function
XPRBnewname).

E-1547(fct) Wrong directive type.
No type, or an incorrect type, has been specified for a directive. See the list of possible
values in the reference manual (functions XPRBsetvardir or XPRBsetsosdir).

E-1550(fct) No index set given.
Function fct requires an index set of type XPRBidxset as an input parameter. Check
whether the index set has been created (function XPRBnewidxset).

W-1551(fct) No name given for an element of an index set.
Function fct requires an index name as input parameter. The command is being ignored.

W-1552(fct) No index set given.
Function fct requires an index set of type XPRBidxset as an input parameter. The
command is being ignored.

Fair Isaac Corporation Confidential and Proprietary Information

327

BCL error messages

W-1555

Incorrect IIS index given (num).
The specified index value num does not correspond to an IIS set (IIS set indices are
positive numbers). The command is being ignored.

E-1560No Xpress BCL license found. Please contact Xpress Support to obtain a license
No valid BCL license has been found. If you did install a license, check whether you havecopied it to the right place and that all environment variables and paths for BCL and theXpress Optimizer are set correctly.

E-1561(fct) Initialization failed (value: num).
Xpress Optimizer could not be initialized (error code num).

W-1562(fct) Working with Student License.
BCL is running in Student mode; this mode implies restrictions to the available
functionality and to the accepted problem size.

E-1563(fct) Inconsistency during matrix generation.
Internal error during the matrix generation.

E-1565(fct) Internal error.
Internal error during the matrix generation.

E-1566

Name too long: ‘name’.
A user-defined or BCL composed name exceeds the maximum length. (Remember that
BCL adds indices to names if they already exist.)

E-1567(fct) Size limits of the Student License exceeded.
The specified model is too large to be run with the Student License.

W-1568Operation fct not allowed in Student License.
You are not authorized to execute function fct with the Student License of BCL.

W-1570

XPRS: text
Refer to the Optimizer Reference Manual for the indicated error.

E-1571text
The initialization has not found a valid license.

E-1572(fct) No Xpress Optimizer problem given.
The function fct requires an argument of type XPRSprob.

W-1573‘fct1’ without matching ‘fct2’.
The indicated functions (e.g., XPRBbegincb / XPRBendcb) must always be used as a pair.

E-1575(fct) Unexpected argument value val.
The value val lies outside the accepted range of values for the indicated function.

W-1580Unknown output file format format.
Refer to the documentation of function XPRBexportprob for admissible output format
options.

E-1582

Internal error writing MPS file.
Please contact Xpress Support.

W-1587

Switch to cut mode.
The cut mode probably needs to be enabled (function XPRBsetcutmode) before thisfunction is called.

E-1591(fct) Non-quadratic term.
A term of the objective function has a power higher than 2.

Fair Isaac Corporation Confidential and Proprietary Information

328

BCL error messages

W-1592(fct) Setting limit for variable ‘name’ of wrong type.
Cannot set the integer limit because the given variable is not a partial integer,semi-continuous or semi-continuous integer variable.

W-1593(fct) Setting limit lim for variable ‘name’ outside bounds (bdl,bdu).
The new integer limit is outside the bounds for the given variable or is negative.

E-1594(fct) Setting ‘descr’ can only be applied to non-binding (type N) constraints.
Only a non-binding (type XPRB_N) constraint can be set to be an ’Include vars’ special
constraint.

E-1595(fct) Incorrect constraint type for include vars constraint ‘name’.
Include vars constraints must be non-binding constraints (constraints of type XPRB_N).

W-1596

Adding MIP solution failed. Error loading matrix (val).
The specified MIP solution has not been added because the current problem definition
could not be loaded into the Optimizer.

E-1597(fct) No solution given.
Function fct requires a solution of type XPRBsol as an input parameter. Check whether
the solution has been created (function XPRBnewsol).

W-1598(fct) No solution given.
Function fct requires a solution of type XPRBsol as an input parameter. Check whether
the solution has been created (function XPRBnewsol).

W-1599(fct) Removing var name, set to a NaN value, from solution.
Variables cannot be assigned NaN values (not a number) in a solution. Therefore variablename is removed from the solution (if present) to avoid ambiguities with its previously
assigned value.

Fair Isaac Corporation Confidential and Proprietary Information

329

A PPENDIX B

Using BCL with the Optimizer library
BCL provides both modeling and basic optimization functions, which correspond to thefunctionality of Xpress Mosel, or of the functions of the Xpress Optimizer library in ‘Console
Mode’, respectively. However, if the user wishes to access the more advanced features of the
Optimizer, obtain additional information, or change algorithm settings, the relevant Optimizer
library functions have to be used directly.
The following sections explain in more detail how to use Optimizer library functions within a BCL
program. The first section lists those functions which are compatible with BCL. It is followed bysome general remarks about initialization, loading the matrix and the use of indices. The lastsection contains some typical examples for the use of BCL-compatible Optimizer functions in BCL
programs.
Important: If a program uses Optimizer library functions the Optimizer header file has to be
included in addition to the BCL header file. That is, the first lines of the program should containthe following:#include "xprb.h"#include "xprs.h"

B.1

Switching between libraries
Generally speaking, there are two types of Optimizer library functions: those that accessinformation about a problem or change settings for the search algorithms, and those that makechanges to the problem definition. The first group of functions may be used in a BCL program
without any problem. The second group requires the user to switch completely to the Optimizer
library, for instance after a problem has been defined in BCL and the matrix has been loaded into
the Optimizer.

B.1.1

BCL-compatible Optimizer functions
The following Optimizer library functions may be used with BCL (however, some caution isrequired with all functions that take column or row indices as input parameters, see Section B.4
below. Furthermore, the solution information in BCL is only updated automatically at the end of
the search, in the global callbacks—not for parallelized MIP—it needs to be updated by calling
XPRBsync with the parameter XPRB_XPRS_SOL or XPRB_XPRS_SOLMIP):

setting and accessing problem and control parameters: functions XPRSsetintcontrol,
XPRSgetintcontrol, XPRSgetintattrib etc.;

output and saving: functions XPRSsave, XPRSwritebasis, XPRSrange, XPRSiis,
XPRSwriteprtsol, XPRSwritesol, XPRSwriteprtrange, XPRSwriterange, XPRSgetlpsol,

Fair Isaac Corporation Confidential and Proprietary Information

330

Using BCL with the Optimizer library

XPRSgetmipsol,XPRSwriteomni, XPRSwriteprob, all logging and solution callbacks with the
exception of XPRSsetcbmessage that is used by BCL and must not be re-defined by the user;

B.1.2



accessing information: all functions XPRSget...,;

settings for algorithms: XPRSreaddirs, XPRSloaddirs, XPRSreadbasis, XPRSloadbasis,
XPRSloadsecurevecs, XPRSscale, XPRSftran, XPRSbtran, all global callbacks;cut manager.

Incompatible Optimizer functions
The following Optimizer library functions may be used only after or in place of BCL:
changing, adding, and deleting matrix elements: all functions XPRSadd..., XPRSchg...,XPRSdel...;

solution algorithms: XPRSlpoptimize, XPRSmipoptimize;

input of data or problem(s): XPRSreadprob, XPRSloadlp, XPRSloadglobal, XPRSloadqglobal,
XPRSloadqp, XPRSalter, XPRSsetprobname;

manipulation of the matrix: XPRSrestore;

callback: XPRSsetcbmessage

Once any of the functions in the preceding list have been called for a given problem, theinformation held in BCL may be different from the problem in the Optimizer and it is not possible
to update BCL accordingly. The program must therefore continue using only Optimizer libraryfunctions on that problem, that is, switch completely to the Optimizer library. The ‘switching’from BCL to the Optimizer library always refers to a single problem. If other problems are being
worked on in parallel, for which none of the above incompatible function have been called, users
can continue to work with them using BCL functions.

B.2

Initialization and termination
The Optimizer library is initialized at the same time as BCL and so there is no need to call the
Optimizer library initialization function, XPRSinit, from a user program. In standard use of BCL
the function XPRBnewprob calls the BCL initialization function XPRBinit that automaticallyinitializes the Optimizer if this is the first call to XPRBinit. In very large applications or integration
with other systems it may be preferrable to call XPRBinit explicitly to separate the initializationfrom the definition of the problem(s).
At the end of the program, the normal BCL termination routine should be applied, first releasing
any memory associated to problems using XPRBdelprob and subsequently calling XPRBfree to tidy
up. These routines also free memory associated with the Optimizer library and hence neither ofthe XPRSdestroyprob or XPRSfree functions must be used. However, if one wishes to continue
working with the Optimizer after terminating BCL, the Optimizer needs to be initialized (possibly
before initializing BCL) and terminated separately.
Thus, the standard use of BCL is as follows:
XPRBprob prob;
prob = XPRBnewprob("Example1");...
/* Define and solve the problem */Integration of a BCL problem into some larger application:

Fair Isaac Corporation Confidential and Proprietary Information

331

Using BCL with the Optimizer library

XPRBprob prob;
XPRBinit("");...
/* Perform other initialization tasks */prob = XPRBnewprob("Example1");...
/* Define and solve the problem */XPRBdelprob(prob);
XPRBfree();

B.3

Loading the matrix
BCL loads the matrix into the Optimizer library whenever (through BCL) an action is required
from the Optimizer and the matrix in the Optimizer does not correspond to the one in BCL. Thismeans, if a user wishes to switch to using Optimizer library commands, for instance for
performing the optimization, he should explicitly load the current BCL problem into the
Optimizer (function XPRBloadmat).
Since both BCL and the Optimizer require separate problem pointers to specify the problem
being worked on, there is an issue about how to obtain the Optimizer problem pointer referring
to a problem just loaded by BCL. Such issues are handled using the function XPRBgetXPRSprob,
which returns the required Optimizer pointer. It should be noted that no call to XPRScreateprob isnecessary in this instance, as the problem is created by BCL at the point that it is first passed to
the Optimizer.
Standard use of BCL:
XPRBarrvar x;...
x = XPRBnewarrvar(prob, 10, XPRB_PL, "x", 0, 100);...
/* (Define the rest of the problem) */XPRBsetsense(prob, XPRB_MAXIM); /* Set sense to maximization */XPRBlpoptimize(prob,"");/* Load matrix and maximize LP problem */for(i=0; i<10; i++)/* Print solution values for variables */printf("%s: %d, ",XPRBgetvarname(prob,x[i]),XPRBgetsol(prob,x[i]));

Switch to using the Optimizer library after problem input with BCL:
XPRBprob bcl_prob;
XPRSprob opt_prob;
XPRBarrvar x;
int i, cols, len, offset;
double *sol;char *names;
bcl_prob = XPRBnewprob("Example1"); /* Initialize BCL (and the Optimizer
library) and create a new problem */x = XPRBnewarrvar(bcl_prob, 10, XPRB_PL, "x", 0, 100);...
/* Define the rest of the problem */XPRBloadmat(bcl_prob);/* Load matrix into the Optimizer */opt_prob = XPRBgetXPRSprob(bcl_prob);/* Get the Optimizer problem */XPRSchgobjsense(opt_prob,XPRS_OBJ_MAXIMIZE); /* Select maximization */XPRSlpoptimize(opt_prob,""); /* Maximize the LP problem */XPRSgetintattrib(opt_prob, XPRS_ORIGINALCOLS, &cols);/* Get the number of columns */sol = malloc(cols * sizeof(double));XPRSgetlpsol(opt_prob, sol, NULL, NULL, NULL);/* Get entire primal solution */XPRSgetnamelist(opt_prob, 2, NULL, 0, &len, 0, cols-1);/* Get number of bytes required for
retrieving names */names = (char *)malloc(len*sizeof(char));
XPRSgetnamelist(opt_prob, 2, names, len, NULL, 0, ncol-1);

Fair Isaac Corporation Confidential and Proprietary Information

332

Using BCL with the Optimizer library/* Get the variable names */offset=0;
for(i=0; i<cols; i++) {/* Print all solution values */printf("%s: %g, ", names+offset, sol[i]);offset += strlen(names+offset)+1;}

B.4

Indices of matrix elements
The row and column indices that are returned by the BCL functions XPRBgetrownum and
XPRBgetcolnum correspond to the position of variables and constraints in the unpresolved matrix
with empty rows or columns removed. The position of matrix elements may be modified by thepresolve/preprocessing algorithms. That means, if these algorithms are not switched off (control
parameters XPRS_PRESOLVE and XPRS_MIPPRESOLVE), the indices for variables and constraints held
by BCL should not be used with any Optimizer library functions. The same rule applies to any
other variable or constraint-specific information, such as solution and dual values. This problem
does not occur within BCL (that is, if only BCL functions are used) since the solution information isaccessible only after the optimization run has finished and the postsolve has been performed by
the Optimizer.
An exception from the rule stated above are the Optimizer library functions XPRSgetlpsol /XPRSgetmipsol: XPRSgetlpsol may be used, for instance, in Optimizer library callback functions
during the global search to access the current solution values, and in combination with theindices for variables and constraints held by BCL. This is possible because XPRSgetlpsol /XPRSgetmipsol return the postsolved solution.

B.5

Using BCL-compatible functions
The Optimizer library functions that are most likely to be used in a BCL program are those forsetting and accessing control and problem parameters, as shown in the following examples. The
control parameters can be set and accessed at any time after the software has been initialized(see Section B.2). The problem attributes only return the problem-specific values once theproblem has been loaded into the Optimizer. Note that all the parameters take their default
values at the beginning of a BCL program but they are not reset if several problems are solved ina single program and changes are made to the parameter values along the way.
Setting control parameters:
XPRBprob bcl_prob;
XPRSprob opt_prob;
bcl_prob = XPRBnewprob("Example1"); /* Initialize BCL (and the Optimizer
library) and create a new problem */...
/* Define the problem */XPRBloadmat(bcl_prob);
opt_prob = XPRBgetXPRSprob(bcl_prob);
XPRSsetintcontrol(opt_prob, XPRS_MAXTIME, 60);/* Set a time limit of 60 seconds */XPRSsetdblcontrol(opt_prob, XPRS_MIPADDCUTOFF, 0.999);/* Set an ADDCUTTOFF value */XPRBsetsense(bcl_prob, XPRB_MAXIM); /* Select maximization */XPRBlpoptimize(bcl_prob,"");/* Load matrix and solve as LP problem */Accessing problem parameters:
int rows;
XPRBprob bcl_prob;

Fair Isaac Corporation Confidential and Proprietary Information

333

Using BCL with the Optimizer library

XPRSprob opt_prob;
bcl_prob = XPRBnewprob("Example1"); /* Initialize BCL (and the Optimizer
library) and create a new problem */...
/* Define the problem */XPRBloadmat(bcl_prob);/* Load matrix into the Optimizer */opt_prob = XPRBgetXPRSprob(bcl_prob);
XPRSgetintattrib(opt_prob, XPRS_ORIGINALROWS, &rows);/* Get number of rows */XPRBsetsense(bcl_prob, XPRB_MAXIM); /* Select maximization */XPRBlpoptimize(bcl_prob,"");/* Load matrix and solve as LP problem */Another likely set of functions are the Optimizer library callbacks for solution printout andpossibly for directing the branch and bound search (see the remarks about indices in Section B.4):
void XPRS_CC printsol(XPRSprob opt_prob,void *my_object){
XPRBprob bcl_prob
XPRBvar x;
int num;
bcl_prob = (XPRBprob)my_object;
XPRBbegincb(bcl_prob, opt_prob);/* Use local Optimizer problem in BCL */XPRSgetintattrib(opt_prob, XPRS_MIPSOLS, &num);/* Get number of the solution */XPRBsync(bcl_prob, XPRB_XPRS_SOL);/* Update BCL solution values */XPRBprintf(bcl_prob, "Solution %d: Objective value: %g\n",num, XPRBgetobjval(bcl_prob));x = XPRBgetbyname(bcl_prob, "x_1", XPRB_VAR);
if(XPRBgetcolnum(x)>-1)/* Test whether variable is in thematrix */XPRBprintf(bcl_prob, "%s: %g\n", XPRBgetvarname(x), XPRBgetsol(x));
XPRBendcb(bcl_prob);/* Reset BCL to main problem */}int main(int argc, char **argv){
XPRBprob bcl_prob;
XPRSprob opt_prob;
XPRBvar x;
bcl_prob = XPRBnewprob("Example1"); /* Initialize BCL (and the Optimizer
library) and create a new problem */x = XPRBnewvar(bcl_prob,XPRB_BV,"x_1",0,1);/* Define a variable */...
/* Define the rest of the problem */opt_prob = (XPRSprob)XPRBgetXPRSprob(bcl_prob);
XPRSsetcbintsol(opt_prob, printsol, bcl_prob);/* Define an integer solution callback */XPRBsetsense(bcl_prob, XPRB_MAXIM); /* Select maximization */XPRBmipoptimize(bcl_prob,"");/* Solve as MIP problem */}The synchronization between BCL and the Optimizer during the MIP search requires some special
care. The code extract above shows how to use the functions XPRBbegincb and XPRBendcb tocoordinate the BCL solution information with the Optimizer subproblem in a default
multi-threaded MIP search. Alternatively, you may choose to disable parallelism by setting the
XPRS_MIPTHREADS control to 1.
opt_prob = XPRBgetXPRSprob(bcl_prob);
XPRSsetintcontrol(opt_prob, XPRS_MIPTHREADS, 1);/* Use single-threaded MIP */MIP solution information can also be accessed through the Optimizer library functions whereby it

Fair Isaac Corporation Confidential and Proprietary Information

334

Using BCL with the Optimizer libraryis possible to use the column or row indices saved for BCL modeling objects as shown below. In
this case there is no need for synchronizing the BCL solution information.
void XPRS_CC printsol(XPRSprob opt_prob,void *my_object){
int num,ncol;
XPRBprob bprob;
XPRBvar x;
double *sol, objval;
bprob = (XPRBprob)vp;
XPRSgetintattrib(oprob, XPRS_ORIGINALCOLS, &ncol);/* Get the number of columns */sol = (double *)malloc(ncol * sizeof(double));/* Create the solution array */XPRSgetintattrib(oprob, XPRS_MIPSOLS, &num); /* Get number of the solution */XPRSgetlpsol(oprob, sol, NULL, NULL, NULL); /* Get the solution values */XPRSgetdblattrib(oprob, XPRS_LPOBJVAL, &objval);printf("Solution %d: Objective value: %g\n", num, objval);
x = XPRBgetbyname(bprob, "x_1", XPRB_VAR);
if(XPRBgetcolnum(x)>-1)
printf("%s: %g\n", XPRBgetvarname(x), sol[XPRBgetcolnum(x)]);free(sol);}

B.6

Using the Optimizer with BCL C++
Everything that has been said above about the combination of BCL and Xpress Optimizer
functions remains true if the BCL program is written in C++.
The examples of BCL-compatible Optimizer functions in the previous section become:Setting and accessing parameters:
int rows;
XPRSprob opt_prob;
XPRBprob bcl_prob("Example1"); // Initialize BCL (and the Optimizer// library) and create a new problem...
// Define the problem
bcl_prob.loadMat();
opt_prob = bcl_prob.getXPRSprob();
XPRSsetintcontrol(opt_prob,XPRS_MAXTIME, 60);// Set a time limit of 60 seconds
XPRSsetdblcontrol(opt_prob,XPRS_MIPADDCUTOFF, 0.999);// Set an ADDCUTTOFF value
XPRSgetintattrib(opt_prob,XPRS_ORIGINALROWS, &rows);// Get number of rows
bcl_prob.setSense(XPRB_MAXIM); // Select maximization
bcl_prob.lpOptimize();// Maximize the LP problem

Using Xpress Optimizer callbacks (multi-threaded MIP):
void XPRS_CC printsol(XPRSprob opt_prob,void *my_object){
XPRBprob *bcl_prob
XPRBvar x;
int num;
bcl_prob = (XPRBprob*)my_object;bcl_prob->beginCB(opt_prob); // Use local Optimizer problem in BCL
XPRSgetintattrib(opt_prob, XPRS_MIPSOLS, &num);// Get number of the solution
bcl_prob->sync(XPRB_XPRS_SOL);// Update BCL solution values

Fair Isaac Corporation Confidential and Proprietary Information

335

Using BCL with the Optimizer librarycout << "Solution " << num << ": Objective value: ";cout << bprob->getObjVal() << endl;
x = bcl_prob->getVarByName("x_1");
if(x.getColNum()>-1)// Test whether variable is in the// matrix
cout << x.getName() << ": " << x.getSol() << endl;
bcl_prob->endCB();// Reset BCL to main problem}
int main(int argc, char **argv){
XPRBprob bcl_prob;
XPRSprob opt_prob;
XPRBvar x;
bcl_prob = XPRBnewprob("Example1"); // Initialize BCL (and the Optimizer// library) and create a new problem
x = bcl_prob.newVar("x_1", XPRB_BV); // Define a variable...
// Define the rest of the problem
opt_prob = bcl_prob.getXPRSprob();
XPRSsetcbintsol(opt_prob, printsol, &bcl_prob);// Define an integer solution callback
bcl_prob.setSense(XPRB_MAXIM);// Select maximization
bcl_prob.mipOptimize();// Maximize the MIP problem}

The code extract below shows how to access MIP solution information directly through the
Optimizer library functions using the column or row indices saved for BCL modeling objects. In
this case there is no need for synchronization of BCL with the local solution information.
void XPRS_CC printsol(XPRSprob opt_prob,void *my_object){
XPRBprob *bcl_prob
XPRBvar x;
int num, ncol;
double *sol, objval;
bcl_prob = (XPRBprob*)my_object;
XPRSgetintattrib(opt_prob, XPRS_ORIGINALCOLS, &ncol);// Get the number of columns
sol = new double[ncol];// Create the solution array
XPRSgetintattrib(opt_prob, XPRS_MIPSOLS, &num);// Get number of the solution
XPRSgetlpsol(opt_prob, sol, NULL, NULL, NULL); // Get the solution
XPRSgetdblattrib(opt_prob, XPRS_LPOBJVAL, &objval);cout << "Solution " << num << ": Objective value: " << objval << endl;
x = bcl_prob->getVarByName("x_1");
if(x.getColNum()>-1)// Test whether variable is in the// matrix
cout << x.getName() << ": " << sol[x.getColNum()] << endl;
delete [] sol;}

As in the C case, it is possible within a BCL program written in C++ to switch entirely to Xpress
Optimizer (see Section B.3).

B.7

Using the Optimizer with BCL Java
Starting with Release 3.0 of BCL it is possible to combine BCL Java problem definition with directaccess to the Optimizer problem in Java. All that is said in the previous sections about
BCL-compatible functions remains true. The only noticeable difference is that the Optimizer Javaneeds to be initialized explicitly (by calling XPRSinit) before the Optimizer problem is accessed.
The following are Java implementations of the code extracts showing the use of BCL-compatible

Fair Isaac Corporation Confidential and Proprietary Information

336

Using BCL with the Optimizer libraryfunctions:
Setting and accessing parameters (this code throws the exceptions XPRSprobException and
XPRSexception):
int rows;
XPRB bcl;
XPRSprob opt_prob;
XPRBprob bcl_prob;
bcl = new XPRB();/* Initialize BCL */bcl_prob = bcl.newProb("Example1"); /* Create a new problem in BCL */XPRS.init();/* Initialize Xpress Optimizer */...
/* Define the problem */bcl_prob.loadMat();
opt_prob = bcl_prob.getXPRSprob();
opt_prob.setIntControl(XPRS.MAXTIME, 60);/* Set a time limit of 60 seconds */opt_prob.setDblControl(XPRS.MIPADDCUTOFF, 0.999);/* Set an ADDCUTTOFF value */rows = opt_prob.getIntAttrib(XPRS.ORIGINALROWS);/* Get number of rows */bcl_prob.setSense(XPRB.MAXIM); // Select maximization
bcl_prob.lpOptimize();// Maximize the LP problem

Using Xpress Optimizer callbacks (multi-threaded MIP):
static class IntSolCallback implements XPRSintSolListener{public void XPRSintSolEvent(XPRSprob opt_prob, Object my_object){
XPRBprob bcl_prob
XPRBvar x;
int num;
bcl_prob = (XPRBprob)my_object;try {bcl_prob.beginCB(opt_prob);/* Use local Optimizer problem in BCL */num = opt_prob.getIntAttrib(XPRS.MIPSOLS);/* Get number of the solution */bcl_prob.sync(XPRB.XPRS_SOL);/* Update BCL solution values */System.out.println("Solution " + num + ": Objective value: " +bcl_prob.getObjVal());
x = bcl_prob.getVarByName("x_1");
if(x.getColNum()>-1)/* Test whether variable is in thematrix */System.out.println(x.getName() + ": " + x.getSol());
bcl_prob.endCB();/* Reset BCL to main problem */}catch(XPRSprobException e) {System.out.println("Error " + e.getCode() + ": " + e.getMessage());}}}
public static void main(String[] args) throws XPRSexception{
XPRB bcl;
XPRBprob bcl_prob;
XPRSprob opt_prob;
IntSolCallback cb;
XPRBvar x;
bcl = new XPRB();
bcl_prob = bcl.newProb("Example1");
XPRS.init();/* Initialize BCL *//* Create a new problem in BCL *//* Initialize Xpress Optimizer */Fair Isaac Corporation Confidential and Proprietary Information

337

Using BCL with the Optimizer libraryx = bcl_prob.newVar("x_1", XPRB_BV); /* Define a variable */...
/* Define the rest of the problem */opt_prob = bcl_prob.getXPRSprob();
cb = new IntSolCallback();
opt_prob.addIntSolListener(cb, bcl_prob);/* Define an integer solution callback */bcl_prob.setSense(XPRB.MAXIM);/* Select maximization */bcl_prob.mipOptimize();/* Maximize the MIP problem */}The code extract below shows how to access MIP solution information directly through the
Optimizer library functions using the column or row indices saved for BCL modeling objects. In
this case there is no need for synchronization of BCL with the local solution information.
static class IntSolCallback implements XPRSintSolListener{public void XPRSintSolEvent(XPRSprob opt_prob, Object my_object){
XPRBprob bcl_prob
XPRBvar x;
int num;
double [] sol;
bcl_prob = (XPRBprob)my_object;try {ncol = opt_prob.getIntAttrib(XPRS.ORIGINALCOLS);/* Get the number of columns */sol = new double[ncol];opt_prob.getSol(sol, null, null, null);/* Get the solution */num = opt_prob.getIntAttrib(XPRS.MIPSOLS);/* Get number of the solution */System.out.println("Solution " + num + ": Objective value: " +opt_prob.getDblAttrib(XPRS.LPOBJVAL));x = bcl_prob.getVarByName("x_1");
if(x.getColNum()>-1)/* Test whether variable is in thematrix */System.out.println(x.getName() + ": " + sol[x.getColNum()]);
sol = null;}
catch(XPRSprobException e) {System.out.println("Error " + e.getCode() + ": " + e.getMessage());
}
}
}

B.8

Using the Optimizer with BCL .NET
Using the Optimizer with BCL .NET is very similar to the other interfaces already seen and thesame considerations regarding BCL-compatible functions remain true. The BCL .NET interface also
requires an explicit intialization of the Optimizer .NET interface (by calling XPRS.Init()) before
the Optimizer problem is accessed.
The following are .NET implementations of the code extracts showing the use of BCL-compatible
functions:
Setting and accessing parameters:
int rows;
XPRB.init();// Initialize BCL
XPRS.Init();// Initialize Xpress Optimizer
XPRSprob opt_prob;
XPRBprob bcl_prob;
bcl_prob = new XPRBprob("Example1"); // Create a new problem in BCL

Fair Isaac Corporation Confidential and Proprietary Information

338

Using BCL with the Optimizer library...
// Define the problem
bcl_prob.loadMat();
opt_prob = bcl_prob.getXPRSprob();
opt_prob.MaxTime = 60;// Set a time limit of 60 seconds
opt_prob.MIPAddCutoff = 0.999; // Set an ADDCUTTOFF valuerows = opt_prob.OriginalRows; // Get number of rows
bcl_prob.setSense(BCLconstant.XPRB_MAXIM); // Select maximization
bcl_prob.lpOptimize();// Maximize the LP problem

Using Xpress Optimizer callbacks (multi-threaded MIP):
public class IntSolExample
public static void PrintSolution(XPRSprob opt_prob, object my_object){
XPRBprob bcl_prob = (XPRBprob)my_object;bcl_prob.beginCB(opt_prob);
int num = opt_prob.MIPSols;
bcl_prob.sync(BCLconstant.XPRB_XPRS_SOL); // Update BCL solution values
System.Console.WriteLine("Solution "+num+": Objective value: "+bcl_prob.getObjVal());
XPRBvar x = bcl_prob.getVarByName("x_1");
if( x.getColNum() > -1 ) // Test whether variable is in the matrix
System.Console.WriteLine(x.getName() + ": " + x.getSol());
bcl_prob.endCB();}public static void Main(){
XPRB.init();
XPRS.Init();
XPRBprob bcl_prob = new XPRBprob("Example1");
XPRBvar x = bcl_prob.newVar("x_1", BCLconstant.XPRB_BV); // Define a variable...
// Define the rest of the problem
XPRSprob opt_prob = bcl_prob.getXPRSprob();// Define an integer solution callback
IntsolCallback printsol = new IntsolCallback(PrintSolution);
opt_prob.AddIntsolCallback(printsol, (object)bcl_prob);
bcl_prob.setSense(BCLconstant.XPRB_MAXIM);
bcl_prob.mipOptimize();// Maximize the MIP problem}}

The code extract below shows how to access MIP solution information directly through the
Optimizer library functions using the column or row indices saved for BCL modeling objects. In
this case there is no need for synchronization of BCL with the local solution information.
public class IntSolExample2
public static void XPRSIntSolEvent(XPRSprob opt_prob, object my_object){
XPRBprob bcl_prob = (XPRBprob)my_object;
int ncol = opt_prob.OriginalCols; // Get the number of columns
double[] sol = new double[ncol];opt_prob.GetLpSol(sol);// Get the solution
int num = opt_prob.MIPSols;// Get number of the solution
System.Console.WriteLine("Solution {0}: Objective value: {1}",num,opt_prob.LPObjVal);
XPRBvar x = bcl_prob.getVarByName("x_1");
if( x.getColNum() >= 0 ) // Test whether variable is in the matrix
System.Console.WriteLine(x.getName() + ": " + sol[x.getColNum()]);}}

Fair Isaac Corporation Confidential and Proprietary Information

339

A PPENDIX C

Working with cuts in BCLThis chapter describes an extension to BCL that enables the user to define cuts in a similar way toconstraints. Although cuts are just additional constraints, they are treated differently by BCL. To
start with, they are defined as a separate type (XPRBcut instead of XPRBctr). Besides the type, thefollowing differences between the representation and use of constraints and cuts in BCL may beobserved:Cuts cannot be non-binding or ranged.

Cuts are not stored with the problem, this is up to the user.

Cuts have no names, but they have got an integer indicating their classification or
identification number.

Function XPRBdelcut deletes the cut definition in BCL, but does not influence the problem in
Xpress Optimizer if the cut has already been added to it.

Cuts are added to the problem while it is being solved without having to regenerate thematrix; they can only be added to the matrix (using function XPRBaddcuts) in one of thecallback functions of the Xpress Optimizer cut manager (see the ‘Xpress Optimizer
Reference Manual’). Furthermore, they can only be defined on variables that are alreadycontained in the matrix.

The following functions are available in BCL for handling cuts:
XPRBaddcutarrterm

Add multiple linear terms to a cut.

p. 34

XPRBaddcuts

Add cuts to a problem.

p. 35

XPRBaddcutterm

Add a term to a cut.

p. 37

XPRBdelcut

Delete a cut definition.

p. 54

XPRBdelcutterm

Delete a term from a cut.

p. 55

XPRBgetcutid

Get the classification or identification number of a cut.

p. 80

XPRBgetcutrhs

Get the RHS value of a cut.

p. 81

XPRBgetcuttype

Get the type of a cut.

p. 82

XPRBnewcut

Create a new cut.

p. 135

XPRBnewcutarrsum

Create a sum cut with individual coefficients (i ci xi).

p. 136

XPRBnewcutprec

Create a precedence cut (v1+dur v2).

p. 137

Fair Isaac Corporation Confidential and Proprietary Information

340

Working with cuts in BCL

C.1

XPRBnewcutsum

Create a sum cut (i xi).

p. 138

XPRBprintcut

Print out a cut.

p. 151

XPRBsetcutid

Set the classification or identification number of a cut.

p. 170

XPRBsetcutmode

Set the cut mode.

p. 171

XPRBsetcutterm

Set a cut term.

p. 172

XPRBsetcuttype

Set the type of a cut.

p. 173

ExampleThe following example shows how the Xpress Optimizer node cut manager callback may be
defined to add cuts during the branch and bound search. Function XPRBaddcuts that adds thecuts to the problem in Xpress Optimizer may only be called from one of the cut manager callback
functions. Nevertheless, cuts may be defined at any place in the program after BCL has been
initialized and the relevant variables have been defined. In order to keep the present example
simple, we only create and add cuts at a single node, they are therefore created in the cut
manager callback immediately before they are added to the problem. More realistically, cuts may
be generated subject to a certain search tree depth or depending on the solution values ofcertain variables in the current LP-relaxation.
#include <stdio.h>#include "xprb.h"#include "xprs.h"...
XPRBvar start[4];int XPRS_CC usrcme(XPRSprob oprob, void* vd){
XPRBcut ca[2];int num;
int i=0;
XPRBprob bprob;
bprob = (XPRBprob)vd;/* Get the BCL problem */XPRBbegincb(bprob, oprob);/* Coordinate BCL and Optimizer */XPRSgetintattrib(oprob, XPRS_NODES, &num);if(num == 2)/* Only generate cuts at node 2 */{/* ca0: s_1+2 <= s_0 */ca[0] = XPRBnewcutprec(bprob, start[1], 2, start[0], 2);
ca[1] = XPRBnewcut(bprob, XPRB_L, 2); /* ca1: 4*s_2 - 5.3*s_3 <= -17 */XPRBaddcutterm(ca[1], start[2], 4);
XPRBaddcutterm(ca[1], start[3], -5.3);
XPRBaddcutterm(ca[1], NULL, -17);
printf("Adding constraints:\n");for(i=0;i<2;i++) XPRBprintcut(ca[i]);if(XPRBaddcuts(bprob, ca, 2)) printf("Problem with adding cuts.\n");}XPRBendcb(bprob);/* Reset BCL to main problem */return 0;/* Call this func. once per node */}int main(int argc, char **argv){
XPRBprob prob;
XPRSprob oprob;
prob=XPRBnewprob("CutExpl");/* Initialization */for(j=0;j<4;j++) start[j] = XPRBnewvar(prob, XPRB_PL, "start", 0, 500);...
/* Define constraints and an objective function */Fair Isaac Corporation Confidential and Proprietary Information

341

Working with cuts in BCL

XPRBsetcutmode(prob, 1);
oprob = XPRBgetXPRSprob(prob);
XPRSsetcbcutmgr(oprob, usrcme, prob);
XPRBmipoptimize(prob, "");...
return 0;}/* Enable the cut mode *//* Get the Optimizer problem *//* Def. the cut manager callback *//* Solve the MIP problem *//* Solution output */When using the default multi-threaded MIP search it is important to coordinate BCL with thelocal Optimizer subproblem by surrounding the calls to BCL functions in the cut manager callback
by calls to XPRBbegincb and XPRBendcb. Alternatively, you may choose to disable parallelism by
setting the XPRS_MIPTHREADS control to 1.

C.2

C++ version of the example
With BCL C++, the implementation of the cut example is similar to what we have seen in theprevious section since the same Xpress Optimizer functions are used.
#include <iostream>#include "xprb_cpp.h"#include "xprs.h"using namespace std;
using namespace ::dashoptimization;...
XPRBvar start[NJ];
XPRBprob p("Jobs");// Initialize BCL and a new problem

int XPRS_CC usrcme(XPRSprob oprob, void* vd){
XPRBcut ca[2];int num;
int i=0;
XPRBprob *bprob;
bprob = (XPRBprob*)vd;// Get the BCL problem
bprob->beginCB(oprob);// Coordinate BCL and Optimizer
XPRSgetintattrib(oprob, XPRS_NODES, &num);if(num == 2)// Only generate cuts at node 2{
ca[0] = bprob->newCut(start[1]+2 <= start[0], 2);
ca[1] = bprob->newCut(4*start[2] - 5.3*start[3] <= -17, 2);cout << "Adding constraints:" << endl;
for(i=0;i<2;i++) ca[i].print();if(bprob->addCuts(ca,2)) cout << "Problem with adding cuts." << endl;}
bprob->endCB();// Reset BCL to main problem
return 0;// Call this function once per node}
int main(int argc, char **argv){
XPRSprob oprob;
for(j=0;j<4;j++) start[j] = p.newVar("start");...
// Define constraints and an objective function
oprob = p.getXPRSprob();// Get Optimizer problem
p.setCutMode(1);// Enable the cut mode
XPRSsetcbcutmgr(oprob,usrcme,&p);// Def. the cut manager callback
p.mipOptimize();// Solve the problem as MIP...
// Solution output
return 0;}

Fair Isaac Corporation Confidential and Proprietary Information

342

Working with cuts in BCL

C.3

Java version of the example
As is explained in Section B.7, before accessing directly the problem held in Xpress Optimizer weneed to initialize explicitly the Optimizer Java. The cut manager callback is implemented in Javaby the class ’cutMgrListener’.
import java.io.*;import com.dashoptimization.*;public class xbcutex{...
static XPRBvar[] start;
static XPRB bcl;
static class CutMgrCallback implements XPRScutMgrListener{public int XPRScutMgrEvent(XPRSprob oprob, Object data){
XPRBprob bprob;
XPRBcut[] ca;
int num,i;bprob = (XPRBprob)data;/* Get the BCL problem */try{bprob.beginCB(oprob);/* Coordinate BCL and Optimizer */num = oprob.getIntAttrib(XPRS.NODES);
if(num == 2)/* Only generate cuts at node 2 */{ca = new XPRBcut[2];ca[0] = bprob.newCut(start[1].add(2) .lEql(start[0]), 2);
ca[1] = bprob.newCut(start[2].mul(4) .add(start[3].mul(-5.3)) .lEql(-17), 2);
System.out.println("Adding constraints:");for(i=0;i<2;i++) ca[i].print();
bprob.addCuts(ca);}bprob.endCB();/* Reset BCL to main problem */}catch(XPRSprobException e){
System.out.println("Error " + e.getCode() + ": " + e.getMessage());}
return 0;/* Call this method once per node */}}public static void main(String[] args) throws XPRSexception{
XPRBprob p;
XPRSprob oprob;
CutMgrCallback cb;
bcl = new XPRB();
p = bcl.newProb("Jobs");
XPRS.init();/* Initialize BCL *//* Create a new problem *//* Initialize Xpress Optimizer */start = new XPRBvar[4];/* Create ’start’ variables */for(j=0;j<4;j++) start[j] = p.newVar("start");...
/* Define constraints and an objective function */oprob = p.getXPRSprob();
p.setCutMode(1);cb = new CutMgrCallback();
oprob.addCutMgrListener(cb, p);
p.mipOptimize();/* Get Optimizer problem *//* Enable the cut mode *//* Def. the cut manager callback *//* Solve the problem as MIP */Fair Isaac Corporation Confidential and Proprietary Information

343

Working with cuts in BCL

...
}
}

C.4

/* Solution output */.NET version of the example
As is explained in Section B.8, before accessing directly the problem held in Xpress Optimizer weneed to initialize explicitly the Optimizer .NET. The cut manager callback is implemented in this.NET example by the method usrcme.
using Optimizer;
using BCL;
namespace Examples{
public class xbcutex{
static XPRBvar[] start = new XPRBvar[4]; // Start times of jobs
public static int usrcme(XPRSprob xprsp, object vd){
XPRBcut[] ca = new XPRBcut[2];
XPRBprob xprbp = (XPRBprob)vd;// Get the BCL problem
xprbp.beginCB(xprsp);// Coordinate BCL and Optimizer
int num = xprsp.Nodes;
if(num == 2)// Only generate cuts at node 2{
ca[0] = xprbp.newCut(start[1]+2 <= start[0], 2);
ca[1] = xprbp.newCut((4*start[2]) - (5.3*start[3]) <= -17, 2);
System.Console.WriteLine("Adding constraints:");for(int i=0;i<2;i++) ca[i].print();if(xprbp.addCuts(ca,2) != 0)
System.Console.WriteLine("Problem with adding cuts.");}xprbp.endCB();// Reset BCL to main problem
return 0;// Call this function once per node}
public static void Main(){
XPRB.init();
XPRS.Init();// Initialize BCL// Initialize Optimizer

XPRBprob xprbp = new XPRBprob("Jobs");// Create a new problem
for(int j=0;j<4;j++)// Create ’start’ variables
start[j] = xprbp.newVar("start");...
// Define constraints and an objective function
XPRSprob xprsp = p.getXPRSprob();// Get Optimizer problem
xprbp.setCutMode(1);// Enable the cut mode
CutmgrCallback del = new CutmgrCallback(usrcme);
xprsp.AddCutmgrCallback(del, (object)xprbp); // Define the cut manager callback
xprbp.mipOptimize();// Solve the problem as MIP}}}

Fair Isaac Corporation Confidential and Proprietary Information

344

A PPENDIX D

Contacting FICO
FICO provides clients with support and services for all our products. Refer to the following
sections for more 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 and have an active support or maintenance contract. You can find support contact
information on the Product Support home page (www.fico.com/support).
On the Product Support home page, you can also register for credentials to log on to FICO Online
Support, our web-based support tool to access Product Support 24x7 from anywhere in the world.
Using FICO Online Support, you can enter cases online, track them through resolution, findarticles in the FICO Knowledge Base, and query known issues.
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, andtraining tools for both new user enablement and ongoing performance support. For additional
information, visit the Product Education homepage at www.fico.com/en/product-training or
email producteducation@fico.com.

Product documentation
FICO continually looks for new ways to improve and enhance the value of the products andservices we provide. If you have comments or suggestions regarding how we can improve thisdocumentation, let us know by sending your suggestions to techpubs@fico.com.

Fair Isaac Corporation Confidential and Proprietary Information

345

Contacting FICO

Sales and maintenanceUSA, CANADA AND ALL AMERICASEmail: XpressSalesUS@fico.com
WORLDWIDE
Email: XpressSalesUK@fico.com
Tel: +44 207 940 8718
Fax: +44 870 420 3601
Xpress Optimization, FICO
FICO HouseInternational Square
Starley Way
Birmingham B37 7GN
UK

Related services
Strategy Consulting: Included in your contract with FICO may be a specified amount ofconsulting 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.fico.com or contact your FICO accountrepresentative.

About FICO
FICO (NYSE:FICO) delivers superior predictive analytics solutions that drive smarter decisions. The
company’s groundbreaking use of mathematics to predict consumer behavior has transformed
entire industries and revolutionized the way risk is managed and products are marketed. FICO’sinnovative solutions include the FICO® Score—the standard measure of consumer credit risk in
the United States—along with industry-leading solutions for managing credit accounts,
identifying and minimizing the impact of fraud, and customizing consumer offers with pinpoint
accuracy. Most of the world’s top banks, as well as leading insurers, retailers, pharmaceuticalcompanies, and government agencies, rely on FICO solutions to accelerate growth, control risk,
boost profits, and meet regulatory and competitive demands. FICO also helps millions ofindividuals manage their personal credit health through www.myfico.com. Learn more atwww.fico.com. FICO: Make every decision countTM .

Fair Isaac Corporation Confidential and Proprietary Information

346

IndexSymbols*, 244+, 244+=, 221, 237, 243, 249, 290-, 244-=, 221, 237, 243<=, 284=, 221, 237, 243, 290==, 284>=, 284[], 249A
activity value, 12, 69, 223
add
index element, 38, 250
add MIP solution, 39, 257
array, 13, 198
add entry, 167
append, 44
create, 8delete, 51
incremental definition, 8
name, 8, 70
print, 22size, 8, 71
terminate, 63
B
basis
class, 218, 312, 322
delete, 12, 52, 219
load, 12, 127, 267
save, 12, 166, 276
validity check, 219
BCL
version number, 7, 124, 215
BCLExceptions, 323
boundfix, 7, 68, 296
get, 7, 72, 297, 301
integer limit, 7, 94, 181, 297, 302
lower, 7, 180, 302
semi-continuous limit, 7, 94, 181, 297, 302
upper, 7, 194, 303
branching directive
SOS, 19, 190, 294
variable, 7, 195, 302
C
callback
end, 64, 260

Fair Isaac Corporation Confidential and Proprietary Information

error messages, 7, 25, 48
messages, 6, 25, 50
parallel MIP, 334, 336, 338, 339
printing, 6, 25, 50
start, 45, 258
changeconstraint type, 10
variable type, 7, 197, 303
column order, 168, 216, 277
constraint
activity, 12, 69, 223
add array, 9, 33
add linear expression, 222
add quadratic term, 40
add term, 9, 43, 223
add terms, 33change type, 10, 169, 236
class, 220, 312, 322
coefficient, 74, 107, 224
creation, 9, 134, 271
definition, 9, 134, 271
delayed, 10, 83, 230, 232delete, 9, 53, 232, 259
delete coefficient, 9delete quadratic term, 57
delete term, 62, 223dual, 12, 84, 225
enumerate terms, 99, 100, 231
enumeration, 101, 270
finding, 262
get range, 10, 108, 226, 227
get RHS, 10, 110, 227
get type, 10, 79, 229
include vars, 10, 12, 91, 178, 230, 233
index, 9, 111, 228
indicator, 10, 92, 93, 225, 226, 230, 233
model cut, 10, 102, 230
name, 9, 76, 226
next, 270
number, 111, 228
precedence, 141
print, 22, 150, 231
ranging information, 77, 227
set coefficient, 9
set delayed, 10, 175
set include vars, 10, 12, 178, 233
set indicator, 10, 179
set model cut, 10, 182, 234
set quadratic term, 186
set range, 9, 187, 235
set term, 193, 235, 288
set type, 169, 236

347

Indexsize, 78, 228
slack, 12, 113, 229
sum, 147
sum with coefficients, 132
validity check, 231
copy
expression, 245
createindex set, 139, 207, 272, 307, 316
cut
add array, 34
add linear expression, 238
add term, 37, 239
add terms, 34
class, 237, 312, 322
classification, 80, 240
creation, 135, 271
definition, 135, 271
delete, 54, 241, 259
delete term, 55, 239
get RHS, 81, 240
get type, 82, 240
identification, 80, 240
model, 10, 102, 182, 230, 234
precedence, 137
print, 151, 241
set classification, 170, 241
set identification, 170, 241
set term, 172, 242
set type, 173, 242
sum, 138
sum with coefficients, 136
switch mode, 171, 277
validity check, 240
cut mode, 171, 277
cuts
add, 35, 256D
data
input, 159, 162, 207, 307, 316
reading, 159, 162
data input, 16
decimal signchange, 6, 174delayed, 10
delayed constraint, 83, 175, 230, 232deletearray, 51
basis, 219
constraint, 9, 53, 232, 259
constraint coefficient, 9
constraint term, 62, 223
cut, 54, 241, 259
expression term, 246
index set, 252
problem, 5, 56
set element, 19
set member, 61, 292
solution, 58, 288

Fair Isaac Corporation Confidential and Proprietary Information

solution variable, 59, 287
SOS, 19, 60, 260
dictionarysize, 176, 278
directive
delete, 46, 259
SOS, 19, 190, 207, 294, 306, 315
variable, 7, 15, 195, 302
directives
file, 200, 281
dual values, 12, 84, 225
E
E-1501, 325
E-1502, 325
E-1504, 325
E-1505, 325
E-1506, 325
E-1507, 325
E-1508, 325
E-1509, 325
E-1510, 325
E-1512, 325
E-1515, 326
E-1521, 326
E-1522, 326
E-1523, 326
E-1524, 326
E-1526, 326
E-1530, 326
E-1531, 327
E-1535, 327
E-1536, 327
E-1538, 327
E-1539, 327
E-1540, 327
E-1541, 327
E-1542, 327
E-1543, 327
E-1545, 327
E-1546, 327
E-1547, 327
E-1550, 327
E-1560, 328
E-1561, 328
E-1563, 328
E-1565, 328
E-1566, 328
E-1567, 328
E-1571, 328
E-1572, 328
E-1575, 328
E-1582, 328
E-1591, 328
E-1594, 329
E-1595, 329
E-1597, 329
error
exit, 7, 177error callback, 7, 25, 48

348

Indexerror handling, 7, 25, 177error message, 7, 25, 48
expression
add expression, 245
add term, 245
class, 243, 312, 322
constant multiplication, 246
copy, 245
delete term, 246
evaluation, 246
linear, 213, 312, 323
multiplication, 246
negation, 247
quadratic, 213, 312, 323
set term, 247
F
file
reading, 16
finalize, 304, 310
find by name, 73
constraint, 262
index set, 262
SOS, 265
variable, 266
fix globals, 67
formatreal numbers, 188, 217, 280
G
garbage collection, 310
generate matrix, 128, 267
getCRef, 213
getCtrByName, 212
getVarByName, 212
getXPRSprob, 312, 323
I
IIS, see irreducible infeasible set
include vars, 10, 12, 91, 178, 230, 233
incremental definition
array, 8
index
constraint, 9, 111, 228variable, 7, 75, 296
index set, 16
add element, 16, 38, 250
class, 249, 312, 322
create, 16, 207, 307, 316
creation, 139, 272
delete, 252element name, 16, 86, 251
find element, 16, 85, 251
finding, 262
index number, 16, 85, 251
name, 16, 87, 251
print, 22, 153, 252size, 16, 88, 251
validity check, 252
indicator constraint, 10, 179, 225, 226, 230, 233

Fair Isaac Corporation Confidential and Proprietary Information

sense, 92variable, 93
initialization, 5, 126, 142, 256, 328
explicit, 215
input
decimal sign, 6, 174file, 159, 162, 207, 307, 316
input file, 16interface pointer, 120, 196
callback, 47
irreducible infeasible set
constraints, 89, 96
number, 103, 264
SOS, 96
variables, 89, 96
isValid, 212
Llazy constraint, see delayed constraint
license, 5, 126, 328
linear expression, see expression
linear relation, see relationload matrix, 6load MIP solution, 129, 268
logic constraint, see indicator constraintMmatrix
add cuts, 35, 256
column ordering, 168, 216, 277
generation, 128, 267
loading, 6
output, 22, 65, 207, 261, 306, 316
matrix generation
column order, 168, 216, 277
maximize, 12
LP, 130, 269
MIP, 131, 269
message level, 6, 183, 210, 216, 278, 310, 320
minimize, 12
LP, 130, 269
MIP, 131, 269
MIPPRESOLVE, 333
MIQP, see Mixed Integer Quadratic Programming
Mixed Integer Quadratic Programming, 23
model cut, 10, 182, 234
modeling object
finding, 73
N
namearray, 8, 70
composing of, 140constraint, 9, 76, 226
dictionary, 176, 278
index set, 16, 87, 251
index set element, 16, 86, 251
problem, 105, 185, 264, 279
SOS, 19, 117, 292
variable, 7, 121, 297

349

Indexnamespace, 205
negation
expression, 247
number
IIS, 103, 264O
objective
get sense, 11, 112, 265
quadratic, 23
set sense, 11, 189, 280
value, 12, 104, 264
objective function, 184, 279
print, 154, 275
optimize, 12
LP, 130, 269
MIP, 131, 269
Optimizer problem, 125, 266
optimizer problem, 45, 258
outputfile, 22, 65, 261
redirection, 210, 310, 320
output level, 6, 183, 210, 216, 278, 310, 320
output stream, 310, 320
Ppackage, 304
parallel MIP, 334, 336, 338, 339
partial integer
get limit, 7, 94, 297
set limit, 7, 181, 302
precedence constraint, 10, 141
precedence cut, 137
PRESOLVE, 333
print
array, 22, 149constraint, 22, 150, 231
cut, 151, 241
index set, 22, 153, 252
objective function, 154, 275
problem, 22, 155, 207, 274, 306, 316
program output, 152solution, 156, 288
SOS, 22, 157, 293
text, 152
variable, 22, 158, 301
print flag, 6, 183, 216, 278
printing
decimal sign, 6, 174
printing callback, 6, 25, 50
priority, 15delete, 46, 259
SOS, 19, 190, 294
variable, 7, 195, 302
problem
add cuts, 35, 256class, 253, 311, 322
delete, 5, 56
delete basis, 12, 52
file output, 22, 65, 261

Fair Isaac Corporation Confidential and Proprietary Information

initialization, 5, 142, 256load basis, 12, 127, 267
LP status, 12, 95, 263
MIP status, 12, 98, 263
objective value, 12, 104, 264
output, 5, 155, 274
print, 22, 207, 306, 316
reset, 165, 276
save basis, 12, 166, 276
solve, 12solve LP, 130, 269
solve MIP, 131, 269
status, 12, 106, 265
synchronization, 199, 281
program output
print, 22, 152
Q
QCQP, see Quadratically Constrained Quadratic
Programming
QP, see Quadratic Programming
quadratic expression, see expression
Quadratic Programming, 23
quadratic term, 40, 186delete, 57
Quadratically Constrained Quadratic
Programming, 23
R
range, 9, 108, 187, 226, 227, 235
get values, 10
ranging information
constraint, 77, 227
variable, 122, 299
readdata line, 159, 162
reduced cost value, 12, 109, 298
reference constraint, 19, 145
relation, 213, 312, 323
class, 284, 312, 322
get type, 285
linear, 213
quadratic, 213
resetproblem, 165, 276
RHS, 10, 81, 110, 227, 240
running time, 119, 214
S
Scanner, 323
scheduling, 12
security system, 5semi-continuous
get limit, 7, 94, 297
set limit, 7, 181, 302
semi-continuous integer
get limit, 7, 94, 297
set limit, 7, 181, 302
sense
objective function, 11, 112, 189, 265, 280

350

Indexset
cut mode, 171, 277
index, 16
sizearray, 8, 71
constraint, 78, 228dictionary, 176, 278
index set, 16, 88, 251
solution, 116, 287
size limit, 328
slack values, 12, 113, 229
solution, 12, 114, 299
add, 39, 257
class, 286, 312, 322
creation, 143, 272
delete, 58, 288
delete variable, 59, 287
load, 20, 129, 268
objective, 12, 104, 264
print, 156, 288
query variable, 115, 287
read, 161, 164, 275
set variable, 192
set variable array, 191
size, 116, 287
validity check, 287
write, 201–204, 282, 283
solution value
expression, 246
solve, 12
LP, 130, 269
MIP, 131, 269
SOS
add array, 19, 41
add element, 19
add linear expression, 291
add member, 42, 292
add members, 41
class, 290, 312, 322
creation, 19, 144–146, 207, 273, 306, 315
delete, 19, 60, 260delete element, 19
delete member, 61, 292
finding, 265
name, 19, 117, 292
print, 22, 157, 293
set directive, 19, 190, 294
type, 19, 118, 293
validity check, 293
weights, 146
sqr, 248
square, 248
statusLP, 12, 95, 263
MIP, 12, 98, 263
problem, 12, 106, 265
Student Edition, 151Student mode, 328
student version, 24, 65, 150, 153–157, 231, 241,
252, 261, 274, 275, 288, 293, 301

Fair Isaac Corporation Confidential and Proprietary Information

sum constraint, 10, 132, 147
sum cut, 138T
tablesparse, 16time measure, 119, 214
typeconstraint, 10, 79, 169, 229, 236
cut, 82, 173, 240, 242
relation, 285
SOS, 19, 118, 293
variable, 7, 123, 197, 300, 303
Vvariablearray, 198
array of, 8, 133change type, 7, 197, 303
class, 295, 312, 322
coefficient, 74, 107, 224
creation, 7, 148, 274
deletion callback, 47
finding, 266
fix globals, 67, 261
fix value, 7, 68, 296
get bounds, 7, 72
get limit, 7, 94, 297
get lower bound, 297
get type, 7, 123, 300
get upper bound, 301
index, 7, 75, 296
interface pointer, 120, 196
lower bound, 7, 180, 302
name, 7, 121, 297
number, 75, 296
print, 22, 158, 301
print array, 149
ranging information, 122, 299
reduced cost, 12, 109, 298
set directive, 7, 195, 302
set limit, 7, 181, 302
set type, 197, 303
solution, 12, 114, 299
upper bound, 7, 194, 303
validity check, 301
variable types, 1
version number, 7, 124, 215
W
W-1513, 326
W-1514, 326
W-1516, 326
W-1518, 326
W-1519, 326
W-1520, 326
W-1525, 326
W-1527, 326
W-1551, 327
W-1552, 327

351

IndexW-1555, 328
W-1562, 328
W-1568, 328
W-1570, 328
W-1573, 328
W-1580, 328
W-1587, 328
W-1592, 329
W-1593, 329
W-1596, 329
W-1598, 329
W-1599, 329
X
xbcut, 135
XPRB, 214
XPRB.getTime, 214
XPRB.getVersion, 214
XPRB.init, 215
XPRB.setColOrder, 215
XPRB.setMsgLevel, 216
XPRB.setRealFmt, 216
XPRB_ARR, 73
XPRB_BV, 123, 133, 148, 197, 274, 300, 303, 312,
323
XPRB_CTR, 73
XPRB_DICT_IDX, 176, 277
XPRB_DICT_NAMES, 176, 277
XPRB_DIR, 106, 265
XPRB_DN, 190, 195, 294, 301
XPRB_E, 79, 82, 132, 134–136, 138, 147, 169, 173,
229, 236, 240, 242, 284, 285
XPRB_ERR, 48
XPRB_G, 79, 82, 132, 134–136, 138, 147, 169, 173,
229, 236, 240, 242, 284, 285
XPRB_GEN, 106, 265
XPRB_IDX, 73
XPRB_L, 79, 82, 132, 134–136, 138, 147, 169, 173,
229, 236, 240, 242, 284
XPRB_LCOST, 122, 299
XPRB_LOACT, 77, 122, 227, 299
XPRB_LP, 65, 260
XPRB_LP_CUTOFF, 95, 263
XPRB_LP_CUTOFF_IN_DUAL, 95, 263
XPRB_LP_INFEAS, 95, 263
XPRB_LP_NONCONVEX, 95, 263
XPRB_LP_OPTIMAL, 95, 263
XPRB_LP_UNBOUNDED, 95, 263
XPRB_LP_UNFINISHED, 95, 263
XPRB_LP_UNSOLVED, 95, 263
XPRB_MAXIM, 112, 189, 265, 280
XPRB_MINIM, 112, 189, 265, 280
XPRB_MIP_INFEAS, 98, 263
XPRB_MIP_LP_NOT_OPTIMAL, 98, 263
XPRB_MIP_LP_OPTIMAL, 98, 263
XPRB_MIP_NO_SOL_FOUND, 98, 263
XPRB_MIP_NOT_LOADED, 98, 263
XPRB_MIP_OPTIMAL, 98, 263
XPRB_MIP_SOLUTION, 98, 263
XPRB_MIP_UNBOUNDED, 98, 263

Fair Isaac Corporation Confidential and Proprietary Information

XPRB_MOD, 106, 265
XPRB_MPS, 65, 260
XPRB_N, 79, 132, 134, 147, 169, 229, 236, 284, 285
XPRB_PD, 190, 195, 294, 301
XPRB_PI, 123, 133, 148, 197, 274, 300, 303
XPRB_PL, 123, 133, 148, 197, 274, 300, 303
XPRB_PR, 190, 195, 294, 301
XPRB_PU, 190, 195, 294, 301
XPRB_R, 79, 229
XPRB_S1, 118, 144–146, 273, 293
XPRB_S2, 118, 144–146, 273, 293
XPRB_SC, 123, 133, 148, 197, 274, 300, 303
XPRB_SI, 123, 133, 148, 197, 274, 300, 303
XPRB_SOL, 106, 265
XPRB_SOS, 73
XPRB_UCOST, 122, 299
XPRB_UDN, 77, 122, 227, 299
XPRB_UI, 123, 133, 148, 197, 274, 300, 303
XPRB_UP, 190, 195, 294, 301
XPRB_UPACT, 77, 122, 227, 299
XPRB_UUP, 77, 122, 227, 299
XPRB_VAR, 73
XPRB_WAR, 48
XPRB_XPRS_PROB, 199, 280
XPRB_XPRS_SOL, 199, 280
XPRB_XPRS_SOLMIP, 199, 280
XPRBaddarrterm, 33
XPRBaddcutarrterm, 34
XPRBaddcuts, 35
XPRBaddcutterm, 37
XPRBaddidxel, 38
XPRBaddmipsol, 39
XPRBaddqterm, 23, 40
XPRBaddsosarrel, 41
XPRBaddsosel, 42
XPRBaddterm, 43
XPRBapparrvarel, 44
XPRBarrvar, 31
XPRBbasis, 31, 218
XPRBbasis.getCRef, 218
XPRBbasis.isValid, 218
XPRBbasis.reset, 219
XPRBbegincb, 45
XPRBcleardir, 46
XPRBctr, 31, 220, 222, 340
XPRBctr.add, 222
XPRBctr.addTerm, 222
XPRBctr.delTerm, 223
XPRBctr.getAct, 223
XPRBctr.getCoefficient, 224
XPRBctr.getCRef, 224
XPRBctr.getDual, 225
XPRBctr.getIndicator, 225
XPRBctr.getIndVar, 225
XPRBctr.getName, 226
XPRBctr.getRange, 226
XPRBctr.getRangeL, 226
XPRBctr.getRangeU, 227
XPRBctr.getRHS, 227
XPRBctr.getRNG, 227352

IndexXPRBctr.getRowNum, 228
XPRBctr.getSize, 228
XPRBctr.getSlack, 229
XPRBctr.getType, 229
XPRBctr.isDelayed, 229
XPRBctr.isIncludeVars, 230
XPRBctr.isIndicator, 230
XPRBctr.isModCut, 230
XPRBctr.isValid, 230
XPRBctr.nextTerm, 231
XPRBctr.print, 231
XPRBctr.reset, 232
XPRBctr.setDelayed, 232
XPRBctr.setIncludeVars, 232
XPRBctr.setIndicator, 233
XPRBctr.setModCut, 234
XPRBctr.setRange, 234
XPRBctr.setTerm, 235
XPRBctr.setType, 236
XPRBcut, 31, 237, 238, 340
XPRBcut.add, 238
XPRBcut.addTerm, 239
XPRBcut.delTerm, 239
XPRBcut.getCRef, 239
XPRBcut.getID, 240
XPRBcut.getRHS, 240
XPRBcut.getType, 240
XPRBcut.isValid, 240
XPRBcut.print, 241
XPRBcut.reset, 241
XPRBcut.setID, 241
XPRBcut.setTerm, 242
XPRBcut.setType, 242
XPRBdefcbdelvar, 47
XPRBdefcberr, 48
XPRBdefcbmsg, 50
XPRBdelarrvar, 51
XPRBdelbasis, 52
XPRBdelctr, 53
XPRBdelcut, 54
XPRBdelcutterm, 55
XPRBdelprob, 56
XPRBdelqterm, 57
XPRBdelsol, 58
XPRBdelsolvar, 59
XPRBdelsos, 60
XPRBdelsosel, 61
XPRBdelterm, 62
XPRBendarrvar, 63
XPRBendcb, 64
XPRBerror, 312
XPRBexportprob, 24, 65
XPRBexpr, 243, 244
XPRBexpr.add, 245
XPRBexpr.addTerm, 245
XPRBexpr.assign, 245
XPRBexpr.delTerm, 246
XPRBexpr.getSol, 246
XPRBexpr.mul, 246
XPRBexpr.neg, 247

Fair Isaac Corporation Confidential and Proprietary Information

XPRBexpr.setTerm, 247
XPRB_FGETS, 159, 162
XPRBfinish, 66
XPRBfixglobals, 67
XPRBfixvar, 68
XPRBfree, 66
XPRBfreemem, 90, 97
XPRBgetact, 69
XPRBgetarrvarname, 70
XPRBgetarrvarsize, 71
XPRBgetbounds, 72
XPRBgetbyname, 73
XPRBgetcoeff, 74
XPRBgetcolnum, 75, 333
XPRBgetctrname, 76
XPRBgetctrrng, 77
XPRBgetctrsize, 78
XPRBgetctrtype, 79
XPRBgetcutid, 80
XPRBgetcutrhs, 81
XPRBgetcuttype, 82
XPRBgetdelayed, 83
XPRBgetdual, 84
XPRBgetidxel, 85
XPRBgetidxelname, 86
XPRBgetidxsetname, 87
XPRBgetidxsetsize, 88
XPRBgetiis, 89
XPRBgetincvars, 91
XPRBgetindicator, 92
XPRBgetindvar, 93
XPRBgetlim, 94
XPRBgetlpstat, 95
XPRBgetmiis, 96
XPRBgetmipstat, 98
XPRBgetmodcut, 102
XPRBgetnextctr, 101
XPRBgetnextqterm, 100
XPRBgetnextterm, 99
XPRBgetnumiis, 103
XPRBgetobjval, 104
XPRBgetprobname, 105
XPRBgetprobstat, 106
XPRBgetqcoeff, 107
XPRBgetrange, 108
XPRBgetrcost, 109
XPRBgetrhs, 110
XPRBgetrownum, 111, 333
XPRBgetsense, 112
XPRBgetslack, 113
XPRBgetsol, 114
XPRBgetsolsize, 116
XPRBgetsolvar, 115
XPRBgetsosname, 117
XPRBgetsostype, 118
XPRBgettime, 119
XPRBgetvarlink, 120
XPRBgetvarname, 121
XPRBgetvarrng, 122
XPRBgetvartype, 123353

IndexXPRBgetversion, 124
XPRBgetXPRSprob, 125
XPRBidxset, 31
XPRBindexSet, 249
XPRBindexSet.addElement, 250
XPRBindexSet.getCRef, 250
XPRBindexSet.getIndex, 250
XPRBindexSet.getIndexName, 251
XPRBindexSet.getName, 251
XPRBindexSet.getSize, 251
XPRBindexSet.isValid, 252
XPRBindexSet.print, 252
XPRBindexSet.reset, 252
XPRBinit, 126, 331
XPRBlicense, 312
XPRBlicenseError, 312
XPRBloadbasis, 127
XPRBloadmat, 128, 332
XPRBloadmipsol, 129
XPRBlpoptimize, 130
XPRBmipoptimize, 131
XPRBnewarrsum, 132
XPRBnewarrvar, 133
XPRBnewctr, 134
XPRBnewcut, 135
XPRBnewcutarrsum, 136
XPRBnewcutprec, 137
XPRBnewcutsum, 138
XPRBnewidxset, 139
XPRBnewname, 140
XPRBnewprec, 141
XPRBnewprob, 126, 142, 331
XPRBnewsol, 143
XPRBnewsos, 144
XPRBnewsosrc, 145
XPRBnewsosw, 146
XPRBnewsum, 147
XPRBnewvar, 148
XPRBprintarrvar, 149
XPRBprintctr, 24, 150
XPRBprintcut, 151
XPRBprintf, 152
XPRBprintidxset, 153
XPRBprintobj, 24, 154
XPRBprintprob, 24, 155
XPRBprintsol, 156
XPRBprintsos, 157
XPRBprintvar, 158
XPRBprob, 31, 253, 256
XPRBprob.addCuts, 256
XPRBprob.addMIPSol, 257
XPRBprob.beginCB, 258
XPRBprob.clearDir, 259
XPRBprob.delCtr, 259
XPRBprob.delCut, 259
XPRBprob.delSos, 260
XPRBprob.endCB, 260
XPRBprob.exportProb, 260
XPRBprob.fixGlobals, 261
XPRBprob.getCRef, 262

Fair Isaac Corporation Confidential and Proprietary Information

XPRBprob.getCtrByName, 262
XPRBprob.getIndexSetByName, 262
XPRBprob.getLPStat, 263
XPRBprob.getMIPStat, 263
XPRBprob.getName, 264
XPRBprob.getNumIIS, 264
XPRBprob.getObjVal, 264
XPRBprob.getProbStat, 264
XPRBprob.getSense, 265
XPRBprob.getSosByName, 265
XPRBprob.getVarByName, 266
XPRBprob.getXPRSprob, 266
XPRBprob.loadBasis, 267
XPRBprob.loadMat, 267
XPRBprob.loadMIPSol, 268
XPRBprob.lpOptimize, 268
XPRBprob.mipOptimize, 269
XPRBprob.newCtr, 270
XPRBprob.newCut, 271
XPRBprob.newIndexSet, 272
XPRBprob.newSol, 272
XPRBprob.newSos, 273
XPRBprob.newVar, 273
XPRBprob.nextCtr, 270
XPRBprob.print, 274
XPRBprob.printObj, 275
XPRBprob.readBinSol, 275
XPRBprob.readSlxSol, 275
XPRBprob.reset, 276
XPRBprob.saveBasis, 276
XPRBprob.setColOrder, 277
XPRBprob.setCutMode, 277
XPRBprob.setDictionarySize, 277
XPRBprob.setMsgLevel, 278
XPRBprob.setName, 279
XPRBprob.setObj, 279
XPRBprob.setRealFmt, 279
XPRBprob.setSense, 280
XPRBprob.sync, 280
XPRBprob.writeBinSol, 282
XPRBprob.writeDir, 281
XPRBprob.writePrtSol, 282
XPRBprob.writeSlxSol, 283
XPRBprob.writeSol, 281
XPRBreadarrlinecb, 159
XPRBreadbinsol, 161
XPRBreadlinecb, 162
XPRBreadslxsol, 164
XPRBrelation, 284
XPRBrelation.getType, 284
XPRBresetprob, 165
XPRBsavebasis, 166
XPRBsetarrvarel, 167
XPRBsetcolorder, 168
XPRBsetctrtype, 169
XPRBsetcutid, 170
XPRBsetcutmode, 171
XPRBsetcutterm, 172
XPRBsetcuttype, 173
XPRBsetdecsign, 174354

IndexXPRBsetdelayed, 175
XPRBsetdictionarysize, 176
XPRBseterrctrl, 177
XPRBsetincvars, 178
XPRBsetindicator, 179
XPRBsetlb, 180
XPRBsetlim, 181
XPRBsetmodcut, 182
XPRBsetmsglevel, 183
XPRBsetobj, 23, 184
XPRBsetprobname, 185
XPRBsetqterm, 23, 186
XPRBsetrange, 187
XPRBsetrealfmt, 188
XPRBsetsense, 189
XPRBsetsolarrvar, 191
XPRBsetsolvar, 192
XPRBsetsosdir, 190
XPRBsetterm, 193
XPRBsetub, 194
XPRBsetvardir, 195
XPRBsetvarlink, 196
XPRBsetvartype, 197
XPRBsol, 31, 286
XPRBsol.delVar, 286
XPRBsol.getSize, 287
XPRBsol.getVar, 287
XPRBsol.isValid, 287
XPRBsol.print, 288
XPRBsol.reset, 288
XPRBsol.setVar, 288
XPRBsos, 31, 290
XPRBsos.add, 291
XPRBsos.addElement, 291
XPRBsos.delElement, 292
XPRBsos.getCRef, 292
XPRBsos.getName, 292
XPRBsos.getType, 293
XPRBsos.isValid, 293
XPRBsos.print, 293
XPRBsos.setDir, 293
XPRBstartarrvar, 198
XPRBsync, 199
XPRBvar, 31, 295, 296
XPRBvar.fix, 296
XPRBvar.getColNum, 296
XPRBvar.getCRef, 297
XPRBvar.getLB, 297
XPRBvar.getLim, 297
XPRBvar.getName, 297
XPRBvar.getRCost, 298
XPRBvar.getRNG, 298
XPRBvar.getSol, 299
XPRBvar.getType, 300
XPRBvar.getUB, 300
XPRBvar.isValid, 301
XPRBvar.print, 301
XPRBvar.setDir, 301
XPRBvar.setLB, 302
XPRBvar.setLim, 302

Fair Isaac Corporation Confidential and Proprietary Information

XPRBvar.setType, 302
XPRBvar.setUB, 303
XPRBwritebinsol, 202
XPRBwritedir, 200
XPRBwriteprtsol, 203
XPRBwriteslxsol, 204
XPRBwritesol, 201
XPRSaddcbmessage, 50
XPRSalter, 331
XPRSbtran, 331
XPRSftran, 331
XPRSgetintattrib, 330
XPRSgetintcontrol, 330
XPRSgetlpsol, 330, 333
XPRSgetmipsol, 331, 333
XPRSiis, 330
XPRSinit, 331
XPRSloadbasis, 331
XPRSloaddirs, 331
XPRSloadglobal, 331
XPRSloadlp, 331
XPRSloadqp, 331
XPRSloadsecurevecs, 331
XPRSlpoptimize, 331
XPRSmipoptimize, 331
XPRSrange, 330
XPRSreadbasis, 331
XPRSreaddirs, 331
XPRSreadprob, 331
XPRSrestore, 331
XPRSsave, 330
XPRSscale, 331
XPRSsetcbmessage, 50, 331
XPRSsetintcontrol, 330
XPRSsetprobname, 331
XPRSwritebasis, 330
XPRSwriteomni, 331
XPRSwriteprob, 331
XPRSwriteprtrange, 330
XPRSwriteprtsol, 330
XPRSwriterange, 330
XPRSwritesol, 330355