qevedo-compiler 0.1.0__tar.gz

qevedo_compiler-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: qevedo-compiler
+Version: 0.1.0
+Summary: QCC, the Quantum Compiler Collection: a technology-agnostic quantum circuit compiler (qevedo.compiler)
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/qevedo/qevedo-compiler
+Project-URL: Repository, https://github.com/qevedo/qevedo-compiler
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: openqasm<4,>=3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# QCC: the Quantum Compiler Collection
+
+A technology-agnostic quantum circuit compiler, part of the Qevedo packages:
+it installs as `qevedo-compiler` and imports as `qevedo.compiler`.
+
+## Install
+
+```bash
+pip install qevedo-compiler
+```
+
+For development, from a checkout:
+
+```bash
+cd qcc/python
+pip install -e ".[dev]"
+```
+
+`openqasm` 3.x is installed from PyPI. To develop both together, also install
+the sibling checkout: `pip install -e ../../openqasm`.
+
+## Usage
+
+```bash
+qcc compile examples/bell.qasm -o /tmp/out.qasm --device qevedo/compiler/profiles/all_to_all.yaml
+qcc compile program.qasm -o /tmp/out.qasm --qasm-version 3 -I lib/
+```
+
+From Python:
+
+```python
+from qevedo.compiler import compile_source, emit_qasm
+
+circuit = compile_source(open("examples/bell.qasm").read())
+print(emit_qasm(circuit))
+```
+
+The reference device profiles ship with the package, in
+`qevedo/compiler/profiles/`.
+
+Input can be OpenQASM 2 or 3. Programs are checked by `openqasm.analyze`
+before lowering, so errors are reported with their location. The frontend
+supports qubit and bit registers, gate calls with constant parameters
+(broadcast over registers), measurements, resets, barriers, `let` aliases of
+qubits and `const` values. Control flow, gate modifiers, classical variables,
+timing and hardware qubits are rejected with an error until the IR supports
+them. Gate definitions are not inlined: gates stay named instructions for the
+decomposition pass.
+
+## Tests
+
+```bash
+pytest
+```

qevedo_compiler-0.1.0/README.md

@@ -0,0 +1,54 @@
+# QCC: the Quantum Compiler Collection
+
+A technology-agnostic quantum circuit compiler, part of the Qevedo packages:
+it installs as `qevedo-compiler` and imports as `qevedo.compiler`.
+
+## Install
+
+```bash
+pip install qevedo-compiler
+```
+
+For development, from a checkout:
+
+```bash
+cd qcc/python
+pip install -e ".[dev]"
+```
+
+`openqasm` 3.x is installed from PyPI. To develop both together, also install
+the sibling checkout: `pip install -e ../../openqasm`.
+
+## Usage
+
+```bash
+qcc compile examples/bell.qasm -o /tmp/out.qasm --device qevedo/compiler/profiles/all_to_all.yaml
+qcc compile program.qasm -o /tmp/out.qasm --qasm-version 3 -I lib/
+```
+
+From Python:
+
+```python
+from qevedo.compiler import compile_source, emit_qasm
+
+circuit = compile_source(open("examples/bell.qasm").read())
+print(emit_qasm(circuit))
+```
+
+The reference device profiles ship with the package, in
+`qevedo/compiler/profiles/`.
+
+Input can be OpenQASM 2 or 3. Programs are checked by `openqasm.analyze`
+before lowering, so errors are reported with their location. The frontend
+supports qubit and bit registers, gate calls with constant parameters
+(broadcast over registers), measurements, resets, barriers, `let` aliases of
+qubits and `const` values. Control flow, gate modifiers, classical variables,
+timing and hardware qubits are rejected with an error until the IR supports
+them. Gate definitions are not inlined: gates stay named instructions for the
+decomposition pass.
+
+## Tests
+
+```bash
+pytest
+```

