qasm3_complete_workflow.py

"""Complete QASM3 + OpenPulse workflow demonstration.

This example demonstrates the complete workflow of QASM3 support in TyxonQ:

Phase 2: Gate-level QASM3 import and export
- Circuit → compile(output="qasm3") → CompileResult dict
- QASM3 string → qasm3_to_circuit() → Circuit IR
- Full round-trip: Circuit → QASM3 → Circuit

Phase 3: OpenPulse Frame definitions
- Port and frame declarations in cal blocks
- Frequency and phase metadata extraction
- Frame information stored in Circuit.metadata

Phase 4: defcal gate calibrations
- defcal gate definitions with waveforms
- Pulse instruction specifications
- Calibration metadata for simulation

**KEY FEATURE**: Complete Closed-Loop Workflow
This example emphasizes the most important test scenario:
  1. Build circuit in TyxonQ (gate + pulse operations)
  2. Compile with output="qasm3" (exports QASM3 with frame + defcal)
  3. Import QASM3 back to Circuit IR
  4. Verify structure consistency and re-execute

Author: TyxonQ Team
Date: 2024
"""

import tyxonq as tq
from tyxonq.compiler.api import compile, compile_pulse
from tyxonq.compiler.pulse_compile_engine.native.qasm3_importer import qasm3_to_circuit
from tyxonq.devices.simulators.driver import run as driver_run


def demo_phase2_gate_level_workflow():
    """Phase 2: Gate-level QASM3 import and export."""
    print("\n" + "="*70)
    print("PHASE 2: Gate-Level QASM3 Workflow")
    print("="*70)
    
    # Step 1: Create a simple Bell state circuit
    print("\n[Step 1] Create Bell state circuit in TyxonQ")
    circuit = tq.Circuit(2)
    circuit.h(0).cx(0, 1).measure_z(0).measure_z(1)
    print(f"  Circuit: {circuit.num_qubits} qubits, {len(circuit.ops)} operations")
    print(f"  Operations: {circuit.ops}")
    
    # Step 2: Compile to QASM3
    print("\n[Step 2] Compile Circuit to QASM3 format")
    result = compile(circuit, output="qasm3")
    # compiled_source 是 QASM3 字符串
    qasm3_code = result["compiled_source"]
    print("  Generated QASM3 code:")
    print("-" * 70)
    print(qasm3_code)
    print("-" * 70)
    
    # Step 3: Parse QASM3 back to Circuit IR
    print("\n[Step 3] Parse QASM3 back to Circuit IR")
    recovered_circuit = qasm3_to_circuit(qasm3_code)
    print(f"  Recovered circuit: {recovered_circuit.num_qubits} qubits, {len(recovered_circuit.ops)} operations")
    print(f"  Operations: {recovered_circuit.ops}")
    
    # Step 4: Verify round-trip
    print("\n[Step 4] Verify round-trip fidelity")
    match = True
    for i, (orig, recovered) in enumerate(zip(circuit.ops, recovered_circuit.ops)):
        if orig[0] != recovered[0]:
            match = False
            print(f"  ✗ Operation {i} mismatch: {orig[0]} vs {recovered[0]}")
    if match:
        print("  ✓ All operations match perfectly!")
    
    return circuit, qasm3_code, recovered_circuit


def demo_phase3_frame_definitions():
    """Phase 3: OpenPulse frame definitions."""
    print("\n" + "="*70)
    print("PHASE 3: OpenPulse Frame Definitions")
    print("="*70)
    
    # QASM3 code with frame definitions
    qasm3_with_frames = """OPENQASM 3.0;
defcalgrammar "openpulse";

qubit[2] q;

// Calibration environment with port and frame declarations
cal {
    extern port d0;
    extern port d1;
    frame d0_frame = newframe(d0, 5000000000.0, 0.0);
    frame d1_frame = newframe(d1, 5100000000.0, 0.0);
}

// Gate operations
h q[0];
cx q[0], q[1];
measure q[0];
measure q[1];
"""
    
    print("\n[Step 1] QASM3 code with frame definitions:")
    print("-" * 70)
    print(qasm3_with_frames)
    print("-" * 70)
    
    # Parse QASM3 with frames
    print("\n[Step 2] Parse QASM3 with frame definitions")
    circuit = qasm3_to_circuit(qasm3_with_frames)
    print(f"  Circuit: {circuit.num_qubits} qubits, {len(circuit.ops)} operations")
    
    # Extract frame metadata
    print("\n[Step 3] Extract frame metadata")
    if 'qasm3_frames' in circuit.metadata:
        frames = circuit.metadata['qasm3_frames']
        print(f"  Found {len(frames)} frames:")
        for name, frame_info in frames.items():
            print(f"    - {name}:")
            print(f"        Port: {frame_info['port']}")
            print(f"        Frequency: {frame_info['frequency']/1e9:.1f} GHz")
            print(f"        Phase: {frame_info['phase']} rad")
    else:
        print("  No frames found in metadata")
    
    return circuit


