hanajit 0.20.1__py3-none-any.whl

hanajit/__init__.py

@@ -0,0 +1,13 @@
+"""hanajit: an LLVM-backed JIT for Python with full-ecosystem fallback.
+
+Uses CPython's own parser (ast), compiles a numeric subset to native code
+via llvmlite/LLVM, and transparently falls back to the interpreter for
+everything else — so any Python library keeps working.
+"""
+from .decorator import jit, pmap
+from .backends.detect import detect
+prange = range
+from .errors import UnsupportedError
+
+__version__ = "0.20.1"
+__all__ = ["jit", "pmap", "prange", "detect", "UnsupportedError"]

hanajit/autopar.py

@@ -0,0 +1,50 @@
+"""Automatic parallelization: `@jit(parallel=True)` promotes the
+outermost eligible `for i in range(...)` loop to `prange`, so the user
+writes an ordinary Python loop and gets multithreaded execution — the
+ergonomic that Taichi gets from auto-parallel top-level `for`, but with
+no DSL and no new syntax.
+
+This is a pure AST rewrite: find the single top-level `for i in range(n)`
+loop, replace its iterator `range` with `prange`, and hand the result to
+the existing `parallel.make_parallel` machinery (chunked, GIL-released
+thread pool, reassociated reductions). If the function doesn't match the
+parallelizable shape, we raise UnsupportedError and the caller compiles it
+serially — auto-parallel never changes results, only scheduling.
+
+Eligibility is intentionally conservative and identical to what
+`parallel.analyze` already accepts: exactly one top-level range loop,
+simple pre-assignments, a body of loop-local assigns / array writes / at
+most one `acc +=` reduction, and a single return. Anything else stays
+serial.
+"""
+import ast
+import copy
+
+from .errors import UnsupportedError
+
+
+def rewrite_range_to_prange(fn_ast):
+    """Return a copy of fn_ast with the single top-level `range` loop's
+    iterator replaced by `prange`. Raise UnsupportedError if there isn't
+    exactly one eligible top-level range loop."""
+    tree = copy.deepcopy(fn_ast)
+    body = tree.body
+    range_loops = [
+        i for i, s in enumerate(body)
+        if isinstance(s, ast.For) and isinstance(s.iter, ast.Call)
+        and isinstance(s.iter.func, ast.Name)
+        and s.iter.func.id in ("range", "prange")
+    ]
+    if len(range_loops) != 1:
+        raise UnsupportedError(
+            "parallel=True needs exactly one top-level range loop")
+    loop = body[range_loops[0]]
+    if loop.iter.func.id == "range":
+        if len(loop.iter.args) not in (1, 2):
+            raise UnsupportedError(
+                "parallel loop must be range(n) or range(lo, hi) (no step)")
+        loop.iter.func = ast.copy_location(ast.Name(id="prange",
+                                                    ctx=ast.Load()),
+                                           loop.iter.func)
+    ast.fix_missing_locations(tree)
+    return tree

hanajit/backends/cpu.py

