Switch to poetry for dependency management

.github/workflows/test.yml

@@ -1,3 +1,6 @@
+# This workflow will install Python dependencies, run tests using poetry.
+# It can be tested locally using https://github.com/nektos/act with the command `act push --container-architecture linux/amd64 -j test`
+
 name: Run Tests
 
 on:
@@ -21,10 +24,14 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install dependencies
+      - name: Install Poetry
         run: |
           python -m pip install --upgrade pip
-          pip install -e .
+          pip install poetry
+
+      - name: Install dependencies & ucc
+        run: |
+          poetry install
 
       - name: Run tests
-        run: pytest ucc --verbose
+        run: poetry run pytest ucc --verbose

.github/workflows/ucc-benchmarks.yml

@@ -32,10 +32,9 @@ jobs:
           docker run --rm \
             -v "/home/runner/work/ucc/ucc:/ucc" \
             ucc-benchmark bash -c "
-              source /venv/bin/activate && \
-              ./benchmarks/scripts/run_benchmarks.sh 8 && \
-              python ./benchmarks/scripts/plot_avg_benchmarks_over_time.py && \
-              python ./benchmarks/scripts/plot_latest_benchmarks.py
+              poetry run ./benchmarks/scripts/run_benchmarks.sh 8 && \
+              poetry run python ./benchmarks/scripts/plot_avg_benchmarks_over_time.py && \
+              poetry run python ./benchmarks/scripts/plot_latest_benchmarks.py
             "
 
       # Commit and push benchmark results

.readthedocs.yml

@@ -7,7 +7,13 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.12"
-
-python:
-  install:
-    - requirements: requirements.txt
+  jobs:
+    post_install:
+      # Install poetry
+      # https://python-poetry.org/docs/#installing-manually
+      - pip install poetry
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      # VIRTUAL_ENV needs to be set manually for now.
+      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs

Dockerfile

@@ -1,18 +1,32 @@
 FROM python:3.12-slim
 
-# Install GNU Parallel and other dependencies
+# Install GNU Parallel for benchmark runs
 RUN apt-get update && apt-get install -y parallel
 
-# Copy the entire project into the container
-COPY . /ucc
+# Install Poetry
+RUN pip3 install poetry==2.0.1
 
 # Set the working directory to the root of your project
 WORKDIR /ucc
 
-# Set up the virtual environment
-RUN python3 -m venv /venv
+# Copy the entire project into the container
+COPY . /ucc
+
+ENV POETRY_NO_INTERACTION=1 \
+POETRY_VIRTUALENVS_IN_PROJECT=1 \
+POETRY_VIRTUALENVS_CREATE=true \
+POETRY_CACHE_DIR=/tmp/poetry_cache
+
+# Install (rarely changing) dependencies only using Poetry to leverage docker caching
+RUN --mount=type=cache,target=/tmp/poetry_cache poetry install --no-root
+
+# Install the `ucc` package itself
+RUN poetry install
+
+# Ensure the virtual environment is properly activated
+ENV VIRTUAL_ENV=/ucc/.venv
+ENV PATH="/ucc/.venv/bin:$PATH"
 
-# Install the required dependencies and the ucc package itself
-RUN /venv/bin/pip install --no-cache-dir -r /ucc/requirements.txt
-RUN /venv/bin/pip install -e . && /venv/bin/pip show ucc  
+# Show installed package details
+RUN poetry run pip show ucc
 

README.md