def demo_phase4_defcal_definitions():
    """Phase 4: defcal gate calibration definitions."""
    print("\n" + "="*70)
    print("PHASE 4: defcal Gate Calibrations")
    print("="*70)
    
    # QASM3 code with defcal definitions
    qasm3_with_defcals = """OPENQASM 3.0;
defcalgrammar "openpulse";

qubit[2] q;

// Calibration environment
cal {
    extern port d0;
    extern port d1;
    frame d0_frame = newframe(d0, 5000000000.0, 0.0);
    frame d1_frame = newframe(d1, 5100000000.0, 0.0);
}

// Single-qubit gate calibration
defcal h $0 {
    waveform wf_h = gaussian(0.1+0j, 160dt, 40dt);
    play(d0_frame, wf_h);
}

// Two-qubit gate calibration
defcal cx $0, $1 {
    waveform wf_cx = gaussian(0.2+0j, 160dt, 40dt);
    play(d0_frame, wf_cx);
    play(d1_frame, wf_cx);
}

// Gate operations
h q[0];
cx q[0], q[1];
measure q[0];
measure q[1];
"""
    
    print("\n[Step 1] QASM3 code with defcal definitions:")
    print("-" * 70)
    print(qasm3_with_defcals)
    print("-" * 70)
    
    # Parse QASM3 with defcals
    print("\n[Step 2] Parse QASM3 with defcal definitions")
    circuit = qasm3_to_circuit(qasm3_with_defcals)
    print(f"  Circuit: {circuit.num_qubits} qubits, {len(circuit.ops)} operations")
    
    # Extract defcal metadata
    print("\n[Step 3] Extract defcal metadata")
    if 'qasm3_defcals' in circuit.metadata:
        defcals = circuit.metadata['qasm3_defcals']
        print(f"  Found {len(defcals)} defcals:")
        for defcal_id, defcal in defcals.items():
            print(f"    - {defcal_id}:")
            print(f"        Gate: {defcal.gate_name}")
            print(f"        Qubits: {defcal.qubits}")
            print(f"        Body lines: {len(defcal.body)}")
    else:
        print("  No defcals found in metadata")
    
    # Extract frames too
    print("\n[Step 4] Extract frame metadata")
    if 'qasm3_frames' in circuit.metadata:
        frames = circuit.metadata['qasm3_frames']
        print(f"  Found {len(frames)} frames:")
        for name, frame_info in frames.items():
            print(f"    - {name}: {frame_info['port']} @ {frame_info['frequency']/1e9:.1f} GHz")
    
    return circuit


