LinearAlgebra.BLAS: sort and group blas functions (JuliaLang#46035)

* stdlib: LinearAlgebra.BLAS: sort and group blas lv1 functions

* stdlib: LinearAlgebra.BLAS: sort and group blas lv2 functions

* stdlib: LinearAlgebra.BLAS: sort and group blas lv3 functions

Co-authored-by: Viral B. Shah <[email protected]>

stdlib/LinearAlgebra/docs/src/index.md

@@ -527,67 +527,124 @@ the input argument belongs on (`side`). The possibilities are:
 | `'N'` | The diagonal values of the matrix `X` will be read. |
 | `'U'` | The diagonal of the matrix `X` is assumed to be all ones. |
 
+
 ```@docs
 LinearAlgebra.BLAS
+LinearAlgebra.BLAS.set_num_threads
+LinearAlgebra.BLAS.get_num_threads
+```
+
+BLAS functions can be divided into three groups, also called three levels,
+depending on when they were first proposed, the type of input parameters,
+and the complexity of the operation.
+
+### Level 1 BLAS functions
+
+The level 1 BLAS functions were first proposed in [(Lawson, 1979)][Lawson-1979] and
+define operations between scalars and vectors.
+
+[Lawson-1979]: https://dl.acm.org/doi/10.1145/355841.355847
+
+```@docs
+# xROTG
+# xROTMG
 LinearAlgebra.BLAS.rot!
+# xROTM
+# xSWAP
+LinearAlgebra.BLAS.scal!
+LinearAlgebra.BLAS.scal
+LinearAlgebra.BLAS.blascopy!
+LinearAlgebra.BLAS.axpy!
+LinearAlgebra.BLAS.axpby!
 LinearAlgebra.BLAS.dot
 LinearAlgebra.BLAS.dotu
 LinearAlgebra.BLAS.dotc
-LinearAlgebra.BLAS.blascopy!
+# xxDOT
 LinearAlgebra.BLAS.nrm2
 LinearAlgebra.BLAS.asum
-LinearAlgebra.BLAS.axpy!
-LinearAlgebra.BLAS.axpby!
-LinearAlgebra.BLAS.scal!
-LinearAlgebra.BLAS.scal
 LinearAlgebra.BLAS.iamax
-LinearAlgebra.BLAS.ger!
-LinearAlgebra.BLAS.syr!
-LinearAlgebra.BLAS.spr!
-LinearAlgebra.BLAS.syrk!
-LinearAlgebra.BLAS.syrk
-LinearAlgebra.BLAS.syr2k!
-LinearAlgebra.BLAS.syr2k
-LinearAlgebra.BLAS.her!
-LinearAlgebra.BLAS.herk!
-LinearAlgebra.BLAS.herk
-LinearAlgebra.BLAS.her2k!
-LinearAlgebra.BLAS.her2k
+```
+
+### Level 2 BLAS functions
+
+The level 2 BLAS functions were published in [(Dongarra, 1988)][Dongarra-1988],
+and define matrix-vector operations.
+
+[Dongarra-1988]: https://dl.acm.org/doi/10.1145/42288.42291
+
+**return a vector**
+```@docs
+LinearAlgebra.BLAS.gemv!
+LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any, ::Any)
+LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.gbmv!
 LinearAlgebra.BLAS.gbmv
+LinearAlgebra.BLAS.hemv!
+LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any, ::Any)
+LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any)
+# hbmv!, hbmv
+LinearAlgebra.BLAS.hpmv!
+LinearAlgebra.BLAS.symv!
+LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any, ::Any)
+LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.sbmv!
 LinearAlgebra.BLAS.sbmv(::Any, ::Any, ::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.sbmv(::Any, ::Any, ::Any, ::Any)
+LinearAlgebra.BLAS.spmv!
+LinearAlgebra.BLAS.trmv!
+LinearAlgebra.BLAS.trmv
+# xTBMV
+# xTPMV
+LinearAlgebra.BLAS.trsv!
+LinearAlgebra.BLAS.trsv
+# xTBSV
+# xTPSV
+```
+
+**return a matrix**
+```@docs
+LinearAlgebra.BLAS.ger!
+# xGERU
+# xGERC
+LinearAlgebra.BLAS.her!
+# xHPR
+# xHER2
+# xHPR2
+LinearAlgebra.BLAS.syr!
+LinearAlgebra.BLAS.spr!
+# xSYR2
+# xSPR2
+```
+
+### Level 3 BLAS functions
+
+The level 3 BLAS functions were published in [(Dongarra, 1990)][Dongarra-1990],
+and define matrix-matrix operations.
+
+[Dongarra-1990]: https://dl.acm.org/doi/10.1145/77626.79170
+
+```@docs
 LinearAlgebra.BLAS.gemm!
 LinearAlgebra.BLAS.gemm(::Any, ::Any, ::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.gemm(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.gemv!
-LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.gemv(::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.symm!
 LinearAlgebra.BLAS.symm(::Any, ::Any, ::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.symm(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.symv!
-LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.symv(::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.spmv!
 LinearAlgebra.BLAS.hemm!
 LinearAlgebra.BLAS.hemm(::Any, ::Any, ::Any, ::Any, ::Any)
 LinearAlgebra.BLAS.hemm(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.hemv!
-LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.hemv(::Any, ::Any, ::Any)
-LinearAlgebra.BLAS.hpmv!
+LinearAlgebra.BLAS.syrk!
+LinearAlgebra.BLAS.syrk
+LinearAlgebra.BLAS.herk!
+LinearAlgebra.BLAS.herk
+LinearAlgebra.BLAS.syr2k!
+LinearAlgebra.BLAS.syr2k
+LinearAlgebra.BLAS.her2k!
+LinearAlgebra.BLAS.her2k
 LinearAlgebra.BLAS.trmm!
 LinearAlgebra.BLAS.trmm
 LinearAlgebra.BLAS.trsm!
 LinearAlgebra.BLAS.trsm
-LinearAlgebra.BLAS.trmv!
-LinearAlgebra.BLAS.trmv
-LinearAlgebra.BLAS.trsv!
-LinearAlgebra.BLAS.trsv
-LinearAlgebra.BLAS.set_num_threads
-LinearAlgebra.BLAS.get_num_threads
 ```
 
 ## LAPACK functions

stdlib/LinearAlgebra/src/blas.jl

@@ -9,44 +9,60 @@ import Base: copyto!
 using Base: require_one_based_indexing, USE_BLAS64
 
 export
+# Note: `xFUNC_NAME` is a placeholder for not exported BLAS fucntions
+# ref: http:https://www.netlib.org/blas/blasqr.pdf
 # Level 1
- asum,
+ # xROTG
+ # xROTMG
+ rot!,
+ # xROTM
+ # xSWAP
+ scal!,
+ scal,
+ blascopy!,
  axpy!,
  axpby!,
- blascopy!,
+ # xDOT
  dotc,
  dotu,
- rot!,
- scal!,
- scal,
+ # xxDOT
  nrm2,
+ asum,
  iamax,
 # Level 2
- gbmv!,
- gbmv,
  gemv!,
  gemv,
+ gbmv!,
+ gbmv,
  hemv!,
  hemv,
+ # xHBMV
  hpmv!,
+ symv!,
+ symv,
  sbmv!,
  sbmv,
  spmv!,
- spr!,
- symv!,
- symv,
- trsv!,
- trsv,
  trmv!,
  trmv,
+ # xTBMV
+ # xTPMV
+ trsv!,
+ trsv,
+ # xTBSV
+ # xTPSV
  ger!,
- syr!,
+ # xGERU
+ # xGERC
  her!,
+ # xHPR
+ # xHER2
+ # xHPR2
+ syr!,
+ spr!,
+ # xSYR2
+ # xSPR2
 # Level 3
- herk!,
- herk,
- her2k!,
- her2k,
  gemm!,
  gemm,
  symm!,
@@ -55,8 +71,12 @@ export
  hemm,
  syrk!,
  syrk,
+ herk!,
+ herk,
  syr2k!,
  syr2k,
+ her2k!,
+ her2k,
  trmm!,
  trmm,
  trsm!,