Merge branch 'master' of https://github.com/scipopt/PySCIPOpt into AND-constraints

Author: Joao-Dionisio

CHANGELOG.md

@@ -2,9 +2,12 @@
 
 ## Unreleased
 ### Added
-- Added support for knapsack constraints
 - More support for AND-Constraints
+- Added support for knapsack constraints
+- Added isPositive(), isNegative(), isFeasLE(), isFeasLT(), isFeasGE(), isFeasGT(), isHugeValue(), and tests
+- Added SCIP_LOCKTYPE, addVarLocksType(), getNLocksDown(), getNLocksUp(), getNLocksDownType(), getNLocksUpType(), and tests
 ### Fixed
+- Raised an error when an expression is used when a variable is required
 ### Changed
 ### Removed
 

INSTALL.md

@@ -56,6 +56,15 @@ Installation from PyPI
 
     python -m pip install pyscipopt
 
+To avoid interfering with system packages, it's best to use a [virtual environment](https://docs.python.org/3/library/venv.html).<br>
+<span style="color:orange">**Warning!**</span> This is mandatory in some newer configurations.
+
+```bash
+python3 -m venv venv source venv/bin/activate  # On Windows use: venv\Scripts\activate pip install pyscipopt
+pip install pyscipopt
+```
+Remember to activate the environment (`source venv/bin/activate`) in each terminal session where you use PySCIPOpt.
+
 Please note that if your Python version and OS version are in the combinations at the start of this INSTALL file then
 pip now automatically installs a pre-built version of SCIP. For these combinations, to use your own installation of SCIP,
 please see the section on building from source. For unavailable combinations this pip command will automatically

README.md

