[Boost-commit] svn:boost r58092 - in sandbox/numeric_bindings/libs/numeric/bindings/tools: . templates templates/level1

Subject: [Boost-commit] svn:boost r58092 - in sandbox/numeric_bindings/libs/numeric/bindings/tools: . templates templates/level1
From: rutger_at_[hidden]
Date: 2009-12-02 03:50:10

Author: rutger
Date: 2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
New Revision: 58092
URL: http://svn.boost.org/trac/boost/changeset/58092

Log:
Sync of numberic_bindings generators, improved documentation generation support

Text files modified: 
   sandbox/numeric_bindings/libs/numeric/bindings/tools/bindings.py               |    13 ++                                      
   sandbox/numeric_bindings/libs/numeric/bindings/tools/blas_generator.py         |    24 -----                                   
   sandbox/numeric_bindings/libs/numeric/bindings/tools/documentation.py          |   175 ++++++++++++++++++++++++++++++++++++++- 
   sandbox/numeric_bindings/libs/numeric/bindings/tools/lapack_generator.py       |    29 -----                                   
   sandbox/numeric_bindings/libs/numeric/bindings/tools/netlib.py                 |     7                                         
   sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/blas.qbk        |    45 ++++++---                               
   sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/lapack.qbk      |    46 +++++++---                              
   sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/level1/axpy.hpp |     2                                         
   8 files changed, 252 insertions(+), 89 deletions(-)

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/bindings.py
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/bindings.py	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/bindings.py	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -204,7 +204,10 @@
 
   for level, level_properties in routines.iteritems():
     content = ''
-    dest_file = dest_path + '/' + level + '.hpp'
+    postfix = '.hpp'
+    if template_map[ 'PARSERMODE' ] == 'LAPACK_DOC':
+        postfix = '.qbk'
+    dest_file = dest_path + '/' + level + postfix
 
     if template_map[ 'PARSERMODE' ] == 'BLAS':
       print "something"
@@ -219,8 +222,12 @@
             group_keys.sort()
 
             for r in group_keys:
-                content += '#include <boost/numeric/bindings/' + parsermode + '/' + level + \
-                    '/' + r.lower() + '.hpp>\n'
+                if template_map[ 'PARSERMODE' ] == 'LAPACK':
+                    content += '#include <boost/numeric/bindings/' + parsermode + '/' + level + \
+                        '/' + r.lower() + '.hpp>\n'
+                if template_map[ 'PARSERMODE' ] == 'LAPACK_DOC':
+                    content += '[include ' + level + \
+                        '/' + r.lower() + '.qbk]\n'
 
     result = template_map[ parsermode + '_include_hierarchy' ]
     result = result.replace( "$CONTENT", content )

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/blas_generator.py
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/blas_generator.py	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/blas_generator.py	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -292,27 +292,6 @@
 
 
 #
-# Write the many (low-level) documentation files
-#
-def write_documentation( info_map, group, template_map, base_dir ):
-
-    for group_name, subroutines in group.iteritems():
-        filename = group_name.lower() + '.qbk'
-        result = template_map[ 'blas.qbk' ]
-
-        result = result.replace( '$GROUPNAME', group_name )
-        result = result.replace( '$groupname', group_name.lower() )
-
-        result = result.replace( '$SUBROUTINES', documentation.readable_join( subroutines ) )
-
-        result = result.replace( '$header', 'boost/numeric/bindings/blas/' + group_name.lower() + '.hpp' )
-
-        result = result.replace( '$DISPATCH_TABLE', documentation.write_dispatch_table( subroutines, info_map ) )
-        result = result.replace( '$BLAS_FRIENDLY_NAME', documentation.blas_friendly_name( group_name, info_map, template_map ) )
-
-        open( os.path.join( base_dir, filename ), 'wb' ).write( result )
-
-#
 # Write the (many) driver routine test cases to cpp files.
 #
 def write_test_case( info_map, group, template_map, base_dir, level_name ):
@@ -343,6 +322,7 @@
   open( os.path.join( base_dir, filename ), 'wb' ).write( result )
 
 
+
 def read_templates( template_file ):
   file_contents = open( template_file ).read()
   split_regex = re.compile( '^\$TEMPLATE\[([^\]]+)\]\s', re.M | re.S )
@@ -438,6 +418,6 @@
   if level_properties.has_key( 'routines_by_value_type' ):
     print "has key..." 
     write_functions( function_info_map, level_properties[ 'routines_by_value_type' ], templates, impl_target_path )
