Add support for debugging PennyLane (Python) and Catalyst (C++) simultaneously

.vscode/launch.json

@@ -0,0 +1,28 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "(debugpy): Debug Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false 
+        },
+        {
+            "name": "(gdb): Attach To Python Process",
+            "type": "cppdbg",
+            "request": "attach",
+            "program": "${command:python.interpreterPath}",
+            "processId": "${command:pickProcess}",
+            "MIMode": "gdb",
+            "setupCommands": [
+                {
+                    "description": "Enable pretty-printing for gdb",
+                    "text": "-enable-pretty-printing",
+                    "ignoreFailures": true,
+				}
+            ]
+        }
+    ]
+}

frontend/catalyst/compiler.py

@@ -21,13 +21,15 @@
 import pathlib
 import platform
 import shutil
+import signal
 import subprocess
 import sys
 import tempfile
 import warnings
 from os import path
 from typing import List, Optional
 
+from catalyst.debug.debugger import is_debugger_active
 from catalyst.logging import debug_logger, debug_logger_init
 from catalyst.pipelines import CompileOptions
 from catalyst.utils.exceptions import CompileError
@@ -438,15 +440,31 @@ def run_from_ir(self, ir: str, module_name: str, workspace: Directory):
         output_ir_name = os.path.join(str(workspace), f"{module_name}.ll")
 
         cmd = self.get_cli_command(tmp_infile_name, output_ir_name, module_name, workspace)
+
         try:
             if self.options.verbose:
                 print(f"[SYSTEM] {' '.join(cmd)}", file=self.options.logfile)
-            result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+
+            with subprocess.Popen(
+                cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+            ) as p:
+                if p.returncode not in {0, None}:
+                    raise subprocess.CalledProcessError(p.returncode, cmd)
+
+                if self.options.debug_compiler and is_debugger_active():
+                    print(f"Compiler PID={p.pid}")
+                    print(
+                        f"""Ensure C++ debugger is attached and running before continuing with:
+                        kill -s SIGCONT {p.pid}"""
+                    )
+                    p.send_signal(signal.SIGSTOP)
+
+                res_stdout, res_stderr = p.communicate()
             if self.options.verbose or os.getenv("ENABLE_DIAGNOSTICS"):
-                if result.stdout:
-                    print(result.stdout.strip(), file=self.options.logfile)
-                if result.stderr:
-                    print(result.stderr.strip(), file=self.options.logfile)
+                if res_stdout:
+                    print(res_stdout.strip(), file=self.options.logfile)
+                if res_stderr:
+                    print(res_stderr.strip(), file=self.options.logfile)
         except subprocess.CalledProcessError as e:  # pragma: nocover
             raise CompileError(f"catalyst failed with error code {e.returncode}: {e.stderr}") from e
 

frontend/catalyst/debug/__init__.py

@@ -22,6 +22,7 @@
     get_compilation_stages_groups,
     replace_ir,
 )
+from catalyst.debug.debugger import is_debugger_active
 from catalyst.debug.instruments import instrumentation
 from catalyst.debug.printing import (  # pylint: disable=redefined-builtin
     print,
@@ -38,4 +39,5 @@
     "instrumentation",
     "replace_ir",
     "compile_executable",
+    "is_debugger_active",
 )

frontend/catalyst/debug/debugger.py

@@ -0,0 +1,26 @@
+# Copyright 2025 Xanadu Quantum Technologies Inc.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This module adds functionality to check if the active Python session
+is being run with an active debugger.
+"""
+
+
+import sys
+
+
+def is_debugger_active() -> bool:
+    """Will return true in active debugger session"""
+    return hasattr(sys, "gettrace") and sys.gettrace()

frontend/catalyst/jit.py

@@ -94,6 +94,7 @@ def qjit(
     circuit_transform_pipeline=None,
     pass_plugins=None,
     dialect_plugins=None,
+    debug_compiler=False
 ):  # pylint: disable=too-many-arguments,unused-argument
     """A just-in-time decorator for PennyLane and JAX programs using Catalyst.
 
@@ -161,6 +162,8 @@ def qjit(
             If not specified, the default pass pipeline will be applied.
         pass_plugins (Optional[List[Path]]): List of paths to pass plugins.
         dialect_plugins (Optional[List[Path]]): List of paths to dialect plugins.
+        debug_compiler (Optional[bool]): Enable external debugger attachment to the compiler
+            driver when launching from an active Python debugging environment.
 
     Returns:
         QJIT object.

frontend/catalyst/pipelines.py

@@ -74,6 +74,8 @@ class CompileOptions:
             Default is None.
         pass_plugins (Optional[Set[Path]]): List of paths to pass plugins.
         dialect_plugins (Optional[Set[Path]]): List of paths to dialect plugins.
+        debug_compiler (Optional[bool]): Enable external debugger attachment to the compiler
+            driver when launching from an active Python debugging environment.
     """
 
     verbose: Optional[bool] = False
@@ -94,6 +96,7 @@ class CompileOptions:
     circuit_transform_pipeline: Optional[dict[str, dict[str, str]]] = None
     pass_plugins: Optional[Set[Path]] = None
     dialect_plugins: Optional[Set[Path]] = None
+    debug_compiler: Optional[bool] = False
 
     def __post_init__(self):
         # Check that async runs must not be seeded