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.

Contributing a New Compiler Pass

1. Proposing a New Compiler Pass

If you’ve found a compiler pass you’d like to implement in UCC, first you’ll submit a New Compiler Pass Discussion, which asks you to provide…

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

   • Use the test circuits defined in section 1. Proposing a New Compiler Pass to validate the technique.

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. Passes should not cause new bugs or worsen performance

   • Whether the new pass is meant to run alongside existing passes or replace some of them, we check that it doesn’t cause any unexpected bugs, break any existing tests, or worsen performance.

4. Integration with the library vs. default transpiler

   • It’s important to know that a new pass might be accepted into the library of passes but not necessarily integrated into the default transpiler. You can see examples of this in this discussion and this pull request.

5. Benchmarking your new pass

   • To run benchmarks on your new pass, please refer to the tutorial and documentation on using ucc-bench.

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.