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')
     ]),
 ]

include/scalapacke.h

@@ -146,16 +146,16 @@ def _mkargs_trmr2d(ctype: str):
 
 
 DECLS_REDIST = [
-    Declaration('pcgemr2d_', 'void', _mkargs_gemr2d('{}*'.format(COMPLEX_TYPE))),
-    Declaration('pdgemr2d_', 'void', _mkargs_gemr2d('double*')),
-    Declaration('pigemr2d_', 'void', _mkargs_gemr2d('{}*'.format(INT_TYPE))),
-    Declaration('psgemr2d_', 'void', _mkargs_gemr2d('float*')),
-    Declaration('pzgemr2d_', 'void', _mkargs_gemr2d('{}*'.format(COMPLEX16_TYPE))),
-    Declaration('pctrmr2d_', 'void', _mkargs_trmr2d('{}*'.format(COMPLEX_TYPE))),
-    Declaration('pdtrmr2d_', 'void', _mkargs_trmr2d('double*')),
-    Declaration('pitrmr2d_', 'void', _mkargs_trmr2d('{}*'.format(INT_TYPE))),
-    Declaration('pstrmr2d_', 'void', _mkargs_trmr2d('float*')),
-    Declaration('pztrmr2d_', 'void', _mkargs_trmr2d('{}*'.format(COMPLEX16_TYPE))),
+    Declaration('pcgemr2d', 'void', _mkargs_gemr2d('{}*'.format(COMPLEX_TYPE))),
+    Declaration('pdgemr2d', 'void', _mkargs_gemr2d('double*')),
+    Declaration('pigemr2d', 'void', _mkargs_gemr2d('{}*'.format(INT_TYPE))),
+    Declaration('psgemr2d', 'void', _mkargs_gemr2d('float*')),
+    Declaration('pzgemr2d', 'void', _mkargs_gemr2d('{}*'.format(COMPLEX16_TYPE))),
+    Declaration('pctrmr2d', 'void', _mkargs_trmr2d('{}*'.format(COMPLEX_TYPE))),
+    Declaration('pdtrmr2d', 'void', _mkargs_trmr2d('double*')),
+    Declaration('pitrmr2d', 'void', _mkargs_trmr2d('{}*'.format(INT_TYPE))),
+    Declaration('pstrmr2d', 'void', _mkargs_trmr2d('float*')),
+    Declaration('pztrmr2d', 'void', _mkargs_trmr2d('{}*'.format(COMPLEX16_TYPE))),
 ]
 
 
@@ -172,7 +172,7 @@ def find_f_decl(lines: List[str]) -> Declaration:
 
         args_list.append(DeclArgument(arg_name, arg_ctype, is_array=arg_is_array))
 
-    return Declaration(name.lower() + '_', rtype, args_list)
+    return Declaration(name.lower(), rtype, args_list)
 
 
 def find_decl(path: pathlib.Path) -> Declaration:
@@ -244,17 +244,6 @@ def find_decl(path: pathlib.Path) -> Declaration:
                     if 'workspace' in match_arg_doc['intent'].lower():
                         # `WORK`
                         arg.is_output = True
-                    if match_arg_doc['extra'] is not None:
-                        if 'complex' in match_arg_doc['extra'].lower():
-                            arg.is_complex = True
-                            arg.to_complex()
-                        # normally, that is useless, since the parser already recognize arrays
-                        if 'array' in match_arg_doc['extra'].lower():
-                            arg.is_array = True
-                        if 'pointer into the local' in match_arg_doc['extra'].lower():
-                            arg.is_array = True
-                        if 'pointer into local' in match_arg_doc['extra'].lower():
-                            arg.is_array = True
 
                     try:
                         for a in ARG_FOLLOW[path.name][arg_name]:

include/scalapacke_pblas.h

@@ -11,7 +11,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_extern_c_decl() }}
+{{ declaration.to_low_level_decl() }}
 {%- endfor %}
 
 #ifdef __cplusplus

scalapacke_files_create/base.py

@@ -10,7 +10,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_extern_c_decl() }}
+{{ declaration.to_low_level_decl() }}
 {%- endfor %}
 
 #ifdef __cplusplus

scalapacke_files_create/create_cblacs.py

@@ -10,7 +10,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_extern_c_decl() }}
+{{ declaration.to_low_level_decl() }}
 {%- endfor %}
 
 #endif // HEADER_SCALAPACK_H

scalapacke_files_create/create_scalapack.py

@@ -1,5 +1,5 @@
 #include "scalapacke.h"
 
 {% for declaration in declarations_f %}
-{{ declaration.to_aliased_wrapper() }}
+{{ declaration.to_mid_level_wrapper() }}
 {% endfor %}

scalapacke_files_create/templates/blacs.h.j2

@@ -10,7 +10,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_aliased_decl() }}
+{{ declaration.to_mid_level_decl() }}
 {%- endfor %}
 
 #ifdef __cplusplus

scalapacke_files_create/templates/pblas.h.j2

@@ -1,5 +1,5 @@
 #include "scalapacke_blacs.h"
 
 {% for declaration in declarations_f %}
-{{ declaration.to_aliased_wrapper() }}
+{{ declaration.to_mid_level_wrapper() }}
 {% endfor %}

scalapacke_files_create/templates/scalapack.h.j2

@@ -10,7 +10,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_aliased_decl() }}
+{{ declaration.to_mid_level_decl() }}
 {%- endfor %}
 
 #ifdef __cplusplus

scalapacke_files_create/templates/scalapacke.c.j2

@@ -1,5 +1,5 @@
 #include "scalapacke_pblas.h"
 
 {% for declaration in declarations_f %}
-{{ declaration.to_aliased_wrapper() }}
+{{ declaration.to_mid_level_wrapper() }}
 {% endfor %}

scalapacke_files_create/templates/scalapacke.h.j2

@@ -10,7 +10,7 @@ extern "C" {
 /* Declarations
  */
 {%- for declaration in declarations_f %}
-{{ declaration.to_aliased_decl() }}
+{{ declaration.to_mid_level_decl() }}
 {%- endfor %}
 
 #ifdef __cplusplus