README update and ct.where removal (#180)

Author: maleadt

README.md

@@ -2,9 +2,9 @@
 
 A Julia package for writing GPU kernels using NVIDIA's tile-based programming model.
 
-**This package is under active development.** Not all Tile IR features are implemented, and
-support for the Julia language is limited and only verified on the examples provided here.
-Interfaces and APIs may change without notice.
+**This package is in beta.** Most Tile IR features are implemented and the package has been
+verified on the benchmarks and tests included in the repository. Interfaces and APIs may
+still change without notice.
 
 
 ## Installation
@@ -19,7 +19,8 @@ julia> Pkg.add("cuTile")
 Execution of cuTile kernels requires CUDA.jl to be installed and imported.
 cuTile generates kernels based on [Tile IR](https://docs.nvidia.com/cuda/tile-ir/), which requires an NVIDIA Driver that supports CUDA 13 (580 or later).
 CUDA.jl automatically downloads the appropriate CUDA toolkit artifacts, so no manual CUDA installation is needed.
-Only Ampere, Ada, and Blackwell GPUs are supported at this time, with Hopper support coming in a later release of CUDA 13.
+Only Ampere, Ada, and Blackwell GPUs are supported at this time, with Hopper support expected
+in a future release of CUDA.
 
 ## Quick Start
 
@@ -124,6 +125,15 @@ cuTile.jl aims to expose as much functionality as possible through Julia-native
 prefixed with `ct.` are cuTile intrinsics with no direct Julia equivalent; everything else
 uses standard Julia syntax and is overlaid on `Base`.
 
+### Supported Types
+
+**Integers:** `Int8`, `UInt8`, `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, `UInt64`
+**Floats:** `Float16`, `BFloat16`, `Float32`, `Float64`, `TFloat32`
+**Boolean:** `Bool`
+
+`TFloat32` is a 32-bit floating-point type with reduced mantissa precision (10 bits),
+optimized for tensor core operations.
+
 ### Memory
 | Operation | Description |
 |-----------|-------------|
@@ -151,6 +161,18 @@ ct.scatter(arr, indices, tile; mask=active_mask)
 | `ct.num_blocks(axis)` | Grid size along axis |
 | `ct.num_tiles(arr, axis, shape)` | Number of tiles along axis |
 
+### Control Flow
+| Construct | Description |
+|-----------|-------------|
+| `if`/`elseif`/`else` | Conditional branching |
+| `for i in start:stop` | Counted loops (compiled to Tile IR ForOp) |
+| `for i in start:step:stop` | Stepped loops |
+| `while cond ... end` | While loops |
+| `ifelse.(cond, x, y)` | Element-wise conditional selection |
+
+Standard Julia control flow works inside kernels and is compiled to structured
+Tile IR operations.
+
 ### Arithmetic
 | Operation | Description |
 |-----------|-------------|
@@ -189,6 +211,7 @@ ct.scatter(arr, indices, tile; mask=active_mask)
 | `map(f, tiles...)` | Apply function element-wise (same shape) |
 | `f.(tiles...)`, `broadcast(f, tiles...)` | Apply function with shape broadcasting |
 | `reduce(f, tile; dims, init)` | Reduction with arbitrary function |
+| `mapreduce(f, op, tile; dims, init)` | Map then reduce |
 | `accumulate(f, tile; dims, init, rev)` | Scan/prefix-sum with arbitrary function |
 
 ### Reductions
@@ -215,10 +238,13 @@ ct.scatter(arr, indices, tile; mask=active_mask)
 | `exp2.(tile)` | Base-2 exponential |
 | `log.(tile)` | Natural logarithm |
 | `log2.(tile)` | Base-2 logarithm |
-| `sin.(tile)`, `cos.(tile)`, etc. | Trigonometric functions |
+| `sin.(tile)`, `cos.(tile)`, `tan.(tile)` | Trigonometric functions |
+| `sinh.(tile)`, `cosh.(tile)`, `tanh.(tile)` | Hyperbolic functions |
 | `fma.(a, b, c)` | Fused multiply-add |
 | `abs.(tile)` | Absolute value |
+| `isnan.(tile)` | NaN test |
 | `max(a, b)`, `min(a, b)` | Maximum/minimum (scalars) |
+| `ceil.(tile)`, `floor.(tile)` | Rounding |
 | `ct.@fpmode rounding_mode=ct.Rounding.Approx flush_to_zero=true begin ... end` | Scoped FP rounding mode and flush-to-zero |
 
 ### Comparison
@@ -242,6 +268,14 @@ ct.scatter(arr, indices, tile; mask=active_mask)
 | `div(a, b)` | Truncating division |
 | `mul_hi.(tile_a, tile_b)`, `mul_hi(x, y)` | High bits of integer multiply (use `Base.mul_hi` on Julia 1.13+) |
 
+### Indexing
+| Operation | Description |
+|-----------|-------------|
+| `arr[i, j, ...]` | Load scalar element from `TileArray` |
+| `arr[i, j, ...] = val` | Store scalar element to `TileArray` |
+| `tile[i, j, ...]` | Extract scalar from `Tile` |
+| `setindex(tile, val, i, j, ...)` | Return new `Tile` with element replaced |
+
 ### Atomics
 | Operation | Description |
 |-----------|-------------|
@@ -257,11 +291,52 @@ ct.scatter(arr, indices, tile; mask=active_mask)
 All atomics accept `memory_order` (default: `ct.MemoryOrder.AcqRel`) and
 `memory_scope` (default: `ct.MemScope.Device`) keyword arguments.
 
+### Performance Tuning
+
+#### Kernel configuration
+
+`ct.@compiler_options` sets optimization hints inside a kernel function body:
+
+```julia
+function matmul(A, B, C, ...)
+    ct.@compiler_options num_ctas=ct.ByTarget(v"10.0" => 2) occupancy=8
+    ...
+end
+```
+
+| Option | Description | Valid values |
+|--------|-------------|--------------|
+| `num_ctas` | Number of CTAs in a CGA | Powers of 2 |
+| `occupancy` | Target concurrent CTAs per SM | 1–32 |
+| `opt_level` | Optimization level | 0–3 |
+
+Values can be plain scalars or `ct.ByTarget(...)` for per-architecture dispatch.
+`ByTarget` maps compute capabilities to values, with an optional default:
+
+```julia
+ct.@compiler_options num_ctas=ct.ByTarget(v"10.0" => 4, v"12.0" => 2; default=1)
+```
+
+Hints can also be passed as keyword arguments to `ct.launch` or `ct.code_tiled`,
+which take precedence over `@compiler_options`.
+
+#### Load/store hints
+
+`ct.load` and `ct.store` accept optional keyword arguments that influence memory
+traffic scheduling:
+
+| Hint | Description |
+|------|-------------|
+| `latency` | DRAM traffic weight hint, integer 1 (low) to 10 (high). Default: compiler-inferred. |
+| `allow_tma` | Whether to allow Tensor Memory Accelerator lowering. Default: allowed. |
+
 ### Debugging
+
 | Operation | Description |
 |-----------|-------------|
 | `print(args...)` | Print values (Base overlay) |
 | `println(args...)` | Print values with newline (Base overlay) |
+| `ct.@assert cond [msg]` | Abort kernel if condition is false |
 
 Standard Julia `print`/`println` work inside kernels. String constants and tiles
 can be mixed freely; format specifiers are inferred from element types at compile
@@ -270,9 +345,27 @@ time. String interpolation is supported.
 ```julia
 println("Block ", ct.bid(1), ": tile=", tile)
 println("result=$result")  # string interpolation
+ct.@assert idx <= n "index out of bounds"
 ```
 
-This is a debugging aid and is not optimized for performance.
+These are debugging aids and are not optimized for performance.
+
+### Code Inspection
+
+Beyond `ct.code_tiled` and `ct.@code_tiled` shown above, cuTile.jl provides
+`@device_code_*` macros that intercept compilation during `ct.launch`:
+
+```julia
+ct.@device_code_tiled ct.launch(vadd, grid, a, b, c, ct.Constant(16))
+ct.@device_code_typed ct.launch(vadd, grid, a, b, c, ct.Constant(16))
+ct.@device_code_structured ct.launch(vadd, grid, a, b, c, ct.Constant(16))
+```
+
+| Macro | Output |
+|-------|--------|
+| `ct.@device_code_tiled` | Final Tile IR (MLIR textual format) |
+| `ct.@device_code_typed` | Typed Julia IR after overlay resolution |
+| `ct.@device_code_structured` | Structured IR (after control-flow structurization) |
 
 
 ## Differences from cuTile Python
@@ -312,7 +405,8 @@ end
 ### Optimization hints
 
 Python passes optimization hints as `@ct.kernel` decorator arguments. Julia uses
-`ct.@compiler_options` inside the function body (like `@inline`):
+`ct.@compiler_options` inside the function body (like `@inline`). See
+[Performance Tuning](#performance-tuning) for full details.
 
 ```python
 # Python
@@ -329,24 +423,6 @@ function matmul(A, B, C, ...)
 end
 ```
 
-Supported options:
-
-| Option | Description | Valid values |
-|--------|-------------|--------------|
-| `num_ctas` | Number of CTAs in a CGA (cooperative group array) | Powers of 2 |
-| `occupancy` | Target occupancy (number of concurrent CTAs per SM) | 1–32 |
-| `opt_level` | Optimization level | 0–3 |
-
-Values can be plain scalars or `ct.ByTarget(...)` for per-architecture dispatch.
-`ByTarget` maps compute capabilities to values, with an optional default:
-
-```julia
-ct.@compiler_options num_ctas=ct.ByTarget(v"10.0" => 4, v"12.0" => 2; default=1)
-```
-
-Hints can also be passed as keyword arguments to `ct.launch` or `ct.code_tiled`,
-which take precedence over `@compiler_options`.
-
 ### Launch Syntax
 
 cuTile.jl implicitly uses the current task-bound stream from CUDA.jl:
@@ -515,7 +591,7 @@ standard Julia silently produce truncated or wrapped results instead:
   throwing `InexactError` for non-integer or out-of-range values. Use
   `unsafe_trunc` for the explicit non-throwing primitive.
 
-Assertions may be added in the future for testing purposes.
+Use `ct.@assert` to add runtime checks in kernels (see Debugging above).
 
 
 ## Host-level operations

src/language/operations.jl

@@ -169,7 +169,7 @@ end
     idx = Intrinsics.iota((flat_len,), Int32)
     mask = idx .== Int32(linear)
     val_tile = broadcast_to(Tile(T(val)), (flat_len,))
-    new_flat = where(mask, val_tile, flat)
+    new_flat = ifelse.(mask, val_tile, flat)
     reshape(new_flat, S)
 end
 
@@ -1038,22 +1038,7 @@ end
  Selection
 =============================================================================#
 
-public where, extract
-
-"""
-    where(cond::Tile{Bool}, x, y) -> Tile
-
-Element-wise conditional selection: returns x where cond is true, y otherwise.
-Similar to numpy.where() or torch.where(). Supports broadcasting and scalar arguments.
-
-# Example
-```julia
-mask = tile_a .> tile_b  # Boolean tile
-result = ct.where(mask, tile_a, tile_b)  # Element-wise max
-result = ct.where(mask, tile_a, 0.0f0)  # Zero out where mask is false
-```
-"""
-where(cond, x, y) = ifelse.(cond, x, y)
+public extract
 
 """
     extract(tile::Tile{T, S}, index::NTuple{N, Int}, shape::NTuple{N, Int}) -> Tile{T, shape}

test/codegen/operations.jl

@@ -366,7 +366,7 @@ spec4d = ct.ArraySpec{4}(16, true)
                 tile_b = ct.load(b, pid, (16,))
                 @check "cmpf"
                 mask = tile_a .< tile_b
-                result = ct.where(mask, tile_a, tile_b)
+                result = ifelse.(mask, tile_a, tile_b)
                 ct.store(c, pid, result)
                 return
             end
@@ -382,7 +382,7 @@ spec4d = ct.ArraySpec{4}(16, true)
                 tile_b = ct.load(b, pid, (16,))
                 @check "cmpi"
                 mask = tile_a .< tile_b
-                result = ct.where(mask, tile_a, tile_b)
+                result = ifelse.(mask, tile_a, tile_b)
                 ct.store(c, pid, result)
                 return
             end
@@ -402,7 +402,7 @@ spec4d = ct.ArraySpec{4}(16, true)
                 result = a .< b
                 # Use same-typed operands for where to avoid Union type
                 b_promoted = convert(ct.Tile{Int64}, b)
-                selected = ct.where(result, a, b_promoted)
+                selected = ifelse.(result, a, b_promoted)
                 ct.store(out, Int32(0), selected)
                 return
             end
@@ -820,7 +820,7 @@ spec4d = ct.ArraySpec{4}(16, true)
                 tile_b = ct.load(b, pid, (16,))
                 mask = tile_a .> tile_b
                 @check "select"
-                result = ct.where(mask, tile_a, tile_b)
+                result = ifelse.(mask, tile_a, tile_b)
                 ct.store(c, pid, result)
                 return
             end

test/device/broadcast.jl

@@ -227,8 +227,8 @@ for (name, op1, op2) in [
             pid = ct.bid(1)
             ta = ct.load(a, pid, (16,))
             tb = ct.load(b, pid, (16,))
-            ct.store(out1, pid, ct.where(broadcast($op1, ta, tb), 1.0f0, 0.0f0))
-            ct.store(out2, pid, ct.where(broadcast($op2, ta, tb), 1.0f0, 0.0f0))
+            ct.store(out1, pid, ifelse.(broadcast($op1, ta, tb), 1.0f0, 0.0f0))
+            ct.store(out2, pid, ifelse.(broadcast($op2, ta, tb), 1.0f0, 0.0f0))
             return
         end
         n = 1024
@@ -248,8 +248,8 @@ end
         pid = ct.bid(1)
         ta = ct.load(a, pid, (16,))
         tb = ct.load(b, pid, (16,))
-        ct.store(out_eq, pid, ct.where(ta .== tb, 1.0f0, 0.0f0))
-        ct.store(out_ne, pid, ct.where(ta .!= tb, 1.0f0, 0.0f0))
+        ct.store(out_eq, pid, ifelse.(ta .== tb, 1.0f0, 0.0f0))
+        ct.store(out_ne, pid, ifelse.(ta .!= tb, 1.0f0, 0.0f0))
         return
     end
 
@@ -281,7 +281,7 @@ end
                 pid = ct.bid(1)
                 ta = ct.load(a, pid, (16,))
                 tb = ct.load(b, pid, (16,))
-                ct.store(out, pid, ct.where(broadcast($op, ta, tb), 1.0f0, 0.0f0))
+                ct.store(out, pid, ifelse.(broadcast($op, ta, tb), 1.0f0, 0.0f0))
                 return
             end
             n = 1024
@@ -302,7 +302,7 @@ end
                                out::ct.TileArray{Float32,1})
         pid = ct.bid(1)
         ta = ct.load(a, pid, (16,))
-        ct.store(out, pid, ct.where(ta .> 0.5f0, 1.0f0, 0.0f0))
+        ct.store(out, pid, ifelse.(ta .> 0.5f0, 1.0f0, 0.0f0))
         return
     end
 
@@ -358,16 +358,16 @@ end
 
 end
 
-@testset "where / ifelse broadcasting" begin
+@testset "ifelse broadcasting" begin
 
-@testset "where same-shape" begin
+@testset "ifelse same-shape" begin
     function where_same_kernel(a::ct.TileArray{Float32,1}, b::ct.TileArray{Float32,1},
                                c::ct.TileArray{Float32,1})
         pid = ct.bid(1)
         ta = ct.load(a, pid, (16,))
         tb = ct.load(b, pid, (16,))
         mask = ta .> tb
-        result = ct.where(mask, ta, tb)
+        result = ifelse.(mask, ta, tb)
         ct.store(c, pid, result)
         return
     end
@@ -382,12 +382,12 @@ end
     @test Array(c) ≈ ifelse.(Array(a) .> Array(b), Array(a), Array(b)) rtol=1e-5
 end
 
-@testset "where with scalar y" begin
+@testset "ifelse with scalar y" begin
     function where_scalar_y_kernel(a::ct.TileArray{Float32,1}, b::ct.TileArray{Float32,1})
         pid = ct.bid(1)
         ta = ct.load(a, pid, (16,))
         mask = ta .> 0.5f0
-        result = ct.where(mask, ta, 0.0f0)
+        result = ifelse.(mask, ta, 0.0f0)
         ct.store(b, pid, result)
         return
     end
@@ -401,12 +401,12 @@ end
     @test Array(b) ≈ ifelse.(Array(a) .> 0.5f0, Array(a), 0.0f0) rtol=1e-5
 end
 
-@testset "where with scalar x" begin
+@testset "ifelse with scalar x" begin
     function where_scalar_x_kernel(a::ct.TileArray{Float32,1}, b::ct.TileArray{Float32,1})
         pid = ct.bid(1)
         ta = ct.load(a, pid, (16,))
         mask = ta .> 0.5f0
-        result = ct.where(mask, 1.0f0, ta)
+        result = ifelse.(mask, 1.0f0, ta)
         ct.store(b, pid, result)
         return
     end
@@ -420,11 +420,11 @@ end
     @test Array(b) ≈ ifelse.(Array(a) .> 0.5f0, 1.0f0, Array(a)) rtol=1e-5
 end
 
-@testset "where with broadcasting" begin
+@testset "ifelse with broadcasting" begin
     function where_broadcast_kernel(a::ct.TileArray{Float32,2}, b::ct.TileArray{Float32,2})
         mask = ct.load(a, (1, 1), (1, 128))  # (1, 128) mask
         tile = ct.load(a, (1, 1), (64, 128))  # (64, 128) tile
-        result = ct.where(mask .> 0.5f0, tile, 0.0f0)
+        result = ifelse.(mask .> 0.5f0, tile, 0.0f0)
         ct.store(b, (1, 1), result)
         return
     end