update and fix circuit.compile compile_api bug

Author: Wall-ee

docs/source/api/compiler/index.rst

@@ -62,14 +62,17 @@ Main Compilation Function
    circuit.cx(0, 1)
    circuit.cx(1, 2)
    
-   # Basic compilation
-   compiled = compile(circuit)
+   # Basic compilation (returns CompileResult dict)
+   result = compile(circuit)
+   circuit_ir = result["circuit"]       # IR object
+   compiled_source = result["compiled_source"]  # None or source string
    
    # Specify optimization
-   compiled = compile(
+   result = compile(
        circuit,
        options={'optimization_level': 2}
    )
+   circuit_ir = result["circuit"]
 
 **Example 2: Pulse Circuit Compilation**:
 
@@ -86,13 +89,15 @@ Main Compilation Function
        "anharmonicity": [-330e6, -320e6]
    })
    
-   # Compile to TQASM (auto-detects pulse operations)
-   result = compile(circuit, output="tqasm")
-   # Returns TQASM code as string
+   # Compile to QASM3 (returns CompileResult dict)
+   result = compile(circuit, output="qasm3")
+   qasm3_code = result["compiled_source"]  # QASM3 string with defcal
+   circuit_ir = result["circuit"]           # Original circuit IR
    
    # Or compile to pulse IR (preserves waveform objects)
    result = compile(circuit, output="pulse_ir")
-   # Returns Circuit with pulse operations
+   pulse_ir = result["compiled_source"]  # PulseProgram IR object
+   circuit_ir = result["circuit"]
 
 **Example 3: Cloud Submission (homebrew_s2)**:
 
@@ -111,10 +116,93 @@ Main Compilation Function
    })
    
    # Compile to TQASM (auto-converts to tyxonq_homebrew_tqasm for homebrew_s2)
-   tqasm_code = compile(circuit, output="tqasm")
+   result = compile(circuit, output="tqasm")
+   tqasm_code = result["compiled_source"]  # TQASM string (QASM2 compatible)
    
    # Submit to cloud
-   result = circuit.run()
+   result = circuit.run(shots=100)
+
+Pulse Compilation Function
+==========================
+
+.. autofunction:: tyxonq.compiler.compile_pulse
+
+**Signature**:
+
+.. code-block:: python
+
+   def compile_pulse(
+       pulse_program,                      # PulseProgram to compile
+       output: str = "pulse_ir",         # Output format: "pulse_ir", "tqasm", "openqasm3"
+       device_params: Dict = None,        # Device parameters (qubit_freq, anharmonicity, etc.)
+       calibrations: Dict = None,         # Custom pulse calibrations
+       device: str = None,                # Target device for format selection
+       options: Dict = None,              # Compilation options (inline_pulses, etc.)
+       **kwargs
+   ) -> PulseCompileResult
+
+**Returns**:
+
+``PulseCompileResult`` TypedDict with three fields:
+
+.. code-block:: python
+
+   {
+       "pulse_program": PulseProgram,              # Original PulseProgram IR
+       "compiled_pulse_schedule": Optional[str],   # Compiled schedule (TQASM/QASM3) or IR object
+       "metadata": Dict[str, Any]                  # Compilation metadata
+   }
+
+**Output Format Options**:
+
+- ``"pulse_ir"`` (default): TyxonQ native Pulse IR
+  - compiled_pulse_schedule: PulseProgram IR object
+- ``"tqasm"`` / ``"tqasm0.2"``: TQASM 0.2 format (cloud-ready)
+  - compiled_pulse_schedule: TQASM string with defcal
+- ``"openqasm3"``: OpenQASM 3.0 with pulse extensions
+  - compiled_pulse_schedule: QASM3 string with defcal
+
+**Example 1: Basic Pulse Compilation**:
+
+.. code-block:: python
+
+   from tyxonq.core.ir.pulse import PulseProgram
+   from tyxonq.compiler import compile_pulse
+   
+   # Create pulse program
+   prog = PulseProgram(1)
+   prog.drag(0, amp=1.0, duration=160, sigma=40, beta=0.2, qubit_freq=5.0e9)
+   
+   # Compile to Pulse IR (default)
+   result = compile_pulse(prog, device_params={
+       "qubit_freq": [5.0e9],
+       "anharmonicity": [-330e6]
+   })
+   pulse_ir = result["pulse_program"]           # PulseProgram IR
+   schedule = result["compiled_pulse_schedule"] # None (IR format)
+
+**Example 2: Compile to TQASM for Cloud**:
+
+.. code-block:: python
+
+   # Compile to TQASM with full defcal definitions
+   result = compile_pulse(
+       prog,
+       output="tqasm",
+       device_params={
+           "qubit_freq": [5.0e9],
+           "anharmonicity": [-330e6]
+       },
+       options={"inline_pulses": True}  # Include full defcal definitions
+   )
+   tqasm_code = result["compiled_pulse_schedule"]  # TQASM string with defcal
+   
+   # Submit to cloud
+   circuit = Circuit(1)
+   task = circuit.device(provider="tyxonq", device="homebrew_s2").run(
+       source=tqasm_code,
+       shots=100
+   )
 
 Optimization Levels
 ===================