@@ -6,12 +6,12 @@
 [![Discord Chat](https://img.shields.io/badge/dynamic/json?color=blue&label=Discord&query=approximate_presence_count&suffix=%20online.&url=https%3A%2F%2Fdiscord.com%2Fapi%2Finvites%2FJqVGmpkP96%3Fwith_counts%3Dtrue)](http://discord.unitary.foundation)
 
 
-The **Unitary Compiler Collection (UCC)** is a Python library for frontend-agnostic, high performance compilation of quantum circuits. 
+The **Unitary Compiler Collection (UCC)** is a Python library for frontend-agnostic, high performance compilation of quantum circuits.
 
 UCC interfaces automatically with multiple quantum computing frameworks, including [Qiskit](https://github.com/Qiskit/qiskit), [Cirq](https://github.com/quantumlib/Cirq), and [PyTKET](https://github.com/CQCL/tket) and supports programs in OpenQASM 2 and [OpenQASM 3](https://openqasm.com/). For a full list of the latest supported interfaces, just call `ucc.supported_formats`.
 
 
-**Want to know more?** 
+**Want to know more?**
 - Check out our [documentation](https://ucc.readthedocs.io/en/latest/), which you can build locally after installation by running `make html` in `ucc/docs/source`.
 - For code, repo, or theory questions, especially those requiring more detailed responses, submit a [Discussion](https://github.com/unitaryfund/ucc/discussions).
 - For casual or time sensitive questions, chat with us on [Discord](http://discord.unitary.foundation).
@@ -26,11 +26,12 @@ UCC interfaces automatically with multiple quantum computing frameworks, includi
 pip install ucc
 ```
 
-or install a dev version!
+If developing or running benchmark, please install [Poetry](https://python-poetry.org/), then setup a dev version:
+
 ```bash
 git clone https://github.com/unitaryfund/ucc.git
 cd ucc
-pip install -e . # Editable mode
+poetry install
 ```
 
 ### Example with Qiskit, Cirq, and PyTKET
@@ -60,7 +61,7 @@ def test_qiskit_compile():
 def test_cirq_compile():
     qubits = LineQubit.range(2)
     circuit = CirqCircuit(
-        H(qubits[0]), 
+        H(qubits[0]),
         CNOT(qubits[0], qubits[1]))
     compile(circuit)
 ```
@@ -72,14 +73,14 @@ We run benchmarks regularly to compare against the most recent versions of the m
 And here you can see progress over time, with new package versions labeled for each compiler:
 ![alt text](benchmarks/avg_compiler_benchmarks_over_time.png)
 Note that the compile times before 2024-12-10 may have been run on different classical compute instances, so their runtime is not reported here, but you can find this data in benchmarks/results.
-After 2024-12-10, all data present in this plot is on the same compute instance using our [ucc-benchmarks](https://github.com/unitaryfund/ucc/blob/main/.github/workflows/ucc-benchmarks.yml) GitHub Actions workflow. 
+After 2024-12-10, all data present in this plot is on the same compute instance using our [ucc-benchmarks](https://github.com/unitaryfund/ucc/blob/main/.github/workflows/ucc-benchmarks.yml) GitHub Actions workflow.
 <!-- end-how-does-ucc-stack-up -->
 
 ## Benchmarking
 
-You can benchmark the performance of ucc against other compilers using `./ucc/benchmarks/scripts/run_benchmarks.sh`. This script runs compiler benchmarks in parallel, so you will need to first install `parallel` to support it.    
+You can benchmark the performance of ucc against other compilers using `./ucc/benchmarks/scripts/run_benchmarks.sh`. This script runs compiler benchmarks in parallel, so you will need to first install `parallel` to support it. If you setup `ucc` via `poetry` as recommended, either run the scripts after running `poetry shell` or prefix the script calls with `poetry run`.
 
-On Mac you can do this with `brew install parallel`. 
+On Mac you can do this with `brew install parallel`.
 
 ## Contributing
 
@@ -95,5 +96,5 @@ If you have questions about contributing please ask on the [Unitary Foundation D
 
 ## License
 
-UCC is distributed under [GNU Affero General Public License version 3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)(AGPLv3). 
+UCC is distributed under [GNU Affero General Public License version 3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)(AGPLv3).
 Parts of ucc contain code or modified code that is part of Qiskit, which is distributed under Apache 2.0 license.

docs/source/conf.py

@@ -1,17 +1,17 @@
 import os
 import sys
-
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../../'))
 sys.path.insert(0, os.path.abspath('../../../'))
 
+from ucc._version import __version__
+
 
 project = "ucc"
 copyright = "2024, Unitary Foundation"
 author = "Unitary Foundation"
 directory_of_this_file = os.path.dirname(os.path.abspath(__file__))
-with open(f"{directory_of_this_file}/../../VERSION.txt", "r") as f:
-    release = f.read().strip()
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/contributing.rst

@@ -13,14 +13,17 @@ The rest of this document describes the technical details of getting set up to d
 Setting up your development environment
 ---------------------------------------
 
-We recommend creating a virtual environment to install the required dependencies.
-Once this is set up using the tool of your choice, install the dependencies and ``ucc`` in editable mode by running the following command in the root directory of the repository.
+We leverage `poetry <https://python-poetry.org/>` for packaging and dependency management. 
+After installing poetry, run the following commands to clone the repository, create a poetry managed virtual environment for development, and install dependencies.
 
 .. code:: bash
 
-    pip install -e .
+    git clone https://github.com/unitaryfund/ucc.git
+    cd ucc
+    poetry install
 
-With this set up you can now run tests using
+For all of the following commands, either first run ``poetry shell`` to enable the poetry managed virtual environment,
+or prefix each command with ``poetry run``.
 
 .. code:: bash
 

docs/source/dev.rst

@@ -12,7 +12,7 @@ Cutting a release
 To release a new version of ``ucc`` on GitHub, follow the steps below.
 
 1. **Bump the Version:**
-    - Increment the version in ``VERSION.txt`` according to `semantic versioning <https://semver.org/>`_.
+    - Increment the version in ``pyproject.toml`` according to `semantic versioning <https://semver.org/>`_.
 
 2. **Update the Changelog:**
     - Update the ``CHANGELOG.rst`` file with all new changes, improvements, and bug fixes since the previous release.

docs/source/user_guide.rst

@@ -7,14 +7,11 @@ It can be used with multiple quantum computing frameworks, including `Qiskit <ht
 Installation
 *************
 
-To install ``ucc`` run:
+To install ``ucc`` run
 
 .. code:: bash
 
-   git clone https://github.com/unitaryfund/ucc.git
-   cd ucc
-   pip install -e . # Editable mode
-
+   pip install ucc
 
 UCC requires Python version :math:`\ge` 3.12.