Metadata-Version: 2.4
Name: qcdiff
Version: 0.2.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Testing
License-File: LICENSE
Summary: Semantic diff for OpenQASM 3 quantum circuits: compare two QASM programs at the gate level, for CI and code review
Keywords: quantum,qasm,openqasm,diff,qiskit,quantum-computing
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/navneet83/qcdiff

# qcdiff

Semantic diff for OpenQASM 3 quantum circuits. `qcdiff` compares two QASM programs at the gate level instead of the text level, so comment, whitespace, and declaration-order changes do not count as differences. Built for CI pipelines and code review of transpiler output.

This package is the Python binding of the Rust [qcdiff](https://github.com/navneet83/qcdiff) tool.

## Install

```sh
pip install qcdiff
```

## Usage

```python
import qcdiff

report = qcdiff.diff_files("reference/ghz.qasm", "build/ghz.qasm")
if report.has_changes():
    print(report)          # the same text the CLI prints

# In a pytest regression gate:
assert not qcdiff.diff_files("reference/ghz.qasm", "build/ghz.qasm")
```

With Qiskit circuits, export to QASM 3 first:

```python
from qiskit import qasm3

report = qcdiff.diff_sources(qasm3.dumps(circuit_a), qasm3.dumps(circuit_b))
print(report.added, report.removed, report.modified)
for line in report.lines:
    if line.change != "same":
        print(line)
```

`diff_sources` and `diff_files` raise `qcdiff.QasmError` on OpenQASM 2 input or parse errors.

`qcdiff` reports what changed, not whether the circuits are equivalent; for formal equivalence checking use [mqt-qcec](https://github.com/munich-quantum-toolkit/qcec).

## License

Apache-2.0