@@ -0,0 +1,193 @@
+"""CPU backend: LLVM MCJIT via llvmlite.binding, called through ctypes.
+
+Compatible with both legacy (<0.45) and new-pass-manager llvmlite APIs.
+"""
+import ctypes
+from llvmlite import binding as llvm
+from ..typeinfer import I64, F64, BOOL, PF64, PI64, AF64, AI64, ARRAY_ELEM
+
+_initialized = False
+_engines = []  # keep engines alive (they own the JITed code memory)
+
+CTYPES = {I64: ctypes.c_int64, F64: ctypes.c_double, BOOL: ctypes.c_bool,
+          PF64: ctypes.c_void_p, PI64: ctypes.c_void_p}
+
+
+def _proto(ret_type, arg_types):
+    from ..codegen import arr_meta_count
+    argt = []
+    for t in arg_types:
+        if t in ARRAY_ELEM:
+            argt += ([ctypes.c_void_p]
+                     + [ctypes.c_int64] * arr_meta_count(t))
+        else:
+            argt.append(CTYPES[t])
+    return ctypes.CFUNCTYPE(CTYPES[ret_type], *argt)
+
+
+def _init():
+    global _initialized
+    if _initialized:
+        return
+    for fn in ("initialize", "initialize_native_target",
+               "initialize_native_asmprinter"):
+        try:
+            getattr(llvm, fn)()
+        except (AttributeError, RuntimeError):
+            pass  # newer llvmlite auto-initializes
+    _initialized = True
+
+
+def _optimize(mod, tm, opt, tuning=None):
+    try:  # llvmlite >= 0.45: new pass manager
+        pto = llvm.create_pipeline_tuning_options(speed_level=opt)
+        for knob, val in (tuning or {}).items():
+            try:
+                setattr(pto, knob, val)
+            except (AttributeError, TypeError):
+                pass  # knob not in this llvmlite build
+        pb = llvm.create_pass_builder(tm, pto)
+        pb.getModulePassManager().run(mod, pb)
+    except AttributeError:
+        try:
+            pto = llvm.PipelineTuningOptions()
+            pto.speed_level = opt
+            pb = llvm.PassBuilder(tm, pto)
+            pb.getModulePassManager().run(mod, pb)
+        except Exception:
+            try:  # legacy pass manager
+                pmb = llvm.PassManagerBuilder()
+                pmb.opt_level = opt
+                pm = llvm.ModulePassManager()
+                pmb.populate(pm)
+                pm.run(mod)
+            except Exception:
+                pass  # run unoptimized rather than fail
+
+
+def _host_target_machine(opt):
+    target = llvm.Target.from_default_triple()
+    try:  # tune codegen for the actual host CPU (AVX etc.), like numba
+        return target.create_target_machine(
+            cpu=llvm.get_host_cpu_name(),
+            features=llvm.get_host_cpu_features().flatten(), opt=opt)
+    except Exception:
+        return target.create_target_machine(opt=opt)
+
+
+def load_cached(cached, func_name, arg_types):
+    """Rebuild callables from cached object code. Returns
+    (callable, kernel_addr, ret_type)."""
+    obj_bytes, meta = cached
+    _init()
+    from . import fastcall as fc
+    fc.register()  # CPython API symbols must resolve before linking
+    tm = _host_target_machine(3)
+    backing = llvm.parse_assembly("")
+    engine = llvm.create_mcjit_compiler(backing, tm)
+    engine.add_object_file(llvm.ObjectFileRef.from_data(obj_bytes))
+    engine.finalize_object()
+    _engines.append(engine)
+    ret_type = meta["ret"]
+    kernel_addr = engine.get_function_address(func_name)
+    if meta.get("wrapper"):
+        try:
+            waddr = engine.get_function_address(meta["wrapper"])
+            return fc.make_builtin(waddr, func_name), kernel_addr, ret_type
+        except Exception:
+            pass
+    return (_proto(ret_type, arg_types)(kernel_addr), kernel_addr,
+            ret_type)
+
+
+def compile_module(module, func_name, arg_types, ret_type, opt=3,
+                   fastcall=True, nogil=False, cache_key=None,
+                   tuning=None, tm_opt=None):
+    """Compile an llvmlite ir.Module.
+
+    Returns (callable, is_fastcall). With fastcall=True the callable is a
+    genuine CPython builtin (C-level dispatch); otherwise ctypes.
+    """
+    _init()
+    wrapper_name = None
+    if any(t in ARRAY_ELEM for t in arg_types):
+        fastcall = False   # arrays use the expanded ctypes ABI
+    if fastcall:
+        try:
+            from . import fastcall as fc
+            fc.register()
+            kernel = None
+            for f in module.functions:
+                if f.name == func_name:
+                    kernel = f
+                    break
+            wrapper_name = fc.add_fastcall_wrapper(
+                module, kernel, arg_types, ret_type, nogil=nogil)
+        except Exception:
+            wrapper_name = None
+    tm = _host_target_machine(tm_opt if tm_opt is not None else opt)
+    mod = llvm.parse_assembly(str(module))
+    mod.verify()
+    _optimize(mod, tm, opt, tuning=tuning)
+
+    engine = llvm.create_mcjit_compiler(mod, tm)
+    captured = {}
+    if cache_key is not None:
+        engine.set_object_cache(
+            notify_func=lambda m, buf: captured.setdefault("obj", buf))
+    engine.finalize_object()
+    _engines.append(engine)
+    if cache_key is not None and "obj" in captured:
+        from .. import cache as _cache
+        _cache.save(cache_key, captured["obj"],
+                    {"ret": ret_type, "args": list(arg_types),
+                     "wrapper": wrapper_name})
+
+    kernel_addr = engine.get_function_address(func_name)
+    if wrapper_name is not None:
+        try:
+            from . import fastcall as fc
+            waddr = engine.get_function_address(wrapper_name)
+            return fc.make_builtin(waddr, func_name), kernel_addr
+        except Exception:
+            pass
+    return _proto(ret_type, arg_types)(kernel_addr), kernel_addr
+
+
+def compile_raw(module, func_name, opt=3):
+    """Compile a module and return the raw address of one function."""
+    _init()
+    tm = _host_target_machine(opt)
+    mod = llvm.parse_assembly(str(module))
+    mod.verify()
+    _optimize(mod, tm, opt)
+    engine = llvm.create_mcjit_compiler(mod, tm)
+    engine.finalize_object()
+    _engines.append(engine)
+    return engine.get_function_address(func_name)
+
+
+def emit_assembly(module, opt=3):
+    """Return native assembly text for inspection."""
+    _init()
+    tm = _host_target_machine(opt)
+    mod = llvm.parse_assembly(str(module))
+    mod.verify()
+    return tm.emit_assembly(mod)
+
+
+def emit_cross(module, triple, cpu=""):
+    """Cross-compile a module's IR for another architecture (portability
+    check, e.g. arm64-apple-darwin for Apple Silicon)."""
+    _init()
+    try:
+        llvm.initialize_all_targets()
+        llvm.initialize_all_asmprinters()
+    except (AttributeError, RuntimeError):
+        pass
+    target = llvm.Target.from_triple(triple)
+    tm = target.create_target_machine(cpu=cpu)
+    ir_text = str(module)
+    mod = llvm.parse_assembly(ir_text)
+    _optimize(mod, tm, 3)
+    return tm.emit_assembly(mod)

