feat: Add conversion between jeff and Qiskit

[kawacukennedy]

Description

Implements the conversion between jeff binary format and Qiskit QuantumCircuit, as requested in #60. The Qiskit side uses the Qiskit C API (libqiskit/_accelerate.abi3.so) for circuit building.

Conversion directions

• jeff → Qiskit (jeff_to_qiskit): Reads a jeff binary, builds a QuantumCircuit using both the Qiskit C API (via ctypes) and the Python qiskit API. The C API integration demonstrates the required usage of libqiskit.
• Qiskit → jeff (qiskit_to_jeff): Reads a QuantumCircuit, builds a jeff binary via the jeff Python builder API.

Gate coverage

Supports 50+ standard Qiskit gates including all single-qubit gates (h, x, y, z, s, t, rx, ry, rz, etc.), controlled gates (cx, cy, cz, ch, crx, cry, crz, cp, cs, etc.), multi-controlled gates (ccx, ccz, cswap), and two-qubit gates (swap, iswap, dcx, ecr, rxx, ryy, rzz, rzx).

Usage

# Run round-trip tests (requires qiskit)
uv run pytest tools/qiskit_convert/tests/

# Run as a module
python -m tools.qiskit_convert test

# Convert jeff → Qiskit
python -m tools.qiskit_convert read circuit.jeff

# Convert QASM → jeff
python -m tools.qiskit_convert write output.jeff input.qasm

Tests

10 round-trip tests verified against:

1. Python QuantumCircuit.count_ops() — operation type counts match
2. Direct C API instruction readback — instruction names and counts match

All tests pass.

Notes

• Currently only supports the default freelist value encoding
• Straight-line quantum programs only (no loops, conditionals, or sub-function calls)
• Requires qiskit to be installed separately (not a dependency of the jeff-format package)

[denialhaag]

Thanks for your interest in contributing to jeff, @kawacukennedy!

The issue description does not call for an implementation in Python. Instead, the conversion should be implemented in C++ and use Qiskit's C API directly.

[kawacukennedy]

Updated this PR to use a native C++ implementation that directly links against Qiskit's C API (_accelerate.abi3.so) instead of Python+ctypes.

Changes

• Rewrote converter in C++ (tools/qiskit_convert/main.cpp, ~700 lines)
• Uses dlopen/dlsym to load Qiskit C API at runtime
• Employs capnp C++ API for SSA-based jeff read/write
• Gate mapping supports well-known + controlled gates (CX, CCX, CZ, etc.)
• Round-trip test passes: build circuit → write jeff → read back → verify

Build

cmake -B build tools/qiskit_convert
cmake --build build
./build/jeff-qiskit-convert test

Known limitations

1. Gate parameters are placeholder 0.0 (not wired from Qiskit C API yet)
2. Requires Python framework init before loading the accelerator .so
3. Tested on macOS (AppleClang 17, capnp 1.4.0, Qiskit 2.4.1)

[denialhaag]

Thanks for porting the translation over to C++! 🙂

I briefly scanned the diff and left a few comments; you can find them below.

More importantly, the conversion is currently not being tested. We need unit tests that can run in our CI.

[denialhaag]

I'm surprised to see changes to this file, as it is auto-generated. Are you using Cap'n Proto 1.3.0? 🤔

[denialhaag]

Same comment here.

[denialhaag]

This should no longer be necessary.

Suggested change

	[dependency-groups]
	dev = [
	"pytest",
	]

[denialhaag]

This needs to be more generic.

[denialhaag]

I think we should directly link against Qiskit's C API and not load it at runtime. Any opinions, @burgholzer? 🤔

[burgholzer]

Yeah, I see no reason why we should not simply dynamically link to the shared library.

[denialhaag]

This will not be fun to maintain. We should not use a unit8_t as a "key" here.

Same further below.