# Magnetron Operator Reference

All operations in Magnetron are exposed as **methods on `Tensor`**.
If you are familiar with PyTorch, think `x.sin()` instead of `torch.sin(x)`.

---

## Tensor Creation & Initialization

| Method                   | Description                                                       | Math                        | Example                              |
|--------------------------|-------------------------------------------------------------------|-----------------------------|--------------------------------------|
| `Tensor.empty(shape)`    | Create an uninitialized tensor (contents undefined)               | N/A                         | `x = Tensor.empty(2, 3)`             |
| `Tensor.empty_like(x)`   | Create an uninitialized tensor with same shape and dtype as input | N/A                         | `y = Tensor.empty_like(x)`           |
| `Tensor.full(shape, v)`  | Create tensor filled with constant value                          | $x_i = v$                   | `x = Tensor.full((2,3), 1.0)`        |
| `Tensor.full_like(x, v)` | Create constant-filled tensor like input                          | $x_i = v$                   | `y = Tensor.full_like(x, 0)`         |
| `Tensor.zeros(shape)`    | Create tensor filled with zeros                                   | $x_i = 0$                   | `x = Tensor.zeros(2,3)`              |
| `Tensor.ones(shape)`     | Create tensor filled with ones                                    | $x_i = 1$                   | `x = Tensor.ones(4)`                 |
| `Tensor.arange(a,b,s)`   | Create evenly spaced values from start to stop                    | $a, a+s, \dots < b$         | `x = Tensor.arange(0, 10, 2)`        |
| `Tensor.rand_perm(n)`    | Random permutation of integers                                    | permutation of $\{0..n-1\}$ | `x = Tensor.rand_perm(10)`           |
| `Tensor.one_hot(c)`      | Convert indices to one-hot vectors                                | $y_{i,j}=[x_i=j]$           | `y = idx.one_hot(10)`                |
| `Tensor.load_image(p)`   | Load image file into tensor                                       | N/A                         | `img = Tensor.load_image("img.png")` |

---

## Filling & Mutation

| Method                 | Description                              | Math                          | Example                  |
|------------------------|------------------------------------------|-------------------------------|--------------------------|
| `fill_(v)`             | Fill tensor in-place with constant value | $x_i=v$                       | `x.fill_(0)`             |
| `zeros_()`             | In-place fill with zeros                 | $x_i=0$                       | `x.zeros_()`             |
| `ones_()`              | In-place fill with ones                  | $x_i=1$                       | `x.ones_()`              |
| `copy_(y)`             | Copy data from another tensor            | $x=y$                         | `x.copy_(y)`             |
| `masked_fill(mask,v)`  | Replace values where mask is true        | $x_i=v$ if $m_i$              | `y = x.masked_fill(m,0)` |
| `masked_fill_(mask,v)` | In-place masked fill                     | N/A                           | `x.masked_fill_(m,0)`    |
| `uniform_(a,b)`        | Fill with uniform random values          | $x\sim U(a,b)$                | `x.uniform_(0,1)`        |
| `normal_(μ,σ)`         | Fill with normal distribution            | $x\sim\mathcal N(\mu,\sigma)$ | `x.normal_(0,1)`         |
| `bernoulli_(p)`        | Fill with Bernoulli samples              | $x\sim\text{Bern}(p)$         | `x.bernoulli_(0.5)`      |

---

## Shape, Views & Indexing

| Method              | Description                           | Math            | Example                 |
|---------------------|---------------------------------------|-----------------|-------------------------|
| `clone()`           | Create a deep copy of the tensor      | N/A             | `y = x.clone()`         |
| `cast(dtype)`       | Cast tensor to another data type      | N/A             | `x.cast(dtype.float16)` |
| `view(shape)`       | Create a view with new shape          | N/A             | `x.view(2, -1)`         |
| `view_slice(d,s,l)` | Slice tensor without copying          | $x[s:s+l]$      | `x.view_slice(0,0,4)`   |
| `reshape(shape)`    | Reshape tensor (may copy)             | N/A             | `x.reshape(4,3)`        |
| `transpose(a,b)`    | Swap two dimensions                   | $x^T$           | `x.transpose(0,1)`      |
| `permute(dims)`     | Reorder dimensions arbitrarily        | N/A             | `x.permute(1,0,2)`      |
| `contiguous()`      | Ensure tensor is contiguous in memory | N/A             | `x = x.contiguous()`    |
| `squeeze()`         | Remove dimensions of size 1           | N/A             | `x.squeeze()`           |
| `unsqueeze(d)`      | Insert new dimension                  | N/A             | `x.unsqueeze(0)`        |
| `flatten(a,b)`      | Flatten a range of dimensions         | N/A             | `x.flatten(1)`          |
| `unflatten(s)`      | Expand flattened dimension            | N/A             | `x.unflatten((2,3))`    |
| `narrow(d,s,l)`     | Take slice along dimension            | N/A             | `x.narrow(1,0,4)`       |
| `movedim(a,b)`      | Move dimension to new position        | N/A             | `x.movedim(0,-1)`       |
| `select(d,i)`       | Select single index along dim         | $x[...,i]$      | `x.select(1,2)`         |
| `split(n,d)`        | Split tensor into chunks              | N/A             | `x.split(4,1)`          |
| `cat(xs,d)`         | Concatenate tensors                   | N/A             | `Tensor.cat([a,b],1)`   |
| `gather(d,idx)`     | Gather elements by index tensor       | $y_i=x_{idx_i}$ | `x.gather(1,idx)`       |

