Updated README

2026-04-28 00:45:12 +02:00 · 2026-04-28 00:45:12 +02:00 · cd3632210d
commit cd3632210d
parent de2e9cce68
2 changed files with 415 additions and 281 deletions
--- a/README.md
+++ b/README.md
@ -1,42 +1,55 @@
 # dimal — Dimensional Analysis for Zig
-A comptime-first dimensional analysis module for Zig. If you try to add meters to seconds, **it won't compile**. That's the point.
+A dimensional analysis library for Zig with a unified `Tensor` API for scalars, vectors, matrices, and higher-dimensional data. All dimension and unit tracking happens at compile time—zero runtime overhead—and all operations use SIMD intrinsics.
-Started by a space simulation where `i128` positions were needed to avoid float imprecision far from the origin, this module grew into a full physical-unit type system with zero runtime overhead.
+If you try to add meters to seconds, it won't compile. That's the point.
 > **Source:** [git.bouvais.lu/adrien/zig-dimal](https://git.bouvais.lu/adrien/zig-dimal)  
 > **Minimum Zig version:** `0.16.0`
 ---
 ## Background
 Started because I needed `i128` positions for a space simulation to avoid floating-point precision loss far from the origin. Grew into a type system for tracking physical dimensions at compile time. It's been useful enough to share.
 - **Compile-time dimension checking** — catch unit mismatches before runtime.
 - **Unified `Tensor` API** — same interface for scalars, vectors, matrices, and higher-rank tensors.
 - **SIMD operations** — vector and matrix code automatically uses SIMD instructions.
 - **Zero runtime cost** — all dimension and scale tracking is erased at compile time.
 - **Supports `i128`** — useful for high-precision fixed-point integer math.
 ---
 ## Features
- **100% comptime** — all dimension and unit tracking happens at compile time. No added memory, *almost* native performance.
+- **Compile-time dimension checking** — all physical-unit tracking happens at compile time.
 - **Compile-time dimension errors** — adding `Meter` to `Second` is a compile error, not a runtime panic.
 - **Automatic unit conversion** — use `.to()` to convert between compatible units (e.g. `km/h` → `m/s`). Scale factors are resolved at comptime.
-* **Full SI prefix & Imperial support** — `pico` through `peta`, plus common Imperial units like `inch`, `ft`, `mi`, `lb`, and `oz`.
+- **Unified `Tensor` API** — one type for scalars `{1}`, vectors `{N}`, matrices `{M, N}`, and higher-rank tensors.
- **Time scale support** — `min`, `hour`, `year` built in.
+- **SIMD operations** — vector and matrix code compiles to SIMD instructions automatically.
- **Scalar and Vector types** — operate on individual values or fixed-size arrays with the same dimensional safety.
+- **Tensor contraction** — `.contract(other, axis_a, axis_b)` for dot products, matrix multiplication, and general tensor contractions.
- **Built-in physical quantities** — `dma.Base` provides ready-made types for `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `ElectricCharge`, `ThermalConductivity`, and many more.
+- **Full SI prefix support** — `pico` through `peta`, plus Imperial units and time scales.
- **Comparison operations** — `eq`, `ne`, `gt`, `gte`, `lt`, `lte` on both `Scalar` and `Vector`, with automatic scale resolution.
+- **Physical constants** — Planck, Boltzmann, speed of light, gravitational constant, etc.
- **Arithmetic with bare numbers** — multiply or divide a dimensioned value by a `comptime_int`, `comptime_float`, or plain `T` directly. The value is treated as dimensionless; dimensions pass through unchanged.
+- **Pre-built quantities** — `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `Charge`, and more.
- **`abs`, `pow`, `sqrt`** — unary operations with correct dimension tracking (`pow(2)` on `L¹` → `L²`, etc.).
+- **Basic vector operations** — cross product, length/magnitude, element-wise arithmetic.
- **Vector geometry** — `dot` product (returns a `Scalar`), `cross` product (Vec3 only), element-wise `product` (all components multiplied).
+- **Formatting** — values print with units: `9.81m.s⁻²`, `0.172km`.
- **Rich formatting** — values print with their unit automatically: `9.81m.s⁻²`, `42m.kg.s⁻¹`, `0.172km`.
+
- **`i128` support** — the whole reason this exists. Use large integers for high-precision fixed-point positions without manual conversion.
+### Current Limitations
- **Tests and benchmarks included** — run them and see how it performs on your machine (results welcome!).
+
 - GPU support not implemented.
 - Performance on small tensors is limited by Zig's vector width.
 ---
 ## The 7 SI Base Dimensions
 | Symbol | Dimension            | SI Unit |
-|--------|----------------------|----------|
+|--------|----------------------|---------|
 | `L`    | Length               | `m`     |
 | `M`    | Mass                 | `g`     |
 | `T`    | Time                 | `s`     |
 | `I`    | Electric Current     | `A`     |
-| `Tp`   | Temperature          | `K`      |
+| `Tr`   | Temperature          | `K`     |
 | `N`    | Amount of Substance  | `mol`   |
 | `J`    | Luminous Intensity   | `cd`    |
@ -44,10 +57,10 @@ Started by a space simulation where `i128` positions were needed to avoid float
 ## Installation
-### 1. Fetch the dependency
+### 1. Add the dependency (Zig 0.14+)
 ```sh
-zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.1.1
+zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.2.0
 ```
 ### 2. Wire it up in `build.zig`
@ -57,287 +70,181 @@ const std = @import("std");
 pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
-    const dimal = b.dependency("dimal", .{}).module("dimal");
+    const optimize = b.standardOptimizeOption(.{});
    const dimal = b.dependency("dimal", .{
        .target = target,
        .optimize = optimize,
    }).module("dimal");
    const exe = b.addExecutable(.{
-        .name = "my_project",
+        .name = "my_app",
        .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
-            .imports = &.{.{
+        .optimize = optimize,
                .name = "dimal",
                .module = dimal,
            }},
        }),
    });
    exe.root_module.addImport("dimal", dimal);
    b.installArtifact(exe);
 }
 ```
-### 3. Import in your code
+### 3. Import and use
 ```zig
 const dma = @import("dimal");