@@ -565,4 +653,25 @@ See Also
 - :doc:`/user_guide/compiler/index` - Compiler User Guide
 - :doc:`/api/core/index` - Core API
 - :doc:`/api/devices/index` - Devices API
+- :doc:`/examples/basic_examples` - Compilation Examples
+   # Benchmark different levels
+   for level in [0, 1, 2, 3]:
+       start = time.time()
+       compiled = circuit.compile(optimization_level=level)
+       duration = time.time() - start
+       
+       print(f"Level {level}:")
+       print(f"  Time: {duration:.3f}s")
+       print(f"  Depth: {compiled.depth()}")
+       print(f"  Gates: {compiled.size()}")
+
+See Also
+========
+
+- :doc:`/user_guide/compiler/index` - Compiler User Guide
+- :doc:`/api/core/index` - Core API
+- :doc:`/api/devices/index` - Devices API
+- :doc:`/examples/basic_examples` - Compilation Examples
+- :doc:`/api/core/index` - Core API
+- :doc:`/api/devices/index` - Devices API
 - :doc:`/examples/basic_examples` - Compilation Examples

docs/source/user_guide/compiler/index.rst

@@ -68,16 +68,17 @@ Usage Examples
 
    import tyxonq as tq
    
-   circuit = tq.Circuit(2).h(0).cnot(0, 1)
+   circuit = tq.Circuit(2).h(0).cx(0, 1)
    
-   # Use default compiler
+   # Use default compiler (Circuit.compile() 返回 self)
    compiled = circuit.compile()
+   print(f"Compiled source: {compiled._compiled_source}")
    
    # Specify compiler engine
-   compiled_qiskit = circuit.compile(compile_engine='qiskit')
+   compiled = circuit.compile(compile_engine='qiskit')
    
    # Set optimization level
-   compiled_opt = circuit.compile(
+   compiled = circuit.compile(
        compile_engine='native',
        options={'optimization_level': 2}
    )
@@ -99,15 +100,18 @@ Decomposition Stage
 
    # RX gate decomposition: RX(θ) = H · RZ(θ) · H
    circuit = tq.Circuit(1).rx(0, 0.5)
-   decomposed = circuit.compile()
+   compiled = circuit.compile()  # 返回 Circuit 对象
+   decomposed_ir = compiled
    
    # RY gate decomposition: RY(θ) = S† · H · RZ(θ) · H · S
    circuit = tq.Circuit(1).ry(0, 0.5)
-   decomposed = circuit.compile()
+   compiled = circuit.compile()  # 返回 Circuit 对象
+   decomposed_ir = compiled
    
    # RZZ gate decomposition: RZZ(θ) = CNOT · RZ(θ) · CNOT
    circuit = tq.Circuit(2).rzz(0, 1, 0.5)
-   decomposed = circuit.compile()
+   compiled = circuit.compile()  # 返回 Circuit 对象
+   decomposed_ir = compiled
 
 Rewriting Stage
 ---------------
@@ -169,12 +173,13 @@ The shot scheduler manages measurement allocation and execution planning:
    # Circuit with measurement grouping
    circuit = (
        tq.Circuit(3)
-       .h(0).cnot(0, 1).cnot(1, 2)
+       .h(0).cx(0, 1).cx(1, 2)
        .measure_z(0).measure_z(1).measure_z(2)
    )
    
    # Automatic scheduling during execution
    result = circuit.run(shots=1000)
+   # result 是 list of unified results
 
 Gradient Processing Stage
 -------------------------

examples/circuit_compiler.py

@@ -23,15 +23,17 @@ def qiskit_compile_levels():
     compiled = []
     for lvl in levels:
         try:
-            # output='ir' uses native compiler by default; request qiskit artifacts explicitly below
-            cc = c.compile(
+            # compile() returns Circuit object with compiled_source stored in _compiled_source
+            compiled_circuit = c.compile(
                 compile_engine="default",
                 output="ir",
                 options={"optimization_level": lvl, "basis_gates": ["cx", "cz", "h", "rz"]},
             )
+            # Extract circuit IR object
+            cc = compiled_circuit
             compiled.append((lvl, cc))
         except Exception as e:
-            print(f"qiskit compile failed at level {lvl}: {e}")
+            print(f"compile failed at level {lvl}: {e}")
     for lvl, cc in compiled:
         # Directly use our Circuit.draw() which compiles to qiskit under the hood
         print(f"level {lvl} drawing:")
@@ -42,10 +44,13 @@ def main():
     qiskit_compile_levels()
     try:
         c = build_demo_circuit()
-        qasm = c.compile(compile_engine="qiskit", output="qasm2", options={"basis_gates": ["cx", "cz", "h", "rz"]})
+        # compile() returns Circuit object with compiled_source stored in _compiled_source
+        compiled_circuit = c.compile(compile_engine="qiskit", output="qasm2", options={"basis_gates": ["cx", "cz", "h", "rz"]})
+        # Extract compiled source (QASM2 string)
+        qasm = compiled_circuit._compiled_source
         print("qasm2 length:", len(qasm))
-    except Exception:
-        pass
+    except Exception as e:
+        print(f"Error: {e}")
 
 
 if __name__ == "__main__":

examples/pulse_cloud_submission_e2e.py

@@ -185,7 +185,8 @@ def example_mode_a_explicit_pulse_with_comparison():
         else:
             print(f"   ✅ 编译成功，无警告")
 
-    tqasm_code = result["circuit"]
+    # compiled_source 是 TQASM 字符串
+    tqasm_code = result["compiled_source"]
 
     print(f"\n   TQASM 代码长度: {len(tqasm_code)} 字符")
 
@@ -344,7 +345,8 @@ def example_mode_b_smart_inference():
             print(f"      2. 参数警告: 缺少 device_params → 自动补足默认值")
             print(f"         默认: qubit_freq=[5.0e9], anharmonicity=[-330e6]")
 
-    tqasm_code = result["circuit"]
+    # compiled_source 是 TQASM 字符串
+    tqasm_code = result["compiled_source"]
 
     print(f"\n   ✅ 智能推断成功!")
     print(f"   TQASM 代码长度: {len(tqasm_code)} 字符")

examples/pulse_gate_calibration.py

@@ -126,7 +126,8 @@ def example_2_virtual_z_gate():
     })
 
     result = compile(circuit_pulse, output="pulse_ir", options={"mode": "pulse_only"})