---

## Reductions

| Method     | Description                       | Math               | Example      |
|------------|-----------------------------------|--------------------|--------------|
| `mean()`   | Compute mean over elements        | $\frac1N\sum x$    | `x.mean()`   |
| `sum()`    | Sum elements                      | $\sum x$           | `x.sum()`    |
| `prod()`   | Product of elements               | $\prod x$          | `x.prod()`   |
| `min()`    | Minimum value                     | $\min(x)$          | `x.min()`    |
| `max()`    | Maximum value                     | $\max(x)$          | `x.max()`    |
| `argmin()` | Index of minimum                  | $\arg\min(x)$      | `x.argmin()` |
| `argmax()` | Index of maximum                  | $\arg\max(x)$      | `x.argmax()` |
| `any()`    | True if any element is non-zero   | $\exists x_i\neq0$ | `x.any()`    |
| `all()`    | True if all elements are non-zero | $\forall x_i\neq0$ | `x.all()`    |

---

## Unary Math Operations

| Method                                    | Description                     | Math (per element)                     | Example               |
|-------------------------------------------|---------------------------------|----------------------------------------|-----------------------|
| `abs()`                                   | Absolute value                  | $y = \vert x \vert$                    | `y = x.abs()`         |
| `sgn()`                                   | Sign of each element            | $y = \mathrm{sign}(x)$                 | `y = x.sgn()`         |
| `neg()`                                   | Negation                        | $y = -x$                               | `y = x.neg()`         |
| `sqr()`                                   | Square                          | $y = x^2$                              | `y = x.sqr()`         |
| `rcp()`                                   | Reciprocal                      | $y = \frac{1}{x}$                      | `y = x.rcp()`         |
| `sqrt()`                                  | Square root                     | $y = \sqrt{x}$                         | `y = x.sqrt()`        |
| `rsqrt()`                                 | Inverse square root             | $y = \frac{1}{\sqrt{x}}$               | `y = x.rsqrt()`       |
| `log()`                                   | Natural logarithm               | $y = \ln(x)$                           | `y = x.log()`         |
| `log2()`                                  | Base-2 logarithm                | $y = \log_2(x)$                        | `y = x.log2()`        |
| `log10()`                                 | Base-10 logarithm               | $y = \log_{10}(x)$                     | `y = x.log10()`       |
| `log1p()`                                 | Log of (1 + x)                  | $y = \ln(1 + x)$                       | `y = x.log1p()`       |
| `exp()`                                   | Exponential                     | $y = e^x$                              | `y = x.exp()`         |
| `exp2()`                                  | Power of 2                      | $y = 2^x$                              | `y = x.exp2()`        |
| `expm1()`                                 | Exponential minus 1             | $y = e^x - 1$                          | `y = x.expm1()`       |
| `floor()`                                 | Round down                      | $y = \lfloor x \rfloor$                | `y = x.floor()`       |
| `ceil()`                                  | Round up                        | $y = \lceil x \rceil$                  | `y = x.ceil()`        |
| `round()`                                 | Round to nearest integer        | $y = \mathrm{round}(x)$                | `y = x.round()`       |
| `trunc()`                                 | Truncate fractional part        | $y = \mathrm{trunc}(x)$                | `y = x.trunc()`       |
| `sin()`                                   | Sine                            | $y = \sin(x)$                          | `y = x.sin()`         |
| `cos()`                                   | Cosine                          | $y = \cos(x)$                          | `y = x.cos()`         |
| `tan()`                                   | Tangent                         | $y = \tan(x)$                          | `y = x.tan()`         |
| `asin()`                                  | Inverse sine                    | $y = \arcsin(x)$                       | `y = x.asin()`        |
| `acos()`                                  | Inverse cosine                  | $y = \arccos(x)$                       | `y = x.acos()`        |
| `atan()`                                  | Inverse tangent                 | $y = \arctan(x)$                       | `y = x.atan()`        |
| `sinh()`                                  | Hyperbolic sine                 | $y = \sinh(x)$                         | `y = x.sinh()`        |
| `cosh()`                                  | Hyperbolic cosine               | $y = \cosh(x)$                         | `y = x.cosh()`        |
| `tanh()`                                  | Hyperbolic tangent              | $y = \tanh(x)$                         | `y = x.tanh()`        |
| `asinh()`                                 | Inverse hyperbolic sine         | $y = \mathrm{asinh}(x)$                | `y = x.asinh()`       |
| `acosh()`                                 | Inverse hyperbolic cosine       | $y = \mathrm{acosh}(x)$                | `y = x.acosh()`       |
| `atanh()`                                 | Inverse hyperbolic tangent      | $y = \mathrm{atanh}(x)$                | `y = x.atanh()`       |
| `step()`                                  | Heaviside step (0/1)            | $y = \mathbb{1}[x > 0]$                | `y = x.step()`        |
| `erf()`                                   | Error function                  | $y = \mathrm{erf}(x)$                  | `y = x.erf()`         |
| `erfc()`                                  | Complementary error function    | $y = \mathrm{erfc}(x)$                 | `y = x.erfc()`        |
| `softmax()`                               | Softmax over last dim           | $y_i = \frac{e^{x_i}}{\sum_j e^{x_j}}$ | `y = x.softmax()`     |
| `sigmoid()`                               | Logistic sigmoid                | $y = \frac{1}{1 + e^{-x}}$             | `y = x.sigmoid()`     |
| `hard_sigmoid()` Piecewise linear sigmoid | approx. sigmoid, clipped linear | `y = x.hard_sigmoid()`                 |
| `silu()`                                  | SiLU / Swish                    | $y = x \cdot \sigma(x)$                | `y = x.silu()`        |
| `relu()`                                  | Rectified Linear Unit           | $y = \max(0,x)$                        | `y = x.relu()`        |
| `gelu()`                                  | Exact GELU                      | $y = x \cdot \Phi(x)$                  | `y = x.gelu()`        |
| `gelu_approx()`                           | Fast approximate GELU           | $y \approx 0.5x(1+\tanh(\cdots))$      | `y = x.gelu_approx()` |

