pycvxset: Convex sets in Python

pycvxset: Convex sets in Python

What is pycvxset?

pycvxset (pronounced "Pie CVX Set") is a Python package for manipulation and visualization of convex sets. The code is open-source (see https://github.com/merlresearch/pycvxset), and is maintained by Abraham P. Vinod.

Currently, pycvxset supports the following three representations:

polytopes,
ellipsoids, and
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 sets in 2D and 3D,
- affine and inverse-affine transformation,
- checking for containment,
- intersection,
- Minkowski sum,
- Pontryagin difference,
- 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 pyproject.toml, pycvxset has the following core dependencies:

numpy
scipy
cvxpy
matplotlib
pycddlib: pycvxset requires pycddlib>=3.0.0. Use pycvxset<=1.0.2 to use pycvxset with earlier versions of pycddlib<=2.1.8.post1.
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:

OS-dependent pre-installation steps:
- Ubuntu: Install gmp.
```
$ sudo apt-get install libgmp-dev libcdd-dev python3-dev
```
  See pycddlib documentation or pycddlib/build.yml for more details.
- MacOS: Install gmp and cddlib.
```
% brew install gmp cddlib
% python3 -m pip install --upgrade pip
% env "CFLAGS=-I$(brew --prefix)/include -L$(brew --prefix)/lib" python -m pip install pycddlib==3.0.0
```
  See pycddlib documentation or pycddlib/build.yml for more details.
- 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.
Clone the pycvxset repository into a desired folder PYCVXSET_DIR.
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.

The following code block is reproduced from run_demo function in examples/pycvxset_diag.py. The code block demonstrates how one can use pycvxset to define sets and manipulate them:

# Copyright (C) 2020-2026 Mitsubishi Electric Research Laboratories (MERL)

import numpy as np
from pycvxset import Ellipsoid, Polytope
from scipy.spatial.transform import Rotation

# Define P as the intersection of a box with different sides and a halfspace
box_with_different_sides = Polytope(c=[0, 0, 0], h=[1, 0.5, 0.1])
P = box_with_different_sides.intersection_with_halfspaces([1, -0.5, 0], 0.25)
# Affine transformation (Rotate and translate P)
rotate_angle = np.pi / 4
R = Rotation.from_rotvec(rotate_angle * np.array([0, 0, 1])).as_matrix()
shift_vec = [5, 4, 3]
transformed_P = R @ P + shift_vec
# Projection (Compute its shadow on to the xy space)
project_transformed_P_to_XY = transformed_P.projection(project_away_dims=2)
# Centering ellipsoids
ellipsoid_inside_projection = Ellipsoid.deflate(project_transformed_P_to_XY)
ellipsoid_outside_projection = Ellipsoid.inflate(project_transformed_P_to_XY)

Optional: Testing

Use pip install -e ".[with_tests]" to install the additional dependencies.
Run $ ./scripts/run_tests_and_update_docs.sh to view testing results on the command window.
View code coverage from testing at ./docs/build/_static/codecoverage/overall/index.html on your browser.

Optional: Documentation

Use pip install -e ".[with_docs_and_tests]" to install the additional dependencies.
To produce the documentation,
- Run $./scripts/run_all.sh. This should take about 15 minutes. For faster but incomplete options,
  - To generate just the latex files for the MANUAL.pdf, run $./scripts/run_sphinx_pdf.sh. This command will assume that the environment has LaTeX setup properly.
  - To build the API documentation without rendering the notebooks or coverage results, run $./scripts/run_sphinx_html.sh.
View the documentation as,
- PDF at ./MANUAL.pdf
- HTML pages (without internet) at localhost:8000 after running python -m http.server --directory ./docs/build/.
  - Documentation website is available 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

See MANUAL.pdf or https://merlresearch.github.io/pycvxset/ for documentation of pycvxset.

Please use the Discussion page or the Issue page, if you still need help.

Contributing

See CONTRIBUTING.md for our policy on contributions.

License

pycvxset code is released under AGPL-3.0-or-later license, as found in the LICENSE.md file. The documentation for pycvxset is released under CC-BY-4.0 license, as found in the LICENSES/CC-BY-4.0.md.

All files:

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

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

except the following files:

.gitignore
README.md
pycvxset/Polytope/__init__.py
pycvxset/Polytope/operations_binary.py
pycvxset/Polytope/operations_unary.py
pycvxset/Polytope/plotting_scripts.py
pycvxset/Polytope/vertex_halfspace_enumeration.py
pycvxset/__init__.py
pycvxset/common/__init__.py
tests/test_polytope_binary.py
tests/test_polytope_init.py
tests/test_polytope_vertex_facet_enum.py

which have the copyright

Copyright (C) 2020-2026 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](https://github.com/heirung/pytope/commit/ebd85404ba235e8223fca1f6ba8817decc

Pycvxset

Install / Use

README