1PySCIPOpt 2========= 3 4This project provides an interface from Python to the [SCIP Optimization 5Suite](http://scip.zib.de). 6 7[](https://gitter.im/PySCIPOpt/Lobby) 8[](https://pypi.python.org/pypi/pyscipopt) 9[](https://travis-ci.org/SCIP-Interfaces/PySCIPOpt) 10[](https://ci.appveyor.com/project/mattmilten/pyscipopt/branch/master) 11 12 13Documentation 14------------- 15 16Please consult the [online documentation](http://scip-interfaces.github.io/PySCIPOpt/docs/html) or use the `help()` function directly in Python or `?` in IPython/Jupyter. 17 18See [CHANGELOG.md](CHANGELOG.md) for added, removed or fixed functionality. 19 20Installation 21------------ 22 23See [INSTALL.md](INSTALL.md) for instructions. 24Please note that the latest PySCIPOpt version is usually only compatible with the latest major release of the SCIP Optimization Suite. 25Information which version of PySCIPOpt is required for a given SCIP version can also be found in [INSTALL.md](INSTALL.md). 26 27Building and solving a model 28---------------------------- 29 30There are several [examples](examples/finished) and 31[tutorials](examples/tutorial). These display some functionality of the 32interface and can serve as an entry point for writing more complex code. 33You might also want to have a look at this article about PySCIPOpt: 34<https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045>. The 35following steps are always required when using the interface: 36 371) It is necessary to import python-scip in your code. This is achieved 38 by including the line 39 40``` {.sourceCode .python} 41from pyscipopt import Model 42``` 43 442) Create a solver instance. 45 46``` {.sourceCode .python} 47model = Model("Example") # model name is optional 48``` 49 503) Access the methods in the `scip.pyx` file using the solver/model 51 instance `model`, e.g.: 52 53``` {.sourceCode .python} 54x = model.addVar("x") 55y = model.addVar("y", vtype="INTEGER") 56model.setObjective(x + y) 57model.addCons(2*x - y*y >= 0) 58model.optimize() 59sol = model.getBestSol() 60print("x: {}".format(sol[x])) 61print("y: {}".format(sol[y])) 62``` 63 64Writing new plugins 65------------------- 66 67The Python interface can be used to define custom plugins to extend the 68functionality of SCIP. You may write a pricer, heuristic or even 69constraint handler using pure Python code and SCIP can call their 70methods using the callback system. Every available plugin has a base 71class that you need to extend, overwriting the predefined but empty 72callbacks. Please see `test_pricer.py` and `test_heur.py` for two simple 73examples. 74 75Please notice that in most cases one needs to use a `dictionary` to 76specify the return values needed by SCIP. 77 78Extending the interface 79----------------------- 80 81PySCIPOpt already covers many of the SCIP callable library methods. You 82may also extend it to increase the functionality of this interface. The 83following will provide some directions on how this can be achieved: 84 85The two most important files in PySCIPOpt are the `scip.pxd` and 86`scip.pyx`. These two files specify the public functions of SCIP that 87can be accessed from your python code. 88 89To make PySCIPOpt aware of the public functions you would like to 90access, you must add them to `scip.pxd`. There are two things that must 91be done in order to properly add the functions: 92 931) Ensure any `enum`s, `struct`s or SCIP variable types are included in 94 `scip.pxd` <br> 952) Add the prototype of the public function you wish to access to 96 `scip.pxd` 97 98After following the previous two steps, it is then possible to create 99functions in python that reference the SCIP public functions included in 100`scip.pxd`. This is achieved by modifying the `scip.pyx` file to add the 101functionality you require. 102 103We are always happy to accept pull request containing patches or 104extensions! 105 106Please have a look at our [contribution guidelines](CONTRIBUTING.md). 107 108Gotchas 109------- 110 111### Ranged constraints 112 113While ranged constraints of the form 114 115``` {.sourceCode .} 116lhs <= expression <= rhs 117``` 118 119are supported, the Python syntax for [chained 120comparisons](https://docs.python.org/3.5/reference/expressions.html#comparisons) 121can't be hijacked with operator overloading. Instead, parenthesis must 122be used, e.g., 123 124``` {.sourceCode .} 125lhs <= (expression <= rhs) 126``` 127 128Alternatively, you may call `model.chgRhs(cons, newrhs)` or 129`model.chgLhs(cons, newlhs)` after the single-sided constraint has been 130created. 131 132### Variable objects 133 134You can't use `Variable` objects as elements of `set`s or as keys of 135`dict`s. They are not hashable and comparable. The issue is that 136comparisons such as `x == y` will be interpreted as linear constraints, 137since `Variable`s are also `Expr` objects. 138 139### Dual values 140 141While PySCIPOpt supports access to the dual values of a solution, there 142are some limitations involved: 143 144- Can only be used when presolving and propagation is disabled to 145 ensure that the LP solver - which is providing the dual 146 information - actually solves the unmodified problem. 147- Heuristics should also be disabled to avoid that the problem is 148 solved before the LP solver is called. 149- There should be no bound constraints, i.e., constraints with only 150 one variable. This can cause incorrect values as explained in 151 [\#136](https://github.com/SCIP-Interfaces/PySCIPOpt/issues/136) 152 153Therefore, you should use the following settings when trying to work 154with dual information: 155 156``` {.sourceCode .python} 157model.setPresolve(pyscipopt.SCIP_PARAMSETTING.OFF) 158model.setHeuristics(pyscipopt.SCIP_PARAMSETTING.OFF) 159model.disablePropagation() 160``` 161 162Citing PySCIPOpt 163---------------- 164 165Please cite [this paper](https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045) 166``` 167@incollection{MaherMiltenbergerPedrosoRehfeldtSchwarzSerrano2016, 168 author = {Stephen Maher and Matthias Miltenberger and Jo{\~{a}}o Pedro Pedroso and Daniel Rehfeldt and Robert Schwarz and Felipe Serrano}, 169 title = {{PySCIPOpt}: Mathematical Programming in Python with the {SCIP} Optimization Suite}, 170 booktitle = {Mathematical Software {\textendash} {ICMS} 2016} 171 publisher = {Springer International Publishing}, 172 pages = {301--307}, 173 year = {2016}, 174 doi = {10.1007/978-3-319-42432-3_37}, 175} 176``` 177as well as the corresponding [SCIP Optimization Suite report](https://scip.zib.de/index.php#cite) when you use this tool for a publication or other scientific work. 178
){kind=link}
){kind=link}
){kind=link}