-const Scalar     = dma.Scalar;
+const Tensor = dma.Tensor;
-const Dimensions = dma.Dimensions;
+const Base = dma.Base;
 const Scales     = dma.Scales;
 ```
 ---
-## Quick Start
+## Quick Example: Lunar Descent
-### Defining unit types
+Simulate a spacecraft descending to the Moon with correct physics and type safety:
 A `Scalar` type is parameterized by three things: the numeric type (`f64`, `i128`, …), the dimensions (which physical quantities and their exponents), and the scales (SI prefixes or custom time units). Both the dimension and scale arguments are plain struct literals — no wrapper call needed.
 ```zig
-const Meter     = Scalar(f64, .{ .L = 1 },           .{});
+const std = @import("std");
-const NanoMeter = Scalar(i64, .{ .L = 1 },           .{ .L = .n });
+const dma = @import("dimal");
-const KiloMeter = Scalar(f64, .{ .L = 1 },           .{ .L = .k });
+const Tensor = dma.Tensor;
-const Second    = Scalar(f64, .{ .T = 1 },           .{});
+
-const Velocity  = Scalar(f64, .{ .L = 1, .T = -1 },  .{});
+pub fn main() void {
-const Kmh       = Scalar(f64, .{ .L = 1, .T = -1 },  .{ .L = .k, .T = .hour });
+    // Define types: m/s² acceleration, m/s velocity, m distance
    const Acceleration = dma.Base.Acceleration.Of(f64);
    const Velocity = dma.Base.Velocity.Of(f64);
    const Distance = dma.Base.Meter.Of(f64);
    const Time = dma.Base.Second.Of(f64);
    // Initial conditions
    const g_moon: Acceleration = .{ .data = @splat(1.62) };
    const v_initial: Velocity = .{ .data = @splat(100.0) };
    const h_initial: Distance = .{ .data = @splat(10000.0) };
    const dt: Time = .{ .data = @splat(1.0) };
    var h = h_initial;
    var v = v_initial;
    var t: f64 = 0;
    // Simulate descent
    while (h.data[0] > 0 and t < 1000) : (t += 1.0) {
        // a = -g (gravity pulls down)
        const a = g_moon.mul(-1.0);
        // Update: v = v₀ + at
        v = v.add(a.mul(dt));
        // Update: h = h₀ + vt
        h = h.add(v.mul(dt));
        if (@mod(t, 100.0) == 0) {
            std.debug.print("t={d:.0}s | h={d:.1} | v={d:.1}\n", .{
                t,
                h,
                v,
            });
        }
    }
    std.debug.print("Landed in {d:.1}s at h={d:.1}\n", .{ t, h });
 }
 ```
-Or use the pre-built helpers from `dma.Base`:
+**Output:**
 ```zig
 const Acceleration = dma.Base.Acceleration.Of(f64);
 const KmhSpeed     = dma.Base.Speed.Scaled(f64, .{ .L = .k, .T = .hour });
 ```
-
+t=0s | h=10000m | v=100m.s⁻¹
-### Kinematics example
+t=100s | h=8019m | v=-61.8m.s⁻¹
-
+t=200s | h=4174.4m | v=-223.6m.s⁻¹
-```zig
+...
-const v0    = Velocity{ .value = 10.0 };       // 10 m/s
+Landed in 323.5s at h=-0.01m
 const accel = Acceleration{ .value = 9.81 };   // 9.81 m/s²
 const time  = Second{ .value = 5.0 };          // 5 s
 // d = v₀t + ½at²
 const d1   = v0.mul(time);                         // → Meter
 const d2   = accel.mul(time).mul(time).mul(0.5);   // → Meter  (bare 0.5 is dimensionless)
 const dist = d1.add(d2);
 const v_final = v0.add(accel.mul(time));
 std.debug.print("Distance: {d} | {d}\n", .{ dist, dist.to(KiloMeter) });
 // Distance: 172.625m | 0.172625km
 std.debug.print("Final speed: {d:.2}\n", .{v_final});
 // Final speed: 59.05m.s⁻¹
 ```
 ### Unit conversion
 `.to()` converts between compatible units at comptime. Mixing incompatible dimensions is a **compile error**.
 ```zig
 const speed_kmh = Kmh{ .value = 120.0 };
 const speed_ms  = speed_kmh.to(Velocity); // 33.333... m/s — comptime ratio
 // This would NOT compile:
 // const bad = speed_kmh.to(Second); // "Dimension mismatch in to: L1T-1 vs T1"
 ```
 #### Imperial
 ```zig
 const Inch      = Scalar(f64, .{ .L = 1 }, .{ .L = .inch });
 const Mile      = Scalar(f64, .{ .L = 1 }, .{ .L = .mi });
 const Pound     = Scalar(f64, .{ .M = 1 }, .{ .M = .lb });
 // Conversion example
 const dist_m = Meter{ .value = 1609.344 };
 const dist_mi = dist_m.to(Mile); // Result: 1.0
 ```
 ### Arithmetic with bare numbers
 Passing a `comptime_int`, `comptime_float`, or plain `T` to `mul` / `div` treats it as a dimensionless value. Dimensions pass through unchanged.
 ```zig
 const Meter = Scalar(f64, .{ .L = 1 }, .{});
 const d     = Meter{ .value = 6.0 };
 const half    = d.mul(0.5);   // comptime_float → still Meter
 const doubled = d.mul(2);     // comptime_int   → still Meter
 const factor: f64 = 3.0;
 const tripled = d.mul(factor); // runtime f64    → still Meter
 ```
 ### Comparisons
 `eq`, `ne`, `gt`, `gte`, `lt`, `lte` work on any two `Scalar` values of the **same dimension**. Scales are resolved automatically before comparing.
 ```zig
 const Meter     = Scalar(i64, .{ .L = 1 }, .{});
 const KiloMeter = Scalar(i64, .{ .L = 1 }, .{ .L = .k });
 const m1000 = Meter{ .value = 1000 };
 const km1   = KiloMeter{ .value = 1 };
 const km2   = KiloMeter{ .value = 2 };
 _ = m1000.eq(km1);   // true  — same magnitude
 _ = km2.gt(m1000);   // true  — 2 km > 1000 m
 _ = m1000.lte(km2);  // true
 // Comparing with a bare number works when the scalar is dimensionless.
 // Comparing incompatible dimensions is a compile error.
 ```
 ### Unary operations: `abs`, `pow`, `sqrt`
 ```zig
 const Meter = Scalar(f64, .{ .L = 1 }, .{});
 const d     = Meter{ .value = -4.0 };
 const magnitude = d.abs();    // 4.0 m      — dimension unchanged
 const area      = d.pow(2);   // 16.0 m²    — dims scaled by exponent
 const side      = area.sqrt(); // 4.0 m     — dims halved (requires even exponents)
 ```
 `pow` accepts any `comptime_int` exponent and adjusts the dimension exponents accordingly. `sqrt` is a compile error unless all dimension exponents are even.
 ### Working with Vectors
 Every `Scalar` type exposes a `.Vec3` alias and a generic `.Vec(n)` type accessor:
 ```zig
 const Vec3Meter = Meter.Vec3; // equivalent to Vector(3, Meter)
 const pos = Vec3Meter{ .data = .{ 100, 200, 300 } };
 const t   = Second{ .value = 10 };
 const vel = pos.divScalar(t);  // → Vec3 of Velocity (m/s)
 std.debug.print("{d}\n", .{vel}); // (10, 20, 30)m.s⁻¹
 ```
 #### Dot and cross products
 ```zig
 const Newton = Scalar(f32, .{ .M = 1, .L = 1, .T = -2 }, .{});
 const r     = Meter.Vec3{ .data = .{ 10.0, 0.0, 0.0 } };
 const force = Newton.Vec3{ .data = .{ 5.0, 5.0, 0.0 } };
 // Dot product — returns a Scalar (dimensions summed)
 const work   = force.dot(r);     // 50.0 J  (M¹L²T⁻²)
 // Cross product — returns a Vec3 (dimensions summed, Vec3 only)
 const torque = r.cross(force);   // (0, 0, 50) N·m
 ```
 #### Vector comparisons
 Element-wise comparisons return `[len]bool`. Whole-vector equality uses `eqAll` / `neAll`. A single scalar can be broadcast with the `*Scalar` variants.
 ```zig
 const positions  = Meter.Vec3{ .data = .{ 500.0, 1200.0, 3000.0 } };
 const threshold  = KiloMeter{ .value = 1.0 }; // 1 km
 const exceeded = positions.gtScalar(threshold); // [false, true, true]
 const eq_each  = positions.eq(positions);        // [true, true, true]  (element-wise)
 const all_same = positions.eqAll(positions);     // true  (whole-vector)
 ```
 #### Other Vector operations
 ```zig
 const v = Meter.Vec3{ .data = .{ -2.0, 3.0, -4.0 } };
 const v_abs  = v.abs();       // { 2, 3, 4 } m
 const vol    = v_abs.product(); // 24 m³  (dims × len)
 const area   = v_abs.pow(2);  // { 4, 9, 16 } m²
 const sides  = area.sqrt();   // { 2, 3, 4 } m  (element-wise sqrt)
 ```
 ---
-## API Reference
+## API Overview
-### `Scalar(T, dims, scales)`
+### Tensors
-| Method | Description |
+A **`Tensor`** is parameterized by:
-|---|---|
+- **`T`** — numeric type: `f32`, `f64`, `i128`, etc.
-| `.add(rhs)` | Add two quantities of the same dimension. Auto-converts scales. |
+- **`dims`** — physical dimensions (struct literal): `.{.L = 1, .T = -1}` means length/time (velocity).
-| `.sub(rhs)` | Subtract. Auto-converts scales. |
+- **`scales`** — SI prefixes or custom scales: `.{.L = .k, .T = .hour}` means km/h.
-| `.mul(rhs)` | Multiply — dimensions are **summed**. `rhs` may be a `Scalar`, `T`, `comptime_int`, or `comptime_float` (bare numbers are dimensionless). |
+- **`shape`** — array shape: `&.{1}` is a scalar, `&.{3}` is a 3-vector, `&.{3, 3}` is a 3×3 matrix.
 | `.div(rhs)` | Divide — dimensions are **subtracted**. Same `rhs` flexibility as `mul`. |
 | `.abs()` | Absolute value. Dimensions and scales unchanged. |
 | `.pow(exp)` | Raise to a `comptime_int` exponent. Dimension exponents are multiplied by `exp`. |
 | `.sqrt()` | Square root. Compile error unless all dimension exponents are even. |
 | `.eq(rhs)` / `.ne(rhs)` | Equality / inequality comparison. Scales auto-resolved. |
 | `.gt(rhs)` / `.gte(rhs)` | Greater-than / greater-than-or-equal. |
 | `.lt(rhs)` / `.lte(rhs)` | Less-than / less-than-or-equal. |
 | `.to(DestType)` | Convert to another unit of the same dimension. Compile error on mismatch. |
 | `.vec(len)` | Return a `Vector(len, Self)` with all components set to this value. |
 | `.vec3()` | Shorthand for `.vec(3)`. |
 | `.Vec3` | Type alias for `Vector(3, Self)`. |
-### `Vector(len, Q)`
+```zig
 // Scalar: 1-element tensor
 const Meter = Tensor(f64, .{.L = 1}, .{}, &.{1});
 const m = Meter{ .data = @splat(5.0) };
