How to know the usage of undocumented function like LinearAlgebra`BLAS?

Question

BLAS is not documented in mathematica. Using

 ?LinearAlgebra`BLAS`*

gives

But None of the function has a detailed usage information

Click any of the function for example, GEMM, gives

At first I thought, BLAS in mma is belong to MKL, so I look up the usage in MKL reference manual, it says

call gemm ( a ,  b ,  c [ , transa ][ , transb ] [ , alpha ][ , beta ])

the last four parameters are all optional. But in fact, if I run

LinearAlgebra`BLAS`GEMM[a, b, c]

mma tells me, it needs 7 arguments

LinearAlgebraBLASGEMM::argrx: LinearAlgebraBLASGEMM called with 3 arguments; 7 arguments are expected.

if I run

LinearAlgebra`BLAS`GEMM[a, b, c, "N", "N", 1., 0.]

mma tells

LinearAlgebraBLASGEMM::blnsetst: The argument a at position 1 is not a string starting with one of the letters from the set NTCntc.

so the order of the arguments is not the same as MKL reference!!

How should I know the correct order of arguments without trying several times? Are there detailed usage information of undocumented function can be found inside mma?

I was wondering if we could extract usage from the content of the message tag like argrx or blnsetst ? But I don't know how to do it.

What do you expect? Really? We call them "internal functions" because they're not System` functions. Their usage might change, etc. -- Personally, I think Oleksandr R. showed the way to those who are not adverse to work. Perhaps it's a coincidence, but the documentation for GEMM indicates 7 arguments. Someone who is truly curious would follow that up. — Michael E2, Nov 26 '15 at 02:00
@MichaelE2 But as I said, the order of the argument is shuffled by mma, not the same as MKL reference. Maybe Mathematica trying its best to prevent user from using undocumented... — matheorem, Nov 26 '15 at 02:03
@MichaelE2 Hi, MichaelE2. Do you think it is possible to extract information from the message tag? If we gather all the content in the message tag, we know the usage, I don't know how to do it — matheorem, Nov 26 '15 at 02:17
"But as I said, the order of the argument is shuffled by mma" -- now you question says it, after the edit! — Michael E2, Nov 26 '15 at 02:17
LinearAlgebra`BLAS`GEMM["N", "N", 2, a, b, 3., c] -- it doesn't seem that hard to figure out, given the several paradigms of the ?gemm functions.... — Michael E2, Nov 26 '15 at 02:32
"How to know the usage" - trial and error, with some help from being familiar with how the original FORTRAN routines are invoked. I presume you'll then ask about LinearAlgebra`LAPACK`* after this? — J. M.'s missing motivation, Nov 26 '15 at 04:18
@J.M. Well, I am just let BLAS as an example. I am actually asking the general solution. If you look into the "?LinearAlgebra*", you can find more undocumented function, like.XSimplex`, what is this? I have no idea. I know many guys (of course including you : ) ) on this site know the usage of many undocumented function, I am curious, how they know it? — matheorem, Nov 26 '15 at 17:10
"I am curious, how they know it?" - I already answered that question in my first comment. Trial and error. Why not try different permutations of the arguments until you see something that works, while letting error messages or unevaluated output guide you in choosing which permutation to do next? — J. M.'s missing motivation, Nov 26 '15 at 17:15
@J.M. ok，i know. but for xsimplex, i even don't know what it is. how to try it? — matheorem, Nov 26 '15 at 17:23
It happens to be a simplex algorithm solver for LP problems, but why would one specifically need to know about it or use it? Especially since there are documented ways to do the same thing. — ilian, Nov 26 '15 at 22:49

ilian · Accepted Answer · 2017-09-15T15:35:06.047

Update

Leaving my old answer below for historical reference, however as of version 11.2.0 (currently available on Wolfram Cloud and soon to be released as a desktop product) the low-level linear algebra functions have been documented, see

http://reference.wolfram.com/language/LowLevelLinearAlgebra/guide/BLASGuide.html

The comments by both Michael E2 and J. M. ♦ are already an excellent answer, so this is just my attempt at summarizing.

Undocumented means just what it says: there need not be any reference pages or usage messages, or any other kind of documentation. There are many undocumented functions and if you follow MSE regularly, you will encounter them often. Using such functionality, however, is not without its caveats.

Sometimes, functions (whether documented or undocumented) are written in top-level (Mathematica, or if you will, Wolfram Language) code, so one can inspect the actual implementation by spelunking. However, that is not the case for functions implemented in C as part of the kernel.

Particularly for the LinearAlgebra`BLAS` interface, the function signatures are kept quite close to the well-established FORTRAN conventions (which is also what MKL adheres to, see the guide for ?gemm) with a few non-surprising adjustments. For instance, consider

xGEMM( TRANSA, TRANSB, M, N, K, ALPHA, A, LDA, B, LDB, BETA, C, LDC )

and the corresponding syntax for LinearAlgebra`BLAS`GEMM which is

GEMM[ transa, transb, alpha, a, b, beta, c ]

where we can see the storage-related parameters such as dimensions and strides are omitted, since the kernel already knows how the matrices are laid out in memory. All other arguments are the same, and even come in the same order.

As an usage example,

a = {{1, 2}, {3, 4}}; b = {{5, 6}, {7, 8}}; c = b; (* c will be overwritten *)
LinearAlgebra`BLAS`GEMM["T", "N", -2, a, b, 1/2, c]; c

(* {{-(99/2), -57}, {-(145/2), -84}} *)

-2 Transpose[a].b + (1/2) b

(* {{-(99/2), -57}, {-(145/2), -84}} *)

Note that for machine precision matrices, Dot will end up calling the corresponding optimized xgemm function from MKL anyway, so I would not expect a big performance difference. It is certainly much more readable and easier to use Dot rather than GEMM for matrix multiplication.

On the topic of BLAS in Mathematica, I would also recommend the 2003 developer conference talk by Zbigniew Leyk, which has some further implementation details and examples.

Thank you so much! especially for providing the conference talk by Zbigniew Leyk, learned a lot. I also add a comment to Simon Woods about why PrintDefinitions@Dot doesn't show any trace to BLAS. Do you have any idea? — matheorem, Nov 28 '15 at 09:04
And there is a strange thing I noticed. According to the conference talk. Mathematica optimized Dot with BLAS. But they didn't optimize Outer with BLAS!!! The GER in BLAS can do Outer of two vectors with Times operation much faster than current Outer in mma(40 times faster I tested). Though I know Outer can do much more. But they should have add an internal optimized branch to this most frequent encountered case. — matheorem, Nov 28 '15 at 09:08
@matheorem The BLAS functions are implemented in C, so there are no top-level definitions that can be read. Outer is already optimized for Times and packed array input. — ilian, Nov 28 '15 at 16:38
Odd enough. Yesterday, I use PrintDefinitions@Dot, and see a lot of output. But today I can only see output Attributes[Dot] := {Flat, OneIdentity, Protected};. Don't know which option I have triggered yesterday... — matheorem, Nov 29 '15 at 12:57
@matheorem You probably used some of the Parallel* functions (e.g. LaunchKernels[]) which do attach a few UpValues to Dot. But that has nothing to do with the actual implementation of Dot... — ilian, Nov 29 '15 at 16:24
Oh, my goodness. How do you know I turned on LaunchKernels[], you are amazing. BTW, I now understand LinearAlgebraBLASas an interface mma write for C implemented BLAS, While `Dot` is actually calling C implementation directly instead of calling `LinearAlgebra`BLA, so there is no definition shown in PrintDefinitions, am I right? — matheorem, Nov 30 '15 at 00:55

score 13 · Answer 2 · answered Nov 26 '15 at 22:20

How should I know the correct order of arguments without trying several times?

You can't, usually. A lot of the undocumented usage that you see on this site will have been worked out by trial and error. Sometimes it is fruitless - I have explored plenty of interesting-sounding internal functions and got nowhere.

Are there detailed usage information of undocumented function can be found inside mma?

No. "Undocumented" rather implies the absence of detailed usage information :-)

I was wondering if we could extract usage from the content of the message tag like argrx or blnsetst?

Sometimes the message will help, for example by stating how many or what type of argument was expected, but there is no hidden usage information. The message you see is all there is.

Some other comments

Sometimes you can read the function's code. For example using PrintDefinitions:

Needs["GeneralUtilities`"]
PrintDefinitions[Export];

Sometimes you cannot read the function's code but you see it being used inside another function which you can read - for example SystemException in the previous output. This can help in working out how and why to use it.

Often the function's name is a big help. Image`DogVision is undocumented but you can probably guess what it does and that it expects an image as its argument.

Other than that it tends to be a question of how patient you are and how badly you want to know.

@bloch, note that this is also a capability of Alpha; I guess this is the function being used behind the scenes. — J. M.'s missing motivation, Nov 27 '15 at 01:58
Thank you very much! PrintDefinitions seems so useful, didn't know this before. It is a pity that PrintDefinitions gives nothing on LinearAlgebra`BLAS`GEMM. But as ilian has answered and I also test it before. Dot is almost the same speed as GEMM, But is Dot really end up with calling MKL? In the output of PrintDefinitions[Dot], I can't find anything related to BLAS. What do you think? — matheorem, Nov 28 '15 at 06:04

How to know the usage of undocumented function like LinearAlgebra`BLAS?

2 Answers2

Linked

Related