Merge pull request #6 from jaurentz/development

Development

Makefile

@@ -26,8 +26,8 @@ objects: FORCE
 tests: FORCE
 	@$(MAKE) -C ./tests
 
-numex: FORCE
-	@$(MAKE) -C ./numex
+examples: FORCE
+	@$(MAKE) -C ./examples
 
 FORCE:
 
@@ -46,6 +46,6 @@ uninstall: clean
 clean:
 	@$(MAKE) clean -C ./src
 	@$(MAKE) clean -C ./tests
-	@$(MAKE) clean -C ./numex
+	@$(MAKE) clean -C ./examples
 
 

README.md

@@ -1,10 +1,10 @@
 # Cucheb - CUDA accelerated large sparse eigensolvers #
 Jared L. Aurentz, Vassilis Kalantzis and Yousef Saad, September 2016
 
-## Github ##
+## GitHub ##
 This README file is written in mark down. For the best experience please view this
 file, along with the rest of the Cucheb library on
-[github](https://github.com/jaurentz/cucheb).
+[GitHub](https://github.com/jaurentz/cucheb).
 
 ## Introduction ##
 Cucheb is a collection of C++ subroutines for accurately and efficiently
@@ -21,7 +21,32 @@ There are many files in the Cucheb library but only a few will be necessary for
 most users. The first set of files are the objects used to store computed
 quantities, such as eigenvalues and eigenvectors. Below we give a brief
 description of each file and a link for further information:
- - [cuchebmatrix](https:/github.com/jaurentz/cucheb/src/double/cuchebmatrix_lanczos.cu)
+ - [cuchebmatrix](include/cuchebmatrix.h) - object for storing sparse matrices
+ - [cucheblanczos](include/cucheblanczos.h) - object for storing computed
+   eigenvalues and eigenvectors
+
+The next set of files are programs used to initialize and delete objects and
+compute eigenvalues and eigenvectors:
+- [cuchebmatrix_init](src/cuchebmatrix/cuchebmatrix_init.cu) - initializes a
+  cuchebmatrix object using a sparse matrix stored in [Matrix Market
+Format](http://math.nist.gov/MatrixMarket/)
+- [cuchebmatrix_destroy](src/cuchebmatrix/cuchebmatrix_destroy.cu) - frees all
+  memory associated with an instance of a cuchebmatrix object
+- [cuchebmatrix_print](src/cuchebmatrix/cuchebmatrix_print.cu) - prints basic
+  propertied of an instance of a cuchebmatrix object
+- [cuchebmatrix_lanczos](src/cuchebmatrix/cuchebmatrix_lanczos.cu) - computes
+  all eigenvalues and eigenvectors in a user-defined interval using the Lanczos
+method and stores the output in a cucheblanczos object
+- [cuchebmatrix_filteredlanczos](src/cuchebmatrix/cuchebmatrix_filteredlanczos.cu)
+  - computes all eigenvalues and eigenvectors in a user-defined interval using
+    the filtered Lanczos procedure and stores the output in a cucheblanczos
+object
+- [cucheblanczos_init](src/cucheblanczos/cucheblanczos_init.cu) - initializes a
+  cucheblanczos object
+- [cucheblanczos_destroy](src/cucheblanczos/cucheblanczos_destroy.cu) - frees
+  all memory associated with an instance of a cucheblanczos object
+- [cucheblanczos_print](src/cucheblanczos/cucheblanczos_print.cu) - prints
+  basic propertied of an instance of a cucheblanczos object
 
 ## Installation ##
 Cucheb is built on top of the [NVIDIA CUDA
@@ -39,6 +64,12 @@ This creates a shared object library __libcucheb.so._version___ and copies it
 into the user specified installation directory. The installation does not
 create any symbolic links or export any library paths.
 
+## Examples ##
+You can find several examples for using Cucheb in the [examples](examples)
+subdirectory. In order to run these examples you will first have to download
+the matrices listed in each example from the University of Florida's [Sparse
+Matrix Collection](https://www.cise.ufl.edu/research/sparse/matrices/).
+
 ## Removing Cucheb ##
 If the source directory has not been removed simply move into the Cucheb
 root directory and type:

numex/tables/Makefile → examples/Makefile

@@ -1,15 +1,15 @@
-include ../../make.inc
+include ../make.inc
 
-TESTS := $(wildcard ./*.cu)
-TESTS := $(TESTS:.cu=)
+EXS := $(wildcard ./*.cu)
+EXS := $(EXS:.cu=)
 
 CUCHEBINCS := -I $(INSTALLDIR)/cucheb/include
 CUCHEBLIBS := -L $(INSTALLDIR)/cucheb/lib -lcucheb 
 
-all: $(TESTS)
+all: $(EXS)
 
 %:: %.cu
 	$(CUC) $(CUFLAGS) -o $@ $< $(CUCHEBINCS) $(CUCHEBLIBS) $(INCS) $(LIBS) 
 
 clean:
-	@rm -f $(TESTS)
+	@rm -f $(EXS)

examples/example_parsec.cu

@@ -0,0 +1,52 @@
+#include <cucheb.h>
+
+/* driver */
+int main(){
+
+  // compute variables
+  cuchebmatrix ccm;
+  cucheblanczos ccl;
+
+  // variables to parse file
+  string matname;
+  double lbnd, ubnd;
+  int bsize;
+
+  // initialize matrix
+  matname = "/path/to/Ge87H76.mtx";
+  cuchebmatrix_init(matname, &ccm);
+
+  // set interval and block size
+  lbnd = -0.645;
+  ubnd = -0.0053;
+  bsize = 3;
+
+  // call filtered lanczos for an interval
+  cuchebmatrix_filteredlanczos(lbnd, ubnd, bsize, &ccm, &ccl);
+
+  // print matrix
+  cuchebmatrix_print(&ccm);
+
+  // print eigenvalues and residuals
+  printf("\nComputed eigenvalues and residuals:\n");
+  for(int ii=0;ii<ccl.nconv;ii++){
+    printf(" eig[%d] = %+e, res[%d] = %e\n",
+           ii,ccl.evals[ccl.index[ii]],ii,ccl.res[ccl.index[ii]]);
+  }
+
+  // print first 10 entries of first eigenvector 
+  printf("\nFirst 10 entries of first eigenvector:\n");
+  for(int ii=0;ii<10;ii++){
+    printf(" vec[%d] = %+e\n",ii,ccl.vecs[ccl.index[ii]*ccl.n+ii]);
+  }
+
+  // destroy ccl
+  cucheblanczos_destroy(&ccl);
+
+  // destroy ccm
+  cuchebmatrix_destroy(&ccm);
+
+  // return 
+  return 0;
+
+}

include/cucheblanczos.h

@@ -1,4 +1,37 @@
 #include <cuchebdependencies.h>
+/*
+
+  cucheblanczos
+
+  This file defines the cucheblanczos object. This object is needed for running
+  the Lanczos algorithm and storing the compute eigenvalues and eigenvectors.
+  The macros listed below are for default variables that are used in the
+  high-level routines. At the bottom of the file is the class definition. It
+  contains two sets of variables one for CPU memory and one for GPU memory.
+  These two sets of memory are needed to avoid time consuming memory transfers
+  between the CPU and GPU.
+
+  CPU variables:
+
+    n         - length of eigenvectors
+    bsize     - block size for block Lanczos
+    nblocks   - total number of blocks allocated
+    stop      - index of most recently computed Lanczos vectors
+    nconv     - number of converged eigenvalues
+    index     - pointer to array of indices used to sort eigenvalues
+    evals     - pointer to array of computed eigenvalues
+    res       - pointer to array of residuals
+    bands     - pointer to array of banded matrix computed during Lanczos process
+    vecs      - pointer to array of Lanczos vector
+    schurvecs - pointer to array of eigenvectors of banded matrix
+
+  GPU variables:
+
+    dtemp      - pointer to array of swap space on GPU
+    dvecs      - pointer to array of Lanczos vectors on GPU
+    dschurvecs - pointer to array of eigenvectors of banded matrix on GPU
+
+*/
 
 /* header file for cucheblanczos data type */
 #ifndef __cucheblanczos_h__ 

include/cuchebmatrix.h

@@ -3,6 +3,39 @@
 /* header file for cuchebmatrix data type */
 #ifndef __cuchebmatrix_h__ 
 #define __cuchebmatrix_h__
+/*
+
+  cuchebmatrix
+
+  This file defines the cuchebmatrix object. This object is needed for storing
+  and using sparse matrices. When an instance of a cuchebmatrix is initialized
+  the entries are first put into the proper order on the CPU. Once this is done
+  a second copy of the matrix is created on the GPU. The second copy on the GPU
+  is necessary in order to avoid making time consuming memory swaps between the
+  CPU and GPU.
+
+  CPU variables:
+
+    matcode - matcode used in Matrix Market files
+    m       - number of rows 
+    n       - number of columns
+    nnz     - number of nonzero entries
+    a,b     - upper and lower bounds on the eigenvalues
+    rowinds - pointer to array of row indices
+    colinds - pointer to array of column indices
+    vals    - pointer to array of nonzero entries
+
+  GPU variables:
+
+    cublashandle   - handle needed to use CUBLAS subroutines
+    cusparsehandle - handle needed to use CUSPARSE subroutines
+    matdescr       - used to describe matrix storage on GPU
+    drowinds       - pointer to array of row indices stored on GPU
+    dcolinds       - pointer to array of column indices stored on GPU
+    dvals          - pointer to array of nonzero entries stored on GPU
+    dtemp          - pointer to array used for swap space on GPU
+
+*/
 
 /* cuchebmatrix data type */
 typedef struct {

make.inc

@@ -1,8 +1,8 @@
 # directory where CUCHEB will be installed
-INSTALLDIR := $(HOME)/Mylibs
+INSTALLDIR := $(HOME)/CUCHEB_INSTALL
 
 # CUDA compiler and flags
-CUC := /usr/local/cuda-7.0/bin/nvcc
+CUC := nvcc
 CUFLAGS := -O3 -gencode arch=compute_35,code=sm_35 
 
 # CUDA libraries