Add _work (#15)

* preparation

* errors in the doc :/

* API change

* doc

Author: pierre-24

docs/about.md

@@ -4,6 +4,8 @@
 
 ## Overview
 
+**Note:** This project is in its early stages, and the API is not yet stable and may undergo changes.
+
 ### Motivation
 
 Using scaLAPACK directly in C presents several challenges:
@@ -19,8 +21,6 @@ This project addresses the first two issues by providing:
 
 The third issue (documentation) remains an ongoing challenge, reflecting a broader trend in netlib's projects that rely heavily on aging user guides and systematic function design.
 
-**Note:** This project is in its early stages, and the API is not yet stable and may undergo changes.
-
 For more information on how to use scaLAPACKe in practice, including common caveats, refer to the [Quickstart Guide](dev/quickstart.md). 
 A more beginner-friendly introduction to (sca)LAPACK(e) is also available [here](dev/tutorial.md).
 

docs/dev/quickstart.md

@@ -96,7 +96,8 @@ The middle-level interface requires all the headers and wrappers files provided
 ```
 
 The naming convention for this interface is as follows: take the Fortran routine name, convert it to lowercase, and prepend it with `SCALAPACKE_`. 
-For example, the Fortran routine `PDGEMM` becomes `SCALAPACKE_pdgemm`.
+If the routine requires an auxiliary workspace (`WORK`, `RWORK`, `IWORK`, etc), the suffix `_work` should be added.
+For example, the Fortran routine [`PDGEMM`](https://netlib.org/scalapack/explore-html/d6/da2/pdgemm___8c_source.html) becomes `SCALAPACKE_pdgemm`, and [`PDSYEV`](https://netlib.org/scalapack/explore-html/d0/d1a/pdsyev_8f_source.html) becomes `SCALAPACKE_pdsyev_work`.
 
 The `INFO` parameter found in the Fortran subroutine is omitted in scaLAPACKe. 
 Instead, the `lapack_int` return value of the function is set to the value that `INFO` would have returned.

docs/dev/tutorial.md

@@ -527,7 +527,7 @@ We will therefore make two calls: one to request the ideal size, the second to a
 ```c
 // request the size of `WORK` by setting `LWORK` to -1
 double tmpw;
-SCALAPACKE_pdsyev(
+SCALAPACKE_pdsyev_work(
   "N", "U", N, 
   loc_A, 1, 1, desc_A, 
   w, 
@@ -539,14 +539,19 @@ lapack_int lwork = (lapack_int) tmpw;
 // compute the eigenvalues, stored in `w`
 double* w = calloc(N, sizeof(double ));
 double* work = calloc(lwork, sizeof(double ));
-SCALAPACKE_pdsyev(
+SCALAPACKE_pdsyev_work(
   "N", "U", N, 
   loc_A, 1, 1, desc_A, // input matrix
   w, 
   NULL, 1, 1, desc_A,  // eigenvectors
   work, lwork);
 ```
 
+!!! info
+    
+    The `_work` suffix indicates that the workspace should be explicitly created.
+    In the future, there might be a version that automatically allocate and free the workspace(s), following [LAPACKe](https://netlib.org/lapack/lapacke.html).
+
 ### 4. Release!
 
 ![](https://media1.tenor.com/m/rFwzdbMTeAoAAAAd/card-captor-sakura-anime.gif)

docs/index.md

@@ -2,7 +2,7 @@
 
 This project provides a set of headers and wrappers designed to facilitate the use of [ScaLAPACK](https://www.netlib.org/scalapack/) and its components, [PBLAS](https://netlib.org/scalapack/pblas_qref.html) and [BLACS](https://netlib.org/blacs/), in C.
 
-Like [LAPACKE](https://netlib.org/lapack/lapacke.html), they are lightweight wrappers that streamline the integration of ScaLAPACK functionalities into C applications, [in a predictable way](dev/quickstart.md).
+Like [LAPACKe](https://netlib.org/lapack/lapacke.html), they are lightweight wrappers that streamline the integration of ScaLAPACK functionalities into C applications, [in a predictable way](dev/quickstart.md).
 
 Below is an example of using the wrapper to perform eigenvalue and eigenvector computations with `PDSYEV`:
 

include/pblas.h

@@ -12,6 +12,9 @@
 INT_TYPE = 'lapack_int'
 COMPLEX_TYPE = 'lapack_complex_float'
 COMPLEX16_TYPE = 'lapack_complex_double'
+LOWLEVEL_SUFFIX = '_'
+MIDLEVEL_WRK_SUFFIX = '_work'
+
 
 # pattern
 PATTERN_C_FUNC = re.compile(r'(?P<rtype>\w+) (?P<name>\w+)\((?P<params>.*)\)')
@@ -72,19 +75,31 @@ def to_complex(self):
 
 
 class Declaration:
+    """
+    Store a declaration.
+    Its arguments are all pointers.
+    """
+
     def __init__(self, name: str, return_type: str, arguments: List[DeclArgument]):
         self.name = name
         self.return_type = return_type
         self.arguments = arguments
 
-    def to_extern_c_decl(self) -> str:
+        self.has_work = any('WORK' in a.name for a in self.arguments)
+
+    def to_low_level_decl(self) -> str:
+        """Low-level API
+        """
         return 'extern {} {}({});'.format(
             self.return_type,
-            self.name,
+            self.name + LOWLEVEL_SUFFIX,
             ', '.join(a.to_c_arg() for a in self.arguments)
         )
 
-    def to_aliased_decl(self) -> str:
+    def to_mid_level_decl(self) -> str:
+        """Mid-level API
+        """
+
         arguments = self.arguments
         return_type = self.return_type
 
@@ -98,11 +113,13 @@ def to_aliased_decl(self) -> str:
         return '{} {}{}({});'.format(
             return_type,
             PREFIX,
-            self.name[:-1],
+            self.name + (MIDLEVEL_WRK_SUFFIX if self.has_work else ''),
             ', '.join(a.aliase().to_c_arg() for a in arguments)
         )
 
-    def to_aliased_wrapper(self) -> str:
+    def to_mid_level_wrapper(self) -> str:
+        """Mid-level API
+        """
         name = self.name
         has_info = False
         arguments = self.arguments
@@ -117,7 +134,7 @@ def to_aliased_wrapper(self) -> str:
         r = '{} {}{}({}) {{\n'.format(
             return_type,
             PREFIX,
-            name[:-1],
+            name + (MIDLEVEL_WRK_SUFFIX if self.has_work else ''),
             ', '.join(a.aliase().to_c_arg() for a in arguments),
         )
 
@@ -126,7 +143,7 @@ def to_aliased_wrapper(self) -> str:
 
         r += '    {}{}({}{});\n'.format(
             'return ' if self.return_type != 'void' else '',
-            name,
+            name + LOWLEVEL_SUFFIX,
             ', '.join('{}{}'.format('&' if x.aliasable() else '', x.name) for x in arguments),
             ', &INFO' if has_info else ''
         )

include/scalapack.h

@@ -27,7 +27,7 @@
 ]
 
 # pattern
-PATTERN_C_FUNC = re.compile(r'(?P<rtype>\w+) (?P<name>\w+)\((?P<args>.*)\)')
+PATTERN_C_FUNC = re.compile(r'(?P<rtype>\w+) (?P<name>\w+)_\((?P<args>.*)\)')
 PATTERN_C_ARG = re.compile(r'(?P<type>\w+) ?(?P<ptr>\*)? ?(?P<name>\w+)')
 PATTERN_ARG_DOC = re.compile(r'\s{1,3}\*\s{1,3}(?P<name>\w*)\s+\((?P<intent>.*)\)(?P<extra>.*)?')
 
@@ -39,64 +39,64 @@ def _p(inp: str, r: int = 0) -> DeclArgument:
 
 BLACS_DECLS = [
     # blacs*() functions do not come with a documentation, so manually handle them
-    Declaration('blacs_abort_', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('{}* ErrNo'.format(INT_TYPE))]),
-    Declaration('blacs_barrier_', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('char* scope')]),
-    Declaration('blacs_exit_', 'void', [_p('{}* NotDone'.format(INT_TYPE))]),
-    Declaration('blacs_freebuff_', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('{}* wait'.format(INT_TYPE))]),
-    Declaration('blacs_get_', 'void', [
+    Declaration('blacs_abort', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('{}* ErrNo'.format(INT_TYPE))]),
+    Declaration('blacs_barrier', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('char* scope')]),
+    Declaration('blacs_exit', 'void', [_p('{}* NotDone'.format(INT_TYPE))]),
+    Declaration('blacs_freebuff', 'void', [_p('{}* ConTxt'.format(INT_TYPE)), _p('{}* wait'.format(INT_TYPE))]),
+    Declaration('blacs_get', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE), ),
         _p('{}* what'.format(INT_TYPE)),
         _p('{}* val'.format(INT_TYPE), 1)
     ]),
-    Declaration('blacs_gridexit_', 'void', [_p('{}* ConTxt'.format(INT_TYPE))]),
-    Declaration('blacs_gridinfo_', 'void', [
+    Declaration('blacs_gridexit', 'void', [_p('{}* ConTxt'.format(INT_TYPE))]),
+    Declaration('blacs_gridinfo', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE)),
         _p('{}* nprow'.format(INT_TYPE), 1),
         _p('{}* npcol'.format(INT_TYPE), 1),
         _p('{}* myrow'.format(INT_TYPE), 1),
         _p('{}* mycol'.format(INT_TYPE), 1)
     ]),
-    Declaration('blacs_gridinit_', 'void', [
+    Declaration('blacs_gridinit', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE), 1),
         _p('char* order'),
         _p('{}* nprow'.format(INT_TYPE),),
         _p('{}* npcol'.format(INT_TYPE)),
     ]),
-    Declaration('blacs_gridmap_', 'void', [
+    Declaration('blacs_gridmap', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE), 1),
         _p('{}* usermap'.format(INT_TYPE), 1),
         _p('{}* ldup'.format(INT_TYPE)),
         _p('{}* nprow0'.format(INT_TYPE)),
         _p('{}* npcol0'.format(INT_TYPE)),
     ]),
-    Declaration('blacs_pcoord_', 'void', [
+    Declaration('blacs_pcoord', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE)),
         _p('{}* nodenum'.format(INT_TYPE)),
         _p('{}* prow'.format(INT_TYPE), 1),
         _p('{}* pcol'.format(INT_TYPE), 1)
     ]),
-    Declaration('blacs_pinfo_', 'void', [
+    Declaration('blacs_pinfo', 'void', [
         _p('{}* mypnum'.format(INT_TYPE), 1),
         _p('{}* nprocs'.format(INT_TYPE), 1),
     ]),
-    Declaration('blacs_pnum_', 'lapack_int', [
+    Declaration('blacs_pnum', 'lapack_int', [
         _p('{}* ConTxt'.format(INT_TYPE)),
         _p('{}* prow'.format(INT_TYPE)),
         _p('{}* pcol'.format(INT_TYPE))
     ]),
-    Declaration('blacs_set_', 'void', [
+    Declaration('blacs_set', 'void', [
         _p('{}* ConTxt'.format(INT_TYPE)),
         _p('{}* what'.format(INT_TYPE)),
         _p('{}* val'.format(INT_TYPE), 1)
     ]),
-    Declaration('blacs_setup_', 'void', [
+    Declaration('blacs_setup', 'void', [
         _p('{}* mypnum'.format(INT_TYPE), 1),
         _p('{}* nprocs'.format(INT_TYPE), 1),
     ]),
-    Declaration('blacs2sys_handle_', 'MPI_Comm', [
+    Declaration('blacs2sys_handle', 'MPI_Comm', [
         _p('{}* BlacsCtxt'.format(INT_TYPE))
     ]),
-    Declaration('sys2blacs_handle_', INT_TYPE, [
+    Declaration('sys2blacs_handle', INT_TYPE, [
         _p('MPI_Comm* SysCtxt')
     ]),
 ]