Updated readme for v0.10

Bumped cmake version to v.10

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

src/CMakeLists.txt

@@ -37,7 +37,7 @@ endif()
 # clSPARSE becomes the name of the project with a particular version
 if( POLICY CMP0048 )
 	cmake_policy( SET CMP0048 NEW )
-	project( clSPARSE VERSION 0.9.0.0 LANGUAGES C CXX )
+	project( clSPARSE VERSION 0.10.0.0 LANGUAGES C CXX )
 else( )
 	project( clSPARSE C CXX )
 	# Define a version for the code
@@ -46,7 +46,7 @@ else( )
 	endif( )
 
 	if( NOT DEFINED clSPARSE_VERSION_MINOR )
-		set( clSPARSE_VERSION_MINOR 9 )
+		set( clSPARSE_VERSION_MINOR 10 )
 	endif( )
 
 	if( NOT DEFINED clSPARSE_VERSION_PATCH )

src/include/clSPARSE.h

@@ -227,8 +227,8 @@ extern "C" {
     */
     typedef struct _clsparseCreateResult
     {
-        clsparseControl control;
         clsparseStatus status;
+        clsparseControl control;
     } clsparseCreateResult;
 
     /*!
@@ -276,8 +276,8 @@ extern "C" {
     */
     typedef struct _clsparseEventResult
     {
-        cl_event event;
         clsparseStatus status;
+        cl_event event;
     } clsparseEventResult;
 
     /*!
@@ -352,8 +352,8 @@ extern "C" {
     */
     typedef struct _clsparseCreateSolverResult
     {
-        clSParseSolverControl control;
         clsparseStatus status;
+        clSParseSolverControl control;
     } clsparseCreateSolverResult;
 
     /*!
@@ -619,8 +619,8 @@ extern "C" {
     */
     typedef struct _clsparseMetaSizeResult
     {
-        clsparseIdx_t metaSize;
         clsparseStatus status;
+        clsparseIdx_t metaSize;
     } clsparseMetaSizeResult;
 
     /*!