# tensor — n-dimensional arrays with SIMD kernels

Tensors are contiguous, row-major, CPU-resident arrays with typed elements.

## Construction

```rinne
@import = .{ std };
const t = @tensor(f32, [2, 3], .{ .device = .cpu, .fill = 1.5 });
```

- First argument: element dtype (`f32`, `f64`, `i32`, `i64`, `u8`, `bool`).
- Second: shape array (1..8 dimensions, positive).
- Optional options struct:
  - `.device = .cpu` (default). `.cuda` / `.rocm` are **not available in v1**
    and fail at runtime with a clear degrade error.
  - `.fill = value` — initialize every element (coerced to the dtype).

## Methods and indexing

| Method        | Returns / effect                                   |
|---------------|----------------------------------------------------|
| `t.shape()`   | array of dimension sizes                           |
| `t.numel()`   | total element count                                |
| `t.dtype()`   | dtype name string                                  |
| `t.fill(v)`   | overwrite every element with `v`                   |
| `t.data()`    | copy-out as a plain array                          |
| `t[i]`, `t[i] = v` | linear indexing (row-major order)            |
| `t.deinit()`  | free the tensor; idempotent, further use is an error |

```rinne
@import = .{ std };
const t = @tensor(f32, [6], .{ .device = .cpu, .fill = -1.5 });
std.print("{} {} {}\n", .{t.shape(), t.numel(), t.dtype()});
```

> **Note:** `defer t.deinit()` does **not** work in v1 — deferred blocks
> cannot see enclosing locals. Call `deinit()` explicitly before returning.

## apply_simd — element-wise kernels

Anonymous function literals are only allowed as the kernel of `apply_simd`.
The kernel runs once per element; the parameter annotation `@vector(N, T)` is
a lane-width hint for the future native backend (the VM interprets it
scalar-wise today; tails are padded automatically):

`apply_simd` transforms the tensor **in place** (the kernel's return value is
written back to each element) and returns nothing:

```rinne
@import = .{ std };
t.apply_simd(fn(x: @vector(8, f32)) f32 {
    if x < 0.0 { return 0.0; }
    return x;
});
// t now holds the ReLU'd values
```

## Native backend

The C11 codegen path (`rinne build`) rejects tensors, method calls, kernels,
and the ai/llm builtins with explicit errors — they are VM-only features.

## Runnable example

```rinne
@import = .{ std };

pub fn main() int {
    const t = @tensor(f32, [6], .{ .device = .cpu, .fill = -1.5 });
    t[1] = 2.0;
    t[3] = 4.25;
    t.apply_simd(fn(x: @vector(8, f32)) f32 {
        if x < 0.0 { return 0.0; }
        return x;
    });
    std.print("relu={}\n", .{t.data()});
    t.deinit();
    return 0;
}
```