Contributing Guide

Thank you for your interest in contributing to UCC! All contributions to this project are welcome, and they are greatly appreciated; every little bit helps. The most common ways to contribute here are

  1. opening an issue to report a bug or propose a new feature, or ask a question, and

  2. opening a pull request to fix a bug, or implement a desired feature.

For issues/contributions related to benchmarks, please open in the ucc-bench repo

The rest of this document describes the technical details of getting set up to develop, and make your first contribution to ucc.

Setting up your development environment

We leverage 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.

git clone https://github.com/unitaryfoundation/ucc.git
cd ucc
uv sync --all-extras --all-groups

This particular invocation of uv sync ensures optional developer and documentation dependencies are installed.

For all of the following commands, we assume you either prefix each command with uv run, or you first activate the uv managed virtual environment by running source .venv/bin/activate in your shell.

For more details on using uv, refer to its documentation or this tutorial.

To run the unit tests, you can use the following command

pytest ucc

and build the documentation by changing to the docs/source directory where you can run

make html

The built documentation will then live in ucc/docs/source/_build/html.

To test that code examples in the documentation work as expected, you can run

make doctest

This leverages Sphinx doctest extension .

We also use pre-commit to run code formatting and linting checks before each commit. To enable the pre-commit hooks, run

pre-commit install

Tip

Remember to run the tests and build the documentation before opening a pull request to ensure a smoother pull request review.

Proposing a new transpiler pass

1. Proposing a New Transpiler Pass

When proposing a new transpiler pass, please include a detailed report containing:

  1. Detailed description of the technique

    1. Provide a written abstract without excessive jargon, citing the source of the technique.

    2. (Optional, recommended): Include a diagram showing an example circuit and how it would be affected by this pass.

  2. Performance expectations

    1. Estimate how much the technique is expected to reduce gate counts or compile time. This rough estimate helps us prioritize techniques.

    2. Specify which types of circuits are expected to improve or not improve with this technique.

    3. Define test circuits of the above types which you will use to validate the technique.

2. Implementing and Validating a Prototype of the Pass

  1. Create a prototype

    • A Jupyter notebook or a small script is sufficient for the prototype.

  2. Validate the prototype

3. Implementing the New Pass in the Codebase

Once the prototype is validated, implement the new pass in the codebase. Documentation to guide you through this process is available in the user guide. For more detailed information and examples, refer to the Qiskit documentation.

4. Clear Acceptance Criteria for Incorporation into default transpiler

For the new pass to be incorporated into the default compiler, it must meet the following criteria:

  1. Reduction in compiled 2-qubit gate count

    • Demonstrate a reduction in the number of 2-qubit gates.

  2. Reduction in runtime

    • Show a reduction in runtime, especially if the new technique replaces a slower one.

  3. Compatibility with other passes

    • Ensure the new pass performs as expected when used with other existing passes.

We appreciate your contributions and look forward to your new pass proposals!

Code of Conduct

UCC development abides by the Contributor Covenant Code of Conduct.