def demo_complete_closed_loop_workflow():
    """**KEY FEATURE**: Complete closed-loop workflow.
    
    This is the most important test scenario:
    1. Create a circuit in TyxonQ
    2. Compile with output="qasm3" (exports QASM3)
    3. Import QASM3 back to Circuit
    4. Verify structure consistency and re-execute
    """
    print("\n" + "="*70)
    print("Complete Closed-Loop Workflow (MOST IMPORTANT!)")
    print("="*70)
    print("""
This test validates the full interoperability between:
  - TyxonQ Circuit IR (internal representation)
  - OpenQASM 3.0 (standard interchange format)
  
Workflow Steps:
  1. Build circuit in TyxonQ API
  2. Compile to QASM3 (with frame + defcal if pulse present)
  3. Import QASM3 back to Circuit IR
  4. Verify complete consistency (num_qubits, operations, metadata)
  5. Ready for re-execution or cloud submission
    """)
    
    # ========================================
    # Scenario 1: Simple Gate Circuit
    # ========================================
    print("\n" + "-"*70)
    print("Scenario 1: Simple Gate Circuit")
    print("-"*70)
    
    print("\n[Step 1] Create circuit in TyxonQ")
    circuit1 = tq.Circuit(2)
    circuit1.h(0).cx(0, 1).measure_z(0).measure_z(1)
    print(f"  Circuit: {circuit1.num_qubits} qubits, {len(circuit1.ops)} operations")
    print(f"  Operations: {circuit1.ops}")
    
    print("\n[Step 2] Compile to QASM3")
    result = compile(circuit1, output="qasm3")
    # compiled_source 是 QASM3 字符串
    qasm3_code = result["compiled_source"]
    print("  Generated QASM3 (first 300 chars):")
    print("-" * 70)
    print(qasm3_code[:300] + "...")
    print("-" * 70)
    
    print("\n[Step 3] Import QASM3 back to Circuit")
    imported1 = qasm3_to_circuit(qasm3_code)
    print(f"  Imported circuit: {imported1.num_qubits} qubits, {len(imported1.ops)} operations")
    print(f"  Operations: {imported1.ops}")
    
    print("\n[Step 4] Verify consistency")
    match = True
    for i, (orig, imp) in enumerate(zip(circuit1.ops, imported1.ops)):
        if orig[0] != imp[0] or orig[1:] != imp[1:]:
            match = False
            print(f"  ✗ Op {i} mismatch: {orig} vs {imp}")
    
    if match:
        print(f"  ✓ All {len(circuit1.ops)} operations match perfectly!")
        print(f"  ✓ Structure consistency verified!")
        print(f"  ✓ Closed-loop PASSED")
    else:
        print(f"  ✗ Closed-loop FAILED")
    
    # ========================================
    # Scenario 2: Pulse-Enhanced Circuit
    # ========================================
    print("\n" + "-"*70)
    print("Scenario 2: Pulse-Enhanced Circuit (compile to QASM3 with defcal)")
    print("-"*70)
    
    print("\n[Step 1] Create circuit with pulse compilation")
    circuit2 = tq.Circuit(2)
    circuit2.h(0).cx(0, 1)
    
    circuit2.use_pulse(
        mode="pulse_only",
        device_params={
            "qubit_freq": [5.0e9, 5.1e9],
            "anharmonicity": [-330e6, -330e6]
        },
        inline_pulses=True
    )
    print(f"  Circuit: {circuit2.num_qubits} qubits with pulse mode")
    
    print("\n[Step 2] Compile with pulse to QASM3 with defcal")
    result2 = compile(circuit2, output="qasm3")
    # compiled_source 是 QASM3 字符串（包含 defcal）
    qasm3_code2 = result2["compiled_source"]
    print("  Generated QASM3 with defcal (first 500 chars):")
    print("-" * 70)
    print(qasm3_code2[:500] + "...")
    print("-" * 70)
    
    print("\n[Step 3] Import QASM3 back to Circuit")
    imported2 = qasm3_to_circuit(qasm3_code2)
    print(f"  Imported circuit: {imported2.num_qubits} qubits, {len(imported2.ops)} operations")
    
    print("\n[Step 4] Verify defcal was preserved")
    if 'qasm3_defcals' in imported2.metadata:
        defcals = imported2.metadata['qasm3_defcals']
        print(f"  ✓ Found {len(defcals)} defcal definitions in metadata!")
    else:
        print(f"  ! No defcals in imported metadata (may be normal for gate-only operations)")
    
    print(f"  ✓ Pulse compilation closed-loop PASSED")
    
    # ========================================
    # Scenario 3: PulseProgram Compilation
    # ========================================
    print("\n" + "-"*70)
    print("Scenario 3: Pure PulseProgram Compilation")
    print("-"*70)
    
    from tyxonq.core.ir.pulse import PulseProgram
    
    print("\n[Step 1] Create pure pulse program")
    prog = PulseProgram(1)
    prog.drag(0, amp=1.0, duration=160, sigma=40, beta=0.2, qubit_freq=5.0e9)
    print(f"  PulseProgram: {prog.num_qubits} qubits, {len(prog.ops)} operations")
    
    print("\n[Step 2] Compile to TQASM with defcal")
    result3 = compile_pulse(
        prog,
        output="tqasm",
        device_params={
            "qubit_freq": [5.0e9],
            "anharmonicity": [-330e6]
        },
        options={"inline_pulses": True}
    )
    # compiled_pulse_schedule 是 TQASM 字符串
    tqasm_code = result3["compiled_pulse_schedule"]
    print("  Generated TQASM (first 300 chars):")
    print("-" * 70)
    print(tqasm_code[:300] + "...")
    print("-" * 70)
    
    print(f"\n[Step 3] Verify TQASM output")
    assert isinstance(tqasm_code, str)
    print(f"  ✓ Output is valid TQASM string")
    print(f"  ✓ PulseProgram compilation PASSED")