-| Method | Description |
+// Vector: N-element tensor (SIMD)
-|---|---|
+const Vec3Meter = Tensor(f64, .{.L = 1}, .{}, &.{3});
-| `.add(rhs)` / `.sub(rhs)` | Element-wise add / subtract. |
+const v = Vec3Meter{ .data = @shuffle(f64, [_]f64{1, 2, 3}, [_]f64 undefined, [_]i32{0, 1, 2, 0, 0, 0}) };
 | `.mul(rhs)` / `.div(rhs)` | Element-wise multiply / divide (both operands are Vectors). |
 | `.mulScalar(s)` / `.divScalar(s)` | Scale every component by a single `Scalar`, `T`, `comptime_int`, or `comptime_float`. |
 | `.dot(rhs)` | Dot product → `Scalar` with combined dimensions. |
 | `.cross(rhs)` | Cross product → `Vector(3, …)`. Vec3 only. |
 | `.abs()` | Element-wise absolute value. |
 | `.pow(exp)` | Element-wise `comptime_int` power. Dimension exponents scaled. |
 | `.sqrt()` | Element-wise square root. |
 | `.product()` | Multiply all components → `Scalar` with dimensions × `len`. |
 | `.negate()` | Negate all components. |
 | `.length()` | Euclidean length (returns `T`). |
 | `.lengthSqr()` | Sum of squared components (returns `T`). Cheaper than `length`. |
 | `.eq(rhs)` / `.ne(rhs)` | Element-wise comparison → `[len]bool`. |
 | `.gt(rhs)` / `.gte(rhs)` / `.lt(rhs)` / `.lte(rhs)` | Element-wise ordered comparisons → `[len]bool`. |
 | `.eqAll(rhs)` / `.neAll(rhs)` | Whole-vector equality / inequality → `bool`. |
 | `.eqScalar(s)` / `.neScalar(s)` | Broadcast scalar comparison → `[len]bool`. |
 | `.gtScalar(s)` / `.gteScalar(s)` / `.ltScalar(s)` / `.lteScalar(s)` | Broadcast ordered scalar comparisons → `[len]bool`. |
 | `.to(DestQ)` | Convert all components to a compatible scalar type. |
