Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing documentation for LAPACK-related functions #799

Open
loiseaujc opened this issue Apr 13, 2024 · 7 comments
Open

Missing documentation for LAPACK-related functions #799

loiseaujc opened this issue Apr 13, 2024 · 7 comments

Comments

@loiseaujc
Copy link

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
Copy link
Member

jvdp1 commented Apr 14, 2024

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
Copy link
Contributor

perazz commented Apr 15, 2024

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
Copy link
Author

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
Copy link
Contributor

perazz commented Apr 15, 2024

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

@loiseaujc
Copy link
Author

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

@perazz
Copy link
Contributor

perazz commented Apr 16, 2024

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

@perazz
Copy link
Contributor

perazz commented Aug 19, 2024

@loiseaujc @jvdp1 this seems to have been addressed in #784 #786, should we close this issue?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants