PySCIPOpt
=========
This project provides an interface from Python to the [SCIP Optimization
Suite](https://www.scipopt.org/). Please review [SCIP's license restrictions](https://scipopt.org/index.php#license) before installing PySCIPOpt.
[](https://gitter.im/PySCIPOpt/Lobby)
[](https://pypi.python.org/pypi/pyscipopt)
[](https://github.com/scipopt/PySCIPOpt/actions/workflows/integration-test.yml)
[](https://ci.appveyor.com/project/mattmilten/pyscipopt/branch/master)
Documentation
-------------
Please consult the [online documentation](https://scipopt.github.io/PySCIPOpt/docs/html) or use the `help()` function directly in Python or `?` in IPython/Jupyter.
See [CHANGELOG.md](CHANGELOG.md) for added, removed or fixed functionality.
Installation
------------
**Using Conda**
[](https://anaconda.org/conda-forge/pyscipopt)
[](https://anaconda.org/conda-forge/pyscipopt)
***DO NOT USE THE CONDA BASE ENVIRONMENT TO INSTALL PYSCIPOPT.***
Conda will install SCIP automatically, hence everything can be installed in a single command:
```bash
conda install --channel conda-forge pyscipopt
```
**Using PyPI and from Source**
See [INSTALL.md](INSTALL.md) for instructions.
Please note that the latest PySCIPOpt version is usually only compatible with the latest major release of the SCIP Optimization Suite.
The following table summarizes which version of PySCIPOpt is required for a given SCIP version:
|SCIP| PySCIPOpt |
|----|----|
8.0 | 4.x
7.0 | 3.x
6.0 | 2.x
5.0 | 1.4, 1.3
4.0 | 1.2, 1.1
3.2 | 1.0
Information which version of PySCIPOpt is required for a given SCIP version can also be found in [INSTALL.md](INSTALL.md).
Building and solving a model
----------------------------
There are several [examples](examples/finished) and
[tutorials](examples/tutorial). These display some functionality of the
interface and can serve as an entry point for writing more complex code.
You might also want to have a look at this article about PySCIPOpt:
<https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045>. The
following steps are always required when using the interface:
1) It is necessary to import python-scip in your code. This is achieved
by including the line
``` {.sourceCode .python}
from pyscipopt import Model
```
2) Create a solver instance.
``` {.sourceCode .python}
model = Model("Example") # model name is optional
```
3) Access the methods in the `scip.pyx` file using the solver/model
instance `model`, e.g.:
``` {.sourceCode .python}
x = model.addVar("x")
y = model.addVar("y", vtype="INTEGER")
model.setObjective(x + y)
model.addCons(2*x - y*y >= 0)
model.optimize()
sol = model.getBestSol()
print("x: {}".format(sol[x]))
print("y: {}".format(sol[y]))
```
Writing new plugins
-------------------
The Python interface can be used to define custom plugins to extend the
functionality of SCIP. You may write a pricer, heuristic or even
constraint handler using pure Python code and SCIP can call their
methods using the callback system. Every available plugin has a base
class that you need to extend, overwriting the predefined but empty
callbacks. Please see `test_pricer.py` and `test_heur.py` for two simple
examples.
Please notice that in most cases one needs to use a `dictionary` to
specify the return values needed by SCIP.
Extending the interface
-----------------------
PySCIPOpt already covers many of the SCIP callable library methods. You
may also extend it to increase the functionality of this interface. The
following will provide some directions on how this can be achieved:
The two most important files in PySCIPOpt are the `scip.pxd` and
`scip.pyx`. These two files specify the public functions of SCIP that
can be accessed from your python code.
To make PySCIPOpt aware of the public functions you would like to
access, you must add them to `scip.pxd`. There are two things that must
be done in order to properly add the functions:
1) Ensure any `enum`s, `struct`s or SCIP variable types are included in
`scip.pxd` <br>
2) Add the prototype of the public function you wish to access to
`scip.pxd`
After following the previous two steps, it is then possible to create
functions in python that reference the SCIP public functions included in
`scip.pxd`. This is achieved by modifying the `scip.pyx` file to add the
functionality you require.
We are always happy to accept pull request containing patches or
extensions!
Please have a look at our [contribution guidelines](CONTRIBUTING.md).
Gotchas
-------
### Ranged constraints
While ranged constraints of the form
``` {.sourceCode .}
lhs <= expression <= rhs
```
are supported, the Python syntax for [chained
comparisons](https://docs.python.org/3.5/reference/expressions.html#comparisons)
can't be hijacked with operator overloading. Instead, parenthesis must
be used, e.g.,
``` {.sourceCode .}
lhs <= (expression <= rhs)
```
Alternatively, you may call `model.chgRhs(cons, newrhs)` or
`model.chgLhs(cons, newlhs)` after the single-sided constraint has been
created.
### Variable objects
You can't use `Variable` objects as elements of `set`s or as keys of
`dict`s. They are not hashable and comparable. The issue is that
comparisons such as `x == y` will be interpreted as linear constraints,
since `Variable`s are also `Expr` objects.
### Dual values
While PySCIPOpt supports access to the dual values of a solution, there
are some limitations involved:
- Can only be used when presolving and propagation is disabled to
ensure that the LP solver - which is providing the dual
information - actually solves the unmodified problem.
- Heuristics should also be disabled to avoid that the problem is
solved before the LP solver is called.
- There should be no bound constraints, i.e., constraints with only
one variable. This can cause incorrect values as explained in
[\#136](https://github.com/scipopt/PySCIPOpt/issues/136)
Therefore, you should use the following settings when trying to work
with dual information:
``` {.sourceCode .python}
model.setPresolve(pyscipopt.SCIP_PARAMSETTING.OFF)
model.setHeuristics(pyscipopt.SCIP_PARAMSETTING.OFF)
model.disablePropagation()
```
Citing PySCIPOpt
----------------
Please cite [this paper](https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045)
```
@incollection{MaherMiltenbergerPedrosoRehfeldtSchwarzSerrano2016,
author = {Stephen Maher and Matthias Miltenberger and Jo{\~{a}}o Pedro Pedroso and Daniel Rehfeldt and Robert Schwarz and Felipe Serrano},
title = {{PySCIPOpt}: Mathematical Programming in Python with the {SCIP} Optimization Suite},
booktitle = {Mathematical Software {\textendash} {ICMS} 2016},
publisher = {Springer International Publishing},
pages = {301--307},
year = {2016},
doi = {10.1007/978-3-319-42432-3_37},
}
```
as 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/SCIP-Interfaces/PySCIPOpt",
"name": "PySCIPOpt",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Zuse Institute Berlin",
"author_email": "scip@zib.de",
"download_url": "https://files.pythonhosted.org/packages/46/7f/2fc04ddc3fce3489ac54d5163db49a96a1286d42951a18098335a708339d/PySCIPOpt-4.3.0.tar.gz",
"platform": null,
"description": "PySCIPOpt\n=========\n\nThis project provides an interface from Python to the [SCIP Optimization\nSuite](https://www.scipopt.org/). Please review [SCIP's license restrictions](https://scipopt.org/index.php#license) before installing PySCIPOpt.\n\n[](https://gitter.im/PySCIPOpt/Lobby)\n[](https://pypi.python.org/pypi/pyscipopt)\n[](https://github.com/scipopt/PySCIPOpt/actions/workflows/integration-test.yml)\n[](https://ci.appveyor.com/project/mattmilten/pyscipopt/branch/master)\n\n\nDocumentation\n-------------\n\nPlease consult the [online documentation](https://scipopt.github.io/PySCIPOpt/docs/html) or use the `help()` function directly in Python or `?` in IPython/Jupyter.\n\nSee [CHANGELOG.md](CHANGELOG.md) for added, removed or fixed functionality.\n\nInstallation\n------------\n\n**Using Conda**\n\n[](https://anaconda.org/conda-forge/pyscipopt)\n[](https://anaconda.org/conda-forge/pyscipopt)\n\n***DO NOT USE THE CONDA BASE ENVIRONMENT TO INSTALL PYSCIPOPT.***\n\nConda will install SCIP automatically, hence everything can be installed in a single command:\n```bash\nconda install --channel conda-forge pyscipopt\n```\n\n**Using PyPI and from Source**\n\nSee [INSTALL.md](INSTALL.md) for instructions.\nPlease note that the latest PySCIPOpt version is usually only compatible with the latest major release of the SCIP Optimization Suite.\nThe following table summarizes which version of PySCIPOpt is required for a given SCIP version:\n\n|SCIP| PySCIPOpt |\n|----|----|\n8.0 | 4.x\n7.0 | 3.x\n6.0 | 2.x\n5.0 | 1.4, 1.3\n4.0 | 1.2, 1.1\n3.2 | 1.0\n\nInformation which version of PySCIPOpt is required for a given SCIP version can also be found in [INSTALL.md](INSTALL.md).\n\nBuilding and solving a model\n----------------------------\n\nThere are several [examples](examples/finished) and\n[tutorials](examples/tutorial). These display some functionality of the\ninterface and can serve as an entry point for writing more complex code.\nYou might also want to have a look at this article about PySCIPOpt:\n<https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045>. The\nfollowing steps are always required when using the interface:\n\n1) It is necessary to import python-scip in your code. This is achieved\n by including the line\n\n``` {.sourceCode .python}\nfrom pyscipopt import Model\n```\n\n2) Create a solver instance.\n\n``` {.sourceCode .python}\nmodel = Model(\"Example\") # model name is optional\n```\n\n3) Access the methods in the `scip.pyx` file using the solver/model\n instance `model`, e.g.:\n\n``` {.sourceCode .python}\nx = model.addVar(\"x\")\ny = model.addVar(\"y\", vtype=\"INTEGER\")\nmodel.setObjective(x + y)\nmodel.addCons(2*x - y*y >= 0)\nmodel.optimize()\nsol = model.getBestSol()\nprint(\"x: {}\".format(sol[x]))\nprint(\"y: {}\".format(sol[y]))\n```\n\nWriting new plugins\n-------------------\n\nThe Python interface can be used to define custom plugins to extend the\nfunctionality of SCIP. You may write a pricer, heuristic or even\nconstraint handler using pure Python code and SCIP can call their\nmethods using the callback system. Every available plugin has a base\nclass that you need to extend, overwriting the predefined but empty\ncallbacks. Please see `test_pricer.py` and `test_heur.py` for two simple\nexamples.\n\nPlease notice that in most cases one needs to use a `dictionary` to\nspecify the return values needed by SCIP.\n\nExtending the interface\n-----------------------\n\nPySCIPOpt already covers many of the SCIP callable library methods. You\nmay also extend it to increase the functionality of this interface. The\nfollowing will provide some directions on how this can be achieved:\n\nThe two most important files in PySCIPOpt are the `scip.pxd` and\n`scip.pyx`. These two files specify the public functions of SCIP that\ncan be accessed from your python code.\n\nTo make PySCIPOpt aware of the public functions you would like to\naccess, you must add them to `scip.pxd`. There are two things that must\nbe done in order to properly add the functions:\n\n1) Ensure any `enum`s, `struct`s or SCIP variable types are included in\n `scip.pxd` <br>\n2) Add the prototype of the public function you wish to access to\n `scip.pxd`\n\nAfter following the previous two steps, it is then possible to create\nfunctions in python that reference the SCIP public functions included in\n`scip.pxd`. This is achieved by modifying the `scip.pyx` file to add the\nfunctionality you require.\n\nWe are always happy to accept pull request containing patches or\nextensions!\n\nPlease have a look at our [contribution guidelines](CONTRIBUTING.md).\n\nGotchas\n-------\n\n### Ranged constraints\n\nWhile ranged constraints of the form\n\n``` {.sourceCode .}\nlhs <= expression <= rhs\n```\n\nare supported, the Python syntax for [chained\ncomparisons](https://docs.python.org/3.5/reference/expressions.html#comparisons)\ncan't be hijacked with operator overloading. Instead, parenthesis must\nbe used, e.g.,\n\n``` {.sourceCode .}\nlhs <= (expression <= rhs)\n```\n\nAlternatively, you may call `model.chgRhs(cons, newrhs)` or\n`model.chgLhs(cons, newlhs)` after the single-sided constraint has been\ncreated.\n\n### Variable objects\n\nYou can't use `Variable` objects as elements of `set`s or as keys of\n`dict`s. They are not hashable and comparable. The issue is that\ncomparisons such as `x == y` will be interpreted as linear constraints,\nsince `Variable`s are also `Expr` objects.\n\n### Dual values\n\nWhile PySCIPOpt supports access to the dual values of a solution, there\nare some limitations involved:\n\n- Can only be used when presolving and propagation is disabled to\n ensure that the LP solver - which is providing the dual\n information - actually solves the unmodified problem.\n- Heuristics should also be disabled to avoid that the problem is\n solved before the LP solver is called.\n- There should be no bound constraints, i.e., constraints with only\n one variable. This can cause incorrect values as explained in\n [\\#136](https://github.com/scipopt/PySCIPOpt/issues/136)\n\nTherefore, you should use the following settings when trying to work\nwith dual information:\n\n``` {.sourceCode .python}\nmodel.setPresolve(pyscipopt.SCIP_PARAMSETTING.OFF)\nmodel.setHeuristics(pyscipopt.SCIP_PARAMSETTING.OFF)\nmodel.disablePropagation()\n```\n\nCiting PySCIPOpt\n----------------\n\nPlease cite [this paper](https://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/6045)\n```\n@incollection{MaherMiltenbergerPedrosoRehfeldtSchwarzSerrano2016,\n author = {Stephen Maher and Matthias Miltenberger and Jo{\\~{a}}o Pedro Pedroso and Daniel Rehfeldt and Robert Schwarz and Felipe Serrano},\n title = {{PySCIPOpt}: Mathematical Programming in Python with the {SCIP} Optimization Suite},\n booktitle = {Mathematical Software {\\textendash} {ICMS} 2016},\n publisher = {Springer International Publishing},\n pages = {301--307},\n year = {2016},\n doi = {10.1007/978-3-319-42432-3_37},\n}\n```\nas 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.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python interface and modeling environment for SCIP",
"version": "4.3.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "467f2fc04ddc3fce3489ac54d5163db49a96a1286d42951a18098335a708339d",
"md5": "7a1d5e8188803c68e53bce5672c6df72",
"sha256": "d91e0080dc9bb77e4c685c724d8d0e154528322cb2a5a0879ff28dac456802ef"
},
"downloads": -1,
"filename": "PySCIPOpt-4.3.0.tar.gz",
"has_sig": false,
"md5_digest": "7a1d5e8188803c68e53bce5672c6df72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 665730,
"upload_time": "2023-03-17T19:54:33",
"upload_time_iso_8601": "2023-03-17T19:54:33.219217Z",
"url": "https://files.pythonhosted.org/packages/46/7f/2fc04ddc3fce3489ac54d5163db49a96a1286d42951a18098335a708339d/PySCIPOpt-4.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-17 19:54:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "SCIP-Interfaces",
"github_project": "PySCIPOpt",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"landscape": true,
"lcname": "pyscipopt"
}
JSON