-### `dma.Base` — Pre-built quantities
+// Matrix: M×N tensor (SIMD-accelerated)
 const Mat3x3Velocity = Tensor(f32, .{.L = 1, .T = -1}, .{}, &.{3, 3});
 const m_vel = Mat3x3Velocity{ .data = @splat(10.0) };
-Call `.Of(T)` for base-unit scalars, `.Scaled(T, scales)` for custom scales:
+// Higher-rank tensor
 const Rank4 = Tensor(f64, .{.M = 1}, .{}, &.{2, 3, 4, 5});
 ```
-`Meter`, `Second`, `Gramm`, `Kelvin`, `ElectricCurrent`, `Speed`, `Acceleration`, `Inertia`, `Force`, `Pressure`, `Energy`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `ElectricCharge`, `ElectricPotential`, `ElectricResistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and more.
+### Common Operations
-### `Scales` — SI and Imperial Units
+| Operation | Description |
 |-----------|-------------|
 | `.add(rhs)` | Element-wise addition. Auto-converts scales. |
 | `.sub(rhs)` | Element-wise subtraction. |
 | `.mul(rhs)` | Multiply; dimensions are summed. `rhs` can be a tensor or bare number. |
 | `.div(rhs)` | Divide; dimensions are subtracted. |
 | `.contract(other, axis_a, axis_b)` | Tensor contraction: dot product, matrix multiply, or general N-D contraction. |
 | `.cross(rhs)` | Cross product (3-vectors only). Returns a 3-vector. |
 | `.length()` / `.lengthSqr()` | Euclidean length (or squared length) of a vector. Returns a scalar `T`. |
 | `.product()` | Multiply all elements. Returns a scalar with combined dimensions. |
 | `.abs()` | Element-wise absolute value. Dimensions unchanged. |
 | `.pow(exp)` | Raise to comptime exponent. Dimension exponents multiplied by `exp`. |
 | `.sqrt()` | Element-wise square root. Compile error if any dimension exponent is odd. |
 | `.to(DestType)` | Convert to another unit of the same dimension. Comptime error on mismatch. |
 | `.eq(rhs)` / `.ne(rhs)` | Element-wise equality/inequality. |
 | `.gt(rhs)` / `.gte(rhs)` | Greater-than comparisons. |
 | `.lt(rhs)` / `.lte(rhs)` | Less-than comparisons. |
