Skip to content

Commit af3c6ee

Browse files
ChrisRackauckasChrisRackauckas
committed
Expand the docs explanations
1 parent 0894dba commit af3c6ee

File tree

8 files changed

+175
-56
lines changed

8 files changed

+175
-56
lines changed

‎docs/make.jl

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ makedocs(;
66
sitename="ArrayInterface.jl",
77
pages=[
88
"ArrayInterface.jl: An Extended Array Interface for Julia Generic Programming" => "index.md",
9+
"indexing.md",
10+
"conversions.md",
11+
"linearalgebra.md",
12+
"sparsearrays.md",
13+
"tuples.md",
14+
"wrapping.md",
915
]
1016
)
1117

‎docs/src/conversions.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Julia's Extended Array Conversions Interface
2+
3+
The following ArrayInterface functions extend Julia's Array interface for how arrays
4+
can be converted to different forms.
5+
6+
##
7+
8+
## Conversion Functions
9+
10+
```@docs
11+
ArrayInterface.aos_to_soa
12+
ArrayInterface.promote_eltype
13+
ArrayInterface.restructure
14+
ArrayInterface.safevec
15+
```

‎docs/src/index.md

Lines changed: 1 addition & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -20,59 +20,4 @@ ArrayInterface.jl uses extension packages in order to add support for popular li
2020
If one is looking for an interface which includes functionality for statically-computed values, see
2121
[StaticArrayInterface.jl](https://github.com/JuliaArrays/StaticArrayInterface.jl).
2222
This was separated from ArrayInterface.jl because it includes a lot of functionality that does not give substantive improvements
23-
to the interface, and is likely to be deprecated in the near future as the compiler matures to automate a lot of its optimizations.
24-
25-
## API
26-
27-
### Traits
28-
29-
```@docs
30-
ArrayInterface.can_avx
31-
ArrayInterface.can_change_size
32-
ArrayInterface.can_setindex
33-
ArrayInterface.device
34-
ArrayInterface.defines_strides
35-
ArrayInterface.ensures_all_unique
36-
ArrayInterface.ensures_sorted
37-
ArrayInterface.fast_matrix_colors
38-
ArrayInterface.fast_scalar_indexing
39-
ArrayInterface.indices_do_not_alias
40-
ArrayInterface.instances_do_not_alias
41-
ArrayInterface.is_forwarding_wrapper
42-
ArrayInterface.ismutable
43-
ArrayInterface.isstructured
44-
ArrayInterface.has_sparsestruct
45-
ArrayInterface.ndims_index
46-
ArrayInterface.ndims_shape
47-
```
48-
49-
### Functions
50-
51-
```@docs
52-
ArrayInterface.allowed_getindex
53-
ArrayInterface.allowed_setindex!
54-
ArrayInterface.aos_to_soa
55-
ArrayInterface.buffer
56-
ArrayInterface.findstructralnz
57-
ArrayInterface.flatten_tuples
58-
ArrayInterface.lu_instance
59-
ArrayInterface.qr_instance
60-
ArrayInterface.svd_instance
61-
ArrayInterface.map_tuple_type
62-
ArrayInterface.matrix_colors
63-
ArrayInterface.issingular
64-
ArrayInterface.parent_type
65-
ArrayInterface.promote_eltype
66-
ArrayInterface.restructure
67-
ArrayInterface.safevec
68-
ArrayInterface.zeromatrix
69-
ArrayInterface.undefmatrix
70-
```
71-
72-
### Types
73-
74-
```@docs
75-
ArrayInterface.ArrayIndex
76-
ArrayInterface.GetIndex
77-
ArrayInterface.SetIndex!
78-
```
23+
to the interface, and is likely to be deprecated in the near future as the compiler matures to automate a lot of its optimizations.

‎docs/src/indexing.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Julia's Extended Array Indexing Interface
2+
3+
The following ArrayInterface functions extend Julia's Base LinearAlgebra interface
4+
to improve the ability to write code for generic array types.
5+
6+
## Indexing Traits
7+
8+
The following traits allow for one to accurately determine the type of indexing allowed
9+
on arrays in order to write optimal code for generic array types.
10+
11+
```@docs
12+
ArrayInterface.can_avx
13+
ArrayInterface.can_change_size
14+
ArrayInterface.can_setindex
15+
ArrayInterface.fast_scalar_indexing
16+
ArrayInterface.ismutable
17+
ArrayInterface.ndims_index
18+
ArrayInterface.ndims_shape
19+
ArrayInterface.defines_strides
20+
ArrayInterface.ensures_all_unique
21+
ArrayInterface.ensures_sorted
22+
ArrayInterface.indices_do_not_alias
23+
ArrayInterface.instances_do_not_alias
24+
ArrayInterface.device
25+
```
26+
27+
## Allowed Indexing Functions
28+
29+
These are generic functions for forced "allowed indexing". For example, with CUDA.jl's
30+
CuArrays a mode can be enabled such that `allowscalar(false)` forces errors to be thrown
31+
if a GPU array is scalar indexed. Instead of using the CUDA-specific `CUDA.@allowscalar`
32+
on an operation, these functions allow for a general generic "allowed indexing" for all
33+
array types.
34+
35+
```@docs
36+
ArrayInterface.allowed_getindex
37+
ArrayInterface.allowed_setindex!
38+
```
39+
40+
## Indexing Type Buffers
41+
42+
The following indexing types allow for generically controlling bounds checking
43+
and index translations.
44+
45+
```@docs
46+
ArrayInterface.ArrayIndex
47+
ArrayInterface.GetIndex
48+
ArrayInterface.SetIndex!
49+
```

‎docs/src/linearalgebra.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Julia's Extended Linear Algebra Interface
2+
3+
The following ArrayInterface functions extend Julia's Base LinearAlgebra interface
4+
to improve the ability to do generic linear algebra.
5+
6+
## Generic Matrix Constructors
7+
8+
These functions allow for the construction of matrices from array information in a generic
9+
way. It handles cases like how if `x` is a vector on the GPU, its associated matrix type
10+
should also be GPU-based, and thus appropriately placed with zeros/undef values.
11+
12+
```@docs
13+
ArrayInterface.zeromatrix
14+
ArrayInterface.undefmatrix
15+
```
16+
17+
## Generic Matrix Functions
18+
19+
These query allow for easily learning properties of a general matrix.
20+
21+
```@docs
22+
ArrayInterface.issingular
23+
```
24+
25+
## Factorization Instance Functions
26+
27+
These functions allow for generating the instance of a factorization's result without
28+
running the full factorization. This thus allows for building types to hold the factorization
29+
without having to perform expensive extra computations.
30+
31+
```@docs
32+
ArrayInterface.lu_instance
33+
ArrayInterface.qr_instance
34+
ArrayInterface.svd_instance
35+
```
36+
37+
## Addtional Linear Algebra Interface Tools
38+
39+
If dealing with general linear algebra, consider:
40+
41+
- [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl): An extended linear solving library with support for generic arrays.

‎docs/src/sparsearrays.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Julia's Extended Sparse Array Interface
2+
3+
The following ArrayInterface functions extend Julia's Base LinearAlgebra interface
4+
to improve the ability to do sparse linear algebra.
5+
6+
## Sparse Indexing
7+
8+
These routines allow for improving sparse iteration and indexing.
9+
10+
```@docs
11+
ArrayInterface.isstructured
12+
ArrayInterface.findstructralnz
13+
ArrayInterface.has_sparsestruct
14+
```
15+
16+
## Matrix Coloring
17+
18+
Many routines require calculating the coloring of a matrix, such as for sparse
19+
differentation. The `matrix_colors` function is the high level function which
20+
returns a color vector `Vector{Int}` with the column colors. This function
21+
is overloaded for many special matrix types with analytical solutions for the
22+
matrix colors.
23+
24+
```@docs
25+
ArrayInterface.fast_matrix_colors
26+
ArrayInterface.matrix_colors
27+
```
28+
29+
### General Matrix Colors
30+
31+
For the general dispatch of `matrix_colors`, see [SparseDiffTools.jl](https://github.com/JuliaDiff/SparseDiffTools.jl)
32+
for a full graph-based coloring algorithm which extends ArrayInterface.
33+
34+
## Addtional Sparse Array Interface Tools
35+
36+
If dealing with general sparse arrays, consider:
37+
38+
- [SparseDiffTools.jl](https://github.com/JuliaDiff/SparseDiffTools.jl): A general set of tools for extending calculus libraries for sparse optimizations.
39+
- [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl): An extended linear solving library with support for generic sparse arrays.

‎docs/src/tuples.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Julia's Extended Tuple Interface
2+
3+
The following ArrayInterface functions extend Julia's tuple interface.
4+
5+
```@docs
6+
ArrayInterface.flatten_tuples
7+
ArrayInterface.map_tuple_type
8+
```

‎docs/src/wrapping.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Julia's Array Wrapping Interface
2+
3+
The following functions make it easier to handle array wrappers, such as `Adjoint`, which
4+
can obscure an underlying array's properties under a layer of indirection.
5+
6+
```@docs
7+
ArrayInterface.is_forwarding_wrapper
8+
ArrayInterface.buffer
9+
ArrayInterface.parent_type
10+
```
11+
12+
## Additional Array Wrapping Libraries
13+
14+
If dealing with array wrappers, additionally consider:
15+
16+
- [Adapt.jl](https://github.com/JuliaGPU/Adapt.jl): conversions for handling device (GPU) wrappers.

0 commit comments

Comments
 (0)