Missing documentation for LAPACK-related functions

[loiseaujc]

Hej,

First of all, congrats for the integration of blas and lapack into stdlib. I think it'll make things much easier from now on to develop an up-to-date scientific ecosystem in fortran.

In any case, it seems that the documentation hosted here is missing the bits about the new lapack-related capabilities.

As a side note, since FORD can handle LaTeX syntax, why hasn't this feature been used for the documentation of the different blas subroutines (at least when I look at the documentation online on my laptop, it does not seem like LaTeX has been used) ? Is there a particular reason or was it just out of simplicity ?

In any case, blas/lapack support is awesome and I'm looking forward to the future of stdlib.

[jvdp1]

thank you @loiseaujc for your comment.

In any case, it seems that the documentation hosted here is missing the bits about the new lapack-related capabilities.

Indeed, it is the case. The reason is that ford takes a long time to process all LAPACK files. See #783 and #784 for some discussions. Any suggestions on how to deal with this issue (or alternatives) are welcome.

As a side note, since FORD can handle LaTeX syntax, why hasn't this feature been used for the documentation of the different blas subroutines (at least when I look at the documentation online on my laptop, it does not seem like LaTeX has been used) ? Is there a particular reason or was it just out of simplicity ?

Thank you for the heads up. I don't thiink there is a particular reason to not use them (as it is already used in the specs). @perazz would it be possible to support this feature in your script?

[perazz]

Thanks @loiseaujc, @jvdp1 has already summarized it all. Couple comments from my side:

• I've been striving to improve good blas/lapack backends, and we get nice interfaces in turn, but our core aim is to provide higher-level APIs for algebra, so the documentation effort will be focused there. That said, if there are parts of the current documentation you don't like, please submit issues / contribute patches. See for example rotm, rotmg documentation #795 for usage of LaTeX in blas functions.
• Unfortunately @jvdp1, zero chance to automate the math part, because most of the LAPACK documentation is just text with variable math syntax (see here). So while for blas we have ~30 routines, it is doable to format them all with LaTeX where applicable, for lapack it will be a far larger effort. So I advise for the incremental improvement: let's keep improving the documentation gradually.
• @loiseaujc if you have more experience with FORD, and have ideas how we could improve our handling of the large documentation body, please let us know! Our main issue is that we cannot remove the individual implemenation files (DGETRF, SGETRF, CGETRF, ...) because when interface getrf refers them, FORD will search for the original function and crash. At the same time, keeping it all together means a huge source code (~0.6M lines of code) that is very slow to be parsed.

[loiseaujc]

I completely agree that the documentation effort should mainly be focused on the high-level API. I was asking simply out of curiosity (and personal pleasedness of having LaTeX-math in documentation). I can certainly help with writing this LaTeX documentation incrementally. I'm commuting a couple of hours per day and that is typically the kind of things I can do in the train every few days.
As for FORD, I have no idea ! I barely started to scratch its surface when writing the documentation for LightKrylov.

[perazz]

That is a great plan! Let's start parsing the BLAS interfaces, these are fewer and easier to start with.

[loiseaujc]

Practical questions : which branch should I fork ? master directly or the linear_algebra one (although it seems to be lagging behind) ?

[perazz]

Usually, a new branch is created for each PR, then is merged back into master when it is approved