Add in-code documentation

[loiseaujc]

We need to document the critical subroutines. I suggest we follow what you've done (@ricardofrantz) for the GMRES, CG and BiCGSTAB solvers.

[ricardofrantz]

Hi JC, some recent updates to the documentation branch:

main function headers, improved some allocation to prevent compiler warnings, eliminated unused variables and started integration wth stdlib_error and stdlib_logging, currently applied only to the GMRES function as a pilot for understanding functionality.

Discussion Points:

• Error Handling convention: Need to standardize how errors are reported and handled.
• Logging Levels: To identify the granularity of logging information, the several available options are: none_level, debug_level, information_level, warning_level, error_level, io_error_level, text_error_level, all_level.

Maybe the more useful are

1. none_level (Verbosity=0): Suppresses all logging. Effective when no output is desired.
2. error_level (Verbosity=1): Captures crucial error messages that could halt program execution.
3. warning_level (Verbosity=2): potential issues that warrant attention but are not critical.
4. information_level (Verbosity=3): Logs operational statuses without the intricate details.
5. debug_level (Verbosity=4): Logs detailed messages.

I think this is too complicated, and we only need 3 categories: nothing, info and debug. verbosity 1 2 and 3 or 0 1 2.

Also for now we are returning info = -1 for error and info = 0 for success. How about:

• info < 0: Argument errors, e.g., -6 implies an error in the 6th argument. (structural error)
• info = 0: No errors encountered. (sucess)
• info > 0: Error occurs during the i-th iteration. (numerical error)

Also, I am still randomly seeing this problem:

--------------------------------------------------
+ Starting SVD Singular Values ... (1/1)
--------------------------------------------------
      ... SVD Singular Values [FAILED]
      Message: Logical value mismatch
               expected 'T' but received 'F'

[loiseaujc]

Regarding the SVD error: it has to do with the precision which is too tight (1.0D-12). This isn't much of a problem. We only need a quick fix for the test (or there may be a more subtle bug in the implementation but I don't think so).

As for the logging: none_level, error_level are definitely needed. I am not sure about the warning_level or the debug_level. Which info would you output for the debug_level?

Regarding info, I agree that we could stick to the BLAS/LAPACK standard. We need to find a way though for Krylov methods to return information about the computation. I'm mostly thinking of the number of calls to matvec or the size of the computed Krylov subspace if the residual reaches our tolerance (remember that the whole Krylov subspace is pre-allocated ahead of time). Other pieces of information might also be useful in some cases, albeit I don't have a particular idea in mind yet.