-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #389 from willow-ahrens/wma/finchlogic
High-Level Interface
- Loading branch information
Showing
47 changed files
with
2,105 additions
and
953 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| ```@meta | ||
| CurrentModule = Finch | ||
| ``` | ||
|
|
||
| # Array API | ||
|
|
||
| Finch tensors also support many of the basic array operations one might expect, | ||
| including indexing, slicing, and elementwise maps, broadcast, and reduce. | ||
| For example: | ||
|
|
||
| ```jldoctest example1; setup = :(using Finch) | ||
| julia> A = fsparse([1, 1, 2, 3], [2, 4, 5, 6], [1.0, 2.0, 3.0]) | ||
| SparseCOO{2} (0.0) [:,1:6] | ||
| ├─ [1, 2]: 1.0 | ||
| ├─ [1, 4]: 2.0 | ||
| └─ [2, 5]: 3.0 | ||
| julia> A + 0 | ||
| Dense [:,1:6] | ||
| ├─ [:, 1]: Dense [1:3] | ||
| │ ├─ [1]: 0.0 | ||
| │ ├─ [2]: 0.0 | ||
| │ └─ [3]: 0.0 | ||
| ├─ [:, 2]: Dense [1:3] | ||
| │ ├─ [1]: 1.0 | ||
| │ ├─ [2]: 0.0 | ||
| │ └─ [3]: 0.0 | ||
| ├─ [:, 3]: Dense [1:3] | ||
| │ ├─ [1]: 0.0 | ||
| │ ├─ [2]: 0.0 | ||
| │ └─ [3]: 0.0 | ||
| ├─ [:, 4]: Dense [1:3] | ||
| │ ├─ [1]: 2.0 | ||
| │ ├─ [2]: 0.0 | ||
| │ └─ [3]: 0.0 | ||
| ├─ [:, 5]: Dense [1:3] | ||
| │ ├─ [1]: 0.0 | ||
| │ ├─ [2]: 3.0 | ||
| │ └─ [3]: 0.0 | ||
| └─ [:, 6]: Dense [1:3] | ||
| ├─ [1]: 0.0 | ||
| ├─ [2]: 0.0 | ||
| └─ [3]: 0.0 | ||
| julia> A + 1 | ||
| Dense [:,1:6] | ||
| ├─ [:, 1]: Dense [1:3] | ||
| │ ├─ [1]: 1.0 | ||
| │ ├─ [2]: 1.0 | ||
| │ └─ [3]: 1.0 | ||
| ├─ [:, 2]: Dense [1:3] | ||
| │ ├─ [1]: 2.0 | ||
| │ ├─ [2]: 1.0 | ||
| │ └─ [3]: 1.0 | ||
| ├─ [:, 3]: Dense [1:3] | ||
| │ ├─ [1]: 1.0 | ||
| │ ├─ [2]: 1.0 | ||
| │ └─ [3]: 1.0 | ||
| ├─ [:, 4]: Dense [1:3] | ||
| │ ├─ [1]: 3.0 | ||
| │ ├─ [2]: 1.0 | ||
| │ └─ [3]: 1.0 | ||
| ├─ [:, 5]: Dense [1:3] | ||
| │ ├─ [1]: 1.0 | ||
| │ ├─ [2]: 4.0 | ||
| │ └─ [3]: 1.0 | ||
| └─ [:, 6]: Dense [1:3] | ||
| ├─ [1]: 1.0 | ||
| ├─ [2]: 1.0 | ||
| └─ [3]: 1.0 | ||
| julia> B = A .* 2 | ||
| Sparse (0.0) [:,1:6] | ||
| ├─ [:, 2]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 2.0 | ||
| ├─ [:, 4]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 4.0 | ||
| └─ [:, 5]: Sparse (0.0) [1:3] | ||
| └─ [2]: 6.0 | ||
| julia> B[1:2, 1:2] | ||
| Sparse (0.0) [:,1:2] | ||
| └─ [:, 2]: Sparse (0.0) [1:2] | ||
| └─ [1]: 2.0 | ||
| julia> map(x -> x^2, B) | ||
| Sparse (0.0) [:,1:6] | ||
| ├─ [:, 2]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 4.0 | ||
| ├─ [:, 4]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 16.0 | ||
| └─ [:, 5]: Sparse (0.0) [1:3] | ||
| └─ [2]: 36.0 | ||
| ``` | ||
|
|
||
| # Array Fusion | ||
|
|
||
| Finch supports array fusion, which allows you to compose multiple array operations | ||
| into a single kernel. This can be a significant performance optimization, as it | ||
| allows the compiler to optimize the entire operation at once. The two functions | ||
| the user needs to know about are `lazy` and `compute`. You can use `lazy` to | ||
| mark an array as an input to a fused operation, and call `compute` to execute | ||
| the entire operation at once. For example: | ||
|
|
||
| ```jldoctest example1 | ||
| julia> C = lazy(A); | ||
| julia> D = lazy(B); | ||
| julia> E = (C .+ D)/2; | ||
| julia> compute(E) | ||
| Sparse (0.0) [:,1:6] | ||
| ├─ [:, 2]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 1.5 | ||
| ├─ [:, 4]: Sparse (0.0) [1:3] | ||
| │ └─ [1]: 3.0 | ||
| └─ [:, 5]: Sparse (0.0) [1:3] | ||
| └─ [2]: 4.5 | ||
| ``` | ||
|
|
||
| In the above example, `E` is a fused operation that adds `C` and `D` together | ||
| and then divides the result by 2. The `compute` function examines the entire | ||
| operation and decides how to execute it in the most efficient way possible. | ||
| In this case, it would likely generate a single kernel that adds the elements of `A` and `B` | ||
| together and divides each result by 2, without materializing an intermediate. | ||
|
|
||
| ```@docs | ||
| lazy | ||
| compute | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| # Sparse and Structured Array Utilities | ||
|
|
||
| ## Sparse Constructors | ||
|
|
||
| In addition to the `Tensor` constructor, Finch provides a number of convenience | ||
| constructors for common tensor types. For example, the `spzeros` and `sprand` functions | ||
| have `fspzeros` and `fsprand` counterparts that return Finch tensors. We can also construct | ||
| a sparse COO `Tensor` from a list of indices and values using the `fsparse` function. | ||
|
|
||
| ```@docs | ||
| fsparse | ||
| fsparse! | ||
| fsprand | ||
| fspzeros | ||
| ffindnz | ||
| ``` | ||
|
|
||
| ## Fill Values | ||
|
|
||
| Finch tensors support an arbitrary "background" value for sparse arrays. While most arrays use `0` as the background value, this is not always the case. For example, a sparse array of `Int` might use `typemin(Int)` as the background value. The `default` function returns the background value of a tensor. If you ever want to change the background value of an existing array, you can use the `redefault!` function. The `countstored` function returns the number of stored elements in a tensor, and calling `pattern!` on a tensor returns tensor which is true whereever the original tensor stores a value. Note that countstored doesn't always return the number of non-zero elements in a tensor, as it counts the number of stored elements, and stored elements may include the background value. You can call `dropdefaults!` to remove explicitly stored background values from a tensor. | ||
|
|
||
| ```jldoctest example1; setup = :(using Finch) | ||
| julia> A = fsparse([1, 1, 2, 3], [2, 4, 5, 6], [1.0, 2.0, 3.0]) | ||
| SparseCOO{2} (0.0) [:,1:6] | ||
| ├─ [1, 2]: 1.0 | ||
| ├─ [1, 4]: 2.0 | ||
| └─ [2, 5]: 3.0 | ||
| julia> min.(A, -1) | ||
| Dense [:,1:6] | ||
| ├─ [:, 1]: Dense [1:3] | ||
| │ ├─ [1]: -1.0 | ||
| │ ├─ [2]: -1.0 | ||
| │ └─ [3]: -1.0 | ||
| ├─ [:, 2]: Dense [1:3] | ||
| │ ├─ [1]: -1.0 | ||
| │ ├─ [2]: -1.0 | ||
| │ └─ [3]: -1.0 | ||
| ├─ [:, 3]: Dense [1:3] | ||
| │ ├─ [1]: -1.0 | ||
| │ ├─ [2]: -1.0 | ||
| │ └─ [3]: -1.0 | ||
| ├─ [:, 4]: Dense [1:3] | ||
| │ ├─ [1]: -1.0 | ||
| │ ├─ [2]: -1.0 | ||
| │ └─ [3]: -1.0 | ||
| ├─ [:, 5]: Dense [1:3] | ||
| │ ├─ [1]: -1.0 | ||
| │ ├─ [2]: -1.0 | ||
| │ └─ [3]: -1.0 | ||
| └─ [:, 6]: Dense [1:3] | ||
| ├─ [1]: -1.0 | ||
| ├─ [2]: -1.0 | ||
| └─ [3]: -1.0 | ||
| julia> default(A) | ||
| 0.0 | ||
| julia> B = redefault!(A, -Inf) | ||
| SparseCOO{2} (-Inf) [:,1:6] | ||
| ├─ [1, 2]: 1.0 | ||
| ├─ [1, 4]: 2.0 | ||
| └─ [2, 5]: 3.0 | ||
| julia> min.(B, -1) | ||
| Sparse (-Inf) [:,1:6] | ||
| ├─ [:, 2]: Sparse (-Inf) [1:3] | ||
| │ └─ [1]: -1.0 | ||
| ├─ [:, 4]: Sparse (-Inf) [1:3] | ||
| │ └─ [1]: -1.0 | ||
| └─ [:, 5]: Sparse (-Inf) [1:3] | ||
| └─ [2]: -1.0 | ||
| julia> countstored(A) | ||
| 3 | ||
| julia> pattern!(A) | ||
| SparseCOO{2} (false) [:,1:6] | ||
| ├─ [1, 2]: true | ||
| ├─ [1, 4]: true | ||
| └─ [2, 5]: true | ||
| ``` | ||
|
|
||
| ```@docs | ||
| redefault! | ||
| pattern! | ||
| countstored | ||
| dropdefaults | ||
| dropdefaults! | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
d379410There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@JuliaRegistrator register
d379410There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Registration pull request created: JuliaRegistries/General/102495
Tip: Release Notes
Did you know you can add release notes too? Just add markdown formatted text underneath the comment after the text
"Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the
release that TagBot creates. i.e.
To add them here just re-invoke and the PR will be updated.
Tagging
After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.
This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via: