Contributing#

We welcome contributions of all sizes—bug fixes, documentation, new components, and improvements to existing layouts or models. Please keep pull requests focused, documented, and easy to review.

How to contribute#

  • Discuss substantial changes in an issue or draft PR before investing significant effort.

  • Keep changeset size reasonable; split large efforts into smaller, reviewable chunks.

  • Add or update tests and documentation alongside code changes.

Installation for Contributors#

This project uses uv for Python package management and just as a command runner.

Clone the repository and install the development dependencies:

git clone https://github.com/gdsfactory/quantum-rf-pdk.git
cd quantum-rf-pdk
just install

Note

Git LFS must be installed to run all tests locally. Some test data files (e.g., CSV files in tests/models/data/) are tracked with Git LFS and will not be properly downloaded without it.

KLayout Technology Installation#

For contributors, you can install the technology files directly from the repository:

just install-tech

Note

After installation, restart KLayout to ensure the new technology appears.

Development workflow#

Check out the commands for testing and building documentation with:

just --list

  • Run the full test suite: just test

  • Run layout regression tests: just test-gds (or just test-gds-fail-fast while iterating)

  • Run formatting/linting hooks: just run-pre

  • Build docs (optional but encouraged when docs change): just docs

AI usage policy#

We encourage using AI tools to accelerate your workflow—for example, prototyping components and layouts, generating model visualizations, writing tests, or drafting documentation. However, do not submit “AI slop.” You are fully responsible for the quality of your contributions. Any AI-generated code, layouts, or text must be reviewed, functionally tested, and completely human-maintainable.

Justfile Commands#

The repository includes a justfile with convenient commands for common development tasks.

Available Commands#

To see the list of available commands at any time, run:

just --list

Available recipes:
    default                # List available commands

    [all]
    all                    # Run all tests, pre-commit hooks, build wheel and documentation in parallel

    [build]
    build                  # Build the Python package (install build tool and create dist)
    show component_name="" # Generate and show a PDK component by name (opens interactive chooser by default), saving its GDS to build/

    [docs]
    docs                   # Build the HTML documentation
    docs-latex             # Setup LaTeX for PDF documentation
    docs-pdf               # Build PDF documentation (requires a TeXLive installation)

    [lint]
    run-pre                # Run all pre-commit hooks on all files
    update-pre             # Update pre-commit hooks to the latest revisions

    [setup]
    clean                  # Clean up all build, test, coverage and Python artifacts
    install                # Install the package and all development dependencies
    install-tech           # Install KLayout technology files for the PDK

    [test]
    test *args             # Run the full test suite in parallel using pytest
    test-gds               # Run GDS regressions tests (tests/test_pdk.py)
    test-gds-fail-fast     # Run GDS regressions tests (tests/test_pdk.py) and stop at first failure
    test-gds-force         # Run GDS regressions tests (tests/test_pdk.py) and regenerate
    test-hfss *args        # Run HFSS simulation tests (requires HFSS to be installed)
    test-ports             # Run optical port position tests (tests/test_pdk.py::test_optical_port_positions)

Usage#

To run any of these commands, use:

just <command>

Code of Conduct#

We follow the gdsfactory Code of Conduct.