---

Interactive Showcase: Real-Time 3D Raymarching

Enki unifies host and accelerator execution. The showcase below demonstrates a real-time procedural 3D raymarching with smooth lighting, ambient occlusion, and mouse-driven orbital camera controls—compiled just-in-time from a single Rust function running on a potato GPU:

Run the Demo:

git clone https://github.com/enkiruntime/enki_sdf.git
cd enki_sdf
cargo run

---

Quick Start

Add Enki and glam to your project:

cargo add enki-gpu glam

Replace src/main.rs with the following:

use enki::*;
use glam::Vec2;

const COUNT: usize = 5;

// Declare the compute kernel with #[nam]
#[nam]
fn scale_vectors(_space: &Space, input: &Vec2, output: &mut Vec2, factor: f32) {
    *output = *input * factor;
}

fn main() {
    // Initialize the headless GPU runtime
    let enki = Enki::init();

    // Allocate physical data directly in GPU VRAM
    let in_gpu = gpu_vec![
        Vec2::new(1.0, 2.0),
        Vec2::new(3.0, 4.0),
        Vec2::new(5.0, 6.0),
        Vec2::new(7.0, 8.0),
        Vec2::new(9.0, 10.0),
    ];
    let mut out_gpu = gpu_vec![Vec2::ZERO; COUNT];

    let factor = 2.5f32;

    // Record and dispatch directly to GPU silicon
    enki.flow(|_| {
        scale_vectors.run(
            &Space::gpu_x(COUNT),
            &in_gpu,
            &mut out_gpu,
            GpuParam::new(factor),
        );
    });

    // Dual Execution: Run the exact same function on CPU native rust
    let in_cpu = vec![
        Vec2::new(1.0, 2.0),
        Vec2::new(3.0, 4.0),
        Vec2::new(5.0, 6.0),
        Vec2::new(7.0, 8.0),
        Vec2::new(9.0, 10.0),
    ];
    let mut out_cpu = vec![Vec2::ZERO; COUNT];

    for i in 0..COUNT {
        scale_vectors(&Space::cpu_x(i, COUNT), &in_cpu[i], &mut out_cpu[i], factor);
    }

    // Verify bit-for-bit equivalence
    assert_eq!(&out_cpu[..], &out_gpu.to_vec()[..]);
    println!("GPU Results: {:?}", out_gpu.to_vec());
    println!("Execution verified: CPU and GPU outputs match identically!");
}

Run the application:

cargo run

Note: On your first build, Enki will prompt to automatically configure --emit=llvm-bc and optimization profiles in .cargo/config.toml. Alternatively, you can run non-intrusively using the official CLI runner via cargo install cargo-enki && cargo enki run.

---

Architectural Highlights

• Runs on Stable Rust: Operates on standard stable Rust (1.80+). No nightly compiler forks, custom toolchains, or experimental compiler plugins.
• Physical Memory Addressing: Built natively on Vulkan 1.3 and 64-bit Buffer Device Addresses (BDA). Eliminates descriptor pools, descriptor sets, and binding tables.
• Two-Tier Borrow Checking: Combines rustc's compile-time borrow checker on the host with a runtime BorrowEngine that intercepts spatial slice collisions, domain bound deficits, and temporal presentation hazards.
• Automated Synchronization (TTRD): An internal Transitive Reduction Dependency Solver constructs a directed hazard graph and derives the mathematically minimal set of Vulkan pipeline barriers (Synchronization2) automatically.
• Dual CPU/GPU Verification: Functions marked with #[nam] are standard Rust functions. They can be tested natively on host CPU threads using rayon and standard #[test] assertions without requiring physical GPU silicon in CI/CD pipelines.

---

Project Status & Pragmatic Safety

Enki is currently an alpha-stage project (v0.1). It represents an active systems research effort into unified language execution:

• Dynamic Invariant Checking: The BorrowEngine operates as a compiler-grade pragmatic safety net at the dispatch boundary. It detects concrete spatial and temporal data race hazards before hardware queue submission. It does not claim to provide formal mathematical soundness proofs for arbitrary parallel access patterns.
• Evolving Interfaces: Runtime APIs, compiler lowering passes, and internal data structures are subject to refinement as the system matures.

---

The Enki Book

For in-depth architectural breakdowns, memory layout analysis, and advanced graphics pipelines, read the official documentation:

--> Read The Enki Book

The book covers:

• The Mental Model: How Rust references map to physical 64-bit GPU virtual addresses.
• Memory & Resource System: Deep dives into GpuVec, zero-cost sub-slicing (Slice), by-value uniform packing (GpuParam), and on-chip scratchpad memory (GpuTileMem).
• Compiler Invariants: Understanding hardware constraints on GPU silicon (divergence, heap allocations, panics).
• The GPU BorrowEngine: Mechanics of spatial disjointness and temporal presentation lifecycles.
• Graphics & Presentation: Building real-time interactive display applications with GLFW and swapchains.

---

System Requirements

• Rust Toolchain: Stable Rust 1.80 or newer.
• Graphics Driver: Official GPU driver with Vulkan 1.3 support, including:
  • 64-bit Buffer Device Addresses (VK_KHR_buffer_device_address)
  • Timeline Semaphores (VK_KHR_timeline_semaphore)
  • Synchronization2 (VK_KHR_synchronization2)
  • 64-bit Shader Integers (shaderInt64)
• Supported Operating Systems: Linux (X11 / Wayland), Windows (10 / 11).

---

Licensing

Enki is structured with an open-core architecture:

• Enki Framework (enki-gpu, anu, apsu, utu, enki_macros): Fully open-source under MIT License or Apache License 2.0.
• Parsu GPU Compiler Backend (Pre-compiled Binary): Distributed under the Parsu License & Commercial Notice. It is free forever for developers, researchers, and open-source use. Commercial production usage will require commercial licensing in future releases.

---