# Arithmetic Types

The arithmetic layer is the set of scalar (`Numeric`) and SIMD (`Vector`) values
a kernel computes with: the types themselves, their public operations.

## The type tower

Every arithmetic value is either a scalar `Numeric` or a `Vector` of a `Numeric`
element type. A type class is also its constructor: `Float32(x)` builds (or
casts to) a `Float32`.

### Numeric scalars

`Numeric` is the base of every scalar that wraps an `ir.Value`.

- **Integers** — `Int4` `Int8` `Int16` `Int32` `Int64` `Int128`, `Uint8`
  `Uint16` `Uint32` `Uint64` `Uint128`. Signedness and width are fixed per type.
- **Floats** — `Float16` `BFloat16` `Float32` `Float64`.
- **Narrow floats** — `Float8E5M2` `Float8E4M3FN` `Float8E4M3FNUZ`
  `Float8E4M3B11FNUZ` `Float8E4M3`, `Float6E2M3FN` `Float6E3M2FN`,
  `Float8E8M0FNU`, `Float4E2M1FN`. These are storage/transport types, not meant
  for direct arithmetic, and native support is architecture-restricted.
- **`Boolean`** — the `i1` type; the result of comparisons and predicates.

### Public methods

Common to `Numeric` and `Vector`, elementwise for `Vector`:

| Method | Meaning | Example |
|--------|---------|---------|
| `Type(x)` | construct or cast — the type class is its own constructor. A `Vector` alias type (`Float32x4`, …) broadcasts a scalar across every lane | `Int32(5)`, `Float32(thread_idx.x)`; `Float32x4(1.0)` → all four lanes `1.0` |
| Arithmetic — `+` `-` `*` `/` `//` `%` `**`, unary `+x` `-x` `abs(x)`, `divmod(x, y)` | result type follows *Type interoperability*; elementwise with scalar broadcast for `Vector` | `Int32(3) + Int32(4)` → `Int32(7)`; `vec * 2.0` |
| Bitwise/shift — `&` `\|` `^` `<<` `>>`, unary `~x` | integer-only | `Int32(6) & Int32(3)` → `Int32(2)` |
| Comparison — `<` `<=` `>` `>=` `==` `!=` | result is `Boolean` | `a < b` |
| `x.bitcast(dtype)` | reinterpret the bits: `Numeric` equal width; `Vector` equal *total* width, recomputing the lane count | `Float32(1.0).bitcast(Int32)`; `Float32x4(0.0).bitcast(Int8)` → `Int8x16` |
| `x.dtype` | the scalar type (`Numeric`) / element type (`Vector`) | `Int32(5).dtype` / `Int32x4(0).dtype` → `Int32` |
| `x.ir_value()` | the underlying `ir.Value`, materializing a constant for a compile-time value | `Int32(5).ir_value()` |
| `cond.select(true_value, false_value)` | ternary select; a non-`Boolean` `cond` is converted by truthiness (nonzero) | `(a < b).select(a, b)` → min |
| `x.to(dtype)` | value-preserving conversion to another type | `Int32(5).to(Float32)` → `Float32(5.0)` |

`Numeric`-only methods:

| Method | Meaning | Example |
|--------|---------|---------|
| `x.is_static()` | whether the value is compile-time (Python) rather than run-time (`ir.Value`) | `Int32(5).is_static()` → `True` |
| `Numeric.width` / `Numeric.log_width` | the type's bit width, and `ceil(log2(width))` | `Int32.width` → `32`; `Int32.log_width` → `5` |
| `as_numeric` / `Numeric.from_python_value(value)` | build a `Numeric` from a Python value | `as_numeric(5)` → `Int32(5)` |
| `Numeric.from_ir_type(ir_type)` | the `Numeric` type for an MLIR type | `Numeric.from_ir_type(T.f32())` → `Float32` |

### Vector

`Vector` is a fixed-length sequence of `N` elements of a single `Numeric`
element type. It has value semantics and inherits the scalar operators, applied
elementwise; a scalar operand is auto-broadcast across the lanes.

- **Type aliases** — `Float32x4`, `BFloat16x8`, `Int32x4`, … name a
  `dtype`×`N` vector type directly (`<dtype>x<N>`).

## Compile-time and run-time values

A `Numeric` is *polymorphic in the value it holds* — the type is the same either
way, and `is_static()` reports which:

- a **compile-time value** — a Python `int` / `float` / `bool`, known while
  tracing; or
- a **run-time value** — an `ir.Value` from an MLIR op, known only at execution.

A `Vector` is always run-time — it is backed by an MLIR vector value, so it has
no compile-time (folded) form.

### Arithmetic preserves the compile-time property