@@ -23,10 +23,21 @@ See [CHANGELOG.md](https://github.com/scipopt/PySCIPOpt/blob/master/CHANGELOG.md
 Installation
 ------------
 
-The recommended installation method is via PyPI
+The recommended installation method is via [PyPI](https://pypi.org/project/PySCIPOpt/):
+
+```bash
+pip install pyscipopt
+```
+
+To avoid interfering with system packages, it's best to use a [virtual environment](https://docs.python.org/3/library/venv.html):
+
 ```bash
+python3 -m venv venv     # creates a virtual environment called venv
+source venv/bin/activate # activates the environment. On Windows use: venv\Scripts\activate
 pip install pyscipopt
 ```
+Remember to activate the environment (`source venv/bin/activate` or equivalent) in each terminal session where you use PySCIPOpt.
+Note that some configurations require the use of virtual environments.
 
 For information on specific versions, installation via Conda, and guides for building from source,
 please see the [online documentation](https://pyscipopt.readthedocs.io/en/latest/install.html).

docs/extend.rst

@@ -44,7 +44,7 @@ Code contributions are very welcome and should comply to a few rules:
 - 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
+  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.
@@ -77,7 +77,7 @@ API. By design, we distinguish different functions in PySCIPOPT:
 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
+to help prototype 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

docs/faq.rst

@@ -60,6 +60,6 @@ is not automatically deleted, and thus stops a new optimization call.
 Why can I not add a non-linear objective?
 =========================================
 
-SCIP does not support non-linear objectives, however, an equivalent optimization
+SCIP does not support non-linear objectives. However, an equivalent optimization
 problem can easily be constructed by introducing a single new variable and a constraint.
 Please see :doc:`this page <tutorials/expressions>` for a guide.

docs/install.rst

@@ -21,6 +21,20 @@ To install PySCIPOpt simply run the command:
 
   pip install pyscipopt
 
+To avoid interfering with system packages, it's best to use a `virtual environment <https://docs.python.org/3/library/venv.html>`.
+
+.. warning::
+
+  Using a virtual environment is **mandatory** in some newer Python configurations
+  to avoid permission and package conflicts.
+
+.. code-block:: bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows use: venv\Scripts\activate
+pip install pyscipopt
+
+Remember to activate the environment (``source venv/bin/activate``) in each terminal session where you use PySCIPOpt.
+
 .. note:: For Linux users: PySCIPOpt versions newer than 5.1.1 installed via PyPI now require glibc 2.28+
 
   For our build infrastructure we use `manylinux <https://github.com/pypa/manylinux>`_.

docs/similarsoftware.rst

@@ -9,7 +9,7 @@ Alternate MIP Solvers (with Python interfaces)
 
 In the following we will give a list of other mixed-integer optimizers with available python interfaces.
 As each solver has its own set of problem classes that it can solve we will use a table with reference
-keys to summarise these problem classes.
+keys to summarize these problem classes.
 
 .. note:: This table is by no means complete.
 
@@ -87,8 +87,8 @@ This is software that is built on PySCIPOpt
 
 - `PyGCGOpt <https://github.com/scipopt/PyGCGOpt>`_: An extension of SCIP, using generic decompositions for solving MIPs
 - `GeCO <https://github.com/CharJon/GeCO>`_: Generators for Combinatorial Optimization
-- `scip-routing <https://github.com/mmghannam/scip-routing>`_:  An exact VRPTW solver in Python
-- `PySCIPOpt-ML <https://github.com/Opt-Mucca/PySCIPOpt-ML>`_:  Python interface to automatically formulate Machine Learning models into Mixed-Integer Programs
+- `scip-routing <https://github.com/mmghannam/scip-routing>`_: An exact VRPTW solver in Python
+- `PySCIPOpt-ML <https://github.com/Opt-Mucca/PySCIPOpt-ML>`_: Python interface to automatically formulate Machine Learning models into Mixed-Integer Programs
 -  `SCIP Book <https://scipbook.readthedocs.io/en/latest/>`_: Mathematical Optimization: Solving Problems using SCIP and Python
 
 Additional SCIP Resources

docs/tutorials/branchrule.rst

@@ -58,7 +58,7 @@ whose LP solution is most fractional.
 
           return {"result": SCIP_RESULT.BRANCHED}
 
-Let's talk about some features of this branching rule. Currently we only explicitly programmed
+Let's talk about some features of this branching rule. Currently, we only explicitly programmed
 a single function, which is called ``branchexeclp``. This is the function that gets called
 when branching on an LP optimal solution. While this is the main case, it is not the only
 case that SCIP handles. What if there was an LP error at the node, or you are given a set of external
@@ -108,7 +108,7 @@ strong branching or obtain some strong branching information.
 
   - What happens if a new primal solution is found and the bound is larger than the cutoff bound?
   - What happens if the bound for one of the children is above a cutoff bound?
-  - If probing is enabled then one would need to handle new found bounds appropriately.
+  - If probing is enabled then one would need to handle new-found bounds appropriately.
 
 .. code-block:: python
 

docs/tutorials/constypes.rst

@@ -134,7 +134,7 @@ constraint, you'd use the code:
 
 SCIP also allows the creation of custom constraint handlers. These could be empty and just
 there to record data, there to provide custom handling of some user defined function, or they could be there to
-enforce a constraint that is  incredibly inefficient to enforce via linear constraints.
+enforce a constraint that is incredibly inefficient to enforce via linear constraints.
 An example of such a constraint handler
 is presented in the lazy constraint tutorial for modelling the subtour elimination
 constraints :doc:`here </tutorials/lazycons>`
@@ -146,8 +146,8 @@ In a similar fashion to Variables with columns, see :doc:`this page </tutorials/
 constraints bring up an interesting feature of SCIP when used in the context of an LP.
 The context of an LP here means that we are after the LP relaxation of the optimization problem
 at some node. Is the constraint even in the LP?
-When you solve an optimization problm with SCIP, the problem is first transformed. This process is
-called presolve, and is done to accelerate the subsequent solving process. Therefore a constraint
+When you solve an optimization problem with SCIP, the problem is first transformed. This process is
+called presolve, and is done to accelerate the subsequent solving process. Therefore, a constraint
 that was originally created may have been transformed entirely, as the original variables that
 featured in the constraint have also been changed. Additionally, maybe the constraint was found to be redundant,
 i.e., trivially true, and was removed. The constraint is also much more general

docs/tutorials/cutselector.rst

@@ -33,7 +33,7 @@ A cut selector in PySCIPOpt takes the following structure:
         """
         :param cuts: the cuts which we want to select from. Is a list of scip Rows
         :param forcedcuts: the cuts which we must add. Is a list of scip Rows
-        :param root: boolean indicating whether weare at the root node
+        :param root: boolean indicating whether we are at the root node
         :param maxnselectedcuts: int which is the maximum amount of cuts that can be selected
         :return: sorted cuts and forcedcuts
         """
@@ -58,14 +58,14 @@ To include a cut selector one would need to do something like the following code
 
 The final argument of the ``includeCutsel`` function in the example above was the
 priority. If the priority is higher than all other cut selectors then it will be called
-first. In the case of some failure or non-success return code, then the second highest
+first. In the case of some failure or non-success return code, then the second-highest
 priority cut selector is called and so on.
 
 Example Cut Selector
 ======================
 
 In this example we will program a cut selector that selects the 10 most
-efficacious cuts. Efficacy is the standard measure for cut quality and can be calcuated
+efficacious cuts. Efficacy is the standard measure for cut quality and can be calculated
 via SCIP directly.
 
 .. code-block:: python

docs/tutorials/eventhandler.rst

@@ -51,7 +51,7 @@ The first argument is the model object and the second argument is the event that
 Adding Event Handlers with Classes
 ==================================
 
-If you need to store additional data in the event handler, you can create a custom event handler class that inherits from :code:`pyscipopt.Eventhdlr`.
+If you need to store additional data in the event handler, you can create a custom event handler class that inherits from :code:`pyscipopt.Eventhdlr`,
 and then include it in the model using the :code:`Model.includeEventHandler` method. The following is an example that stores the number of best solutions found:
 
 .. code-block:: python

docs/tutorials/expressions.rst

@@ -24,7 +24,7 @@ Non-Linear Objectives
 ======================
 
 While SCIP supports general non-linearities, it only supports linear objective functions.
-With some basic reformulation this is not a restriction however. Let's consider the general
+With some basic reformulation this is not a restriction, however. Let's consider the general
 optimization problem:
 
 .. math::
@@ -118,7 +118,7 @@ Absolute (Abs)
 ===============
 
 Absolute values of expressions is supported by overloading how ``__abs__`` function of
-SCIP expression objects. Therefore one does not need to import any functions.
+SCIP expression objects. Therefore, one does not need to import any functions.
 Let's see an example for constructing the following constraint:
 
 .. math::

docs/tutorials/heuristic.rst

@@ -97,10 +97,10 @@ To include the heuristic in the SCIP model one would use the following code:
 
 .. note:: The ``timingmask`` is especially important when programming your own heuristic. See
   `here <https://www.scipopt.org/doc/html/HEUR.php>`_ for information on timing options and how the affect
-  when the heuristic can be called. Note also that heuristic are as other plugins, called in order of
+  when the heuristic can be called. Note also that heuristics are, as other plugins, called in order of
   their priorities.
 
 .. note:: When you create a SCIP solution object it is important that you eventually free the object.
   This is done by calling ``scip.freeSol(sol)``, although this is not necessary when the solution has been
-  passed to ``scip.trySol(sol)`` with ``free=True`` (default behaviour).
+  passed to ``scip.trySol(sol)`` with ``free=True`` (default behavior).
 

docs/tutorials/lazycons.rst

@@ -24,7 +24,7 @@ Why use a Constraint Handler?
 =============================
 
 SCIP does not have a lazy constraint plug-in, rather its definition of constraint is broad enough to
-naturally encompass lazy constraints already. Therefore the user must simply create an appropriate
+naturally encompass lazy constraints already. Therefore, the user must simply create an appropriate
 constraint handler.
 
 
@@ -48,8 +48,8 @@ integer programming formulation for the problem is:
     & & & x_{i,j} \in \{0,1\}, \quad \forall (i,j) \in \mathcal{V} \times \mathcal{V}
 
 In the above formulation, the second set of constraints (marked with an \*) are called subtour elimination constraints.
-They are called such as a valid solution in absense of those constraints might consist of a collection
-of smaller cycles instead of a single large cycle. As the constraint set requires checking every subset of nodes
+They are called such as a valid solution in absence of those constraints might consist of a collection
+of smaller cycles instead of a single large cycle. As the constraint set requires checking every subset of nodes,
 there are exponentially many. Moreover, we know that most of the constraints are probably unnecessary,
 because it is clear from the objective that a minimum tour does not exist with a mini-cycle of nodes that are
 extremely far away from each other. Therefore, we want to model them as lazy constraints!
@@ -147,7 +147,7 @@ Now we will create the code on how to implement such a constraint handler.
 
                   # add subtour elimination constraint for each subtour
                   for S in subtours:
-                      print("Constraint added!)
+                      print("Constraint added!")
                       self.model.addCons(quicksum(x[i][j] for i in S for j in S if j>i) <= len(S)-1)
                       consadded = True
 
@@ -164,7 +164,7 @@ Now we will create the code on how to implement such a constraint handler.
 
 In the above we've created our problem and custom constraint handler! We now need to actually
 add the constraint handler to the problem. After that, we can simply call ``optimize`` whenever we are ready.
-To add the costraint handler use something along the lines of the following:
+To add the constraint handler use something along the lines of the following:
 
 .. code-block:: python
 

docs/tutorials/logfile.rst

@@ -226,7 +226,7 @@ how much memory is being used, and predicted amount of the tree search completed
 It should be mentioned that in the log file above there is a pause in between the branch-and-bound
 output and SCIP provides more presolve information. This is due to SCIP identifying that
 it is beneficial to start the branch-and-bound tree again but this time applying information
-it has learnt to the beginning of the search process. In the example above this is explained by the lines:
+it has learned to the beginning of the search process. In the example above this is explained by the lines:
 
 .. code-block:: RST
 
@@ -248,7 +248,7 @@ and finally the gap (the relative difference between the primal and dual bound).
 How to Redirect SCIP Output
 ===========================
 
-If you do not want this information output to your terminal than before calling ``optimize`` one can
+If you do not want this information output to your terminal, then before calling ``optimize`` one can
 call the following function:
 
 .. code-block:: python

docs/tutorials/model.rst

@@ -38,16 +38,16 @@ We can construct the optimization problem as follows:
   y = scip.addVar(vtype='C', lb=0, ub=None, name='y')
   z = scip.addVar(vtype='C', lb=0, ub=None, name='z')
   cons_1 = scip.addCons(x + y <= 5, name="cons_1")
-  cons_2 = scip.addCons(y + z >= 3, name="cons_2")
-  cons_3 = scip.addCons(x + y == 5, name="cons_3")
+  cons_2 = scip.addCons(x + z >= 3, name="cons_2")
+  cons_3 = scip.addCons(y + z == 4, name="cons_3")
   scip.setObjective(2 * x + 3 * y - 5 * z, sense="minimize")
   scip.optimize()
 
 That's it! We've built the optimization problem defined above and we've optimized it.
 For how to read a Model from file see :doc:`this page </tutorials/readwrite>` and for best practices
 on how to create more variables see :doc:`this page </tutorials/vartypes>`.
 
-.. note:: ``vtype='C'`` here refers to a continuous variables.
+.. note:: ``vtype='C'`` here refers to a continuous variable.
   Providing the lb, ub was not necessary as they default to (0, None) for continuous variables.
   Providing the name attribute is not necessary either but is good practice.
   Providing the objective sense was also not necessary as it defaults to "minimize".
@@ -173,7 +173,7 @@ You can find below a list of the available options, alongside their meaning.
     * - ``PARAMEMPHASIS.COUNTER``
       - to get feasible and "fast" counting process
     * - ``PARAMEMPHASIS.CPSOLVER`` 
-      - to get CP like search (e.g. no LP relaxation)
+      - to get CP-like search (e.g. no LP relaxation)
     * - ``PARAMEMPHASIS.EASYCIP``
       - to solve easy problems fast
     * - ``PARAMEMPHASIS.FEASIBILITY`` 
@@ -200,7 +200,7 @@ A SCIP Model can also be copied. This can be done with the following logic:
 
   scip_alternate_model = Model(sourceModel=scip) # Assuming scip is a pyscipopt Model
 
-This model is completely independent from the source model. The data has been duplicated.
+This model is completely independent of the source model. The data has been duplicated.
 That is, calling ``scip.optimize()`` at this point will have no effect on ``scip_alternate_model``.
 
 .. note:: After optimizing users often struggle with reoptimization. To make changes to an

docs/tutorials/nodeselector.rst

@@ -17,7 +17,7 @@ What is a Node Selector?
 ========================
 
 In the branch-and-bound tree an important question that must be answered is which node should currently
-be processed. That is, given a branch-and-bound tree in an intermediate state, select a a leaf node of the tree
+be processed. That is, given a branch-and-bound tree in an intermediate state, select a leaf node of the tree
 that will be processed next (most likely branched on). In SCIP this problem has its own plug-in,
 and thus custom algorithms can easily be included into the solving process!
 

docs/tutorials/readwrite.rst

@@ -51,7 +51,7 @@ what formats those are and the model types they're associated with.
 
 .. note:: In general we recommend sharing files using the ``.mps`` extension when possible.
 
-  For a more human readable format for equivalent problems we recommend the ``.lp`` extension.
+  For a more human-readable format for equivalent problems we recommend the ``.lp`` extension.
 
   For general non-linearities that are to be shared with others we recommend the ``.osil`` extension.