hanajit/backends/detect.py

@@ -0,0 +1,73 @@
+"""Hardware auto-detection for @jit(target="auto").
+
+Probes for vendor runtimes by attempting to load their driver libraries
+(cheap, no initialization) plus platform checks. Results are cached for
+the process. Override everything with HANAJIT_TARGET=<cpu|cuda|amd|intel|metal>.
+"""
+import ctypes
+import functools
+import os
+import sys
+
+_PROBES = {
+    "cuda": {"linux": ["libcuda.so.1", "libcuda.so"],
+             "win32": ["nvcuda.dll"],
+             "darwin": []},          # NVIDIA is dead on modern macOS
+    "amd": {"linux": ["libamdhip64.so", "libhsa-runtime64.so.1"],
+            "win32": ["amdhip64.dll"],
+            "darwin": []},
+    "intel": {"linux": ["libze_loader.so.1", "libze_loader.so"],
+              "win32": ["ze_loader.dll"],
+              "darwin": []},
+}
+# preference order per platform ("best" = most mature backend first)
+_ORDER = {"darwin": ["metal"], "win32": ["cuda", "intel", "amd"],
+          "linux": ["cuda", "amd", "intel"]}
+
+
+def _platform():
+    if sys.platform == "darwin":
+        return "darwin"
+    if sys.platform.startswith("win"):
+        return "win32"
+    return "linux"
+
+
+def _loadable(names):
+    for n in names:
+        try:
+            ctypes.CDLL(n)
+            return n
+        except OSError:
+            continue
+    return None
+
+
+@functools.lru_cache(maxsize=1)
+def detect():
+    """Return ordered list of (target, evidence) for this machine.
+    Always ends with ("cpu", ...) — the only target hanajit executes on
+    directly today; GPU entries indicate device-code emission targets."""
+    plat = _platform()
+    found = []
+    forced = os.environ.get("HANAJIT_TARGET")
+    if forced:
+        return [(forced, "forced via HANAJIT_TARGET")]
+    if plat == "darwin":
+        found.append(("metal", "macOS (Metal is always present)"))
+    for vendor in _ORDER[plat]:
+        if vendor == "metal":
+            continue
+        lib = _loadable(_PROBES[vendor][plat])
+        if lib:
+            found.append((vendor, f"driver library {lib}"))
+    found.append(("cpu", "always available"))
+    return found
+
+
+def best_gpu():
+    """Best detected GPU target, or None if the machine has no GPU runtime."""
+    for target, _ in detect():
+        if target != "cpu":
+            return target
+    return None

