ricci 0.0.1__tar.gz

ricci-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

ricci-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Ricci authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ricci-0.0.1/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.5
+Name: ricci
+Version: 0.0.1
+Summary: A shape-typed tensor language whose compiler emits NVIDIA PTX directly.
+Project-URL: Homepage, https://github.com/bsowlx/ricci
+Project-URL: Issues, https://github.com/bsowlx/ricci/issues
+Author: The Ricci authors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compiler,cuda,deep-learning,gpu,ptx,tensor,type-system
+Classifier: Development Status :: 1 - Planning
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Ricci
+
+**Ricci** is a tensor language where shape bugs are compile errors, gradients are a compiler pass, and GPU kernels are emitted straight as NVIDIA PTX, with no LLVM and no nvcc.
+
+It is named after Gregorio Ricci-Curbastro, who invented tensor calculus. Ricci programs end in `.ri`.
+
+```rust
+fn forward<B>(p: Params, x: f32[B, 784]) -> f32[B, 10] {
+    let h = relu(x @ p.w1 + p.b1);   // shapes are checked at compile time
+    h @ p.w2 + p.b2
+}
+```
+
+## Status
+
+Early development. This first release ships the CUDA driver runtime and one command:
+
+```
+pip install ricci
+ricci doctor
+```
+
+`ricci doctor` finds the NVIDIA driver and lists your GPUs. It reports which PTX versions the driver accepts, then JIT-compiles and runs a small PTX kernel to check that your machine can run Ricci's output. It needs only the NVIDIA driver, not the CUDA toolkit. On machines without an NVIDIA GPU it says so; Ricci will use a CPU reference backend there.
+
+The lexer, parser, shape checker, autodiff and PTX code generator are in progress at [github.com/bsowlx/ricci](https://github.com/bsowlx/ricci).

ricci-0.0.1/docs/pypi.md

@@ -0,0 +1,25 @@
+# Ricci
+
+**Ricci** is a tensor language where shape bugs are compile errors, gradients are a compiler pass, and GPU kernels are emitted straight as NVIDIA PTX, with no LLVM and no nvcc.
+
+It is named after Gregorio Ricci-Curbastro, who invented tensor calculus. Ricci programs end in `.ri`.
+
+```rust
+fn forward<B>(p: Params, x: f32[B, 784]) -> f32[B, 10] {
+    let h = relu(x @ p.w1 + p.b1);   // shapes are checked at compile time
+    h @ p.w2 + p.b2
+}
+```
+
+## Status
+
+Early development. This first release ships the CUDA driver runtime and one command:
+
+```
+pip install ricci
+ricci doctor
+```
+
+`ricci doctor` finds the NVIDIA driver and lists your GPUs. It reports which PTX versions the driver accepts, then JIT-compiles and runs a small PTX kernel to check that your machine can run Ricci's output. It needs only the NVIDIA driver, not the CUDA toolkit. On machines without an NVIDIA GPU it says so; Ricci will use a CPU reference backend there.
+
+The lexer, parser, shape checker, autodiff and PTX code generator are in progress at [github.com/bsowlx/ricci](https://github.com/bsowlx/ricci).

ricci-0.0.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ricci"
+version = "0.0.1"
+description = "A shape-typed tensor language whose compiler emits NVIDIA PTX directly."
+readme = "docs/pypi.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The Ricci authors" }]
+keywords = ["compiler", "tensor", "gpu", "cuda", "ptx", "deep-learning", "type-system"]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Environment :: GPU :: NVIDIA CUDA",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Compilers",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/bsowlx/ricci"
+Issues = "https://github.com/bsowlx/ricci/issues"
+
+[project.scripts]
+ricci = "ricci.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ricci"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ricci", "docs/pypi.md", "LICENSE", "pyproject.toml"]

ricci-0.0.1/src/ricci/__init__.py

@@ -0,0 +1,3 @@
+"""Ricci: a shape-typed tensor language whose compiler emits NVIDIA PTX directly."""
+
+__version__ = "0.0.1"

ricci-0.0.1/src/ricci/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from ricci.cli import main
+
+sys.exit(main())

ricci-0.0.1/src/ricci/cli.py