If every operand is compile-time, the result is compile-time — the host folds it
and emits no MLIR (`Int32(3) + Int32(4)` ⇒ `Int32` holding `7`). As soon as one
operand is run-time, the result is run-time and an MLIR op is emitted. This
holds uniformly across arithmetic, comparison, bitwise, and shift operators.

### Python literals

A bare literal stays plain Python while it only meets other Python values
(`2 + 3` is ordinary Python). On contact with a `Numeric` it takes a DSL type
*by value* (see *Operand normalization*) as a compile-time value; on contact
with a `Vector` it broadcasts to the lanes and the result is run-time. After
this the interoperability rules apply. An explicit `Int32(5)` is likewise
compile-time until combined with a run-time value.

### Using a compile-time value as Python

Because it holds a real Python value, a compile-time `Numeric` works wherever
Python expects one — `int(x)`, `bool(x)`, indexing, a Python `if` — so a DSL
constant can still drive host-side control flow. A run-time `Numeric` raises if
forced to a Python value.

## Type interoperability

How a binary operation between two DSL numeric values determines the type its
operands are converted to (the *common type*) and the type it produces (the
*result type*). The rules are the same whether operands are scalar (`Numeric`),
`Vector`, or a mix of the two; `Vector ⊗ Vector` additionally broadcasts shapes,
which is independent of type and covered in the layout guides.

### Operand normalization

Before the rules below apply, operands are normalized:

- **Python literals** take a DSL type by value: an `int` becomes `Int32`, or
  `Int64` when it falls outside the `Int32` range; a `float` becomes `Float32`;
  a `bool` becomes `Boolean`.
- **`Boolean`** depends on the operation:
  - In arithmetic (`+ - * / // %`) it is converted to `Int32` and then follows
    the `Int32` rules.
  - In comparisons it is compared directly and the result is `Boolean`.
  - In bitwise (`& | ^`) and shift (`<< >>`) it stays `Boolean` and the result
    is `Boolean`.

### Common type

For two numeric operands (after normalization above; `Boolean` in arithmetic is
already `Int32` here), the common type is:

| lhs \ rhs | Int8 | Int16 | Int32 | Int64 | Uint32 | Float16 | BFloat16 | Float32 | Float64 |
|-----------|------|-------|-------|-------|--------|---------|----------|---------|---------|
| Int8      | Int8 | Int16 | Int32 | Int64 | Uint32 | Float16 | BFloat16 | Float32 | Float64 |
| Int16     | Int16 | Int16 | Int32 | Int64 | Uint32 | Float16 | BFloat16 | Float32 | Float64 |
| Int32     | Int32 | Int32 | Int32 | Int64 | Uint32 | Float32 | Float32  | Float32 | Float64 |
| Int64     | Int64 | Int64 | Int64 | Int64 | Int64  | Float64 | Float64  | Float64 | Float64 |
| Uint32    | Uint32 | Uint32 | Uint32 | Int64 | Uint32 | Float32 | Float32  | Float32 | Float64 |
| Float16   | Float16 | Float16 | Float32 | Float64 | Float32 | Float16 | Float32 | Float32 | Float64 |
| BFloat16  | BFloat16 | BFloat16 | Float32 | Float64 | Float32 | Float32 | BFloat16 | Float32 | Float64 |
| Float32   | Float32 | Float32 | Float32 | Float64 | Float32 | Float32 | Float32 | Float32 | Float64 |
| Float64   | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 |

The table follows these rules (other integer widths obey the same integer
rules):

- **Same type** → itself.
- **Two integers, same signedness** → the wider one (`Int8 + Int8` stays `Int8`;
  there is no promotion to a machine `int`).
- **Two integers, mixed signedness** → the unsigned type when it is at least as
  wide as the signed one, otherwise the signed type. So `Int32 + Uint32` is
  `Uint32`, and `Int64 + Uint32` is `Int64`.
- **One float, one integer** → the float, widened to cover the integer's width:
  `Float16 + Int32` is `Float32`, `Float32 + Int64` is `Float64`, and
  `Float16 + Int8` is `Float16`.
- **Two floats** → the wider one; at equal width the higher-precision one
  (`Float64 > Float32 > Float16`/`BFloat16`). `Float16` and `BFloat16` are
  equal width and neither converts to the other without loss, so they combine to
  `Float32`.

### Result type

Given the common type `C` from the table above:

| Operation | Result type |
|-----------|-------------|
| `+`  `-`  `*` `//`  `%` `**` | `C` |
| `/` | `C` if `C` is a `Float`; if `C` is an `Integer`, `Float32` when its width is at most 32 bits, otherwise `Float64` |
| `<`  `<=`  `>`  `>=`  `==`  `!=` | `Boolean` (operands are compared as `C`) |
| `&`  `\|`  `^`  `<<`  `>>` | `C`; operands must be `Integer` (a `Float` operand raises `TypeError`) |