hanajit/backends/fastcall.py

@@ -0,0 +1,146 @@
+"""C-level dispatch: JIT a CPython METH_FASTCALL wrapper in LLVM.
+
+Instead of calling native code through ctypes (~0.45us/call), we generate
+an LLVM function with the CPython fastcall ABI:
+
+    PyObject *wrapper(PyObject *self, PyObject *const *args, Py_ssize_t n)
+
+that unboxes arguments (PyLong_AsLongLong / PyFloat_AsDouble), calls the
+JITed kernel directly (same module -> inlinable), boxes the result, and is
+then installed as a genuine builtin via PyCFunction_NewEx. Call overhead
+drops to builtin-function level — the same trick Numba's C dispatcher uses.
+"""
+import ctypes
+from llvmlite import ir, binding as llvm
+from ..typeinfer import I64, F64, BOOL, PF64, PI64, POINTER_ELEM
+
+I8P = ir.IntType(8).as_pointer()
+I64T = ir.IntType(64)
+F64T = ir.DoubleType()
+
+_PYAPI = ["PyLong_AsLongLong", "PyFloat_AsDouble", "PyLong_FromLongLong",
+          "PyFloat_FromDouble", "PyBool_FromLong", "PyErr_Occurred",
+          "PyErr_SetString", "PyEval_SaveThread", "PyEval_RestoreThread"]
+_registered = False
+_keepalive = []
+
+
+def _register_symbols():
+    """Point MCJIT at the CPython API symbols in this process."""
+    global _registered
+    if _registered:
+        return
+    for name in _PYAPI:
+        addr = ctypes.cast(getattr(ctypes.pythonapi, name), ctypes.c_void_p).value
+        llvm.add_symbol(name, addr)
+    exc = ctypes.c_void_p.in_dll(ctypes.pythonapi, "PyExc_TypeError")
+    llvm.add_symbol("PyExc_TypeError", ctypes.addressof(exc))
+    _registered = True
+
+
+def _declare(module, name, ret, args):
+    for f in module.functions:
+        if f.name == name:
+            return f
+    return ir.Function(module, ir.FunctionType(ret, args), name=name)
+
+
+def add_fastcall_wrapper(module, kernel, arg_types, ret_type, nogil=False):
+    """Append a METH_FASTCALL wrapper for `kernel` to the module."""
+    wname = kernel.name + "__fastcall"
+    wty = ir.FunctionType(I8P, [I8P, I8P.as_pointer(), I64T])
+    w = ir.Function(module, wty, name=wname)
+    self_, argv, nargs = w.args
+
+    as_i64 = _declare(module, "PyLong_AsLongLong", I64T, [I8P])
+    as_f64 = _declare(module, "PyFloat_AsDouble", F64T, [I8P])
+    from_i64 = _declare(module, "PyLong_FromLongLong", I8P, [I64T])
+    from_f64 = _declare(module, "PyFloat_FromDouble", I8P, [F64T])
+    from_bool = _declare(module, "PyBool_FromLong", I8P, [I64T])
+    err_occ = _declare(module, "PyErr_Occurred", I8P, [])
+    err_set = _declare(module, "PyErr_SetString", ir.VoidType(), [I8P, I8P])
+    exc_type = ir.GlobalVariable(module, I8P, "PyExc_TypeError")
+
+    msg_text = f"{kernel.name}() takes {len(arg_types)} positional arguments\0"
+    msg = ir.GlobalVariable(module, ir.ArrayType(ir.IntType(8), len(msg_text)),
+                            name=wname + ".argmsg")
+    msg.global_constant = True
+    msg.initializer = ir.Constant(msg.type.pointee,
+                                  bytearray(msg_text.encode()))
+
+    entry = w.append_basic_block("entry")
+    bad = w.append_basic_block("badargs")
+    good = w.append_basic_block("unbox")
+    fail = w.append_basic_block("unboxfail")
+    ok = w.append_basic_block("call")
+    b = ir.IRBuilder(entry)
+
+    b.cbranch(b.icmp_signed("==", nargs, ir.Constant(I64T, len(arg_types))),
+              good, bad)
+
+    b.position_at_end(bad)
+    b.call(err_set, [b.load(exc_type), b.bitcast(msg, I8P)])
+    b.ret(ir.Constant(I8P, None))
+
+    b.position_at_end(good)
+    unboxed = []
+    for i, ty in enumerate(arg_types):
+        slot = b.load(b.gep(argv, [ir.Constant(I64T, i)]))
+        if ty == F64:
+            unboxed.append(b.call(as_f64, [slot]))
+        else:
+            v = b.call(as_i64, [slot])
+            if ty == BOOL:
+                v = b.icmp_signed("!=", v, ir.Constant(I64T, 0))
+            elif ty in POINTER_ELEM:  # address passed as int
+                from ..codegen import LLTY
+                v = b.inttoptr(v, LLTY[ty])
+            unboxed.append(v)
+    b.cbranch(b.icmp_unsigned("==", b.call(err_occ, []),
+                              ir.Constant(I8P, None)), ok, fail)
+
+    b.position_at_end(fail)
+    b.ret(ir.Constant(I8P, None))
+
+    b.position_at_end(ok)
+    if nogil:
+        save = _declare(module, "PyEval_SaveThread", I8P, [])
+        restore = _declare(module, "PyEval_RestoreThread", ir.VoidType(), [I8P])
+        tstate = b.call(save, [])       # release the GIL
+        res = b.call(kernel, unboxed)   # pure native compute, no CPython API
+        b.call(restore, [tstate])       # reacquire before boxing
+    else:
+        res = b.call(kernel, unboxed)
+    if ret_type == F64:
+        obj = b.call(from_f64, [res])
+    elif ret_type == BOOL:
+        obj = b.call(from_bool, [b.zext(res, I64T)])
+    else:
+        obj = b.call(from_i64, [res])
+    b.ret(obj)
+    return wname
+
+
+METH_FASTCALL = 0x0080
+
+
+class _PyMethodDef(ctypes.Structure):
+    _fields_ = [("ml_name", ctypes.c_char_p), ("ml_meth", ctypes.c_void_p),
+                ("ml_flags", ctypes.c_int), ("ml_doc", ctypes.c_char_p)]
+
+
+def make_builtin(wrapper_addr, name):
+    """Wrap a JITed fastcall address as a real CPython builtin function."""
+    _register_symbols()
+    nm = name.encode()
+    mdef = _PyMethodDef(nm, wrapper_addr, METH_FASTCALL, None)
+    _keepalive.append((nm, mdef))
+    new = ctypes.pythonapi.PyCFunction_NewEx
+    new.restype = ctypes.py_object
+    new.argtypes = [ctypes.POINTER(_PyMethodDef), ctypes.c_void_p,
+                    ctypes.c_void_p]
+    return new(ctypes.byref(mdef), None, None)
+
+
+def register():
+    _register_symbols()

