diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f996ce613..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,78 +0,0 @@ -Contributing to PySCIPOpt -========================= - -Code contributions are very welcome and should comply to a few rules: - -1. Read [Design principles of PySCIPOpt](#design-principles-of-pyscipopt). -2. New features should be covered by tests *and* examples. Please - extend [tests](tests) and [examples](examples). Tests uses pytest - and examples are meant to be accessible for PySCIPOpt newcomers - (even advanced examples). -3. New code should be documented in the same style as the rest of - the code. -4. New features or bugfixes have to be documented in the CHANGELOG. -5. New code should be - [pep8-compliant](https://www.python.org/dev/peps/pep-0008/). Help - yourself with the [style guide - checker](https://pypi.org/project/pep8/). -6. Before implementing a new PySCIPOpt feature, check whether the - feature exists in SCIP. If so, implement it as a pure wrapper, - mimicking SCIP whenever possible. If the new feature does not exist - in SCIP but it is close to an existing one, consider if implementing - that way is substantially convenient (e.g. Pythonic). If it does - something completely different, you are welcome to pull your request - and discuss the implementation. -7. PySCIPOpt uses [semantic versioning](https://semver.org/). Version - number increase only happens on master and must be tagged to build a - new PyPI release. - -For general reference, we suggest: - -- [PySCIPOpt README](README.md); -- [SCIP documentation](http://scip.zib.de/doc/html/); -- [SCIP mailing list](https://listserv.zib.de/mailman/listinfo/scip/) - which can be easily searched with search engines (e.g. - [Google](http://www.google.com/#q=site:listserv.zib.de%2Fpipermail%2Fscip)); -- [open and closed PySCIPOpt - issues](https://github.com/SCIP-Interfaces/PySCIPOpt/issues?utf8=%E2%9C%93&q=is%3Aissue); -- [SCIP/PySCIPOpt Stack - Exchange](https://stackoverflow.com/questions/tagged/scip). - -If you find this contributing guide unclear, please open an issue! :) - -How to craft a release ----------------------- - -Moved to [RELEASE.md](RELEASE.md). - -Design principles of PySCIPOpt -============================== - -PySCIPOpt is meant to be a fast-prototyping interface of the pure SCIP C -API. By design, we distinguish different functions in PySCIPOPT: - -- pure wrapping functions of SCIP; -- convenience functions. - -**PySCIPOpt wrappers of SCIP functions** should act: - -- with an expected behavior - and parameters, returns, attributes, ... - - as close to SCIP as possible -- without *"breaking"* Python and the purpose for what the language it - is meant. - -Ideally speaking, we want every SCIP function to be wrapped in -PySCIPOpt. - -**Convenience functions** are additional, non-detrimental features meant -to help prototyping the Python way. Since these functions are not in -SCIP, we wish to limit them to prevent difference in features between -SCIP and PySCIPOPT, which are always difficult to maintain. A few -convenience functions survive in PySCIPOpt when keeping them is -doubtless beneficial. - -Admittedly, *there is a middle ground where functions are not completely -wrappers or just convenient*. That is the case, for instance, of -fundamental `Model`{.sourceCode} methods like `addCons`{.sourceCode} or -`writeProblem`{.sourceCode}. We want to leave their development to -negotiation. diff --git a/README.md b/README.md index 55985f631..b612c064d 100644 --- a/README.md +++ b/README.md @@ -13,54 +13,23 @@ This project provides an interface from Python to the [SCIP Optimization Suite]( 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. +Please consult the [online documentation](https://pyscipopt.readthedocs.io/en/latest/) or use the `help()` function directly in Python or `?` in IPython/Jupyter. -See [CHANGELOG.md](https://github.com/scipopt/PySCIPOpt/blob/master/CHANGELOG.md) for added, removed or fixed functionality. +The old documentation, which we are in the process of migrating from, +is still more complete w.r.t. the API, and can be found [here](https://scipopt.github.io/PySCIPOpt/docs/html/index.html) -You can also build the documentation locally with the command -```shell -pip install -r docs/requirements.txt -sphinx-build docs docs/_build -``` -Às the documentation requires additional python packages, one should run the following command -before building the documentation for the first time: -```shell -(venv) pip install -r docs/requirements.txt -``` +See [CHANGELOG.md](https://github.com/scipopt/PySCIPOpt/blob/master/CHANGELOG.md) for added, removed or fixed functionality. Installation ------------ -**Using Conda** - -[![Conda version](https://img.shields.io/conda/vn/conda-forge/pyscipopt?logo=conda-forge)](https://anaconda.org/conda-forge/pyscipopt) -[![Conda platforms](https://img.shields.io/conda/pn/conda-forge/pyscipopt?logo=conda-forge)](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: +The recommended installation method is via PyPI ```bash -conda install --channel conda-forge pyscipopt +pip install pyscipopt ``` -**Using PyPI and from Source** - -See [INSTALL.md](https://github.com/scipopt/PySCIPOpt/blob/master/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 | -|----|----| -9.1 | 5.1+ -9.0 | 5.0.x -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](https://github.com/scipopt/PySCIPOpt/blob/master/INSTALL.md). +For information on specific versions, installation via Conda, and guides for building from source, +please see the online documentation. Building and solving a model ---------------------------- @@ -113,90 +82,6 @@ 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.pxi`. 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`
-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.pxi` 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](https://github.com/scipopt/PySCIPOpt/blob/master/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 ---------------- diff --git a/docs/build.rst b/docs/build.rst index 9a18b51e1..b18fe0bda 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -184,3 +184,12 @@ Ideally, the status of your tests must be passed or skipped. Running tests with pytest creates the __pycache__ directory in tests and, occasionally, a model file in the working directory. They can be removed harmlessly. +Building Documentation Locally +=============================== + +You can build the documentation locally with the command: + +.. code-block:: bash + + pip install -r docs/requirements.txt + sphinx-build docs docs/_build diff --git a/docs/extend.rst b/docs/extend.rst new file mode 100644 index 000000000..396afbcbd --- /dev/null +++ b/docs/extend.rst @@ -0,0 +1,89 @@ +######################## +Extending the Interface +######################## + +PySCIPOpt covers many of the SCIP callable library methods, however it is not complete. +One can extend the interface to encompass even more functionality that is possible with +SCIP. The following will provide some directions on how this can be achieved. + +.. contents:: Contents + +General File Structure +====================== + +The two most important files in PySCIPOpt are the ``scip.pxd`` and +``scip.pxi``. 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 that one can access, +one must add them to ``scip.pxd``. There are two things that must +be done in order to properly add the functions: + +- Ensure any ``enum``, ``struct`` or SCIP variable types are included in ``scip.pxd`` +- 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.pxi` file to add the +functionality you require. + +Contribution Guidelines +======================= + +Code contributions are very welcome and should comply to a few rules: + +- Read Design Principles of PySCIPOpt in the section below +- New features should be covered by tests and examples. Please extend + the tests and example appropriately. Tests uses pytest + and examples are meant to be accessible for PySCIPOpt newcomers + (even advanced examples). +- New code should be documented in the same style as the rest of the code. +- New features or bugfixes have to be documented in the CHANGELOG. +- New code should be `pep8-compliant `_. Help + yourself with the `style guide checker `_. +- Before implementing a new PySCIPOpt feature, check whether the + feature exists in SCIP. If so, implement it as a pure wrapper, + mimicking SCIP whenever possible. If the new feature does not exist + in SCIP but it is close to an existing one, consider if implementing + that way is substantially convenient (e.g. Pythonic). If it does + something completely different, you are welcome to pull your request + and discuss the implementation. +- PySCIPOpt uses `semantic versioning `_. Version + number increase only happens on master and must be tagged to build a new PyPI release. + +For general reference, we suggest: + +- `SCIP documentation `_ +- `SCIP mailing list `_ +- `open and closed PySCIPOpt issues `_ +- `SCIP/PySCIPOpt Stack Exchange `_ + +If you find this contributing guide unclear, please open an issue! :) + +Design Principles of PySCIPOpt +============================== + +PySCIPOpt is meant to be a fast-prototyping interface of the pure SCIP C +API. By design, we distinguish different functions in PySCIPOPT: + +- pure wrapping functions of SCIP; +- convenience functions. + +**PySCIPOpt wrappers of SCIP functions** should act: + +- with an expected behavior - and parameters, returns, attributes, ... - as close to SCIP as possible +- without **"breaking"** Python and the purpose for what the language it is meant. + +Ideally speaking, we want every SCIP function to be wrapped in PySCIPOpt. + +**Convenience functions** are additional, non-detrimental features meant +to help prototyping the Python way. Since these functions are not in +SCIP, we wish to limit them to prevent difference in features between +SCIP and PySCIPOPT, which are always difficult to maintain. A few +convenience functions survive in PySCIPOpt when keeping them is +doubtless beneficial. + +Admittedly, there is a middle ground where functions are not completely +wrappers or just convenient. That is the case, for instance, of +fundamental ``Model`` methods like ``addCons`` or +``writeProblem``. We want to leave their development to negotiation. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index a69063218..1a62ca3ef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,7 @@ Contents build tutorials/index whyscip + extend similarsoftware faq api diff --git a/docs/install.rst b/docs/install.rst index d9cc7613b..b66ee7c26 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -2,6 +2,8 @@ Installation Guide ################## +**This file is deprecated and will be removed soon. Please see the online documentation.** + This page will detail all methods for installing PySCIPOpt via package managers, which come with their own versions of SCIP. For building PySCIPOpt against your own custom version of SCIP, or for building PySCIPOpt from source, visit :doc:`this page `.