Merge branch 'develop'

Author: Kent Knox

.travis.yml

@@ -9,19 +9,19 @@
 # Ubuntu 15.10 (Wily Werewolf)
 # Ubuntu 16.04 LTS (Xenial Xantus)
 
-# language: instructs travis what compilers && environment to set up in build matrix
-language: cpp
-
-# sudo: false instructs travis to build our project in a docker VM (faster)
-# Can not yet install fglrx packages with 'false'
-sudo: required # false
-
 # os: expands the build matrix to include multiple os's
-# disable linux, as we get sporadic failures on building boost, needs investigation
 os:
   - linux
   - osx
 
+# sudo: false instructs travis to build our project in a docker VM (faster),
+# but we cannot yet install fglrx packages with 'false'
+sudo: required # false
+dist: trusty
+
+# language: instructs travis what compilers && environment to set up in build matrix
+language: cpp
+
 # compiler: expands the build matrix to include multiple compilers (per os)
 compiler:
   - gcc
@@ -35,37 +35,20 @@ addons:
   apt:
     sources:
       # ubuntu-toolchain-r-test contains newer versions of gcc to install
-      - ubuntu-toolchain-r-test
+      # - ubuntu-toolchain-r-test
+
       # llvm-toolchain-precise-3.6 contains newer versions of clang to install
       # - llvm-toolchain-precise-3.6
-      # kubuntu-backports contains newer versions of cmake to install
-      - kubuntu-backports
-      # boost-latest contains boost v1.55
-      # - boost-latest
     packages:
-      # g++-4.8 is minimum version considered to be the first good c++11 gnu compiler
-      - g++-4.8
-      # - clang-3.6
-      # We require v2.8.12 minimum
-      - cmake
-      # I'm finding problems between pre-compiled versions of boost ublas, with gtest
-      # stl_algobase.h: error: no matching function for call to swap()
-      # - libboost-program-options1.55-dev
-      # - libboost-serialization1.55-dev
-      # - libboost-filesystem1.55-dev
-      # - libboost-system1.55-dev
-      # - libboost-regex1.55-dev
       # The package opencl-headers on 'precise' only installs v1.1 cl headers; uncomment for 'trusty' or greater
-#      - opencl-headers
-      # Uncomment one of the following when fglrx modules are added to the apt whitelist
-#      - fglrx
-#      - fglrx=2:8.960-0ubuntu1
-#      - fglrx=2:13.350.1-0ubuntu0.0.1
+      - opencl-headers
 
 # env: specifies additional global variables to define per row in build matrix
 env:
   global:
     - CLSPARSE_ROOT=${TRAVIS_BUILD_DIR}/bin/make/release
+    - OPENCL_REGISTRY=https://www.khronos.org/registry/cl
+    - OPENCL_ROOT=${TRAVIS_BUILD_DIR}/bin/opencl
 
 # The following filters our build matrix; we are interested in linux-gcc & osx-clang
 matrix:
@@ -79,39 +62,52 @@ before_install:
   # Remove the following linux clause when fglrx can be installed with sudo: false
   - if [ ${TRAVIS_OS_NAME} == "linux" ]; then
       sudo apt-get update -qq &&
-      sudo apt-get install -qq fglrx=2:13.350.1-0ubuntu0.0.1;
-    fi
-  - if [ ${TRAVIS_OS_NAME} == "linux" ]; then
-      export OPENCL_ROOT="${TRAVIS_BUILD_DIR}/opencl-headers";
-      export BUILD_BOOST="ON";
+      sudo apt-get install -qq libboost-all-dev;
+      export BUILD_BOOST="OFF";
     fi
   - if [ ${TRAVIS_OS_NAME} == "osx" ]; then
       brew update;
       brew outdated boost || brew upgrade boost;
       brew outdated cmake || brew upgrade cmake;
       export BUILD_BOOST="OFF";
     fi
-  - if [ ${CXX} = "g++" ]; then export CXX="g++-4.8" CC="gcc-4.8"; fi
+#  - if [ ${CXX} = "g++" ]; then export CXX="g++-4.8" CC="gcc-4.8"; fi
   - cmake --version;
   - ${CC} --version;
   - ${CXX} --version;
 
 install:
-  # 'Precise' only distributes v1.1 opencl headers; download 1.2 headers from khronos website
-  # Remove when the travis VM upgrades to 'trusty' or beyond
-  - if [ ${TRAVIS_OS_NAME} == "linux" ]; then
-      mkdir -p ${OPENCL_ROOT}/include/CL;
-      pushd ${OPENCL_ROOT}/include/CL;
-      wget -w 1 -r -np -nd -nv -A h,hpp https://www.khronos.org/registry/cl/api/1.2/;
-      popd;
-    fi
   # osx image does not contain cl.hpp file; download from Khronos
   - if [ ${TRAVIS_OS_NAME} == "osx" ]; then
       pushd /System/Library/Frameworks/OpenCL.framework/Versions/A/Headers/;
-      sudo wget -w 1 -np -nd -nv -A h,hpp https://www.khronos.org/registry/cl/api/1.2/cl.hpp;
+      sudo wget -w 1 -np -nd -nv -A h,hpp https://www.khronos.org/registry/cl/api/2.1/cl.hpp;
+      popd;
+    fi
+  # The following linux logic is necessary because of Travis's move to the GCE platform, which does not
+  # currently contain packages for fglrx: https://github.com/travis-ci/travis-ci/issues/5221
+  # We build our own linkable .so file
+  - if [ ${TRAVIS_OS_NAME} == "linux" ]; then
+      mkdir -p ${OPENCL_ROOT};
+      pushd ${OPENCL_ROOT};
+      wget ${OPENCL_REGISTRY}/specs/opencl-icd-1.2.11.0.tgz;
+      tar -xf opencl-icd-1.2.11.0.tgz;
+      mv ./icd/* .;
+      mkdir -p inc/CL;
+      pushd inc/CL;
+      wget -r -w 1 -np -nd -nv -A h,hpp https://www.khronos.org/registry/cl/api/1.2/;
+      wget -w 1 -np -nd -nv -A h,hpp https://www.khronos.org/registry/cl/api/2.1/cl.hpp;
+      popd;
+      mkdir -p lib;
+      pushd lib;
+      cmake -G "Unix Makefiles" ..;
+      make;
+      cp ../bin/libOpenCL.so .;
+      popd;
+      mv inc/ include/;
       popd;
     fi
 
+
 # Use before_script: to run configure steps
 before_script:
   - mkdir -p ${CLSPARSE_ROOT}
@@ -123,6 +119,7 @@ script:
   - make clSPARSE-samples
   - cd clSPARSE-build
   - make package
+  - popd
 
 deploy:
   provider: releases
@@ -132,8 +129,8 @@ deploy:
   # This uses a personal OAuth token generated by kknox
   api_key:
     secure: MBkxtcfSk+4UvGRO+WRhmS86vIVzAs0LIF2sAtr/S+Ed+OdUAuhZypUsDXGWtK3mL55v9c8BZXefFfHfJqElcNmyHKwCptbCR/JiM8YBtjoy2/RW1NcJUZp+QuRlk23xPADj7QkPjv7dfrQUMitkLUXAD+uTmMe2l8gmlbhMrQqPBKhb+31FNv6Lmo6oa6GjbiGi7qjsrJc7uQjhppLam+M7BZbBALGbIqMIrb2BMDMMhBoDbb4zSKrSg3+krd3kKiCClJlK7xjIlyFXZ527ETQ+PMtIeQb0eJ3aQwa4caBRCm5BDzt8GnJ48S88EkynbQioCEE87ebcyOM7M+wfslW/Fm1Y86X5odIljkOmTNKoDvgLxc9vUCBtMyVHNIgZcToPdsrMsGxcHV+JtU3yVQVm6dnA5P/zG5bA+aBjsd7p7BdOE4fdhvZV5XRAk/wmiyWalF7hKJxHIiWAKknL+tpPDDUF+fHmDDsdf7yRDJBegNcKfw4+m19MIvLn9fbiNVCtwCAL1T4yWkIEpi4MRMDPtftmkZPbi6UwluOJUTeCeHe4en99Yu2haemNPqXs6rR0LlXGk31GQwzlrNfb+94F5tT2a4Ka4PsruA2NMW/IYCYEE5Gu7PihVDR031Fn9cdCU9kefUgyB07rJD6q/W+ljsU0osyg7VxyfMg8rkw=
-  file: ${CLSPARSE_ROOT}/clSPARSE-build/*.tar.gz
   file_glob: true
+  file: ${CLSPARSE_ROOT}/clSPARSE-build/*.tar.gz
   on:
     all_branches: true
     tags: true

CMakeLists.txt

@@ -38,7 +38,7 @@ endif()
 if( POLICY CMP0048 )
   cmake_policy( SET CMP0048 NEW )
 
-  project( SuperBuild.clSPARSE VERSION 0.8.1.0 )
+  project( SuperBuild.clSPARSE VERSION 0.10.0.0 )
 else( )
   project( SuperBuild.clSPARSE )
 
@@ -48,11 +48,11 @@ else( )
   endif( )
 
   if( NOT DEFINED SuperBuild.clSPARSE_VERSION_MINOR )
-    set( SuperBuild.clSPARSE_VERSION_MINOR 8 )
+    set( SuperBuild.clSPARSE_VERSION_MINOR 10 )
   endif( )
 
   if( NOT DEFINED SuperBuild.clSPARSE_VERSION_PATCH )
-    set( SuperBuild.clSPARSE_VERSION_PATCH 1 )
+    set( SuperBuild.clSPARSE_VERSION_PATCH 0 )
   endif( )
 
   if( NOT DEFINED SuperBuild.clSPARSE_VERSION_TWEAK )

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:
@@ -46,23 +60,27 @@ Two mailing lists have been created for the clMath projects:
     developers interested in contributing to the library code itself
 
 ### API semantic versioning
-Good software is typically the result of the loop of feedback and iteration;
-software interfaces no less so.  clSPARSE follows the
+Good software is typically the result of iteration and feedback.  clSPARSE follows the
 [semantic versioning](http://semver.org/) guidelines, and while the major version
 number remains '0', the public API should not be considered stable.  We release
 clSPARSE as beta software (0.y.z) early to the community to elicit feedback and
 comment.  This comes with the expectation that with feedback, we may incorporate
 breaking changes to the API that might require early users to recompile, or rewrite
 portions of their code as we iterate on the design.
 
+## clSPARSE Wiki
+The [project wiki](https://github.com/clMathLibraries/clSPARSE/wiki) contains helpful documentation.  
+A [build primer](https://github.com/clMathLibraries/clSPARSE/wiki/Build) is available,
+which describes how to use cmake to generate platforms specific build files
+
 ## Samples
 clSPARSE contains a directory of simple [OpenCL samples](./samples) that demonstrate the use
 of the API in both C and C++.  The [superbuild](http://www.kitware.com/media/html/BuildingExternalProjectsWithCMake2.8.html)
 script for clSPARSE also builds the samples as an external project, to demonstrate
 how an application would find and link to clSPARSE with cmake.
 
 ### clSPARSE library documentation
-**API documentation** is now available http://clmathlibraries.github.io/clSPARSE/ . The included samples will give an excellent
+**API documentation** is available at http://clmathlibraries.github.io/clSPARSE/. The samples give an excellent
 starting point to basic library operations.
 
 ### Contributing code
@@ -72,14 +90,8 @@ how to contribute code to this open source project. Code in the
 when commits are merged into /master.  Active development and pull-requests should
 be made to the **develop** branch.
 
-## Build
-clSPARSE is primarily written with C++ using C++11 core features.  It does export
-a 'C' interface for compatibility with other languages.
-
-### How to build clSPARSE for your platform
-A [Build primer](https://github.com/clMathLibraries/clSPARSE/wiki/Build) is available on
-the wiki, which describes how to use cmake to generate platforms specific build
-files
+## License
+clSPARSE is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
 ### Compiling for Windows
 -  Windows&reg; 7/8
@@ -107,5 +119,9 @@ files
 -   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

appveyor.yml

@@ -49,6 +49,7 @@ install:
   # The cmake build files expect a directory called inc
   - ps: mkdir inc/CL
   - ps: wget $opencl_registry/api/1.2/ | select -ExpandProperty links | where {$_.href -like "*.h*"} | select -ExpandProperty outerText | foreach{ wget $opencl_registry/api/1.2/$_ -OutFile inc/CL/$_ }
+  - ps: wget $opencl_registry/api/2.1/cl.hpp -OutFile inc/CL/cl.hpp
   # - ps: dir; if( $lastexitcode -eq 0 ){ dir include/CL } else { Write-Output boom }
   # Create the static import lib in a directory called lib, so findopencl() will find it
   - ps: mkdir lib
@@ -59,7 +60,6 @@ install:
   # Rename the inc directory to include, so FindOpencl() will find it
   - ps: ren inc include
   - ps: popd
-  - ps: popd
 
 # before_build is used to run configure steps
 before_build:
@@ -81,6 +81,7 @@ after_build:
   - echo after_build step
   - ps: ls $env:CLSPARSE_ROOT\clSPARSE-build
   - ps: mv $env:CLSPARSE_ROOT\clSPARSE-build\*.zip $env:APPVEYOR_BUILD_FOLDER
+  - ps: popd
 
 # Appyeyor will save a copy of the package in it's personal storage
 artifacts: