0
Fork 0
mirror of https://github.com/zml/zml.git synced 2026-11-16 19:11:09 +00:00
zml/examples
Guillaume Wenzek 493f61d31b
zml/tensor: gatherValues (#12)
gather1d was quite limited by design.
gatherValues is a generalization of gather1d, that handles tuple of
indices and batching.

For each coordinate in `indices`,
`gatherValues` extracts a single value of the given tensor.

* axes_ is a single axis, or a tuple of axis: .b, or .{ .b, .c }
* indices is an integer tensor
* result is a tensor whose shape is similar to the input shape
where the gathered axes have been replaced by axes from 'indices'.

Some example input for the base case where we work on one axis:
- gatherValues(f:[a]->float, .a, ind:[n]->int)[n] == f[ind[n]]
- gatherValues(f:[a, b], .a, ind:[n])[n, b] == f[ind[n], b]
- gatherValues(f: [a,b,c], .{.b}, ind: [n,m])[a, n, m, c] == f[a, ind[n,
m], c]

If an axis in common between `self` and `indices`,
it is treated as a "batching" axis, meaning that semantically
the operator is doing a gatherValues one time per dimension of this
axis:
- gatherValues(f: [a,b,c], .{.b}, ind: [a,n])[a, n] == f[a, ind[a, n]]

It is an error to have an axis present in `self`, `axes_` and `indices`.

If several axes are passed, then the last axis of indices is treated as
coordinates:
- gatherValues(f: [a,b,c], .{.b, .c}, ind: [n,2])[a, n] == f[a,
ind[n][0], ind[n][1]]
- gatherValues(f: [a,b,c,d], .{.b, .c}, ind: [a, n,2])[a, n, d] == f[a,
ind[a, n][0], ind[a, n][1], d]

It is possible to use gatherValues without tags, but batching won't be
available.


> [!WARNING]
> The semantic of inserting the indices axis where we are dropping the
input axis is very useful in practice:
> `roll`, `nearest`, `resize` benefit greatly from it.
> But it doesn't always play nice with batching dimensions.
> In particular the following currently isn't accepted:
> `gatherValues(.{ .{ .a = 10, .b = 20 }, .b, .{ .n = 8, .a = 10 })`
> because MLIR will produce `.{ .n = 8, .a = 10 }` following the indices
shape,
> while we produce `.{.a = 10, n=8}` following the semantic of
"replacing .b with axes from indices".
> If you do `gatherValues(.{ .{ .a = 10, .b = 20 }, .b, .{ .a = 10, .n =
8 })` then both convention agrees and it's a non issue.
> I think this inconsistency is ok for now because it only happens when
you have both batch axes and extra-indices axes which act like second
set of batching dimensions.
> the issue is avoidable from the user side by eg broadcasting the
values along `.n`, or transposing one of the operand.

---------

Signed-off-by: Guillaume Wenzek <wzk@zml.ai>
History 2024-09-19 16:17:07 +02:00
..
.vscode zml: initial release 2024-09-17 11:11:18 +02:00
benchmark zml: initial release 2024-09-17 11:11:18 +02:00
llama zml/tensor: gatherValues (#12) 2024-09-19 16:17:07 +02:00
loader zml: initial release 2024-09-17 11:11:18 +02:00
mnist zml: initial release 2024-09-17 11:11:18 +02:00
simple_layer zml: initial release 2024-09-17 11:11:18 +02:00
third_party/tigerbeetle zml: initial release 2024-09-17 11:11:18 +02:00
tools zml: initial release 2024-09-17 11:11:18 +02:00
.bazelignore zml: initial release 2024-09-17 11:11:18 +02:00
.bazelrc zml: initial release 2024-09-17 11:11:18 +02:00
.bazelversion zml: initial release 2024-09-17 11:11:18 +02:00
.gitignore zml: initial release 2024-09-17 11:11:18 +02:00
.nvim.lua zml: initial release 2024-09-17 11:11:18 +02:00
bazel.sh zml: initial release 2024-09-17 11:11:18 +02:00
build.zig zml: initial release 2024-09-17 11:11:18 +02:00
MODULE.bazel zml: initial release 2024-09-17 11:11:18 +02:00
MODULE.bazel.lock zml: initial release 2024-09-17 11:11:18 +02:00
platform_mappings zml: initial release 2024-09-17 11:11:18 +02:00
zls.build.json zml: initial release 2024-09-17 11:11:18 +02:00