Draft: Switch to uv for dependency management

.github/workflows/test.yml

@@ -16,15 +16,22 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          # enable caching but invalidate if dependencies change
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          # pin to a specific version
+          version: "0.5.5"
+
+      - name: "Set up Python"
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version-file: "pyproject.toml"
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e .
+      - name: Install the project
+        run: uv sync --all-extras --dev
 
       - name: Run tests
-        run: pytest ucc --verbose
+        run: uv run pytest ucc --verbose

.github/workflows/ucc-benchmarks.yml

@@ -15,13 +15,13 @@ jobs:
   run-benchmarks:
     runs-on: ucc-benchmarks-8-core-U22.04
     if: contains(github.event.head_commit.message, '[benchmark chore]') == false
-    
+
     steps:
       - name: Checkout Code
         uses: actions/checkout@v4
         with:
           ssh-key: ${{ secrets.DEPLOY_KEY }}
-          
+
       # Build the Docker image
       - name: Build Docker image
         run: docker build -t ucc-benchmark .
@@ -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
+              uv run ./benchmarks/scripts/run_benchmarks.sh 8 && \
+              uv run ./benchmarks/scripts/plot_avg_benchmarks_over_time.py && \
+              uv run ./benchmarks/scripts/plot_latest_benchmarks.py
             "
 
       # Commit and push benchmark results

.readthedocs.yml

@@ -7,7 +7,7 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.12"
-
-python:
-  install:
-    - requirements: requirements.txt
+  jobs:
+    post_install:
+      - pip install uv
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --group docs --link-mode=copy

Dockerfile

@@ -1,18 +1,34 @@
-FROM python:3.12-slim
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-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
-
 # Set the working directory to the root of your project
 WORKDIR /ucc
 
-# Set up the virtual environment
-RUN python3 -m venv /venv
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+# Copy the entire project into the container
+COPY . /ucc
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
 
-# 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  
+# Place executables in the environment at the front of the path
+ENV PATH="/ucc/.venv/bin:$PATH"
 
+# Show installed package details
+RUN uv 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,11 @@ UCC interfaces automatically with multiple quantum computing frameworks, includi
 pip install ucc
 ```
 
-or install a dev version!
+If developing or running benchmark, please install [uv](https://docs.astral.sh/uv/getting-started/installation/), then setup a dev version:
 ```bash
 git clone https://github.com/unitaryfund/ucc.git
 cd ucc
-pip install -e . # Editable mode
+uv install --all-extras --all-groups
 ```
 
 ### Example with Qiskit, Cirq, and PyTKET
@@ -60,7 +60,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 +72,16 @@ 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 `uv run ./ucc/benchmarks/scripts/run_benchmarks.sh` assuming you setup for development using `uv` as recommended above.
 
-On Mac you can do this with `brew install parallel`. 
+This script runs compiler benchmarks in parallel, so you will need to first install `parallel` to support it.
+
+On Mac you can do this with `brew install parallel`.
 
 ## Contributing
 
@@ -95,5 +97,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,24 +13,23 @@ 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 `uv <https://docs.astral.sh/uv/>` for packaging and dependency management.
+After installing uv, run the following commands to clone the repository, create a uv managed virtual environment for development, and install dependencies.
 
 .. code:: bash
-
-    pip install -e .
-
-With this set up you can now run tests using
+    git clone https://github.com/unitaryfund/ucc.git
+    cd ucc
+    uv install --all-extras --all-groupsS
 
 .. code:: bash
 
-    pytest ucc
+    uv run pytest ucc
 
 and build the documentation by changing to the ``docs/source`` directory where you can run
 
 .. code:: bash
 
-    make html
+    uv run make html
 
 The built documentation will then live in ``ucc/docs/source/_build/html``.
 

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.
@@ -23,7 +23,7 @@ To release a new version of ``ucc`` on GitHub, follow the steps below.
 4. **Create a New Tag:**
     - Once the PR is merged, pull the changes to your local repository.
     - Create a new Git tag for the release. The tag name should match the version number (e.g., ``v1.1.0``).
-    
+
     .. code-block:: bash
 
         git tag v1.1.0
@@ -36,4 +36,4 @@ To release a new version of ``ucc`` on GitHub, follow the steps below.
     - Publish the release.
 
 .. tip::
-    Ensure that all changes pass the tests, and the documentation builds correctly before creating a release.
+    Ensure that all changes pass the tests, and the documentation builds correctly before creating a release.

docs/source/user_guide.rst

