Skip to content

Home

Jump to bottom
Santiago Nunez-Corrales edited this page May 19, 2026 · 8 revisions

lccfq-lang Wiki

A research compiler for quantum circuits, written in Python. This wiki tells you what it is, how to install it, how to write programs with it, how to make those programs run fast, and how to extend it.

About the backend. lccfq-lang compiles circuits down to a native gate set and is intended to drive real superconducting hardware via a separate backend layer. That backend layer is a stub today. The compiler is fully functional — gate decomposition, routing, optimization, transpilation all work and are tested — but QPU.exec_circuit does not yet send circuits to physical hardware. Read each page with that in mind; "running" in this wiki means "compiling to the point where hardware would execute it," not "executing on a QPU."

Where to start

You are... Read
New to the project 01 Introduction → [02 Setup](02 Setup) → 05 Examples
Writing your first quantum program 03 Gates for the low-level API, or 04 Blocks for the high-level one
Looking up a specific gate or config field 07 Native Gates or 06 QPU Configuration
Wondering what opt_level=2 actually does 10 Optimizations, with depth in 11 Performance Notes
Confused by a term 09 Glossary
Contributing code 12 Contributing → 13 Limitations & Roadmap

All pages

Tier 1 — Getting Started

The "I just arrived" tier. Assumes no prior knowledge of the project.

  • [01 Introduction](01 Introduction) — what lccfq-lang is, what it solves, the five-stage compilation pipeline at a glance, a 5-minute first program.
  • [02 Setup](02 Setup) — installing via uv, running the test suite, what works out of the box, what doesn't (backend caveat).

Tier 2 — User Guide / Programming

How to write circuits. Two complementary APIs.

  • 03 Writing Programs with Gates — the low-level API: Circuit, the >> operator, every gate family, measurement, QASM export.
  • 04 Writing Programs with Blocks — the high-level API: BlockFactory, all built-in block types (oracle, diffusion, QFT, Trotter, …), the multi-control decomposition modes.
  • 05 Examples — annotated walkthroughs of bell_state.py, dj.py, teleportation.py, grover5.py, and opt_demo.py.

Tier 3 — Reference

Look-up material. Each page stands alone.

  • 06 QPU Configuration — the TOML schema, what each field means, how to add a new topology type, the pfaff_v1 reference configuration.
  • 07 Native Gates (XYiSW) — what the transpiler produces, the gate set, the sqiSWAP-based decompositions in tabular form.
  • 08 Pipeline Architecture — the lowering pipeline stage by stage: mapped → swapped → expanded → arch_optimized → transpiled → mach_optimized, with input/output types per stage.
  • 09 Glossary — definitions of terms used across the other pages. Other pages link here rather than redefining.

Tier 4 — Optimization & Performance

How to make the compiler do useful work for you.

  • 10 Optimizations — choosing opt_level, what each level enables, reading opt_report, registering custom passes.
  • 11 Performance Notes — when to pick which opt_level and routing_strategy, compile-time vs circuit-quality trade-offs, known hot spots.

Tier 5 — Contributor

For people writing code in the repository.

  • 12 Contributing — repository layout, dev environment, how to add a new pass / gate / block, test conventions, code style.
  • 13 Limitations & Roadmap — known gaps and the order they're likely to be addressed.

Conventions used in this wiki

  • Code blocks are real Python from the repository (examples/, src/lccfq_lang/, src/tests/) wherever possible, marked with the source file.
  • Deep technical details live in "Details" sections at the bottom of each page, or in dedicated reference pages (07, 08, 11). The body of every page is meant to be actionable on its own.
  • Cross-references go through "See also" lists at the end of each page. Inline links are used sparingly to avoid pulling readers off-page mid-paragraph.
  • Terms are defined in the Glossary; pages link there rather than redefining in-line.

What this wiki is not

  • Not an API reference. For exact function signatures and types, read the source — every public module has docstrings.
  • Not a quantum computing textbook. It assumes you know what a qubit is, what a unitary is, and roughly what gates like H and CX do. The Glossary defines project-specific terms; standard quantum vocabulary is taken as given.
  • Not a paper. Where compilation algorithms come from published work (e.g., the da Silva & Park multi-controlled-gate construction), the relevant pages cite the paper and table the result rather than reproducing the derivation.

Clone this wiki locally