hanajit/backends/fpga.py

@@ -0,0 +1,39 @@
+"""FPGA backend (experimental).
+
+There is no direct LLVM->bitstream path; FPGA flows go through
+High-Level Synthesis (HLS). Two practical routes from our IR:
+
+1. LLVM IR -> Vitis HLS: AMD/Xilinx Vitis HLS is itself LLVM-based and
+   accepts LLVM IR through its front-end flow (inject .ll into the
+   hls compilation, or use the open-source Vitis HLS LLVM fork).
+2. LLVM IR -> CIRCT: the LLVM CIRCT project (circt.llvm.org) lowers to
+   hardware dialects (Calyx/FIRRTL) and emits Verilog.
+
+v0.1 exports self-contained annotated IR plus a Vitis-ready C shim so
+either flow can pick it up. Iqbal-note: this pairs naturally with the
+existing FPGA acceleration work — the IR here is plain scalar compute,
+ideal for HLS pipelining pragmas.
+"""
+import textwrap
+
+
+def export_for_hls(module, func_name, path_prefix):
+    """Write <prefix>.ll and a Vitis HLS TCL stub. Returns file paths."""
+    ll_path = f"{path_prefix}.ll"
+    tcl_path = f"{path_prefix}_hls.tcl"
+    with open(ll_path, "w") as f:
+        f.write(str(module))
+    with open(tcl_path, "w") as f:
+        f.write(textwrap.dedent(f"""\
+            # Vitis HLS flow stub for {func_name}
+            open_project {func_name}_prj
+            set_top {func_name}
+            # Inject LLVM IR via the Vitis HLS LLVM front-end flow:
+            #   https://github.com/Xilinx/HLS
+            open_solution sol1
+            set_part xcu250-figd2104-2L-e
+            create_clock -period 3.3
+            csynth_design
+            export_design -format ip_catalog
+        """))
+    return ll_path, tcl_path