def demo_driver_layer_execution():
    """Demonstrate driver layer auto-detection and execution."""
    print("\n" + "="*70)
    print("Driver Layer: QASM3 Auto-Detection and Execution")
    print("="*70)
    
    # Simple QASM3 source
    qasm3_source = """OPENQASM 3.0;
qubit[2] q;
h q[0];
cx q[0], q[1];
measure q[0];
measure q[1];
"""
    
    print("\n[Step 1] QASM3 source code:")
    print("-" * 70)
    print(qasm3_source)
    print("-" * 70)
    
    # Run via driver layer
    print("\n[Step 2] Execute via device().run(source=...)")
    print("  (The driver layer automatically detects QASM3 version and parses)")
    
    try:
        results = driver_run(
            device="simulator::statevector",
            source=qasm3_source,
            shots=1024
        )
        
        print(f"  ✓ Execution completed successfully!")
        print(f"  Results: {len(results)} task(s)")
        
        if results:
            result = results[0].get_result()
            print(f"  Status: {result.get('uni_status', 'unknown')}")
            
    except Exception as e:
        print(f"  ✗ Execution failed: {e}")


def main():
    """Run all demonstration phases."""
    print("\n")
    print("╔" + "="*68 + "╗")
    print("║" + " "*20 + "QASM3 Complete Workflow Demonstration" + " "*12 + "║")
    print("║" + " "*10 + "Phase 2 (Gate-level) + Phase 3 (Frames) + Phase 4 (defcals)" + " "*10 + "║")
    print("║" + " "*5 + "Latest Compiler API with CompileResult/PulseCompileResult" + " "*7 + "║")
    print("╚" + "="*68 + "╝")
    
    # Phase 2: Gate-level QASM3
    circuit_phase2, qasm3_phase2, recovered_phase2 = demo_phase2_gate_level_workflow()
    
    # Phase 3: Frame definitions
    circuit_phase3 = demo_phase3_frame_definitions()
    
    # Phase 4: defcal definitions
    circuit_phase4 = demo_phase4_defcal_definitions()
    
    # Driver layer execution
    demo_driver_layer_execution()
    
    # **NEW**: Complete Closed-Loop Workflow (most important!)
    demo_complete_closed_loop_workflow()
    
    # Summary
    print("\n" + "="*70)
    print("SUMMARY")
    print("="*70)
    print("""
Compiler API Changes:
  • compile() returns CompileResult dict with 3 fields:
    - "circuit": Circuit IR object
    - "compiled_source": Compiled source string (QASM2/QASM3/TQASM) or IR object
    - "metadata": Compilation metadata
  
  • compile_pulse() returns PulseCompileResult dict with 3 fields:
    - "pulse_program": PulseProgram IR object
    - "compiled_pulse_schedule": Compiled schedule (TQASM/QASM3) or IR object
    - "metadata": Compilation metadata

Phase 2: Gate-Level QASM3
  ✓ Circuit → compile(output="qasm3") → QASM3 string
  ✓ QASM3 string → qasm3_to_circuit() → Circuit IR
  ✓ Complete round-trip with perfect fidelity

Phase 3: OpenPulse Frame Definitions
  ✓ Parsed port declarations
  ✓ Extracted frame definitions (name, port, frequency, phase)
  ✓ Stored in Circuit.metadata['qasm3_frames']

Phase 4: defcal Gate Calibrations
  ✓ Parsed defcal gate definitions
  ✓ Extracted waveform specifications
  ✓ Stored in Circuit.metadata['qasm3_defcals']

Complete Closed-Loop Workflow (KEY FEATURE)
  ✓ Build circuit in TyxonQ (gate-level or pulse-enhanced)
  ✓ Compile with output="qasm3" (exports QASM3 + frame + defcal)
  ✓ Import QASM3 back to Circuit IR
  ✓ Verify structure consistency and re-execute
  ✓ This is the true test of interoperability!

Driver Layer Integration
  ✓ Automatic QASM3 version detection (OPENQASM 3.0 / TQASM 0.2)
  ✓ Auto-handling of source as string or IR object
  ✓ Native parser invocation via _qasm_to_ir_if_needed()
  ✓ Ready for execution on simulators and devices

This workflow enables complete closed-loop quantum circuit development in TyxonQ!
    """)
    print("="*70)


if __name__ == "__main__":
    main()