pycvxset: Convex sets in Python

• pycvxset: Convex sets in Python
  • What can pycvxset do for me?
  • Quick start
    • Requirements
    • Installation
      • Sanity check
    • Optional: Testing
    • Optional: Documentation and testing
  • Getting help
  • Contributing
  • License
  • Acknowledgements
  • Contact

What can pycvxset do for me?

pycvxset is a Python package for manipulation and visualization of convex sets.

Currently, pycvxset supports the following three representations:

1. polytopes,
2. ellipsoids, and
3. constrained zonotopes (which are equivalent to polytopes).

Some of the operations enabled by pycvxset include:

• construct sets from a variety of representations and transform between these representations,
• perform various operations on these sets including (but not limited to):
  • plot in 2D and 3D,
  • affine and inverse-affine transformation,
  • Minkowski sum,
  • Pontryagin difference,
  • intersection,
  • checking for containment,
  • projection,
  • slicing, and
  • support function evaluation.

See the Jupyter notebooks in examples folder for more details on how pycvxset can be used in set-based control and perform reachability analysis.

Quick start

Requirements

pycvxset supports Python 3.9+ on Ubuntu, Windows, and MacOS. As described in setup.py, pycvxset has the following core dependencies:

1. numpy
2. scipy
3. cvxpy
4. matplotlib
5. pycddlib
6. gurobipy: This dependency is optional. Almost all functionalities of pycvxset are available without Gurobi. However, pycvxset uses Gurobi (through cvxpy) to perform some containment and equality checks involving constrained zonotopes. See License section for more details.

Installation

Refer to .github/workflows for exact steps to install pycvxset for different OSes. These steps are summarized below:

1. OS-dependent pre-installation steps:
   • Ubuntu: Install gmp.

     $ sudo apt-get install libgmp-dev
     

   • MacOS: Install pycddlib manually in order to link with gmp.

     % brew install gmp
     % python3 -m pip install --upgrade pip
     % git clone https://github.com/mcmtroffaes/pycddlib.git
     % cd pycddlib
     % git checkout master
     % git submodule update --init
     % ./cddlib-makefile-gmp.sh
     % env "CFLAGS=-I$(brew --prefix)/include -L$(brew --prefix)/lib" python3 -m pip install .
     % cd ..
     

     These steps are adapted from pycddlib/build.yml.
   • Windows: No special steps required since pip takes care of it. If plotting fails, you can set matplotlib backend via an environment variable set MPLBACKEND=Agg. See https://matplotlib.org/3.5.1/users/explain/backends.html#selecting-a-backend for more details.
2. Clone the pycvxset repository into a desired folder PYCVXSET_DIR.
3. Run pip install -e . in the folder PYCVXSET_DIR.

Sanity check

Check your installation by running python3 examples/pycvxset_diag.py in the folder PYCVXSET_DIR. The script should generate a figure with two subplots, each generated using pycvxset.

• Left subplot: A 3D plot of two polytopes (one at the origin, and the other translated and rotated). You can interact with this plot using your mouse.
• Right subplot: A 2D plot of the projection of the polytope, and its corresponding minimum volume circumscribing and maximum volume inscribing ellipsoids.

Optional: Testing

1. Use pip install -e ".[with_tests]" to install the additional dependencies.
2. Run $ ./scripts/run_tests_and_update_docs.sh to view testing results on the command window.
3. Open ./docs/source/_static/codecoverage/overall/index.html in your browser for coverage results.

Optional: Documentation and testing

1. Use pip install -e ".[with_docs_and_tests]" to install the additional dependencies.
2. Run $./scripts/run_all.sh. This will take about 5 minutes.
   • Faster but incomplete option: Run only $./scripts/run_sphinx_docs.sh to build the API documentation without rendering the tutorial notebooks or performing coverage.
3. In your browser, view
   • API documentation at ./docs/build/index.html.
   • View the Jupyter notebooks at ./docs/build/tutorials/tutorials.html.
   • View code coverage from testing at ./docs/build/_static/codecoverage/overall/index.html.

Getting help

Let us say that you have read the available Documentation and searched the Discussion and the Issue webpages, but still need help.

Please start a Discussion for...

• Getting help in setting up pycvxset to work on your computer.
• Advice on how to use pycvxset for your set manipulations problem.
• Suggestions on documentation of the code.
• Collecting ideas for potential new features/enhancements from the community.

Please open an Issue if you believe that fixing your problem will involve a change in the pycvxset source code. For example...

• Bug reports.
• New feature/enhancement proposals with details.

How to submit a good bug report? When opening an Issue, please consider providing:

• High-level description of the behavior you would expect and the actual behavior.
• Which version of pycvxset are you using? The bleeding edge or the version number.
• OS (Windows, Linux, Mac, or something else)
• Can you reliably reproduce the issue?
• Details of the bug (a stack trace can be useful).
• A reduced test case that reproduces the issue for our development team.

Contributing

See CONTRIBUTING.md for our policy on contributions.

License

pycvxset is released under AGPL-3.0-or-later license, as found in the LICENSE.md file.

All files:

Copyright (c) 2020-2024 Mitsubishi Electric Research Laboratories (MERL).

SPDX-License-Identifier: AGPL-3.0-or-later

except the following files:

1. .gitignore
2. README.md
3. pycvxset/Polytope/__init__.py
4. pycvxset/Polytope/operations_binary.py
5. pycvxset/Polytope/operations_unary.py
6. pycvxset/Polytope/plotting_scripts.py
7. pycvxset/Polytope/vertex_halfspace_enumeration.py
8. pycvxset/__init__.py
9. pycvxset/common/__init__.py
10. setup.py
11. tests/test_polytope_binary.py
12. tests/test_polytope_init.py
13. tests/test_polytope_vertex_facet_enum.py

which have the copyright

Copyright (C) 2020-2024 Mitsubishi Electric Research Laboratories (MERL)
Copyright (c) 2019 Tor Aksel N. Heirung

SPDX-License-Identifier: AGPL-3.0-or-later
SPDX-License-Identifier: MIT

The method contains in pycvxset/ConstrainedZonotope/operations_binary.py uses gurobipy (through cvxpy) and requires acceptance of appropriate license terms.

Acknowledgements

The development of pycvxset started from commit ebd85404 of pytope.

Copyright (c) 2019 Tor Aksel N. Heirung

SPDX-License-Identifier: MIT

pycvxset extends pytope in several new directions, including:

• Plotting for 3D polytopes using matplotlib,
• Interface with cvxpy for access to a wider range of solvers,
• Introduce new methods for Polytope class including circumscribing and inscribing ellipsoids, volume computation, and containment checks,
• Minimize the use of vertex-halfspace enumeration using convex optimization,
• Include extensive documentation and example Jupyter notebooks,
• Implement exhaustive testing with nearly 100% coverage, and
• Support for Ellipsoid and ConstrainedZonotope set representations.

Contact

For questions or bugs, contact Abraham P. Vinod (Email: vinod@mail.com or abraham.p.vinod@ieee.org).