1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22 23:- comment(desc, html("\ 24<P> 25 This library lets you use an external Mathematical Programming solver 26 from within ECLiPSe. This is done either directly to the solver, like 27 CPLEX, XPRESS-MP or Gurobi, or indirectly via COIN-OR project's Open Solver 28 Interface (OSI), giving access to the CLP, CBC and SYMPHONY solvers. 29 For the commercial solvers, the library provides just the interface, 30 and does not include the solver or any required licence to use them. 31</P><P> 32 The constraints provided are: 33 <DL> 34 <DT>Vs $:: Bound</DT><DD>Bounds on variables</DD> 35 <DT>X $= Y</DT><DD>equality over linear expressions</DD> 36 <DT>X $>= Y</DT><DD>inequality over linear expressions</DD> 37 <DT>X $=< Y</DT><DD>inequality over linear expressions</DD> 38 <DT>integers(Xs)</DT><DD>integrality of variables</DD> 39 <DT>sos1(Xs)</DT><DD>all but one are zero</DD> 40 <DT>sos2(Xs)</DT><DD>all but two consecutive values are zero</DD> 41 <DT>Cond=>Linear</DT><DD>indicator constraint (some solvers only)</DD> 42 </DL> 43 The operational behaviour of the linear constraints is as follows: 44</P><UL> 45 <LI>When they contain no variables, they simply succeed or fail. 46 47 <LI>When they contain exactly one variable, they are translated into a 48 bound update on that variable for the external solver instance. This 49 can lead to immediate failure if the lower bound is greater than the upper. 50 51 <LI>Otherwise, the constraint is transferred to the external solver 52 immediately (or as soon as the solver is set up). 53</UL><P> 54The following arithmetic expression can be used inside the constraints: 55<DL> 56<DT><STRONG><B>X</B></STRONG> 57<DD>Variables. If X is not yet a problem variable for the external solver 58 instance, it is turned into one via an implicit declaration 59 <TT>X :: -inf..inf</TT>. 60 61<P> 62<DT><STRONG><B>123, 3.4</B></STRONG> 63<DD>Integer or floating point constants. 64 65<P> 66<DT><STRONG><B>+</B>Expr</STRONG> 67<DD>Identity. 68 69<P> 70<DT><STRONG><B>-</B>Expr</STRONG> 71<DD>Sign change. 72 73<P> 74<DT><STRONG>E1<B>+</B>E2</STRONG> 75<DD>Addition. 76 77<P> 78<DT><STRONG><B>sum</B>(ListOfExpr)</STRONG> 79<DD>Equivalent to the sum of all list elements. 80 81<P> 82<DT><STRONG>E1<B>-</B>E2</STRONG> 83<DD>Subtraction. 84 85<P> 86<DT><STRONG>E1<B>*</B>E2</STRONG> 87<DD>Multiplication. 88 89<P> 90<DT><STRONG>ListOfExpr1<B>*</B>ListOfExpr2</STRONG> 91<DD>Scalar product: The sum of the products of the corresponding 92elements in the two lists. The lists must be of equal length. 93</DL> 94</P><P> 95The external solver can either be explicitly invoked to solve the 96problem represented by the constraints, or be invoked in response to 97certain trigger conditions. This mechanism makes it possible to tailor 98the solving behaviour for a particular application's needs. 99</P> 100")). 101 102:- comment(lp_get_license/0, [ 103 summary:"Get a runtime license token for the external solver.", 104 fail_if:"Fails if no license can (currently) be obtained", 105 see_also:[lp_get_license/2,lp_release_license/0], 106 desc:html("\ 107 The eplex-library interfaces to an external simplex/MIP solver 108 which might require a license to run (e.g. CPLEX, XPRESS-MP, Gurobi). 109 When the eplex-library is loaded, it tries to obtain a license 110 immediately. If this is not possible, for example because the 111 license pool is temporarily empty, a warning is printed. The 112 application program should then call lp_get_license/0 later 113 to obtain a license before any eplex functionality is used. 114 If a license is successfully obtained or already held, 115 lp_get_license succeeds, otherwise it fails. 116 <P> 117 This predicate uses information from the file eplex_lic_info.ecl 118 in the ECLiPSe library directory, or solver specific environment 119 variable settings to locate the licensing information. 120 ")]). 121 122:- comment(lp_get_license/2, [ 123 amode: lp_get_license(+,+), 124 args: ["LicStr":"String or Atom", "LicNum":"Integer"], 125 summary:"Get a runtime license token for the external solver.", 126 fail_if:"Fails if no license can (currently) be obtained", 127 see_also:[lp_get_license/0,lp_release_license/0,lp_get_license_challenge/1], 128 desc:html("\ 129 The eplex-library interfaces to an external simplex/MIP solver 130 which might require a license to run (e.g. CPLEX, XPRESS-MP, Gurobi). 131 When the eplex-library is loaded, it tries to obtain a license 132 immediately. However, this might not be possible, either 133 because no licenses are currently available, or because 134 specific licensing information needs to be supplied. 135 <P> 136 In the latter case, lp_get_license/2 must be called explicitly 137 by the programmer, and the relevant licensing information must 138 be supplied as arguments. The meaning of the arguments is 139 specific to the solver used: 140 <PRE> 141 LicStr LicNum 142 143 CPLEX development unused unused 144 CPLEX runtime licenvstring serialnum 145 XPRESS-MP development xpress_path unused 146 XPRESS-MP runtime xpress_path response 147 Gurobi license_file unused 148 OSI unused unused 149 </PRE> 150 If LicStr is a file or directory name, it is expected to be in 151 the native operating system syntax. 152 ")]). 153 154:- comment(lp_get_license_challenge/1, [ 155 amode: lp_get_license_challenge(-), 156 args: ["Challenge":"Variable"], 157 summary:"Get parameter for computing license key (some external solvers only)", 158 fail_if:"Fails if the solver doesn't use a challenge-response licensing system", 159 see_also:[lp_get_license/2], 160 eg:" 161 ?- ( lp_get_license_challenge(Challenge) -> 162 magic_formula(Challenge, Response), 163 lp_get_license(RuntimeLicenseString, Response) 164 ; 165 lp_get_license(DevelopmentLicensePath, 0) 166 ). 167 ", 168 desc:html("\ 169 This is only needed for certain OEM versions of external solvers! 170 <P> 171 The eplex-library interfaces to an external simplex/MIP solver 172 which might require a license to run (e.g. CPLEX, XPRESS-MP). 173 Certain versions of these external solvers use a challenge- 174 response licensing system. Only in such cases is this predicate 175 needed. lp_get_license_challenge/1 returns a value which is used to 176 compute a license key. This key is then passed into lp_get_license/2. 177 For the details of this procedure you will need to consult the 178 documentation of the solver vendor. 179 <P> 180 Be aware that the magic formula supplied by the vendor is usually 181 designed to be performed in a language like C, and may rely on the 182 behaviour of overflowing with 32 bit integers. In ECLiPSe, no 183 overflowing will takes place because of bignums, and this has to be 184 taken into account if the magic formula is calculated in ECLiPSe. 185 <P> 186 If you have a development license of CPLEX or XPRESS-MP, this 187 predicate does not need to be called. If called anyway, it fails. 188 ")]). 189 190:- comment(lp_release_license/0, [ 191 summary:"Release a runtime license token for the external solver.", 192 see_also:[lp_get_license/0,lp_get_license/2], 193 desc:html("\ 194 The eplex-library interfaces to an external simplex/MIP solver 195 which might require a license to run (e.g. CPLEX, XPRESS-MP, Gurobi). 196 When the eplex-library is loaded, it tries to obtain a license 197 immediately, or a license can be obtained by calling 198 lp_get_license/0. A held license can then be released using 199 lp_release_license/0. The predicate always succeeds, even 200 if no license was held. 201 ")]). 202 203:- comment(integers/1, [ 204 template: ["integers(?Vars)","EplexInstance:integers(?Vars)"], 205 args: ["Vars": "Variable or number, or a list or submatrix of variables/numbers"], 206 see_also: [_:integers/1,reals/1,(::)/2], 207 summary: "Constrains Vars to integers for eplex instance EplexInstance.", 208 desc: html("<P>\ 209 Constrains list Vars to integers in the eplex instance 210 EplexInstance. If a variable in Vars is not already a problem 211 variable for EplexInstance, it will be added as a new problem 212 variable. The external solver will then take the integrality into 213 account, i.e. to solve a MIP/MIQP rather than a relaxed LP/QP 214 problem. Unlike integers/1 constraints from other solvers, the 215 variables are not constrained to be integer type at the ECLiPSe 216 level. However, when a typed_solution is retrieved (e.g. via 217 eplex_var_get/3), this will be rounded to the nearest integer. 218 <P> 219 Note that even when problem variables have been declared as 220 integers in other solvers (ic or other external solver 221 states), if the integrality constraint is not made known to this 222 EplexInstance, any invocation of the eplex external solver (e.g. via 223 eplex_solve/1) will only solve a continuous relaxation. 224 <P> 225 ") 226 ]). 227 228 229:- comment(sos1/1, [ 230 template: ["sos1(?Vars)","EplexInstance:sos1(?Vars)"], 231 args: ["Vars": "A collection of variables"], 232 see_also: [_:sos1/1,sos2/1,integers/1], 233 summary: "Constrains all but one of Vars to be zero.", 234 desc: html("<P>\ 235 Constrains all but one of Vars to be zero. In MIP terminology 236 this is called a Special Ordered Set (SOS) of type 1. 237</P><P> 238 If the variables are also required to be integral, this must 239 be separately declared using integers/1. Similarly for bounds. 240</P> 241 ") 242 ]). 243 244 245:- comment(sos2/1, [ 246 template: ["sos2(?Vars)","EplexInstance:sos2(?Vars)"], 247 args: ["Vars": "A collection of variables"], 248 see_also: [_:sos2/1,sos1/1,integers/1], 249 summary: "Constrains all but two consecutive elements of Vars to be zero.", 250 desc: html("<P>\ 251 Constrains all but two consecutive elements of Vars to be zero. In 252 MIP terminology this is called a Special Ordered Set (SOS) of type 2. 253</P><P> 254 If the variables are also required to be integral, this must 255 be separately declared using integers/1. Similarly for bounds. 256</P> 257 ") 258 ]). 259 260 261:- comment(reals/1, [ 262 template: ["reals(?Vars)","EplexInstance:reals(?Vars)"], 263 args: ["Vars": "Variable or number, or a list or submatrix of variables/numbers"], 264 see_also: [_:reals/1,integers/1,(::)/2], 265 summary: "Constraints Vars to the real domain for EplexInstance.", 266 fail_if: "Vars contain elements which are neither variable or number.", 267 desc: html("<P>\ 268 Constrains Vars to the real domain in the eplex instance 269 EplexInstance. Any variables that are not problem variables 270 for EplexInstance are added to the problem, with unconstrained 271 bounds (except by the external solver's idea of infinity). 272</P><P> 273 Note that the notion of real is used here in the pure mathematical 274 sense, where real numbers subsume the integers. If the variables 275 are already instantiated, this call checks that the variable is 276 instantiated to a number. 277</P> 278 ") 279 ]). 280 281 282:- comment((::)/2, [ 283 amode: ::(?,++), 284 template: ["?Vars :: ++Lo..Hi","EplexInstance: (?Vars :: ++Lo..Hi)"], 285 args: ["Vars":"Variable or number, or a list or submatrix of variables/numbers", 286 "Lo..Hi":"Lo, Hi are numbers or arithmetic expressions" 287 ], 288 see_also: [integers/1,reals/1,_:(::)/2,(#::)/2,($::)/2,get_var_bounds/3], 289 summary: "Constrains list elements to lie between the given bounds.", 290 fail_if: "Lo is greater than Hi.", 291 exceptions: [5: "Lo..Hi is not in correct form", 292 5: "Lo and Hi are of different numeric types"], 293 desc: html("\ 294 Constrain a variable (or all variables in a list) to take only 295 values in a given range for the eplex instance EplexInstance. Any 296 variables that are not already problem variables for EplexInstance 297 will be added to the problem. The range information is passed to 298 the external solver state associated with EplexInstance as 299 floats. No type information are implied by the bounds. 300 <P> 301 In particular, if the bounds are given as integers, this 302 information is <STRONG>not</STRONG> passed to the external solver. 303 Unless eplex:integers/1 is invoked, any 304 invocation of the eplex external solver (whether via eplex_solve/1, 305 lp_solve/2, lp_demon_setup/5 or optimize/2) will only solve a 306 continuous relaxation, even when problem variables have been 307 declared as integers in other solvers (e.g. ic). 308 <P> 309 No propagation is done at the ECLiPSe level with the bounds. In 310 particular, the variable is not instantiated even if the lower and 311 upper bounds are identical. The bounds may be inconsistent with the 312 bounds given for the variables in other EplexInstances or solvers 313 (i.e. this will not result in immediate failure).") 314 ]). 315 316:- comment(($::)/2, [ 317 amode: $::(?,++), 318 template: ["?Vars $:: ++Lo..Hi","EplexInstance: (?Vars $:: ++Lo..Hi)"], 319 args: ["Vars":"Variable or number or a list of them", 320 "Lo..Hi":"Lo, Hi are numbers or arithmetic expressions" 321 ], 322 see_also: [integers/1,reals/1,(::)/2,(#::)/2,_:($::)/2], 323 summary: "Constrains list elements to lie between the given bounds.", 324 exceptions: [5: "Lo..Hi is not in correct form", 325 5: "Lo and Hi are of different numeric types"], 326 desc: html("\ 327 Constrain a variable (or all variables in a list) to take only 328 values in a given range for the eplex instance EplexInstance. Any 329 variables that are not already problem variables for EplexInstance 330 will be added to the problem. The range information is passed to 331 the external solver state associated with EplexInstance as 332 floats. No type information are implied by the bounds. 333 <P> 334 In particular, if the bounds are given as integers, this 335 information is <STRONG>not</STRONG> passed to the external solver. 336 Unless eplex:integers/1 is invoked, any 337 invocation of the eplex external solver (whether via eplex_solve/1, 338 lp_solve/2, lp_demon_setup/5 or optimize/2) will only solve a 339 continuous relaxation, even when problem variables have been 340 declared as integers in other solvers (e.g. ic). 341 <P> 342 No propagation is done at the ECLiPSe level with the bounds. In 343 particular, the variable is not instantiated even if the lower and 344 upper bounds are identical. The bounds may be inconsistent with the 345 bounds given for the variables in other EplexInstances or solvers 346 (i.e. this will not result in immediate failure).") 347 ]). 348 349 350:- comment(eplex_var_get/3, [ 351template: ["eplex_var_get(+Var, ++What, -Value)","EplexInstance:eplex_var_get(+Var, ++What, -Value)"], 352args: ["Var": "A solver problem variable for solver associated with EplexInstance", 353 "What": "Specification for information wanted (atom)", 354 "Value": "Returned value of What" 355 ], 356summary: "Obtain information for an individual solver problem variable Var.", 357exceptions: [ 358 6: "What is not a valid value.", 359 6: "Var is not a problem variable for EplexInstance.", 360 6: "What is unavailable; the information was not requested" 361 " at solver setup.", 362 40: "Solver state had been previously destroyed." 363 ], 364desc: html("\ 365<P> 366 Retrieve information about the (logically) most recent solver state and 367 results related to a particular variable, for the eplex instance 368 EplexInstance. Fails if no solution has been computed yet. What can 369 take one of the following values: 370 371<DL> 372 <DT><TT>solution</TT> 373 <DD>Returns the floating-point solution for variable Var. 374<P> 375 376 <DT><TT>typed_solution</TT> 377 <DD>Returns the properly typed (integer or float) solution for variable 378 Var, depending on if the variable was constrained to be an integer 379 or not for EplexInstance. 380<P> 381 382 <DT><TT>reduced_cost</TT> 383 <DD>Returns the reduced cost for variable Var. If the problem is a MIP, 384 then depending on the external solver, this is either unavailable 385 or is the value at the optimal LP node. 386 Note that reduced cost is defined as the minimal amount the 387 objective value will be changed by if the variable's value is 388 increased by 1 from its solution value. 389 390 <DT><TT>type</TT> 391 <DD>Returns the type the variable Var is constrained to in 392 EplexInstance. Possible values are integer or real. 393</DL> 394<P> 395 Note that solution or reduced_cost can only be retrieved 396 when previously requested in the option list of eplex_solver_setup/4, 397 lp_demon_setup/5, lp_setup/4 or with lp_set/3. 398</P>") 399]). 400 401:- comment(lp_var_get/4, [ 402amode: lp_var_get(+,+,++,-), 403args: ["Handle": "Handle to a solver state", 404 "Var": "A solver problem variable for Handle", 405 "What": "Specification for information wanted (atom)", 406 "Value": "Returned value of What" 407 ], 408summary: "Obtain information for an individual solver problem variable Var.", 409see_also: [eplex_var_get/3], 410exceptions: [4: "Handle is not instantiated.", 411 5: "Handle is not a compound term.", 412 6: "What is not a valid value.", 413 6: "Var is not a problem variable for Handle.", 414 6: "What is unavailable; the information was not requested" 415 " at solver setup.", 416 40: "Handle not valid: solver state had been destroyed by cleanup" 417 ], 418desc: html("\ 419<P> 420 Retrieve information about the (logically) most recent solver state and 421 results related to a particular variable, for the solver state 422 represented by Handle. Fails if no solution has been computed yet. What 423 can take the same values as those in eplex_var_get/3.") 424 425]). 426 427 428:-comment(suspend_on_change/2, 429 [template:["suspend_on_change(?Var, +Susp)","EplexInstance:suspend_on_change(?Var, +Susp)"], 430 args:["Var" : "A solver problem variable for solver associated with EplexInstance", 431 "Susp" : "Suspension to schedule when the typed solution for this variable changes"], 432 summary:"Record the given suspension to be scheduled whenever a solution is found for the EplexInstance."]). 433 434:-comment(get_changeable_value/2, 435 [template:["get_changeable_value(?Var, -Val)","EplexInstance:get_changeable_value(?Var, -Val)"], 436 args:["Var" : "A solver problem variable for solver associated with EplexInstance", 437 "Val" : "The typed_solution value for this variable"], 438 summary:"Interface predicate to access the <EM>changeable</EM> value for this variable."]). 439 440:-comment(lp_suspend_on_change/3, 441 [template:"lp_suspend_on_change(+Handle, ?Var, +Susp)", 442 args:["Handle" : "Handle to a solver state", 443 "Var" : "A solver problem variable for solver state" 444 " represented by Handle", 445 "Susp" : "Suspension to schedule when the typed solution for this variable changes"], 446 summary:"Record the given suspension to be scheduled" 447 " whenever a solution is found for the Eplex handle."]). 448 449:-comment(lp_get_changeable_value/3, 450 [template:"lp_get_changeable_value(+Handle, ?Var, -Val)", 451 args:["Handle" : "Handle to a solver state", 452 "Var" : "A solver problem variable for solver state" 453 " represented by Handle", 454 "Val" : "The typed_solution value for this variable"], 455 summary:"Interface predicate to access the <EM>changeable</EM> value for this variable."]). 456 457 458:- comment(eplex_instance/1, [ 459 amode:eplex_instance(++), 460 args: ["EplexInstance": "Eplex instance name (atom)" 461 ], 462 summary: "Initialises the eplex instance EplexInstance.", 463 desc: html("\ 464 <P> 465 Initialises the eplex instance EplexInstance. An eplex instance is an 466 instance of the eplex solver, to which eplex linear arithmetic and 467 integrality constraints can be posted, and to which an external LP/MIP 468 solver can be associated and used to optimise the posted constraints 469 with respect to some objective. 470 </P><P> 471 If EplexInstance is not an already existing eplex instance, a new eplex 472 instance will be created and initialised. If it is an existing eplex 473 instance, and it is not currently being used (having no outstanding posted 474 constraints and no associated solver), it is effectively reinitialised. 475 Otherwise, the predicate aborts with an error. Note that an eplex instance 476 is a module, and each eplex instance can be associated with at most one 477 solver at any time and vice versa. An eplex instance should NOT be 478 erased (e.g. using erase_module/1), as this would only erase the module, 479 but not the information that eplex keeps on it as an eplex instance. 480 </P> 481 "), 482 see_also: [($=)/2,($=<)/2,($>=)/2,(=:=)/2,(=<)/2,(>=)/2, 483 ($::)/2,(::)/2,integers/1,reals/1, 484 eplex_solver_setup/1, eplex_solver_setup/4, 485 eplex_probe/2, eplex_solve/1, 486 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 487 ] 488]). 489 490:- comment((>=)/2, [ 491 template: "EplexInstance:(?X >= ?Y)", 492 args: ["X": "Linear expression", 493 "Y": "Linear expression" 494 ], 495 see_also: [_:(>=)/2,(=:=)/2,(=<)/2, 496 ($>=)/2,($=)/2,($=<)/2, 497 eplex_solver_setup/1, eplex_solver_setup/4, 498 eplex_probe/2, eplex_solve/1, 499 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 500 ], 501 502 summary: "Constrains X to be greater than or equal to Y.", 503 desc: html("\ 504 Logically: Constrains X to be greater than or equal to Y. 505 X and Y are linear expressions. 506 Operationally, the constraint gets delayed until the external 507 solver state for EplexInstance is invoked.") 508 509 ]). 510 511:- comment(($>=)/2, [ 512 template: ["?X $>= ?Y","EplexInstance:(?X $>= ?Y)"], 513 args: ["X": "Linear expression", 514 "Y": "Linear expression" 515 ], 516 see_also: [(>=)/2,(=:=)/2,(=<)/2, 517 _:($>=)/2,($=)/2,($=<)/2, 518 eplex_solver_setup/1, eplex_solver_setup/4, 519 eplex_probe/2, eplex_solve/1, 520 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 521 ], 522 523 summary: "Constrains X to be greater than or equal to Y.", 524 desc: html("\ 525 Logically: Constrains X to be greater than or equal to Y. 526 X and Y are linear expressions. 527 Operationally, the constraint gets delayed until the external 528 solver state for EplexInstance is invoked. 529 </P><P> 530 The $ version of the arithmetic constraints are provided to allow 531 code to be written which does not specify the solver. They are 532 equivalent to their eplex instance counterparts without the $ prefix. 533") 534 535 ]). 536 537:- comment((=<)/2, [ 538 template: "EplexInstance:(?X =< ?Y)", 539 args: ["X": "Linear expression", 540 "Y": "Linear expression" 541 ], 542 see_also: [(=:=)/2,_:(=<)/2,(>=)/2, 543 ($>=)/2,($=)/2,($=<)/2, 544 eplex_solver_setup/1, eplex_solver_setup/4, 545 eplex_probe/2, eplex_solve/1, 546 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 547 ], 548 summary: "Constrains X to be less than or equal to Y.", 549 desc: html("\ 550 Logically: Constrains X to be less than or equal to Y. 551 X and Y are linear expressions. 552 Operationally, the constraint gets delayed until the external 553 solver state for EplexInstance is invoked.") 554 ]). 555 556:- comment(($=<)/2, [ 557 template: ["?X $=< ?Y","EplexInstance:(?X $=< ?Y)"], 558 args: ["X": "Linear expression", 559 "Y": "Linear expression" 560 ], 561 see_also: [(=:=)/2,(=<)/2,(>=)/2, 562 ($>=)/2,($=)/2,_:($=<)/2, 563 eplex_solver_setup/1, eplex_solver_setup/4, 564 eplex_probe/2, eplex_solve/1, 565 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 566 ], 567 summary: "Constrains X to be less than or equal to Y.", 568 desc: html("\ 569 Logically: Constrains X to be less than or equal to Y. 570 X and Y are linear expressions. 571 Operationally, the constraint gets delayed until the external 572 solver state for EplexInstance is invoked. 573 </P><P> 574 The $ version of the arithmetic constraints are provided to allow 575 code to be written which does not specify the solver. They are 576 equivalent to their eplex instance counterparts without the $ prefix. 577 ") 578]). 579 580:- comment((=:=)/2, [ 581 template: "EplexInstance:(?X =:= ?Y)", 582 args: ["X": "Linear expression", 583 "Y": "Linear expression" 584 ], 585 see_also: [_:(=:=)/2,(=<)/2,(>=)/2, 586 ($>=)/2,($=)/2,($=<)/2, 587 eplex_solver_setup/1, eplex_solver_setup/4, 588 eplex_probe/2, eplex_solve/1, 589 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 590 ], 591 summary: "Constrains X to be equal to Y.", 592 desc: html("\ 593 Logically: Constrains X to be equal to Y. 594 X and Y are linear expressions. 595 Operationally, the constraint gets delayed until the external 596 solver state for EplexInstance is invoked.") 597 ]). 598 599:- comment(($=)/2, [ 600 template: ["?X $= ?Y","EplexInstance:(?X $= ?Y)"], 601 args: ["X": "Linear expression", 602 "Y": "Linear expression" 603 ], 604 see_also: [(=:=)/2,(=<)/2,(>=)/2, 605 ($>=)/2,_:($=)/2,($=<)/2, 606 eplex_solver_setup/1, eplex_solver_setup/4, 607 eplex_probe/2, eplex_solve/1, 608 eplex_get/2, eplex_var_get/3, eplex_cleanup/0 609 ], 610 summary: "Constrains X to be equal to Y.", 611 desc: html("\ 612 Logically: Constrains X to be equal to Y. 613 X and Y are linear expressions. 614 Operationally, the constraint gets delayed until the external 615 solver state for EplexInstance is invoked. 616 </P><P> 617 The $ version of the arithmetic constraints are provided to allow 618 code to be written which does not specify the solver. They are 619 equivalent to their eplex instance counterparts without the $ prefix. 620 ") 621]). 622 623:- comment((=>)/2, [ 624 template: ["Ind => LinCon","EplexInstance:(Ind => LinCon)"], 625 args: ["Ind": "A binary variable or negated binary variable", 626 "LinCon": "A linear constraint" 627 ], 628 see_also: [ _:(=>)/2, ($>=)/2,($=)/2,($=<)/2, 629 eplex_add_constraints/2 630 ], 631 summary: "Linear constraint conditional on binary variable", 632 desc: html("<P>\ 633 Logical implication Ind =≥ LinCon. The linear constraint LinCon 634 is enforced when the indicator Ind is 1, and violation of LinCon 635 forces the indicator Ind to 0. 636</P><P> 637 Ind can be a variable, or a subscript expression resulting in a 638 variable. It can also be negated using the neg/1 prefix operator. 639 Correspondingly, LinCon is either enforced by the binary being 0 or 1. 640</P><P> 641 LinCon is any linear constraint accepted by eplex, i.e. an equality 642 or inequality constraint over linear expressions. 643</P><P> 644 This constraint does not implicitly impose bounds or a type on the 645 binary variable in Ind. It will usually make sense to separately 646 impose bounds of 0..1 and invoke integers/1. 647</P><P> 648 Indicator constraints are not supported by every external solver. 649 Use lp_get(has_indicator_constraints,yes) to check availability. 650</P> 651 "), 652 eg:" 653 B => ( X1 $>= X2+8 ) 654 neg B => ( X1+5 $=< X2 ) 655 B[12] => ( sum(Costs) $= 42 ) 656" 657]). 658 659:- comment(eplex_add_constraints/2, [ 660 template: ["eplex_add_constraints(+Constraints,+Integers)", 661 "EplexInstance: eplex_add_constraints(+Constraints,+Integers)"], 662 args: [ 663 "Constraints": "A (possibly empty) list of equality or inequality constraints", 664 "Integers": "A (possibly empty) list of variables to be considered as integers" 665 ], 666 see_also: [lp_add_constraints/3,lp_demon_setup/5,lp_add/3,lp_add_constraints/4, 667 ($=)/2,($=<)/2,($>=)/2,(=:=)/2,(=<)/2,(>=)/2,sos1/1,sos2/1,(=>)/2], 668 resat: no, 669 fail_if: "Any ground (no variable) or bound constraints (one variable) is self-inconsistent.", 670 exceptions: [4: "Constraints or Integers uninstantiated.", 671 5: "Some constraint in Constraints is non-linear.", 672 40: "Solver state had been previously destroyed." 673 ], 674 summary: "Add new constraints to the eplex instance EplexInstance," 675 " possibly triggering it.", 676 desc: html("\ 677<P> 678 Add new constraints (with possibly new variables) to the eplex instance 679 EplexInstance. Cstrs is a list of equality or inequality constraints; 680 NewIntegers is a list of (possibly new) variables that should be 681 consider as integers This is logically the same as posting the 682 constraints one by one to the solver, but it may be more convenient if 683 the constraints are already collected as a list. 684</P><P> 685 Operationally, if a solver state has been associated with the eplex 686 instance, the constraints are added to the solver state in one go. 687 For some solvers, this can be more efficient than adding the constraints 688 incrementally. 689</P><P> 690 If the new_constraint trigger option was selected, then the solver will 691 be invoked after the adding of the constraints if these constraints are 692 not already satisfied. The constraints will be removed on backtracking. 693</P><P> 694 The constraints are normalised and simplified before being passed to 695 the external solver. If any constraint is ground, they are tested for 696 consistency. 697</P><P> 698 The constraints can be linear equalities and inequalities, sos/1 and 699 sos2/1 constraints, and =≥/2 indicator constraints. 700</P><P> 701 Note that variables in NewIntegers can be any problem variables. In 702 previous versions of ECLiPSe, there was a restriction that the variables 703 be new problem variables; this restriction has been removed. 704</P><P> 705 706 </P>") 707 ]). 708 709:- comment(lp_add_constraints/3, [ 710 amode: lp_add_constraints(+,+,++), 711 args: ["Handle": "Handle to a solver state", 712 "Constraints": "A (possibly empty) list of equality or inequality constraints", 713 "Integers": "A (possibly empty) list of variables to be" 714 " considered as integers in the problem" 715 ], 716 see_also: [lp_demon_setup/5,lp_add/3,lp_add_constraints/4, 717 eplex_add_constraints/2, 718 ($=)/2,($=<)/2,($>=)/2,(=:=)/2,(=<)/2,(>=)/2,sos1/1,sos2/1,(=>)/2], 719 resat: no, 720 fail_if: "Any ground (no variable) or bound constraints (one variable) is self-inconsistent.", 721 exceptions: [4: "Handle, Constraints or Integers uninstantiated.", 722 5: "Some constraint in Constraints is non-linear.", 723 40: "Handle not valid: solver state had been destroyed by cleanup" 724 725 ], 726 summary: "Add new constraints to the solver Handle, possibly" 727 " triggering it.", 728 desc: html("\ 729<P> 730 Add new constraints (with possibly new variables) to a solver. 731 NewIntegers is a list of variables that the external solver should 732 consider as integers The new constraints will be taken into 733 account the next time the solver is run: if the new_constraint option of 734 lp_demon_setup was turned on, then the solver will be invoked after the 735 adding of the constraints, unless they are already satisfied. The 736 constraints will be removed on backtracking. 737</P><P> 738 The constraints are normalised and simplified before being passed to 739 the external solver. If any constraint is ground, they are tested for 740 consistency. 741</P><P> 742 The constraints can be linear equalities and inequalities, sos/1 and 743 sos2/1 constraints, and =≥/2 indicator constraints. 744</P><P> 745 Note that variables in NewIntegers can be any problem variables. In 746 previous versions of ECLiPSe, there was a restriction that the variables 747 be new problem variables; this restriction has been removed. 748</P><P> 749 750 </P>") 751 ]). 752 753 754:- comment(lp_add_constraints/4, [ 755 amode: lp_add_constraints(+,+,++, -), 756 args: ["Handle": "Handle to a solver state", 757 "Constraints": "A (possibly empty) list of expandable" 758 "linear equality or inequality constraints", 759 "Integers": "A (possibly empty) list of problem variables to be considered as integers", 760 "Indices": "Indices for the constraints in Constraints" 761 ], 762 see_also: [lp_add_constraints/3,lp_demon_setup/5,lp_add/3,lp_add_columns/2, 763 ($=)/2,($=<)/2,($>=)/2,(=:=)/2,(=<)/2,(>=)/2], 764 resat: no, 765 exceptions: [4: "Handle, Constraints or Integers uninstantiated.", 766 5: "Some constraint in Constraints is ground.", 767 5: "Some constraint in Constraints is non-linear.", 768 40: "Handle not valid: solver state had been destroyed by cleanup" 769 770 ], 771 summary: "Add new expandable constraints to the demon solver Handle.", 772 desc: html("\ 773<P> 774 Add new expandable constraints (with possibly new variables) to a solver. 775 An expandable constraint can be expanded when new variables are added to 776 the problem. These constraints are in the form of having a constant on 777 the right-hand side, and coefficients for the problem variables on the 778 left. When new variables are added (via lp_add_columns/2), the 779 coefficients for these variables can be given for the expandable 780 constraints. Note that the constraints can only be expanded if there are 781 no trigger conditions (i.e. the problem must be solved explicitly), or if 782 the problem is not associated with an eplex instance. Otherwise, the 783 added constraints are treated as normal (non-expandable) constraints. 784</P><P> 785 Constraints is a list of expandable constraints. NewIntegers is a list 786 of variables that the external solver should consider as integers, 787 Indices is a list of the indices for the added constraints. It is 788 returned by the predicate, and has the same length as Constraints. Each 789 element in Indices is the index for the constraint in Constraints at the 790 same position in the list. This index is used to refer to the constraint 791 in lp_add_columns/2. 792</P><P> 793 Operationally lp_add_constraints/4 behaves like lp_add_constraints/3, 794 except that it never trigger the solver as a demon: 795 The new constraints will be taken into account the next time the solver 796 is run, and removed on backtracking. The constraints are normalised 797 before being passed to the external solver. Unlike lp_add_constraints/3, 798 they are not simplified, and no consistency checks are performed. If any 799 of the constraints are ground, a type error is raised. 800</P><P> 801 Note that variables in NewIntegers can be any problem variables. 802 </P>") 803 ]). 804 805 806:- comment(lp_add_cutpool_constraints/4, [ 807 amode: lp_add_cutpool_constraints(+,+,+,-), 808 args: ["Handle": "Handle to a solver state", 809 "Constraints": "A (possibly empty) list of equality or inequality constraints", 810 "Options": "A (possibly empty) list of Option:Value pairs", 811 "Indices": "Indices for the constraints in CstrSpecs" 812 ], 813 resat: no, 814 summary: "Add constraints to the cutpool associated with solver state Handle.", 815 exceptions:[6: "Constraints contains variable(s) that is not in the" 816 " problem during setup.", 817 5: "A constraint in Constraints is ground." 818 ], 819 820 see_also: [lp_get/3, lp_set/3], 821 desc: html("\ 822<P> 823 Add constraints to the cutpool associated with solver state Handle. 824 Unlike normal constraints, cutpool constraints are not added directly to 825 the problem, and are *NOT* removed on backtracking. Logically, cutpool 826 constraints are valid for all solves of the problem, regardless of when 827 a constraint is added to the pool -- they are `globally valid'. The 828 purpose of the cutpool is to give the user more flexibility on how 829 constraints are used by the external solver. 830</P><P> 831 <TT>Constraints</TT> is the list of constraints to be added to the 832 cutpool. As they are not removed on backtracking, they can only involve 833 variables that are present at problem setup. Otherwise, an out of range 834 error is raised. Variables can be created for a problem before setup by 835 posting normal constraints involving the variables, in particular, using 836 reals/1. The constraints are normalised before being passed to the 837 external solver. They are not simplified, and no consistency checks 838 are performed. If any of the constraints are ground, a type error is 839 raised. Instantiated variables are treated as constants (i.e. the value 840 they are instantiated to when the predicate is called), even when the 841 execution backtracks to a point before the instantiations. 842</P><P> 843 <TT>Options</TT> is a possibly empty list of Option:Value pairs specifying 844 the options. Valid options are: 845<DL> 846<P> 847<DT><STRONG><TT>add_initially</TT></STRONG> 848 <DD>specifies if the constraints should be added to the problem matrix 849 before the external solver is invoked. Valid values are <TT>1</TT> for 850 adding the constraints before solving, and <TT>0</TT> for not adding. 851 The default is <TT>1</TT>. 852<DT><STRONG><TT>active</TT></STRONG> 853 <DD>specifies if the constraints should be active. Valid values are 854 <TT>1</TT> for active, and <TT>0</TT> for non-active. The default is <TT>1</TT>. 855<DT><STRONG><TT>group</TT></STRONG> 856 <DD>specifies the cutpool constraints group that the constraints will be 857 added to. <TT>Value</TT> must be an existing group name for the cutpool, 858 i.e. the default group, or a group name previously created with 859 the cutpool_group option of lp_set/3. The default is the default group 860 name ([]). 861</DL> 862</P><P> 863 Operationally, the cutpool constraints are taken into account when the 864 external solver is invoked, and the user can specify how they are taken 865 into account by setting the status of these constraints: by default, 866 cutpool constraints are active, and are taken into account during solver 867 invocation: none of these constraints will be violated in the solution 868 produced: they are either part of the problem matrix solved by the 869 external solver, or they have been explicitly checked for non-violation. 870 This is done as follows: active cutpool constraints that are labelled as 871 `add_initially' (the default) are added to the problem matrix, and the 872 external solver is invoked. When a solution is produced, the unadded 873 active cutpool constraints are checked to see if they are violated. Any 874 violated constraints are added to the problem matrix and the problem is 875 resolved by the external solver. This is repeated until there are no 876 violated constraints. This approach allows the user to leave out 877 constraints that might be expensive (i.e. slow down the solving) unless 878 they usefully constrain the problem. 879</P><P> 880 Checking for violations require the solution values of the problem 881 variables. Thus, if the <TT>solution</TT> option is turned off and no 882 solution value is available, and there are unadded active cutpool 883 constraints, an out of range error would be raised when the solver tries 884 to solve the problem. 885</P><P> 886 The violation checking is only done if the external solver produces a 887 solution with solution values. If the problem is unbounded (or unknown, 888 i.e. the solver cannot determine if the problem is infeasible or 889 unbounded), then all the active cutpool constraints are added to the 890 problem without checking for violations, and the problem is resolved once 891 more. This is done because adding constraints to the problem can make the 892 problem become bounded. 893</P><P> 894 The user can change a cutpool constraint's status to non-active, in which 895 case it is neither checked for violations nor added to the problem. 896 For logical correctness, the user should only make a constraint non-active 897 if it is certain that the constraint will not be violated, e.g. if it is 898 superceded by a stronger constraint. 899</P><P> 900 Cutpool constraints are organised into named groups, allowing multiple 901 constraints to be referred to as a unit, e.g. with the cutpool_info 902 option of lp_get/3. 903</P><P> 904 Note that as the constraints are added to the cutpool, and not to the 905 problem directly, this is not considered as adding new constraints, and 906 will not cause the solver to trigger with the new_constraint trigger 907 condition set. 908 ") 909]). 910 911:- comment(lp_add_columns/2, [ 912 amode: lp_add_columns(+,+), 913 args: ["Handle": "Handle to a solver state", 914 "Columns": "A list of Variable:ColumnSpecification pairs." 915 ], 916 summary: "Add new variables as columns to the external solver's matrix.", 917 exceptions:[4: "Handle or Columns are uninstantiated.", 918 5: "A Variable in Columns is already a problem variable for" 919 " problem represented by Handle.", 920 40: "Handle not valid: solver state had been destroyed by cleanup", 921 abort: "Handle is an eplex instance problem, or trigger" 922 " conditions have been specified." 923 ], 924 925 desc: html("\ 926<P> 927 Add new variables as columns to the external solver's matrix. This 928 allows non-zero coefficients for the objective and existing constraints 929 to be specified for these variables. 930</P><P> 931 Each column is specified as a Variable:ColumnSpecification pair. 932 Variable is the variable that is being added to the problem, and 933 ColumnSpecification is the specification for the non-zero coefficients 934 for the column representing the variable in the external solver matrix: 935 this is a list of Index:Coefficient pairs. Where index is the index of an 936 existing constraint (obtained when the constraint was added using 937 lp_add_constraints/4), and coefficient is its coefficient. 938</P><P> 939 The ColumnSpecification list can optionally start with a special element 940 'obj':Coeff, in which case the coefficient is the objective coefficient 941 for the column (otherwise zero). This can be optionally followed by two 942 entries of the form 'lo':Lwb,'hi':Upb, which specify initial lower and 943 upper bound on the column variable (otherwise unbounded). Each 944 constraint coefficient should only occur once. Any index not specified 945 is given a zero value. 946</P><P> 947 Note that lp_add_columns/2 essentially modifies the problem represented 948 by Handle. This is not compatible with the view of the problem as a 949 compound constraint, and therefore, lp_add_columns/2 can only be used 950 for problems that are not eplex instances, and/or have no trigger 951 conditions for triggering the external solver. 952</P> 953 ") 954]). 955 956 957 958:- comment(lp_add_vars/2, [ 959 amode: lp_add_vars(+,+), 960 args: ["Handle": "Handle to a solver state", 961 "Vars": "A list of variables or numbers" 962 ], 963 summary: "Declare Vars to be problem variables for the solver state" 964 " Handle", 965 see_also: [lp_setup/4,lp_demon_setup/5], 966 desc: html("\ 967<P> 968 Declares variables in Vars as problem variables for the solver state 969 represented by Handle. Any of the variables that are not existing 970 problem variables for Handle are added to the problem. The new 971 variables' bounds are constrained to -infinity..infinity (infinity as 972 defined by the external solver). 973"), 974 fail_if: "Vars contain elements which are neither variables or numbers."]). 975 976 977 978:- comment(normalise_cstrs/3, [ 979amode: normalise_cstrs(+,-,-), 980args: ["Constraints": "List of arithmetic relations", 981 "NormConstraints": "Linear constraints from Constraints (normalised)", 982 "NonlinConstraints": "Non-linear constraints from Constraints" 983 ], 984summary: "Normalise the linear constraints in Constraints.", 985see_also: [($=)/2,($=<)/2,($>=)/2,(=:=)/2,(=<)/2,(>=)/2], 986desc: html("\ 987 Constraints is a list of terms of the form X $= Y, X $>= Y or X $=< Y (or 988 their non-$ equivalents) where X and Y are arithmetic expressions. The linear 989 constraints are returned in normalised form in NormConstraints, the 990 nonlinear ones are returned unchanged in NonlinConstr. 991") 992]). 993 994:- comment(eplex_solver_setup/1, [ 995template: ["eplex_solver_setup(+Objective)","EplexInstance:eplex_solver_setup(+Objective)"], 996args: ["Objective": "Objective function: min(CostExpr) or max(CostExpr)"], 997summary: "Setup an external solver state for eplex instance EplexInstance", 998see_also:[($=)/2,($=<)/2,($>=)/2,(=:=)/2, (>=)/2, (=<)/2, 999 ($::)/2, (::)/2,integers/1,reals/1, 1000 eplex_solver_setup/4, eplex_probe/2, 1001 eplex_solve/1, 1002 eplex_get/2, eplex_var_get/3 1003 ], 1004desc: html("\ 1005<P> 1006 Setup a new external solver state for the eplex instance EplexInstance. 1007 The solver state will be associated with EplexInstance; 1008 EplexInstance must not already have a solver state associated with it. 1009 Once the solver state is setup, it can be invoked (e.g. via eplex_solve/1 1010 or eplex_probe/2) to optimise the Objective function. 1011</P><P> 1012 CostExpr is a linear expression 1013 (or quadratic if supported by the external solver). 1014</P><P> 1015 Declaratively, this can be seen as a compound constraint representing all 1016 the individual linear constraints that have been set so far and are going 1017 to be set up later for <TT>EplexInstance</TT>. The invoking of this 1018 constraint is done explicitly by the user, usually via eplex_solve/1. 1019 Operationally, when the external solver is invoked, the delayed 1020 constraints posted to <TT>EplexInstance</TT> are collected and taken into 1021 account. 1022</P><P> 1023 This is a simplified version of eplex_solver_setup/4, it is equivalent to 1024 calling eplex_solver_setup/4 with the following defaults: 1025<PRE> 1026 eplex_solver_setup(Objective, _, [], []) 1027</PRE> 1028") 1029]). 1030 1031:- comment(eplex_solver_setup/4, [ 1032template: ["eplex_solver_setup(+Objective, ?Cost, ++ListOfOptions, +TriggerModes)", 1033 "EplexInstance:eplex_solver_setup(+Objective, ?Cost, ++ListOfOptions, +TriggerModes)"], 1034args: ["Objective": "Objective function: min(CostExpr) or max(CostExpr)", 1035 "Cost": "Variable bounded by the optimal solution", 1036 "ListOfOptions": "List of solver options", 1037 "TriggerModes": "List of conditions for re-triggering solver" 1038 ], 1039summary: "Setup an external solver state for eplex instance EplexInstance", 1040see_also:[($=)/2,($=<)/2,($>=)/2,(=:=)/2, (>=)/2, (=<)/2, 1041 ($::)/2,(::)/2,integers/1, reals/1, 1042 eplex_solver_setup/1, 1043 eplex_probe/2, eplex_solve/1, 1044 eplex_get/2, eplex_var_get/3, 1045 eplex_get_iis/4, 1046 lp_demon_setup/5, lp_setup/4 1047 ], 1048desc: html("\ 1049<P> 1050 Setup a new external solver state for the eplex instance EplexInstance. 1051 The solver state will be associated with EplexInstance; 1052 EplexInstance must not already have a solver state associated with it. 1053 This predicate allow various options to be specified when setting up the 1054 solver state. <TT>ListOfOptions</TT> allows a list of solver options to 1055 be specified, and <TT>TriggerModes</TT> allows the 1056 solver state to be set up as a demon so that the external solver is 1057 automatically invoked when the conditions for re-triggering specified in 1058 <TT>TriggerModes</TT> are met. The external solver can also be invoked 1059 explicitly via eplex_solve/1. 1060</P><P> 1061 Declaratively, this can be seen as a compound constraint representing all 1062 the individual linear constraints that have been set so far and are going 1063 to be set up later for <TT>EplexInstance</TT>. Operationally, when the 1064 external solver is invoked, the delayed constraints posted to 1065 <TT>EplexInstance</TT> are collected and taken into account. 1066</P><P> 1067 <TT>CostExpr</TT> is a linear cost expression (or quadratic, if supported 1068 by the external solver). 1069</P><P> 1070 The external solver's best objective bound will be exported as a bound 1071 for <TT>Cost</TT>: For a minimisation problem, each solution's best bound 1072 becomes a lower bound, for maximisation an upper bound on Cost. This 1073 technique allows for repeated re-solving with reduced bounds or added 1074 constraints. Note that Cost is not automatically made a problem variable 1075 (it can be a problem variable if there are constraints that involve it), 1076 and thus may not have bounds associated with in. In order for the bounds 1077 information not to be lost, some bounds should be given to <TT>Cost</TT> 1078 (e.g. making it a problem variable (but this might introduce unnecessary 1079 self-waking on bounds change), or via another solver with bounds 1080 (e.g. ic)). 1081</P><P> 1082 <TT>ListOfOptions</TT> is the same as in the low-level primitive 1083 lp_demon_setup/5, except that EplexInstance is implicitly associated with 1084 the new external solver state, so the <TT>collect_from</TT> option of 1085 lp_demon_setup/5 is not allowed (it is set to <TT> 1086 collect_from(pool(EplexInstance))</TT> by the predicate). See 1087 below for more details. 1088</P><P> 1089 <TT>TriggerModes</TT> specifies under which conditions the external solver 1090 will be re-triggered. If no condition is specified, then the solver must 1091 be explicitly triggered, usually via eplex_solve/1. The conditions are the 1092 same as in the low-level primitive lp_demon_setup/5 called by this predicate. 1093 See below (after <TT>ListOfOptions</TT> descriptions) for more details. 1094</P><P> 1095 Note: Some external solvers need to write temporary files when they 1096 are solving a problem. These are written to the temporary directory 1097 specified in ECLiPSe's tmp_dir setting (get_flag/2, set_flag/2). 1098 1099</P><P> 1100ListOfOptions are (unless explicitly specified otherwise, each option should 1101occur no more than once): 1102 1103<DL> 1104 1105<P> 1106<DT><STRONG><TT>initial_solve(+YesNo)</TT></STRONG> 1107 <DD>Specifies if an initial solve (call to the external solver) should 1108 be performed immediately after problem setup. 1109 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1110 <TT>yes</TT> if any trigger condition is specified in TriggerModes, 1111 <TT>no</TT> if no trigger condition is specified. 1112 1113<P> 1114<DT><STRONG><TT>method(+Method)</TT></STRONG> 1115 <DD>Use the specified method (<TT>default, auto, primal, dual, net, 1116 barrier, sifting, concurrent, concurrent_det</TT>) (representing Primal 1117 Simplex, Dual Simplex, Network Simplex, Barrier, Sifting etc) to solve 1118 the problem. For MIP problems, this specifies the start algorithm (the 1119 one that is used to solve the initial relaxation). See the external 1120 solver's manual for a description of these methods. 1121<P> 1122 For some of the methods, an additional `auxiliary' method may be 1123 specified in brackets. These are: 1124<DL> 1125<P> 1126 <DT><TT>net(Simplex)</TT>: 1127 <DD>specifies the Simplex method (<TT>primal</TT> or <TT>dual</TT>) to 1128 follow the network optimisation. For LP problems only. 1129<P> 1130 <DT><TT>barrier(Crossover)</TT>: 1131 <DD>specifies how the crossover to a basic solution from the barrier 1132 solution is performed. <TT>Crossover</TT> can be <TT>primal</TT>, 1133 <TT>dual</TT>, or <TT>none</TT>. <TT>none</TT> means no crossover is 1134 performed. 1135<P> 1136 <DT><TT>sifting(SubMethod)</TT>: 1137 <DD>specifies the method for solving the sifting subproblem. 1138 <TT>SubMethod</TT> can be <TT>primal, dual, net, barrier</TT>. 1139<P> 1140</DL> 1141 For all the auxiliary methods, <TT>default</TT> can also be specified. 1142 This is equivalent to not specifying an auxiliary method at all. 1143<P> 1144 Note that not every method is available on every external solver. 1145 The default method would use the solver's default method, or any 1146 selections done via solver-specific optimizer_param(_) settings. 1147 1148<P> 1149<DT><STRONG><TT>node_method(+Method)</TT></STRONG> 1150 <DD>For MIP problems only. Use the specified method (<TT>default, primal, 1151 dual, net, barrier, sifting</TT>) to solve the subproblem at each node 1152 of the MIP search-tree, except the root node, which is specified by 1153 <TT>method</TT> option above. See method option for more description of 1154 the methods. Note that there are less choices in the specifications of 1155 the auxiliary methods that in the method option, due to limitations in 1156 the solvers. If a specified auxiliary method cannot be used, `default' 1157 will be used instead. 1158 1159<P> 1160<DT><STRONG><TT>solution(+YesNo)</TT></STRONG> 1161 <DD>Make the solutions available each time the problem has been (re-)solved 1162 successfully. 1163 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1164 <TT>yes</TT>. 1165 1166<P> 1167<DT><STRONG><TT>dual_solution(+YesNo)</TT></STRONG> 1168 <DD>Make the dual solutions available each time the problem has been 1169 (re-)solved successfully. If the problem is a MIP, then depending on 1170 the external solver, this is either unavailable or are the values for 1171 the optimal LP node. 1172 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1173 <TT>no</TT>. 1174 1175<P> 1176<DT><STRONG><TT>slack(+YesNo)</TT></STRONG> 1177 <DD>Make the constraint slacks available each time the problem has been 1178 (re-)solved successfully. 1179 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1180 <TT>no</TT>. 1181 1182<P> 1183<DT><STRONG><TT>reduced_cost(+YesNo)</TT></STRONG> 1184 <DD>Make the reduced costs available each time the problem has been 1185 (re-)solved successfully. If the problem is a MIP, then depending on 1186 the external solver, this is either unavailable or are the values for 1187 the optimal LP node. 1188 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1189 <TT>no</TT>. 1190 1191<P> 1192<DT><STRONG><TT>keep_basis(+YesNo)</TT></STRONG> 1193 <DD>Store the basis each time the problem has been solved successfully, 1194 and use this basis as a starting point for re-solving next time. 1195 This option only affects performance. 1196 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1197 <TT>no</TT>. 1198 1199<P> 1200 <DT><STRONG><TT>mipstart(+Option)</TT></STRONG> 1201 <DD>Use the previous solution values as a warm-start heuristics for 1202 the MIP search. This only has an effect for certain solvers (e.g. 1203 Gurobi), if there are integrality constraints, and if there is a 1204 previous solution available. Possible values are <TT>none</TT> 1205 (no mipstart values, the default), <TT>all</TT> (use previous 1206 solution for all variables), or <TT>integers</TT> (use previous 1207 solution for all variables that are now constrained to be integral). 1208 1209<P> 1210 <DT><STRONG><TT>cache_iis(YesNo)</TT></STRONG> 1211 <DD>Specify if an IIS should be computed immediately for an infeasible problem 1212 (if supported by the external solver), and store it so that it can bee retrieved by 1213 eplex_get_iis/4 or lp_get_iis/5 (called from within a user-defined infeasible 1214 handler). This will be done before the problem can be modified and make the computing 1215 of the IIS impossible. The IIS will only be available before the problem is solved 1216 again, and also before the infeasible solve is backtracked. This option has no effect 1217 if the external solver does not support the computation of an IIS. Note that if this 1218 option is set, eplex will always ask for an IIS to computed for an infeasible problem, 1219 even if it is immediately backtracked by the infeasible handler failing, and that the 1220 option is only needed if the problem instance in the external solver is modified 1221 before eplex_get_iis/4 or lp_get_iis/5 is called. 1222 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1223 <TT>no</TT>. 1224 1225<P> 1226<DT><STRONG><TT>demon_tolerance(RealTol, IntTol)</TT></STRONG> 1227 <DD>Specify how far outside a variable's range an lp-solution 1228 can fall before lp_demon_setup/5 re-triggers. 1229 <TT>RealTol</TT> and <TT>IntTol</TT> are floats and default to 1230 0.00001 and 0.5 respectively. 1231 1232<P> 1233<DT><STRONG><TT>sos1(VarList)</TT></STRONG> - deprecated, use sos1/1 constraint 1234 <DD><TT>VarList</TT> is a list of variables which the solver should 1235 treat as variables of a type 1 special ordered set (SOS), i.e. at most 1236 one of the variables in the set can be non-zero. This can occur multiple 1237 times, for different sets of variables. 1238 1239<P> 1240<DT><STRONG><TT>sos2(VarList)</TT></STRONG> - deprecated, use sos2/1 constraint 1241 <DD><TT>VarList</TT> is a list of variables which the solver should 1242 treat as variables of a type 2 special ordered set (SOS), i.e. at most 1243 two of the variables in the set can be non-zero. This can occur multiple 1244 times, for different sets of variables. 1245 1246<P> 1247<DT><STRONG><TT>presolve(+YesNo)</TT></STRONG> 1248 <DD>Specify if the external solver should perform presolve for this 1249 problem. With presolving, the external solver will transform the 1250 problem before solving it. This can lead to significantly faster times 1251 to find solutions. However, as the problem has been transformed, some 1252 external solvers have restriction on accessing or changing the problem 1253 state. In addition, if the solver is repeatedly called because the 1254 problem is frequently modified, then presolve may not be an advantage. 1255 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1256 determined by the global setting of <TT>presolve</TT>, which can be 1257 changed via <TT>lp_set/2</TT>. The initial default is <TT>yes</TT>. 1258 Note that the presolve setting cannot be changed for a problem once it 1259 is set. If the external solver supports per-problem optimizer_params, 1260 their global defaults will be used for presolve(yes). 1261<P> 1262<DT><STRONG><TT>timeout(+TimeOut)</TT></STRONG> 1263 <DD>Set the external solver to time-out after <TT>TimeOut</TT> seconds. 1264 <TT>TimeOut</TT> is a positive number. The solver will abort (in either 1265 the abort or suboptimal state, depending on if a suboptimal solution 1266 was found) if the optimal solution was not found within the time 1267 limit. This should be used instead of setting the solver-specific 1268 parameter for time-out directly. In cases where the solver expects an 1269 integer for the time-out interval, the time given is rounded up to the 1270 next integer value. The timeout is set by setting the external 1271 solver's timeout settings, and the exact behaviour may be solver dependent. 1272<P> 1273<DT><STRONG><TT>suboptimal_handler(+Goal)</TT></STRONG> 1274 <DD>Specifies a user defined goal Goal to handle the case when the 1275 external solver returned a suboptimal solution (because the problem 1276 was aborted). Goal would be run in place of raising the default 1277 <TT>eplex_suboptimal</TT> event. 1278<P> 1279<DT><STRONG><TT>unbounded_handler(+Goal)</TT></STRONG> 1280 <DD>Specifies a user defined goal Goal to handle the case when the 1281 problem is unbounded. Goal would be run in place of raising the 1282 default <TT>eplex_unbounded</TT> event. 1283<P> 1284<DT><STRONG><TT>infeasible_handler(+Goal)</TT></STRONG> 1285 <DD>Specifies a user defined goal Goal to handle the case when the 1286 external solver found that the problem is infeasible. Goal would be run 1287 in place of raising the default <TT>eplex_infeasible</TT> event. Note 1288 that the default and logically correct behaviour is to fail, this 1289 handler is provided to allow the user to analyse the cause of the 1290 infeasibility. It is recommended that the handler should also fail 1291 after performing the analysis. 1292<P> 1293<DT><STRONG><TT>unknown_handler(+Goal)</TT></STRONG> 1294 <DD>Specifies a user defined goal Goal to handle the case when the 1295 external solver was not able to determine if the problem is unbounded 1296 or infeasible. Goal would be run in place of raising the default 1297 <TT>eplex_unknown</TT> event. 1298<P> 1299<DT><STRONG><TT>abort_handler(+Goal)</TT></STRONG> 1300 <DD>Specifies a user defined goal Goal to handle the case when the 1301 external solver aborted without finding any solution. Goal would be 1302 run in place of raising the default <TT>eplex_abort</TT> event. 1303<P> 1304<DT><STRONG><TT>use_var_names(+YesNo)</TT></STRONG> 1305 <DD>Specify if variable names (set using <TT>set_var_name/2</TT> of the 1306 var_name library) should be passed to the external solver. If a 1307 particular variable does not have a name when it is first passed to the 1308 external solver, a default name determined by the solver would be used. 1309 Note that for XPRESS-MP, there is a limit on the length of the name, 1310 which can be changed between 8 and 64 in steps of 8 with the 1311 parameter <TT>mpsnamelength (XPRS_MPSNAMELENGTH)</TT>. Variable 1312 names longer than this limit are truncated to the limit. 1313 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1314 <TT>no</TT>. 1315<P> 1316<DT><STRONG><TT>priority(+Prio)</TT></STRONG> 1317 <DD><TT>Prio</TT> is the scheduling priority with which the solver gets 1318 woken up. This priority determines whether the solver is run before or 1319 after other constraints. By default, if no priority is specified, the 1320 default priority (0, mapped to 5 unless changed) is used. Normally, the 1321 default priority should be sufficient and this option is not needed, 1322 unless there is a specific need to have the external solver invoked with 1323 higher or lower priority than some other constraints. 1324<P> 1325<DT><STRONG><TT>mip_use_copy(+YesNo)</TT></STRONG> 1326 <DD>Some external solvers do not allow a MIP problem to be modified 1327 once the MIP search has been started. Eplex works around this 1328 problem by making a copy of the problem and solving that, so that 1329 the original problem can still be modified. This can be turned off to 1330 avoid the overhead of making this copy, in which case the MIP 1331 problem cannot be modified. This option is used only when solving a 1332 MIP problem, and the external solver does not allow a MIP problem to 1333 be modified; otherwise it is ignored. 1334 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default 1335 is <TT>yes</TT> so that the problem can be modified. 1336<P> 1337<DT><STRONG><TT>write_before_solve(+Format,+File)</TT></STRONG> 1338 <DD>This option is most useful for debugging purposes. If given, Eplex 1339 will ask the external solver to dump the problem each time the problem 1340 is solved. This allows the problem in an <TT>eplex_probe/2</TT> or 1341 <TT>lp_probe/3</TT> to be dumped. As in <TT>lp_write/3</TT>, 1342 <TT>Format</TT> is the format of the dumped file and <TT>File</TT> is 1343 its name. Note that the problem is dumped each time the external solver 1344 is invoked if the problem has cutpool constraints, where there may be 1345 multiple invocations of the solver per solver call. 1346 The default without this option is that the problem would not be dumped. 1347<P> 1348<DT><STRONG><TT>post_equality_when_unified(+YesNo)</TT></STRONG> 1349 <DD>This option determines if an equality constraint between two 1350 variables will be posted to the solver when these variables are 1351 unified. Setting <TT>YesNo</TT> to no means that the constraint 1352 will <EM>not</EM> be posted. Note that this can lead to the 1353 solver's problem becoming inconsistent with ECLiPSe's. 1354 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1355 <TT>yes</TT>. 1356<P> 1357<DT><STRONG><TT>sync_bounds(+YesNo)</TT></STRONG> 1358 <DD>This option determines if the bounds of the problems variables are 1359 synchronised with other solvers (i.e. the generic bounds are obtained 1360 with get_var_bounds/3 and then passed to the external solver) before 1361 the external solver is invoked. This was always done for previous 1362 non-standalone version of eplex. For standalone eplex, as the bounds 1363 are communicated directly to the external solver, the synchronisation 1364 of variable bounds is not needed unless the user is using eplex 1365 co-operatively with other solvers (e.g. ic). Even in such cases, it may 1366 be more efficient to communicate these bounds changes by explicitly 1367 programming it, especially if the problem has many variables and bounds 1368 changes happen only to a few of the variables. Setting <TT>YesNo</TT> 1369 to yes should increase compatibility with previous code (but note that 1370 previous eplex obtained the bounds from a specific bounds keeper like 1371 ic rather than the generic bounds). YesNo is one of the atoms 1372 <TT>yes</TT> or <TT>no</TT>, the default is <TT>no</TT>. 1373 1374</DL> 1375<P> 1376<TT>TriggerModes</TT> can be a list of the following specifiers: 1377 1378<DL> 1379 1380 <DT><STRONG><TT>inst</TT></STRONG> 1381 <DD>re-trigger if a problem variable gets instantiated. 1382 1383 <DT><STRONG><TT>ModuleName:Index</TT></STRONG> 1384 <DD>re-trigger when the suspension list given by ModuleName:Index is woken 1385 for any of the problem variables. 1386 The format for <TT>ModuleName:Index</TT> is the same as for specifying 1387 the suspension list in suspend/3,4. 1388 1389 <DT><STRONG><TT>deviating_inst</TT></STRONG> 1390 <DD>re-trigger if a problem variable gets instantiated 1391 to a value that differs from its lp-solution more than a tolerance. 1392 1393 <DT><STRONG><TT>bounds</TT></STRONG> 1394 <DD>re-trigger each time a variable bound for the solver instance changes. 1395 1396 <DT><STRONG><TT>deviating_bounds</TT></STRONG> 1397 <DD>re-trigger each time a variable's solver instance bound changes 1398 such that its lp-solution gets excluded more than a tolerance. 1399 1400 <DT><STRONG><TT>new_constraint</TT></STRONG> 1401 <DD>re-trigger each time a new (arithmetic or integral) constraint is 1402 added to the solver instance. Note that adding integral constraint 1403 on new problem variables, or adding bounds constraint, or adding 1404 constraints to the cutpool will *not* re-trigger. 1405 1406 <DT><STRONG><TT>trigger(Atom)</TT></STRONG> 1407 <DD>re-trigger each time the symbolic trigger Atom is pulled by invoking 1408 schedule_suspensions/1 1409 1410 <DT><STRONG><TT>pre(Goal)</TT></STRONG> 1411 <DD>an additional condition to be used together with other triggers. When 1412 the demon is triggered, it first executes <TT>PreGoal</TT>. Only if 1413 that succeeds, does the appropriate external solver get invoked. 1414 This provides a way of reducing the number of (possibly expensive) 1415 solver invocations when given preconditions are not met. 1416 1417 <DT><STRONG><TT>post(Goal)</TT></STRONG> 1418 <DD>this is not a trigger condition, but specifies a goal to be executed 1419 after solver success, but before the Cost variable gets 1420 constrained. It is intended as a hook for exporting solution 1421 information, e.g. copying solutions from the solver state into 1422 variable attributes (eg. tentative value), or computing weights for 1423 labelling heuristics from the solver state. 1424 <DT><STRONG><TT>suspension(Susp)</TT></STRONG> 1425 <DD>this is not a trigger condition, but instead is used to access the 1426 demon used to trigger the solver. Susp is instantiated to 1427 the suspension that triggers the solver: by waking Susp, the solver 1428 is triggered. Susp is a demon in that it stays around after being 1429 woken. Accessing Susp allows the user to specify arbitrary conditions 1430 for triggering the solver. 1431</DL> 1432 1433 The tolerances mentioned can be specified in lp_setup/4 or lp_set/3 1434 as <TT>demon_tolerance</TT>. 1435 1436</P><P> 1437 If several trigger conditions are specified, then any of them will trigger 1438 the solver. 1439 1440</P><P> 1441 When a solver demon runs frequently on relatively small problems, 1442 it can be important for efficiency to switch off the presolve option 1443 to reduce overheads. 1444 1445</P>") 1446]). 1447 1448 1449 1450 1451:- comment(lp_demon_setup/5, [ 1452amode:lp_demon_setup(+,?,++,++,-), 1453args: ["Objective": "Objective function: min(CostExpr) or max(CostExpr)", 1454 "Cost": "Variable bounded by the optimal solution", 1455 "ListOfOptions": "List of solver options", 1456 "TriggerModes": "List of conditions for re-triggering solver", 1457 "Handle": "handle to solver state" 1458 ], 1459see_also: [lp_solve/2, lp_set/3, lp_setup/4, lp_get_iis/5, 1460 solution_out_of_range/1, schedule_suspensions/1, 1461 library(constraint_pools)], 1462summary: "Setup the external solver as a simplex demon.", 1463eg: "\ 1464 Some common invocations patterns for this predicate are the following. 1465 The first triggers the solver only on instantiation of variables to 1466 values that don't fit with the simplex solution: 1467 1468 lp_demon_setup(min(Expr), C, [], [deviating_inst], H) 1469 1470", 1471desc: html("\ 1472<P> 1473 Setup the external solver as a simplex demon. A simplex demon collects 1474 linear constraints and re-solves the problem whenever the triggering 1475 conditions in TriggerModes are met. 1476 1477</P><P> 1478 Declaratively, this can be seen as a compound constraint representing all 1479 the individual linear constraints that have been set so far and are going 1480 to be set up later. Operationally, the delayed constraints are collected 1481 and an external solver is set up (as with lp_setup/4). Then the problem 1482 is solved once initially (if <TT>initial_solve</TT> option is yes) and a 1483 delayed goal lp_demon is set up which will re-trigger the solver when 1484 certain conditions are met. 1485 1486</P><P> 1487 <TT>CostExpr</TT> is a linear cost expression (or quadratic, if supported 1488 by the external solver). 1489 1490</P><P> 1491 <TT>Handle</TT> refers to the created solver state (as in lp_setup/4 or 1492 lp_read/3 described below). It can be used to access and modify the state 1493 of the solver, retrieve solution information etc. 1494 1495</P><P> 1496 Unlike with lp_solve/2, <TT>Cost</TT> will not be instantiated to a 1497 solution's cost, but only be bounded by the best-bound on cost: 1498 For a minimisation problem, each solution's best-bound becomes a lower bound, 1499 for maximisation an upper bound on Cost. This technique allows for 1500 repeated re-solving with reduced bounds or added constraints. Note that 1501 Cost is not automatically made a problem variable (it can be a problem 1502 variable if there are constraints that involve it), and thus may not have 1503 bounds associated with in. In order for the bounds information not to be 1504 lost, some bounds should be given to <TT>Cost</TT> (e.g. making it a 1505 problem variable (but this might introduce unnecessary self-waking on 1506 bounds change), or via another solver with bounds (e.g. ic)). 1507</P><P> 1508 <TT>ListOfOptions</TT> is a list of solver options as described for 1509 lp_setup/4. In addition, the following extra options are also available: 1510 1511<DL> 1512 1513<DT><STRONG><TT>collect_from(+Pool)</TT></STRONG> 1514 <DD>Specifies if this solver state should be associated with an eplex 1515 instance. If Pool is <TT>none</TT>, then the solver is not associated 1516 with an eplex instance. If Pool is <TT>pool(Instance)</TT>, where 1517 Instance is the (atomic) name of an existing eplex instance, then this 1518 eplex instance would be associated with the solver state, i.e. when the 1519 solver is invoked, it will collect constraints posted to 1520 <TT>Instance</TT>. Note that <TT>Instance</TT> must not be associated 1521 with any other solver state already. 1522 The default value for <TT>Pool</TT> is pool(eplex) (for backward 1523 compatibility). 1524 1525<DT><STRONG><TT>initial_solve(+YesNo)</TT></STRONG> 1526 <DD>Specifies if an initial solve (call to the external solver) should 1527 be performed immediately after problem setup. 1528 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1529 <TT>yes</TT> if any trigger condition is specified in TriggerModes, 1530 <TT>no</TT> if no trigger condition is specified. 1531 1532<DT><STRONG><TT>priority(+Prio)</TT></STRONG> 1533 <DD><TT>Prio</TT> is the scheduling priority with which the solver gets 1534 woken up. This priority determines whether the solver is run before or 1535 after other constraints. By default, if no priority is specified, the 1536 default priority (0, mapped to 5 unless changed) is used. Normally, the 1537 default priority should be sufficient and this option is not needed, 1538 unless there is a specific need to have the external solver invoked with 1539 higher or lower priority than some other constraints. 1540</DL> 1541 1542</P><P> 1543 1544 <TT>TriggerModes</TT> specifies under which conditions the solver demon 1545 will be re-triggered. It can be a list of the following specifiers 1546 1547<DL> 1548 1549 <DT><STRONG><TT>inst</TT></STRONG> 1550 <DD>re-trigger if a problem variable gets instantiated. 1551 1552 <DT><STRONG><TT>ModuleName:Index</TT></STRONG> 1553 <DD>re-trigger when the suspension list given by ModuleName:Index is woken 1554 for any of the problem variables. 1555 The format for <TT>ModuleName:Index</TT> is the same as for specifying 1556 the suspension list in suspend/3,4. 1557 1558 <DT><STRONG><TT>deviating_inst</TT></STRONG> 1559 <DD>re-trigger if a problem variable gets instantiated 1560 to a value that differs from its lp-solution more than a tolerance. 1561 1562 <DT><STRONG><TT>bounds</TT></STRONG> 1563 <DD>re-trigger each time a variable bound for the solver instance changes. 1564 1565 <DT><STRONG><TT>deviating_bounds</TT></STRONG> 1566 <DD>re-trigger each time a variable's solver instance bound changes 1567 such that its lp-solution gets excluded more than a tolerance. 1568 1569 <DT><STRONG><TT>new_constraint</TT></STRONG> 1570 <DD>re-trigger each time a new (arithmetic or integral) constraint is 1571 added to the solver instance. Note that adding integral constraint 1572 on new problem variables, or adding bounds constraint, or adding 1573 constraints to the cutpool will *not* re-trigger. 1574 1575 <DT><STRONG><TT>trigger(Atom)</TT></STRONG> 1576 <DD>re-trigger each time the symbolic trigger Atom is pulled by invoking 1577 schedule_suspensions/1 1578 1579 <DT><STRONG><TT>pre(Goal)</TT></STRONG> 1580 <DD>an additional condition to be used together with other triggers. When 1581 the demon is triggered, it first executes <TT>PreGoal</TT>. Only if 1582 that succeeds, does the appropriate external solver get invoked. 1583 This provides a way of reducing the number of (possibly expensive) 1584 solver invocations when given preconditions are not met. 1585 1586 <DT><STRONG><TT>post(Goal)</TT></STRONG> 1587 <DD>this is not a trigger condition, but specifies a goal to be executed 1588 after solver success, but before the Cost variable gets 1589 constrained. It is intended as a hook for exporting solution 1590 information, e.g. copying solutions from the solver state into 1591 variable attributes (eg. tentative value), or computing weights for 1592 labelling heuristics from the solver state. 1593 <DT><STRONG><TT>suspension(Susp)</TT></STRONG> 1594 <DD>this is not a trigger condition, but instead is used to access the 1595 demon used to trigger the solver. Susp is instantiated to 1596 the suspension that triggers the solver: by waking Susp, the solver 1597 is triggered. Susp is a demon in that it stays around after being 1598 woken. Accessing Susp allows the user to specify arbitrary conditions 1599 for triggering the solver. 1600</DL> 1601 1602 The tolerances mentioned can be specified in lp_setup/4 or lp_set/3 1603 as <TT>demon_tolerance</TT>. 1604 1605</P><P> 1606 If several trigger conditions are specified, then any of them will trigger 1607 the solver. 1608 1609</P><P> 1610 When a solver demon runs frequently on relatively small problems, 1611 it can be important for efficiency to switch off the presolve option 1612 to reduce overheads. 1613 1614</P><P> 1615 The solver demon calls lp_solve/2 when it wakes up. See the description 1616 of lp_solve/2 for the handling of exceptions. 1617</P><P> 1618 Note: Some external solvers need to write temporary files when they 1619 are solving a problem. These are written to the temporary directory 1620 specified in ECLiPSe's tmp_dir setting (get_flag/2, set_flag/2). 1621</P>") 1622]). 1623 1624 1625:- comment(instantiation_deviates/1, [ 1626amode: instantiation_deviates(+), 1627args: ["Handle": "Handle to a solver state"], 1628see_also: [lp_demon_setup/5], 1629summary: "A trigger goal for lp_demon_setup/5.", 1630desc: html("\ 1631<P> 1632 1633 This is intended as a useful pre(Goal) for lp_demon_setup/5 in connection 1634 with the <TT>inst</TT> trigger mode. It succeeds if any of the variables 1635 originally involved in Handle have been instantiated to a value that is 1636 not within +/- tolerance from the latest simplex solution for that 1637 variable. The admissible tolerances can be specified in lp_setup/4 or 1638 lp_set/3 as <TT>demon_tolerance</TT>. 1639 1640</P>") 1641]). 1642 1643:- comment(solution_out_of_range/1, [ 1644amode: solution_out_of_range(+), 1645args: ["Handle": "Handle to a solver state"], 1646see_also: [lp_demon_setup/5], 1647summary: "A trigger goal for lp_demon_setup/5.", 1648desc: html("\ 1649<P> 1650 This is intended as a useful pre(Goal) for lp_demon_setup/5 in connection 1651 with the <TT>bounds</TT> trigger mode. It succeeds if any of the 1652 solutions (computed by the most recent successful solving) of Handle are 1653 more than a tolerance outside the range of the corresponding variables, 1654 ie. couldn't be instantiated to this value. The admissible tolerances 1655 can be specified in lp_setup/4 or lp_set/3 as <TT>demon_tolerance</TT>. 1656</P>") 1657]). 1658 1659:- comment(lp_setup/4, [ 1660amode: lp_setup(+,+,++,-), 1661args: ["NormConstraints": "normalised constraints", 1662 "Objective": "Objective function: min(CostExpr) or max(CostExpr)", 1663 "ListOfOptions": "List of solver options", 1664 "Handle": "handle to solver state" 1665 ], 1666summary: "Create a new external solver state for the constraints NormConstraints.", 1667see_also: [lp_add/3, lp_set/3, lp_add_vars/2, lp_add_constraints/3, 1668 lp_solve/2, lp_probe/3, lp_get/3, lp_get_iis/5, 1669 normalise_cstrs/3, lp_write/3], 1670desc: html("\ 1671<P> 1672 Create a new solver state for the set of constraints NormConstraints 1673 (see normalise_cstrs/3 for how to obtain a set of normalised 1674 constraints). Apart from the explicitly listed constraints, the 1675 variable's ranges will be taken into account as the variable bounds for 1676 the simplex algorithm. Undeclared variables are implicitly declared as 1677 reals. 1678 1679</P><P> 1680 However, when variables have been declared integers by other solvers (e.g. 1681 integers/1 of the ic library) that is not taken into account by the 1682 solver by default. This means that the solver will only work on the 1683 <EM>relaxed problem</EM> (ie. ignoring the integrality constraints), 1684 unless specified otherwise in the options. 1685 1686</P><P> 1687 CostExpr is a linear expression 1688 (or quadratic if supported by the external solver). 1689 1690</P><P> 1691 Options is a list of options (see below). Unless explicitly specified 1692 otherwise, each option should occur no more than once. 1693 1694 1695</P><P> 1696 A solver-handle Handle is returned which is used to refer to the solver 1697 subsequently. 1698 1699</P><P> 1700 Note: Some external solvers need to write temporary files when they 1701 are solving a problem. These are written to the temporary directory 1702 specified in ECLiPSe's tmp_dir setting (get_flag/2, set_flag/2). 1703 1704</P><P> 1705The solver Options are: 1706<DL> 1707 1708<DT><STRONG><TT>integers(+ListOfVars)</TT></STRONG> 1709 <DD>Consider the specified variables to be integers (whether or not 1710 they have been declared such). 1711 This option will instruct the external solver to use its own MIP solver 1712 (ie. branch-and-bound search happens within the external solver). 1713<P> 1714<DT><STRONG><TT>reals(+ListOfVars)</TT></STRONG> 1715 <DD>Consider the specified variables to be problem variables, but does 1716 not otherwise constrain the variables. This option allows variables to 1717 be added to the problem without requiring them to occur in other 1718 constraints. 1719<P> 1720<DT><STRONG><TT>method(+Method)</TT></STRONG> 1721 <DD>Use the specified method (<TT>default, auto, primal, dual, net, 1722 barrier, sifting, concurrent, concurrent_det</TT>) (representing Primal 1723 Simplex, Dual Simplex, Network Simplex, Barrier, Sifting etc) to solve 1724 the problem. For MIP problems, this specifies the start algorithm (the 1725 one that is used to solve the initial relaxation). See the external 1726 solver's manual for a description of these methods. 1727<P> 1728 For some of the methods, an additional `auxiliary' method may be 1729 specified in brackets. These are: 1730<DL> 1731<P> 1732 <DT><TT>net(Simplex)</TT>: 1733 <DD>specifies the Simplex method (<TT>primal</TT> or <TT>dual</TT>) to 1734 follow the network optimisation. For LP problems only. 1735<P> 1736 <DT><TT>barrier(Crossover)</TT>: 1737 <DD>specifies how the crossover to a basic solution from the barrier 1738 solution is performed. <TT>Crossover</TT> can be <TT>primal</TT>, 1739 <TT>dual</TT>, or <TT>none</TT>. <TT>none</TT> means no crossover is 1740 performed. 1741<P> 1742 <DT><TT>sifting(SubMethod)</TT>: 1743 <DD>specifies the method for solving the sifting subproblem. 1744 <TT>SubMethod</TT> can be <TT>primal, dual, net, barrier</TT>. 1745<P> 1746</DL> 1747 For all the auxiliary methods, <TT>default</TT> can also be specified. 1748 This is equivalent to not specifying an auxiliary method at all. 1749<P> 1750 Note that not every method is available on every external solver. 1751 The default method would use the solver's default method, or any 1752 selections done via solver-specific optimizer_param(_) settings. 1753 1754<P> 1755<DT><STRONG><TT>node_method(+Method)</TT></STRONG> 1756 <DD>For MIP problems only. Use the specified method (<TT>default, primal, 1757 dual, net, barrier, sifting</TT>) to solve the subproblem at each node 1758 of the MIP search-tree, except the root node, which is specified by 1759 <TT>method</TT> option above. See method option for more description of 1760 the methods. Note that there are less choices in the specifications of 1761 the auxiliary methods that in the method option, due to limitations in 1762 the solvers. If a specified auxiliary method cannot be used, `default' 1763 will be used instead. 1764 1765<P> 1766<DT><STRONG><TT>solution(+YesNo)</TT></STRONG> 1767 <DD>Make the solutions available each time the problem has been (re-)solved 1768 successfully. 1769 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1770 <TT>yes</TT>. 1771 1772<P> 1773<DT><STRONG><TT>dual_solution(+YesNo)</TT></STRONG> 1774 <DD>Make the dual solutions available each time the problem has been 1775 (re-)solved successfully. If the problem is a MIP, then depending on 1776 the external solver, this is either unavailable or are the values for 1777 the optimal LP node. 1778 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1779 <TT>no</TT>. 1780 1781<P> 1782<DT><STRONG><TT>slack(+YesNo)</TT></STRONG> 1783 <DD>Make the constraint slacks available each time the problem has been 1784 (re-)solved successfully. 1785 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1786 <TT>no</TT>. 1787 1788<P> 1789<DT><STRONG><TT>reduced_cost(+YesNo)</TT></STRONG> 1790 <DD>Make the reduced costs available each time the problem has been 1791 (re-)solved successfully. If the problem is a MIP, then depending on 1792 the external solver, this is either unavailable or are the values for 1793 the optimal LP node. 1794 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1795 <TT>no</TT>. 1796 1797<P> 1798<DT><STRONG><TT>keep_basis(+YesNo)</TT></STRONG> 1799 <DD>Store the basis each time the problem has been solved successfully, 1800 and use this basis as a starting point for re-solving next time. 1801 This option only affects performance. 1802 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1803 <TT>no</TT>. 1804 1805<P> 1806 <DT><STRONG><TT>mipstart(+Option)</TT></STRONG> 1807 <DD>Use the previous solution values as a warm-start heuristics for 1808 the MIP search. This only has an effect for certain solvers (e.g. 1809 Gurobi), if there are integrality constraints, and if there is a 1810 previous solution available. Possible values are <TT>none</TT> 1811 (no mipstart values, the default), <TT>all</TT> (use previous 1812 solution for all variables), or <TT>integers</TT> (use previous 1813 solution for all variables that are now constrained to be integral). 1814 1815<P> 1816 <DT><STRONG><TT>cache_iis(YesNo)</TT></STRONG> 1817 <DD>Specify if an IIS should be computed immediately for an infeasible problem 1818 (if supported by the external solver), and store it so that it can bee retrieved by 1819 eplex_get_iis/4 or lp_get_iis/5 (called from within a user-defined infeasible 1820 handler). This will be done before the problem can be modified and make the computing 1821 of the IIS impossible. The IIS will only be available before the problem is solved 1822 again, and also before the infeasible solve is backtracked. This option has no effect 1823 if the external solver does not support the computation of an IIS. Note that if this 1824 option is set, eplex will always ask for an IIS to computed for an infeasible problem, 1825 even if it is immediately backtracked by the infeasible handler failing, and that the 1826 option is only needed if the problem instance in the external solver is modified 1827 before eplex_get_iis/4 or lp_get_iis/5 is called. 1828 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1829 <TT>no</TT>. 1830 1831<P> 1832<DT><STRONG><TT>demon_tolerance(RealTol, IntTol)</TT></STRONG> 1833 <DD>Specify how far outside a variable's range an lp-solution 1834 can fall before lp_demon_setup/5 re-triggers. 1835 <TT>RealTol</TT> and <TT>IntTol</TT> are floats and default to 1836 0.00001 and 0.5 respectively. 1837 1838<DT><STRONG><TT>integers(+ListOfVars)</TT></STRONG> 1839 <DD>Consider the specified variables to be integers (whether or not 1840 they have been declared such). 1841 This option will instruct the external solver to use its own MIP solver 1842 (ie. branch-and-bound search happens within the external solver). 1843<P> 1844<DT><STRONG><TT>sos1(VarList)</TT></STRONG> 1845 <DD><TT>VarList</TT> is a list of variables which the solver should 1846 treat as variables of a type 1 special ordered set (SOS), i.e. at most 1847 one of the variables in the set can be non-zero. This can occur multiple 1848 times, for different sets of variables. 1849 1850<P> 1851<DT><STRONG><TT>sos2(VarList)</TT></STRONG> 1852 <DD><TT>VarList</TT> is a list of variables which the solver should 1853 treat as variables of a type 2 special ordered set (SOS), i.e. at most 1854 two of the variables in the set can be non-zero. This can occur multiple 1855 times, for different sets of variables. 1856 1857<P> 1858<DT><STRONG><TT>presolve(+YesNo)</TT></STRONG> 1859 <DD>Specify if the external solver should perform presolve for this 1860 problem. With presolving, the external solver will transform the 1861 problem before solving it. This can lead to significantly faster times 1862 to find solutions. However, as the problem has been transformed, some 1863 external solvers have restriction on accessing or changing the problem 1864 state. In addition, if the solver is repeatedly called because the 1865 problem is frequently modified, then presolve may not be an advantage. 1866 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1867 determined by the global setting of <TT>presolve</TT>, which can be 1868 changed via <TT>lp_set/2</TT>. The initial default is <TT>yes</TT>. 1869 Note that the presolve setting cannot be changed for a problem once it 1870 is set. If the external solver supports per-problem optimizer_params, 1871 their global defaults will be used for presolve(yes). 1872<P> 1873<DT><STRONG><TT>timeout(+TimeOut)</TT></STRONG> 1874 <DD>Set the external solver to time-out after <TT>TimeOut</TT> seconds. 1875 <TT>TimeOut</TT> is a positive number. The solver will abort (in either 1876 the abort or suboptimal state, depending on if a suboptimal solution 1877 was found) if the optimal solution was not found within the time 1878 limit. This should be used instead of setting the solver-specific 1879 parameter for time-out directly. In cases where the solver expects an 1880 integer for the time-out interval, the time given is rounded up to the 1881 next integer value. The timeout is set by setting the external solver's 1882 timeout settings, and the exact behaviour may be solver dependent. 1883<P> 1884<DT><STRONG><TT>suboptimal_handler(+Goal)</TT></STRONG> 1885 <DD>Specifies a user defined goal Goal to handle the case when the 1886 external solver returned a suboptimal solution (because the problem 1887 was aborted). Goal would be run in place of raising the default 1888 <TT>eplex_suboptimal</TT> event. 1889<P> 1890<DT><STRONG><TT>unbounded_handler(+Goal)</TT></STRONG> 1891 <DD>Specifies a user defined goal Goal to handle the case when the 1892 problem is unbounded. Goal would be run in place of raising the 1893 default <TT>eplex_unbounded</TT> event. 1894<DT><STRONG><TT>infeasible_handler(+Goal)</TT></STRONG> 1895 <DD>Specifies a user defined goal Goal to handle the case when the 1896 external solver found that the problem is infeasible. Goal would be run 1897 in place of raising the default <TT>eplex_infeasible</TT> event. Note 1898 that the default and logically correct behaviour is to fail, this 1899 handler is provided to allow the user to analyse the cause of the 1900 infeasibility. It is recommended that the handler should also fail 1901 after performing the analysis. 1902<P> 1903<P> 1904<DT><STRONG><TT>unknown_handler(+Goal)</TT></STRONG> 1905 <DD>Specifies a user defined goal Goal to handle the case when the 1906 external solver was not able to determine if the problem is unbounded 1907 or infeasible. Goal would be run in place of raising the default 1908 <TT>eplex_unknown</TT> event. 1909<P> 1910<DT><STRONG><TT>abort_handler(+Goal)</TT></STRONG> 1911 <DD>Specifies a user defined goal Goal to handle the case when the 1912 external solver aborted without finding any solution. Goal would be 1913 run in place of raising the default <TT>eplex_abort</TT> event. 1914<P> 1915<DT><STRONG><TT>use_var_names(+YesNo)</TT></STRONG> 1916 <DD>Specify if variable names (set using <TT>set_var_name/2</TT> of the 1917 var_name library) should be passed to the external solver. If a 1918 particular variable does not have a name when it is first passed to the 1919 external solver, a default name determined by the solver would be used. 1920 Note that for XPRESS-MP, there is a limit on the length of the name, 1921 which can be changed between 8 and 64 in steps of 8 with the 1922 parameter <TT>mpsnamelength (XPRS_MPSNAMELENGTH)</TT>. Variable 1923 names longer than this limit are truncated to the limit. 1924 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default is 1925 <TT>no</TT>. 1926<P> 1927 <DT><STRONG><TT>mip_use_copy(YesNo)</TT></STRONG> 1928 <DD>Some external solvers do not allow a MIP problem to be modified 1929 once the MIP search has been started. Eplex works around this 1930 problem by making a copy of the problem and solving that, so that 1931 the original problem can still be modified. This can be turned off to 1932 avoid the overhead of making this copy, in which case the MIP 1933 problem cannot be modified. This option is used only when solving a 1934 MIP problem, and the external solver does not allow a MIP problem to 1935 be modified; otherwise it is ignored. 1936 YesNo is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default 1937 is <TT>yes</TT> so that the problem can be modified. 1938<P> 1939 <DT><STRONG><TT>write_before_solve(Format,File)</TT></STRONG> 1940 <DD>This option is most useful for debugging purposes. If given, 1941 Eplex will ask the external solver to dump the problem each time 1942 the problem is solved. This allows the problem in an 1943 <TT>eplex_probe/2</TT> or <TT>lp_probe/3</TT> to be dumped. As in 1944 <TT>lp_write/3</TT>, <TT>Format</TT> is the format of the dumped 1945 file and <TT>File</TT> is its name. Note that the problem is dumped 1946 each time the external solver is invoked if the problem has cutpool 1947 constraints, where there may be multiple invocations of the solver 1948 per solver call. 1949 The default without this option is that the problem would not be 1950 dumped. 1951 1952 1953 <DT><STRONG><TT>post_equality_when_unified(+YesNo)</TT></STRONG> 1954 <DD>This option determines if an equality constraint between two 1955 variables will be posted to the solver when these variables are 1956 unified. Setting <TT>YesNo</TT> to no means that the constraint 1957 will <EM>not</EM> be posted. Note that this can lead to the 1958 solver's problem becoming inconsistent with ECLiPSe's. 1959<P> 1960<DT><STRONG><TT>sync_bounds(+YesNo)</TT></STRONG> 1961 <DD>This option determines if the bounds of the problems variables are 1962 synchronised with other solvers (i.e. the generic bounds are obtained 1963 with get_var_bounds/3 and then passed to the external solver) before 1964 the external solver is invoked. This was always done for previous 1965 non-standalone version of eplex. For standalone eplex, as the bounds 1966 are communicated directly to the external solver, the synchronisation 1967 of variable bounds is not needed unless the user is using eplex 1968 co-operatively with other solvers (e.g. ic). Even in such cases, it may 1969 be more efficient to communicate these bounds changes by explicitly 1970 programming it, especially if the problem has many variables and bounds 1971 changes happen only to a few of the variables. Setting <TT>YesNo</TT> 1972 to yes should increase compatibility with previous code (but note that 1973 previous eplex obtained the bounds from a specific bounds keeper like 1974 ic rather than the generic bounds). YesNo is one of the atoms 1975 <TT>yes</TT> or <TT>no</TT>, the default is <TT>no</TT>. 1976 1977</DL> 1978") 1979]). 1980 1981:- comment(lp_add/3, [ 1982amode: lp_add(+,+,+), 1983args: ["Handle": "Handle to a solver state", 1984 "NewNormCons": "List of new normalised constraints", 1985 "NewIntegers": "List of variables to be considered as integers" 1986 ], 1987see_also: [lp_setup/4], 1988resat: no, 1989summary: "Add new constraints to a solver state Handle.", 1990desc: html("\ 1991<P> 1992 Add new normalised constraints (with possibly new variables) to a solver. 1993 This is a lower level predicate called by lp_add_constraints/3 and when 1994 constraints are collected from the constraints pool by the solver. The 1995 constraints are not simplified and must already be normalised, so 1996 constraints which would otherwise be simplified away by the higher level 1997 predicates can be added to the external solver. The constraints will be 1998 removed on backtracking. Note that the solver will not be invoked directly. 1999</P><P> 2000 Note that variables in NewIntegers can be any problem variables. In 2001 previous versions of ECLiPSe, there was a restriction that the variables 2002 be new problem variables; this restriction has been removed. 2003</P> 2004") 2005]). 2006 2007:- comment(eplex_solve/1, [ 2008template: ["eplex_solve(-Cost)","EplexInstance:eplex_solve(-Cost)"], 2009args: [ 2010 "Cost": "Value of returned solution" 2011 ], 2012summary: "Explicitly invoke the external solver associated with EplexInstance.", 2013fail_if: "External solver was unable to find a solution (default behaviour)", 2014see_also: [eplex_solver_setup/4, eplex_solver_setup/1, eplex_var_get/3, eplex_get/2, 2015 ($=)/2,($=<)/2,($>=)/2,(=:=)/2, (>=)/2, (=<)/2, 2016 ($::)/2, (::)/2,integers/1, reals/1 2017 ], 2018desc: html("\ 2019<P> 2020 Explicitly triggers the solver associated with the eplex instance 2021 EplexInstance. If the solver was set up without any trigger conditions, 2022 then it needs to be explicitly triggered via a call to this predicate. 2023 The objective value of the solve is unified with Cost, which should be a 2024 free variable. 2025</P><P> 2026 The external solver's LP, QP or MIP solver is applied to the 2027 problem represented by the eplex instance. Precisely which method is used 2028 depends on the options given at set up. eplex_solve/1 fails if 2029 there is no solution or succeeds if an optimal solution is found, 2030 returning the solution's cost in Cost. After a success, various 2031 solution and status information can be retrieved using eplex_get/2 2032 and eplex_var_get/3. 2033</P><P> 2034 Normally, the external solver is invoked once per call in this 2035 predicate, but if the problem contain cutpool constraints (see 2036 lp_add_cutpool_constraints/4), then the external solver may be invoked 2037 repeatedly to produce a solution which does not violate the cutpool 2038 constraints. 2039</P><P> 2040 When a solver is triggered repeatedly, each invocation will 2041 automatically take into account the current variable bounds. The set of 2042 constraints considered by the solver is the one given when the solver 2043 was created plus any new constraints that were posted in the 2044 meantime. 2045</P><P> 2046 The user can define their own handlers (per eplex instance/problem) to 2047 handle cases where there was some error condition, or some limits were 2048 exceeded during the solving of the problem. If no handler was defined, 2049 by default an event would be raised. These are: 2050<DL> 2051 <DT>suboptimal handler (eplex_suboptimal event)<DD> 2052 This means that a solution was found but it may be suboptimal. 2053 The default behaviour is to print a warning and succeed. 2054 <DT>unbounded_handler (eplex_unbounded event)<DD> 2055 This means that the problem is unbounded. The default 2056 behaviour is to bind Cost to infinity (positive or negative 2057 depending on the optimisation direction), print a warning and 2058 succeed. CAUTION: No solution values are computed when the 2059 problem is unbounded, so unless the problem was set up with 2060 the solution(no) option, an error will occur when trying to 2061 continue as if the optimisation had succeeded. 2062 <DT>infeasible_handler (eplex_infeasible event)<DD> 2063 This means that the problem is infeasible. The default 2064 behaviour is to fail. Redefining this handler allows the 2065 examination of the failed problem, e.g. obtaining an IIS for it. 2066 <DT>unknown_handler (eplex_unknown event)<DD> 2067 This means that due to the solution method chosen, it is unknown 2068 whether the problem is unbounded or infeasible. The default 2069 behaviour is to print a warning and fail (even though this 2070 may be logically wrong!). 2071 <DT>abort_handler (eplex_abort event)<DD> 2072 Some other error condition occurred during optimisation. 2073 The default behaviour is to print an error and abort. 2074</DL> 2075</P><P> 2076 Note that the events are raised for the low-level primitive lp_solve/2, 2077 which is called by eplex_solve/1. 2078</P>"), 2079 exceptions:[ 2080 5: "EplexInstance does not a solver setup for it.", 2081 eplex_suboptimal : "Solution was found, but is possibly suboptimal", 2082 eplex_unbounded : "Problem is unbounded, no solution values", 2083 eplex_unknown : "Result is unknown (infeasible or unbounded)", 2084 eplex_abort : "External solver aborted for some reason", 2085 40: "Solver state had been previously destroyed." 2086 2087 ] 2088]). 2089 2090 2091:- comment(lp_solve/2, [ 2092amode: lp_solve(+,-), 2093args: ["Handle": "Handle to a solver state", 2094 "Cost": "Value of returned solution" 2095 ], 2096summary: "Explicitly invoke the external solver.", 2097fail_if: "External solver was unable to find a solution.", 2098see_also: [lp_setup/4, lp_add/3, lp_get/3, lp_var_get/4, 2099 lp_add_cutpool_constraints/4], 2100desc: html("\ 2101<P> 2102 A solver that was setup manually with lp_solve/2 needs to be 2103 triggered explicitly using this predicate. 2104</P><P> 2105 The external solver's LP, QP or MIP solver is applied to the 2106 problem represented by Handle. Precisely which method is used 2107 depends on the options given to lp_setup/4. lp_solve/2 fails if 2108 there is no solution or succeeds if an optimal solution is found, 2109 returning the solution's cost in Cost (unlike with lp_demon_setup/5, 2110 Cost gets instantiated to a number). After a success, various 2111 solution and status information can be retrieved using lp_get/3 2112 and lp_var_get/4. 2113</P><P> 2114 Normally, the external solver is invoked once per call in this 2115 predicate, but if the problem contain cutpool constraints (see 2116 lp_add_cutpool_constraints/4), then the external solver may be invoked 2117 repeatedly to produce a solution which does not violate the cutpool 2118 constraints. 2119</P><P> 2120 When a solver is triggered repeatedly, each invocation will 2121 automatically take into account the current variable bounds. The set of 2122 constraints considered by the solver is the one given when the solver 2123 was created plus any new constraints that were added (lp_add/3) in the 2124 meantime. 2125</P><P> 2126 The user can define their own handlers (per eplex instance/problem) to 2127 handle cases where there was some error condition, or some limits were 2128 exceeded during the solving of the problem. If no handler was defined, 2129 by default an event would be raised. These are: 2130<DL> 2131 <DT>suboptimal handler (eplex_suboptimal event)<DD> 2132 This means that a solution was found but it may be suboptimal. 2133 The default behaviour is to print a warning and succeed. 2134 <DT>unbounded_handler (eplex_unbounded event)<DD> 2135 This means that the problem is unbounded. The default 2136 behaviour is to bind Cost to infinity (positive or negative 2137 depending on the optimisation direction), print a warning and 2138 succeed. CAUTION: No solution values are computed when the 2139 problem is unbounded, so unless the problem was set up with 2140 the solution(no) option, an error will occur when trying to 2141 continue as if the optimisation had succeeded. 2142 <DT>infeasible_handler (eplex_infeasible event)<DD> 2143 This means that the problem is infeasible. The default 2144 behaviour is to fail. Redefining this handler allows the 2145 examination of the failed problem, e.g. obtaining an IIS for it. 2146 <DT>unknown_handler (eplex_unknown event)<DD> 2147 This means that due to the solution method chosen, it is unknown 2148 whether the problem is unbounded or infeasible. The default 2149 behaviour is to print a warning and fail (even though this 2150 may be logically wrong!). 2151 <DT>abort_handler (eplex_abort event)<DD> 2152 Some other error condition occurred during optimisation. 2153 The default behaviour is to print an error and abort. 2154</DL> 2155</P>"), 2156 exceptions:[ 2157 eplex_suboptimal : "Solution was found, but is possibly suboptimal", 2158 eplex_unbounded : "Problem is unbounded, no solution values", 2159 eplex_unknown : "Result is unknown (infeasible or unbounded)", 2160 eplex_abort : "External solver aborted for some reason", 2161 40: "Handle not valid: solver state had been destroyed by cleanup" 2162 ] 2163]). 2164 2165:- comment(eplex_probe/2, [ 2166template: ["eplex_probe(+Probes, -Cost)","EplexInstance:eplex_probe(+Probes, -Cost)"], 2167args: [ 2168 "Probes": "Temporary probe specification(s)", 2169 "Cost": "Value of solution" 2170 ], 2171summary: "Invoke EplexInstance's external solver, probing the problem" 2172 " temporarily modified by the probe specifications.", 2173see_also: [eplex_solve/1, eplex_solver_setup/1, eplex_solver_setup/4, 2174 eplex_get/2, eplex_var_get/3, eplex_set/2, lp_add_constraints/4], 2175desc: html("\ 2176<P> 2177 Similar to eplex_solve/1, but the problem is first temporarily modified 2178 as specified in Probes. Probes is a list of one or more probe 2179 specifications that specifies how the problem is modified. The 2180 objective value of the modified problem is unified with Cost 2181 after the solve. Cost should be a free variable. 2182</P><P> 2183 After the call to this predicate, the problem is restored for the 2184 external solver. However, the results from the probe (obtainable from 2185 eplex_var_get/3 and eplex_get/2) are retained. 2186</P><P> 2187 The following probe specifications are allowed: 2188<DL> 2189 <DT>min(Expr)/max(Expr)</DT><DD> 2190 Minimise/maximise the problem with the objective function Expr. 2191 Only existing problem variables can be given in Expr. Cannot be 2192 used in conjunction with objsense, objexpr or perturb_obj.</DD> 2193 <DT>objsense(Sense)</DT><DD> 2194 Sense is either min or max. Solves the problem with the original 2195 objective function, but with the sense given in Sense rather than 2196 that specified at setup. If only the sense of the objective is to 2197 be changed, this changes the objective more efficiently than using 2198 min(Expr)/max(Expr). Cannot be used in conjunction with min/max.</DD> 2199 <DT>objexpr(Expr)</DT><DD> 2200 Optimise the problem with respect to the objective function Expr, 2201 without changing the optimisation direction specified at problem 2202 setup. Cannot be used in conjunction with min/max or perturb_obj.</DD> 2203 <DT>perturb_obj(ObjDeltas)</DT><DD> 2204 Perturb the existing linear objective coefficients as specified by 2205 ObjDeltas. ObjDeltas is a (possibly empty) list of specifications 2206 Var : Delta, where Var is a problem variable and Delta is the 2207 amount its existing objective coefficient should be changed by. For 2208 example, if the existing objective is 2*X + 3*Y + Z, 2209 perturb_obj([X : 1, Y : -0.5]) will modify the objective to 2210 3*X + 2.5*Y + Z for the probe. If a variable occurs more than once in 2211 ObjDeltas, the change to the objective coefficient is cumulative. 2212 Perturb_obj is not strictly needed, as its effect can be achieved 2213 by constructing the whole objective and then probing with that. 2214 However, this can be expensive if most of the objective stays 2215 unchanged, with only a few of its coefficients changed. It is 2216 recommended that perturb_obj probe be used in such cases. 2217 Cannot be used in conjunction with objexpr or min/max.</DD> 2218 <DT>rhscoeffs(RhsCoeffs)</DT><DD> 2219 Alter the rhs coefficients of the matrix as specified by RhsCoeffs. 2220 RhsCoeffs is a (possibly empty) list of rhs coefficient 2221 specifications of the form Idx : Rhs, where Idx is the index of the 2222 expandable constraint obtained from using lp_add_constraints/4, and 2223 Rhs is the value for the right-hand side constant to use during the 2224 probe. Any constraints not specified in RhsCoeffs remain unchanged 2225 during the probe. If Idx occurs more than once in RhsCoeffs, the 2226 result is undefined.</DD> 2227 <DT>bounds(BoundsChanges)</DT><DD> 2228 Alter the bounds of problem variables as specified by 2229 BoundsChanges. BoundsChanges is a (possibly empty) list of bounds 2230 changes of the form Var $:: Lo..Hi, where Var is a problem variable 2231 and Lo and Hi are the new lower and upper bounds to use for the 2232 variable during the probe. Unlike normal bound changes, the bounds 2233 can be widened as well narrowed, although failure will still occur 2234 if Hi < Lo. Variables not specified in BoundsChanges retain their 2235 bounds during the probe. If Var occurs more than once in 2236 BoundsChanges, the result is undefined.</DD> 2237 <DT>fixed</DT><DD> 2238 The problem is solved as an LP problem by `fixing' the integer 2239 variables to their optimal MIP solution values. If there is an 2240 existing MIP solution for the problem, eplex will try to use that; 2241 otherwise, a MIP solution is obtained first. 2242 `Fixed' probing is useful for providing reduced costs for 2243 MIP problems. Note that reduced costs for the variables will only be 2244 available if the reduced_cost option for the problem is set to yes 2245 (this can be done either at problem setup, or by using 2246 eplex_set/2). For a problem without integer variables, the original 2247 problem is solved without change. Note that this probe 2248 specification is not available if the mip_use_copy option is set to 2249 no for external solvers that cannot modify a MIP problem. Cannot 2250 be used in conjunction with `relaxed'.</DD> 2251 <DT>relaxed</DT><DD> 2252 The problem is solved as an LP problem by relaxing all the integer 2253 constraints. For a problem with integer variables, this should be 2254 equivalent to the initial relaxation solved at the start of the MIP 2255 search. Depending on the solver, the discreteness of the integer 2256 variables may still be taken into account during presolve. To 2257 ensure that the problem solved is exactly the LP problem without 2258 any integer constraints, presolve should be off. For a problem 2259 without integer variables, the original problem is solved without 2260 change. Note that this probe specification is not available if the 2261 mip_use_copy option is set to no for external solvers that cannot 2262 modify a MIP problem. Cannot be used in conjunction with `fixed'.</DD> 2263 2264</DL> 2265</P>"), 2266fail_if: "External solver was unable to find a solution, or bounds probe" 2267 " used and the specified interval for some variable is empty", 2268exceptions:[ 2269 5: "EplexInstance does not have a solver setup for it.", 2270 eplex_suboptimal : "Solution was found, but is possibly suboptimal", 2271 eplex_unbounded : "Problem is unbounded, no solution values", 2272 eplex_unknown : "Result is unknown (infeasible or unbounded)", 2273 eplex_abort : "External solver aborted for some reason", 2274 abort : "Incorrect specification for the probe(s)", 2275 6: "mip_use_copy option was set to no (solver dependent) for probes" 2276 " that require yes.", 2277 40: "Solver state had been previously destroyed." 2278 ] 2279 2280]). 2281 2282:- comment(lp_probe/3, [ 2283amode: lp_probe(+,+,-), 2284args: ["Handle": "Handle to existing solver state", 2285 "Probes": "Temporary probe specification(s)", 2286 "Cost": "Value of solution" 2287 ], 2288summary: "Invoke external solver, probing the problem" 2289 " temporarily modified by the probe specifications.", 2290see_also: [lp_solve/2, lp_setup/4, lp_var_get/4, lp_get/3, lp_set/3, lp_add_constraints/4], 2291desc: html("\ 2292<P> 2293 Similar to lp_solve/2, but the problem is first temporarily modified 2294 as specified in Probes. Probes is a list of one or more probe 2295 specifications that specifies how the problem is modified. After the call 2296 to this predicate, the problem is restored for the external 2297 solver. However, the results from the probe (obtainable from 2298 lp_var_get/4 and lp_get/3) are retained. 2299</P><P> 2300 The following probe specifications are allowed: 2301<DL> 2302 <DT>min(Expr)/max(Expr)</DT><DD> 2303 Minimise/maximise the problem with the objective function Expr. 2304 Only existing problem variables can be given in Expr. Cannot be 2305 used in conjunction with objsense, objexpr or perturb_obj.</DD> 2306 <DT>objsense(Sense)</DT><DD> 2307 Sense is either min or max. Solves the problem with the original 2308 objective function, but with the sense given in Sense rather than 2309 that specified at setup. If only the sense of the objective is to 2310 be changed, this changes the objective more efficiently than using 2311 min(Expr)/max(Expr). Cannot be used in conjunction with min/max.</DD> 2312 <DT>objexpr(Expr)</DT><DD> 2313 Optimise the problem with respect to the objective function Expr, 2314 without changing the optimisation direction specified at problem 2315 setup. Cannot be used in conjunction with min/max or perturb_obj.</DD> 2316 <DT>perturb_obj(ObjDeltas)</DT><DD> 2317 Perturb the existing linear objective coefficients as specified by 2318 ObjDeltas. ObjDeltas is a (possibly empty) list of specifications 2319 Var : Delta, where Var is a problem variable and Delta is the 2320 amount its existing objective coefficient should be changed by. For 2321 example, if the existing objective is 2*X + 3*Y + Z, 2322 perturb_obj([X : 1, Y : -0.5]) will modify the objective to 2323 3*X + 2.5*Y + Z for the probe. If a variable occurs more than once in 2324 ObjDeltas, the change to the objective coefficient is cumulative. 2325 Perturb_obj is not strictly needed, as its effect can be achieved 2326 by constructing the whole objective and then probing with that. 2327 However, this can be expensive if most of the objective stays 2328 unchanged, with only a few of its coefficients changed. It is 2329 recommended that perturb_obj probe be used in such cases. 2330 Cannot be used in conjunction with objexpr or min/max.</DD> 2331 <DT>rhscoeffs(RhsCoeffs)</DT><DD> 2332 Alter the rhs coefficients of the matrix as specified by RhsCoeffs. 2333 RhsCoeffs is a (possibly empty) list of rhs coefficient 2334 specifications of the form Idx : Rhs, where Idx is the index of the 2335 expandable constraint obtained from using lp_add_constraints/4, and 2336 Rhs is the value for the right-hand side constant to use during the 2337 probe. Any constraints not specified in RhsCoeffs remain unchanged 2338 during the probe. If Idx occurs more than once in RhsCoeffs, the 2339 result is undefined.</DD> 2340 <DT>bounds(BoundsChanges)</DT><DD> 2341 Alter the bounds of problem variables as specified by 2342 BoundsChanges. BoundsChanges is a (possibly empty) list of bounds 2343 changes of the form Var $:: Lo..Hi, where Var is a problem variable 2344 and Lo and Hi are the new lower and upper bounds to use for the 2345 variable during the probe. Unlike normal bound changes, the bounds 2346 can be widened as well narrowed, although failure will still occur 2347 if Hi < Lo. Variables not specified in BoundsChanges retain their 2348 bounds during the probe. If Var occurs more than once in 2349 BoundsChanges, the result is undefined.</DD> 2350 <DT>fixed</DT><DD> 2351 The problem is solved as an LP problem by `fixing' the integer 2352 variables to their optimal MIP solution values. If there is an 2353 existing MIP solution for the problem, eplex will try to use that; 2354 otherwise, a MIP solution is obtained first. 2355 `Fixed' probing is useful for providing reduced costs for 2356 MIP problems. Note that reduced costs for the variables will only be 2357 available if the reduced_cost option for the problem is set to yes 2358 (this can be done either at problem setup, or by using 2359 eplex_set/2). For a problem without integer variables, the original 2360 problem is solved without change. Note that this probe 2361 specification is not available if the mip_use_copy option is set to 2362 no for external solvers that cannot modify a MIP problem. Cannot 2363 be used in conjunction with `relaxed'.</DD> 2364 <DT>relaxed</DT><DD> 2365 The problem is solved as an LP problem by relaxing all the integer 2366 constraints. For a problem with integer variables, this should be 2367 equivalent to the initial relaxation solved at the start of the MIP 2368 search. Depending on the solver, the discreteness of the integer 2369 variables may still be taken into account during presolve. To 2370 ensure that the problem solved is exactly the LP problem without 2371 any integer constraints, presolve should be off. For a problem 2372 without integer variables, the original problem is solved without 2373 change. Note that this probe specification is not available if the 2374 mip_use_copy option is set to no for external solvers that cannot 2375 modify a MIP problem. Cannot be used in conjunction with `fixed'.</DD> 2376 2377</DL> 2378</P>"), 2379fail_if: "External solver was unable to find a solution, or bounds probe" 2380 " used and the specified interval for some variable is empty", 2381exceptions:[ 2382 5: "EplexInstance does not have a solver setup for it.", 2383 eplex_suboptimal : "Solution was found, but is possibly suboptimal", 2384 eplex_unbounded : "Problem is unbounded, no solution values", 2385 eplex_unknown : "Result is unknown (infeasible or unbounded)", 2386 eplex_abort : "External solver aborted for some reason", 2387 abort : "Incorrect specification for the probe(s)", 2388 6: "mip_use_copy option was set to no (solver dependent) for probes" 2389 " that require yes.", 2390 40: "Handle not valid: solver state had been destroyed by cleanup" 2391 ] 2392]). 2393 2394:- comment(eplex_cleanup/0, [ 2395template: ["eplex_cleanup","EplexInstance:eplex_cleanup"], 2396summary: "Destroy the external solver associated with EplexInstance.", 2397desc: html("\ 2398<P> 2399 Destroy the specified solver, free all memory, etc. Note that ECLiPSe 2400 will normally do the cleanup automatically, for instance when execution 2401 fails across the solver setup. The solver is disassociated with 2402 EplexInstance, and any outstanding constraints not yet collected by the 2403 solver are removed, with a warning to the user. In effect, EplexInstance 2404 is reinitialised and can now be associated with a new solver without 2405 backtracking. Note that this last behaviour is unlike lp_cleanup/1, which 2406 also destroy the solver and disassociate it from the eplex instance (if 2407 any), but does not remove any outstanding constraints. 2408</P><P> 2409 This predicate should be used with caution as the information from the 2410 solver state will no longer be available. In particular, if the program 2411 backtracks to a point between the problem set up and clean up, 2412 accessing the solver state directly or indirectly (e.g. unifying a 2413 problem variable) will result in a stale handle error. 2414 2415</P>") 2416]). 2417 2418:- comment(lp_cleanup/1, [ 2419amode: lp_cleanup(+), 2420args: ["Handle": "Handle to a solver state"], 2421summary: "Destroy the specified solver Handle and clean up.", 2422desc: html("\ 2423<P> 2424 Destroy the specified solver, free all memory, etc. Note that ECLiPSe 2425 will normally do the cleanup automatically, for instance when execution 2426 fails across the solver setup, or when a solver handle gets garbage 2427 collected. 2428</P><P> 2429 This predicate should be used with caution as the information from the 2430 solver state will no longer be available. In particular, if the program 2431 backtracks to a point between the problem set up and clean up, 2432 accessing the solver state directly or indirectly (e.g. unifying a 2433 problem variable) will result in a stale handle error. 2434</P>") 2435]). 2436 2437:- comment(lp_read/3, [ 2438amode: lp_read(+,++,-), 2439args: ["File": "File name", 2440 "Format": "lp or mps", 2441 "Handle": "Returns a handle to the new solver state" 2442 ], 2443see_also: [lp_write/3, lp_setup/4, eplex_read/2, eplex_write/2, lp_probe/3], 2444summary: "Read a problem from a file and setup a solver for it.", 2445desc: html(" 2446 Read a problem from a file and setup a solver for it. Format is 2447 lp or mps. The result is a handle similar to the one obtained by 2448 lp_setup/4. Note that minimisation of the objective is assumed 2449 for mps format, as the sense of the objective is not included in 2450 the mps format. Minimisation is also assumed for external solvers 2451 that ignore the optimisation direction of the lp file (e.g. Xpress). 2452 Note also that although quadratic problems can be read in correctly if 2453 supported by the external solver, the quadratic objective coefficients 2454 are not extracted from the problem by eplex. These coefficients are 2455 used to set/reset the objective when a problem is probed with a 2456 different objective in eplex_probe/2 or lp_probe/3, so the objective 2457 will not be changed or restored correctly in this case. 2458") 2459]). 2460 2461:- comment(eplex_read/2, [ 2462template: ["eplex_read(++Format,++File)","EplexInstance:eplex_read(++Format,++File)"], 2463args: ["Format": "lp or mps", 2464 "File": "File name" 2465 ], 2466see_also: [eplex_write/2, lp_write/3, lp_setup/4, eplex_probe/2], 2467summary: "Read a problem from a file into eplex instance EplexInstance.", 2468exceptions: [5: "EplexInstance already has a solver setup for it."], 2469desc: html(" 2470 Read a problem from a file and setup a solver for it in EplexInstance. 2471 A solver should not already be setup for EplexInstance. Format is lp or 2472 mps. Note that minimisation of the objective is assumed for mps format, 2473 as the sense of the objective is not included in the mps format. 2474 Minimisation is also assumed for external solvers that ignore the 2475 optimisation direction of the lp file (e.g. Xpress). Note also that 2476 although quadratic problems can be read in correctly if supported by the 2477 external solver, the quadratic objective coefficients are not extracted 2478 from the problem by eplex. These coefficients are used to set/reset the 2479 objective when a problem is probed with a different objective in 2480 eplex_probe/2 or lp_probe/3, so the objective will not be changed or 2481 restored correctly in this case. 2482") 2483]). 2484 2485:- comment(lp_write/3, [ 2486amode: lp_write(+,++,+), 2487args: ["Handle": "Handle to an existing solver state", 2488 "Format": "lp or mps", 2489 "File": "File name" 2490 ], 2491see_also: [lp_read/3, lp_setup/4], 2492summary: "Write a solver problem to a file.", 2493desc: html(" 2494 Write the problem which corresponds to Handle to a file. The set of 2495 supported formats depends on the actual external solver which is used. 2496 All solvers support the mps format. Some solvers on some operating 2497 system platforms may change or append a suffix to the filename. Note 2498 that the mps format does not specify the sense (min or max) of the 2499 objective function. Note also that any active cutpool constraints in the 2500 problem will be included in the dump, even though they could be left out 2501 of the problem that the external solver actually solves.") 2502]). 2503 2504:- comment(eplex_write/2, [ 2505template: ["eplex_write(++Format,++File)","EplexInstance:eplex_write(++Format,++File)"], 2506args: ["Format": "lp or mps", 2507 "File": "File name" 2508 ], 2509see_also: [eplex_read/2, lp_write/3, lp_setup/4], 2510summary: "Write the problem in the solver for eplex instance" 2511" EplexInstance to a file.", 2512exceptions: [5: "EplexInstance does not a solver setup for it.", 2513 40: "Solver state had been previously destroyed." 2514 ], 2515desc: html(" 2516 Write the problem in the solver for EplexInstance to a file. The set of 2517 supported formats depends on the actual external solver which is used. 2518 All solvers support the mps format. Some solvers on some operating 2519 system platforms may change or append a suffix to the filename. 2520 Note that the mps format does not specify the sense (min or max) of the 2521 objective function. Minimisation is also assumed for external solvers 2522 that ignore the optimisation direction of the lp file (e.g. Xpress). 2523 Note also that any active cutpool constraints in the problem will be 2524 included in the dump, even though they could be left out of the problem 2525 that the external solver actually solves. 2526") 2527]). 2528 2529:- comment(eplex_get/2, [ 2530template: ["eplex_get(++ParamName, -Value)","EplexInstance:eplex_get(++ParamName, -Value)"], 2531args: [ 2532 "ParamName": "Name of parameter (atom)", 2533 "Value": "Returned value for ParamName" 2534 ], 2535summary: "Retrieve information about solver state and results for eplex instance EplexInstance.", 2536exceptions: [5: "EplexInstance does not a solver setup for it.", 2537 40: "Solver state had been previously destroyed." 2538 ], 2539see_also: [eplex_solver_setup/4, eplex_set/2, lp_set/3, lp_get/3, lp_add_constraints/4], 2540desc: html("\ 2541<P> 2542 Retrieve information about solver state and the logically most recent 2543 results for the eplex instance <TT>EplexInstance</TT>. <TT>ParamName</TT> 2544 is the same as that for lp_get/3, which retrieves the same information 2545 via the solver state. 2546</P> 2547 2548<DL> 2549<P> 2550 <DT><STRONG><TT>vars</TT></STRONG> 2551 <DD>Returns a term ''(X1,...,Xn) whose arity is the number of 2552 variables involved in the solver's constraint set, and whose 2553 arguments are these variables. 2554 2555<P> 2556 <DT><STRONG><TT>ints</TT></STRONG> 2557 <DD>Returns a list [Xi1,...,Xik] which is the subset of the problem 2558 variables that the solver considers to be integers. 2559 2560<P> 2561 <DT><STRONG><TT>constraints_norm</TT></STRONG> 2562 <DD>Returns a list of the problem constraints (excluding any cutpool 2563 constraints) in normalised form. They may be simplified with 2564 respect to the originals that were passed to the problem. 2565 2566<P> 2567 <DT><STRONG><TT>constraints</TT></STRONG> 2568 <DD>Returns a list of the problem constraints (excluding any cutppol 2569 constraints) in denormalised (readable) form. They may be 2570 simplified with respect to the originals that were passed to the 2571 problem. 2572 2573<P> 2574 <DT><STRONG><TT>objective</TT></STRONG> 2575 <DD>Returns a term min(E) or max(E), representing objective function 2576 and optimisation direction. E is a linear expression: any 2577 quadratic components will not be retrieved. 2578 2579<P> 2580 <DT><STRONG><TT>num_cols</TT></STRONG> 2581 <DD>Returns the number of columns (i.e. variables) in the matrix of the 2582 solver state. 2583 2584<P> 2585 <DT><STRONG><TT>num_rows</TT></STRONG> 2586 <DD>Returns the number of rows (i.e. constraints) in the matrix of the 2587 solver state. 2588 2589<P> 2590 <DT><STRONG><TT>num_nonzeros</TT></STRONG> 2591 <DD>Returns the number of non-zero coefficients in the matrix of the 2592 solver state. 2593 2594<P> 2595 <DT><STRONG><TT>num_ints</TT></STRONG> 2596 <DD>Returns the number of columns (i.e. variables) constrained to be 2597 integers in the matrix of the solver state. 2598 2599<P> 2600 <DT><STRONG><TT>num_quads</TT></STRONG> 2601 <DD>Returns the number of non-zero coefficients in the quadratic 2602 coefficient matrix (Q-matrix) of the solver state. 2603 2604<P> 2605 <DT><STRONG><TT>method</TT></STRONG> 2606 <DD>Returns the method that is specified to solve the problem. If an 2607 auxiliary method can be given for the method, and this auxiliary 2608 method is not <TT>default</TT>, the method will be returned as 2609 Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be 2610 <TT>default</TT> unless otherwise specified by the the user (at setup or 2611 via eplex_setup/2 or lp_setup/3). In that case, the external solver's 2612 defaults and any settings done via optimizer_param(_) will be used. 2613 2614<P> 2615 <DT><STRONG><TT>node_method</TT></STRONG> 2616 <DD>Applicable to MIP problems only. Returns the method that is 2617 specified to solve the problem at the nodes of the branch-and-bound 2618 tree. If an auxiliary method can be given for the method, and this 2619 auxiliary method is not <TT>default</TT>, the method will be returned 2620 as Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be 2621 <TT>default</TT> unless otherwise specified by the the user (at setup 2622 or via eplex_setup/2 or lp_setup/3). In that case, the external solver's 2623 defaults and any settings done via optimizer_param(_) will be used. 2624 2625<P> 2626 <DT><STRONG><TT>status</TT></STRONG> 2627 <DD>Status that was returned by the most recent invocation of the 2628 external solver. 2629 2630<P> 2631 <DT><STRONG><TT>cost</TT></STRONG> 2632 <DD>Objective value (i.e. cost/profit) of the current solution. 2633 Fails if no solution has been computed yet. 2634 2635<P> 2636 <DT><STRONG><TT>best_bound</TT></STRONG> 2637 <DD>The best bound (for minimisation, the lower bound) on the optimal 2638 objective value for the current problem. Together with the 2639 worst_bound, this specifies the range for the optimal objective 2640 value. Note that a non-empty range does not mean that the problem 2641 is feasible unless an objective value (cost) is also 2642 available. The best_bound is the same as the current objective 2643 value if the problem has been solved to optimality. It can be 2644 better than the objective value either because a) (for MIP 2645 problems only) the problem has been optimised to within the 2646 mipgap tolerance, or b) the problem was not solved to optimality, 2647 i.e. it was aborted before the optimal solution was found. 2648<P> 2649 <DT><STRONG><TT>worst_bound</TT></STRONG> 2650 <DD>The worst bound (for minimisation, the upper bound) on the optimal 2651 objective value for the current problem. Together with the 2652 best_bound, this specifies the range for the optimal objective 2653 value. Note that a non-empty range does not mean that the problem 2654 is feasible unless an objective value (cost) is also 2655 available. The worst_bound is the same as the current objective 2656 value if a solution has been computed for the problem, whether 2657 the problem was solved to optimality or not. Depending on the 2658 problem type and method used to solve the problem, a worst bound 2659 can be returned for a problem even if the solving of the problem 2660 was aborted before a solution was obtained. 2661<P> 2662 <DT><STRONG><TT>typed_solution</TT></STRONG> 2663 <DD>Returns a term ''(X1,...,Xn) whose arguments are the properly 2664 typed (integer or float) solution values for the corresponding 2665 problem variables (<TT>vars</TT>). The floating point solutions 2666 are the same as returned by <TT>solution</TT>, the integers are 2667 obtained by rounding the corresponding floating-point solution to 2668 the nearest integer. To instantiate the problem variables to 2669 their solutions, unify this term with the corresponding term 2670 containing the variables. Note that this unification could fail 2671 if two problem variables Xa and Xb were unified after the solution 2672 was lasted computed, as the solutions values in the Xa and Xb 2673 positions could be different, even though they are now represented 2674 by one variable. 2675 Fails if no solution has been computed yet. 2676 2677<PRE> 2678 instantiate_solution(Handle) :- 2679 lp_get(Handle, vars, Vars), 2680 lp_get(Handle, typed_solution, Values), 2681 Vars = Values. 2682</PRE> 2683 2684<P> 2685 <DT><STRONG><TT>slack</TT></STRONG> 2686 <DD>Returns a list of floating-point values representing the constraint 2687 slacks in the logically last solve. The problem consists of normal 2688 constraints followed by any added cutpool constraints, and the 2689 order corresponds to the list order in <TT>constraints</TT> for 2690 normal constraints, and to cutpool_info(last_added,Info) for the 2691 cutpool constraints. Fails if no solution has been computed yet. 2692 2693<P> 2694 <DT><STRONG><TT>slack(Indexes)</TT></STRONG> 2695 <DD>Returns a list of floating-point values representing the slack 2696 values for the constraints represented by Indexes. Indexes are a 2697 list of constraint indices (as returned by lp_add_constraints/4 for 2698 normal constraints, and lp_add_cutpool_constraints/4 for cutpool 2699 constraints), and the order of the returned list corresponds to the 2700 order in <TT>Indexes</TT>. Fails if no slack value has been 2701 computed yet for any of the constraints in Indexes -- note that 2702 values are only computed for cutpool constraints if they were added 2703 to the problem. 2704 2705<P> 2706 <DT><STRONG><TT>dual_solution</TT></STRONG> 2707 <DD>Returns a list of floating-point values representing the dual 2708 solutions in the logically last solve. The problem consists of 2709 normal constraints followed by any added cutpool constraints, and 2710 the order corresponds to the list order in <TT>constraints</TT> for 2711 normal constraints, and to cutpool_info(last_added,Info) for the 2712 cutpool constraints. Fails if no solution has been computed yet. 2713 2714<P> 2715 <DT><STRONG><TT>dual_solution(Indexes)</TT></STRONG> 2716 <DD>Returns a list of floating-point values representing the dual 2717 solutions for the constraints represented by Indexes. Indexes are a 2718 list of constraint indices (as returned by lp_add_constraints/4 2719 normal constraints, and lp_add_cutpool_constraints/4 for cutpool 2720 constraints), and the order of the returned list corresponds to the 2721 order in <TT>Indexes</TT>. Fails if no dual solution has been 2722 computed yet for any of the constraints in Indexes -- note that 2723 values are only computed for cutpool constraints if they were added 2724 to the problem. 2725 2726<P> 2727 <DT><STRONG><TT>constraints(Indexes)</TT></STRONG> 2728 <DD>Returns a list of problem constraints as specified by 2729 Indexes in denormalised form. The constraints can be either 2730 normal constraints or cutpool constraints. 2731<P> 2732 <DT><STRONG><TT>constraints_norm(Indexes)</TT></STRONG> 2733 <DD>Returns a list of problem constraints as specified by 2734 Indexes in normalised form. The constraints can be either 2735 normal constraints or cutpool constraints. 2736<P> 2737 <DT><STRONG><TT>cutpool_info(Select,Info)</TT></STRONG> 2738 <DD>Returns the information specified by Info for the cutpool constraints 2739 specified by Select. The returned information is either 2740 i) a pair of lists Indexes-Values where Indexes is the index for 2741 the constraint in the corresponding position of Values, or 2742 ii) a list of Indexes if the information requested is index. Info 2743 can be: 2744<DL> 2745 <DT><STRONG><TT>index</TT></STRONG> 2746 <DD>the indexes for the selected constraints. A list 2747 of Indexes are returned. 2748 <DT><STRONG><TT>active</TT></STRONG> 2749 <DD>the current active status of the selected constraints. 2750 The status is either 0 (not active) or 1 (active). 2751 A pair of lists Indexes-ActiveStatus is returned. 2752 <DT><STRONG><TT>add_initially</TT></STRONG> 2753 <DD>the current add_initially status of the selected 2754 constraints. The status is either 0 (not add) or 1 (add). 2755 Note that although inactive constraints have a 2756 add_initially status, they will not be added to a problem. 2757 A pair of lists Indexes-AddInitially is returned. 2758 <DT><STRONG><TT>binding_state</TT></STRONG> 2759 <DD>the binding state for the selected constraints in the 2760 logically last solve for the problem. A pair of lists 2761 Indexes-BindingStates is returned. To get this 2762 information, the slack values must be available from the 2763 last solve. 2764 The state can be: 2765 a) binding - the constraint was satisfied and binding, i.e. 2766 it is within tolerance of its RHS value in the 2767 normalised form. 2768 b) satisfied - the constraint was satisfied but not 2769 binding. 2770 c) inactive - the constraint was inactive. 2771 <DT><STRONG><TT>constraints_norm</TT></STRONG> 2772 <DD>the normalised form of the constraints for the selected 2773 constraints is returned in a pair of lists 2774 Indexes-Constraints. 2775 <DT><STRONG><TT>constraints</TT></STRONG> 2776 <DD>the denormalised form of the constraints for the selected 2777 constraints is returned in a pair of lists 2778 Indexes-Constraints. 2779</DL> 2780 2781 The constraints are selected by Select, which can be: 2782<DL> 2783 <DT><STRONG><TT>cstr(Idx)</TT></STRONG> 2784 <DD>The cutpool constraint as specified by <TT>Idx</TT>. 2785 <DT><STRONG><TT>group(Name)</TT></STRONG> 2786 <DD>The cutpool constraints in the group <TT>Name</TT>. Both 2787 active and non-active constraints are returned. Note that 2788 the name of the default group is the atom nil (<TT>[]</TT>). 2789 <DT><STRONG><TT>last_added</TT></STRONG> 2790 <DD>The cutpool constraints that were added to the 2791 problem in the logically previous solve of the problem. 2792 The constraints were either added initially, or were 2793 added because they were violated in an intermediate 2794 invocation. 2795 <DT><STRONG><TT>last_notadded</TT></STRONG> 2796 <DD>The cutpool constraints that were not added to the 2797 problem in the logically previous solve of the problem, 2798 i.e. they were not violated. 2799 <DT><STRONG><TT>last_inactive</TT></STRONG> 2800 <DD>The cutpool constraints that were inactive during the 2801 logically last solve of the problem. This does not 2802 include any constraints that were added since the last 2803 solve. 2804</DL> 2805<P> 2806 <DT><STRONG><TT>demon_tolerance</TT></STRONG> 2807 <DD>Returns a comma-separated pair <TT>(RealTol,IntTol)</TT> of 2808 floating-point values which specify how far outside a variable's 2809 range an lp-solution can fall before lp_demon_setup/5 2810 re-triggers. The tolerances differ for real (default 0.00001) and 2811 integer (default 0.5) variables. 2812 2813<P> 2814 <DT><STRONG><TT>simplex_iterations</TT></STRONG> 2815 <DD>Returns the external solver's count of simplex iterations. 2816 2817<P> 2818 <DT><STRONG><TT>node_count</TT></STRONG> 2819 <DD>Returns the external MIP solver's node count. Note that this may 2820 or may not include the initial root node. 2821<P> 2822 <DT><STRONG><TT>statistics</TT></STRONG> 2823 <DD>Returns a list of counter values <TT>[Successes, Failures, 2824 Aborts]</TT>, indicating how often lp_solve/2 was invoked on the 2825 Handle, and how many invocations succeeded, failed and aborted 2826 respectively. 2827 2828<P> 2829 <DT><TT>timeout</TT></STRONG> 2830 <DD>Returns the time-out value for the solver state. This is the amount 2831 of CPU time in seconds that the external solver will be allow to 2832 spend solving the problem before timing out. The value is 0 if 2833 no time-out has been set. 2834<P> 2835 <DT><STRONG><TT>optimizer_param(Param)</TT></STRONG> 2836 <DD>Returns the value of the external solver's parameter Param 2837 for the problem represented by Handle. The external solver 2838 has a number of parameters that affect the way they work, and 2839 this queries their values. If Param is not a valid parameter for 2840 the solver, an out of range exception is raised. See below for 2841 more details on the parameters. 2842<P> 2843 <DT><STRONG><TT>post_equality_when_unified</TT></STRONG> 2844 <DD>Returns the value (yes or no) if an equality constraint will be 2845 posted to a solver if two variables in the solver's problem are 2846 unified. 2847<P> 2848 <DT><STRONG><TT>pool</TT></STRONG> 2849 <DD>Returns the name of the eplex instance (if any) associated with 2850 the solver state. Fails otherwise. Only useful if called with 2851 lp_get/3. 2852<P> 2853 <DT><STRONG><TT>handle</TT></STRONG> 2854 <DD>Returns the solver state handle (if any) associated with the eplex 2855 instance. Fails otherwise. Only useful if called with eplex_get/2. 2856<P> 2857</DL> 2858Note that reduced_cost, slack, dual_solution can only be retrieved 2859when previously requested in the option list of lp_setup/4 or with lp_set/3. 2860An out of range error will be raised otherwise. 2861 2862<P> 2863For the external solver's control parameter specified by 2864optimizer_param(Param), Param must be an atom. The Value returned is 2865either an integer, float or atom, depending on the parameter. The parameter 2866is generally specific to a solver and version, and also, they may be 2867problem specific, or global, again depending on the solver version. In all 2868cases, the value returned by lp_get/3 is the current value for the parameter 2869for the problem Handle. Refer to the solver documentation for details on the 2870parameters. The names of the parameters are derived from the names of the 2871parameters in the external solver. For CPLEX, take the parameter name from 2872the CPLEX manual (or cplex.h), remove the CPX_PARAM_ prefix and convert the 2873rest to lower case, e.g. 2874 2875<PRE> 2876 CPX_PARAM_NODELIM becomes nodelim. 2877</PRE> 2878For XPRESS-MP (version 13 and newer), take the parameter name from the 2879manual (or xpresso.h), remove the XPRS_ prefix (if present) and convert 2880the rest to lower case, e.g. 2881<PRE> 2882 XPRS_MAXNODE becomes maxnode. 2883</PRE> 2884<P> 2885For Gurobi, take the parameter name from the manual and convert it to 2886all lower case, e.g. 2887<PRE> 2888 IntFeasTol becomes intfeastol. 2889</PRE> 2890<P> 2891For solvers used via the OSI, there are a few generic parameters supported 2892via OSI, and depending on the actual solver, there may be some additional 2893solver-specific parameters. For the generic parameters, take the parameter 2894name, remove the Osi prefix and convert the rest to lower case, e.g. 2895<PRE> 2896 OsiPrimalTolerance becomes primaltolerance 2897</PRE> 2898 2899<P> 2900 The following parameter names are additional aliases that work for 2901 several solvers: 2902<DL> 2903 <DT><TT>feasibility_tol</TT> 2904 <DD>CPX_PARAM_EPRHS (CPLEX) or XPRS_FEASTOL (XPRESS-MP) or 2905 OsiPrimalTolerance (OSI) or FeasibilityTol (GRB) - float 2906 <DT><TT>integrality</TT> 2907 <DD>CPX_PARAM_EPINT (CPLEX) or XPRS_MIPTOL (XPRESS-MP) or 2908 CbcIntegerTolerance (OSI,Cbc specific) or IntFeasTol (GRB) - float 2909 <DT><TT>iteration_limit</TT> 2910 <DD>CPX_PARAM_ITLIM (CPLEX) or XPRS_LPITERLIMIT (XPRESS-MP) or 2911 OsiMaxNumIteration (OSI) or IterationLimit (GRB) - integer 2912 <DT><TT>node_limit</TT> 2913 <DD>CPX_PARAM_NODELIM (CPLEX) or XPRS_MAXNODE (XPRESS-MP) or 2914 CbcMaxNumNode (OSI, Cbc specific) or NodeLimit (GRB)- integer 2915 <DT><TT>objdifference</TT> 2916 <DD>CPX_PARAM_OBJDIF (CPLEX) or XPRS_MIPADDCUTOFF (XPRESS-MP) or 2917 CbcCutoffIncrement (OSI, Cbc specific) - float 2918</DL> 2919 2920 ") 2921]). 2922 2923:- comment(lp_get/3, [ 2924amode: lp_get(+,++,-), 2925args: ["Handle": "Handle to an existing solver state", 2926 "ParamName": "Name of parameter (atom or structure)", 2927 "Value": "Returned value for ParamName" 2928 ], 2929summary: "Retrieve information about solver state and results for solver state Handle.", 2930see_also: [lp_setup/4, lp_set/3, eplex_get/2, lp_add_constraints/4], 2931desc: html("\ 2932<P> 2933 Retrieve information about solver state and results for the (logically) 2934 most recent solved solver state represented by <TT>Handle</TT>. 2935 <TT>ParamName</TT> is the same as that for eplex_get/2, which retrieves 2936 the same information via the EplexInstance. 2937 It can be one of: 2938</P> 2939 2940<DL> 2941<P> 2942 <DT><STRONG><TT>vars</TT></STRONG> 2943 <DD>Returns a term ''(X1,...,Xn) whose arity is the number of 2944 variables involved in the solver's constraint set, and whose 2945 arguments are these variables. 2946 2947<P> 2948 <DT><STRONG><TT>ints</TT></STRONG> 2949 <DD>Returns a list [Xi1,...,Xik] which is the subset of the problem 2950 variables that the solver considers to be integers. 2951 2952<P> 2953 <DT><STRONG><TT>constraints_norm</TT></STRONG> 2954 <DD>Returns a list of the problem constraints (excluding any cutpool 2955 constraints) in normalised form. They may be simplified with 2956 respect to the originals that were passed to the problem. 2957 2958<P> 2959 <DT><STRONG><TT>constraints</TT></STRONG> 2960 <DD>Returns a list of the problem constraints (excluding any cutpool 2961 constraints) in denormalised (readable) form. They may be 2962 simplified with respect to the originals that were passed to the 2963 problem. 2964 2965<P> 2966 <DT><STRONG><TT>objective</TT></STRONG> 2967 <DD>Returns a term min(E) or max(E), representing objective function 2968 and optimisation direction. E is a linear expression: any 2969 quadratic components will not be retrieved. 2970 2971<P> 2972 <DT><STRONG><TT>num_cols</TT></STRONG> 2973 <DD>Returns the number of columns (i.e. variables) in the matrix of the 2974 solver state. 2975 2976<P> 2977 <DT><STRONG><TT>num_rows</TT></STRONG> 2978 <DD>Returns the number of rows (i.e. constraints) in the matrix of the 2979 solver state. 2980 2981<P> 2982 <DT><STRONG><TT>num_nonzeros</TT></STRONG> 2983 <DD>Returns the number of non-zero coefficients in the matrix of the 2984 solver state. 2985 2986<P> 2987 <DT><STRONG><TT>num_ints</TT></STRONG> 2988 <DD>Returns the number of columns (i.e. variables) constrained to be 2989 integers in the matrix of the solver state. 2990 2991<P> 2992 <DT><STRONG><TT>num_quads</TT></STRONG> 2993 <DD>Returns the number of non-zero coefficients in the quadratic 2994 coefficient matrix (Q-matrix) of the solver state. 2995 2996<P> 2997 <DT><STRONG><TT>method</TT></STRONG> 2998 <DD>Returns the method that is specified to solve the problem. If an 2999 auxiliary method can be given for the method, and this auxiliary 3000 method is not <TT>default</TT>, the method will be returned as 3001 Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be 3002 <TT>default</TT> unless otherwise specified by the the user (at setup or 3003 via eplex_setup/2 or lp_setup/3). In that case, the external solver's 3004 defaults and any settings done via optimizer_param(_) will be used. 3005 3006<P> 3007 <DT><STRONG><TT>node_method</TT></STRONG> 3008 <DD>Applicable to MIP problems only. Returns the method that is 3009 specified to solve the problem at the nodes of the branch-and-bound 3010 tree. If an auxiliary method can be given for the method, and this 3011 auxiliary method is not <TT>default</TT>, the method will be returned 3012 as Method(Aux), e.g. <TT>barrier(none)</TT>. The method will be 3013 <TT>default</TT> unless otherwise specified by the the user (at setup or 3014 via eplex_setup/2 or lp_setup/3). In that case, the external solver's 3015 defaults and any settings done via optimizer_param(_) will be used. 3016 3017<P> 3018 <DT><STRONG><TT>status</TT></STRONG> 3019 <DD>Status that was returned by the most recent invocation of the 3020 external solver. 3021 3022<P> 3023 <DT><STRONG><TT>cost</TT></STRONG> 3024 <DD>Cost of the current solution. 3025 Fails if no solution has been computed yet. 3026 3027<P> 3028 <DT><STRONG><TT>best_bound</TT></STRONG> 3029 <DD>The best bound (for minimisation, the lower bound) on the optimal 3030 objective value for the current problem. Together with the 3031 worst_bound, this specifies the range for the optimal objective 3032 value. Note that a non-empty range does not mean that the problem 3033 is feasible unless an objective value (cost) is also 3034 available. The best_bound is the same as the current objective 3035 value if the problem has been solved to optimality. It can be 3036 better than the objective value either because a) (for MIP 3037 problems only) the problem has been optimised to within the 3038 mipgap tolerance, or b) the problem was not solved to optimality, 3039 i.e. it was aborted before the optimal solution was found. 3040<P> 3041 <DT><STRONG><TT>worst_bound</TT></STRONG> 3042 <DD>The worst bound (for minimisation, the upper bound) on the optimal 3043 objective value for the current problem. Together with the 3044 best_bound, this specifies the range for the optimal objective 3045 value. Note that a non-empty range does not mean that the problem 3046 is feasible unless an objective value (cost) is also 3047 available. The worst_bound is the same as the current objective 3048 value if a solution has been computed for the problem, whether 3049 the problem was solved to optimality or not. Depending on the 3050 problem type and method used to solve the problem, a worst bound 3051 can be returned for a problem even if the solving of the problem 3052 was aborted before a solution was obtained. 3053<P> 3054 <DT><STRONG><TT>typed_solution</TT></STRONG> 3055 <DD>Returns a term ''(X1,...,Xn) whose arguments are the properly 3056 typed (integer or float) solution values for the corresponding 3057 problem variables (<TT>vars</TT>). The floating point solutions 3058 are the same as returned by <TT>solution</TT>, the integers are 3059 obtained by rounding the corresponding floating-point solution to 3060 the nearest integer. To instantiate the problem variables to 3061 their solutions, unify this term with the corresponding term 3062 containing the variables: 3063 3064<PRE> 3065 instantiate_solution(Handle) :- 3066 lp_get(Handle, vars, Vars), 3067 lp_get(Handle, typed_solution, Values), 3068 Vars = Values. 3069</PRE> 3070<P> 3071 Note that this unification could fail if two problem variables Xa 3072 and Xb were unified after the solution was lasted computed, as the 3073 solutions values in the Xa and Xb positions could be different, 3074 even though they are now represented by one variable. 3075 Fails if no solution has been computed yet. 3076 3077</P><P> 3078 <DT><STRONG><TT>slack</TT></STRONG> 3079 <DD>Returns a list of floating-point values representing the constraint 3080 slacks in the logically last solve. The problem consists of normal 3081 constraints followed by any added cutpool constraints, and the 3082 order corresponds to the list order in <TT>constraints</TT> for 3083 normal constraints, and to cutpool_info(last_added,Info) for the 3084 cutpool constraints. Fails if no solution has been computed yet. 3085 3086<P> 3087 <DT><STRONG><TT>slack(Indexes)</TT></STRONG> 3088 <DD>Returns a list of floating-point values representing the slack 3089 values for the constraints represented by Indexes. Indexes are a 3090 list of constraint indices (as returned by lp_add_constraints/4 for 3091 normal constraints, and lp_add_cutpool_constraints/4 for cutpool 3092 constraints), and the order of the returned list corresponds to the 3093 order in <TT>Indexes</TT>. Fails if no slack value has been 3094 computed yet for any of the constraints in Indexes -- note that 3095 values are only computed for cutpool constraints if they were added 3096 to the problem. 3097 3098<P> 3099 <DT><STRONG><TT>dual_solution</TT></STRONG> 3100 <DD>Returns a list of floating-point values representing the dual 3101 solutions in the logically last solve. The problem consists of 3102 normal constraints followed by any added cutpool constraints, and 3103 the order corresponds to the list order in <TT>constraints</TT> for 3104 normal constraints, and to cutpool_info(last_added,Info) for the 3105 cutpool constraints. Fails if no solution has been computed yet. 3106 3107<P> 3108 <DT><STRONG><TT>dual_solution(Indexes)</TT></STRONG> 3109 <DD>Returns a list of floating-point values representing the dual 3110 solutions for the constraints represented by Indexes. Indexes are a 3111 list of constraint indices (as returned by lp_add_constraints/4 3112 normal constraints, and lp_add_cutpool_constraints/4 for cutpool 3113 constraints), and the order of the returned list corresponds to the 3114 order in <TT>Indexes</TT>. Fails if no dual solution has been 3115 computed yet for any of the constraints in Indexes -- note that 3116 values are only computed for cutpool constraints if they were added 3117 to the problem. 3118 3119<P> 3120 <DT><STRONG><TT>constraints(Indexes)</TT></STRONG> 3121 <DD>Returns a list of problem constraints as specified by 3122 Indexes in denormalised form. The constraints can be either 3123 normal constraints or cutpool constraints. 3124<P> 3125 <DT><STRONG><TT>constraints_norm(Indexes)</TT></STRONG> 3126 <DD>Returns a list of problem constraints as specified by 3127 Indexes in normalised form. The constraints can be either 3128 normal constraints or cutpool constraints. 3129<P> 3130 <DT><STRONG><TT>cutpool_info(Select,Info)</TT></STRONG> 3131 <DD>Returns the information specified by Info for the cutpool constraints 3132 specified by Select. The returned information is either 3133 i) a pair of lists Indexes-Values where Indexes is the index for 3134 the constraint in the corresponding position of Values, or 3135 ii) a list of Indexes if the information requested is index. Info 3136 can be: 3137<DL> 3138 <DT><STRONG><TT>index</TT></STRONG> 3139 <DD>the indexes for the selected constraints. A list 3140 of Indexes are returned. 3141 <DT><STRONG><TT>active</TT></STRONG> 3142 <DD>the current active status of the selected constraints. 3143 The status is either 0 (not active) or 1 (active). 3144 A pair of lists Indexes-ActiveStatus is returned. 3145 <DT><STRONG><TT>add_initially</TT></STRONG> 3146 <DD>the current add_initially status of the selected 3147 constraints. The status is either 0 (not add) or 1 (add). 3148 Note that although inactive constraints have a 3149 add_initially status, they will not be added to a problem. 3150 A pair of lists Indexes-AddInitially is returned. 3151 <DT><STRONG><TT>binding_state</TT></STRONG> 3152 <DD>the binding state for the selected constraints in the 3153 logically last solve for the problem. A pair of lists 3154 Indexes-BindingStates is returned. To get this 3155 information, the slack values must be available from the 3156 last solve. 3157 The state can be: 3158 a) binding - the constraint was satisfied and binding, i.e. 3159 it is within tolerance of its RHS value in the 3160 normalised form. 3161 b) satisfied - the constraint was satisfied but not 3162 binding. 3163 c) inactive - the constraint was inactive. 3164 <DT><STRONG><TT>constraints_norm</TT></STRONG> 3165 <DD>the normalised form of the constraints for the selected 3166 constraints is returned in a pair of lists 3167 Indexes-Constraints. 3168 <DT><STRONG><TT>constraints</TT></STRONG> 3169 <DD>the denormalised form of the constraints for the selected 3170 constraints is returned in a pair of lists 3171 Indexes-Constraints. 3172</DL> 3173 3174 The constraints are selected by Select, which can be: 3175<DL> 3176 <DT><STRONG><TT>cstr(Idx)</TT></STRONG> 3177 <DD>The cutpool constraint as specified by <TT>Idx</TT>. 3178 <DT><STRONG><TT>group(Name)</TT></STRONG> 3179 <DD>The cutpool constraints in the group <TT>Name</TT>. Both 3180 active and non-active constraints are returned. Note that 3181 the name of the default group is the atom nil (<TT>[]</TT>). 3182 <DT><STRONG><TT>last_added</TT></STRONG> 3183 <DD>The cutpool constraints that were added to the 3184 problem in the logically previous solve of the problem. 3185 The constraints were either added initially, or were 3186 added because they were violated in an intermediate 3187 invocation. 3188 <DT><STRONG><TT>last_notadded</TT></STRONG> 3189 <DD>The cutpool constraints that were not added to the 3190 problem in the logically previous solve of the problem, 3191 i.e. they were not violated. 3192 <DT><STRONG><TT>last_inactive</TT></STRONG> 3193 <DD>The cutpool constraints that were inactive during the 3194 logically last solve of the problem. This does not 3195 include any constraints that were added since the last 3196 solve. 3197</DL> 3198 3199<P> 3200 <DT><STRONG><TT>demon_tolerance</TT></STRONG> 3201 <DD>Returns a comma-separated pair <TT>(RealTol,IntTol)</TT> of 3202 floating-point values which specify how far outside a variable's 3203 range an lp-solution can fall before lp_demon_setup/5 3204 re-triggers. The tolerances differ for real (default 0.00001) and 3205 integer (default 0.5) variables. 3206 3207<P> 3208 <DT><STRONG><TT>simplex_iterations</TT></STRONG> 3209 <DD>Returns the external solver's count of simplex iterations. 3210 3211<P> 3212 <DT><STRONG><TT>node_count</TT></STRONG> 3213 <DD>Returns the external MIP solver's node count. 3214 3215<P> 3216 <DT><STRONG><TT>statistics</TT></STRONG> 3217 <DD>Returns a list of counter values <TT>[Successes, Failures, 3218 Aborts]</TT>, indicating how often lp_solve/2 was invoked on the 3219 Handle, and how many invocations succeeded, failed and aborted 3220 respectively. 3221 3222<P> 3223 <DT><TT>timeout</TT></STRONG> 3224 <DD>Returns the time-out value for the solver state. This is the amount 3225 of CPU time in seconds that the external solver will be allow to 3226 spend solving the problem before timing out. The value is 0 if 3227 no time-out has been set. 3228<P> 3229 <DT><STRONG><TT>optimizer_param(Param)</TT></STRONG> 3230 <DD>Returns the value of the external solver's parameter Param 3231 for the problem represented by Handle. The external solver 3232 has a number of parameters that affect the way they work, and 3233 this queries their values. If Param is not a valid parameter for 3234 the solver, an out of range exception is raised. See below for 3235 more details on the parameters. 3236<P> 3237 <DT><STRONG><TT>post_equality_when_unified</TT></STRONG> 3238 <DD>Returns the value (yes or no) if an equality constraint will be 3239 posted to a solver if two variables in the solver's problem are 3240 unified. 3241<P> 3242 <DT><STRONG><TT>pool</TT></STRONG> 3243 <DD>Returns the name of the eplex instance (if any) associated with 3244 the solver state. Fails otherwise. Only useful if called with 3245 lp_get/3. 3246<P> 3247 <DT><STRONG><TT>handle</TT></STRONG> 3248 <DD>Returns the solver state handle (if any) associated with the eplex 3249 instance. Fails otherwise. Only useful if called with eplex_get/2. 3250<P> 3251</DL> 3252Note that reduced_cost, slack, dual_solution can only be retrieved 3253when previously requested in the option list of lp_setup/4 or with lp_set/3. 3254An out of range error would be raised otherwise. 3255 3256<P> 3257For the external solver's control parameter specified by 3258optimizer_param(Param), Param must be an atom. The Value returned is 3259either an integer, float or atom, depending on the parameter. The parameter 3260is generally specific to a solver and version, and also, they may be 3261problem specific, or global, again depending on the solver version. In all 3262cases, the value returned by lp_get/3 is the current value for the parameter 3263for the problem Handle. Refer to the solver documentation for details on the 3264parameters. The names of the parameters are derived from the names of the 3265parameters in the external solver. For CPLEX, take the parameter name from 3266the CPLEX manual (or cplex.h), remove the CPX_PARAM_ prefix and convert the 3267rest to lower case, e.g. 3268 3269<PRE> 3270 CPX_PARAM_NODELIM becomes nodelim. 3271</PRE> 3272For XPRESS-MP (version 13 and newer), take the parameter name from the 3273manual (or xpresso.h), remove the XPRS_ prefix (if present) and convert 3274the rest to lower case, e.g. 3275<PRE> 3276 XPRS_MAXNODE becomes maxnode. 3277</PRE> 3278For Gurobi, take the parameter name from the manual and convert it to 3279all lower case, e.g. 3280<PRE> 3281 IntFeasTol becomes intfeastol. 3282</PRE> 3283<P> 3284For solvers used via the OSI, there are a few generic parameters supported 3285via OSI, and depending on the actual solver, there may be some additional 3286solver-specific parameters. For the generic parameters, take the parameter 3287name, remove the Osi prefix and convert the rest to lower case, e.g. 3288<PRE> 3289 OsiPrimalTolerance becomes primaltolerance 3290</PRE> 3291 3292<P> 3293 The following parameter names are additional aliases that work for 3294 either solver: 3295<DL> 3296 <DT><TT>feasibility_tol</TT> 3297 <DD>CPX_PARAM_EPRHS (CPLEX) or XPRS_FEASTOL (XPRESS-MP) or 3298 OsiPrimalTolerance (OSI) or FeasibilityTol (GRB) - float 3299 <DT><TT>integrality</TT> 3300 <DD>CPX_PARAM_EPINT (CPLEX) or XPRS_MIPTOL (XPRESS-MP) or 3301 CbcIntegerTolerance (OSI,Cbc specific) or IntFeasTol (GRB) - float 3302 <DT><TT>iteration_limit</TT> 3303 <DD>CPX_PARAM_ITLIM (CPLEX) or XPRS_LPITERLIMIT (XPRESS-MP) or 3304 OsiMaxNumIteration (OSI) or IterationLimit (GRB) - integer 3305 <DT><TT>node_limit</TT> 3306 <DD>CPX_PARAM_NODELIM (CPLEX) or XPRS_MAXNODE (XPRESS-MP) or 3307 CbcMaxNumNode (OSI, Cbc specific) or NodeLimit (GRB)- integer 3308 <DT><TT>objdifference</TT> 3309 <DD>CPX_PARAM_OBJDIF (CPLEX) or XPRS_MIPADDCUTOFF (XPRESS-MP) or 3310 CbcCutoffIncrement (OSI, Cbc specific) - float 3311</DL> 3312 3313") 3314]). 3315 3316 3317:- comment(lp_set/3, [ 3318amode: lp_set(+,++,+), 3319args: ["Handle": "Handle to a solver state", 3320 "What": "Option to set", 3321 "Value": "Value being set" 3322 ], 3323resat: no, 3324summary: "Change initial options for solver state Handle.", 3325see_also: [lp_setup/4, lp_get/3, lp_var_get/4, lp_get_iis/5, eplex_set/2], 3326desc: html("\ 3327<P> 3328This primitive can be used to change some of the initial options 3329even after setup. 3330<EM>Handle</EM> refers to an existing solver state, 3331<EM>What</EM> can be one of the following: 3332 3333 3334<DL> 3335 <DT><STRONG><TT>method</TT></STRONG> 3336 <DD>Set the method that will be used to solve the problem. Value 3337 is one of <TT>default, auto, primal, dual, net, net(Simplex), barrier, 3338 barrier(Crossover), sifting, sifting(SubMethod), concurrent, 3339 concurrent_det</TT>. Simplex can be one of <TT>default, auto, primal, dual</TT>, 3340 specifying the Simplex method to use in the Network Simplex algorithm. 3341 Crossover can be one of <TT>default, auto, primal, dual, none</TT>, 3342 specifying the crossover method to use for the barrier method. 3343 SubMethod could be one of default, auto, primal, dual, net, barrier</TT>, 3344 specifying the method to use for the subproblems in the sifting method. 3345 Note that not every method is available on every external solver. 3346 In case of MIP solving, this is the start algorithm (the one that 3347 is used to solve the initial relaxation). This method setting will 3348 override similar settings done via optimizer_param(_). 3349 3350<P> 3351 <DT><STRONG><TT>node_method</TT></STRONG> 3352 <DD>Applicable to MIP problems only. Set the method that will be 3353 used to solve the problem at the nodes (except the root) of the 3354 branch-and-bound tree. Note that the method for solving the root 3355 node is controlled by the <TT>method</TT> option. Value can be set 3356 to the same values as in the <TT>method</TT> option, although 3357 there may be more restrictions on what the actual methods/auxiliary 3358 methods that are allowed in combination with the root method, 3359 due to limitations/restrictions from the external solver. A warning 3360 will be given when the problem is solved if this is the case, and 3361 the default method used instead. This node_method setting will 3362 override similar settings done via optimizer_param(_). 3363 3364<P> 3365 <DT><STRONG><TT>solution</TT></STRONG> 3366 <DD>Make the solutions available each time the problem has been 3367 (re-)solved successfully. 3368 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3369 3370<P> 3371 <DT><STRONG><TT>reduced_cost</TT></STRONG> 3372 <DD>Make the reduced costs available each time the problem has been 3373 (re-)solved successfully. If the problem is a MIP, then depending on 3374 the external solver, this is either unavailable or are the values for 3375 the optimal LP node. 3376 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3377 3378<P> 3379 <DT><STRONG><TT>slack</TT></STRONG> 3380 <DD>Make the constraint slacks available each time the problem has been 3381 (re-)solved successfully. 3382 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3383 3384<P> 3385 <DT><STRONG><TT>dual_solution</TT></STRONG> 3386 <DD>Make the dual solutions available each time the problem has been 3387 (re-)solved successfully. If the problem is a MIP, then depending on 3388 the external solver, this is either unavailable or are the values for 3389 the optimal LP node. 3390 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3391 3392<P> 3393 <DT><STRONG><TT>keep_basis</TT></STRONG> 3394 <DD>Store the basis each time the problem has been solved successfully, 3395 and use this basis as a starting point for re-solving next time. 3396 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3397 3398<P> 3399 <DT><STRONG><TT>mipstart</TT></STRONG> 3400 <DD>Use the previous solution values as a warm-start heuristics for 3401 the MIP search. This only has an effect for certain solvers (e.g. 3402 Gurobi), if there are integrality constraints, and if there is a 3403 previous solution available. Possible values are <TT>none</TT> 3404 (no mipstart values, the default), <TT>all</TT> (use previous 3405 solution for all variables), or <TT>integers</TT> (use previous 3406 solution for all variables that are now constrained to be integral). 3407 3408<P> 3409 <DT><STRONG><TT>cache_iis</TT></STRONG> 3410 <DD>When a problem is found to be infeasible, compute an IIS for the problem 3411 (if supported by the external solver), and store it so that it can bee retrieved 3412 by eplex_get_iis/4 or lp_get_iis/5. This will be done before the problem can 3413 be modified and make the computing of the IIS impossible. The IIS will oulu 3414 be available before the problem is solved again, and before the infeasible 3415 solve is backtracked. This option has no effect if the external solver does not 3416 support the finding of IIS. Note that if this option is set, eplex will always ask 3417 for an IIS to computed for an infeasible problem, even if it is immediately backtracked 3418 by the infeasible handler failing, and that the option is only needed if the problem 3419 instance in the external solver is modified before eplex_get_iis/4 or lp_get_iis/5 is called. 3420 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3421 3422<P> 3423 <DT><STRONG><TT>demon_tolerance</TT></STRONG> 3424 <DD>Specify how far outside a variable's range an lp-solution 3425 can fall before lp_demon_setup/5 re-triggers. 3426 Value is a comma-separated pair <TT>(RealTol,IntTol)</TT> of 3427 floating-point values (default <TT>(0.00001,0.5)</TT>). 3428 3429<P> 3430 <DT><STRONG><TT>use_var_names</TT></STRONG> 3431 <DD>Specify if variable names (set using <TT>set_var_name/2</TT> of 3432 the var_name library) should be passed to the external solver. If a 3433 particular variable does not have a name, a solver's default name 3434 would be used. Note that for XPRESS-MP, there is a limit on the length 3435 of the name, which can be changed between 8 and 64 in steps of 8 with 3436 the parameter <TT>N_NAMLEN</TT>. Variable names longer than this limit 3437 are truncated to the limit. 3438 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>, the default 3439 is <TT>no</TT>. 3440 3441<P> 3442 <DT><STRONG><TT>timeout</TT></STRONG> 3443 <DD>Set the external solver to time-out after <TT>Value</TT> 3444 seconds. The solver will abort (in either the abort or suboptimal 3445 state, depending on if a suboptimal solution was found) if the 3446 optimal solution was not found within the time limit. In cases 3447 where the solver expects an integer for the time-out interval, the 3448 time given is rounded up to the next integer value. This should be 3449 used instead of the solver specific optimizer_param(Param) for 3450 setting timeouts, as eplex sets these parameter(s) itself. Note 3451 that the exact behaviour of the timeout setting is solver dependent. 3452 Value is a positive number. 3453<P> 3454 <DT><STRONG><TT>cutpool_option(Idx,Option)</TT></STRONG> 3455 <DD>Set the option Option as specified by Value for the cutpool 3456 constraint with index Idx. Option is one of the following: 3457<DL> 3458 <DT><STRONG><TT>active</TT></STRONG> 3459 <DD>Set the active status for the constraint Idx to Value. 3460 Value can be 0 or 1. 0 is non-active, 1 is active. 3461 <DT><STRONG><TT>add_initially</TT></STRONG> 3462 <DD>Specify if the constraint Idx should be added to a 3463 problem before the solver is invoked. 3464 Value can be 0 or 1. 1 is to add initially, 0 not. 3465</DL> 3466</P><P> 3467 Note that the option is <STRONG>not</STRONG> undone on 3468 backtracking. 3469</P><P> 3470 <DT><STRONG><TT>cutpool_group</TT></STRONG> 3471 <DD>Value is an atom, and is used to specify the name of a group of 3472 cutpool constraints. If Name is not a current group name, a new 3473 group with that name is created. Once created, a named group exists 3474 until the problem is destroyed. The default group (with the atom 3475 nil (<TT>[]</TT>) as its name) is predefined and does not need to 3476 be created with <TT>cutpool_group</TT>. 3477<P> 3478 <DT><STRONG><TT>suboptimal_handler</TT></STRONG> 3479 <DD>Value is a user defined goal to handle the case when the 3480 external solver returned a suboptimal solution (because the problem 3481 was aborted). Value would replace any existing suboptimal handler, 3482 and would also be run in place of raising the default 3483 <TT>eplex_suboptimal</TT> event. 3484<P> 3485 <DT><STRONG><TT>unbounded_handler</TT></STRONG> 3486 <DD>Value is a user defined goal to handle the case when the 3487 problem is unbounded. Value would replace any existing unbounded 3488 handler, and would be run in place of raising the default 3489 <TT>eplex_unbounded</TT> event. 3490<P> 3491 <DT><STRONG><TT>infeasible_handler</TT></STRONG> 3492 <DD>Value is a user defined goal to handle the case when the 3493 external solver found the problem to be infeasible. Value would 3494 replace any existing infeasible handler, and would be run in place 3495 of raising the default <TT>eplex_infeasible</TT> event. Note that 3496 the default and logically correct behaviour is to fail, this 3497 handler is provided to allow the user to analyse the cause of the 3498 infeasibility. It is recommended that the handler should also fail 3499 after performing the analysis. 3500<P> 3501 <DT><STRONG><TT>unknown_handler</TT></STRONG> 3502 <DD>Value is a user defined goal to handle the case when the 3503 external solver was not able to determine if the problem is 3504 unbounded Value would replace any existing unknown handler, and 3505 would be run in place of raising the default <TT>eplex_unknown</TT> 3506 event. 3507<P> 3508 <DT><STRONG><TT>abort_handler</TT></STRONG> 3509 <DD>Value is a user defined goal to handle the case when the 3510 external solver aborted without finding any solution. Value would 3511 replace any existing abort handler, and would be run in place of 3512 raising the default <TT>eplex_abort</TT> event. 3513<P> 3514 <DT><STRONG><TT>optimizer_param(Param)</TT></STRONG> 3515 <DD>Set the external solver's control parameter Param for the problem 3516 <TT>Handle</TT>. If the solver's parameters are global and not 3517 problem specific, an unimplemented functionality exception would 3518 be raised. See lp_get/3 for more details on the external solver's 3519 parameters. Note that the new setting is <EM>not</EM> undone on 3520 backtracking. 3521<P> 3522 <DT><STRONG><TT>write_before_solve</TT></STRONG> 3523 <DD>Value can be the pair (Format,File) or the atom no. If 3524 (Format,File) is given, Eplex will ask the external solver to dump 3525 the problem each time the solver is solved. This allows the problem 3526 in an <TT>eplex_probe/2</TT> or <TT>lp_probe/3</TT> to be dumped. As 3527 in <TT>lp_write/3</TT>, <TT>Format</TT> is the format of the dumped 3528 problem, and File is the filename. See for more details. Note that 3529 the problem is dumped each time the external solver is invoked if 3530 the problem has cutpool constraints, where there may be multiple 3531 invocations of the solver per solver call. `no' for Value will turn 3532 off this dumping. 3533<P> 3534 <DT><STRONG><TT>post_equality_when_unified</TT></STRONG> 3535 <DD>Value can be the atoms yes or no. Determines if an equality 3536 constraint between two solver variables will be posted to the 3537 solver when these variables are unified. Setting Value to no means 3538 that the constraint will <EM>not</EM> be posted. Note that this can 3539 lead to the solver's problem becoming inconsistent with 3540 ECLiPSe's. 3541<P> 3542</DL> 3543 Making solutions available means that they can be retrieved using 3544 lp_get/3 or lp_var_get/4 after the solver has been run successfully. 3545</P><P> 3546 All settings apart from optimizer_param(Param) and cutpool settings 3547 will be undone on backtracking! 3548</P>") 3549]). 3550 3551:- comment(eplex_set/2, [ 3552template: ["eplex_set(++ParamName, -Value)","EplexInstance:eplex_set(++ParamName, -Value)"], 3553args: [ 3554 "ParamName": "Name of parameter (atom)", 3555 "Value": "New value for ParamName" 3556 ], 3557resat: no, 3558summary: "Change initial options for solver state associated with EplexInstance", 3559exceptions: [5: "EplexInstance does not a solver setup for it.", 3560 40: "Solver state had been previously destroyed." 3561 ], 3562see_also: [eplex_solver_setup/4, eplex_set/2, eplex_get_iis/4, lp_set/3, lp_get/3], 3563desc: html("\ 3564<P> 3565This primitive can be used to change some of the initial options 3566even after setup of a solver for eplex instance <EM>EplexInstance</EM>. 3567<EM>What</EM> can be one of the following: 3568 3569<DL> 3570 <DT><STRONG><TT>method</TT></STRONG> 3571 <DD>Set the method that will be used to solve the problem. Value 3572 is one of <TT>default, auto, primal, dual, net, net(Simplex), barrier, 3573 barrier(Crossover), sifting, sifting(SubMethod), concurrent, 3574 concurrent_det</TT>. Simplex can be one of <TT>default, auto, primal, dual</TT>, 3575 specifying the Simplex method to use in the Network Simplex algorithm. 3576 Crossover can be one of <TT>default, auto, primal, dual, none</TT>, 3577 specifying the crossover method to use for the barrier method. 3578 SubMethod could be one of default, auto, primal, dual, net, barrier</TT>, 3579 specifying the method to use for the subproblems in the sifting method. 3580 Note that not every method is available on every external solver. 3581 In case of MIP solving, this is the start algorithm (the one that 3582 is used to solve the initial relaxation). This method setting will 3583 override similar settings done via optimizer_param(_). 3584 3585<P> 3586 <DT><STRONG><TT>node_method</TT></STRONG> 3587 <DD>Applicable to MIP problems only. Set the method that will be 3588 used to solve the problem at the nodes (except the root) of the 3589 branch-and-bound tree. Note that the method for solving the root 3590 node is controlled by the <TT>method</TT> option. Value can be set 3591 to the same values as in the <TT>method</TT> option, although 3592 there may be more restrictions on what the actual methods/auxiliary 3593 methods that are allowed in combination with the root method, 3594 due to limitations/restrictions from the external solver. A warning 3595 will be given when the problem is solved if this is the case, and 3596 the default method used instead. This node_method setting will 3597 override similar settings done via optimizer_param(_). 3598 3599<P> 3600 <DT><STRONG><TT>solution</TT></STRONG> 3601 <DD>Make the solutions available each time the problem has been 3602 (re-)solved successfully. 3603 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3604 3605<P> 3606 <DT><STRONG><TT>reduced_cost</TT></STRONG> 3607 <DD>Make the reduced costs available each time the problem has been 3608 (re-)solved successfully. If the problem is a MIP, then depending on 3609 the external solver, this is either unavailable or are the values 3610 for the optimal LP node. 3611 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3612 3613<P> 3614 <DT><STRONG><TT>slack</TT></STRONG> 3615 <DD>Make the constraint slacks available each time the problem has been 3616 (re-)solved successfully. 3617 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3618 3619<P> 3620 <DT><STRONG><TT>dual_solution</TT></STRONG> 3621 <DD>Make the dual solutions available each time the problem has been 3622 (re-)solved successfully. If the problem is a MIP, then depending on 3623 the external solver, this is either unavailable or are the values 3624 for the optimal LP node. 3625 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3626 3627<P> 3628 <DT><STRONG><TT>keep_basis</TT></STRONG> 3629 <DD>Store the basis each time the problem has been solved successfully, 3630 and use this basis as a starting point for re-solving next time. 3631 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3632 3633<P> 3634 <DT><STRONG><TT>mipstart</TT></STRONG> 3635 <DD>Use the previous solution values as a warm-start heuristics for 3636 the MIP search. This only has an effect for certain solvers (e.g. 3637 Gurobi), if there are integrality constraints, and if there is a 3638 previous solution available. Possible values are <TT>none</TT> 3639 (no mipstart values, the default), <TT>all</TT> (use previous 3640 solution for all variables), or <TT>integers</TT> (use previous 3641 solution for all variables that are now constrained to be integral). 3642 3643<P> 3644 <DT><STRONG><TT>cache_iis</TT></STRONG> 3645 <DD>When a problem is found to be infeasible, compute an IIS for the problem 3646 (if supported by the external solver), and store it so that it can bee retrieved 3647 by eplex_get_iis/4 or lp_get_iis/5. This will be done before the problem can 3648 be modified and make the computing of the IIS impossible. The IIS will only 3649 be available before the problem is solved again, and before the infeasible 3650 solve is backtracked. This option has no effect if the external solver does not 3651 support the finding of IIS. Note that if this option is set, eplex will always ask 3652 for an IIS to computed for an infeasible problem, even if it is immediately backtracked 3653 by the infeasible handler failing, and that the option is only needed if the problem 3654 instance in the external solver is modified before eplex_get_iis/4 or lp_get_iis/5 is called. 3655 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3656 3657<P> 3658 <DT><STRONG><TT>demon_tolerance</TT></STRONG> 3659 <DD>Specify how far outside a variable's range an lp-solution 3660 can fall before lp_demon_setup/5 re-triggers. 3661 Value is a comma-separated pair <TT>(RealTol,IntTol)</TT> of 3662 floating-point values (default <TT>(0.00001,0.5)</TT>). 3663 3664<P> 3665 <DT><STRONG><TT>use_var_names</TT></STRONG> 3666 <DD>Specify if variable names (set using <TT>set_var_name/2</TT> of the 3667 var_name library) should be passed to the external solver. If a 3668 particular variable does not have a name, a solver's default name 3669 would be used. Note that for XPRESS-MP, there is a limit on the 3670 length of the name, which can be changed between 8 and 64 in steps 3671 of 8 with the parameter <TT>N_NAMLEN</TT>. Variable names longer 3672 than this limit are truncated to the limit. Note also that only 3673 new variables from constraints added after the <TT>lp_set/3</TT> call 3674 will pass their names to the external solver. 3675 Value is one of the atoms <TT>yes</TT> or <TT>no</TT>. 3676<P> 3677 <DT><STRONG><TT>timeout</TT></STRONG> 3678 <DD>Set the external solver to time-out after <TT>Value</TT> 3679 seconds. The solver will abort (in either the abort or suboptimal 3680 state, depending on if a suboptimal solution was found) if the 3681 optimal solution was not found within the time limit. In cases 3682 where the solver expects an integer for the time-out interval, the 3683 time given is rounded up to the next integer value. This should be 3684 used instead of the solver specific optimizer_param(Param) for 3685 setting timeouts, as eplex sets these parameter(s) itself. Note 3686 that the exact behaviour of the timeout setting is solver dependent. 3687 Value is a positive number. 3688<P> 3689<DT><STRONG><TT>suboptimal_handler</TT></STRONG> 3690 <DD>Value is a user defined goal to handle the case when the 3691 external solver returned a suboptimal solution (because the problem 3692 was aborted). Value would replace any existing suboptimal handler, 3693 and would also be run in place of raising the default 3694 <TT>eplex_suboptimal</TT> event. 3695<P> 3696<DT><STRONG><TT>unbounded_handler</TT></STRONG> 3697 <DD>Value is a user defined goal to handle the case when the 3698 problem is unbounded. Value would replace any existing unbounded 3699 handler, and would be run in place of raising the default 3700 <TT>eplex_unbounded</TT> event. 3701<P> 3702<DT><STRONG><TT>infeasible_handler</TT></STRONG> 3703 <DD>Value is a user defined goal to handle the case when the 3704 external solver found the problem to be infeasible. Value would 3705 replace any existing infeasible handler, and would be run in place 3706 of raising the default <TT>eplex_infeasible</TT> event. Note that 3707 the default and logically correct behaviour is to fail, this 3708 handler is provided to allow the user to analyse the cause of the 3709 infeasibility. It is recommended that the handler should also fail 3710 after performing the analysis. 3711<P> 3712<DT><STRONG><TT>unknown_handler</TT></STRONG> 3713 <DD>Value is a user defined goal to handle the case when the 3714 external solver was not able to determine if the problem is 3715 unbounded Value would replace any existing unknown handler, and 3716 would be run in place of raising the default <TT>eplex_unknown</TT> 3717 event. 3718<P> 3719<DT><STRONG><TT>abort_handler</TT></STRONG> 3720 <DD>Value is a user defined goal to handle the case when the 3721 external solver aborted without finding any solution. Value would 3722 replace any existing abort handler, and would be run in place of 3723 raising the default <TT>eplex_abort</TT> event. 3724<P> 3725 <DT><STRONG><TT>optimizer_param(Param)</TT></STRONG> 3726 <DD>Set the external solver's control parameter Param for the problem 3727 <TT>Handle</TT>. If the solver's parameters are global and not 3728 problem specific, an unimplemented functionality exception would 3729 be raised. See lp_get/3 for more details on the external solver's 3730 parameters. Note that the new setting is <EM>not</EM> undone on 3731 backtracking. 3732<P> 3733 <DT><STRONG><TT>write_before_solve</TT></STRONG> 3734 <DD>Value can be the pair (Format,File) or the atom no. If 3735 (Format,File) is given, Eplex will ask the external solver to dump 3736 the problem each time the solver is solved. This allows the problem 3737 in an <TT>eplex_probe/2</TT> or <TT>lp_probe/3</TT> to be dumped. As 3738 in <TT>lp_write/3</TT>, <TT>Format</TT> is the format of the dumped 3739 problem, and File is the filename. See for more details. Note that 3740 the problem is dumped each time the external solver is invoked if 3741 the problem has cutpool constraints, where there may be multiple 3742 invocations of the solver per solver call. `no' for Value will turn 3743 off this dumping. 3744<P> 3745 <DT><STRONG><TT>post_equality_when_unified</TT></STRONG> 3746 <DD>Value can be the atoms yes or no. Determines if an equality 3747 constraint will be posted to a solver when two of its variables are 3748 unified. Setting Value to no means that the constraint will not be 3749 posted. Note that this could mean that the 3750 solver's problem may become inconsistent with ECLiPSe's. 3751<P> 3752</DL> 3753 Making solutions available means that they can be retrieved using 3754 lp_get/3 or lp_var_get/4 after the solver has been run successfully. 3755</P><P> 3756 All settings apart from optimizer_param(Param) will be undone on backtracking! 3757</P>") 3758]). 3759 3760 3761 3762:- comment(lp_get/2, [ 3763amode: lp_get(++,-), 3764amode: lp_get(++,+), 3765args: ["ParamName": "Atom or structure", 3766 "Value": "Variable, integer, float or atom" 3767 ], 3768summary: "Obtain the value of a global parameter.", 3769see_also: [lp_set/2], 3770desc: html("\ 3771 Eplex has a number of global (i.e. not specific to a 3772 particular problem) parameters. These can be queried using this 3773 predicate. 3774<DL> 3775 <DT><TT>has_indicator_constraints</TT> 3776 <DD>Returns 'yes' if the solver supports =≥/2 indicator constraints, 3777 else 'no'. 3778 <DT><TT>has_miqp</TT> 3779 <DD>Returns 'yes' if the solver supports mixed integer problems 3780 with quadratic objectives, else 'no'. 3781 <DT><TT>has_qp</TT> 3782 <DD>Returns 'yes' if the solver supports quadratic objectives, 3783 else 'no'. 3784 <DT><TT>optimizer</TT> 3785 <DD>Returns the name of the external solver, currently 3786 'cplex', 'xpress', 'osi' or gurobi. 3787 <DT><TT>optimizer_version</TT> 3788 <DD>Returns an integer derived from the version of the 3789 external solver (for osi, the version is the actual solvers 3790 used, including any significant third-party packages such as 3791 sparse matrix ordering packages required by the barrier solver) 3792 <DT><TT>presolve</TT> 3793 <DD>Returns the default presolve setting for solver setup, i.e. the 3794 presolve setting that a solver state would be given if it was not 3795 directly specified during setup. A value of 0 disables presolving. 3796 A value of 1 either enables presolving (for external solvers that 3797 have only global parameters), or uses the default optimizer_param 3798 settings (for external solvers with per-problem parameters). 3799 <DT><TT>timeout</TT> 3800 <DD>Returns the default time-out setting that a solver state would 3801 be given if it was not directly specified during setup. Value is 3802 0 if there is no time-out. 3803 <DT><TT>optimizer_param(Param)</TT> 3804 <DD>Get the Value of the external solver's parameter <TT>Param</TT>. 3805 The exact behaviour and available parameters are dependent on the 3806 external solver: if the external solver has only problem specific 3807 parameters (e.g. XPRESS-MP 13 and later), this gets the default 3808 setting that would be used for new problems; if the external solver 3809 has global parameters, this gets the global value for the parameter. 3810 If Param is not a valid parameter for the solver, an out of range 3811 error is raised. See lp_get/3 for more details on the parameters. 3812</DL> 3813") 3814]). 3815 3816:- comment(lp_set/2, [ 3817amode: lp_set(++,++), 3818args: ["ParamName": "Atom or structure", 3819 "Value": "Integer, float, string or structure" 3820 ], 3821see_also: [lp_get/2], 3822resat: no, 3823summary: "Set a global parameter for the external solver.", 3824desc: html(" 3825<P> 3826 Set a global parameter. The parameter names are the same as described 3827 in lp_get/2. For the timeout parameter, Value can be of any numeric 3828 type. Note that for the external solver's parameters (set via 3829 optimizer_param(Param)), the exact behaviour is solver dependent: if 3830 the solver has global parameters, this sets the value of the parameter 3831 globally; otherwise, this sets the default value of the parameter that 3832 would be assigned to a new problem. The setting is <EM>not</EM> undone 3833 on backtracking. 3834</P><P> 3835 In addition, lp_set/2 is used to control the output from the external 3836 solver: 3837<DL> 3838 <DT><TT>lp_set(SolverChannel, +(Stream))</TT> 3839 <DD>Send output from SolverChannel to the ECLiPSe I/O stream Stream. 3840 <DT><TT>lp_set(SolverChannel, -(Stream))</TT> 3841 <DD>Stop sending output from SolverChannel to the ECLiPSe I/O stream 3842 Stream. 3843</DL> 3844 SolverChannel is one of <TT>result_channel, error_channel, warning_channel, 3845 log_channel</TT>, and Stream is an ECLiPSe stream identifier (e.g. 3846 <TT>output</TT>, or the result of an open/3 operation). 3847<P> 3848 By default, <TT>error_channel</TT> is directed to ECLiPSe's 3849 <TT>error</TT> stream, <TT>warning_channel</TT> to <TT>warning_output</TT> 3850 while <TT>result_channel</TT> and <TT>log_channel</TT> are suppressed. 3851 To see the output on these channels, do 3852</P> 3853<TT><PRE> 3854 :- lp_set(result_channel, +output). 3855 :- lp_set(log_channel, +log_output). 3856</PRE></TT> 3857<P> 3858Similarly, to create a log file: 3859<TT><PRE> 3860 :- open('mylog.log', write, logstream), lp_set(log_channel, +logstream). 3861</PRE></TT> 3862and to stop logging: 3863<TT><PRE> 3864 :- lp_set(log_channel, -logstream), close(logstream). 3865</PRE></TT> 3866</P>") 3867]). 3868 3869:- comment(reduced_cost_pruning/2, [ 3870summary:"Prune bounds of all problem variables based on their reduced costs", 3871amode: reduced_cost_pruning(+,?), 3872args: ["Handle": "Handle to a (solved) solver state", 3873 "GlobalCost": "Bounded global cost variable"], 3874see_also: [lp_demon_setup/5], 3875fail_if: "None", 3876desc:html(" 3877 <P> 3878 Handle is a problem handle referring to the linear relaxation of 3879 a more complex problem. GlobalCost is the overall cost variable 3880 of the complex problem. 3881 </P><P> 3882 This predicate tries to prune the bounds of all variables that 3883 occur in the linear relaxation, based on their reduced costs, 3884 the optimum of the relaxation, and the currently known bounds 3885 (lower if maximising, upper if minimising) on the global cost. 3886 </P><P> 3887 This predicate should be called just after the Handle has been solved. 3888 In particular, it can be used as the post-goal in an lp-demon. 3889 The solver should have been set up with the <TT>reduced_cost(yes)</TT> 3890 option. 3891 </P><P> 3892 Note that the bounds of GlobalCost is obtained using the generic 3893 get_var_bounds/3. For correct pruning, GlobalCost should only have 3894 bounds that are relevant to this problem. 3895 3896")]). 3897 3898:- comment(lp_var_occurrence/3, [ 3899amode: lp_var_occurrence(?,+,-), 3900amode: lp_var_occurrence(?,-,-), 3901args: ["Var": "Variable", 3902 "Handle": "Handle to a solver state, or a variable", 3903 "Index": "Column number for Var in Handle's matrix (integer)" 3904 ], 3905summary: "Returns the column number Index for Var in the external solver represented by Handle", 3906resat: "Yes (if Handle is a variable).", 3907desc: html(" 3908 <P> 3909 If Handle is a problem handle, then Index is the column number for the 3910 variable Var in the problem matrix of the external solver presented by 3911 Handle. If Handle is a variable, then the predicate returns the handles 3912 and index for each problem handle the variable non-determinately. 3913 </P> 3914")]). 3915 3916 3917:- comment(eplex_var_get_bounds/3, [ 3918 template: ["eplex_var_get_bounds(+Var, -Lo, -Hi)","EplexInstance:eplex_var_get_bounds(+Var, -Lo, -Hi)"], 3919args: [ 3920 "Var": "A problem variable for EplexInstance", 3921 "Lo": "Lower bound for Var", 3922 "Hi": "Upper bound for Var" 3923 ], 3924summary: "Returns the bounds stored in the solver state for Var in eplex instance EplexInstance.", 3925resat: no, 3926exceptions: [5: "EplexInstance does not a solver setup for it.", 3927 6: "Var is not a problem variable for EplexInstance.", 3928 40: "Solver state had been previously destroyed." 3929 ], 3930see_also: [lp_var_get_bounds/4,eplex_solver_setup/1, eplex_solver_setup/4], 3931desc: html(" 3932 <P> 3933 Returns the numeric bounds for Var stored in the solver state 3934 associated with the eplex instance EplexInstance. The bounds are 3935 returned as floats. Var must be an existing problem variable for 3936 EplexInstance. ") 3937]). 3938 3939:- comment(lp_var_get_bounds/4, [ 3940amode: lp_var_get_bounds(+,?,-,-), 3941args: ["Handle": "Handle to a solver state", 3942 "Var": "A solver problem variable for Handle", 3943 "Lo": "Lower bound for Var", 3944 "Hi": "Upper bound for Var" 3945 ], 3946summary: "Returns the bounds stored in the solver state of Handle for Var.", 3947resat: no, 3948see_also: [eplex_var_get_bounds/3, lp_var_set_bounds/4], 3949exceptions: [5: "Handle is not in the form of a solver handle.", 3950 6: "Var is not a problem variable for Handle.", 3951 40: "Handle not valid: solver state had been destroyed by cleanup" 3952 3953 ], 3954desc: html(" 3955 <P> 3956 Returns the numeric bounds stored in the solver state of Handle for the 3957 variable Var. The bounds are returned as floats. Var must be an 3958 existing problem variable for Handle, i.e. it must occur in the 3959 constraints posted to the solver state. ") 3960]). 3961 3962:- comment(lp_var_set_bounds/4, [ 3963amode: lp_var_set_bounds(+,?,+,+), 3964args: ["Handle": "Handle to a solver state", 3965 "Var": "A solver problem variable for Handle", 3966 "Lo": "New lower bound for Var (number)", 3967 "Hi": "New upper bound for Var (number)" 3968 ], 3969summary: "Imposes new bounds for Var on the solver state of Handle.", 3970resat: no, 3971see_also: [lp_var_get_bounds/4], 3972fail_if: "Lo is greater than Hi.", 3973exceptions: [5: "Handle is not in the form of a solver handle.", 3974 6: "Var is not a problem variable for Handle.", 3975 40: "Handle not valid: solver state had been destroyed by cleanup" 3976 ], 3977desc: html(" 3978 <P> 3979 Imposes numeric bounds on the solver state of Handle for the variable 3980 Var. Each bound is only updated if it is more narrow than the current 3981 bound for the variable. The bounds are converted to floats before they 3982 are imposed, and no typing is implied by the type of the numbers. It is 3983 possible to impose incompatible bounds for the same variable on 3984 different solver states. Var must be an existing problem variable for 3985 Handle, i.e. it must occur in the constraints posted to the solver 3986 state. ") 3987]). 3988 3989:- comment(eplex_get_iis/4, [ 3990 summary: "Returns an IIS for an infeasible problem associated with EplexInstance.", 3991 template: ["eplex_get_iis(-NumConstraints, -NumVars, -ConstraintIdxs, -VarInfos)", 3992 "EplexInstance:eplex_get_iis(-NumConstraints, -NumVars, -ConstraintIdxs, -VarInfos)"], 3993 exceptions: [141: "External solver does not support finding IIS", 3994 213: "Error in external solver while getting IIS" 3995 ], 3996 args: ["NumConstraints" : "Number of constraints in the IIS", 3997 "NumVars" : "Number of variables in the IIS", 3998 "ConstraintIdxs": "List of Indexes of the constraints in the IIS", 3999 "VarInfos": "List of Variable:Status pairs where Variables" 4000 " are the variables in the IIS and Status is the" 4001 " status of that variable" 4002 ], 4003 amode: eplex_get_iis(-,-,-,-), 4004 see_also: [lp_get_iis/5, eplex_solver_setup/4, eplex_solve/1, eplex_probe/2, 4005 eplex_get/2, eplex_set/2, 4006 lp_add_constraints/4, lp_add_cutpool_constraints/4], 4007 eg: " 4008 % simple inconsistency, get the constraints with constraints option of eplex_get/2 4009 [eclipse 6]: eplex:(X=:=Y), 4010 eplex:(X+Y>=3), 4011 eplex:(X+Y=<2), 4012 eplex_solver_setup(min(X)), 4013 eplex_set(cache_iis, yes), 4014 eplex_set(infeasible_handler, 4015 eplex_get_iis(NC,BV, Is, Vs), 4016 eplex_get(constraints(Is), Cs))), 4017 eplex_solve(C). 4018 CPLEX Error 1217: No solution exists. 4019 4020 X = X{-1e+20 .. 1e+20} 4021 Y = Y{-1e+20 .. 1e+20} 4022 NC = 2 4023 BV = 0 4024 Is = [0, 1] 4025 Vs = [] 4026 Cs = [X{-1e+20 .. 1e+20} + Y{-1e+20 .. 1e+20} =< 2.0, X + Y >= 3.0] 4027 C = C 4028 Yes (0.00s cpu) 4029 [eclipse 7]: 4030 4031 % simple example using cutpool constraints and cache_iis option 4032 [eclipse 7]: eplex:(X=:=Y), eplex_solver_setup(min(X)), 4033 eplex_set(cache_iis, yes), eplex_set(infeasible_handler, eplex_get_iis(NC,NV,Is,Vs)), 4034 eplex_get(handle, H), 4035 lp_add_cutpool_constraints(H, [(X+Y>=4),(2*X =:= 2*Y), (X+Y=<3)], [], Idxs), 4036 eplex_solve(C). 4037 4038 CPLEX Error 1217: No solution exists. 4039 4040 X = X{-1e+20 .. 1e+20} 4041 Y = Y{-1e+20 .. 1e+20} 4042 NC = 2 4043 NV = 0 4044 Is = [g(2, 0), g(2, 2)] 4045 Vs = [] 4046 H = lp_handle(0) 4047 Idxs = [g(2, 0), g(2, 1), g(2, 2)] 4048 C = C 4049 Yes (0.00s cpu) 4050 [eclipse 8]: 4051 ", 4052 desc: html("\ 4053 <P> 4054 If the solver found that the problem was infeasible, this predicate 4055 will return an IIS (Irreducible Infeasible Subsystem or Irreducible 4056 Inconsistent Subsystem) for the problem, if supported by the solver. 4057<P> 4058 This predicate must be called from within a user defined 4059 infeasible_handler, and with the cache_iis option set to yes (both 4060 can be set during solver set-up or using eplex_set/2). The reason for 4061 this is the IIS must be computed by the solver before the failed 4062 solver state changes, and backtracking pass the failure (the normal 4063 behaviour when a problem is infeasible) will logically remove the failed 4064 state. cache_iis is needed because the default setting for this 4065 option is no, as the IIS need to be computed as an extra step, so 4066 IIS is normally not computed. 4067<P> 4068 An IIS is a subset of the problem constraints and variables which 4069 defines an infeasible subproblem. It is usually irreducible in that 4070 any proper subset of the IIS is feasible. Finding an IIS allows the 4071 diagnostic analysis of the infeasible problem. Note that a problem 4072 may have more than one infeasibility, and thus more than one IIS, 4073 but this predicate only returns one. 4074 </P><P> 4075 NumConstraints and NumVars are the number of constraints and variables 4076 that are in the IIS. ConstraintIdxs is a list of the constraint indexes 4077 of the constraints in the IIS, these indexes are the indexes that are 4078 returned by lp_add_constraints/4 and lp_add_cutpool_constraints/4, and can 4079 also be used to retrieve the constraint with the constraints_norm(Indexes) 4080 and constraints(Indexes) options of eplex_get/2 and lp_get/3. VarInfos gives 4081 information for the variables in the IIS, and is a list of Var:Status 4082 pair, where Var is a variable in the IIS, and Status is its status. 4083 Status is a one character string, and can be: 4084<DL> 4085 <DT>\"b\": <DD>if both bounds of the variable are involved in the infeasibility 4086 <DT>\"u\": <DD>if the upper bound of the variable is involved in the infeasibility 4087 <DT>\"l\": <DD>if the lower bound of the variable is involved in the infeasibility 4088 <DT>\"x\": <DD>if it is unknown which bound is involved in the infeasibility 4089</DL><P> 4090 An IIS is returned only if finding IIS is supported by the external 4091 solver. In addition, the solver may limit the type of problems and the 4092 information returned by the IIS, for example, finding an IIS may be 4093 limited to linear problems, and/or bound status information may be 4094 unavailable for the variables (hence the need for the \"x\" status). 4095 Consult the solver's manual entry for infeasibility analyses for more detail. 4096</P><P> 4097 For some external solvers, and for problems on the boundary between 4098 feasible and infeasible, it is possible that the routine that finds 4099 the IIS will conclude that the problem is feasible, even though it was 4100 considered infeasible when the problem was solved. In such cases, an 4101 empty IIS will be returned. 4102") 4103]). 4104 4105:- comment(lp_get_iis/5, [ 4106 summary: "Returns an IIS for an infeasible problem.", 4107 args: ["Handle" : "Handle to a solver state", 4108 "NumConstraints" : "Number of constraints in the IIS", 4109 "NumVars" : "Number of variables in the IIS", 4110 "ConstraintIdxs": "List of Indexes of the constraints in the IIS", 4111 "VarInfos": "List of Variable:Status pairs where Variables" 4112 " are the variables in the IIS and Status is the" 4113 " status of that variable" 4114 ], 4115 amode: lp_get_iis(+,-,-,-,-), 4116 exceptions: [141: "External solver does not support finding IIS"], 4117 see_also: [eplex_get_iis/4, lp_setup/4, lp_demon_setup/5, lp_solve/2, lp_probe/3, 4118 lp_get/3, lp_set/3, lp_add_constraints/4, lp_add_cutpool_constraints/4], 4119 desc: html("\ 4120 <P> 4121 If the solver found that the problem was infeasible, this predicate 4122 will return an IIS (Irreducible Infeasible Subsystem or Irreducible 4123 Inconsistent Subsystem) for the problem, if supported by the solver. 4124 </P><P> 4125 This predicate must be called from within a user defined 4126 infeasible_handler, and with the cache_iis option set to yes (both 4127 can be set during solver set-up or using lp_set/2). The reason for 4128 this is the IIS must be computed by the solver before the failed 4129 solver state changes, and backtracking pass the failure (the normal 4130 behaviour when a problem is infeasible) will logically remove the failed 4131 state. cache_iis is needed because the default setting for this 4132 option is no, as the IIS need to be computed as an extra step, so 4133 IIS is normally not computed. 4134 </P><P> 4135 An IIS is a subset of the problem constraints and variables which 4136 defines an infeasible subproblem. It is usually irreducible in that 4137 any proper subset of the IIS is feasible. Finding an IIS allows the 4138 diagnostic analysis of the infeasible problem. Note that a problem 4139 may have more than one infeasibility, and thus more than one IIS, 4140 but this predicate only returns one. 4141 </P><P> 4142 NumConstraints and NumVars are the number of constraints and variables 4143 that are in the IIS. ConstraintIdxs is a list of the constraint indexes 4144 of the constraints in the IIS, these indexes are the indexes that are 4145 returned by lp_add_constraints/4 and lp_add_cutpool_constraints/4, and can 4146 also be used to retrieve the constraint with the constraints_norm(Indexes) 4147 and constraints(Indexes) options of eplex_get/2 and lp_get/3. VarInfos gives 4148 information for the variables in the IIS, and is a list of Var:Status 4149 pair, where Var is a variable in the IIS, and Status is its status. 4150 Status is a one character string, and can be: 4151<DL> 4152 <DT>\"b\": <DD>if both bounds of the variable are involved in the infeasibility 4153 <DT>\"u\": <DD>if the upper bound of the variable is involved in the infeasibility 4154 <DT>\"l\": <DD>if the lower bound of the variable is involved in the infeasibility 4155 <DT>\"x\": <DD>if it is unknown which bound is involved in the infeasibility 4156</DL><P> 4157 An IIS is returned only if finding IIS is supported by the external 4158 solver. In addition, the solver may limit the type of problems and the 4159 information returned by the IIS, for example, finding an IIS may be 4160 limited to linear problems, and/or bound status information may be 4161 unavailable for the variables (hence the need for the \"x\" status). 4162 Consult the manual entry for infeasibility analyses for more detail. 4163</P><P> 4164 For some external solvers, and for problems on the boundary between 4165 feasible and infeasible, it is possible that the routine that finds 4166 the IIS will conclude that the problem is feasible, even though it was 4167 considered infeasible when the problem was solved. In such cases, an 4168 empty IIS will be returned. 4169") 4170]). 4171 4172 4173:- comment(eplex_verify_solution/2, [ 4174 summary: "Verifies the current solution for the problem associated with EplexInstance.", 4175 template:["eplex_verify_solution(-ViolatedCstrs,-ViolatedVars)", 4176 "EplexInstance:eplex_verify_solution(-ViolatedCstrs,-ViolatedVars)"], 4177 args: ["ViolatedCstrs": "List of violated Constraints.", 4178 "ViolatedVars": "List of violated variables." 4179 ], 4180 amode: eplex_verify_solution(-,-), 4181 desc: html( 4182"<P> 4183 This predicate checks the current solution for the problem associated with 4184 EplexInstance. It verifies that all the constraints are satisfied by the 4185 solution values for the problem variables, and that the solution values do 4186 not violate their bounds, and the values are integral for integer variables. 4187 Violated Constraints are returned in ViolatedCstrs, and violated variables in 4188 ViolatedVars. 4189</P><P> 4190 Under normal circumstances, if the external solver produces a solution, it 4191 should produce no violations. Any violation probably indicates a problem 4192 with the external solver. However, because the external solver is a complex 4193 piece of software and may contain problems, it is a good idea to verify the 4194 solution, and this predicate provides an easy way to do this. 4195</P><P> 4196 Each violation is returned as a structure of the following form: 4197 <PRE> vio(type,delta,idx,item) </PRE> 4198 where 4199<DL> 4200 <DT>type: <DD>the type of violation: 4201 <DL> 4202 <DT>norm: <DD>the violated item is a normal constraint. 4203 <DT>condcp: <DD>the violated item is an active cutpool constraint. 4204 <DT>int: <DD>the violated item is an integer variable whose 4205 solution value is not integral. 4206 <DT>lower: <DD>the violated item is a variable whose solution value 4207 is less than the lower bound. 4208 <DT>upper: <DD>the violated item is a variable whose solution value 4209 is greater than the upper bound. 4210 </DL> 4211 <DT>delta: <DD>the absolute value of the violation. 4212 <DT>idx: <DD>the index used by the external solver for the item (most 4213 likely the row/column number in the problem matrix). This 4214 is needed to locate the violation in the solver for reporting 4215 or investigating the problem. 4216 <DT>item: <DD>the violated item, i.e. the constraint or variable. 4217</DL><P> 4218 For checking of constraints, a fresh copy of the constraint is made with 4219 the solution values, as this avoids binding the original variables. Any active 4220 cutpool constraints in the (logically) last solve of the problem are checked, 4221 along with the normal constraints. A constraint is considered to be violated 4222 if the difference between the sum of the left-hand side and the right-hand side 4223 for the constraint is greater than the feasibility tolerance (feasibility_tol) 4224 parameter for the instance. For variables, a bound is considered violated if 4225 the solution value falls outside the bound by more than feasibility tolerance, 4226 and integrality is considered to be violated if the fractional part of the 4227 soltuion is greater than the integrality parameter for the instance. 4228"), 4229 fail_if: "no solution values are available." 4230]). 4231 4232:- comment(lp_verify_solution/3, [ 4233 summary: "Verifies the current solution for the problem associated with Handle.", 4234 args: ["Handle": "Handle to a solver state", 4235 "ViolatedCstrs": "List of violated Constraints.", 4236 "ViolatedVars": "List of violated variables." 4237 ], 4238 amode: lp_verify_solution(+,-,-), 4239 desc: html( 4240"<P> 4241 This predicate checks the current solution for the problem associated with 4242 Handle. It verifies that all the constraints are satisfied by the 4243 solution values for the problem variables, and that the solution values do 4244 not violate their bounds, and the values are integral for integer variables. 4245 Violated Constraints are returned in ViolatedCstrs, and violated variables in 4246 ViolatedVars. 4247</P><P> 4248 Under normal circumstances, if the external solver produces a solution, it 4249 should produce no violations. Any violation probably indicates a problem 4250 with the external solver. However, because the external solver is a complex 4251 piece of software and may contain problems, it is a good idea to verify the 4252 solution, and this predicate provides an easy way to do this. 4253</P><P> 4254 Each violation is returned as a structure of the following form: 4255 <PRE> vio(type,delta,idx,item) </PRE> 4256 where 4257<DL> 4258 <DT>type: <DD>the type of violation: 4259 <DL> 4260 <DT>norm: <DD>the violated item is a normal constraint. 4261 <DT>condcp: <DD>the violated item is an active cutpool constraint. 4262 <DT>int: <DD>the violated item is an integer variable whose 4263 solution value is not integral. 4264 <DT>lower: <DD>the violated item is a variable whose solution value 4265 is less than the lower bound. 4266 <DT>upper: <DD>the violated item is a variable whose solution value 4267 is greater than the upper bound. 4268 </DL> 4269 <DT>delta: <DD>the absolute value of the violation. 4270 <DT>idx: <DD>the index used by the external solver for the item (most 4271 likely the row/column number in the problem matrix). This 4272 is needed to locate the violation in the solver for reporting 4273 or investigating the problem. 4274 <DT>item: <DD>the violated item, i.e. the constraint or variable. 4275</DL><P> 4276 For checking of constraints, a fresh copy of the constraint is made with 4277 the solution values, as this avoids binding the original variables. Any active 4278 cutpool constraints in the (logically) last solve of the problem are checked, 4279 along with the normal constraints. A constraint is considered to be violated 4280 if the difference between the sum of the left-hand side and the right-hand side 4281 for the constraint is greater than the feasibility tolerance (feasibility_tol) 4282 parameter for the instance. For variables, a bound is considered violated if 4283 the solution value falls outside the bound by more than feasibility tolerance, 4284 and integrality is considered to be violated if the fractional part of the 4285 soltuion is greater than the integrality parameter for the instance. 4286"), 4287 fail_if: "no solution values are available." 4288]). 4289 4290:- comment(piecewise_linear_hull/3, [ 4291template:["piecewise_linear_hull(?X, ++Points, ?Y)", 4292 "EplexInstance:piecewise_linear_hull(?X, ++Points, ?Y)"], 4293args:["X":"Parameter/domain of the piecewise function", 4294 "Points":"List of points defining the piecewise function", 4295 "Y":"Result/range of piecewise the function" 4296 ], 4297summary: "Relates X and Y according to a piecewise linear function.", 4298see_also: [_:piecewise_linear/3], 4299desc: html("\ 4300<P> 4301This predicate is intended for use with hybrid ic/eplex solving. It 4302imposes the constraint Y = f(X), where f is a piecewise 4303linear function defined by Points: the piecewise_linear/3 constraint for 4304 the ic solver, and a linear relaxation of it for the eplex instance 4305 EplexInstance. Please see the documentation for 4306piecewise_linear/3 for details of how the piecewise linear function is 4307specified. 4308</P><P> 4309This predicate extends lib(ic)'s piecewise_linear/3 by also computing the convex hull 4310of the portions of the constraint which are feasible with respect to the 4311current bounds (stored with the IC bounds) of X and Y. Constraints (and 4312 bounds) defining this convex hull are then 4313passed to the eplex instance. Changes in the IC bounds of the variables are 4314 automatically forwarded to the eplex instance, so that these constraints are updated whenever new 4315bounds on X or Y change the convex hull. Note that the reverse, i.e. bounds 4316 changes on the eplex instance, are NOT forwarded to the IC bounds. 4317</P><P> 4318This implementation of the piecewise 4319constraint accepts bounded reals in its arguments, but it 4320does not fully support bounded reals of non-zero width (i.e. 4321those which do not correspond to a single floating point value). As a 4322result, use of such bounded reals is not recommended at this time.</P> 4323") 4324]). 4325 4326:- comment(lp_add_indexed/4, hidden). 4327:- comment(eplex_solver_setup/5, hidden). 4328 4329 4330