qevedo_compiler-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qevedo-compiler"
+version = "0.1.0"
+description = "QCC, the Quantum Compiler Collection: a technology-agnostic quantum circuit compiler (qevedo.compiler)"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "PyYAML>=6.0",
+    "openqasm>=3,<4",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+qcc = "qevedo.compiler.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/qevedo/qevedo-compiler"
+Repository = "https://github.com/qevedo/qevedo-compiler"
+
+# `qevedo` is a namespace package (no __init__.py) shared with the other
+# Qevedo packages, such as qevedo-simulator.
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qevedo.compiler*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"qevedo.compiler" = ["profiles/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qevedo_compiler-0.1.0/qevedo/compiler/__init__.py

@@ -0,0 +1,19 @@
+"""QCC, the Quantum Compiler Collection (`qevedo.compiler`)."""
+
+from qevedo.compiler.compiler import CompileOptions, compile_circuit, compile_file, compile_source
+from qevedo.compiler.emit.qasm import emit_qasm
+from qevedo.compiler.frontend.qasm import QasmFrontendError, parse_qasm
+from qevedo.compiler.ir import Circuit, Instruction
+
+__all__ = [
+    "Circuit",
+    "Instruction",
+    "CompileOptions",
+    "QasmFrontendError",
+    "compile_circuit",
+    "compile_file",
+    "compile_source",
+    "emit_qasm",
+    "parse_qasm",
+]
+__version__ = "0.1.0"

qevedo_compiler-0.1.0/qevedo/compiler/cli.py

@@ -0,0 +1,79 @@
+"""QCC command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from qevedo.compiler.compiler import CompileOptions, compile_file
+from qevedo.compiler.device import DeviceSpec, default_device
+from qevedo.compiler.emit.qasm import emit_qasm
+from qevedo.compiler.frontend.qasm import QasmFrontendError
+
+
+def _profiles_dir() -> Path:
+    return Path(__file__).resolve().parent / "profiles"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="qcc", description="Quantum Compiler Collection")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    compile_cmd = sub.add_parser("compile", help="Compile an OpenQASM 2 or 3 circuit")
+    compile_cmd.add_argument("input", type=Path, help="Input .qasm file")
+    compile_cmd.add_argument("-o", "--output", type=Path, required=True, help="Output .qasm file")
+    compile_cmd.add_argument(
+        "--device",
+        type=Path,
+        default=None,
+        help="Device profile YAML (default: built-in all-to-all)",
+    )
+    compile_cmd.add_argument(
+        "--qasm-version",
+        choices=["2", "3"],
+        default="2",
+        help="OpenQASM version of the output (default: 2)",
+    )
+    compile_cmd.add_argument(
+        "-I",
+        "--include",
+        action="append",
+        default=[],
+        type=Path,
+        metavar="DIR",
+        help="Directory searched by include statements (repeatable)",
+    )
+    compile_cmd.add_argument(
+        "--stats",
+        action="store_true",
+        help="Print gate counts and depth to stderr",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "compile":
+        return _run_compile(args)
+    return 1
+
+
+def _run_compile(args: argparse.Namespace) -> int:
+    device = DeviceSpec.from_yaml(args.device) if args.device else default_device()
+    try:
+        options = CompileOptions(device=device, include_paths=args.include)
+        compiled = compile_file(args.input, options)
+    except QasmFrontendError as error:
+        print(f"qcc: {error}", file=sys.stderr)
+        return 1
+    output = emit_qasm(compiled, version=f"{args.qasm_version}.0")
+    args.output.write_text(output + "\n", encoding="utf-8")
+    if args.stats:
+        counts = compiled.gate_counts()
+        print(f"device: {device.name}", file=sys.stderr)
+        print(f"depth: {compiled.depth()}", file=sys.stderr)
+        print(f"2q_gates: {compiled.two_qubit_gate_count()}", file=sys.stderr)
+        print(f"gates: {counts}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qevedo_compiler-0.1.0/qevedo/compiler/compiler.py

@@ -0,0 +1,51 @@
+"""End-to-end compilation driver."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from qevedo.compiler.device import DeviceSpec, default_device
+from qevedo.compiler.emit.qasm import emit_qasm
+from qevedo.compiler.frontend.qasm import parse_qasm
+from qevedo.compiler.ir import Circuit
+from qevedo.compiler.passes.base import PassManager
+
+
+@dataclass
+class CompileOptions:
+    device: DeviceSpec | None = None
+    pass_manager: PassManager | None = None
+    #: Directories searched by ``include`` statements, after the input's directory.
+    include_paths: Sequence[str | Path] = field(default_factory=tuple)
+
+
+def compile_circuit(circuit: Circuit, options: CompileOptions | None = None) -> Circuit:
+    opts = options or CompileOptions()
+    device = opts.device or default_device()
+    manager = opts.pass_manager or PassManager.default(device)
+    return manager.run(circuit, device)
+
+
+def compile_file(input_path: str | Path, options: CompileOptions | None = None) -> Circuit:
+    """Compile an OpenQASM 2 or 3 file."""
+    opts = options or CompileOptions()
+    circuit = parse_qasm(path=input_path, include_paths=opts.include_paths)
+    return compile_circuit(circuit, opts)
+
+
+def compile_source(source: str, options: CompileOptions | None = None) -> Circuit:
+    """Compile OpenQASM 2 or 3 source text."""
+    opts = options or CompileOptions()
+    circuit = parse_qasm(source=source, include_paths=opts.include_paths)
+    return compile_circuit(circuit, opts)
+
+
+def compile_to_qasm(
+    input_path: str | Path,
+    options: CompileOptions | None = None,
+    version: str = "2.0",
+) -> str:
+    """Compile a file and return the result as OpenQASM ``version`` source."""
+    return emit_qasm(compile_file(input_path, options), version=version)

qevedo_compiler-0.1.0/qevedo/compiler/device.py

@@ -0,0 +1,84 @@
+"""Technology-agnostic backend description."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Set, Tuple
+
+import yaml
+
+
+@dataclass
+class DeviceSpec:
+    """Describes qubit connectivity and native gates for a target."""
+
+    name: str
+    topology: str
+    qubits: int
+    edges: List[Tuple[int, int]] = field(default_factory=list)
+    native_gates: Set[str] = field(default_factory=set)
+    directed_edges: bool = False
+    max_parallel_2q: int = 1
+    gate_rules: Dict[str, dict] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> DeviceSpec:
+        edges = [tuple(edge) for edge in data.get("edges", [])]
+        topology = data.get("topology", "coupling_graph")
+        qubits = int(data["qubits"])
+        if topology == "all_to_all" and not edges:
+            edges = [(i, j) for i in range(qubits) for j in range(i + 1, qubits)]
+        native = {gate.lower() for gate in data.get("native_gates", [])}
+        return cls(
+            name=data["name"],
+            topology=topology,
+            qubits=qubits,
+            edges=edges,
+            native_gates=native,
+            directed_edges=bool(data.get("directed_edges", False)),
+            max_parallel_2q=int(data.get("max_parallel_2q", 1)),
+            gate_rules=data.get("gate_rules", {}),
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> DeviceSpec:
+        with open(path, encoding="utf-8") as handle:
+            data = yaml.safe_load(handle)
+        return cls.from_dict(data)
+
+    def adjacency(self) -> Dict[int, Set[int]]:
+        graph: Dict[int, Set[int]] = {q: set() for q in range(self.qubits)}
+        for a, b in self.edges:
+            graph.setdefault(a, set()).add(b)
+            if not self.directed_edges:
+                graph.setdefault(b, set()).add(a)
+        return graph
+
+    def supports_gate(self, gate: str, qubits: Iterable[int]) -> bool:
+        gate = gate.lower()
+        if gate not in self.native_gates:
+            return False
+        if gate not in self.gate_rules:
+            return True
+        rule = self.gate_rules[gate]
+        placement = rule.get("placement") or rule.get("on")
+        if placement == "edge" and len(list(qubits)) == 2:
+            pair = tuple(qubits)
+            if self.directed_edges:
+                return pair in self.edges
+            return pair in self.edges or (pair[1], pair[0]) in self.edges
+        return True
+
+
+def default_device() -> DeviceSpec:
+    """All-to-all superconducting-style device with a common IBM-like gateset."""
+    qubits = 32
+    edges = [(i, j) for i in range(qubits) for j in range(i + 1, qubits)]
+    return DeviceSpec(
+        name="all_to_all_32",
+        topology="all_to_all",
+        qubits=qubits,
+        edges=edges,
+        native_gates={"rz", "sx", "x", "cx"},
+    )

qevedo_compiler-0.1.0/qevedo/compiler/emit/qasm.py

@@ -0,0 +1,83 @@
+"""QCC IR → OpenQASM 2 or 3, printed by the ``openqasm`` package (3.x)."""
+
+from __future__ import annotations
+
+import math
+from fractions import Fraction
+
+import openqasm
+from openqasm import ast
+
+from qevedo.compiler.ir import Circuit, Clbit, Instruction, Qubit
+
+__all__ = ["emit_qasm"]
+
+# IR gate names that are spelled differently in OpenQASM 3's stdgates.inc.
+_OPENQASM3_NAMES = {"u": "U"}
+
+
+def emit_qasm(circuit: Circuit, version: str = "2.0", include_barriers: bool = True) -> str:
+    """Serialize ``circuit`` as an OpenQASM ``version`` ("2.0" or "3.0") program.
+
+    Gates keep their IR names and come from ``qelib1.inc`` (OpenQASM 2) or
+    ``stdgates.inc`` (OpenQASM 3).
+    """
+    if version not in ("2.0", "3.0"):
+        raise ValueError(f"unsupported OpenQASM version {version!r}")
+    openqasm3 = version == "3.0"
+    statements: list[ast.Statement] = [ast.Include("stdgates.inc" if openqasm3 else "qelib1.inc")]
+    for name, size in circuit.qreg_sizes.items():
+        statements.append(ast.QubitDeclaration(ast.Identifier(name), ast.IntegerLiteral(size)))
+    for name, size in circuit.creg_sizes.items():
+        statements.append(
+            ast.ClassicalDeclaration(ast.BitType(ast.IntegerLiteral(size)), ast.Identifier(name))
+        )
+    for inst in circuit.instructions:
+        statement = _statement(inst, openqasm3, include_barriers)
+        if statement is not None:
+            statements.append(statement)
+    # The printer uses OpenQASM 2 syntax (qreg, creg, measure ->) for version 2.0.
+    return openqasm.dumps(ast.Program(statements, version=version)).rstrip("\n")
+
+
+def _statement(inst: Instruction, openqasm3: bool, include_barriers: bool) -> ast.Statement | None:
+    name = inst.name.lower()
+    if name == "barrier":
+        return ast.Barrier([_bit(q) for q in inst.qubits]) if include_barriers else None
+    if name == "measure":
+        measure = ast.MeasureExpression(_bit(inst.qubits[0]))
+        return ast.MeasureStatement(measure, _bit(inst.clbits[0]))
+    if name == "reset":
+        return ast.Reset(_bit(inst.qubits[0]))
+    name = _OPENQASM3_NAMES.get(name, inst.name) if openqasm3 else inst.name
+    return ast.GateCall(
+        [], ast.Identifier(name), [_angle(p) for p in inst.params], [_bit(q) for q in inst.qubits]
+    )
+
+
+def _bit(bit: Qubit | Clbit) -> ast.IndexedIdentifier:
+    return ast.IndexedIdentifier(ast.Identifier(bit.register), [[ast.IntegerLiteral(bit.index)]])
+
+
+def _angle(value: float) -> ast.Expression:
+    """``value`` as a readable expression: a small rational multiple of pi when it is one."""
+    ratio = Fraction(value / math.pi).limit_denominator(16)
+    if ratio and abs(float(ratio) * math.pi - value) < 1e-12:
+        # Build "-3 * pi / 4" rather than "-(3 * pi / 4)".
+        expression: ast.Expression = ast.Identifier("pi")
+        numerator = abs(ratio.numerator)
+        if numerator != 1:
+            factor: ast.Expression = ast.IntegerLiteral(numerator)
+            if ratio < 0:
+                factor = ast.UnaryExpression(ast.UnaryOperator.NEGATE, factor)
+            expression = ast.BinaryExpression(ast.BinaryOperator.MULTIPLY, factor, expression)
+        elif ratio < 0:
+            expression = ast.UnaryExpression(ast.UnaryOperator.NEGATE, expression)
+        if ratio.denominator != 1:
+            expression = ast.BinaryExpression(
+                ast.BinaryOperator.DIVIDE, expression, ast.IntegerLiteral(ratio.denominator)
+            )
+        return expression
+    if value < 0:
+        return ast.UnaryExpression(ast.UnaryOperator.NEGATE, ast.FloatLiteral(-value))
+    return ast.FloatLiteral(value)