Discopygal Installation ----------------------- .. _dicopygal_installation: Before installing, make sure you have already completed the steps in :doc:`Prerequisites `. If you run into a problem, check :ref:`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: .. list-table:: :header-rows: 1 :widths: 22 26 52 * - 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 :ref:`starter_package` below — it installs the same way as the release package. Step 1: Prepare the installation directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: .. tab:: Release package Extract the DiscoPygal release archive into a directory of your choice, then open that directory in your terminal. It should contain at least: .. code-block:: text install.py build_cgal_variants.py discopygal_taucgl--.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. .. tab:: Starter package Extract the DiscoPygal starter package archive into a directory of your choice, then open that directory in your terminal. It should contain at least: .. code-block:: text install.py build_cgal_variants.py discopygal_taucgl_starter--.whl The starter package has no ``requirements.txt``, so ``install.py`` installs it exactly like the release package. See :ref:`starter_package` for what makes this build different. .. tab:: Source checkout Clone the repository and enter it: .. code-block:: bash git clone https://github.com/TAU-CGL/discopygal.git cd discopygal Because the checkout contains ``requirements.txt``, ``install.py`` automatically uses source mode and compiles the CGAL variants for you. .. note:: Compiling the CGAL bindings from source takes a long time and needs a working C++ compiler and at least 8 GB of RAM. See :doc:`Prerequisites `. 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. .. tabs:: .. tab:: Linux / macOS .. code-block:: bash uv venv source .venv/bin/activate .. tab:: Windows (PowerShell) .. code-block:: powershell uv venv .\.venv\Scripts\Activate.ps1 .. tab:: Windows (CMD) .. code-block:: bat uv venv .\.venv\Scripts\activate.bat Step 3: Run the installer ~~~~~~~~~~~~~~~~~~~~~~~~~ With the environment active, run the script with the environment's Python: .. code-block:: bash 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 :ref:`package developers ` Validation installation ----------------------- Installing DiscoPygal adds three command line tools to the environment: .. list-table:: :header-rows: 1 :widths: 26 74 * - Command - Purpose * - ``scene_designer`` - Author and edit scene files. See :doc:`Scene Designer guide <../../guides/tutorial_first_scene>`. * - ``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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. tabs:: .. tab:: Linux / macOS .. code-block:: bash source .venv/bin/activate scene_designer solver_viewer .. tab:: Windows (PowerShell) .. code-block:: powershell .\.venv\Scripts\Activate.ps1 scene_designer solver_viewer .. tab:: Windows (CMD) .. code-block:: bat .\.venv\Scripts\activate.bat scene_designer solver_viewer Method 2: Run the tools through uv ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash uv run scene_designer uv run solver_viewer .. _starter_package: 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 :ref:`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 :doc:`Scene Designer guide <../../guides/tutorial_first_scene>` and the :doc:`Solver Viewer walkthrough <../../guides/tutorial_using_solver_viewer>`.