-    pulse_circuit = result["circuit"]
+    # compiled_source 是 pulse IR 对象
+    pulse_circuit = result["compiled_source"]
 
     # 分析脉冲序列
     print(f"\n脉冲序列分析:")
@@ -147,7 +148,8 @@ def example_2_virtual_z_gate():
 
     # 导出 TQASM 查看 Virtual-Z 实现
     tqasm_result = compile(circuit_pulse, output="tqasm", options={"mode": "pulse_only"})
-    tqasm_code = tqasm_result["circuit"]
+    # compiled_source 是 TQASM 字符串
+    tqasm_code = tqasm_result["compiled_source"]
 
     print(f"\n TQASM 中的 Virtual-Z 实现:")
     print(f"  (在 defcal 中表现为 shift_phase 指令)")
@@ -303,7 +305,8 @@ def example_5_gate_calibration_export():
 
     # 导出为 TQASM (包含优化后的 defcal)
     result = compile(circuit_pulse, output="tqasm", options={"mode": "pulse_only"})
-    tqasm_code = result["circuit"]
+    # compiled_source 是 TQASM 字符串
+    tqasm_code = result["compiled_source"]
 
     print(f"\n导出的 TQASM 校准文件:")
     print("=" * 70)

tests_core_module/test_pulse_compiler.py

@@ -38,14 +38,15 @@ def test_compile_single_x_gate(self):
         c.x(0)
 
         compiler = PulseCompiler()
-        pulse_circuit = compiler.compile(
+        result = compiler.compile(
             c,
             device_params={
                 "qubit_freq": [5.0e9],
                 "anharmonicity": [-330e6]
             },
             mode="pulse_only"
         )
+        pulse_circuit = result["circuit"]
 
         # Check that circuit has pulse operations
         assert pulse_circuit is not None
@@ -90,7 +91,8 @@ def test_hybrid_mode_preserves_gates(self):
         c.measure_z(1)
 
         compiler = PulseCompiler()
-        pulse_circuit = compiler.compile(c, mode="hybrid")
+        result = compiler.compile(c, mode="hybrid")
+        pulse_circuit = result["circuit"]
 
         # Check that measurement gates are preserved
         measure_ops = [op for op in pulse_circuit.ops 
@@ -189,14 +191,15 @@ def test_full_pipeline_with_multiple_gates(self):
         c.measure_z(1)
 
         compiler = PulseCompiler(optimization_level=2)
-        pulse_circuit = compiler.compile(
+        result = compiler.compile(
             c,
             device_params={
                 "qubit_freq": [5.0e9, 5.1e9],
                 "anharmonicity": [-330e6, -320e6]
             },
             mode="hybrid"
         )
+        pulse_circuit = result["circuit"]
 
         # Verify compilation succeeded
         assert pulse_circuit is not None
@@ -219,7 +222,8 @@ def test_pulse_compilation_with_device_params(self):
         }
 
         compiler = PulseCompiler()
-        pulse_circuit = compiler.compile(c, device_params=device_params)
+        result = compiler.compile(c, device_params=device_params)
+        pulse_circuit = result["circuit"]
 
         # Verify device params are stored in metadata
         assert pulse_circuit.metadata["pulse_device_params"] == device_params