-    write_documentation( function_info_map, level_properties[ 'routines_by_value_type' ], templates, doc_target_path )
+    documentation.write_documentation( function_info_map, level_properties[ 'routines_by_value_type' ], templates, doc_target_path )
 
 

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/documentation.py
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/documentation.py	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/documentation.py	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -8,7 +8,8 @@
 # http://www.boost.org/LICENSE_1_0.txt)
 #
 
-import re
+import bindings
+import os, re
 
 routine_value_type = \
     { 'C' : 'complex<float>',
@@ -33,7 +34,16 @@
     { 'MV' : ' matrix-vector operation',
       'MM' : ' matrix-matrix operation',
       'R' :  ' rank-1 update',
-      'R2' : ' rank-2 update'
+      'R2' : ' rank-2 update',
+      'RK' : ' rank-k update',
+      'R2K' : ' rank-2k update',
+      'SV'  : ' solve system of equations'
+    }
+
+number_to_text = \
+    { 2 :    'two',
+      3 :    'three',
+      4 :    'four'
     }
 
 def readable_join( some_tuple, last_word = "and" ):
@@ -45,20 +55,20 @@
     return ", ".join( some_tuple[:-1] ) + ", " + last_word + " " + some_tuple[-1]
 
 
-def write_dispatch_table( subroutines, info_map ):
+def write_blas_dispatch_table( subroutines, info_map ):
     result = ""
-    result += "[  [ Value type ] [BLAS routine] [CBLAS routine] [CUBLAS routine] ]\n"
+    result += "[  [ Value type of $FIRST_TYPENAME ] [BLAS routine] [CBLAS routine] [CUBLAS routine] ]\n"
     for subroutine in subroutines:
         cblas_routine = ''
         if 'cblas_routine' in info_map[ subroutine ]:
             cblas_routine = info_map[ subroutine ][ 'cblas_routine' ]
         else:
-            cblas_routine = 'Not available'
+            cblas_routine = 'Unavailable'
         cublas_routine = ''
         if 'cublas_routine' in info_map[ subroutine ]:
             cublas_routine = info_map[ subroutine ][ 'cublas_routine' ]
         else:
-            cublas_routine = 'Not available'
+            cublas_routine = 'Unavailable'
 
         result += "[  "
         result += "[`" + routine_value_type[ subroutine[0] ] + "`]"
@@ -70,13 +80,23 @@
     return result
 
 
+def write_lapack_dispatch_table( subroutines, info_map ):
+    result = ""
+    result += "[  [ Value type of $FIRST_TYPENAME ] [LAPACK routine] ]\n"
+    for subroutine in subroutines:
+        result += "[  "
+        result += "[`" + routine_value_type[ subroutine[0] ] + "`]"
+        result += "[" + subroutine + "]"
+        result += " ]\n"
+    return result
+
 
 
 def blas_friendly_name( group_name, info_map, template_map ):
 
     possible_key = group_name.lower() + ".friendly_name"
     if possible_key in template_map:
-        return template_map[ possible_key ]
+        return template_map[ possible_key ].strip()
 
     result = ""
 
@@ -91,3 +111,144 @@
 
     return result
 
+
+
+def combine_purposes( subroutines, info_map ):
+
+    purposes = []
+
+    for subroutine in subroutines:
+
+        purpose = info_map[ subroutine ][ 'purpose' ]
+        purpose = purpose.replace( subroutine, "`$groupname`" )
+        purpose = purpose.replace( '  ', ' ' )
+        purpose = purpose.replace( '  ', ' ' )
+        purpose = purpose.replace( '  ', ' ' )
+
+        #purpose = purpose.replace( ",   or", ", or\n  " )
+        #purpose = purpose.replace( "   or   ", ", or\n  " )
+
+        # strip spaces from the purpose
+        result = []
+        for line in purpose.splitlines():
+            result.append( line.strip() )
+        purpose = "\n".join( result )
+
+        # only add if there's something new
+        if purpose not in purposes:
+            purposes.append( purpose )
+
+
+    if len(purposes)>1:
+        print "UNMERGED: ", subroutines
+
+    return purposes[-1]
+
+
+
+
+
+#
+# Write the many (low-level) documentation files
+#
+def write_documentation( info_map, group, template_map, base_dir ):
+
+    parsermode = template_map[ 'PARSERMODE' ].lower()
+
+    for group_name, subroutines in group.iteritems():
+        filename = group_name.lower() + '.qbk'
+
+        result = template_map[ parsermode + '.qbk' ]
+
+        prototypes = []
+        first_typename = None
+        originating_sources = []
+        for subroutine in subroutines:
+            if parsermode == 'blas':
+                originating_sources.append( "[@http://www.netlib.org/blas/" +
+                    subroutine.lower() + ".f " + subroutine.lower() + ".f]" )
+            if parsermode == 'lapack':
+                originating_sources.append( "[@http://www.netlib.org/lapack/explore-html/" +
+                    subroutine.lower() + ".f.html " + subroutine.lower() + ".f]" )
+
+            level2_arg_list_pre = []
+            for arg in info_map[ subroutine ][ 'arguments' ]:
+                if info_map[ subroutine ][ 'argument_map' ][ arg ][ 'code' ][ 'level_2' ] != None:
+                    level2_arg_list_pre += [ info_map[ subroutine ][ 'argument_map' ][ arg ][ 'code' ][ 'level_2' ] ]
+
+            level2_arg_list = []
+            for arg in level2_arg_list_pre:
+                readable_arg = ''
+                if '::real_type' in arg:
+                    splitted = arg.split( "::real_type" )
+                    readable_arg = "Scalar" + splitted[1]
+                    if 'const' in arg:
+                        readable_arg = 'const ' + readable_arg
+                elif '::value_type' in arg:
+                    splitted = arg.split( "::value_type" )
+                    readable_arg = "Scalar" + splitted[1]
+                    if 'const' in arg:
+                        readable_arg = 'const ' + readable_arg
+                else:
+                    readable_arg = arg
+
+                if (first_typename == None ) and ('Vector' in arg or 'Matrix' in arg):
+                    first_typename = arg.replace( "const ", "" ).replace( "&", "" ).split(" ")[0]
+
+                level2_arg_list.append( readable_arg )
+
+
+            prototype = template_map[ parsermode + '_prototype.qbk' ]
+            prototype = prototype.replace( "$LEVEL2", ", ".join( level2_arg_list ) )
+
+            if prototype not in prototypes:
+                prototypes.append( prototype )
+
+        prototype_overloads = ''
+        if len(prototypes) == 1:
+            prototype_overloads = 'is one prototype of'
+        else:
+            prototype_overloads = 'are ' + number_to_text[ len(prototypes) ] + ' prototypes of'
+
+        prototypes = bindings.proper_indent( "\n".join( prototypes ) )
+
+        #prototypes.append( prototype )
+        result = result.replace( "$PROTOTYPES", prototypes )
+        result = result.replace( "$PROTOTYPE_OVERLOADS", prototype_overloads )
+        result = result.replace( "$ORIGINATING_SOURCES", readable_join( originating_sources ) )
+        result = result.replace( '$PURPOSE', combine_purposes( subroutines, info_map ) )
+
+        result = result.replace( '$SUBROUTINES', readable_join( subroutines ) )
+        result = result.replace( '$header', 'boost/numeric/bindings/' + parsermode + '/' + group_name.lower() + '.hpp' )
+
+        if parsermode == 'blas':
+            result = result.replace( '$DISPATCH_TABLE', write_blas_dispatch_table( subroutines, info_map ) )
+            result = result.replace( '$FRIENDLY_NAME', blas_friendly_name( group_name, info_map, template_map ) )
+        if parsermode == 'lapack':
+            result = result.replace( '$DISPATCH_TABLE', write_lapack_dispatch_table( subroutines, info_map ) )
+            #result = result.replace( '$FRIENDLY_NAME', lapack_friendly_name( group_name, info_map, template_map ) )
+
+        if first_typename != None:
+            result = result.replace( "$FIRST_TYPENAME", first_typename )
+        result = result.replace( '$GROUPNAME', group_name )
+        result = result.replace( '$groupname', group_name.lower() )
+        print "Writing " + base_dir + "/" + filename
+        open( os.path.join( base_dir, filename ), 'wb' ).write( result )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/lapack_generator.py
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/lapack_generator.py	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/lapack_generator.py	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -415,29 +415,6 @@
     open( os.path.join( base_dir, filename ), 'wb' ).write( result )
 
 #
-# Write the many (low-level) documentation files
-#
-def write_documentation( info_map, group, template_map, base_dir ):
-
-    for group_name, subroutines in group.iteritems():
-        filename = group_name.lower() + '.qbk'
-        result = template_map[ 'lapack.qbk' ]
-
-        result = result.replace( '$GROUPNAME', group_name )
-        result = result.replace( '$groupname', group_name.lower() )
-
-        result = result.replace( '$SUBROUTINES', documentation.readable_join( subroutines ) )
-
-        result = result.replace( '$header', 'boost/numeric/bindings/blas/' + group_name.lower() + '.hpp' )
-
-        result = result.replace( '$DISPATCH_TABLE', documentation.write_dispatch_table( subroutines, info_map ) )
-        #result = result.replace( '$BLAS_FRIENDLY_NAME', documentation.blas_friendly_name( group_name, info_map, template_map ) )
-
-        print "Writing " + base_dir + "/" + filename
-        open( os.path.join( base_dir, filename ), 'wb' ).write( result )
-
-
-#
 # Write the (many) driver routine test cases to cpp files.
 #
 def write_test_case( info_map, group, template_map, base_dir, level_name ):
@@ -588,7 +565,9 @@
 bindings.write_header( function_info_map, routines, templates, bindings_impl_target_path + 'detail/lapack.h' )
 
 bindings.write_include_hierarchy( function_info_map, routines, templates, bindings_impl_target_path )
-
+templates[ 'PARSERMODE' ] = 'LAPACK_DOC'
+bindings.write_include_hierarchy( function_info_map, routines, templates, bindings_doc_target_path )
+templates[ 'PARSERMODE' ] = 'LAPACK'
 
 for level, level_properties in routines.iteritems():
   impl_target_path = bindings_impl_target_path + level
@@ -607,7 +586,7 @@
   for problem_type, problem_properties in level_properties.iteritems():
     if problem_properties.has_key( 'routines_by_value_type' ):
       write_functions( function_info_map, problem_properties[ 'routines_by_value_type' ], templates, impl_target_path )
-      write_documentation( function_info_map, problem_properties[ 'routines_by_value_type' ], templates, doc_target_path )
+      documentation.write_documentation( function_info_map, problem_properties[ 'routines_by_value_type' ], templates, doc_target_path )
 
       #write_test_case( function_info_map, problem_properties[ 'routines_by_value_type' ], templates, test_target_path + level, level )
 

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/netlib.py
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/netlib.py	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/netlib.py	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -169,8 +169,9 @@
 
   if result != None:
     if properties[ 'value_type' ] == 'REAL' or properties[ 'value_type' ] == 'DOUBLE PRECISION':
-      result = result.replace( "real_type", "typename traits::type_traits< typename traits::$TYPEOF_FIRST_TYPENAME" + \
-        "_traits< $FIRST_TYPENAME >::value_type >::real_type" )
+      result = result.replace( "real_type", \
+        "typename traits::type_traits< typename traits::tensor_traits" + \
+        "< $FIRST_TYPENAME >::value_type >::real_type" )
     if properties[ 'value_type' ][ 0:7] == 'COMPLEX' or \
       properties[ 'value_type' ] == 'DOUBLE COMPLEX':
       result = result.replace( "value_type", "typename tensor_traits" + \
@@ -858,7 +859,7 @@
   # and stopping before the "Arguments" block.
   subroutine_purpose = ''
   if purpose_line_nr > 0 and arguments_line_nr > 0:
-    subroutine_purpose = "//" + "\n//".join( comments[ purpose_line_nr+3:arguments_line_nr-1 ] )
+    subroutine_purpose = "\n".join( comments[ purpose_line_nr+3:arguments_line_nr-1 ] )
 
   # try to see if we are overriding the arguments piece
   arguments_key = subroutine_group_name.lower() + '.' + subroutine_value_type + '.arguments'

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/blas.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/blas.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/blas.qbk	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -3,26 +3,24 @@
 [section x$GROUPNAME]
 
 [section Prototype]
+There $PROTOTYPE_OVERLOADS `$groupname` available, please see below.
+$PROTOTYPES
+
 [endsect]
 
 [section Description]
 
-Numeric_bindings routine $groupname, or $BLAS_FRIENDLY_NAME, is a value-type based
-dispatching routine to routines in BLAS. It's name, $groupname, is made
-up by stripping the first character from the BLAS routines 
-$SUBROUTINES.
-
-A $BLAS_FRIENDLY_NAME is defined as
-equation stuff here
-
-where A is a matrix with a symmetric data structure, B is a matrix, C is an
-integer containing ..., and x and y are vectors. 
-
-Compile-time dispatching of this routine is determind by the value type of tensor A,
-and should be the same type the numeric_bindings meta-function `typename tensor_traits<A>::value_type`.
-Table xx illustrates to which specific routines this dispatching will take place. 
+`$groupname` (short for $FRIENDLY_NAME) provides a C++
+interface to BLAS routines $SUBROUTINES. 
+$PURPOSE
+
+The selection of the BLAS routine is done during compile-time, 
+and is determined by the type of values contained in type `$FIRST_TYPENAME`.
+The type of values is obtained through the tensor-traits 
+type-definition `typename tensor_traits<$FIRST_TYPENAME>::value_type`.
+Table xx illustrates to which specific routinev this dispatching will take place. 
 
-[table x$GROUPNAME dispatching of routines
+[table Dispatching of $groupname.
 $DISPATCH_TABLE
 ]
 
@@ -34,6 +32,16 @@
 
 [section Parameters or Requirements on Types]
 
+[variablelist Parameters
+    [[MatrixA] [The definition of term 1]]
+    [[MatrixB] [The definition of term 2]]
+    [[MatrixC] [
+    The definition of term 3.
+
+    Definitions may contain paragraphs.
+    ]]
+]
+
 The tensor_traits<>::value_type of A, B, and C should be the same.
 Tensor C should be mutable.
 
@@ -63,7 +71,14 @@
 [endsect]
 
 [section See Also]
+
+* Originating Fortran source files $ORIGINATING_SOURCES at Netlib.
+
 [endsect]
 
 [endsect]
+$TEMPLATE[blas_prototype.qbk]
+``
+$groupname( $LEVEL2 );
+``
 $TEMPLATE[end]

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/lapack.qbk
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/lapack.qbk	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/lapack.qbk	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -3,26 +3,23 @@
 [section x$GROUPNAME]
 
 [section Prototype]
+There $PROTOTYPE_OVERLOADS `$groupname` available, please see below.
+$PROTOTYPES
 [endsect]
 
 [section Description]
 
-Numeric_bindings routine $groupname, or $BLAS_FRIENDLY_NAME, is a value-type based
-dispatching routine to routines in BLAS. It's name, $groupname, is made
-up by stripping the first character from the BLAS routines 
-$SUBROUTINES.
-
-A $BLAS_FRIENDLY_NAME is defined as
-equation stuff here
-
-where A is a matrix with a symmetric data structure, B is a matrix, C is an
-integer containing ..., and x and y are vectors. 
-
-Compile-time dispatching of this routine is determind by the value type of tensor A,
-and should be the same type the numeric_bindings meta-function `typename tensor_traits<A>::value_type`.
+`$groupname` (short for $FRIENDLY_NAME) provides a C++
+interface to LAPACK routines $SUBROUTINES. 
+$PURPOSE
+
+The selection of the LAPACK routine is done during compile-time, 
+and is determined by the type of values contained in type `$FIRST_TYPENAME`.
+The type of values is obtained through the tensor-traits 
+type-definition `typename tensor_traits<$FIRST_TYPENAME>::value_type`.
 Table xx illustrates to which specific routines this dispatching will take place. 
 
-[table x$GROUPNAME dispatching of routines
+[table Dispatching of $groupname
 $DISPATCH_TABLE
 ]
 
@@ -34,6 +31,16 @@
 
 [section Parameters or Requirements on Types]
 
+[variablelist Parameters
+    [[MatrixA] [The definition of term 1]]
+    [[MatrixB] [The definition of term 2]]
+    [[MatrixC] [
+    The definition of term 3.
+
+    Definitions may contain paragraphs.
+    ]]
+]
+
 The tensor_traits<>::value_type of A, B, and C should be the same.
 Tensor C should be mutable.
 
@@ -63,7 +70,18 @@
 [endsect]
 
 [section See Also]
+
+* Originating Fortran source files $ORIGINATING_SOURCES at Netlib.
+
 [endsect]
 
 [endsect]
+$TEMPLATE[lapack_doc_include_hierarchy]
+
+$CONTENT
+
+$TEMPLATE[lapack_prototype.qbk]
+``
+$groupname( $LEVEL2 );
+``
 $TEMPLATE[end]

Modified: sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/level1/axpy.hpp
==============================================================================
--- sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/level1/axpy.hpp	(original)
+++ sandbox/numeric_bindings/libs/numeric/bindings/tools/templates/level1/axpy.hpp	2009-12-02 03:50:07 EST (Wed, 02 Dec 2009)
@@ -12,4 +12,6 @@
  Y        (output) DATATYPE array of length (N)
 $TEMPLATE[axpy.all.cblas_alias]
 A,ALPHA
+$TEMPLATE[axpy.friendly_name]
+a times x plus y
 $TEMPLATE[end]