Merge pull request #180 from kknox/hide-the-meta

Hide the meta & API refactoring 👍

Author: Kent Knox

CMakeLists.txt

@@ -38,7 +38,7 @@ endif()
 if( POLICY CMP0048 )
   cmake_policy( SET CMP0048 NEW )
 
-  project( SuperBuild.clSPARSE VERSION 0.9.0.0 )
+  project( SuperBuild.clSPARSE VERSION 0.10.0.0 )
 else( )
   project( SuperBuild.clSPARSE )
 
@@ -48,7 +48,7 @@ else( )
   endif( )
 
   if( NOT DEFINED SuperBuild.clSPARSE_VERSION_MINOR )
-    set( SuperBuild.clSPARSE_VERSION_MINOR 9 )
+    set( SuperBuild.clSPARSE_VERSION_MINOR 10 )
   endif( )
 
   if( NOT DEFINED SuperBuild.clSPARSE_VERSION_PATCH )

README.md

@@ -11,12 +11,26 @@ an OpenCL™ library implementing Sparse linear algebra routines.  This proj
 a collaboration between [AMD Inc.](http://www.amd.com/) and
 [Vratis Ltd.](http://www.vratis.com/).
 
-### What's new in clSPARSE **v0.8**
-- New single precision SpM-SpM (SpGEMM) function
-- Optimizations to the sparse matrix conversion routines
-- [API documentation](http://clmathlibraries.github.io/clSPARSE/) available
-- SpM-dV routines now provide [higher precision accuracy] (https://github.com/clMathLibraries/clSPARSE/wiki/Precision)
-- Various bug fixes integrated
+### What's new in clSPARSE **v0.10**
+**This release introduces breaking API changes from the prior version**.  clSPARSE is still in a beta phase, and we may need to change the API at times to increase maintainability or fix design issues.  A few changes are introduced to more closely follow the recently published [Cpp Core Guidelines](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html), a strong candidate to be the coding guidelines to be used in clSPARSE.  Changes are noted below.
+- The API to create meta data for a csr encoded sparse matrix has changed.  This is an attempt to hide the implementation details of how meta data is stored from the user.  This allows the library freedom to change and iterate meta data without breaking clients.
+  - `clsparseCsrMetaCompute()` renamed to `clsparseCsrMetaCreate()`, to more intuitively pair with the
+  - New API `clsparseCsrMetaDelete()`
+- A few routines changed pure 'out' parameters to be returned on the stack as structs<sup>[1](#return-tuple)</sup>
+  - `clsparseCreateControl()`
+  - `clsparseGetEvent()`
+  - `clsparseCreateSolverControl()`
+  - `clsparseCsrMetaSize()`
+- A new index type has been introduced `clsparseIdx_t` to abstract the size of an index from the library interface; the only choice currently is 4 bytes.  If users use this datatype for indices in their code, changing to 8-byte indices in the future should only be a recompile.
+- The names of member variables in our public structs have been renamed for consistency.  Before, our member variables was not consistent with camel case and underscore naming.  Member variables are now standardized to use underscores, but we keep camel casing for function and struct names<sup>[2](#consistent-naming)</sup>
+  - `colIndices` to `col_indices`
+  - `rowIndices` to `row_indices`
+  - `rowOffsets` to `row_pointer` (renamed to pointer to remove confusion with buffer offsets for cl1.2)
+  - `offValues` to `off_values`
+  - `offColInd` to `off_col_indices`
+  - `offRowOff` to `off_row_pointer`
+  - `offValues` to `off_values`
+- All samples have been changed to compile with the above changes.
 
 
 ## clSPARSE features
@@ -34,7 +48,7 @@ projects to build wrappers around clSPARSE in any language they need.  A great d
 of thought and effort went into designing the API’s to make them less ‘cluttered’
 compared to the older clMath libraries.  OpenCL state is not explicitly passed
 through the API, which enables the library to be forward compatible when users are
-ready to switch from OpenCL 1.2 to OpenCL 2.0 <sup>[1](#opencl-2)</sup>
+ready to switch from OpenCL 1.2 to OpenCL 2.0 <sup>[3](#opencl-2)</sup>
 
 ### Google Groups
 Two mailing lists have been created for the clMath projects:
@@ -105,5 +119,9 @@ clSPARSE is licensed under the [Apache License, Version 2.0](http://www.apache.o
 -   Googletest v1.7
 -   Boost v1.58
 
-## Clarifications
-<a name="opencl-2">[1]</a>: OpenCL 2.0 support is not yet fully implemented; only the interfaces have been designed
+## Footnotes
+<a name="return-tuple">[1]</a>: Changed to reflect CppCoreGuidelines: [F.21](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html#a-namerf-out-multia-f21-to-return-multiple-out-values-prefer-returning-a-tuple-or-struct)
+
+<a name="consistent-naming">[2]</a>: Changed to reflect CppCoreGuidelines: [NL.8](http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines.html#a-namerl-namea-nl8-use-a-consistent-naming-style)
+
+<a name="opencl-2">[3]</a>: OpenCL 2.0 support is not yet fully implemented; only the interfaces have been designed

cmake/ExternalBoost.cmake

@@ -24,7 +24,7 @@ include( ExternalProject )
 # ExternalProject
 
 # Change this one line to upgrade to newer versions of boost
-set( ext.Boost_VERSION "1.59.0" CACHE STRING "Boost version to download/use" )
+set( ext.Boost_VERSION "1.60.0" CACHE STRING "Boost version to download/use" )
 mark_as_advanced( ext.Boost_VERSION )
 string( REPLACE "." "_" ext.Boost_Version_Underscore ${ext.Boost_VERSION} )
 
@@ -105,7 +105,7 @@ elseif( DEFINED ENV{CC} )
   list( APPEND Boost.Command toolset=${gccToolset} )
 endif( )
 
-if( WIN32 )
+if( WIN32 AND (ext.Boost_VERSION VERSION_LESS "1.60.0") )
   list( APPEND Boost.Command define=BOOST_LOG_USE_WINNT6_API )
 endif( )
 
@@ -151,16 +151,16 @@ if( WIN32 )
 
   if( CMAKE_VERSION VERSION_LESS "3.1.0" )
     # .zip file
-    set( ext.MD5_HASH "08d29a2d85db3ebc8c6fdfa3a1f2b83c" )
+    set( ext.MD5_HASH "0cc5b9cf9ccdf26945b225c7338b4288" )
   else( )
     # .7z file
-    set( ext.MD5_HASH "0a2e512844f3e30a6240f8139ee983f3" )
+    set( ext.MD5_HASH "7ce7f5a4e396484da8da6b60d4ed7661" )
   endif( )
 else( )
   set( Boost.Bootstrap "./bootstrap.sh" )
 
   # .tar.bz2
-  set( ext.MD5_HASH "6aa9a5c6a4ca1016edd0ed1178e3cb87" )
+  set( ext.MD5_HASH "65a840e1a0b13a558ff19eeb2c4f0cbe" )
 
   if( XCODE_VERSION )
     list( APPEND Boost.Bootstrap --with-toolset=clang )

samples/sample-axpy.cpp

@@ -28,7 +28,8 @@
 #include <CL/cl.hpp>
 #endif
 
-#include <clSPARSE.h>
+#include "clSPARSE.h"
+#include "clSPARSE-error.h"
 
 /*!
  * \brief Sample AXPY (C++)
@@ -174,15 +175,11 @@ int main(int argc, char* argv[])
 
 
     // Create clsparseControl object
-    clsparseControl control = clsparseCreateControl(queue(), &status);
-    if (status != CL_SUCCESS)
-    {
-        std::cout << "Problem with creating clSPARSE control object"
-                  <<" error [" << status << "]" << std::endl;
-    }
+    clsparseCreateResult createResult = clsparseCreateControl( queue( ) );
+    CLSPARSE_V( createResult.status, "Failed to create clsparse control" );
     /** Step 4. Execute AXPY algorithm **/
 
-    status = cldenseSaxpy(&gpuY, &gpuAlpha, &gpuX, &gpuY, control);
+    status = cldenseSaxpy(&gpuY, &gpuAlpha, &gpuX, &gpuY, createResult.control );
 
     if (status != clsparseSuccess)
     {
@@ -191,7 +188,7 @@ int main(int argc, char* argv[])
     }
 
     /** Step 5. Shutdown clSPARSE library & OpenCL **/
-    status = clsparseReleaseControl(control);
+    status = clsparseReleaseControl( createResult.control );
 
 	status = clsparseTeardown();
     if (status != clsparseSuccess)

samples/sample-cg.cpp

@@ -28,7 +28,8 @@
 #include <CL/cl.hpp>
 #endif
 
-#include <clSPARSE.h>
+#include "clSPARSE.h"
+#include "clSPARSE-error.h"
 
 /*!
  * \brief Sample Conjugate Gradients Solver (CG C++)
@@ -155,17 +156,11 @@ int main (int argc, char* argv[])
     }
 
 
-    // Create clsparseControl object
-    clsparseControl control = clsparseCreateControl(queue(), &status);
-    if (status != CL_SUCCESS)
-    {
-        std::cout << "Problem with creating clSPARSE control object"
-                  <<" error [" << status << "]" << std::endl;
-        return -4;
-    }
-
+    // Create clSPARSE control object it require queue for kernel execution
+    clsparseCreateResult createResult = clsparseCreateControl( queue( ) );
+    CLSPARSE_V( createResult.status, "Failed to create clsparse control" );
 
-    // Read matrix from file. Calculates the rowBlocks strucutres as well.
+    // Read matrix from file. Calculates the rowBlocks structures as well.
     clsparseIdx_t nnz, row, col;
     // read MM header to get the size of the matrix;
     clsparseStatus fileError
@@ -185,26 +180,20 @@ int main (int argc, char* argv[])
     A.values = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
                                  A.num_nonzeros * sizeof( float ), NULL, &cl_status );
 
-    A.colIndices = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
+    A.col_indices = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
                                      A.num_nonzeros * sizeof( clsparseIdx_t ), NULL, &cl_status );
 
-    A.rowOffsets = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
+    A.row_pointer = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
                                      ( A.num_rows + 1 ) * sizeof( clsparseIdx_t ), NULL, &cl_status );
 
-    A.rowBlocks = ::clCreateBuffer( context(), CL_MEM_READ_ONLY,
-                                    A.rowBlockSize * sizeof( cl_ulong ), NULL, &cl_status );
-
 
     // Read matrix market file with explicit zero values included.
-    fileError = clsparseSCsrMatrixfromFile( &A, matrix_path.c_str( ), control, true );
+    fileError = clsparseSCsrMatrixfromFile( &A, matrix_path.c_str( ), createResult.control, true );
 
     // This function allocates memory for rowBlocks structure. If not called
     // the structure will not be calculated and clSPARSE will run the vectorized
     // version of SpMV instead of adaptive;
-    clsparseCsrMetaSize( &A, control );
-    A.rowBlocks = ::clCreateBuffer( context(), CL_MEM_READ_WRITE,
-            A.rowBlockSize * sizeof( cl_ulong ), NULL, &cl_status );
-    clsparseCsrMetaCompute( &A, control );
+    clsparseCsrMetaCreate( &A, createResult.control );
 
     if (fileError != clsparseSuccess)
     {
@@ -249,28 +238,27 @@ int main (int argc, char* argv[])
     // relative tolerance: 1e-2
     // absolute tolerance: 1e-5
     // max iters: 1000
-    clSParseSolverControl solverControl =
-            clsparseCreateSolverControl(DIAGONAL, 1000, 1e-2, 1e-5);
+    clsparseCreateSolverResult solverResult =
+        clsparseCreateSolverControl( DIAGONAL, 1000, 1e-2, 1e-5 );
+    CLSPARSE_V( solverResult.status, "Failed to create clsparse solver control" );
 
     // We can set different print modes of the solver status:
     // QUIET - print no messages (default)
     // NORMAL - print summary
     // VERBOSE - per iteration status;
-    clsparseSolverPrintMode(solverControl, VERBOSE);
+    clsparseSolverPrintMode( solverResult.control, VERBOSE);
 
     /* TODO: provide various solver statuses for different scenarios
-     * Solver reached max numer of iterations is not a failure.
+     * Solver reached max number of iterations is not a failure.
      */
 
-    status = clsparseScsrcg(&x, &A, &b, solverControl, control);
+    status = clsparseScsrcg(&x, &A, &b, solverResult.control, createResult.control );
 
     //release solver control structure after finishing execution;
-    clsparseReleaseSolverControl(solverControl);
-
-
+    clsparseReleaseSolverControl( solverResult.control );
 
     /** Step 5. Close & release resources */
-    status = clsparseReleaseControl(control);
+    status = clsparseReleaseControl( createResult.control );
     if (status != clsparseSuccess)
     {
         std::cout << "Problem with releasing control object."
@@ -285,10 +273,10 @@ int main (int argc, char* argv[])
                   << " Error: " << status << std::endl;
     }
     //release mem;
+    clsparseCsrMetaDelete( &A );
     clReleaseMemObject ( A.values );
-    clReleaseMemObject ( A.colIndices );
-    clReleaseMemObject ( A.rowOffsets );
-    clReleaseMemObject ( A.rowBlocks );
+    clReleaseMemObject ( A.col_indices );
+    clReleaseMemObject ( A.row_pointer );
 
     clReleaseMemObject ( x.values );
     clReleaseMemObject ( b.values );

samples/sample-norm1-c.c

@@ -17,7 +17,8 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-#include <clSPARSE.h>
+#include "clSPARSE.h"
+#include "clSPARSE-error.h"
 
 /*! \file
 * \brief Simple demonstration code for calculating Norm1 from within 'C' host code
@@ -34,7 +35,7 @@
  * 5. Shutdown clSPARSE library & OpenCL
  *
  * UNIX Hint: Before allocating more than 3GB of VRAM define GPU_FORCE_64BIT_PTR=1
- * in your system environment to enable 64bit addresing;
+ * in your system environment to enable 64bit addressing;
  */
 int main( int argc, char* argv[ ] )
 {
@@ -55,7 +56,7 @@ int main( int argc, char* argv[ ] )
 
     if (num_platforms == 0)
     {
-        printf ("No OpenCL platforms found. Exitting.\n");
+        printf ("No OpenCL platforms found. Exiting.\n");
         return 0;
     }
 
@@ -67,7 +68,7 @@ int main( int argc, char* argv[ ] )
 
     if (cl_status != CL_SUCCESS)
     {
-        printf("Poblem with getting platform IDs. Err: %d\n", cl_status);
+        printf("Problem with getting platform IDs. Err: %d\n", cl_status);
         free(platforms);
         return -1;
     }
@@ -78,7 +79,7 @@ int main( int argc, char* argv[ ] )
 
     if (num_devices == 0)
     {
-        printf("No OpenCL GPU devices found on platform 0. Exitting\n");
+        printf("No OpenCL GPU devices found on platform 0. Exiting\n");
         free(platforms);
         return -2;
     }
@@ -91,7 +92,7 @@ int main( int argc, char* argv[ ] )
 
     if (cl_status != CL_SUCCESS)
     {
-        printf("Problem with getting device id from platform. Exitting\n");
+        printf("Problem with getting device id from platform. Exiting\n");
         free(devices);
         free(platforms);
         return -3;
@@ -134,9 +135,10 @@ int main( int argc, char* argv[ ] )
     }
 
     // Create clSPARSE control object it require queue for kernel execution
-    clsparseControl control = clsparseCreateControl(queue, &status);
+    clsparseCreateResult createResult = clsparseCreateControl( queue );
+    CLSPARSE_V( createResult.status, "Failed to create clsparse control" );
 
-    status = cldenseSnrm1(&norm_x, &x, control);
+    status = cldenseSnrm1(&norm_x, &x, createResult.control );
 
     // Read  result
     float* host_norm_x =
@@ -148,7 +150,7 @@ int main( int argc, char* argv[ ] )
     cl_status = clEnqueueUnmapMemObject(queue, norm_x.value, host_norm_x,
                                         0, NULL, NULL);
 
-    status = clsparseReleaseControl(control);
+    status = clsparseReleaseControl( createResult.control );
 
     status = clsparseTeardown();
     if (status != clsparseSuccess)