@@ -7,16 +7,14 @@ It can be used with multiple quantum computing frameworks, including `Qiskit <ht
 Installation
 *************
 
-To install ``ucc`` run:
+To install the latest version of ``ucc`` from PyPI 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 ≥ 3.12. 
+UCC requires Python version ≥ 3.12.
 
 Basic usage
 ***********
@@ -68,11 +66,11 @@ The full list of transpiler passes available in UCC can be found in the :doc:`ap
 Customization
 *************
 
-UCC offers different levels of customization, from settings accepted by the "default" pass ``UCCDefault1`` to the ability to add custom transpiler passes. 
+UCC offers different levels of customization, from settings accepted by the "default" pass ``UCCDefault1`` to the ability to add custom transpiler passes.
 
 Transpilation settings
 ======================
-UCC settings can be adjusted using the keyword arguments of the ``ucc.compile()`` function, as shown. 
+UCC settings can be adjusted using the keyword arguments of the ``ucc.compile()`` function, as shown.
 
 .. code:: python
 
@@ -83,7 +81,7 @@ UCC settings can be adjusted using the keyword arguments of the ``ucc.compile()`
    )
 
 
-- ``return_format`` is the format in which the input circuit will be returned, e.g. "TKET" or "OpenQASM2". Check ``ucc.supported_circuit_formats()`` for supported circuit formats. Default is the format of input circuit. 
+- ``return_format`` is the format in which the input circuit will be returned, e.g. "TKET" or "OpenQASM2". Check ``ucc.supported_circuit_formats()`` for supported circuit formats. Default is the format of input circuit.
 - ``target_device`` can be specified as a Qiskit backend or coupling map, or a list of connections between qubits. If None, all-to-all connectivity is assumed. If a Qiskit backend or coupling map is specified, only the coupling list extracted from the backend is used.
 
 Writing a custom pass
@@ -114,7 +112,7 @@ UCC's built-in pass manager ``UCCDefault1().pass_manager`` can be used to apply
 In the following example we show how to add passes for merging single qubit rotations interrupted by a commuting 2 qubit gate.
 
 .. code:: python
-   
+
    from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
    from qiskit.transpiler.passes import Optimize1qGatesSimpleCommutation
 
@@ -127,7 +125,7 @@ In the following example we show how to add passes for merging single qubit rota
    ucc_compiler = UCCDefault1()
 
    ucc_compiler.pass_manager.append(Optimize1qGatesSimpleCommutation(basis=single_q_basis))
-   ucc_compiler.pass_manager.append(BasisTranslator(sel, target_basis=target_basis)) 
+   ucc_compiler.pass_manager.append(BasisTranslator(sel, target_basis=target_basis))
 
    custom_compiled_circuit = ucc_compiler.run(circuit_to_compile)
 
@@ -149,5 +147,5 @@ A note on terminology
 
 .. important::
    There is some disagreement in the quantum computing community on the proper usage of the terms "transpilation" and "compilation."
-   For instance, Qiskit refers to optimization of the Directed Acyclic Graph (DAG) of a circuit as "transpilation," whereas in qBraid, the 1:1 translation of one circuit representation into another without optimization (e.g. a Cirq circuit to a Qiskit circuit; OpenQASM 2 into PyTKET) is called "transpilation." 
+   For instance, Qiskit refers to optimization of the Directed Acyclic Graph (DAG) of a circuit as "transpilation," whereas in qBraid, the 1:1 translation of one circuit representation into another without optimization (e.g. a Cirq circuit to a Qiskit circuit; OpenQASM 2 into PyTKET) is called "transpilation."
    In addition, Cirq uses the term "transformer" and PyTKET uses :code:`CompilationUnit` to refer to what Qiskit calls a transpiler pass.

pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "ucc"
+version = "0.4.2"
+description = "Unitary Compiler Collection: A quantum circuit interface and compiler for multiple quantum frameworks"
+authors = [
+    {name="Jordan Sullivan", email="jordan@unitary.foundation"},
+    {name="Misty Wahl"},
+    {name="Nate Stemen"}
+]
+license = "GPL-3.0"
+readme = "README.md"
+repository = "https://github.com/unitaryfund/ucc"
+requires-python = ">=3.12"
+dependencies = [
+    "cirq-core>=1.4.1",
+    "ply>=3.11",
+    "pytket>=1.40.0",
+    "qbraid>=0.9.3",
+    "qiskit>=1.3.2",
+    "qiskit-qasm3-import>=0.5.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-cov>=6.0.0",
+]
+docs = [
+    "myst-parser>=4.0.0",
+    "sphinx>=8.1.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+