hanajit/backends/gpu.py

@@ -0,0 +1,126 @@
+"""Multi-vendor GPU backends (experimental): NVIDIA, AMD, Intel.
+
+All three retarget the same LLVM IR; only the triple, datalayout, and
+kernel calling convention differ:
+
+- NVIDIA: nvptx64 triple + nvvm.annotations  -> PTX text
+- AMD:    amdgcn-amd-amdhsa + amdgpu_kernel  -> GCN ISA / HSA code object
+          (runtime: ROCm/HIP)
+- Intel:  spirv64 + spir_kernel              -> SPIR-V
+          (runtime: Level Zero / oneAPI / OpenCL)
+
+v0.1 emits device code for inspection/offline use; host-side kernel
+launch bridges are on the roadmap.
+"""
+from llvmlite import binding as llvm
+
+TARGETS = {
+    "cuda":  dict(triple="nvptx64-nvidia-cuda",
+                  datalayout="e-i64:64-i128:128-v16:16-v32:32-n16:32:64",
+                  cpu="sm_75", callconv=None),  # Turing+: CUDA 11–13
+    "amd":   dict(triple="amdgcn-amd-amdhsa",
+                  datalayout=("e-p:64:64-p1:64:64-p2:32:32-p3:32:32-p4:64:64-"
+                              "p5:32:32-p6:32:32-i64:64-v16:16-v24:32-v32:32-"
+                              "v48:64-v96:128-v192:256-v256:256-v512:512-"
+                              "v1024:1024-v2048:2048-n32:64-S32-A5-G1-ni:7"),
+                  cpu="gfx90a", callconv="amdgpu_kernel"),
+    "intel": dict(triple="spirv64-unknown-unknown",
+                  datalayout="e-i64:64-v16:16-v24:32-v32:32-v48:64-v96:128-"
+                             "v192:256-v256:256-v512:512-v1024:1024-n8:16:32:64",
+                  cpu="", callconv="spir_kernel"),
+}
+
+_init_done = False
+
+
+import os as _os
+
+# AMDGPU HSA code-object version. v5 is the broadly-compatible default
+# (ROCm 5.x..current, LLVM 15..latest). v6 requires LLVM>=19 toolchains and
+# will fail to assemble on older ROCm. Override with the env var if needed.
+AMD_CODE_OBJECT_VERSION = int(
+    _os.environ.get("HANAJIT_AMD_CODE_OBJECT_VERSION", "5"))
+
+
+def _init():
+    global _init_done
+    if not _init_done:
+        try:
+            llvm.initialize_all_targets()
+            llvm.initialize_all_asmprinters()
+        except (AttributeError, RuntimeError):
+            pass
+        # pin AMDGPU code-object version for portable GCN output
+        try:
+            llvm.set_option("hanajit",
+                            "--amdhsa-code-object-version=%d"
+                            % AMD_CODE_OBJECT_VERSION)
+        except Exception:
+            pass
+        _init_done = True
+
+
+def retarget(module, kernel_name, vendor):
+    cfg = TARGETS[vendor]
+    module.triple = cfg["triple"]
+    module.data_layout = cfg["datalayout"]
+    ir_text = str(module)
+    if cfg["callconv"]:
+        ir_text = ir_text.replace(f'define {_rettype(ir_text, kernel_name)}',
+                                  f'define {cfg["callconv"]} '
+                                  f'{_rettype(ir_text, kernel_name)}', 1)
+    if vendor == "cuda":
+        ir_text += (f'\n!nvvm.annotations = !{{!0}}\n'
+                    f'!0 = !{{ptr @{kernel_name}, !"kernel", i32 1}}\n')
+    return ir_text
+
+
+def _rettype(ir_text, name):
+    # find `define <ty> @"name"` to splice the calling convention in front
+    for line in ir_text.splitlines():
+        if line.startswith("define") and f'@"{name}"' in line:
+            return line[len("define "):].split(f' @"{name}"')[0] + f' @"{name}"'
+    return ""
+
+
+# environment overrides so users retarget without editing source:
+#   HANAJIT_CUDA_ARCH=sm_90  HANAJIT_AMD_ARCH=gfx1100  HANAJIT_INTEL_ARCH=...
+import os as _os
+
+_ARCH_ENV = {"cuda": "HANAJIT_CUDA_ARCH", "amd": "HANAJIT_AMD_ARCH",
+             "intel": "HANAJIT_INTEL_ARCH"}
+
+
+def resolve_arch(vendor, cpu=None):
+    """Explicit arg > env var > portable table default."""
+    if cpu:
+        return cpu
+    env = _os.environ.get(_ARCH_ENV.get(vendor, ""))
+    if env:
+        return env
+    return TARGETS[vendor]["cpu"]
+
+
+def emit(module, kernel_name, vendor, cpu=None):
+    """Best-effort device-code emission. Returns (text, native: bool).
+
+    Architecture is resolved as: explicit `cpu=` > env var
+    (HANAJIT_CUDA_ARCH / HANAJIT_AMD_ARCH / HANAJIT_INTEL_ARCH) > a portable
+    default (CUDA sm_75 / AMD gfx90a). PTX and GCN are forward-compatible:
+    the driver re-JITs device code for a newer GPU at load time, so the
+    conservative default runs on the widest range of installed hardware."""
+    _init()
+    cfg = TARGETS[vendor]
+    arch = resolve_arch(vendor, cpu)
+    ir_text = retarget(module, kernel_name, vendor)
+    try:
+        target = llvm.Target.from_triple(cfg["triple"])
+        tm = target.create_target_machine(cpu=arch)
+        mod = llvm.parse_assembly(ir_text)
+        # mem2reg & friends: AMDGPU cannot select generic-addrspace allocas,
+        # and optimized IR yields cleaner PTX/GCN anyway
+        from .cpu import _optimize
+        _optimize(mod, tm, 3)
+        return tm.emit_assembly(mod), True
+    except Exception:
+        return ir_text, False  # annotated IR for offline llc/toolchain