---

## Binary Arithmetic

| Method     | Operator | Description                | Math          | Example |
|------------|----------|----------------------------|---------------|---------|
| `add()`    | `+`      | Elementwise addition       | $x+y$         | `x + y` |
| `sub()`    | `-`      | Elementwise subtraction    | $x-y$         | `x - y` |
| `mul()`    | `*`      | Elementwise multiplication | $x\cdot y$    | `x * y` |
| `div()`    | `/`      | Elementwise division       | $\frac{x}{y}$ | `x / y` |
| `mod()`    | `%`      | Elementwise modulus        | $x\bmod y$    | `x % y` |
| `matmul()` | `@`      | Matrix multiplication      | $XY$          | `x @ y` |

---

## Logical & Bitwise

| Method          | Operator | Description         | Math        | Example  |
|-----------------|----------|---------------------|-------------|----------|
| `logical_and()` | `&`      | Elementwise AND     | $x\land y$  | `x & y`  |
| `logical_or()`  | `\|`     | Elementwise OR      | $x\lor y$   | `x \| y` |
| `logical_xor()` | `^`      | Elementwise XOR     | $x\oplus y$ | `x ^ y`  |
| `logical_not()` | `~`      | Elementwise NOT     | $\lnot x$   | `~x`     |
| `bitwise_and()` | `&`      | Elementwise AND     | $x\land y$  | `x & y`  |
| `bitwise_or()`  | `\|`     | Bitwise OR          | $x\lor y$   | `x \| y` |
| `bitwise_xor()` | `^`      | Bitwise XOR         | $x\oplus y$ | `x ^ y`  |
| `bitwise_not()` | `~`      | Bitwise NOT         | $\lnot x$   | `~x`     |
| `bitwise_shl()` | `<<`     | Bitwise shift left  | $x\ll k$    | `x << 1` |
| `bitwise_shr()` | `>>`     | Bitwise shift right | $x\gg k$    | `x >> 1` |

---

## Matrix Utilities

| Method   | Description             | Math     | Example    |
|----------|-------------------------|----------|------------|
| `tril()` | Lower-triangular matrix | $i\ge j$ | `x.tril()` |
| `triu()` | Upper-triangular matrix | $i\le j$ | `x.triu()` |