@@ -0,0 +1,29 @@
+"""Command-line entry point: `ricci <command>`."""
+
+from __future__ import annotations
+
+import argparse
+
+from ricci import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ricci",
+        description="Ricci: a shape-typed tensor language that compiles to NVIDIA PTX.",
+    )
+    parser.add_argument("--version", action="version", version=f"ricci {__version__}")
+    commands = parser.add_subparsers(dest="command", metavar="<command>")
+    commands.add_parser(
+        "doctor",
+        help="check the NVIDIA driver and GPU, then run a PTX smoke test",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "doctor":
+        from ricci.doctor import run
+
+        return run()
+
+    parser.print_help()
+    return 0

ricci-0.0.1/src/ricci/doctor.py

@@ -0,0 +1,129 @@
+"""`ricci doctor`: can this machine run the PTX that Ricci generates?
+
+1. Find the NVIDIA driver and list GPUs.
+2. Ask the driver's JIT which PTX ISA versions it accepts for this GPU.
+3. Load a hand-written vector-add kernel, run it on 16M floats, check the
+   result and report the achieved memory bandwidth.
+"""
+
+from __future__ import annotations
+
+import array
+import ctypes
+import random
+import sys
+
+from ricci import __version__
+from ricci.runtime.cuda import CudaError, Driver, DriverNotFound, PtxError
+
+# PTX ISA versions to probe, oldest first. 7.8 is the first with sm_89 (RTX 40);
+# 8.7 is the first with sm_120 (RTX 50).
+PTX_VERSIONS = ["7.8", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5", "8.6", "8.7", "8.8", "9.0", "9.1", "9.2"]
+
+# c[i] = a[i] + b[i] for i < n. Written by hand; Ricci's code generator will emit
+# kernels of exactly this shape.
+VADD_PTX = """\
+.version {version}
+.target {target}
+.address_size 64
+
+.visible .entry vadd(.param .u64 pa, .param .u64 pb, .param .u64 pc, .param .u32 pn)
+{{
+    .reg .pred  %p<2>;
+    .reg .b32   %r<6>;
+    .reg .f32   %f<4>;
+    .reg .b64   %rd<8>;
+
+    ld.param.u64    %rd1, [pa];
+    ld.param.u64    %rd2, [pb];
+    ld.param.u64    %rd3, [pc];
+    ld.param.u32    %r1, [pn];
+    mov.u32         %r2, %ctaid.x;
+    mov.u32         %r3, %ntid.x;
+    mov.u32         %r4, %tid.x;
+    mad.lo.s32      %r5, %r2, %r3, %r4;      // i = blockIdx.x * blockDim.x + threadIdx.x
+    setp.ge.u32     %p1, %r5, %r1;
+    @%p1 bra        DONE;                    // threads past the end do nothing
+    mul.wide.u32    %rd4, %r5, 4;            // byte offset of element i
+    add.s64         %rd5, %rd1, %rd4;
+    add.s64         %rd6, %rd2, %rd4;
+    add.s64         %rd7, %rd3, %rd4;
+    ld.global.f32   %f1, [%rd5];
+    ld.global.f32   %f2, [%rd6];
+    add.f32         %f3, %f1, %f2;
+    st.global.f32   [%rd7], %f3;
+DONE:
+    ret;
+}}
+"""
+
+
+def _say(status: str, message: str) -> None:
+    print(f"  [{status:^4}] {message}")
+
+
+def run() -> int:
+    print(f"ricci {__version__} doctor (Python {sys.version.split()[0]}, {sys.platform})\n")
+
+    try:
+        driver = Driver()
+    except DriverNotFound as exc:
+        _say("info", str(exc))
+        _say("info", "Ricci will run programs on its CPU reference backend on this machine.")
+        return 0
+    except CudaError as exc:
+        _say("fail", f"the NVIDIA driver is present but could not start: {exc}")
+        return 1
+
+    major, minor = driver.version()
+    _say("ok", f"NVIDIA driver found, supports CUDA {major}.{minor}")
+    devices = driver.devices()
+    if not devices:
+        _say("fail", "the driver reports no GPUs")
+        return 1
+    for d in devices:
+        _say("ok", f"GPU {d.index}: {d.name}, {d.target}, {d.sm_count} SMs, {d.total_memory / 2**30:.1f} GiB")
+
+    gpu = devices[0]
+    ctx = driver.context(gpu.index)
+
+    accepted = []
+    for version in PTX_VERSIONS:
+        try:
+            ctx.load_ptx(VADD_PTX.format(version=version, target=gpu.target)).unload()
+            accepted.append(version)
+        except PtxError:
+            pass
+    if not accepted:
+        _say("fail", f"the driver accepted none of PTX ISA {PTX_VERSIONS[0]}..{PTX_VERSIONS[-1]} for {gpu.target}")
+        return 1
+    _say("ok", f"driver JIT accepts PTX ISA {accepted[0]} to {accepted[-1]} for {gpu.target}")
+
+    module = ctx.load_ptx(VADD_PTX.format(version=accepted[0], target=gpu.target))
+    kernel = module.function("vadd")
+    n = 1 << 24
+    nbytes = 4 * n
+    a = array.array("f", (float(i % 1000) for i in range(n)))
+    b = array.array("f", (float((7 * i) % 1000) for i in range(n)))
+    c = array.array("f", bytes(nbytes))
+    da, db, dc = ctx.alloc(nbytes), ctx.alloc(nbytes), ctx.alloc(nbytes)
+    try:
+        ctx.to_device(da, a.buffer_info()[0], nbytes)
+        ctx.to_device(db, b.buffer_info()[0], nbytes)
+        block = 256
+        args = [da, db, dc, ctypes.c_uint32(n)]
+        ms = ctx.time_ms(lambda: ctx.launch(kernel, ((n + block - 1) // block, 1, 1), (block, 1, 1), args))
+        ctx.to_host(c.buffer_info()[0], dc, nbytes)
+    finally:
+        for ptr in (da, db, dc):
+            ctx.free(ptr)
+        module.unload()
+
+    wrong = sum(1 for i in random.sample(range(n), 10_000) if c[i] != a[i] + b[i])
+    if wrong:
+        _say("fail", f"vector add gave {wrong} wrong values out of 10,000 checked")
+        return 1
+    gbps = 3 * nbytes / (ms / 1e3) / 1e9
+    _say("ok", f"PTX vector add on 16M floats: correct, {ms:.2f} ms, {gbps:.0f} GB/s")
+    print("\nThis machine can run Ricci's GPU backend.")
+    return 0

ricci-0.0.1/src/ricci/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtimes that execute compiled Ricci kernels."""

ricci-0.0.1/src/ricci/runtime/cuda.py

@@ -0,0 +1,236 @@
+"""A minimal binding to the CUDA *driver* API through ctypes.
+
+Ricci never needs the CUDA toolkit (nvcc, NVRTC) at run time. The compiler
+writes PTX text; the NVIDIA driver, which every machine with an NVIDIA GPU
+already has, JIT-compiles that PTX to machine code inside `cuModuleLoadDataEx`.
+
+Only the handful of driver calls Ricci uses are wrapped here: init, device
+queries, PTX loading, memory, kernel launch and event timing.
+
+Pitfall worth remembering: device pointers are 64-bit, so they must be passed
+as `c_uint64` / `c_void_p`, never as bare Python ints (ctypes would truncate
+them to 32 bits).
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+# CUdevice_attribute values from cuda.h
+_ATTR_MULTIPROCESSOR_COUNT = 16
+_ATTR_COMPUTE_CAPABILITY_MAJOR = 75
+_ATTR_COMPUTE_CAPABILITY_MINOR = 76
+
+# CUjit_option values from cuda.h
+_JIT_INFO_LOG_BUFFER = 3
+_JIT_INFO_LOG_BUFFER_SIZE_BYTES = 4
+_JIT_ERROR_LOG_BUFFER = 5
+_JIT_ERROR_LOG_BUFFER_SIZE_BYTES = 6
+
+_LOG_SIZE = 8192
+
+
+class CudaError(RuntimeError):
+    """A CUDA driver call returned an error code."""
+
+
+class DriverNotFound(CudaError):
+    """No NVIDIA driver library on this machine (e.g. macOS, or no NVIDIA GPU)."""
+
+
+class PtxError(CudaError):
+    """The driver's JIT rejected a PTX module; `log` holds ptxas's message."""
+
+    def __init__(self, message: str, log: str) -> None:
+        super().__init__(f"{message}\n{log}" if log else message)
+        self.log = log
+
+
+def _load_library() -> Any:
+    if sys.platform == "win32":
+        candidates, loader = ["nvcuda.dll"], getattr(ctypes, "WinDLL")
+    elif sys.platform.startswith("linux"):
+        candidates, loader = ["libcuda.so.1", "libcuda.so"], ctypes.CDLL
+    else:
+        raise DriverNotFound(f"CUDA is not available on {sys.platform}")
+    for name in candidates:
+        try:
+            return loader(name)
+        except OSError:
+            continue
+    raise DriverNotFound("no NVIDIA driver found (looked for " + ", ".join(candidates) + ")")
+
+
+@dataclass(frozen=True)
+class Device:
+    index: int
+    name: str
+    compute_capability: tuple[int, int]
+    sm_count: int
+    total_memory: int  # bytes
+
+    @property
+    def target(self) -> str:
+        """PTX target name, e.g. 'sm_89' for an RTX 40-series GPU."""
+        major, minor = self.compute_capability
+        return f"sm_{major}{minor}"
+
+
+class Driver:
+    """The process-wide CUDA driver. Create one, then ask it for a `Context`."""
+
+    def __init__(self) -> None:
+        self.lib = _load_library()
+        self.check(self.lib.cuInit(0), "cuInit")
+
+    def check(self, result: int, what: str) -> None:
+        if result != 0:
+            name = ctypes.c_char_p()
+            self.lib.cuGetErrorName(result, ctypes.byref(name))
+            label = name.value.decode() if name.value else f"error {result}"
+            raise CudaError(f"{what} failed: {label}")
+
+    def version(self) -> tuple[int, int]:
+        """Highest CUDA version the driver supports, e.g. (13, 0)."""
+        v = ctypes.c_int()
+        self.check(self.lib.cuDriverGetVersion(ctypes.byref(v)), "cuDriverGetVersion")
+        return v.value // 1000, (v.value % 1000) // 10
+
+    def devices(self) -> list[Device]:
+        count = ctypes.c_int()
+        self.check(self.lib.cuDeviceGetCount(ctypes.byref(count)), "cuDeviceGetCount")
+        return [self._device(i) for i in range(count.value)]
+
+    def _device(self, index: int) -> Device:
+        dev = ctypes.c_int()
+        self.check(self.lib.cuDeviceGet(ctypes.byref(dev), index), "cuDeviceGet")
+        name = ctypes.create_string_buffer(256)
+        self.check(self.lib.cuDeviceGetName(name, 256, dev), "cuDeviceGetName")
+
+        def attr(code: int) -> int:
+            out = ctypes.c_int()
+            self.check(self.lib.cuDeviceGetAttribute(ctypes.byref(out), code, dev), "cuDeviceGetAttribute")
+            return out.value
+
+        mem = ctypes.c_size_t()
+        self.check(self.lib.cuDeviceTotalMem_v2(ctypes.byref(mem), dev), "cuDeviceTotalMem")
+        return Device(
+            index=index,
+            name=name.value.decode(errors="replace"),
+            compute_capability=(attr(_ATTR_COMPUTE_CAPABILITY_MAJOR), attr(_ATTR_COMPUTE_CAPABILITY_MINOR)),
+            sm_count=attr(_ATTR_MULTIPROCESSOR_COUNT),
+            total_memory=mem.value,
+        )
+
+    def context(self, device_index: int = 0) -> Context:
+        return Context(self, device_index)
+
+
+class Module:
+    """A loaded PTX module; look kernels up by name."""
+
+    def __init__(self, ctx: Context, handle: ctypes.c_void_p) -> None:
+        self._ctx = ctx
+        self.handle = handle
+
+    def function(self, name: str) -> ctypes.c_void_p:
+        fn = ctypes.c_void_p()
+        self._ctx.driver.check(
+            self._ctx.lib.cuModuleGetFunction(ctypes.byref(fn), self.handle, name.encode()),
+            f"cuModuleGetFunction({name})",
+        )
+        return fn
+
+    def unload(self) -> None:
+        self._ctx.lib.cuModuleUnload(self.handle)
+
+
+class Context:
+    """A CUDA context on one device: memory, modules, launches and timing."""
+
+    def __init__(self, driver: Driver, device_index: int) -> None:
+        self.driver = driver
+        self.lib = driver.lib
+        dev = ctypes.c_int()
+        driver.check(self.lib.cuDeviceGet(ctypes.byref(dev), device_index), "cuDeviceGet")
+        self.handle = ctypes.c_void_p()
+        driver.check(self.lib.cuDevicePrimaryCtxRetain(ctypes.byref(self.handle), dev), "cuDevicePrimaryCtxRetain")
+        driver.check(self.lib.cuCtxSetCurrent(self.handle), "cuCtxSetCurrent")
+
+    # -- modules -----------------------------------------------------------------
+
+    def load_ptx(self, ptx: str) -> Module:
+        """JIT-compile PTX text with the driver's built-in ptxas."""
+        error_log = ctypes.create_string_buffer(_LOG_SIZE)
+        info_log = ctypes.create_string_buffer(_LOG_SIZE)
+        options = (ctypes.c_int * 4)(
+            _JIT_ERROR_LOG_BUFFER, _JIT_ERROR_LOG_BUFFER_SIZE_BYTES,
+            _JIT_INFO_LOG_BUFFER, _JIT_INFO_LOG_BUFFER_SIZE_BYTES,
+        )
+        values = (ctypes.c_void_p * 4)(
+            ctypes.cast(error_log, ctypes.c_void_p), ctypes.c_void_p(_LOG_SIZE),
+            ctypes.cast(info_log, ctypes.c_void_p), ctypes.c_void_p(_LOG_SIZE),
+        )
+        handle = ctypes.c_void_p()
+        result = self.lib.cuModuleLoadDataEx(ctypes.byref(handle), ptx.encode() + b"\0", 4, options, values)
+        if result != 0:
+            raise PtxError(f"the driver rejected the PTX module (error {result})",
+                           error_log.value.decode(errors="replace").strip())
+        return Module(self, handle)
+
+    # -- memory --------------------------------------------------------------------
+
+    def alloc(self, nbytes: int) -> ctypes.c_uint64:
+        ptr = ctypes.c_uint64()
+        self.driver.check(self.lib.cuMemAlloc_v2(ctypes.byref(ptr), ctypes.c_size_t(nbytes)), "cuMemAlloc")
+        return ptr
+
+    def free(self, ptr: ctypes.c_uint64) -> None:
+        self.driver.check(self.lib.cuMemFree_v2(ptr), "cuMemFree")
+
+    def to_device(self, dst: ctypes.c_uint64, host_address: int, nbytes: int) -> None:
+        self.driver.check(
+            self.lib.cuMemcpyHtoD_v2(dst, ctypes.c_void_p(host_address), ctypes.c_size_t(nbytes)), "cuMemcpyHtoD")
+
+    def to_host(self, host_address: int, src: ctypes.c_uint64, nbytes: int) -> None:
+        self.driver.check(
+            self.lib.cuMemcpyDtoH_v2(ctypes.c_void_p(host_address), src, ctypes.c_size_t(nbytes)), "cuMemcpyDtoH")
+
+    # -- launch and timing -------------------------------------------------------------
+
+    def launch(self, fn: ctypes.c_void_p, grid: tuple[int, int, int], block: tuple[int, int, int],
+               args: list[Any], shared_bytes: int = 0) -> None:
+        """Launch a kernel. `args` are ctypes values (c_uint64 pointers, c_uint32, c_float...).
+
+        The driver wants an array of *pointers to* each argument, hence the byref casts.
+        """
+        params = (ctypes.c_void_p * len(args))(*(ctypes.cast(ctypes.byref(a), ctypes.c_void_p) for a in args))
+        self.driver.check(
+            self.lib.cuLaunchKernel(fn, *grid, *block, shared_bytes, None, params, None), "cuLaunchKernel")
+
+    def synchronize(self) -> None:
+        self.driver.check(self.lib.cuCtxSynchronize(), "cuCtxSynchronize")
+
+    def time_ms(self, body: Any, repeat: int = 20, warmup: int = 3) -> float:
+        """Median-free quick timing: average milliseconds per call of `body()` over `repeat` calls."""
+        for _ in range(warmup):
+            body()
+        self.synchronize()
+        start, stop = ctypes.c_void_p(), ctypes.c_void_p()
+        self.driver.check(self.lib.cuEventCreate(ctypes.byref(start), 0), "cuEventCreate")
+        self.driver.check(self.lib.cuEventCreate(ctypes.byref(stop), 0), "cuEventCreate")
+        try:
+            self.driver.check(self.lib.cuEventRecord(start, None), "cuEventRecord")
+            for _ in range(repeat):
+                body()
+            self.driver.check(self.lib.cuEventRecord(stop, None), "cuEventRecord")
+            self.driver.check(self.lib.cuEventSynchronize(stop), "cuEventSynchronize")
+            elapsed = ctypes.c_float()
+            self.driver.check(self.lib.cuEventElapsedTime(ctypes.byref(elapsed), start, stop), "cuEventElapsedTime")
+            return elapsed.value / repeat
+        finally:
+            self.lib.cuEventDestroy_v2(start)
+            self.lib.cuEventDestroy_v2(stop)