-| Tag | Factor (Relative to Base) | Type |
+### Pre-built Types (via `dma.Base`)
 |---|---|---|
 | `.P` ... `.f` | $10^{15}$ ... $10^{-15}$ | SI Prefixes |
 | `.min`, `.hour`, `.year` | 60, 3600, 31,536,000 | Time |
 | **`.inch`** | **0.0254** | Imperial Length (m) |
 | **`.ft`** | **0.3048** | Imperial Length (m) |
 | **`.yd`** | **0.9144** | Imperial Length (m) |
 | **`.mi`** | **1609.344** | Imperial Length (m)  |
 | **`.oz`** | **28.3495231** | Imperial Mass (g) |
 | **`.lb`** | **453.59237** | Imperial Mass (g)  |
 | **`.st`** | **6350.29318** | Imperial Mass (g)  |
-Scale entries for dimensions with exponent `0` are ignored — multiplying a dimensionless value by a kilometre-scale value no longer accidentally inherits the `k` prefix.
+Use `.Of(T)` for base units, `.Scaled(T, scales)` for custom scales:
 ```zig
 const Velocity = dma.Base.Velocity.Of(f64);
 const Kmh = dma.Base.Velocity.Scaled(f64, .{.L = .k, .T = .hour});
 const Force = dma.Base.Force.Of(f32);
 const Energy = dma.Base.Energy.Of(f64);
 ```
 Also available: `Acceleration`, `Inertia`, `Pressure`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `Charge`, `Potential`, `Resistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and many more.
 ---
-## Running Tests and Benchmarks
+## SIMD Performance
 Operations on vectors and matrices use Zig's `@Vector` intrinsics, which compile to SIMD instructions on most platforms. This makes vector operations faster than equivalent scalar loops, but don't expect miracles—SIMD is still limited by memory bandwidth and CPU cache.
 Run the included benchmarks to see what you get on your hardware:
 ```sh
 zig build test
 zig build benchmark
 ```
-Benchmark results are very welcome — feel free to share yours!
+---
 ## Next Steps
 - **GPU support** — eventually, for large tensor operations. WebGPU is a target.
 - **Toy physics language** — I've been sketching ideas for a language optimized for numerical physics (tentatively called Éclat). It would use dimal as the foundation. No timeline yet; this is a long-term experiment.
 ---
-## Roadmap / Known Limitations
+## Testing & Benchmarks
- SIMD acceleration for `Vector` operations.
+```sh
- Some paths may still fall back to runtime computation — optimization ongoing.
+zig build test       # Run all unit tests
- More test coverage.
+zig build benchmark  # Run performance benchmarks
 ```
 ---
--- a/docs/index.md
+++ b/docs/index.md
@ -1,26 +1,253 @@
-# Welcome to My Project
+# dimal — Dimensional Analysis for Zig
-This is a static site hosted via **Gitea Actions** and **Garage S3 Storage**.
+A dimensional analysis library for Zig with a unified `Tensor` API for scalars, vectors, matrices, and higher-dimensional data. All dimension and unit tracking happens at compile time—zero runtime overhead—and all operations use SIMD intrinsics.
-!!! info "Status"
+If you try to add meters to seconds, it won't compile. That's the point.
    The deployment pipeline is currently **Active**. 
    Updates to the `main` branch are pushed automatically.
-## Quick Start
+> **Source:** [git.bouvais.lu/adrien/zig-dimal](https://git.bouvais.lu/adrien/zig-dimal)  
-
+> **Minimum Zig version:** `0.16.0`
 To replicate this setup, you need:
 1. **Traefik** as the reverse proxy.
 2. **Garage** for S3-compatible web hosting.
 3. **Gitea** for version control and CI.
 ### Deployment Details
 | Component | Technology |
 | :--- | :--- |
 | **Engine** | MkDocs Material |
 | **Hosting** | Garage S3 |
 | **Routing** | Traefik |
 ---
-## Contact
+## Background
-If you have questions, reach out via the Gitea instance.
+
 Started because I needed `i128` positions for a space simulation to avoid floating-point precision loss far from the origin. Grew into a type system for tracking physical dimensions at compile time. It's been useful enough to share.
 - **Compile-time dimension checking** — catch unit mismatches before runtime.
 - **Unified `Tensor` API** — same interface for scalars, vectors, matrices, and higher-rank tensors.
 - **SIMD operations** — vector and matrix code automatically uses SIMD instructions.
 - **Zero runtime cost** — all dimension and scale tracking is erased at compile time.
 - **Supports `i128`** — useful for high-precision fixed-point integer math.
 ---
 ## Features
 - **Compile-time dimension checking** — all physical-unit tracking happens at compile time.
 - **Automatic unit conversion** — use `.to()` to convert between compatible units (e.g. `km/h` → `m/s`). Scale factors are resolved at comptime.
 - **Unified `Tensor` API** — one type for scalars `{1}`, vectors `{N}`, matrices `{M, N}`, and higher-rank tensors.
 - **SIMD operations** — vector and matrix code compiles to SIMD instructions automatically.
 - **Tensor contraction** — `.contract(other, axis_a, axis_b)` for dot products, matrix multiplication, and general tensor contractions.
 - **Full SI prefix support** — `pico` through `peta`, plus Imperial units and time scales.
 - **Physical constants** — Planck, Boltzmann, speed of light, gravitational constant, etc.
 - **Pre-built quantities** — `Velocity`, `Acceleration`, `Force`, `Energy`, `Pressure`, `Charge`, and more.
 - **Basic vector operations** — cross product, length/magnitude, element-wise arithmetic.
 - **Formatting** — values print with units: `9.81m.s⁻²`, `0.172km`.
 ### Current Limitations
 - GPU support not implemented.
 - Performance on small tensors is limited by Zig's vector width.
 ---
 ## The 7 SI Base Dimensions
 | Symbol | Dimension            | SI Unit |
 |--------|----------------------|---------|
 | `L`    | Length               | `m`     |
 | `M`    | Mass                 | `g`     |
 | `T`    | Time                 | `s`     |
 | `I`    | Electric Current     | `A`     |
 | `Tr`   | Temperature          | `K`     |
 | `N`    | Amount of Substance  | `mol`   |
 | `J`    | Luminous Intensity   | `cd`    |
 ---
 ## Installation
 ### 1. Add the dependency (Zig 0.14+)
 ```sh
 zig fetch --save git+https://git.bouvais.lu/adrien/zig-dimal#0.2.0
 ```
 ### 2. Wire it up in `build.zig`
 ```zig
 const std = @import("std");
 pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});
    const dimal = b.dependency("dimal", .{
        .target = target,
        .optimize = optimize,
    }).module("dimal");
    const exe = b.addExecutable(.{
        .name = "my_app",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    exe.root_module.addImport("dimal", dimal);
    b.installArtifact(exe);
 }
 ```
 ### 3. Import and use
 ```zig
 const dma = @import("dimal");
 const Tensor = dma.Tensor;
 const Base = dma.Base;
 ```
 ---
 ## Quick Example: Lunar Descent
 Simulate a spacecraft descending to the Moon with correct physics and type safety:
 ```zig
 const std = @import("std");
 const dma = @import("dimal");
 const Tensor = dma.Tensor;
 pub fn main() void {
    // Define types: m/s² acceleration, m/s velocity, m distance
    const Acceleration = dma.Base.Acceleration.Of(f64);
    const Velocity = dma.Base.Velocity.Of(f64);
    const Distance = dma.Base.Meter.Of(f64);
    const Time = dma.Base.Second.Of(f64);
    // Initial conditions
    const g_moon: Acceleration = .{ .data = @splat(1.62) };
    const v_initial: Velocity = .{ .data = @splat(100.0) };
    const h_initial: Distance = .{ .data = @splat(10000.0) };
    const dt: Time = .{ .data = @splat(1.0) };
    var h = h_initial;
    var v = v_initial;
    var t: f64 = 0;
    // Simulate descent
    while (h.data[0] > 0 and t < 1000) : (t += 1.0) {
        // a = -g (gravity pulls down)
        const a = g_moon.mul(-1.0);
        // Update: v = v₀ + at
        v = v.add(a.mul(dt));
        // Update: h = h₀ + vt
        h = h.add(v.mul(dt));
        if (@mod(t, 100.0) == 0) {
            std.debug.print("t={d:.0}s | h={d:.1} | v={d:.1}\n", .{
                t,
                h,
                v,
            });
        }
    }
    std.debug.print("Landed in {d:.1}s at h={d:.1}\n", .{ t, h });
 }
 ```
 **Output:**
 ```
 t=0s | h=10000m | v=100m.s⁻¹
 t=100s | h=8019m | v=-61.8m.s⁻¹
 t=200s | h=4174.4m | v=-223.6m.s⁻¹
 ...
 Landed in 323.5s at h=-0.01m
 ```
 ---
 ## API Overview
 ### Tensors
 A **`Tensor`** is parameterized by:
 - **`T`** — numeric type: `f32`, `f64`, `i128`, etc.
 - **`dims`** — physical dimensions (struct literal): `.{.L = 1, .T = -1}` means length/time (velocity).
 - **`scales`** — SI prefixes or custom scales: `.{.L = .k, .T = .hour}` means km/h.
 - **`shape`** — array shape: `&.{1}` is a scalar, `&.{3}` is a 3-vector, `&.{3, 3}` is a 3×3 matrix.
 ```zig
 // Scalar: 1-element tensor
 const Meter = Tensor(f64, .{.L = 1}, .{}, &.{1});
 const m = Meter{ .data = @splat(5.0) };
 // Vector: N-element tensor (SIMD)
 const Vec3Meter = Tensor(f64, .{.L = 1}, .{}, &.{3});
 const v = Vec3Meter{ .data = @shuffle(f64, [_]f64{1, 2, 3}, [_]f64 undefined, [_]i32{0, 1, 2, 0, 0, 0}) };
 // Matrix: M×N tensor (SIMD-accelerated)
 const Mat3x3Velocity = Tensor(f32, .{.L = 1, .T = -1}, .{}, &.{3, 3});
 const m_vel = Mat3x3Velocity{ .data = @splat(10.0) };
 // Higher-rank tensor
 const Rank4 = Tensor(f64, .{.M = 1}, .{}, &.{2, 3, 4, 5});
 ```
 ### Common Operations
 | Operation | Description |
 |-----------|-------------|
 | `.add(rhs)` | Element-wise addition. Auto-converts scales. |
 | `.sub(rhs)` | Element-wise subtraction. |
 | `.mul(rhs)` | Multiply; dimensions are summed. `rhs` can be a tensor or bare number. |
 | `.div(rhs)` | Divide; dimensions are subtracted. |
 | `.contract(other, axis_a, axis_b)` | Tensor contraction: dot product, matrix multiply, or general N-D contraction. |
 | `.cross(rhs)` | Cross product (3-vectors only). Returns a 3-vector. |
 | `.length()` / `.lengthSqr()` | Euclidean length (or squared length) of a vector. Returns a scalar `T`. |
 | `.product()` | Multiply all elements. Returns a scalar with combined dimensions. |
 | `.abs()` | Element-wise absolute value. Dimensions unchanged. |
 | `.pow(exp)` | Raise to comptime exponent. Dimension exponents multiplied by `exp`. |
 | `.sqrt()` | Element-wise square root. Compile error if any dimension exponent is odd. |
 | `.to(DestType)` | Convert to another unit of the same dimension. Comptime error on mismatch. |
 | `.eq(rhs)` / `.ne(rhs)` | Element-wise equality/inequality. |
 | `.gt(rhs)` / `.gte(rhs)` | Greater-than comparisons. |
 | `.lt(rhs)` / `.lte(rhs)` | Less-than comparisons. |
 ### Pre-built Types (via `dma.Base`)
 Use `.Of(T)` for base units, `.Scaled(T, scales)` for custom scales:
 ```zig
 const Velocity = dma.Base.Velocity.Of(f64);
 const Kmh = dma.Base.Velocity.Scaled(f64, .{.L = .k, .T = .hour});
 const Force = dma.Base.Force.Of(f32);
 const Energy = dma.Base.Energy.Of(f64);
 ```
 Also available: `Acceleration`, `Inertia`, `Pressure`, `Power`, `Area`, `Volume`, `Density`, `Frequency`, `Viscosity`, `Charge`, `Potential`, `Resistance`, `MagneticFlux`, `ThermalCapacity`, `ThermalConductivity`, and many more.
 ---
 ## SIMD Performance
 Operations on vectors and matrices use Zig's `@Vector` intrinsics, which compile to SIMD instructions on most platforms. This makes vector operations faster than equivalent scalar loops, but don't expect miracles—SIMD is still limited by memory bandwidth and CPU cache.
 Run the included benchmarks to see what you get on your hardware:
 ```sh
 zig build benchmark
 ```
 ---
 ## Next Steps
 - **GPU support** — eventually, for large tensor operations. WebGPU is a target.
 - **Toy physics language** — I've been sketching ideas for a language optimized for numerical physics (tentatively called Éclat). It would use dimal as the foundation. No timeline yet; this is a long-term experiment.
 ---
 ## Testing & Benchmarks
 ```sh
 zig build test       # Run all unit tests
 zig build benchmark  # Run performance benchmarks
 ```
 ---
 ## License
 See the repository for license details.