# Roma4D User Guide — What This Language Is For **Roma4D** is a **compiled**, **native** programming language built around **four-dimensional geometric algebra** (**Cl(4,0)**), **structure-of-arrays (SoA) data**, and **explicit parallelism**—with a surface that reads like **Python** so ideas move fast from brain to binary. This guide is the **“why” and “what if”** story. For exact syntax, rules, and what compiles today, use the **[Roma4D Elite Reference Guide](Roma4D_Guide.md)**. --- ## Why bother with 4D in a programming language? Most code treats the world as lists of numbers and ad-hoc matrices. That works until you need **rotations that compose cleanly**, **planes and volumes** in the same algebra as **vectors**, or **massive parallel updates** over millions of entities without pointer soup. **4D here is not a gimmick.** It is a **mathematical workspace** where: - **Vectors** (`vec4`) carry position, direction, color, or any four-tuple you want to treat geometrically. - **Rotors** encode rotations in planes; they **multiply** like the physics of the real world expects. - **Multivectors** hold the full Clifford algebra—grades mixed intentionally—so you can express **fields**, **blades**, and **operators** in one type system instead of bolting quaternions, matrices, and tensors together by hand. Roma4D makes that algebra **first-class**: operators like **`*`**, **`^`**, and **`|`** mean geometric things, not “whatever overload C++ felt like today.” --- ## What Roma4D is *amazing* at (vision + reality) Below is a deliberately **wide** lens—applications that fit the **mental model** (columns, rotors, parallel sweeps, spacetime-shaped programs). Some demos exist in this repo today; others are **natural targets** as the toolchain and GPU path mature. When something is still **roadmap**, we say so. ### 1. Living universes — millions of entities, one coherent geometry Think **N-body–style** worlds, **particle galaxies**, **crowds**, **sensor swarms**, or **game entities** whose state is fundamentally “a bag of vectors that evolve under the same rules.” Roma4D wants you to store hot state as **`list[vec4]`** and **SoA fields**, then sweep them with **`par for`**. That is not just “faster loops”—it is an invitation to write **physics as geometry**: each step is **rotate**, **scale**, **add**, **project**, repeated at scale, with the compiler aiming at **SIMD** and (over time) **GPU-oriented** lowering for `spacetime:` regions. **Crazy-but-sane idea:** a **cosmic-scale** demo where ten million worldlines are not a stunt—they are a **stress test** that the language layout (SoA + par) was designed to survive. ### 2. “Spacetime-shaped” programs (compile-time narrative) Roma4D has **`t`**, **`expr @ t`**, and **`spacetime:`** blocks. Today they primarily drive **compile-time staging** and **MIR metadata**—they shape *how* the compiler thinks about regions, not a hidden interpreter loop in your release binary. **Why that still matters creatively:** you can **author** programs where *when* a quantity is meaningful is **written in the source**, not scattered across booleans and phase flags. As the pipeline grows, that becomes the backbone for **temporal optimization**, **GPU scheduling hints**, and **proof-like structure** in simulation code. **Outside-the-box:** treat **`spacetime:`** as a **director’s mark** in code—“this whole region is one physical scene transition”—even before every backend exploit is switched on. ### 3. Robotics, aerospace, and anything that rotates for a living Where traditional code chains **Euler angles** and prays, geometric algebra **composes rotors** without gimbal melodrama. Roma4D is a strong fit for: - **Joint chains** and **constraints** expressed as **planes and rotors**. - **Sensor fusion** where **frames** are **transforms**, not accidental 4×4 soup. - **Satellite / drone** attitude and **reference frames** as **first-class rotors**. If your bug sounds like “the rotation order is wrong on Tuesdays,” you are the target user. ### 4. Creative coding and “impossible” visuals **Projective `w` in `vec4`** is a classic graphics trick; here it sits inside an algebra that also knows **outer products** and **contractions**. That opens: - **Non-Euclidean** toy worlds (warped stepping, weird lights, “4D→2D” projections as experiments). - **Shader-like logic** experimented with in **native** code first, then ported once you like the math. - **Generative art** where **fields** are multivector-valued and **par** smears them across a grid. You are not stuck in “triangle API of the month”—you are sketching **geometry** and letting LLVM carry it. ### 5. Signal and field metaphors (Clifford-flavored DSP) Multivectors can represent **structured measurements**—not just audio samples, but **vector sensor arrays**, **polarized** quantities, **mixed-grade** decompositions. **`par for`** then becomes “update every probe the same way, deterministically.” **Wild-but-plausible:** compressive sensing, beamforming, or custom **geometric filters** where a **blade** is not a metaphor but a **typed value**. ### 6. Science at the boundary of geometry and data The repo includes **large, serious demos** (e.g. **cosmic genesis**, **collider**, **proteome**-themed experiments) that are valid Roma4D—not Python scripts pretending. That spirit is the point: **express huge structured models** in a language that **won’t silently dynamic-type you out of performance**. **Honest frontier:** bleeding-edge HPC and CUDA-backed execution are **roadmap**; today you get **native CPU** executables, **LLVM**, and **hooks** that record intent for what comes next. The **language** is not waiting—the **runtime story** is catching up. ### 7. Systems programmers who hate mystery allocations **Ownership 2.0** and **SoA linear access** mean: hot paths are **predictable**. You **move** values out of columns, **transform** them with geometric ops, **write back**. Parallel regions have **explicit** capture discipline. **Amazing consequence:** you can pitch Roma4D to people who love **Rust’s honesty** but need **rotors** in the type system—not in a side library. ### 8. Teaching “real math” that actually runs Because the surface looks like Python, you can **teach** **rotors**, **blades**, and **parallel sweeps** without students drowning in template errors first. Then **`r4d`** hands them a **binary**—confidence that the idea is not only notation. --- ## The emotional pitch (yes, really) **3D graphics** taught a generation to think in matrices. **ML** taught a generation to think in tensors with opaque autodiff. **Roma4D** invites you to think in **geometry that composes**—and to **compile** that thought into something **fast** and **inspectable**. If you have ever felt that “my simulation is correct but the math is spread across seventeen files,” this language is trying to **pull the truth back into one algebra**—and then **let the machine parallelize** the honest structure you wrote. --- ## What to run first | You want… | Start here | |-----------|------------| | Smallest working program | `examples/min_main.r4d` | | Hello geometry | `examples/hello_4d.r4d` | | Spacetime + `par` shape | `demos/spacetime_collider.r4d` | | Epic scale showcase | `demos/cosmic_genesis.r4d` | | Install toolchain | **[Install_Guide.md](Install_Guide.md)** (full) · root [INSTALL.md](../../INSTALL.md) (quick link) | --- ## Relationship to other docs | Document | Role | |----------|------| | **[Roma4D_Master_Guide.md](Roma4D_Master_Guide.md)** | **All guides in one file** (install → ship + full spec) | | **This User Guide** | Capabilities, vision, “what can I build?” | | **[Roma4D_Guide.md](Roma4D_Guide.md)** | Authoritative syntax, rules, LLM protocol, debugging | | **[README.md](README.md)** (this docs folder) | Hub: install, LLM, errors, shipping, dependencies | | **[../README.md](../README.md)** | Repo quick start, CLI table, layout | --- ## One-line summary **Roma4D lets you write native programs where four-dimensional geometric algebra, parallel columns, and spacetime-shaped structure are the main character—not an afterthought library.** Welcome to the workshop. Build something unreasonable.