diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 38a94f4..0000000 --- a/docs/index.md +++ /dev/null @@ -1,253 +0,0 @@ -# dimal — Dimensional Analysis for Zig - -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. - -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 - -- **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. diff --git a/docs/wishlist.md b/docs/wishlist.md deleted file mode 100644 index 5c848e4..0000000 --- a/docs/wishlist.md +++ /dev/null @@ -1,3 +0,0 @@ -## GPU support with WebGPU - -Example: https://github.com/seyhajin/webgpu-wasm-zig