Discopygal Installation

Before installing, make sure you have already completed the steps in Prerequisites. If you run into a problem, check Troubleshooting.

Installation is driven by the install.py script that ships with DiscoPygal. The script detects which kind of distribution it is running inside and picks the matching installation mode, so the same command works in both cases:

Mode	Detected when	What the script does
Release (wheel)	requirements.txt is absent	Runs build_cgal_variants.py (located next to install.py) to install the CGAL bindings, finds the single .whl beside it, and installs that wheel with pip.
Source	requirements.txt is present	Runs scripts/build_cgal_variants.py to compile the CGAL binding variants, then installs the package from the source directory with pip install .

Most users want the release mode. Choose the tab below that matches what you have.

Note

There is also a Starter package, a trimmed-down build meant for learning and coursework. See Starter package below — it installs the same way as the release package.

Step 1: Prepare the installation directory

Release packageStarter packageSource checkout

Extract the DiscoPygal release archive into a directory of your choice, then open that directory in your terminal. It should contain at least:

install.py
build_cgal_variants.py
discopygal_taucgl-<version>-<tags>.whl

Important

Keep exactly one .whl file next to install.py. The script aborts if it finds several wheels, so it never has to guess which one you meant. Delete or move older wheels before continuing.

Step 2: Create a virtual environment

install.py installs into whichever Python interpreter runs it, so create and activate an environment first. Otherwise DiscoPygal is installed system-wide.

Linux / macOSWindows (PowerShell)Windows (CMD)

uv venv
source .venv/bin/activate

Step 3: Run the installer

With the environment active, run the script with the environment’s Python:

python install.py

The script prints each step as it runs and stops at the first failure, reporting the exit status of the command that failed. On success it ends with:

Installation completed successfully!

To uninstall, delete the .venv folder. It may be hidden.

More installation methods for package developers

Validation installation

Installing DiscoPygal adds three command line tools to the environment:

Command	Purpose
scene_designer	Author and edit scene files. See Scene Designer guide.
solver_viewer	Run solvers on a scene and visualize the resulting paths.
scenarios_runner	Run batch experiments from a scenarios file.

The best way to validate the installation is to run the tools. You can do that in two ways.

Method 1: Activate the virtual environment

Linux / macOSWindows (PowerShell)Windows (CMD)

source .venv/bin/activate
scene_designer
solver_viewer

Method 2: Run the tools through uv

uv run scene_designer
uv run solver_viewer

Starter package

The starter package is a reduced build of DiscoPygal intended for courses and self-study. It ships from the same source tree as the full release, built by stripping out the built-in solver implementations before packaging, so learners implement solvers themselves instead of importing ready-made ones.

Compared to the release package, the starter wheel omits:

• The discopygal.solvers implementations (the solvers package itself, minus its __init__.py, is excluded).

• discopygal.solvers_infra.tensor_solver.

• discopygal.solvers_infra.nearest_neighbors, samplers, SamplingSolver, and roadmap.

Everything else — the CGAL bindings, scene_designer, solver_viewer, scenarios_runner, and the rest of the infrastructure — is unchanged.

Installation is identical to the release package: the starter archive has no requirements.txt, so install.py detects release mode, runs build_cgal_variants.py to install the CGAL bindings, and installs the single .whl file next to it with pip. Follow Step 1 above using the Starter package tab, then continue with Steps 2 and 3 as normal.

Notes

• You may need the .exe suffix on Windows, for example scene_designer.exe.

• If the tools do not start, make sure the Python packages directory is on PATH.

• If install.py reports that build_cgal_variants.py or scripts/build_cgal_variants.py does not exist, the distribution is incomplete — re-extract the release archive, or make sure you are running the script from the root of the repository.

• For more information, see the Scene Designer guide and the Solver Viewer walkthrough.