[Experimental Backline] Remote exec 2

doc/releases/changelog-dev.md

@@ -60,6 +60,10 @@
   argument is at an arbitrary position in the argument list.
   [(#2836)](https://github.com/PennyLaneAI/catalyst/pull/2836)
 
+* A new `catalyst.debug.compile_mlir` function has been added, allowing standalone MLIR files to be
+  compiled through the full Catalyst pipeline and returned as a callable Python object.
+  [(#2832)](https://github.com/PennyLaneAI/catalyst/pull/2832)
+
 * PPRs and PPMs can now be lowered properly into MLIR directly in the non-capture workflow.
   [(#2816)](https://github.com/PennyLaneAI/catalyst/pull/2816)
 
@@ -242,6 +246,10 @@
 
 <h3>Internal changes ⚙️</h3>
 
+* A new compiler pass `mark-entry-points` has been added, which annotates externally-callable
+  entry functions with the `catalyst.entry_point` attribute.
+  [(#2899)](https://github.com/PennyLaneAI/catalyst/pull/2899)
+
 * The `dim` argument of the `quantum.pcphase` operation has been changed to a static integer attribute
   (previously a dynamic float operand). This allows, among other things, the decomposition graph to
   distinguish pcphase gates with different `dim` values, since they need different decomposition rules.

frontend/catalyst/__init__.py

@@ -68,7 +68,7 @@
 sys.modules["mlir_quantum.ir"] = __import__("jaxlib.mlir.ir").mlir.ir
 sys.modules["mlir_quantum._mlir_libs"] = __import__("jaxlib.mlir._mlir_libs").mlir._mlir_libs
 
-from catalyst import debug, logging, passes
+from catalyst import debug, kernel, logging, passes
 from catalyst.api_extensions import *
 from catalyst.api_extensions import __all__ as _api_extension_list
 from catalyst.autograph import *
@@ -196,6 +196,7 @@
     "CompileOptions",
     "debug",
     "draw_graph",
+    "kernel",
     "passes",
     "pipeline",
     "compile_without_static_conditionals",

frontend/catalyst/api_extensions/__init__.py

@@ -40,6 +40,7 @@
     measure,
     pauli_measure,
 )
+from catalyst.api_extensions.target import target
 
 __all__ = (
     "accelerate",
@@ -60,4 +61,5 @@
     "pauli_measure",
     "adjoint",
     "ctrl",
+    "target",
 )

frontend/catalyst/api_extensions/target.py

@@ -0,0 +1,85 @@
+# Copyright 2026 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.
+
+"""Tag a PennyLane device as a separate cross-compilation target, optionally remote."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+_TARGET_ATTR = "_catalyst_target"
+_DISPATCH_ATTR = "_catalyst_dispatch"
+
+
+@dataclass(frozen=True)
+class Target:
+    """Cross-compilation target spec attached to a device by :func:`target`.
+
+    Args:
+        pipeline: Optional name of a lowering pipeline registered with the compiler.
+        triple: Optional LLVM target triple. Defaults to the host triple.
+    """
+
+    pipeline: Optional[str] = None
+    triple: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RemoteDispatch:
+    """Remote dispatch spec attached to a device by :func:`target` with an ``address``.
+
+    Args:
+        address: Executor address, e.g. ``"127.0.0.1:1373"``.
+    """
+
+    address: str
+
+
+def target(
+    device,
+    *,
+    pipeline: Optional[str] = None,
+    triple: Optional[str] = None,
+    address: Optional[str] = None,
+):
+    """Tag a PennyLane device as a separate cross-compilation target and return it.
+
+    Any QNode wrapping the returned device is kept as a separate compilation unit which carries
+    ``catalyst.target = {pipeline, triple}`` and is cross-compiled to a standalone object rather
+    than being inlined into the host module. With ``address`` set, the object is additionally
+    dispatched to a remote executor (``catalyst.dispatch = {address}``); without it, the object is
+    statically linked and runs in-process.
+
+    Args:
+        device: A PennyLane device.
+        pipeline: Optional lowering-pipeline name registered with the compiler.
+        triple: Optional LLVM target triple. Defaults to the host triple.
+        address: Optional executor address; when set, the target is dispatched remotely.
+
+    Returns:
+        The same device, now tagged with target (and, if ``address`` is given, dispatch) metadata.
+    """
+    setattr(device, _TARGET_ATTR, Target(pipeline=pipeline, triple=triple))
+    if address is not None:
+        setattr(device, _DISPATCH_ATTR, RemoteDispatch(address=address))
+    return device
+
+
+def get_target(device) -> Optional[Target]:
+    """Return the :class:`Target` attached via :func:`target`, or ``None``."""
+    return getattr(device, _TARGET_ATTR, None)
+
+
+def get_dispatch(device) -> Optional[RemoteDispatch]:
+    """Return the :class:`RemoteDispatch` attached via :func:`target` (``address=...``), or ``None``."""
+    return getattr(device, _DISPATCH_ATTR, None)

frontend/catalyst/compiled_functions.py

@@ -109,15 +109,11 @@ def load_symbols(self):
         return function, setup, teardown, mem_transfer
 
     def __enter__(self):
-        params_to_setup = [b"jitted-function"]
-        argc = len(params_to_setup)
-        array_of_char_ptrs = (ctypes.c_char_p * len(params_to_setup))()
-        array_of_char_ptrs[:] = params_to_setup
-        self.setup(ctypes.c_int(argc), array_of_char_ptrs)
+        wrapper.invoke_setup(self.setup, ["jitted-function"])
         return self
 
     def __exit__(self, _type, _value, _traceback):
-        self.teardown()
+        wrapper.invoke_teardown(self.teardown)
 
 
 class CompiledFunction:

frontend/catalyst/compiler.py

@@ -176,11 +176,23 @@
             "-lrt_decoder",
         ]
 
+        rt_remote_so = "librt_remote" + file_extension
+        if os.path.isfile(os.path.join(rt_lib_path, rt_remote_so)):
+            default_flags.append("-lrt_remote")
+
         # If OQD runtime capi is built, link to it as well
         # TODO: This is not ideal and should be replaced when the compiler is device aware
         if os.path.isfile(os.path.join(rt_lib_path, "librt_OQD_capi" + file_extension)):
             default_flags.append("-lrt_OQD_capi")
 
+        for artifact_path in options.runtime_artifacts:
+            dir_name = os.path.dirname(artifact_path)
+            default_flags += [
+                f"-Wl,-rpath,{dir_name}",
+                f"-L{dir_name}",
+                artifact_path,
+            ]
+
         return default_flags
 
     @staticmethod
@@ -210,9 +222,9 @@
                 yield compiler
 
     @staticmethod
-    def _attempt_link(compiler, flags, infile, outfile, options):
+    def _attempt_link(compiler, flags, infile, outfile, options, extra_objects=None):
         try:
-            command = [compiler] + flags + [infile, "-o", outfile]
+            command = [compiler] + flags + [infile] + list(extra_objects or []) + ["-o", outfile]
             run_writing_command(command, options)
             return True
         except subprocess.CalledProcessError as e:
@@ -239,7 +251,9 @@
 
     @staticmethod
     @debug_logger
-    def run(infile, outfile=None, flags=None, fallback_compilers=None, options=None):
+    def run(
+        infile, outfile=None, flags=None, fallback_compilers=None, options=None, extra_objects=None
+    ):
         """
         Link the infile against the necessary libraries and produce the outfile.
 
@@ -249,6 +263,8 @@
             flags (Optional[List[str]]): flags to be passed down to the compiler
             fallback_compilers (Optional[List[str]]): name of executables to be looked for in PATH
             compile_options (Optional[CompileOptions]): generic compilation options.
+            extra_objects (Optional[List[str]]): additional object files to statically link
+                (e.g. locally cross-compiled catalyst.target kernels).
         Raises:
             EnvironmentError: The exception is raised when no compiler succeeded.
         """
@@ -261,7 +277,9 @@
         if fallback_compilers is None:
             fallback_compilers = LinkerDriver._default_fallback_compilers
         for compiler in LinkerDriver._available_compilers(fallback_compilers):
-            success = LinkerDriver._attempt_link(compiler, flags, infile, outfile, options)
+            success = LinkerDriver._attempt_link(
+                compiler, flags, infile, outfile, options, extra_objects
+            )
             if options.verbose:
                 print("Shared object linking successful", file=options.logfile)
             if success:
@@ -498,7 +516,16 @@
             out_IR = None
 
         if self.options.link:
-            output = LinkerDriver.run(output_object_name, options=self.options)
+            # Locally cross-compiled catalyst.target kernels are emitted as separate objects; the
+            # driver lists them in `{module}.objects` for the linker to statically include.
+            extra_objects = []
+            objects_manifest = os.path.join(str(workspace), f"{module_name}.objects")
+            if os.path.exists(objects_manifest):
+                with open(objects_manifest, "r", encoding="utf-8") as f:
+                    extra_objects = [line.strip() for line in f if line.strip()]
+            output = LinkerDriver.run(
+                output_object_name, options=self.options, extra_objects=extra_objects
+            )
             output = str(pathlib.Path(output).absolute())
         else:
             output = None
@@ -706,41 +733,26 @@
         Returns
             (Optional[str]): output IR
         """
-        file_content = None
-        for dirpath, _, filenames in os.walk(str(workspace)):
-            filenames = [f for f in filenames if f.endswith(".mlir") or f.endswith(".ll")]
-            if not filenames:
-                break
-            filenames_no_ext = [os.path.splitext(f)[0] for f in filenames]
-            if pipeline == "mlir":
-                # Sort files and pick the first one
-                selected_file = [
-                    sorted(filenames)[0],
-                ]
-            elif pipeline == "last":
-                # Sort files and pick the last one
-                selected_file = [
-                    sorted(filenames)[-1],
-                ]
-            else:
-                selected_file = [
-                    f
-                    for f, name_no_ext in zip(filenames, filenames_no_ext)
-                    if pipeline in name_no_ext
-                ]
-            if len(selected_file) != 1:
-                msg = f"Attempting to get output for pipeline: {pipeline},"
-                msg += " but no or more than one file was found.\n"
-                raise CompileError(msg)
-            filename = selected_file[0]
-
-            full_path = os.path.join(dirpath, filename)
-            with open(full_path, "r", encoding="utf-8") as file:
-                file_content = file.read()
-
-        if file_content is None:
+        workspace = str(workspace)
+        filenames = [f for f in os.listdir(workspace) if f.endswith(".mlir") or f.endswith(".ll")]
+        if not filenames:
             msg = f"Attempting to get output for pipeline: {pipeline},"
             msg += " but no file was found.\n"
             msg += "Are you sure the file exists?"
             raise CompileError(msg)
-        return file_content
+
+        if pipeline == "mlir":
+            # Sort files and pick the first one
+            selected_file = [sorted(filenames)[0]]
+        elif pipeline == "last":
+            # Sort files and pick the last one
+            selected_file = [sorted(filenames)[-1]]
+        else:
+            selected_file = [f for f in filenames if pipeline in os.path.splitext(f)[0]]
+        if len(selected_file) != 1:
+            msg = f"Attempting to get output for pipeline: {pipeline},"
+            msg += " but no or more than one file was found.\n"
+            raise CompileError(msg)
+
+        with open(os.path.join(workspace, selected_file[0]), "r", encoding="utf-8") as file:
+            return file.read()

frontend/catalyst/debug/__init__.py

@@ -17,6 +17,7 @@
 from catalyst.debug.callback import callback
 from catalyst.debug.compiler_functions import (
     compile_executable,
+    compile_mlir,
     get_cmain,
     get_compilation_stage,
     get_compilation_stages_groups,
@@ -27,6 +28,7 @@
 
 __all__ = (
     "callback",
+    "compile_mlir",
     "print",
     "print_memref",
     "get_compilation_stage",