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]